Docs: promote the shipped review stage into docs/architecture and reconcile CLAUDE.md #271

Closed
opened 2026-10-27 13:35:39 +00:00 by sam · 0 comments
Owner

Under the scope-discipline rule merged as PR #533, a design is promoted into docs/architecture/ only once it is built and true. This is that promotion, and it is deliberately a separate bead so it is not lost when the feature lands and attention moves on.

Do three things once the stage ships:

  1. Promote the docs/prds/ decision into docs/architecture/, describing the review stage as it actually works -- not as designed. Cut anything a reader could learn from the code.
  2. Update ARCHITECTURE.md's task lifecycle: queued -> running(workflow:stage) -> pr_open -> merged|rejected gains a review stage that can divert to waiting_human before pr_open. The current text does not mention it.
  3. Reconcile CLAUDE.md's Development Protocol. It currently tells a human or agent contributor to run the adversarial pass by hand. Once archied does this for the PRs it opens, that section needs to say which path applies to whom, or it will read as describing a manual step that is now automatic.

CLAUDE.md's own rule: a comment or doc that contradicts its code is worse than none, because the next reader trusts it.

Acceptance criteria

docs/architecture/ describes the shipped stage; ARCHITECTURE.md's lifecycle includes the review stage and the waiting_human diversion; CLAUDE.md distinguishes the manual contributor pass from archied's automated one; no doc still claims review is only manual.

Close reason

Promoted docs/prds/adversarial-self-review.md to docs/architecture/adversarial-review.md (as shipped), added the review stage to ARCHITECTURE.md's task lifecycle, and reconciled CLAUDE.md's Development Protocol (contributor opt-in vs archied's automatic pass). PR #785. Documented parked, not waiting_human (h019.1 resolved the state).


Imported from beads archie-core-h019.7 · GitHub #557 · type task · priority P2 · created 2026-08-21 · closed 2026-09-09

Under the scope-discipline rule merged as PR #533, a design is promoted into docs/architecture/ only once it is built and true. This is that promotion, and it is deliberately a separate bead so it is not lost when the feature lands and attention moves on. Do three things once the stage ships: 1. Promote the docs/prds/ decision into docs/architecture/, describing the review stage as it actually works -- not as designed. Cut anything a reader could learn from the code. 2. Update ARCHITECTURE.md's task lifecycle: queued -> running(workflow:stage) -> pr_open -> merged|rejected gains a review stage that can divert to waiting_human before pr_open. The current text does not mention it. 3. Reconcile CLAUDE.md's Development Protocol. It currently tells a human or agent contributor to run the adversarial pass by hand. Once archied does this for the PRs it opens, that section needs to say which path applies to whom, or it will read as describing a manual step that is now automatic. CLAUDE.md's own rule: a comment or doc that contradicts its code is worse than none, because the next reader trusts it. ### Acceptance criteria docs/architecture/ describes the shipped stage; ARCHITECTURE.md's lifecycle includes the review stage and the waiting_human diversion; CLAUDE.md distinguishes the manual contributor pass from archied's automated one; no doc still claims review is only manual. ### Close reason Promoted docs/prds/adversarial-self-review.md to docs/architecture/adversarial-review.md (as shipped), added the review stage to ARCHITECTURE.md's task lifecycle, and reconciled CLAUDE.md's Development Protocol (contributor opt-in vs archied's automatic pass). PR #785. Documented parked, not waiting_human (h019.1 resolved the state). --- _Imported from beads `archie-core-h019.7` · GitHub #557 · type task · priority P2 · created 2026-08-21 · closed 2026-09-09_
sam added the mediumtask labels 2026-10-27 13:35:39 +00:00
sam self-assigned this 2026-10-27 13:35:39 +00:00
sam closed this issue 2026-10-27 13:35:39 +00:00
sam added a new dependency 2026-10-27 13:41:51 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: sam/archie#271