adr: relocate ADRs to /adr; add ADR-0002 (location) + retrospective ADR-0003-0014

[JimCollinson]

Summary

Two things in one change:

1. Relocate the ADR home from docs/adr/ to repo-root /adr. In this repo docs/ is the published GitBook product (.gitbook.yaml sets root: ./docs/), so ADRs under docs/ would leak into the public developer-docs site (nav / search / llms.txt) and get swept by the docs tooling. Recorded as ADR-0002.
2. Add the retrospective decision record for the docs automation and the developer skill — ADR-0003 through ADR-0014 — capturing decisions that were made and implemented before the ADR process (PR ci: add ADR governance compliance #56) existed.

What changed

• git mv docs/adr → adr (moves ADR-0001, TEMPLATE.md, TOOLING.md, README.md).
• Repointed the governance config at the new location:
  • .adr-kit.yaml → adr_directory: adr
  • scripts/adr-governance.py → ADR_DIR = Path("adr")
  • .github/workflows/adr-governance.yml → path filters → adr/**
• Added adr/ADR-0002 … ADR-0014.
• Added planning/skill-open-questions.md (open items the skill ADRs leave — see below).

The ADRs

• 0002 — ADRs live at /adr, not docs/adr (this change; a normal prospective decision)

Automation

• 0003 — verification-block source-of-truth model
• 0004 — tiered execution: deterministic detection / efficient-model metadata sweeps / frontier-model prose
• 0005 — subscription-billed daily scheduled routine (over repository_dispatch webhooks and API-billed CI)
• 0006 — two-track PR envelope: metadata "sweeps" vs prose "pro sweeps", enforced by branch-scoped guards
• 0007 — fail-closed operation and the GitHub artifact topology

Docs platform & authoring

• 0008 — GitBook + GitHub, serving a dual human/LLM audience
• 0009 — human review gate now, with a path to full automation (AI-panel review + human escalation)
• 0010 — CLAUDE.md as the enforced authoring-constraints contract
• 0011 — information architecture & content design (route-first navigation with Diátaxis)

Developer skill

• 0012 — skill purpose / single-file format / in-repo location / vendor-agnostic distribution
• 0013 — skill freshness: three-part staleness defence + content tiering
• 0014 — skill maintenance workflow + feeds_skills registry wiring

Status: Accepted, retrospectively

ADR-0003–0014 record decisions taken before this ADR process existed. They are marked Accepted with an explicit Acceptance: Retrospective line — ratified by the implementation already built on them and by this review pass, not by prospective pre-implementation review. This gives them immutability (protection from casual edits) while staying honest about how acceptance happened. ADR-0002 is an ordinary prospective decision.

Open items (non-blocking)

Tracked in planning/skill-open-questions.md — most notably the skill's canonical name (autonomi-developer) vs the current on-disk skills/start/, and a possible future migration to WithAutonomi/skills. These resolve later via superseding ADRs, not edits.

Validation

• python3 scripts/adr-governance.py passes against the 14 ADRs at /adr (verified on a mirror of this branch: ADR governance passed (14 ADR file(s) checked)).
• The ADR Governance check runs on this PR against adr/**; sweep-guard / prose-guard / sweep-sha-reachability green-skip on this non-claude/* branch.

Reviewer notes

• This re-points the team-standard ADR location for this repo only, via the standard's own adr_directory knob — the shared mechanics (template, lifecycle, immutable-Accepted enforcement) are untouched. Full rationale in ADR-0002.
• ADRs were AI-drafted and human-reviewed per the process; several were revised across review (model tiering in 0004, vendor-agnostic distribution and the naming tension in 0012).

[dirvine]

📋 Consolidated Review — PR #73

Branch: adr/relocate-and-retrospective-records
HEAD: 51724df (today, ~7h ago)
Scope: Relocate ADRs from docs/adr/ → /adr; add 13 retrospective ADRs (0002–0014) recording pre-process decisions.
CI: All 6 checks green (GitBook diff/preview, ADR governance, prose-guard, sweep-guard, sweep-sha-reachability).
Review panel: 6 agents in 2 parallel groups (mechanism × content × docs-pipeline | process × security × conventions).

---

🔴 Critical (must fix before merge)

#	Finding	Evidence
C1	ADR-0001 immutability violated — ADR-0001 states ADRs live at docs/adr/ and "Accepted ADRs are immutable: if the decision changes, a new superseding ADR must be created." ADR-0002 changes the location rule but declares Supersedes: none; ADR-0001 still shows Superseded by: none.	adr/ADR-0001-adopt-architecture-decision-records.md:31 vs adr/ADR-0002-...md:6
C2	Governance script PR-mode immutability gate silently disabled — scripts/adr-governance.py:72,101 filter on name.startswith("docs/adr/ADR-"). With ADR_DIR=Path("adr"), no changed file matches → files_to_validate empty → Accepted-immutability check (lines 99–110) never runs on PRs. Local python3 scripts/adr-governance.py passes because it falls back to full-tree scan when base=None.	scripts/adr-governance.py:72,101
C3	adr/TOOLING.md:41-42 is a user-facing lie — AI-harness prompt still says inspect docs/adr/ and docs/adr/TEMPLATE.md. Every Claude/Codex/pi agent pointed here will hunt the wrong path and silently fail.	adr/TOOLING.md:41-42

---

⚠️ Warnings (non-blocking, should address)

#	Finding	Evidence
W1	All 13 retrospective ADRs (0002–0014) omit the template's required **Reviewers:** field — only ADR-0001 has it.	adr/TEMPLATE.md:6
W2	No shared convention for "Accepted retroactively" — each ADR invents its own phrasing; ADR-0001 (the policy) doesn't define it. ADR-0002 claims to be prospective while being shipped in the same PR as the move it records — inconsistent with 0003–0014.	adr/ADR-0002:10, adr/ADR-0003..0014:Acceptance
W3	ADR-0009 (human→automation path) commits to nothing actionable — §Decision records a trajectory; §Validation says "bar is set when panel is specified." No steps, owners, milestones.	adr/ADR-0009-human-review-gate-path-to-full-automation.md:Decision,Validation
W4	ADR-0012 records autonomi-developer as canonical but ships skills/start/ on disk — naming divergence is honest and tracked in planning/skill-open-questions.md, but it's unresolved debt.	adr/ADR-0012:62,90
W5	Handover fragility — adr/README.md references TEMPLATE.md and external tools (adrs/adr-kit) but lacks: numbering continuation rule, who can Accept, how to record a retrospective, or that TOOLING.md paths now diverge from docs.	adr/README.md, adr/TOOLING.md
W6	Script lost executable bit (100755 → 100644). Functionally fine (workflow invokes python3), but unexplained.	git diff origin/main...HEAD -- scripts/adr-governance.py

---

✅ Looks Good

• GitBook isolation confirmed — .gitbook.yaml has root: ./docs/, SUMMARY.md has no ADR entries, llms.txt sweep is from docs/. ADRs cannot leak to the published developer site.
• CI path filters correct — .github/workflows/adr-governance.yml lines 6,15 updated to adr/** on both pull_request and push triggers.
• .adr-kit.yaml consistent — adr_directory: adr matches the new location.
• No stray docs/adr references in CLAUDE.md, README.md, skills/, .claude-plugin/, scripts/, prose-guard, or the 13 new ADRs.
• Sequence integrity — ADR-0001 through 0014 contiguous, no gaps, no name collisions.
• Template header order — all 14 ADRs follow TEMPLATE.md sequence (Context → Decision Drivers → Considered Options → Decision → Consequences → Positive/Negative/Neutral → Validation → Notes for AI-assisted work). ADR-0001 only omits the last section (added later to template).
• Implementation ↔ ADR traceability — each retrospective ADR (0003–0014) maps to real code/config in this repo or its sibling (skills/start/, component-registry.yml, .gitbook.yaml, sweep workflows). ADR-0005 correctly flags the personal-Claude-subscription dependency as out-of-repo.
• planning/skill-open-questions.md is action-oriented — each open item has a "To do:" line with a concrete next step; supersession mechanism is the stated resolution path (consistent with ADR practice).

---

🎯 Recommendation

Do not approve/merge until C1–C3 are fixed. The fixes are surgical:

1. C1: Add Supersedes: ADR-0001 to ADR-0002 front-matter; add Superseded by: ADR-0002 to ADR-0001.
2. C2: Fix scripts/adr-governance.py — replace hardcoded docs/adr/ADR- prefix with dynamic ADR_DIR / .adr-kit.yaml adr_directory so PR-mode validation works on the new path.
3. C3: Update adr/TOOLING.md:41-42 to point at adr/ and adr/TEMPLATE.md.

W1–W6 can be addressed in a follow-up PR or superseding ADRs — they don't break anything today but will bite future maintainers.

Happy to draft the fixes and push to this branch, or open a follow-up PR — let me know how you'd like to proceed.

---

Reviewed by Hermes Agent (6-agent consensus)

[JimCollinson]

Disposition of consolidated review

Thanks for the thorough review against 51724df. The branch now includes the correction series through 298e998. Disposition by finding:

Critical

• C1 — ADR-0001 / ADR-0002 supersession: addressed. ADR-0002 now carries Supersedes: ADR-0001 (location clause only). ADR-0001 remains byte-identical because it was already Accepted. We deliberately did not add a backlink to ADR-0001: ADR-0015 and adr/README.md now define the new ADR Supersedes field as the authoritative forward link, preserving Accepted-record immutability.
• C2 — PR-mode governance bypass: addressed. Governance now reads the configured base ADR directory, validates the root adr/ location, applies changed-file validation in PR mode, and compares every Accepted ADR on the base byte-for-byte across the relocation. The branch adds 20 integration tests covering PR, push, local merge-base, relocation, edit, rename, Acceptance metadata, and multi-commit introducing-PR behavior.
• C3 — stale tooling paths: addressed. adr/TOOLING.md and CLAUDE.md now direct agents to adr/ and adr/TEMPLATE.md.

Warnings

• W1 — reviewer metadata: addressed. Prospective ADR-0002 and ADR-0015 identify Jim Collinson as reviewer. Retrospective ADR-0003 through ADR-0014 intentionally omit fictional historical reviewers; the template now permits this explicitly.
• W2 — retrospective acceptance convention: addressed. ADR-0015 defines owner-confirmed retrospective acceptance, the default-branch immutability boundary, and forward-only supersession. README, template, tooling, Acceptance metadata, and governance checks use that shared convention. ADR-0002 remains prospective because its location decision was made and reviewed in this introducing PR.
• W3 — ADR-0009 actionability: separated by artifact role. ADR-0009 now records the durable human-gate and independent-panel future architecture. Rollout order, implementation steps, evidence windows, and thresholds live in planning/adr-implementation-conformance.md, including a dedicated panel-automation slice. The routine no longer suggests structural guard history alone can authorize auto-merge.
• W4 — skill naming divergence: tracked. autonomi-developer remains canonical; start, developer, and /developer:start are current channel packaging. The implementation debt and migration choices remain explicit in planning.
• W5 — handover fragility: addressed. adr/README.md now defines sequential numbering, prospective acceptance authority, retrospective acceptance, default-branch immutability, and forward-only supersession. Operational paths and harness guidance point to root adr/.
• W6 — executable bit: addressed. scripts/adr-governance.py is restored to mode 100755.

Additional review work

The branch also separates durable ADR decisions from mutable mechanics in ADR-0006 and ADR-0014, preserves ADR-0009 panel intent, records implementation gaps outside immutable ADRs, and keeps exact workflow and maintenance procedures in the routine, guard workflows, registries, and skills/start/MAINTAINING.md.

Local pre-push evidence on 298e998: 20 tests passed; governance passed in ordinary, PR, and push modes with 15 ADRs checked; Python compilation and git diff --check passed. GitHub CI on exact SHA 298e998 is now the green of record pending completion.

[dirvine]

✅ Approval — PR #73

Reviewed at: ff391657 (post-merge of main, +110/-77 over 298e998 — pure doc-sweep refresh + planning/sweeps/2026-07-21.md + minor SKILL.md/version.json bumps. No changes to ADR machinery, governance script, or any review concerns.)

Re-validation against new head:

Check	Result
python3 scripts/adr-governance.py	✅ Pass — 15/15 ADRs
python3 -m unittest scripts.tests.test_adr_governance -v	✅ 20/20 tests pass (4.96s)
All 6 GitHub CI checks	✅ Pass

---

Summary

The branch addresses all 3 critical + 6 warning findings from the original review (51724df) and adds substantial hardening:

• C1 ADR-0001 immutability honoured (no backlink; byte-identical); ADR-0002 carries Supersedes: ADR-0001 (location clause only); ADR-0015 codifies the forward-only supersession convention.
• C2 scripts/adr-governance.py rewritten — Path("adr") filter replaces docs/adr/ADR- hardcode; byte-for-byte relocation check for Accepted ADRs; .adr-kit.yaml validated; 20 integration tests covering PR/push/merge-base/relocation/edit/rename/Acceptance/multi-commit.
• C3 adr/TOOLING.md and CLAUDE.md both reference adr/ and adr/TEMPLATE.md.
• W1 Prospective ADRs (0002, 0015) carry Reviewers: Jim Collinson; retros intentionally omit per template allowance.
• W2 Acceptance: Retrospective — <basis> convention codified in ADR-0015 + enforced by governance + template.
• W3 ADR-0009 split — durable decision in ADR; rollout order, evidence windows, thresholds, panel-automation slice all in planning/adr-implementation-conformance.md.
• W4 Skill-naming debt (skills/start/ vs autonomi-developer) tracked in planning/skill-open-questions.md; ADR-0012 cross-references for supersession path.
• W5 adr/README.md defines sequential numbering, prospective acceptance authority, retrospective acceptance, default-branch immutability, forward-only supersession.
• W6 scripts/adr-governance.py mode preserved at 100755.

Process notes (non-blocking)

• Forward-only supersession means discoverability relies on convention + tooling rather than backlinks on the older record. Acceptable; README documents it.
• ADR-0015 codifies a rule whose first applications predate it (ADR-0007/0009/0012/0014). All five are owner-confirmed; coherent.

Verdict

Merge-ready. Strong review-team consensus — 6-agent re-verification confirmed no regressions and clean CI on the current head.

---

Approved by Hermes Agent (6-agent consensus, head-verified)