diff --git a/docs/prds/self-development-loop.md b/docs/prds/self-development-loop.md new file mode 100644 index 000000000..65d1ca060 --- /dev/null +++ b/docs/prds/self-development-loop.md @@ -0,0 +1,53 @@ +# Self-development loop: archie develops its own codebase + +**Status:** Approved (2026-11-03, sam) **Scope:** how archie persistently takes +on development of archie-core itself. The plan is tracked as epic #1769 with +child issues #1770–#1775; this file is the decision record, the issues are the +work. + +## Decision + +Archie improves its own codebase through a closed loop, built in stages: + +1. **Self-intake** (#1770): a curator pass reads run outcomes, step transcripts, + gate failures and alerts, dedupes against open issues, and files new issues. + Archie files its own work; the maintainer approves priority. +2. **Approved-issue loop** (#1771): an approved issue runs the shipped + triage/implement workflows end to end — read-only plan, gated build, + adversarial self-review, daemon commits and opens a green PR. The maintainer + still merges at this stage. +3. **Implementation judge** (#1772): the prbench judge pattern scores diffs, + calibrated against the maintainer's merge decisions; auto-merge applies only + when the gate is green, the review stage is clean, and the judge is above the + calibrated bar. +4. **Outcome distillation** (#1773): a curator turns merged-run postmortems into + proposals for the repo's agent instructions, each added only because it + changes a decision; rules that stop changing decisions are removed. +5. **Canary** (#1774): self-directed changes ship through the canary release + window and are judged on the installed release before promotion. Rollback is + a plain revert, because every self-directed change is one gated commit. + +## Boundary + +Enforcement lives in the harness, never in the prompt (#1775). Changes to the +commit gate, the invariants in `AGENTS.md`, access control and grant scoping, +the daemon-only git path, and webhook HMAC verification may be proposed by +archie but are never merged by archie — they require a maintainer merge. +Everything else (workflows, curators, memory, docs, the dashboard) is fair game +for the loop. + +## Why + +Self-improvement degrades when it relies on the model choosing to follow rules. +Gates, scoped grants and the daemon's monopoly on git cannot be argued with; a +prompt can. Keeping quality measurable — a judge bar and a canary verdict as +numbers, tests guarding the protected seams — is what lets the loop widen +without turning the codebase to garbage. + +## Consequences + +- One issue → one small PR applies doubly to self-directed work: past about 100 + lines or any new mechanism, the change stops and reassesses. +- Every self-directed commit cites the issue that authorized it. +- Rule proposals from the distillation curator must name the run that triggered + them, and `AGENTS.md` stays short enough to read in full every session.