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