docs: ADR-005 through ADR-013 (feedback, flags, knowledge, DoD, security, recovery, conflicts, knowledge stack, validation pyramid)#144
Draft
scottschreckengaust wants to merge 10 commits into
Conversation
Introduces `docs/decisions/` as the normative location for Architecture Decision Records. ADR-001 documents the stacked PR methodology for delivering multi-PR features with reduced review fatigue. - docs/decisions/README.md — ADR process, template, lifecycle - docs/decisions/001-stacked-pull-requests.md — stacked PR methodology - AGENTS.md routing table updated for agent discoverability - Starlight sync + sidebar includes Decisions section Closes #129 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…tion ADR-003 defines how agents/humans pick up, own, and deliver work: priority evaluation, predecessor validation, cross-reference audit, self-assignment, and issue body as source of truth. ADR-004 defines the documentation standard: zero-context self-sufficiency, progressive disclosure, international English, testable instructions, and the tabula rasa quality test. Refs #134, #135 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…rity posture ADR-005: PR review feedback propagates upstream to issues and ADRs. Classification (nit/bug/design/architecture), pause-assess-propagate- resolve-resume protocol, stacked PR chain recovery. ADR-008: Progressive definition of done (Level 1-4). Default levels per issue type. Verification responsibility scales with risk. ADR-009: Development-time agent security. Role separation (planner/ implementor/reviewer/admin), blast radius classification, 2P review for high-risk changes, no self-approval. Refs #136, #139, #140 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…rror recovery, ADR-011 conflict resolution ADR-006: Feature flags for concurrent development. When to use, lifecycle (proposed→introduced→active→verified→permanent), ownership, maximum lifetime enforcement. ADR-007: Knowledge acquisition through progressive failure. Zero-context execution attempts, failure capture protocol, maturity model (L0-L3), self-improvement loop. ADR-010: Error recovery and rollback. Decision tree (revert vs fix- forward), stacked PR chain recovery, things agents must never do. ADR-011: Conflict resolution. Escalation ladder (4 levels), decision criteria, merge conflict ownership, human vs agent disagreements. Refs #137, #138, #141, #142 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
3 tasks
Fixes metadata gap: ADR-002 now references its implementing issue (#121) consistent with all other ADRs. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
… rework - Predecessor validation now uses GitHub GraphQL blockedBy/subIssues as the machine-enforceable source of truth (hard gate) - Rename "Self-assignment" to "Assignments" — supports self-assignment, directed assignment, and priority-based pickup - Add dependency graph maintenance rules (addBlockedBy, addSubIssue) - Sync rule: graph is authoritative; prose explains rationale - Folds comment feedback from issue #134 discussion Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Approval mechanism: label (not GitHub Projects) - Priority challenge: soft gate (warn + proceed if confirmed) - Stale assignments: auto-unassign after N configurable hours - Update references to reflect questions are resolved Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
9 tasks
…, ADR-003 enforcement ADR-012: Three-layer pattern (Decision → Guide → Skill) for operational knowledge. Includes ADR-003 decomposition example and documented failure mode where prose governance was bypassed. ADR-013: Four-tier validation pyramid addressing the missing Tier 2 (local sandbox) that causes agents to waste cycles on slow remote feedback loops. ADR-003: Add "no branches without an issue" rule, enforcement mechanisms table, and "conversational approval is NOT issue approval" section based on observed governance bypass. Refs #148 Refs #149 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
9 tasks
scottschreckengaust
changed the title
Contributor
Author
ADR-012, ADR-013, and ADR-003 enforcement updates addedThis commit ( 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:
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 pyramidAddresses 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
Follow-up work (after this PR merges)These are tracked but not in scope for this PR:
|
3 tasks
…lementation Adds two bullets to top of "Common mistakes": 1. Conversational approval ≠ governance approval — create issue first 2. Branch naming must include issue number Implements the "AGENTS.md directive" row from ADR-003's enforcement mechanisms table. Fixes #150 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
|
||
| ## References | ||
|
|
||
| - Issue #137 — full RFC with open questions on mechanism (CDK context vs. DynamoDB vs. env vars) |
There was a problem hiding this comment.
Mentions open questions but should we decide on a mechanism (CDK context, DynamoDB runtime config, env vars) before moving ahead or is this going to be context dependent?
scottschreckengaust
force-pushed
the
feat/adr-003-004
branch
from
daf33f1 to
744492d
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
Plus ADR-003 enforcement updates:
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)
Changes
10 new/modified ADR source files + 10 generated Starlight mirrors = 20 files, all documentation.
Test plan
astro check— 0 errorsCloses #136
Closes #137
Closes #138
Closes #139
Closes #140
Closes #141
Closes #142
Refs #148
Refs #149
🤖 Generated with Claude Code