Historical snapshot, archived on 2026-10-09. This audit's findings were resolved on 2026-10-03 (last section). The rules it states now live in the decision index (reading protocol, maintenance rules), the records themselves, docs/development/documentation.md and the specification; read those first. Retained for provenance.

ADR organization audit — 2026-10-02¶

Scope and method¶

Reviewed all 65 records present at commit 5cf499f3: 12,219 lines, IDs 001–064 with two records numbered 040. Read their decisions, statuses, addenda and relationships, then compared the documentation entry points, CLAUDE.md, the specification and the site's navigation. This is a point-in-time documentation audit, not a certification that each decision has been implemented or deployed.

The topic index accounts for every record exactly once. The site previously listed 44 records and omitted 21. The largest records were notifications (870 lines), polls (590) and student view (558): together 2,018 lines whose final rules could require reading multiple historical amendments.

Findings and treatment¶

Finding	Evidence	Treatment
No common entry point; incomplete chronological site list	65 records, 44 navigation entries	One complete topic index used by the site and linked from `CLAUDE.md`; removed the parallel per-record navigation list.
Ambiguous identifier	Both ADR-040 files, references in ADR-019 and spec 02/04/05/06	Preserve filenames; explicitly qualify the two records and link documentation references to the intended file. Existing code comments still use the historical number.
Original choices and later overrides read as equally current	ADR-014 audience and reveal; ADR-018 entry point and preview; ADR-030 events and hooks	Local reading maps, stable section links and scoped historical notes; original rationales retained.
Obsolete cross-record status	ADR-009 excludes ADR-011; ADR-058 calls accepted ADR-059/060 proposals and grading unwired	Correct the status using already accepted decisions, retaining intermediate history where it explains the evolution.
Missing reverse links	ADR-025/032 to 053, 036 to 041, 037/046 to 063, 041 to 056, 055 to 058	Add scoped links at the older entry points. These are amendments or extensions, not whole-record replacements.
A copied later decision can drift	ADR-049's second addendum repeats ADR-057's mode rules	Replace the repeated mode description with the authoritative ADR-057 link and exact affected points; retain the addendum anchor.
Historical open questions remain phrased as open after settlement	ADR-035 D06; ADR-051 D21	Point to their documented settlement while preserving the M6 implementation boundary.
Delivery notes and decisions share the same status	ADR-041, 045, 056, 057, 062	Reading protocol distinguishes acceptance from implementation; ADR-045's old obligations are explicitly historical. Remaining examples below need a separate implementation audit.

Overlap that should remain separate¶

These groups are related decisions, not duplicate records to merge:

Platform (001–012, 016, 028, 055): framework, persistence, jobs, deadlines, runner isolation and operations have distinct trade-offs. Imported requirement IDs and obsolete deployment details need their status overlays; the deployment runbook owns actual operating commands.
Access and authoring (013, 017–024, 027, 032, 034, both 040, 051, 053–054, 061): sharing, personal preferences, preview, impersonation, API authorization and confined sessions have different trust boundaries. Repeated references to access invariants are useful local rationale.
Question types (015, 019, 021, 024, 036, 040 circuit, 046, 056): trial execution, server grading, editing and parameterization are different responsibilities. AC stimuli extend transient circuit grading rather than replacing it.
Evaluation and feedback (014, 020, 025–026, 031, 033, 037, 044, 050, 052): templates, retained attempts, penalties, bonus points, publication and student-visible material each constrain a different step.
Statistics and drill (038–039, 041–043): population selection, server-measured dwell, discrimination, distractors and spaced practice share data but settle different rules. Read 038's population before its extensions; do not infer that exercise attempts count in pool statistics.
LLM (045, 058–060, 063): stub history, gateway, authoring, nightly review and grading remain separate. Start at 058 for infrastructure and 063 for grading; 063 changes specific parts of 045/058 and permits a deliberate justification copy, not automatic disclosure of private criteria.
Merge and projects (007, 029, 035, 047–049, 057, 061–062, 064): 029 is wholly superseded by 035; 049 is only partially amended by 057. Project CI runners (007) and question execution (016) must not be conflated. Read 064 for project deadline application and 012 for freeze semantics.
Notifications (030): common delivery guarantees recur beside each event's specific races and failure modes. Preserve those distinctions, especially the residual pointsAcrossRegrade limitation; avoid replacing them with a misleading promise of exactly-once delivery.

