docs: ADR-005 through ADR-013 (feedback, flags, knowledge, DoD, security, recovery, conflicts, knowledge stack, validation pyramid)

[scottschreckengaust]

Stack position

PR 4 of 4 for #145 — ADR governance framework

Prior (PR 3 / #143): ADR-003 governance + ADR-004 tabula rasa documentation

This PR: ADR-005 through ADR-013 — the full process/operational ADR set

Remaining: Merge full stack to main once reviewed

Summary

Nine ADRs completing the autonomous agent operating system:

ADR	Title	Theme
005	Feedback loop (PR → issue → ADR)	Evolution
006	Feature flags for concurrency	Execution
007	Knowledge acquisition through progressive failure	Learning
008	Definition of Done (progressive maturity)	Quality
009	Security posture & blast radius (dev-time agents)	Security
010	Error recovery and rollback	Resilience
011	Conflict resolution protocol	Collaboration
012	Operational knowledge stack (Decision → Guide → Skill)	Enforcement
013	Tiered validation pyramid	Velocity

Plus ADR-003 enforcement updates:

• "No branches without an issue" rule
• "Conversational approval is NOT issue approval" section
• Enforcement mechanisms table (branch naming, commit-msg hook, pre-push hook, skill gates)

ADR-012 and ADR-013 context

ADR-012 establishes the three-layer pattern for operational knowledge (ADR → Guide → Skill) and documents an observed failure mode where an agent violated ADR-003 despite having it loaded in context — proving that prose governance alone is insufficient for agents.

ADR-013 defines the four-tier validation pyramid (pre-commit → local build → local sandbox → remote CI) with emphasis on the missing Tier 2 that causes agents to waste cycles on slow remote feedback loops.

Dependency graph (all satisfied within the stack)

ADR-001 (PR #130) ─────────────────────────────────┐
ADR-003 (PR #143) ─┬─ ADR-005 (this PR)            │
                   ├─ ADR-008 (this PR)            │
                   ├─ ADR-009 (this PR)            │
                   └─ ADR-012 (this PR)            │
ADR-004 (PR #143) ─── ADR-007 (this PR)            │
ADR-005 + ADR-009 ─── ADR-006, 010, 011 (this PR)  │
ADR-012 ──────────── ADR-013 (this PR)             │
All ─── enable ─── Agent Swarm (roadmap) ◄─────────┘

Changes

10 new/modified ADR source files + 10 generated Starlight mirrors = 20 files, all documentation.

Test plan

• astro check — 0 errors
• Pre-commit hooks pass
• Pre-push hooks pass (security scans + package tests)
• CI build passes
• Full Starlight sidebar shows all 13 ADRs + README

Closes #136
Closes #137
Closes #138
Closes #139
Closes #140
Closes #141
Closes #142
Closes #150
Closes #148
Closes #149

🤖 Generated with Claude Code

[scottschreckengaust]

ADR-012, ADR-013, and ADR-003 enforcement updates added

This commit (8bb9407) adds three new pieces to this PR:

ADR-012: Operational knowledge stack (Decision → Guide → Skill)

Establishes the three-layer pattern. Key addition: "Why prose alone fails" section documenting how an agent (in this very session) violated ADR-003 despite having it loaded in context. The agent:

1. Created a branch without an issue number
2. Committed without a GitHub issue existing
3. Attempted to push without approval
4. Extended the PR stack without confirming
5. Worked from the wrong worktree location

This is the evidence that Layer 3 (executable skills with hard gates) is necessary — not just Layers 1 and 2 (prose + guides).

ADR-013: Tiered validation pyramid

Addresses the Tier 2 gap (local sandbox) that causes agents to waste 15+ minute cycles on remote CI feedback loops. Progressive build-out plan from LocalStack to full MicroVM sandbox.

ADR-003 enforcement updates

• New rule: "No branches without an issue" — branches must include issue numbers
• New section: "Conversational approval is NOT issue approval" — explicitly blocks the most common agent bypass
• New table: Enforcement mechanisms (branch naming, commit-msg hook, pre-push hook, Claude Code hook, skill gate, AGENTS.md directive)

Follow-up work (after this PR merges)

These are tracked but not in scope for this PR:

• Implement commit-msg hook enforcing Refs #N or Fixes #N
• Implement branch naming convention validation
• Create pickup-issue skill for Claude Code plugin
• Add AGENTS.md directive: "Do NOT begin implementation without an approved issue, even if user says 'go ahead'"
• Decompose ADR-003 into Guide + Skills (Phase 2 of ADR-012 migration plan)

[krokoko]

Great work on this ADR set — the intellectual framework is solid and the ideas (especially the three-layer stack in ADR-012 and the validation pyramid in ADR-013) represent genuine architectural thinking about executable governance for autonomous agents. The "Why prose alone fails" section in ADR-012 is particularly compelling as motivational evidence.

That said, I have some concerns I'd like to see addressed before merge. I've organized them by severity.

---

Critical: Aspirational content presented as factual

The ADR-003 enforcement mechanisms table uses present-tense language ("The following enforcement points prevent bypass") but comparing against the actual repo state, none of the six listed mechanisms exist today:

• No commit-msg hook validating Refs #N
• No pre-push hook checking issue existence/approval
• No branch name convention enforcement
• No Claude Code PreToolUse: Write hook
• No pickup-issue skill

The only mechanism that exists is the AGENTS.md directive — which ADR-012 itself argues is insufficient. Could we add an "Implementation Status" column (Implemented / Planned / Proposed) to the table? Or rename the section "Planned Enforcement Mechanisms"? Future readers (especially agents) cannot distinguish between "we decided this" and "we built this."

Critical: The PR's own branch violates the rules it introduces

The new AGENTS.md directive states branch names must follow (feat|fix|chore|docs)/<issue-number>-short-description. This PR's branch is feat/adr-005-008-009 — no issue number. A governance framework that violates itself on delivery teaches agents that rules are suggestions. I'd suggest either:

• Adding a transition note: "Applies to branches created after enforcement hooks are deployed"
• Or delaying the AGENTS.md directive until at least one enforcement hook exists

Important: The bootstrapping paradox in ADR-012

ADR-012 states that ADRs "MUST NOT contain: Step-by-step procedures, checklists with >3 items, decision trees with branches, protocol sequences." Yet this same PR introduces ADRs that contain all of these (ADR-003's enforcement table, ADR-008's level checklists, ADR-010's decision tree, ADR-012's own migration plan). The "existing ADRs are updated incrementally" clause doesn't fully resolve this since these are new ADRs introduced alongside the rule.

Suggestion: Add an explicit "Applies to ADRs created after Phase 2 is complete" scoping clause, or extract the operational content from 012/013 into companion documents to demonstrate the pattern.

Important: ADR-012/013 circular dependency

• ADR-012 references ADR-013 for enforcement hooks
• ADR-013 references ADR-012 for skill interaction

Each defines half of the enforcement architecture. Could we either give them a clear dependency direction (013 depends on 012, not bidirectional) or merge them into a single "Agentic Enforcement Architecture" ADR?

Important: ADR-003 (accepted) depends on ADR-012/013 (proposed)

ADR-003's enforcement section references proposed ADRs as its foundation. If 012/013 are revised or rejected, ADR-003's enforcement section becomes incoherent. Suggestion: make the references conditional, e.g., "See ADR-012 (proposed) for the planned enforcement model."

Moderate: ADR-012 scope creep

At 265 lines, ADR-012 contains the decision (~100 lines), a full ADR-003 decomposition example, a failure mode narrative, a 4-phase migration plan, and "Plugin marketplace (future)" speculation. The migration plan in particular belongs in tracked issues — without deadlines or milestone references, it will become stale within 3-6 months. Consider extracting Phases 1-4 into issues (one per phase) and the ADR-003 decomposition example into a guide document.

Minor: ADR-013 Tier 1 characterization

ADR-013 states Tier 1 is "not enforced as a push gate," but .pre-commit-config.yaml already includes monorepo-tests-pre-push at the pre-push stage. It's more accurate to say the full mise run build isn't gated on push, but a subset (tests + security) already is.

---

Suggested path forward

I'd feel comfortable approving if we could:

1. Label aspirational enforcement as planned (status column or renamed section header)
2. Add a transition/scoping clause so the rules don't claim authority they can't enforce yet
3. Extract the migration plan from ADR-012 into tracked issues
4. Break the 012/013 cycle (clear dependency direction)

Bonus: implementing even one enforcement hook (e.g., a commit-msg hook checking for Refs #N) in this PR would demonstrate that the enforcement philosophy is more than theoretical — and would powerfully complement the "prose alone fails" argument in ADR-012.

The thinking here is strong. One more pass on form and we're good to go.

[scottschreckengaust]

Addressing review feedback (commit 5904ae3)

Thanks for the thorough review. Here's what's addressed and what's deferred:

Addressed in this commit

Concern	Resolution
Critical: Aspirational content as factual	ADR-003 enforcement table now has a Status column (Implemented / Planned). Section renamed to "Enforcement mechanisms (planned)". Only the AGENTS.md directive is marked as Implemented.
Critical: Branch violates own rules	Added transition clause: "Branch naming and commit-msg rules apply to branches created after the corresponding hooks are deployed. Existing branches (including this PR's) pre-date enforcement."
Important: 012/013 circular dependency	Broken with clear direction: ADR-013 depends on ADR-012 (not bidirectional). ADR-012's reference to 013 is now informational ("depends on this ADR for skill-based agent interaction"). ADR-013 explicitly marks ADR-012 as (prerequisite).
Important: ADR-003 depends on proposed ADRs	References now marked (proposed) with conditional language.
ADR status	All ADRs 005–013 changed to proposed status (reviewer + author agreed these are decisions not yet implemented).

Deferred to follow-on (tracked in #186)

Concern	Tracking
Moderate: ADR-012 scope creep / migration plan extraction	The 4-phase migration plan will be extracted into issues per-phase. #186 tracks all enforcement implementation. ADR-012 stays as-is for this PR — the migration plan provides context for the proposed architecture.
Important: Bootstrapping paradox	Acknowledged as a bootstrapping reality: the ADRs that define the knowledge-stack rules are themselves the first content to be decomposed. A scoping note can be added in Phase 2 once companion documents exist to demonstrate the pattern.
Minor: Tier 1 characterization	Fair point — a follow-on PR can clarify that a subset (tests + security) already gates push while the full mise run build does not.

CI "no space left on device"

The build job (mise run build) includes Docker image bundling for the agent container during cdk synth. GitHub-hosted runners have ~14GB usable disk. This build exhausts it when combining: yarn install (node_modules), Python venv, Docker layers, and CDK output. This affects all PRs — not specific to this one. A disk cleanup step (docker system prune, remove pre-installed tools) should be added to build.yml as a separate fix. Filed as a known issue.

Dependency direction summary

ADR-003 (accepted) ──references──→ ADR-012 (proposed)
                    ──references──→ ADR-013 (proposed)

ADR-012 (proposed) ──informational──→ ADR-013 (proposed)

ADR-013 (proposed) ──depends on──→ ADR-012 (proposed)

No cycles. If ADR-012 is rejected, ADR-013's agent interaction model needs revision. If ADR-013 is rejected, ADR-012 stands alone (its references to 013 are informational only).