aws-samples · krokoko · May 29, 2026 · May 29, 2026
@@ -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 <n>`. 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)/<issue-number>-short-description`.
    A branch without an issue reference is unauthorized work — flag it.
 4. Review the commit history (`gh pr view <n> --json commits` / `git log`) to understand the

@@ -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)/<issue-number>-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.

@@ -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

@@ -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")

@@ -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
 

@@ -1,5 +1,5 @@
 ---
-title: 001 stacked pull requests
+title: Adr 001 stacked pull requests
 ---
 
 # ADR-001: Stacked pull requests for multi-PR features

@@ -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

@@ -1,5 +1,5 @@
 ---
-title: 003 contribution governance
+title: Adr 003 contribution governance
 ---
 
 # ADR-003: Contribution governance for async agents and humans

@@ -1,5 +1,5 @@
 ---
-title: 004 tabula rasa documentation
+title: Adr 004 tabula rasa documentation
 ---
 
 # ADR-004: Tabula rasa documentation standard

@@ -1,5 +1,5 @@
 ---
-title: 005 feedback loop
+title: Adr 005 feedback loop
 ---
 
 # ADR-005: Feedback loop — PR reviews propagate to issues and ADRs

@@ -1,5 +1,5 @@
 ---
-title: 006 feature flags
+title: Adr 006 feature flags
 ---
 
 # ADR-006: Feature flags for concurrent development

@@ -1,5 +1,5 @@
 ---
-title: 007 knowledge acquisition
+title: Adr 007 knowledge acquisition
 ---
 
 # ADR-007: Knowledge acquisition through progressive failure

@@ -1,5 +1,5 @@
 ---
-title: 008 definition of done
+title: Adr 008 definition of done
 ---
 
 # ADR-008: Definition of Done (progressive maturity)

@@ -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

@@ -1,5 +1,5 @@
 ---
-title: 010 error recovery
+title: Adr 010 error recovery
 ---
 
 # ADR-010: Error recovery and rollback protocol

@@ -1,5 +1,5 @@
 ---
-title: 011 conflict resolution
+title: Adr 011 conflict resolution
 ---
 
 # ADR-011: Conflict resolution protocol

@@ -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")

@@ -1,5 +1,5 @@
 ---
-title: 013 tiered validation pyramid
+title: Adr 013 tiered validation pyramid
 ---
 
 # ADR-013: Tiered validation pyramid for agentic-first development

@@ -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