From 8823d96bfe9ecd3f235f768f839c7d736c9878e4 Mon Sep 17 00:00:00 2001 From: bgagent Date: Fri, 29 May 2026 19:58:52 +0000 Subject: [PATCH] docs(decisions): rename ADR files to ADR-NNN-slug.md format Rename all 13 ADR files in docs/decisions/ from NNN-slug.md to ADR-NNN-slug.md format per issue #161. Update all cross-references in ADR files, AGENTS.md, and .abca/commands/review_pr.md. Update README.md numbering section to show the new naming pattern. Regenerate Starlight mirrors via docs sync script. Co-Authored-By: Claude Sonnet 4.6 Task-Id: 01KSTMWJY42A83G6XTA33EY6B1 Prompt-Version: 1c9c10e027a2 --- .abca/commands/review_pr.md | 2 +- AGENTS.md | 2 +- ...cked-pull-requests.md => ADR-001-stacked-pull-requests.md} | 0 ...icies.md => ADR-002-least-privilege-bootstrap-policies.md} | 2 +- ...ution-governance.md => ADR-003-contribution-governance.md} | 0 ...-documentation.md => ADR-004-tabula-rasa-documentation.md} | 0 .../{005-feedback-loop.md => ADR-005-feedback-loop.md} | 0 .../{006-feature-flags.md => ADR-006-feature-flags.md} | 0 ...wledge-acquisition.md => ADR-007-knowledge-acquisition.md} | 0 ...08-definition-of-done.md => ADR-008-definition-of-done.md} | 0 ...e-dev-agents.md => ADR-009-security-posture-dev-agents.md} | 0 .../{010-error-recovery.md => ADR-010-error-recovery.md} | 0 ...-conflict-resolution.md => ADR-011-conflict-resolution.md} | 0 ...wledge-stack.md => ADR-012-operational-knowledge-stack.md} | 2 +- ...dation-pyramid.md => ADR-013-tiered-validation-pyramid.md} | 0 docs/decisions/README.md | 2 +- ...cked-pull-requests.md => Adr-001-stacked-pull-requests.md} | 2 +- ...icies.md => Adr-002-least-privilege-bootstrap-policies.md} | 4 ++-- ...ution-governance.md => Adr-003-contribution-governance.md} | 2 +- ...-documentation.md => Adr-004-tabula-rasa-documentation.md} | 2 +- .../{005-feedback-loop.md => Adr-005-feedback-loop.md} | 2 +- .../{006-feature-flags.md => Adr-006-feature-flags.md} | 2 +- ...wledge-acquisition.md => Adr-007-knowledge-acquisition.md} | 2 +- ...08-definition-of-done.md => Adr-008-definition-of-done.md} | 2 +- ...e-dev-agents.md => Adr-009-security-posture-dev-agents.md} | 2 +- .../{010-error-recovery.md => Adr-010-error-recovery.md} | 2 +- ...-conflict-resolution.md => Adr-011-conflict-resolution.md} | 2 +- ...wledge-stack.md => Adr-012-operational-knowledge-stack.md} | 4 ++-- ...dation-pyramid.md => Adr-013-tiered-validation-pyramid.md} | 2 +- docs/src/content/docs/decisions/Readme.md | 2 +- 30 files changed, 21 insertions(+), 21 deletions(-) rename docs/decisions/{001-stacked-pull-requests.md => ADR-001-stacked-pull-requests.md} (100%) rename docs/decisions/{002-least-privilege-bootstrap-policies.md => ADR-002-least-privilege-bootstrap-policies.md} (98%) rename docs/decisions/{003-contribution-governance.md => ADR-003-contribution-governance.md} (100%) rename docs/decisions/{004-tabula-rasa-documentation.md => ADR-004-tabula-rasa-documentation.md} (100%) rename docs/decisions/{005-feedback-loop.md => ADR-005-feedback-loop.md} (100%) rename docs/decisions/{006-feature-flags.md => ADR-006-feature-flags.md} (100%) rename docs/decisions/{007-knowledge-acquisition.md => ADR-007-knowledge-acquisition.md} (100%) rename docs/decisions/{008-definition-of-done.md => ADR-008-definition-of-done.md} (100%) rename docs/decisions/{009-security-posture-dev-agents.md => ADR-009-security-posture-dev-agents.md} (100%) rename docs/decisions/{010-error-recovery.md => ADR-010-error-recovery.md} (100%) rename docs/decisions/{011-conflict-resolution.md => ADR-011-conflict-resolution.md} (100%) rename docs/decisions/{012-operational-knowledge-stack.md => ADR-012-operational-knowledge-stack.md} (99%) rename docs/decisions/{013-tiered-validation-pyramid.md => ADR-013-tiered-validation-pyramid.md} (100%) rename docs/src/content/docs/decisions/{001-stacked-pull-requests.md => Adr-001-stacked-pull-requests.md} (99%) rename docs/src/content/docs/decisions/{002-least-privilege-bootstrap-policies.md => Adr-002-least-privilege-bootstrap-policies.md} (97%) rename docs/src/content/docs/decisions/{003-contribution-governance.md => Adr-003-contribution-governance.md} (99%) rename docs/src/content/docs/decisions/{004-tabula-rasa-documentation.md => Adr-004-tabula-rasa-documentation.md} (98%) rename docs/src/content/docs/decisions/{005-feedback-loop.md => Adr-005-feedback-loop.md} (99%) rename docs/src/content/docs/decisions/{006-feature-flags.md => Adr-006-feature-flags.md} (99%) rename docs/src/content/docs/decisions/{007-knowledge-acquisition.md => Adr-007-knowledge-acquisition.md} (98%) rename docs/src/content/docs/decisions/{008-definition-of-done.md => Adr-008-definition-of-done.md} (98%) rename docs/src/content/docs/decisions/{009-security-posture-dev-agents.md => Adr-009-security-posture-dev-agents.md} (98%) rename docs/src/content/docs/decisions/{010-error-recovery.md => Adr-010-error-recovery.md} (98%) rename docs/src/content/docs/decisions/{011-conflict-resolution.md => Adr-011-conflict-resolution.md} (98%) rename docs/src/content/docs/decisions/{012-operational-knowledge-stack.md => Adr-012-operational-knowledge-stack.md} (99%) rename docs/src/content/docs/decisions/{013-tiered-validation-pyramid.md => Adr-013-tiered-validation-pyramid.md} (99%) diff --git a/.abca/commands/review_pr.md b/.abca/commands/review_pr.md index be566c9c..fb56972d 100644 --- a/.abca/commands/review_pr.md +++ b/.abca/commands/review_pr.md @@ -20,7 +20,7 @@ the control plane reliable, bounded, and improvable. 1. Read the PR title and description carefully — does it explain *why*, not just *what*? 2. Identify and read linked issues with `gh issue view `. Confirm the issue carries the `approved` label and that the work matches the stated acceptance criteria (see - [ADR-003 contribution governance](../../docs/decisions/003-contribution-governance.md)). + [ADR-003 contribution governance](../../docs/decisions/ADR-003-contribution-governance.md)). 3. Confirm the branch name follows `(feat|fix|chore|docs)/-short-description`. A branch without an issue reference is unauthorized work — flag it. 4. Review the commit history (`gh pr view --json commits` / `git log`) to understand the diff --git a/AGENTS.md b/AGENTS.md index 02296af0..a328e248 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -39,7 +39,7 @@ Handler entry tests: `cdk/test/handlers/orchestrate-task.test.ts`, `create-task. ### Common mistakes -- **Starting implementation without an approved GitHub issue** — Conversational approval ("yes, do it", "go ahead", "start with X") is NOT governance approval. The correct sequence is: create a GitHub issue with acceptance criteria → get the `approved` label from an admin → self-assign → comment "Starting implementation" → then begin work. Even if the user explicitly directs the work in conversation, create the durable artifact (issue) first. See [ADR-003](./docs/decisions/003-contribution-governance.md). +- **Starting implementation without an approved GitHub issue** — Conversational approval ("yes, do it", "go ahead", "start with X") is NOT governance approval. The correct sequence is: create a GitHub issue with acceptance criteria → get the `approved` label from an admin → self-assign → comment "Starting implementation" → then begin work. Even if the user explicitly directs the work in conversation, create the durable artifact (issue) first. See [ADR-003](./docs/decisions/ADR-003-contribution-governance.md). - **Creating branches without an issue reference** — Branch names must follow the pattern `(feat|fix|chore|docs)/-short-description`. A branch without an issue number is unauthorized work. Example: `feat/148-operational-knowledge-stack`. - Editing **`docs/src/content/docs/`** instead of **`docs/guides/`** or **`docs/design/`** — content is generated; sync from sources. - Adding or editing files in **`docs/design/`** or **`docs/guides/`** without running **`cd docs && node scripts/sync-starlight.mjs`** — CI will reject ("Fail build on mutation") because the Starlight mirror files in `docs/src/content/docs/` are stale. Always commit the regenerated mirrors alongside source changes. diff --git a/docs/decisions/001-stacked-pull-requests.md b/docs/decisions/ADR-001-stacked-pull-requests.md similarity index 100% rename from docs/decisions/001-stacked-pull-requests.md rename to docs/decisions/ADR-001-stacked-pull-requests.md diff --git a/docs/decisions/002-least-privilege-bootstrap-policies.md b/docs/decisions/ADR-002-least-privilege-bootstrap-policies.md similarity index 98% rename from docs/decisions/002-least-privilege-bootstrap-policies.md rename to docs/decisions/ADR-002-least-privilege-bootstrap-policies.md index a56238cc..8c9272c8 100644 --- a/docs/decisions/002-least-privilege-bootstrap-policies.md +++ b/docs/decisions/ADR-002-least-privilege-bootstrap-policies.md @@ -64,7 +64,7 @@ The implementation is decomposed into 8 sub-issues, each independently reviewabl ## References -- [ADR-001](./001-stacked-pull-requests.md) — delivery methodology (stacked PRs) +- [ADR-001](./ADR-001-stacked-pull-requests.md) — delivery methodology (stacked PRs) - RFC #120 — parent issue with full design and sub-issue breakdown - `docs/design/DEPLOYMENT_ROLES.md` — current documentation (will become generated) - PR #46 — original policy derivation and validation methodology diff --git a/docs/decisions/003-contribution-governance.md b/docs/decisions/ADR-003-contribution-governance.md similarity index 100% rename from docs/decisions/003-contribution-governance.md rename to docs/decisions/ADR-003-contribution-governance.md diff --git a/docs/decisions/004-tabula-rasa-documentation.md b/docs/decisions/ADR-004-tabula-rasa-documentation.md similarity index 100% rename from docs/decisions/004-tabula-rasa-documentation.md rename to docs/decisions/ADR-004-tabula-rasa-documentation.md diff --git a/docs/decisions/005-feedback-loop.md b/docs/decisions/ADR-005-feedback-loop.md similarity index 100% rename from docs/decisions/005-feedback-loop.md rename to docs/decisions/ADR-005-feedback-loop.md diff --git a/docs/decisions/006-feature-flags.md b/docs/decisions/ADR-006-feature-flags.md similarity index 100% rename from docs/decisions/006-feature-flags.md rename to docs/decisions/ADR-006-feature-flags.md diff --git a/docs/decisions/007-knowledge-acquisition.md b/docs/decisions/ADR-007-knowledge-acquisition.md similarity index 100% rename from docs/decisions/007-knowledge-acquisition.md rename to docs/decisions/ADR-007-knowledge-acquisition.md diff --git a/docs/decisions/008-definition-of-done.md b/docs/decisions/ADR-008-definition-of-done.md similarity index 100% rename from docs/decisions/008-definition-of-done.md rename to docs/decisions/ADR-008-definition-of-done.md diff --git a/docs/decisions/009-security-posture-dev-agents.md b/docs/decisions/ADR-009-security-posture-dev-agents.md similarity index 100% rename from docs/decisions/009-security-posture-dev-agents.md rename to docs/decisions/ADR-009-security-posture-dev-agents.md diff --git a/docs/decisions/010-error-recovery.md b/docs/decisions/ADR-010-error-recovery.md similarity index 100% rename from docs/decisions/010-error-recovery.md rename to docs/decisions/ADR-010-error-recovery.md diff --git a/docs/decisions/011-conflict-resolution.md b/docs/decisions/ADR-011-conflict-resolution.md similarity index 100% rename from docs/decisions/011-conflict-resolution.md rename to docs/decisions/ADR-011-conflict-resolution.md diff --git a/docs/decisions/012-operational-knowledge-stack.md b/docs/decisions/ADR-012-operational-knowledge-stack.md similarity index 99% rename from docs/decisions/012-operational-knowledge-stack.md rename to docs/decisions/ADR-012-operational-knowledge-stack.md index 273b6e3e..339e242a 100644 --- a/docs/decisions/012-operational-knowledge-stack.md +++ b/docs/decisions/ADR-012-operational-knowledge-stack.md @@ -151,7 +151,7 @@ Organized by persona: ```markdown # Contributor Workflow -> Operationalizes [ADR-003](../decisions/003-contribution-governance.md) +> Operationalizes [ADR-003](../decisions/ADR-003-contribution-governance.md) ## For Planners - Issue quality bar (what makes an issue "ready") diff --git a/docs/decisions/013-tiered-validation-pyramid.md b/docs/decisions/ADR-013-tiered-validation-pyramid.md similarity index 100% rename from docs/decisions/013-tiered-validation-pyramid.md rename to docs/decisions/ADR-013-tiered-validation-pyramid.md diff --git a/docs/decisions/README.md b/docs/decisions/README.md index 05983c2f..930c6bb9 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -45,7 +45,7 @@ What follows from this decision: ## Numbering -ADRs are numbered sequentially with zero-padded three-digit prefixes: `001-slug.md`, `002-slug.md`, etc. Numbers are never reused. +ADRs are numbered sequentially with zero-padded three-digit prefixes: `ADR-001-slug.md`, `ADR-002-slug.md`, etc. Numbers are never reused. ## Lifecycle diff --git a/docs/src/content/docs/decisions/001-stacked-pull-requests.md b/docs/src/content/docs/decisions/Adr-001-stacked-pull-requests.md similarity index 99% rename from docs/src/content/docs/decisions/001-stacked-pull-requests.md rename to docs/src/content/docs/decisions/Adr-001-stacked-pull-requests.md index 8f62aad2..77062c04 100644 --- a/docs/src/content/docs/decisions/001-stacked-pull-requests.md +++ b/docs/src/content/docs/decisions/Adr-001-stacked-pull-requests.md @@ -1,5 +1,5 @@ --- -title: 001 stacked pull requests +title: Adr 001 stacked pull requests --- # ADR-001: Stacked pull requests for multi-PR features diff --git a/docs/src/content/docs/decisions/002-least-privilege-bootstrap-policies.md b/docs/src/content/docs/decisions/Adr-002-least-privilege-bootstrap-policies.md similarity index 97% rename from docs/src/content/docs/decisions/002-least-privilege-bootstrap-policies.md rename to docs/src/content/docs/decisions/Adr-002-least-privilege-bootstrap-policies.md index 2dbd1651..f4dd80b3 100644 --- a/docs/src/content/docs/decisions/002-least-privilege-bootstrap-policies.md +++ b/docs/src/content/docs/decisions/Adr-002-least-privilege-bootstrap-policies.md @@ -1,5 +1,5 @@ --- -title: 002 least privilege bootstrap policies +title: Adr 002 least privilege bootstrap policies --- # ADR-002: Least-privilege CDK bootstrap policies as code @@ -68,7 +68,7 @@ The implementation is decomposed into 8 sub-issues, each independently reviewabl ## References -- [ADR-001](/architecture/001-stacked-pull-requests) — delivery methodology (stacked PRs) +- [ADR-001](/architecture/adr-001-stacked-pull-requests) — delivery methodology (stacked PRs) - RFC #120 — parent issue with full design and sub-issue breakdown - `docs/design/DEPLOYMENT_ROLES.md` — current documentation (will become generated) - PR #46 — original policy derivation and validation methodology diff --git a/docs/src/content/docs/decisions/003-contribution-governance.md b/docs/src/content/docs/decisions/Adr-003-contribution-governance.md similarity index 99% rename from docs/src/content/docs/decisions/003-contribution-governance.md rename to docs/src/content/docs/decisions/Adr-003-contribution-governance.md index 5453488e..1521f8be 100644 --- a/docs/src/content/docs/decisions/003-contribution-governance.md +++ b/docs/src/content/docs/decisions/Adr-003-contribution-governance.md @@ -1,5 +1,5 @@ --- -title: 003 contribution governance +title: Adr 003 contribution governance --- # ADR-003: Contribution governance for async agents and humans diff --git a/docs/src/content/docs/decisions/004-tabula-rasa-documentation.md b/docs/src/content/docs/decisions/Adr-004-tabula-rasa-documentation.md similarity index 98% rename from docs/src/content/docs/decisions/004-tabula-rasa-documentation.md rename to docs/src/content/docs/decisions/Adr-004-tabula-rasa-documentation.md index d125ab3b..41699251 100644 --- a/docs/src/content/docs/decisions/004-tabula-rasa-documentation.md +++ b/docs/src/content/docs/decisions/Adr-004-tabula-rasa-documentation.md @@ -1,5 +1,5 @@ --- -title: 004 tabula rasa documentation +title: Adr 004 tabula rasa documentation --- # ADR-004: Tabula rasa documentation standard diff --git a/docs/src/content/docs/decisions/005-feedback-loop.md b/docs/src/content/docs/decisions/Adr-005-feedback-loop.md similarity index 99% rename from docs/src/content/docs/decisions/005-feedback-loop.md rename to docs/src/content/docs/decisions/Adr-005-feedback-loop.md index 174713f4..9a10beae 100644 --- a/docs/src/content/docs/decisions/005-feedback-loop.md +++ b/docs/src/content/docs/decisions/Adr-005-feedback-loop.md @@ -1,5 +1,5 @@ --- -title: 005 feedback loop +title: Adr 005 feedback loop --- # ADR-005: Feedback loop — PR reviews propagate to issues and ADRs diff --git a/docs/src/content/docs/decisions/006-feature-flags.md b/docs/src/content/docs/decisions/Adr-006-feature-flags.md similarity index 99% rename from docs/src/content/docs/decisions/006-feature-flags.md rename to docs/src/content/docs/decisions/Adr-006-feature-flags.md index da778eb1..2881af33 100644 --- a/docs/src/content/docs/decisions/006-feature-flags.md +++ b/docs/src/content/docs/decisions/Adr-006-feature-flags.md @@ -1,5 +1,5 @@ --- -title: 006 feature flags +title: Adr 006 feature flags --- # ADR-006: Feature flags for concurrent development diff --git a/docs/src/content/docs/decisions/007-knowledge-acquisition.md b/docs/src/content/docs/decisions/Adr-007-knowledge-acquisition.md similarity index 98% rename from docs/src/content/docs/decisions/007-knowledge-acquisition.md rename to docs/src/content/docs/decisions/Adr-007-knowledge-acquisition.md index b137b2c6..92187986 100644 --- a/docs/src/content/docs/decisions/007-knowledge-acquisition.md +++ b/docs/src/content/docs/decisions/Adr-007-knowledge-acquisition.md @@ -1,5 +1,5 @@ --- -title: 007 knowledge acquisition +title: Adr 007 knowledge acquisition --- # ADR-007: Knowledge acquisition through progressive failure diff --git a/docs/src/content/docs/decisions/008-definition-of-done.md b/docs/src/content/docs/decisions/Adr-008-definition-of-done.md similarity index 98% rename from docs/src/content/docs/decisions/008-definition-of-done.md rename to docs/src/content/docs/decisions/Adr-008-definition-of-done.md index caeda51b..ac04ccab 100644 --- a/docs/src/content/docs/decisions/008-definition-of-done.md +++ b/docs/src/content/docs/decisions/Adr-008-definition-of-done.md @@ -1,5 +1,5 @@ --- -title: 008 definition of done +title: Adr 008 definition of done --- # ADR-008: Definition of Done (progressive maturity) diff --git a/docs/src/content/docs/decisions/009-security-posture-dev-agents.md b/docs/src/content/docs/decisions/Adr-009-security-posture-dev-agents.md similarity index 98% rename from docs/src/content/docs/decisions/009-security-posture-dev-agents.md rename to docs/src/content/docs/decisions/Adr-009-security-posture-dev-agents.md index 7fa62f81..98690138 100644 --- a/docs/src/content/docs/decisions/009-security-posture-dev-agents.md +++ b/docs/src/content/docs/decisions/Adr-009-security-posture-dev-agents.md @@ -1,5 +1,5 @@ --- -title: 009 security posture dev agents +title: Adr 009 security posture dev agents --- # ADR-009: Security posture and blast radius for development-time agents diff --git a/docs/src/content/docs/decisions/010-error-recovery.md b/docs/src/content/docs/decisions/Adr-010-error-recovery.md similarity index 98% rename from docs/src/content/docs/decisions/010-error-recovery.md rename to docs/src/content/docs/decisions/Adr-010-error-recovery.md index d16c44bf..ecf174a3 100644 --- a/docs/src/content/docs/decisions/010-error-recovery.md +++ b/docs/src/content/docs/decisions/Adr-010-error-recovery.md @@ -1,5 +1,5 @@ --- -title: 010 error recovery +title: Adr 010 error recovery --- # ADR-010: Error recovery and rollback protocol diff --git a/docs/src/content/docs/decisions/011-conflict-resolution.md b/docs/src/content/docs/decisions/Adr-011-conflict-resolution.md similarity index 98% rename from docs/src/content/docs/decisions/011-conflict-resolution.md rename to docs/src/content/docs/decisions/Adr-011-conflict-resolution.md index b9068b6c..1fba99dd 100644 --- a/docs/src/content/docs/decisions/011-conflict-resolution.md +++ b/docs/src/content/docs/decisions/Adr-011-conflict-resolution.md @@ -1,5 +1,5 @@ --- -title: 011 conflict resolution +title: Adr 011 conflict resolution --- # ADR-011: Conflict resolution protocol diff --git a/docs/src/content/docs/decisions/012-operational-knowledge-stack.md b/docs/src/content/docs/decisions/Adr-012-operational-knowledge-stack.md similarity index 99% rename from docs/src/content/docs/decisions/012-operational-knowledge-stack.md rename to docs/src/content/docs/decisions/Adr-012-operational-knowledge-stack.md index 5c6ab7a2..41c6e251 100644 --- a/docs/src/content/docs/decisions/012-operational-knowledge-stack.md +++ b/docs/src/content/docs/decisions/Adr-012-operational-knowledge-stack.md @@ -1,5 +1,5 @@ --- -title: 012 operational knowledge stack +title: Adr 012 operational knowledge stack --- # ADR-012: Operational knowledge as a three-layer stack (Decision → Guide → Skill) @@ -155,7 +155,7 @@ Organized by persona: ```markdown # Contributor Workflow -> Operationalizes [ADR-003](/architecture/003-contribution-governance) +> Operationalizes [ADR-003](/architecture/adr-003-contribution-governance) ## For Planners - Issue quality bar (what makes an issue "ready") diff --git a/docs/src/content/docs/decisions/013-tiered-validation-pyramid.md b/docs/src/content/docs/decisions/Adr-013-tiered-validation-pyramid.md similarity index 99% rename from docs/src/content/docs/decisions/013-tiered-validation-pyramid.md rename to docs/src/content/docs/decisions/Adr-013-tiered-validation-pyramid.md index 610abccb..762fccf7 100644 --- a/docs/src/content/docs/decisions/013-tiered-validation-pyramid.md +++ b/docs/src/content/docs/decisions/Adr-013-tiered-validation-pyramid.md @@ -1,5 +1,5 @@ --- -title: 013 tiered validation pyramid +title: Adr 013 tiered validation pyramid --- # ADR-013: Tiered validation pyramid for agentic-first development diff --git a/docs/src/content/docs/decisions/Readme.md b/docs/src/content/docs/decisions/Readme.md index a6e8d0af..bca2568b 100644 --- a/docs/src/content/docs/decisions/Readme.md +++ b/docs/src/content/docs/decisions/Readme.md @@ -49,7 +49,7 @@ What follows from this decision: ## Numbering -ADRs are numbered sequentially with zero-padded three-digit prefixes: `001-slug.md`, `002-slug.md`, etc. Numbers are never reused. +ADRs are numbered sequentially with zero-padded three-digit prefixes: `ADR-001-slug.md`, `ADR-002-slug.md`, etc. Numbers are never reused. ## Lifecycle