For governance-heavy changes, run claw governance doctor --json first and use its reads, checks, externalPending, and staleDocs sections as the routing baseline.

For a new ADR, reserve the number first with scripts/adr-reserve.mjs; do not choose numbers by scanning filenames manually.

Update the canonical document first: Constitution, ADR, ownership doc, storage boundary, naming guide, catalog guide, or interface matrix. Durable ADRs and governance changes must use the Decision Tension Rubric.

Add or update the decision-map row with: decision, canonical document, and guardrail or validation.

When the decision introduces durable meta-code, update docs/discoverability.registry.json so the canonical source is reachable from AGENTS.md/CLAUDE.md, this skill, docs routers, and CLI discovery within two hops.

For accepted ADRs, keep the row aligned with docs/adr-operational-coverage.manifest.json; a map row without a real guard/test or CLI search/inspect route is incomplete.

Remove stale rows only when the canonical source has been retired or superseded.

Before closure, run node scripts/discoverability-check.mjs closure --changed-file docs/decision-map.md --json and include the real claw search ... --json, claw inspect ... --json, and discovered artifact in the closing report. If discovery cannot run or cannot find the affected row's artifact, close as PARTIAL/BLOCKED.

Run docs alignment checks or add a guard if the map should enforce a snippet.

Constraints

Keep rows short and factual.

Do not copy long ADR rationale into the map.

Every row should help an agent choose what to read next.

Do not accept "docs updated" as closure without CLI discovery evidence for closure-gated decisions.

decision-map-maintenance

Maintain the decision map as an index, not a duplicate source of truth.

Procedure

Identify the durable decision being added, changed, or retired.