ADR-0029: Headless Evolve With Staged Proposals¶
Metadata¶
Status: Accepted (2026-10-22) · Date: 2026-10-22 · Deciders: nguyenhuuca · Tags: agents, ci, security Related: reverses the "local only" part of ADR-0027 D4; the allowlist (D2), the eval gate (D3), pruning (D5) and compress (D6) stay as they are
Context¶
- The first weekly
agent-evolve.yml(2026-10-21) wrote nothing. Headless Claude Code treats.claude/files as sensitive and asks permission on every edit, and CI cannot answer. - The same run hit
Refusing to create empty bundlewhile packaging, then still filed a "no proposal" issue forcompress:2026-10(#50, closed by the owner). - The owner wants the loop back in CI on a weekly schedule, with the same checks as a local run.
Decision¶
D1. The agent stages file copies; it never touches .claude/ or git¶
In --headless mode the agent writes the full new content of every file it would change under evolve-out/<slug>/tree/:
| Repo path | Staged path |
|---|---|
.claude/agents/worker-reviewer.md |
evolve-out/<slug>/tree/dot-claude/agents/worker-reviewer.md.staged |
CLAUDE.md |
evolve-out/<slug>/tree/CLAUDE.md.staged |
evals/seeded/<id>/case.json |
evolve-out/<slug>/tree/evals/seeded/<id>/case.json.staged |
- No staged path has a
.claudesegment or a file name Claude Code treats specially, soWriteneeds no permission. - A file cannot be deleted this way. Rule files are never deleted (ADR-0027 D2), and compress removes lines inside files.
- The agent holds a read-only token, as before. Its tools:
Read,Glob,Grep, read-onlygit diff/show/log/rev-parse/ls-files, andWrite/Editscoped toevolve-out/**. It cannot write.git/or.gitattributes(a planted git helper would run under the allowed git commands), cannot read/procor/sys, has no shell readers (cat,grep,head,tail) and no web tools. Git runs withGIT_CONFIG_NOSYSTEM=1andGIT_CONFIG_GLOBAL=/dev/null.
D2. A manifest row for every signal¶
evolve-out/manifest.json is an array with one row per signal:
- a proposal:
{signal, slug, case, kind, body, message}, wherekindisrule,case-only,not-eval-provenorcompress; - no proposal:
{signal, kind: "none", body}, wherebodyexplains why.
The ship job files a "no proposal" issue, which closes the signal, only for a none row. A signal with no row, or a row without a tree/ (agent crash, turn limit, broken artifact), is left for next week's run. A row whose staged files are invalid becomes a "rejected (staging)" issue and closes the signal.
D3. The ship job builds the branch; the agent's files are data¶
node scripts/evolve.mjs apply --dir <proposal>/evolve-out/<slug> --base <main sha> --branch evolve/<slug> --message <file>:
- accepts only regular files ≤ 64 KiB whose decoded path matches the Evolve allowlist or a new case path (ADR-0027 D2), and rejects
.., symlinks and an empty tree; - writes the commit with git plumbing (temporary index,
commit-tree,update-ref), so the ship job's working tree, and theevolve.mjsit runs, stay onmain.
Then check-paths and gate run unchanged. A pass becomes a PR labelled evolve (draft for compress and not-eval-proven). A fail becomes an issue. Nothing is merged: the owner merges.
D4. Schedule and cost¶
- The workflow runs every Monday at 09:00 Asia/Ho_Chi_Minh, or on
workflow_dispatch(owner only, optionalsince). - It handles at most 3 signals per run (ADR-0027 D4 budget). The agent step costs about $1–5 a week (approximate). Weeks with no new signal cost $0, because the agent does not start.
Consequences¶
- The local
/evolveflow is unchanged. Headless is a second way in, with the same gate. - The ship job still pushes
evolve/*branches with a write token. The PR is the owner's Gate 2. - Everything published (issue and PR bodies, gate tables) passes a token-shape redaction (
sk-ant-,gh?_,github_pat_, JWT) first. - PRs opened with
GITHUB_TOKENdo not trigger other workflows, and the repo setting "Allow GitHub Actions to create and approve pull requests" must be on (it was for the 2026-10-21 version). - Not yet proven: that headless
Writetoevolve-out/raises no permission prompt. The firstworkflow_dispatchrun checks it; if it fails, disable the workflow again.
Changelog¶
- 2026-10-22: accepted.