Plan adr

Current — the latest status report. Reports freeze once published; corrections appear in later reports.

ADRs: schema-validated, wiki-synced architecture decisions

Why

Decisions are currently scattered across plan docs, commit messages, and spec changelog entries. This project has already made a dozen decisions worth a permanent, findable record (skill-based edges vs typed contract, deterministic ev, green-gates merge, the taxonomy axes). An ADR is the right container: one decision per file, schema-validated front matter so tooling can trust it, published to the wiki so non-repo readers see it.

Design — reuse over invention

• Location: docs/adr/NNNN-slug.md (4-digit, monotonically numbered).
• Front matter validated against schema/adr.schema.json (same JSON-Schema subset the capabilities gate uses): id (int), slug, title, date, status (proposed | accepted | deprecated | superseded), deciders (list), tags (list), supersedes (int|null), superseded_by (int|null).
• Body sections required: Context, Decision, Consequences (Alternatives optional). The body is written once; only status / superseded_by mutate afterward — Nygard rules, matching our supersede-don't-edit discipline for plans.
• Sync: each ADR registers in .work/published.json (key adr/NNNN-slug, page ADR-NNNN-slug) at creation — the existing wiki-add machinery. Publish semantics are roadmap-style, not plan-style: republish on hash change, because a status flip (proposed→accepted) must reach the wiki.
• CLI (bin/worklog):
  • adr new <title> [--status proposed] [--deciders a,b] [--tags x,y] [--supersedes N] — next number, scaffolded file, ledger registration, prints path.
  • adr list — id / status / title table.
  • adr check — validate every ADR: schema, unique ids, filename↔front-matter agreement, supersedes/superseded_by pairs consistent, required body sections present. Nonzero with named problems.
• Enforcement: hooks/pre-commit runs adr check when docs/adr/ exists (same guard style as the fold tests). CI inherits it via the shared script.
• Seeds — three real ADRs written from this project's history:
  • 0001 Append-only event log + fold + union merge (accepted)
  • 0002 Edge integration: skills first, typed dispatcher contract hybrid (accepted, records the v1.4→v1.6 arc)
  • 0003 Green-gates merge policy (accepted)
• Docs: wiki-publish skill's default set gains "every ADR in docs/adr/ (republish on change)"; wiki Home gains an "## Architecture decisions" section; cli-reference + user-guide get short ADR entries.

Tasks

• (P1) worklog adr new|list|check + schema/adr.schema.json + pre-commit guard + tests (tests: scaffold round-trips check; bad status rejected naming field; duplicate id rejected; supersedes pair mismatch rejected; missing Context section rejected; ledger entry written on new)
• (P1) Seed ADRs 0001–0003 from real decisions; wiki-publish skill default set + Home section + user-guide/cli-reference entries

Verification

• All suites incl. new tests/test_adr.py green; coverage gate holds.
• worklog adr new → file validates, ledger entry exists; adr check catches each seeded failure mode.
• Wiki shows ADR-0001..0003 + Home section; status-flip republish verified by editing a seed's status and re-running the publish flow (hash changes).
• PR merged via green-gates loop; v0.8.0 unreleased changelog entry.