Handbook
Engineering Autonomy program (Phase A)
Phase A proves that one authenticated Matrix task, one fresh forgeadmin approval bound to that exact task, and one confined agent run can edit a disposable repository (src/calc.py → pure add(a, b)), be independently…
Updated
Executive capsule
Phase A proves that one authenticated Matrix task, one fresh forgeadmin approval bound to that exact task, and one confined agent run can edit a disposable repository (src/calc.py → pure add(a, b)), be independently verified on the changed bytes, report the result to Matrix, and leave a checksummed archive. This page is the tracker of record. Until 2026-10-27 that state lived only in workbench/*.zip archives and chat; it is canon here from now on.
Why this matters
Without a single tracker, each session re-derives the program state from archives and chat, and the temptation to call a gate PASS from an exit code grows. This page fixes the vocabulary and the evidence trail.
Who this is for
- Operators deciding what to approve next in Element.
- Architects judging whether the execution substrate (laptop vs Granite) matches the policy.
- Agents that must know which gates are open before claiming progress.
How it works
An operator posts a task in Element; Roadrunner registers a pending request with a canonical digest; forgeadmin posts !approve <request_id> <digest>; the receipt is stored once and cannot be reused; the executor runs only after the receipt matches; a verifier outside the executor checks the changed bytes; the result and a checksummed archive close the task. Each phase below hardens one link of that chain.
Phases
| Phase | Name | State (2026-10-27) |
|---|---|---|
| P00 | Runtime truth | DONE — evidence P00-1-runtime-truth |
| P01 | Matrix admission and approval binding | DONE — !approve <request_id> <digest> receipt gate live; receipts immutable; second claim denied; bot cannot self-approve |
| P02 | Minimal task, attempt, verification, workcell-result contracts | DONE — P02-1..3 |
| P03 | Autonomous execution | ACTIVE — see tracker below |
| P04 | Adaptive task decomposition | NOT STARTED |
| P05 | Economic model routing | NOT STARTED |
| P06 | Element / Matrix UX | NOT STARTED (thread approve shape agreed and tested, not wired) |
| P07 | Replay and scaling | NOT STARTED |
P03 increment tracker
| Increment | State | Note |
|---|---|---|
| P03.6f4 | PARTIAL | Host AF_UNIX isolation stands; stage race closed in f4a |
| P03.6f4a | Accepted offline | Descriptor-relative stage; no host worktree mount |
| P03.6f5 | PARTIAL | One-file write-back could publish outside the checkout |
| P03.6f5a | BLOCKED_ENVIRONMENT | BLOCKED_UNSAFE_PUBLICATION refusal; no kernel conditional replace |
| P03.6f6 | NOT STARTED | Confined deterministic verification of a written checkout |
| P03.6g | BLOCKED_POLICY on laptop | Real Cursor activation: transport proven to api2.cursor.sh:443; Cursor agent then needs agentn.global.api5.cursor.sh:443, which is not allowlisted. Decision: do not widen the allowlist |
| P03.7 | NOT STARTED | Matrix end-to-end canary on the chosen rail |
Roadrunner agentic-dev leaves (W1–W4)
| Leaf | State | Shipped as |
|---|---|---|
| R01 forge-agents in git + CI | DONE | autowww/forge-agents main, CI with sibling clones |
| R02 program canon in repo | DONE | this page |
| R03 agent branch lane + rulesets | PARTIAL | policy + docs/rulesets/*.json; rulesets applied by operator |
R04 Fleet agentic_dev_task + source guard |
DONE | forge-fleet v0.3.165 |
| R05 credential plane (courier, git identity) | PARTIAL | courier service in forge-agents; Granite FLEET_AGENTIC_GIT_TOKEN pending |
R06 Roadrunner service + !agent task + broker |
DONE | forge-agents 926edc4; Fleet rollout route v0.3.166 |
| R07 Element repo-task protocol | DONE | protocol page |
| R08 code_review_worker + HITL merge | DONE | Fleet run_review.py v0.3.166; forge-workcells code_review_worker |
| R09 freshness, branch GC, propagation | DONE | Fleet stale/hold matrix, /v1/admin/agentic-dev/branch-gc |
R10 agentic_dev class across peers |
DONE | node: auto, mesh advise workload: agentic_dev |
| R11 dual-wiki closure | DONE | FA-ADV-001, FA-REV-001 pairs; platform catalog/approval model; handbook rebuilt |
| R12 Element one-task canary | NOT STARTED | autowww/forge-calc-canary seeded; operator-driven; needs R03/R05/R06 operator steps |
| R13 web-GPT API/MCP bridge | PARTIAL | forge-web-bridge + guard + Open WebUI API keys (forge-fleet); lcdl.web_chat MCP tool (forge-lcdl); Granite rollout + key mint pending |
How it fits the ecosystem
forge-agents hosts Roadrunner (Matrix adapter, approval receipt, broker); forge-fleet is the only Granite execution rail (cursor_cli, agentic_dev_task); forge-workcells hosts the review workcell; forge-platform owns the approval model, envelopes, and this tracker; Lenses remains the ForgeRun system of record.
Phase A exit gates
| Gate | Definition | State |
|---|---|---|
| R1 | Approval binding: the executed task digest equals the digest in the forgeadmin !approve receipt; receipt consumed once |
Mechanism proven; no PASS run yet |
| R2 | Independent verification on changed bytes: a verifier outside the agent process checks the pushed/written file, not the agent's claim | No changed bytes yet (src/calc.py still placeholder) |
| R3 | Result and archive: Matrix result event ids, checksums.sha256, archive SHA-256 recorded |
Archives exist for FAIL runs only |
Phase A exit is not claimed.
Exit blockers (current)
- No Cursor session has produced a patch on the confined laptop rail (two runs failed: TLS facade defect, then non-allowlisted agent endpoint).
- All prepared calc approvals are consumed or expired; the next run needs a fresh receipt.
- The Roadrunner code base (
forge-agents) only entered git on 2026-10-27 (autowww/forge-agents); Granite could not receive it before. - No repo-aware Granite job exists yet (Fleet
cursor_clihost job v0.3.164 is generic).
Decisions
| Date | Decision |
|---|---|
| 2026-10-27 | Execution moves to the Granite Cursor CLI rail (Fleet-managed container, credential supplied from localhost at submit time). The local egress allowlist (api2.cursor.sh:443) is not widened. |
| 2026-10-27 | Remediation proceeds through pdca-prompts/roadrunner-agentic-dev/ (R01–R13): git-only code transfer, no SSH, agent branch lane, Element report protocol, separate review workcell with HITL merge. |
Evidence log
| Archive | SHA-256 | Verdict |
|---|---|---|
engineering-autonomy-PhaseA-analysis-20261027T101410Z.zip |
de673539941176370547f97313ac3f388c378bab2c2e876c7a2b485480e7788b |
BLOCKED (analysis; thread shape tested) |
engineering-autonomy-PhaseA-recovery-20261027T113415Z.zip |
9b94ca1eb661e950e106f70bb7a667e473d458664fe87a60eeeefe93cb49c023 |
FAIL (no patch) |
engineering-autonomy-PhaseA-run-20261027T121742Z.zip |
ad85cec0e18620a66a98bbd690c73ebf624180aabcbdf8d6c7167de3184c8a6a |
FAIL (appr_task_ce8c9548; TLS facade defect, fixed afterwards) |
Later run on req_task_3a7d3685 (appr_task_452bf91b): FAIL, exit 1, agent endpoint not allowlisted; staged under workbench/phase-a-run-stage/.
Trust boundary
A human approves every write-capable run with a fresh receipt. Agents cannot approve themselves, cannot reuse a receipt, and cannot claim PASS; only the independent verifier and the archive do. Widening egress allowlists, reusing approvals, or editing archives are outside what any agent may decide.
How to use this page
Before approving anything in Element, read the exit blockers. After any new evidence archive, add a row above with its SHA-256 and the true failing stage. Status words are limited to DONE, ACTIVE, PARTIAL, BLOCKED_*, NOT STARTED, PASS, FAIL.
Related / next
- Approval model
- Workcell catalog
- Channel agent catalog
- Remediation pack:
pdca-prompts/roadrunner-agentic-dev/00-master-sequence.md(workspace root)