Follow-up findings recorded on 2026-10-02¶

These observations are deliberately not new architectural decisions:

Location	Follow-up needed
ADR-001/002/004/008 inherited bodies	Historical process names, library versions and original library choices are not an installed-dependency manifest. Compare against code and spec before changing a design claim.
ADR-044 Status versus §2	Status calls the `grading` member optional, while §2 calls it required. Reconcile against the actual contract and its history.
ADR-056 Status and Consequences	“Not implemented yet” coexists with implementation addenda; the consequences mention an `(attempt, item)` column while §5 names `attempts.instances`. Check the shipped schema before rewriting the delivery summary.
ADR-057 Status	The original “Not implemented yet” is not sufficient to establish present progress; use merge progress and task cards.
ADR-041 Rollback	The paragraph describes slice 1 after later slices have been recorded. A current rollback procedure belongs in the operational documentation.
Imported ADR-047–049	Original names and milestone/requirement IDs remain historical. Preserve the Quiz translation in Status when extracting a section for an agent.
ADR-030 and other long records	Future delivery details should go into task cards or runbooks. Splitting existing bodies requires preserving external section references; a cosmetic deletion of repeated safety rationale would lose context.

No product open question was settled, no record renumbered, and no decision was marked wholly superseded merely because a newer record touches its topic.

Resolution after code review — 2026-10-03¶

The follow-up checked the implementation at 59c8925a and retained pending product decisions. No runtime code was changed. The archive is now loaded only for provenance; it is excluded from site search.

Finding	Verified resolution / source
Inherited platform/library assumptions	ADR-001/002/004/008 now distinguish Quiz's implementation from the inherited proposal. Evidence: root/workspace manifests, `apps/api/src/{config,app,server,events,jobs}.ts`, web router/UI/i18n. Original records remain in `history/`. The cross-process event relay remains planned.
ADR-044 grading contract	Corrected to required, as `packages/core/src/client.ts` declares.
ADR-056 delivery and storage	Implemented migration `0051_parameterized_questions.sql`, `db/live.ts`, `db/drill.ts`, `live/parameters.db.test.ts` and drill tests establish persisted values. Removed the obsolete per-item column claim.
ADR-057 journal delivery	M4-07/08/09 implemented: `journal/quiz.ts`, `mode.ts`, `quiz.db.test.ts`, `writes.db.test.ts`. M4-10–13 remain pending; no blanket “not implemented” or claim that switches already exist.
ADR-041 rollback	Old slice-1 rollback marked historical; current operations link to the deployment runbook. No destructive rollback invented.
Imported ADR-047/048/049	Entry points distinguish pending M6/group work from the implemented journal and its ADR-057 amendments. Future accepted requirements remain intact.
Long ADR-014/018/030	Consolidated current rules checked against poll, preview, notification, grading/result services and their contracts/tests. Full histories and old anchors preserved. At-most-once loss windows, privacy exceptions, preview limits and regrade notification limitations remain explicit.
Specs 00/06/07	Initial phases/comparison/log and settled questions moved to linked historical pages. Question numbers remain stable; unmarked assumptions and partially settled questions remain active.
Specs 01/02/08	Corrected institutional LLM settings, retakes, attempt events, exercise/poll lifecycle, immediate-feedback restrictions, API path and command registry against code.
Specs 04/05	Corrected generator/LLM/grading contracts, canonical UUID and planned CLI scope, registry ownership, journal revision fields, gateway calls and implementation boundaries. Detailed table intent is a separate reference, not default architecture context.
Agent entry point	`CLAUDE.md` links to task-specific reading instead of duplicating the package map, seed inventory and development guide. Mandatory invariants remain; admin access wording is aligned with the already accepted Super Powers scope in ADR-054 and `guards.ts`.

Remaining product choices and delivery work are tracked explicitly: open questions stay in spec 06, accepted future delivery in merge progress, historical evidence in linked archives. The detailed data-model reference still includes explicitly planned schema; always verify actual declarations before a migration. This audit does not establish that production has deployed every committed feature.