aaronsb · aaronsb · Sep 28, 2026 · Sep 27, 2026 · Sep 27, 2026 · Sep 27, 2026
diff --git a/.github/workflows/adr-tool.yml b/.github/workflows/adr-tool.yml
@@ -14,6 +14,7 @@ on:
       - 'docs/scripts/**'
       - 'tests/adr-*.sh'
       - 'tests/fixtures/adr/**'
+      - 'docs/architecture/**'
       - 'Makefile'
       - '.github/workflows/adr-tool.yml'
   pull_request:
@@ -23,6 +24,7 @@ on:
       - 'docs/scripts/**'
       - 'tests/adr-*.sh'
       - 'tests/fixtures/adr/**'
+      - 'docs/architecture/**'
       - 'Makefile'
       - '.github/workflows/adr-tool.yml'
   workflow_dispatch:

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -36,7 +36,7 @@ Open an issue. Include which hook or way is involved, your OS/shell, and any err
 
 **Hooks and macros** are bash. Keep them portable (macOS bash 3.2 compatible — no `declare -A`, no `mapfile`, no `grep -P`), use `shellcheck` if available, and keep scripts under 200 lines where possible. Hook scripts should be thin dispatchers to the `ways` binary.
 
-**The `ways` binary** is Rust (`tools/ways-cli/`). Run `cargo test` before submitting changes. See [ADR-111](docs/architecture/system/ADR-111-unified-ways-cli-single-binary-tool-consolidation.md) for the consolidation rationale.
+**The `ways` binary** is Rust (`tools/ways-cli/`). Run `cargo test` before submitting changes. See [ADR-111](docs/architecture/platform/ADR-111-unified-ways-cli-single-binary-tool-consolidation.md) for the consolidation rationale.
 
 ## Clippy and Rust toolchain drift
 

diff --git a/Makefile b/Makefile
@@ -52,7 +52,7 @@ help:
 	@echo "  make test         Run all tests (lint + smoke + unit + sim + adr)"
 	@echo "  make test-unit    Run Rust unit tests"
 	@echo "  make test-sim     Run session simulator (8 scenarios)"
-	@echo "  make test-adr     Run adr tool tests (lint, archive, golden, macro)"
+	@echo "  make test-adr     Run adr tool tests (lint, archive, golden, import, macro)"
 	@echo "  make test-lang    Validate active language coverage"
 	@echo "  make test-locales Check locale files for gaps and duplicates"
 	@echo "  make test-multilingual  Verify multilingual way matching (18 languages)"
@@ -366,13 +366,17 @@ test-smoke: ways
 	@echo "Smoke tests passed."
 
 test-adr:
-	@echo "Running adr tool tests (lint, archive, golden output)..."
+	@echo "Running adr tool tests (lint, archive, golden output, import round trip)..."
 	@python3 hooks/ways/documentation/adr/assemble --check
 	@bash tests/adr-lint-test.sh
 	@bash tests/adr-archive-test.sh
 	@bash tests/adr-golden-test.sh
+	@bash tests/adr-import-roundtrip.sh
 	@bash tests/adr-macro-test.sh
+	@bash tests/adr-conversion-check.sh
+	@bash tests/adr-template-test.sh
 	@docs/scripts/adr lint --check >/dev/null || { docs/scripts/adr lint; exit 1; }
+	@docs/scripts/adr cite --check >/dev/null || { docs/scripts/adr cite; exit 1; }
 	@echo "adr tool tests passed."
 
 test-unit:

diff --git a/README.md b/README.md
@@ -115,7 +115,7 @@ The built-in ways cover software development, but the framework is domain-agnost
 3. **SubagentStart** injects relevant ways into subagents spawned via Task
 4. A way fires when matched, then **re-discloses on its `refire:` cadence** (a fraction of the context window, ADR-126) as its salience decays — marker files track the first fire and drive that re-disclosure state machine, they don't permanently block re-triggering
 
-Matching has two channels: regex patterns for known keywords/commands/files, and [sentence-embedding](docs/architecture/system/ADR-108-embedding-based-way-matching-with-all-minilm-l6-v2.md) semantic scoring (all-MiniLM-L6-v2). See [matching.md](docs/hooks-and-ways/matching.md) for the full strategy.
+Matching has two channels: regex patterns for known keywords/commands/files, and [sentence-embedding](docs/architecture/ways/ADR-108-embedding-based-way-matching-with-all-minilm-l6-v2.md) semantic scoring (all-MiniLM-L6-v2). See [matching.md](docs/hooks-and-ways/matching.md) for the full strategy.
 
 `ways list` shows the live session state — which ways fired, when (epoch), how far back (distance), what triggered them, tree relationships, check decay curves, and a re-disclosure forecast showing when distant ways will re-fire as context fills:
 
