docs: ADR-003 contribution governance + ADR-004 tabula rasa documentation#143
Merged
Conversation
This was referenced May 19, 2026
scottschreckengaust
force-pushed
the
feat/bootstrap-adr
branch
from
0174e2a to
010786e
Compare
…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>
scottschreckengaust
force-pushed
the
feat/adr-003-004
branch
from
daf33f1 to
744492d
Compare
Address review feedback: - Issue quality bar: body is primary directive, not exclusively sufficient — comments, predecessors, downstream goals all add context - Issue body section: renamed from "source of truth" to "primary directive"; reviewer synthesizes threads with body before implementation - Pre-start review: adds context synthesis step (predecessors, adjacent state, forward-look into downstream) - Work-in-progress: allows serializable work with declared ordering Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
mandeep408
reviewed
May 21, 2026
mandeep408
reviewed
May 21, 2026
mandeep408
reviewed
May 21, 2026
mandeep408
left a comment
mandeep408
left a comment
There was a problem hiding this comment.
Overall LGTM. Two clarifying questions on ADR-003 line 28 regarding the approval gate logic and workflow existence. Non-blocking.
- Rename "Admin approval gate" → "Gated approval" - "admin" → "permitted users" (workflow-based authorization) - Clarify AND condition: issue must be both approved AND assigned - Add scope-freeze semantic: after approval, deliverable changes need re-approval - Add consequence: self-assignment race condition acknowledged with refresh mitigation - Soften roadmap alignment to reference "permitted user" not "admin" Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
mandeep408
approved these changes
May 21, 2026
mandeep408
left a comment
mandeep408
left a comment
There was a problem hiding this comment.
LGTM with the follow-up items captured.
scottschreckengaust
added a commit
that referenced
this pull request
May 26, 2026
ADR-012: Operational knowledge stack (Decision → Guide → Skill) — three-layer pattern for executable governance. Documents observed failure mode where prose alone was insufficient. ADR-013: Tiered validation pyramid — addresses the missing Tier 2 (local sandbox) gap that causes agents to waste cycles on slow remote CI feedback loops. ADR-003: Adds "No branches without an issue" rule, "Conversational approval is NOT issue approval" section, and enforcement mechanisms table. These were lost during the rebase that consolidated the branch after PR #143 merged. Recovered from orphaned commit 8bb9407. Refs #148 Refs #149 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
isadeks
pushed a commit
to isadeks/sample-autonomous-cloud-coding-agents
that referenced
this pull request
May 27, 2026
…ity, recovery, conflicts, knowledge stack, validation pyramid) (aws-samples#144) * docs: ADR-005 feedback loop, ADR-008 definition of done, ADR-009 security 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 aws-samples#136, aws-samples#139, aws-samples#140 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: ADR-006 feature flags, ADR-007 knowledge acquisition, ADR-010 error 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 aws-samples#137, aws-samples#138, aws-samples#141, aws-samples#142 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs(ADR-003): GraphQL dependency graph as authoritative, assignments 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 aws-samples#134 discussion Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs(AGENTS.md): add governance directive — issue required before implementation 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 aws-samples#150 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: recover ADR-012, ADR-013, and ADR-003 enforcement (lost in rebase) ADR-012: Operational knowledge stack (Decision → Guide → Skill) — three-layer pattern for executable governance. Documents observed failure mode where prose alone was insufficient. ADR-013: Tiered validation pyramid — addresses the missing Tier 2 (local sandbox) gap that causes agents to waste cycles on slow remote CI feedback loops. ADR-003: Adds "No branches without an issue" rule, "Conversational approval is NOT issue approval" section, and enforcement mechanisms table. These were lost during the rebase that consolidated the branch after PR aws-samples#143 merged. Recovered from orphaned commit 8bb9407. Refs aws-samples#148 Refs aws-samples#149 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: address PR aws-samples#144 review feedback (ADR-006, -007, -009) ADR-006: Add lifecycle metadata table (merge date, max lifetime, expected removal) and mechanism constraint (synth-time vs runtime). ADR-007: Add retrospective concept as first-class knowledge artifact. ADR-009: Expand role table (Planner adds vision, Reviewer adds suggest code, Implementor clarifies no CI/security config) and add "not the last committer" constraint to no-self-approval. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: address reviewer feedback — status, decoupling, transition clause - Change ADR-005 through ADR-011 status from "accepted" to "proposed" (ADR-012/013 were already "proposed") - ADR-003 enforcement table: add Status column (Implemented/Planned), rename section to "Enforcement mechanisms (planned)", add transition clause for branch naming rules - ADR-012→013: make reference informational (013 depends on 012, not bidirectional) - ADR-013→012: mark as prerequisite dependency - ADR-003 references: mark 012/013 as "(proposed)" Addresses review from krokoko: critical items 1+2 (aspirational content labeled, transition clause added) and important item 4 (circular dependency broken with clear direction: 013 depends on 012). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: bgagent <345885+scottschreckengaust@users.noreply.github.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Co-authored-by: Alain Krok <alkrok@amazon.com>
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 3 of 4 for #145 — ADR governance framework
Prior (PR 2 / #133): ADR-002 least-privilege bootstrap decision record
This PR: ADR-003 (governance) + ADR-004 (documentation standard) — the two process foundations
Remaining: ADR-005 through ADR-011 (feedback loop, feature flags, knowledge acquisition, DoD, security posture, error recovery, conflict resolution)
Summary
Two foundational ADRs that everything else depends on:
ADR-003 — Contribution governance:
ADR-004 — Tabula rasa documentation:
Changes
docs/decisions/003-contribution-governance.mddocs/decisions/004-tabula-rasa-documentation.mddocs/src/content/docs/decisions/003-*.mddocs/src/content/docs/decisions/004-*.mdTest plan
astro check— 0 errorsCloses #134
Closes #135
🤖 Generated with Claude Code