PRD 0012: Stuck-agent recovery flow #18

Merged
didericis merged 13 commits from agent-unstuck into main 2026-05-25 04:19:52 -04:00

13 Commits

Author SHA1 Message Date
didericis e10634abe7 docs(prd-0012): split into overview + 4 implementation PRDs
test / unit (pull_request) Successful in 12s
test / integration (pull_request) Successful in 22s
PRD 0012 becomes the cross-cutting overview (stuck categories taxonomy,
sidecar-vs-in-container rationale, implementation chunk pointers).
Implementation detail moves into four follow-on PRDs that 0012
references: 0013 (supervise plane foundation), 0014 (cred-proxy block
remediation), 0015 (pipelock block remediation), 0016 (capability
block remediation).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-25 03:40:02 -04:00
didericis 5c3c60cff4 docs(prd-0012): explain why the MCP server is a sidecar, not in-container
test / unit (pull_request) Successful in 13s
test / integration (pull_request) Successful in 23s
Captures the rationale for placing the MCP server outside the agent
container. The bottle wall doesn't strictly require it (the operator
TUI is the actual gate), but pattern consistency, audit metadata
trust, connection lifecycle, future enforcement headroom, and
pipelock cleanliness all argue for sidecar placement.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-25 03:05:55 -04:00
didericis c71713e7d3 docs(prd-0012): switch /stuck to three structured MCP tool calls
test / unit (pull_request) Successful in 12s
test / integration (pull_request) Successful in 24s
Replaces the text-only /supervise/notify protocol with three MCP tools
the agent calls directly: cred-proxy-block, pipelock-block, and
capability-block. Each tool carries the agent's proposed config file
(routes.json, pipelock allowlist, or Dockerfile) plus a justification.
Adds a new MCP sidecar, a read-only current-config mount in the agent
container, and renames "capability gap" to "capability block" to match
the tool name. The text-only-vs-structured tradeoff is captured as an
Open question with pros/cons on both sides.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-25 02:53:26 -04:00
didericis e5a4c324a0 docs(prd-0012): name the three stuck categories and add pipelock path
test / unit (pull_request) Successful in 12s
test / integration (pull_request) Successful in 22s
Introduces cred-proxy block, pipelock block, and capability gap as the
three named categories of stuck. Adds pipelock-edit support (restart-
based for v1) parallel to the existing cred-proxy routes-edit path,
plus a pipelock audit log. Broadens Goals to cover all three paths.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-25 01:47:24 -04:00
didericis 49082dfadf docs(prd-0012): adopt text-only notify protocol + SIGHUP routes reload
test / unit (pull_request) Successful in 12s
test / integration (pull_request) Successful in 23s
Rewrites Scope, Proposed Design, Data model, and Open questions to
match the model where /supervise/notify is text-in/text-out, routes
edits + SIGHUP reload are supervisor-side tooling, and manifest
rebuilds are the heavy path. Adds the per-bottle routes-edit audit log.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-25 01:36:29 -04:00
didericis 95a4433d39 docs(research): drop auto-respawn from the supervisor design
test / unit (pull_request) Successful in 13s
test / integration (pull_request) Successful in 24s
The autonomous "review comment → respawn bottle with comment as
next prompt" loop is the one feature that opens a prompt-injection
vector the bottle wall can't close (a public commenter would get
to issue instructions inside the agent's perimeter on every
launch). The available mitigations — commenter allowlists,
prompt-injection regex screens, private-repo defaults — are all
soft. The durable defense is to keep the human between the
review comment and any next agent prompt.

So `supervise` is now strictly notify-only. The `auto_respawn`
manifest field, the "with auto_respawn: true" behavior paragraph,
and the matching trust-model edge case all go. The reasoning
stays in the "Where to be conservative" bullet so the decision
isn't re-litigated later.
2026-05-25 00:50:41 -04:00
didericis f733e7195f Merge branch 'built-in-supervisor' into agent-unstuck
test / unit (pull_request) Successful in 14s
test / integration (pull_request) Successful in 22s
Brings the built-in supervisor research note (TUI + PR feedback design)
onto the agent-unstuck branch alongside the existing PRD 0012 +
companion research stack.
2026-05-25 00:20:30 -04:00
didericis 02647917b2 docs(research): built-in supervisor design (TUI + PR feedback) 2026-05-25 00:15:18 -04:00
didericis 1f9722ae27 docs(research): add Betterleaks switching analysis
test / unit (pull_request) Successful in 13s
test / integration (pull_request) Successful in 28s
2026-05-24 23:59:42 -04:00
didericis c33930290f docs(research): survey gitleaks dashboards + add baseline-file primitive
test / unit (pull_request) Successful in 13s
test / integration (pull_request) Successful in 24s
2026-05-24 23:54:46 -04:00
didericis a74dd2b97f docs: research on git-gate commit approval; link from PRD 0012
test / unit (pull_request) Successful in 12s
test / integration (pull_request) Successful in 22s
2026-05-24 23:39:17 -04:00
didericis 83756fa8c9 docs(prd-0012): open question for gitlock/pipelock exception flow
test / unit (pull_request) Successful in 12s
test / integration (pull_request) Successful in 22s
2026-05-24 23:12:55 -04:00
didericis b4c9e149b0 docs: add PRD 0012 — stuck-agent recovery flow
test / unit (pull_request) Successful in 12s
test / integration (pull_request) Successful in 22s
2026-05-24 23:10:30 -04:00