|
| 1 | +# Runtime Adapter Checklist |
| 2 | + |
| 3 | +Use this checklist when evaluating whether a runtime can implement VALP. |
| 4 | + |
| 5 | +The question is not "can this runtime run an agent?" The question is whether it |
| 6 | +can export enough evidence for another person, agent, or CI job to audit the |
| 7 | +work. |
| 8 | + |
| 9 | +## 1. Classify The Adapter |
| 10 | + |
| 11 | +Choose the closest shape: |
| 12 | + |
| 13 | +| Adapter class | Typical runtime | Mode | |
| 14 | +|---|---|---| |
| 15 | +| pane controller | terminal panes or browser-controlled panes | Full Mode if proof is exported | |
| 16 | +| daemon queue | local job queue or runner daemon | Full Mode if state and evidence are exported | |
| 17 | +| hosted/local platform | web board plus agent workers | Full Mode if audit data is accessible | |
| 18 | +| remote SSH | runtime state lives on another host | Remote Mode | |
| 19 | +| manual | human copies prompts and results | Manual Mode | |
| 20 | + |
| 21 | +## 2. Required Full Mode Evidence |
| 22 | + |
| 23 | +A Full Mode adapter must export: |
| 24 | + |
| 25 | +- agent list; |
| 26 | +- agent metadata and status; |
| 27 | +- provider matrix; |
| 28 | +- context policy; |
| 29 | +- runtime preflight; |
| 30 | +- dispatch submission proof; |
| 31 | +- runtime task state mapping; |
| 32 | +- expected evidence refs; |
| 33 | +- receipt ledger; |
| 34 | +- failure reason when blocked or failed; |
| 35 | +- approval gate status. |
| 36 | + |
| 37 | +If any of these are missing, the adapter may still be useful, but it should not |
| 38 | +claim Full Mode yet. |
| 39 | + |
| 40 | +## 3. Dispatch Proof |
| 41 | + |
| 42 | +Check each dispatch step: |
| 43 | + |
| 44 | +- `dispatch_written`: the task-local dispatch file or equivalent exists. |
| 45 | +- `dispatch_inserted`: text was inserted into an input surface, if applicable. |
| 46 | +- `dispatch_submitted`: the runtime proves the message/job was submitted. |
| 47 | +- `dispatch_completed`: expected evidence exists after execution. |
| 48 | +- `dispatch_blocked`: delivery or completion could not be proven. |
| 49 | + |
| 50 | +Text inserted into a pane is not enough. Queue accepted is not enough. Hosted |
| 51 | +job completed is not enough. The adapter must connect runtime state to expected |
| 52 | +evidence. |
| 53 | + |
| 54 | +## 4. Expected Evidence |
| 55 | + |
| 56 | +For each selected agent, record: |
| 57 | + |
| 58 | +- exact expected evidence paths; |
| 59 | +- who owns each path; |
| 60 | +- whether the evidence exists; |
| 61 | +- whether evidence is valid, superseded, rejected, blocked, or invalid; |
| 62 | +- whether build/test/runtime claims cite concrete logs or screenshots. |
| 63 | + |
| 64 | +## 5. Preflight |
| 65 | + |
| 66 | +Pane adapters should record: |
| 67 | + |
| 68 | +- pane id; |
| 69 | +- foreground cwd, when available; |
| 70 | +- terminal size, when available; |
| 71 | +- minimum terminal size expected by the agent; |
| 72 | +- CLI availability and version probe, when available; |
| 73 | +- known TUI/display caveats. |
| 74 | + |
| 75 | +Queue, hosted, or remote adapters should record equivalent job/session facts: |
| 76 | + |
| 77 | +- queue id or run id; |
| 78 | +- worker id; |
| 79 | +- session status; |
| 80 | +- output refs; |
| 81 | +- retry state or failure reason; |
| 82 | +- expected refs. |
| 83 | + |
| 84 | +Do not fake pane fields for non-pane runtimes. |
| 85 | + |
| 86 | +## 6. Approval And Risk |
| 87 | + |
| 88 | +The adapter must stop or require approval for: |
| 89 | + |
| 90 | +- destructive changes; |
| 91 | +- release, publish, upload, submit, or deploy; |
| 92 | +- auth, secrets, signing, entitlements, privacy metadata; |
| 93 | +- migrations; |
| 94 | +- memory, agent config, or MCP config changes; |
| 95 | +- private-data export. |
| 96 | + |
| 97 | +Approval evidence must be task-local and visible. A permissive runtime default |
| 98 | +does not override VALP approval gates. |
| 99 | + |
| 100 | +## 7. Recommendation Resolution |
| 101 | + |
| 102 | +If selected workers return recommendations: |
| 103 | + |
| 104 | +- collect them in task-local evidence; |
| 105 | +- record whether each meaningful recommendation was adopted, merged, bounded, |
| 106 | + converted to follow-up, rejected, or escalated; |
| 107 | +- avoid unbounded redispatch loops; |
| 108 | +- require user approval when a recommendation expands into high-risk work. |
| 109 | + |
| 110 | +## 8. Minimal Smoke Test |
| 111 | + |
| 112 | +Before claiming compatibility, run a small task through this sequence: |
| 113 | + |
| 114 | +```text |
| 115 | +publish task |
| 116 | +scan capabilities |
| 117 | +route selected agents |
| 118 | +write concise dispatch |
| 119 | +submit through runtime |
| 120 | +record dispatch_submitted proof |
| 121 | +wait for worker output |
| 122 | +write expected evidence |
| 123 | +record dispatch_completed |
| 124 | +write final synthesis |
| 125 | +run valp audit |
| 126 | +``` |
| 127 | + |
| 128 | +The task is compatible only when the audit passes for the right reason. |
| 129 | + |
| 130 | +## 9. What To Post For Feedback |
| 131 | + |
| 132 | +In a runtime-adapter discussion, include: |
| 133 | + |
| 134 | +- adapter class; |
| 135 | +- runtime or platform name; |
| 136 | +- which Full Mode fields are exported today; |
| 137 | +- which fields are missing; |
| 138 | +- one sample receipt ledger; |
| 139 | +- one expected evidence map; |
| 140 | +- known failure modes; |
| 141 | +- whether the adapter should start as Full Mode, Remote Mode, or Manual Mode. |
0 commit comments