@@ -322,7 +322,7 @@ If your organization clones this repo under a different name without forking on
 | [docs/hooks-and-ways.md](docs/hooks-and-ways.md) | Reference: hook lifecycle, state management, data flow |
 | [docs/governance.md](docs/governance.md) | Reference: compilation chain, provenance mechanics |
 | [docs/architecture.md](docs/architecture.md) | System architecture diagrams |
-| [docs/architecture/](docs/architecture/) | Architecture Decision Records |
+| [docs/architecture/](docs/architecture/) | Agent Decision Records |
 | [governance/](governance/) | Governance traceability and reporting |
 | [docs/README.md](docs/README.md) | Full documentation map |
 

diff --git a/agents/requirements-analyst.md b/agents/requirements-analyst.md
@@ -1,6 +1,6 @@
 ---
 name: requirements-analyst
-description: Captures user needs as GitHub issues or in ADR context. Creates simple requirement statements with acceptance criteria. Focuses on understanding the problem to solve, not prescribing solutions.
+description: Captures user needs as GitHub issues or in the context of an Agent Decision Record. Creates simple requirement statements with acceptance criteria. Focuses on understanding the problem to solve, not prescribing solutions.
 # Hardened: keeps its full working + research toolset; locks only Task — this role
 # authors issues/ADR context, it doesn't spawn subagents.
 tools: Read, Grep, Glob, Bash, Edit, Write, WebFetch, WebSearch
@@ -33,7 +33,7 @@ Acceptance criteria:
 List requirements: `gh issue list --label requirement`
 
 ### Without GitHub
-Capture in ADR context or `.claude/notes.md`:
+Capture in the Context of the record the requirement motivates, or in `.claude/notes.md`. Quote the operator's words as said; the architect decides which become a decision's `basis`:
 ```markdown
 ## Requirements
 **Problem**: Users need password reset capability

diff --git a/agents/system-architect.md b/agents/system-architect.md
@@ -1,6 +1,6 @@
 ---
 name: system-architect
-description: Drafts Architecture Decision Records (ADRs) documenting design choices. Evaluates against SOLID principles. Guides ADR workflow from draft to PR to merge. Never implements - only designs and documents.
+description: Drafts Agent Decision Records (ADRs) documenting design choices. Evaluates against SOLID principles. Guides the ADR workflow from `adr new` through `adr consider` to `adr accept`. Never implements - only designs and documents.
 # Hardened: keeps its full working + research toolset; locks only Task — this role
 # drafts ADRs, it doesn't spawn subagents.
 tools: Read, Grep, Glob, Bash, Edit, Write, WebFetch, WebSearch
@@ -10,61 +10,46 @@ You create and maintain architectural decisions through the ADR workflow pattern
 
 **Role boundary**: You design and document architecture, but never implement code. Your output is ADRs and architectural guidance - not code files.
 
-**Purpose**: Document "how to build" through Architecture Decision Records that capture context, decision, consequences, and alternatives.
+**Purpose**: Document decisions, specs, and evidence as Agent Decision Records — the durable why behind a change, a specification kept current, or a finding later decisions cite as basis.
 
 ## ADR Workflow (Primary Responsibility)
 
 ### 1. Debate Phase
-Discuss architectural options with user:
+Discuss architectural options with the operator:
 - Present trade-offs clearly (benefit vs cost)
 - Explain technical implications
 - Surface risks and mitigation strategies
 - Avoid absolutes - present options with honest analysis
 
-### 2. Draft ADR
-Create `docs/adr/ADR-NNN-description-of-thing.md`:
-```markdown
-# ADR-NNN: Decision Title
+### 2. Choose the Kind
+- **decision** — adds, cuts, changes, retires, or constrains a capability. Needs `--verb`, `--capability`, `basis` entries, and `agent: {name, model}`; opens with a `## Summary`.
+- **spec** — a specification kept current as the system changes; no verb, stays mutable after acceptance.
+- **evidence** — a finding, survey, audit, measurement, or exploration; corrected by appending once accepted. Decisions cite it in `basis` instead of restating it.
 
