docs: architecture-doc sweep (non-ADR) - reconcile diagrams and flow docs with the current code #246

New issue

Closed

opened 2026-07-17 19:49:33 +00:00 by hexajon · 1 comment

hexajon commented

2026-07-17 19:49:33 +00:00

(Migrated from codeberg.org)

Known drift candidates from the recent work, to check first:

request-lifecycle.md: the elicitation seam is fully removed (both consumers retired with the strict-omission convergence); any lifecycle step or diagram showing a server-to-client consent dialog is stale.
mcp-registration.md: mcp-config is now a pure snippet printer; all client wiring lives under madtea install (--mcp-client for the non-Claude-Code agents); the hook-delivery channel is plugin-only.
cli-commands.md: worktree add follows git's signature (-b creates, positional checks out); worktree remove and the five irreversible deletes are refusal-shaped; commit refuses the default branch with a per-call override.
error-handling.md: repo-scoped 404s are context-enriched (forge host, slug, per-item sources, host-mismatch note); the Forgejo generic-body classification is endpoint-contextual.
finish-workflow.md: the release gate is score-based with train grace and (once the cadence follow-up lands) the daily cap; finish's mainline return can carry the ahead-of-origin warning.
mcp-tool-annotations.md and packages-and-layout.md: verify against the removed tools/files (madt_delete, elicitation.go, hooks_claude.go) and the new ones (url_chain, deleterefusal, forgecontext).

Scope: every file under docs/architecture/, including any embedded diagrams (mermaid or ascii) - a diagram showing a removed component counts as drift. Each doc gets checked against the code it describes, with the check recorded (a one-line per-doc verdict in the PR body: current / updated / rewritten). ADRs are explicitly out of scope; where an architecture doc should cite a governing ADR it may link one (docs are allowed direct ADR references).

Acceptance criteria:

Every docs/architecture file carries a per-doc verdict in the PR body; drifted ones updated to match the code as merged.
No diagram or flow references a removed component (elicitation seam, madt_delete, binary hook channel, worktree force-remove).
check-doc-links.sh green; cross-links to reference docs and ADRs resolve.

The docs/architecture tree (NOT docs/adr - decision records are historical and stay as written) describes the system as built, and the last two days changed a lot of what it describes. Sweep every architecture doc against the current code and update where reality moved. Known drift candidates from the recent work, to check first: - request-lifecycle.md: the elicitation seam is fully removed (both consumers retired with the strict-omission convergence); any lifecycle step or diagram showing a server-to-client consent dialog is stale. - mcp-registration.md: mcp-config is now a pure snippet printer; all client wiring lives under `madtea install` (--mcp-client for the non-Claude-Code agents); the hook-delivery channel is plugin-only. - cli-commands.md: worktree add follows git's signature (-b creates, positional checks out); worktree remove and the five irreversible deletes are refusal-shaped; commit refuses the default branch with a per-call override. - error-handling.md: repo-scoped 404s are context-enriched (forge host, slug, per-item sources, host-mismatch note); the Forgejo generic-body classification is endpoint-contextual. - finish-workflow.md: the release gate is score-based with train grace and (once the cadence follow-up lands) the daily cap; finish's mainline return can carry the ahead-of-origin warning. - mcp-tool-annotations.md and packages-and-layout.md: verify against the removed tools/files (madt_delete, elicitation.go, hooks_claude.go) and the new ones (url_chain, deleterefusal, forgecontext). Scope: every file under docs/architecture/, including any embedded diagrams (mermaid or ascii) - a diagram showing a removed component counts as drift. Each doc gets checked against the code it describes, with the check recorded (a one-line per-doc verdict in the PR body: current / updated / rewritten). ADRs are explicitly out of scope; where an architecture doc should cite a governing ADR it may link one (docs are allowed direct ADR references). Acceptance criteria: - Every docs/architecture file carries a per-doc verdict in the PR body; drifted ones updated to match the code as merged. - No diagram or flow references a removed component (elicitation seam, madt_delete, binary hook channel, worktree force-remove). - check-doc-links.sh green; cross-links to reference docs and ADRs resolve.

hexajon commented

2026-07-18 21:54:27 +00:00

(Migrated from codeberg.org)

Reopening: the sweep that closed this marked finish-workflow.md current-as-is while it was missing the #224 ahead-of-origin warning on the return step and the release-gate note - both named in this issue's drift candidates - and several other architecture claims went unverified. A full re-verification (every file, every diagram, counts recomputed) lands with the public-release accuracy sweep PR, which closes this properly.

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

sixfold-space/madtea#246

No description provided.

Rows
Columns