<!-- CURSOR_AGENT_PR_BODY_BEGIN -->
## Summary
ARCHITECTURE.md still described the v0.5 hand-fired implementer → reviewer
→ addresser era. This refreshes it into an orientation document for the
current orchestrator: unattended dispatch, the Mercy watch phase, automatic
conflict resolution, the discovery/eligibility supply tier, retro drones +
harvest-followups, and the S3 receipt mirror each now have a clear place,
and the module map covers every non-test module under src/ (module count
rose from 83 to 111 since the ticket was filed, because the AI-245/246/247
cli.ts split landed in between — the CLI-surface rewrite below reflects
its end state). The headline deliverable is an inline Mermaid diagram
covering the full loop end-to-end.
## Why It's Needed
node scripts/arch-drift.mjs (added by this PR — see below) measured the
gap before this change: 53 of 111 non-test src/ modules (48%) were not
named anywhere in the doc, and the concepts retro, conflict resolution,
S3/receipt-mirror, and discovery/eligibility had zero mentions. A
reader of the old doc would not learn that unattended dispatch — the
system's current whole shape — exists at all.
## Changes
- New ## The full loop (end-to-end) section with the headline Mermaid
diagram: supply (discovery → eligibility → ready-queue curation) →
dispatch (scheduled tick → claim → fire, with caps + the concurrency
lock) → build (implementer → PR) → review loop (reviewer fan-out →
addresser, bounded to the review_loops budget with convergence
early-exit) → Mercy phase (bounded auto-address, never gated on
APPROVED) → PARK → conflict path (CONFLICTING → auto-resolve → CI
restored) → human merge (the one hexagon-shaped node — nothing else
in the diagram merges) → write-back (post-merge → Linear Done →
dependent tickets released) → telemetry (receipts → optional S3 mirror →
analytics/eval) → feedback (retro + harvest findings file new Linear
tickets, which re-enter supply). The pre-existing three-stage-loop
diagram is kept as a smaller detail inset on the Build + Review-loop box,
rather than folded in — the per-child fan-out detail would overload the
master graph without adding new information.
- Six new subsystem sections: Unattended dispatch (the scheduler),
Mercy watch phase, Automatic conflict resolution, Discovery / eligibility
(the supply tier), Retro drones + harvest-followups (the feedback loop),
Off-host telemetry (S3 receipt mirror).
- Rewrote ## CLI surface for the post-split shape: cli.ts is
registration-only (157 lines, 0 verbs inline, down from 6,501/30);
30 verbs live across 17 src/cli/<verb>.ts files + src/cli/shared/;
states the AI-245 (help-parity harness) → AI-246 (six large verbs) →
AI-247 (remaining 24) chain that produced it. Did not touch
src/cli.ts / src/cli/* themselves (AI-246/AI-247 own those files).
- Expanded the module map to name every non-test src/ module,
including the new src/cli/* split modules and the ~40 supporting
modules (dispatch-lock/queue-order/tick-outcome, retro-\*, conflict
resolution, discovery/eligibility, S3 mirror, review-loop-adjudication,
etc.) that existed but were never named.
- Corrected a standing inaccuracy while touching the "moat" section:
it previously credited lifecycle.ts as the unattended-loop glue;
lifecycle.ts is actually just cancel/list-active (confirmed by
reading it) — the real orchestration lives in runner.ts, which now
says so.
- scripts/arch-drift.mjs (new) — computes non-test-module ↔
ARCHITECTURE.md inline-code-mention coverage, with an explicit,
reasoned allowlist (ARCH_DRIFT_ALLOWLIST) for the ten src/cli/shared/*
helpers + one test fixture that are documented collectively rather than
individually.
- src/arch-drift.test.ts (new) — vitest pin wiring the drift check
into pnpm test, on the same precedent as src/agents-md-verbs.test.ts
(which pins AGENTS.md's verb list against cli.ts). Asserts zero
undocumented modules, no stale allowlist entries, and that every
allowlist entry names a real file with a non-empty reason.
- No changelog prose: kept the existing section skeleton, removed stray
AI-NNN ticket-number references from the new prose (the original doc
had zero — matching that convention) except the one explicitly required
by the ticket (the AI-245/246/247 chain in ## CLI surface).
## Breaking Changes
None. Documentation + a new opt-in-nothing test file; no production code
touched.
## Test Plan
- node scripts/arch-drift.mjs → NOT mentioned: 0 (0%) (was 53/111,
48%, before this PR; re-measured against the post-cli-split module
count per the ticket's 2026-07-31 update, not the stale 83/50 snapshot).
- pnpm typecheck — clean.
- pnpm test (vitest + Python) — 83 test files / 2305 tests passed,
including the new src/arch-drift.test.ts (3 tests) and the
pre-existing src/agents-md-verbs.test.ts (untouched, still green,
confirming src/cli.ts / src/cli/* were not edited).
- Mermaid rendering verification (the PR body must state this): GitHub
renders Mermaid client-side with mermaid.js, so I validated all four
fenced mermaid blocks two ways rather than eyeballing syntax:
1. Extracted each block and ran it through mermaid.parse(text, {
suppressErrors: false }) (the exact parser GitHub's renderer calls
before drawing) inside a Node + jsdom harness. I first confirmed the
harness itself catches errors by feeding it a deliberately broken
diagram (unclosed bracket) and watching it fail with a real parse
error at the correct line; all four real blocks then parsed cleanly.
2. Rendered the two larger diagrams (the end-to-end diagram and the
state-model diagram) to PNG via @mermaid-js/mermaid-cli (real
headless-Chromium Mermaid rendering, not just parsing) and reviewed
them visually for both correctness and readability — this is what
caught and fixed an earlier draft where a caps-decision diamond and a
stray node visually crowded into the wrong subgraph box; the current
version reads top-to-bottom in one pass.
(Scratch validation harness and rendered images were temporary and are
not part of this diff.)
## Verification Artifact
[Rendered end-to-end architecture diagram (headless-Chromium Mermaid render, matches what GitHub will draw from the fenced block in ARCHITECTURE.md)](https://cursor.com/agents/bc-fb884295-b148-4450-bffc-0e41d6eff9ab/artifacts?path=%2Fopt%2Fcursor%2Fartifacts%2Farchitecture_end_to_end_diagram.png)
drift check output before/after:
before: src modules (non-test): 111 / mentioned: 48 / NOT mentioned: 53 (48%)after: src modules (non-test): 111 / mentioned: 101 / allowlisted: 10 / NOT mentioned: 0 (0%)
<sub>To show artifacts inline, <a href="https://cursor.com/dashboard/cloud-agents#team-pull-requests">enable</a> in settings.</sub>
<!-- CURSOR_AGENT_PR_BODY_END -->
<div><a href="https://cursor.com/agents/bc-fb884295-b148-4450-bffc-0e41d6eff9ab?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-web-light.png"><img alt="Open in Web" width="114" height="28" src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a> <a href="https://cursor.com/background-agent?bcId=bc-fb884295-b148-4450-bffc-0e41d6eff9ab&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img alt="Open in Cursor" width="131" height="28" src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a> </div>