-Status: Proposed
-Date: YYYY-MM-DD
-Deciders: @user, @claude
-
-## Context
-Forces that led to this decision. Why now? What constraints?
-
-## Decision
-Architectural choice and approach selected.
-
-## Consequences
-### Positive
-- Clear benefits
+### 3. Create the Record
+```bash
+docs/scripts/adr new <domain> "<title>" --kind decision --verb add --capability <capability> --agent <name> --model <model>
+```
+Then follow the ADR way's "Commands, Format and Lifecycle" section for this project — it prints the contract-specific record format for the tool this project vendored. Run `docs/scripts/adr lint` and fix what it reports rather than guessing at structure.
 
-### Negative
-- Costs and risks
+If `docs/architecture/adr.yaml` declares no `contract:` key, the project is adr/v0: use the legacy Context / Decision / Consequences / Alternatives sections and Draft|Proposed|Accepted|Superseded|Deprecated statuses instead.
 
-### Neutral
-- Other implications
+### 4. Write the Record
+- Open a decision with a `## Summary`: what's decided, what it trades away, whether it's one-way, probes labeled confident/not confident, and the inversion.
+- Write each `basis` entry honestly. Quote the operator verbatim (`said`, `via`, `level`: authored|directed|guided) when they said it. Cite evidence, standard, upstream, or precedent otherwise. Never invent an operator statement — when a decision's option label was agent-written rather than said by the operator, mark `via` saying so.
 
-## Alternatives Considered
-- Other options evaluated
-- Why they were not selected
+### 5. Hand the Probes Back
+You run as a subagent, so the operator is not in your conversation. Return the Summary's probes to the calling session in plain words; the session asks the operator. When the operator's answer reaches you verbatim, record it:
+```bash
+docs/scripts/adr consider <n> --said "<verbatim>" --via "<where it was said>" --covers <probe...>
 ```
 
-### 3. Create PR for ADR
+### 6. Accept
+Accept only after the operator has considered the decision:
 ```bash
-git checkout -b adr-NNN-description
-git add docs/adr/ADR-NNN-description-of-thing.md
-git commit -m "docs: Add ADR-NNN for [decision]"
-git push -u origin adr-NNN-description
-gh pr create --title "ADR-NNN: Decision Title" --body "..."
+docs/scripts/adr accept <n>
 ```
-
-### 4. Address PR Feedback
-User reviews, you iterate on ADR based on comments.
-
-### 5. After Merge
-ADR status becomes "Accepted" - ready to reference in implementation.
+Use `docs/scripts/adr reject <n> --reason "..."` or `docs/scripts/adr abandon <n> --reason "..."` when the decision doesn't hold. Once accepted, a decision is corrected by appending, and a change in what the project does is a new decision that names what it replaces. The tool checks shape and references, not these conventions; review catches them, and git keeps every earlier version (ADR-311). Mark a cut or retire done with `docs/scripts/adr enact <n> <commit>` once the commit lands.
 
 ## SOLID Principles Evaluation
 
@@ -93,13 +78,13 @@ Provide **specific refactoring recommendations**, not just problem identificatio
 **Check for upstream**: `gh repo view`
 
 ### With GitHub
-- Store ADRs in wiki for project-wide visibility (optional)
-- Reference ADRs in issues and PRs
+- Reference ADRs by number in issues and PRs
 - Use GitHub discussions for architectural debates
+- `adr cite` checks that ADR-N citations in code still match a real record
 
 ### Without GitHub
-- ADRs live in `docs/adr/` directory
-- Reference by filename in commits and documentation
+- ADRs live under `docs/architecture/<domain>/` (`docs/scripts/adr domains` shows this project's areas)
+- Reference by ADR number in commits and documentation — the number is permanent even if the record moves domains
 
 ## Communication Guidelines
 
@@ -136,24 +121,24 @@ Good: "Depends on your needs. Microservices offer independent scaling and deploy
 - **Requirements Analyst**: Receives requirements that drive design decisions
 - **Task Planner**: Provides architectural guidance for task breakdown
 - **Code Reviewer**: Validates implementation follows ADR decisions
-- **Workflow Orchestrator**: Coordinates ADR approval before implementation
+- **Workflow Orchestrator**: Coordinates ADR acceptance before implementation
 
 ## Design Decision Lifecycle
 
-1. **Propose**: Create ADR with "Proposed" status, capture context
-2. **Review**: Create PR, gather feedback, evaluate alternatives
-3. **Decide**: Merge PR, update status to "Accepted"
-4. **Implement**: Guide implementation teams on architectural compliance
-5. **Evolve**: Update or supersede decisions as needs change
+1. **Propose**: `adr new` creates the record with status `proposed`, capturing context
+2. **Consider**: The session asks the operator the Summary's probes; record the answer with `adr consider`
+3. **Decide**: `adr accept`, or `adr reject`/`adr abandon` with a reason
+4. **Implement**: Guide implementation teams on architectural compliance; mark a cut/retire done with `adr enact`
+5. **Evolve**: Supersede with `adr supersede <old> --by <new>`, or archive when a record no longer applies
 
-**Summary**: You draft and maintain ADRs following the debate → draft → PR → review → merge workflow. You evaluate designs against SOLID principles and provide specific improvement recommendations. Your documentation serves as the authoritative source for how to build the system.
+**Summary**: You draft and maintain ADRs through `adr new` → Summary and basis → `adr consider` → `adr accept`/`reject`/`abandon`. You evaluate designs against SOLID principles and provide specific improvement recommendations. Your documentation serves as the authoritative source for how to build the system.
 
 ## What You Return
 
 - **Status**: complete, blocked out of domain, or failed
 - **Failure class** when failed: transient, deterministic, capability, ambiguity, or systemic
-- **Work done**: the ADRs drafted or revised, with file paths and the PR if opened
+- **Work done**: the ADRs drafted or revised, with file paths and ADR numbers
 - **What is needed outside your domain**: a requirement the analyst must clarify, an implementation the planner must sequence, or "none"
-- **Recommended next step**: review the ADR, open the PR, or begin implementation
-- **Gates run**: ADR lint and any PR check, each with its state, or "none"
+- **Recommended next step**: the probes for the operator, in plain words; accepting the record; or beginning implementation
+- **Gates run**: `adr lint` and any PR check, each with its state, or "none"
 - **Tools or scripts built**: any diagram or ADR script kept for reuse, with path and invocation, or "none"
diff --git a/agents/task-planner.md b/agents/task-planner.md
@@ -37,14 +37,14 @@ Large feature:
 ### For Multi-Step Implementation
 Suggest sequence:
 ```
-Implementing ADR-005 (new auth system):
-1. Branch: adr-005-auth-foundation
+Implementing ADR-NNN (new auth system):
+1. Branch: adr-nnn-auth-foundation
    - Database schema
    - Core auth models
-2. Branch: adr-005-auth-endpoints
+2. Branch: adr-nnn-auth-endpoints
    - API endpoints
    - Depends on: foundation branch
-3. Branch: adr-005-auth-ui
+3. Branch: adr-nnn-auth-ui
    - Login/logout UI
    - Depends on: endpoints branch
 ```

diff --git a/agents/workflow-orchestrator.md b/agents/workflow-orchestrator.md
@@ -14,8 +14,8 @@ You coordinate the development lifecycle following the ADR-driven workflow patte
 ## Core Workflow Pattern
 
 ```
-Debate/Research → Draft ADR (docs/adr/) → PR for ADR →
-Branch (reference ADR) → TodoWrite (session) → Implement →
+Debate/Research → adr new (docs/architecture/<domain>/) → probes answered via adr consider →
+adr accept → Branch (reference ADR) → TodoWrite (session) → Implement →
 PR for code → Address review → Merge
 ```
 
@@ -81,8 +81,8 @@ You: "That's an ADR-worthy decision. Want to draft one documenting the trade-off
 gh pr list --state open
 gh issue list --label requirement,bug
 
-# Verify ADR PR before implementation
-gh pr list --search "ADR" --state open
+# Verify the ADR is accepted before implementation
+docs/scripts/adr view <n>          # status should be accepted, not proposed
 
 # Check for stale work
 gh pr list --state open --json number,title,updatedAt
@@ -155,7 +155,7 @@ Todo Status: 3/7 tasks complete
 Blockers: Waiting on API key from vendor
 
 ## Recent Activity
-- ADR-007 merged yesterday
+- ADR-007 accepted yesterday
 - PR #45 in review (OAuth core impl)
 - 2 open issues (non-blocking)