You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-**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).
43
+
-**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`.
42
44
- Editing **`docs/src/content/docs/`** instead of **`docs/guides/`** or **`docs/design/`** — content is generated; sync from sources.
43
45
- 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.
44
46
- Changing **`cdk/.../types.ts`** without updating **`cli/src/types.ts`** — CLI and API drift.
Copy file name to clipboardExpand all lines: docs/decisions/003-contribution-governance.md
+48-3Lines changed: 48 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,6 +11,10 @@ The rules below define how any contributor — human or AI — picks up, owns, a
11
11
12
12
## Decision
13
13
14
+
### No branches without an Issue
15
+
16
+
Every feature branch references an issue in its name (e.g., `feat/123-short-description` or `fix/456-bug-name`). A branch without an issue reference is unauthorized work. This prevents the failure mode where work is started "just to explore" and then snowballs into a PR without governance.
17
+
14
18
### No PRs without an Issue
15
19
16
20
Every PR references an issue. The issue provides rationale, sufficient context for the solution to be obvious, and verifiable acceptance criteria.
@@ -27,9 +31,9 @@ Issues align to the [product roadmap](https://github.com/aws-samples/sample-auto
27
31
28
32
Only permitted users can mark an issue `approved` — a GitHub Actions workflow validates that the label applicant is authorized. An issue is not workable until it is both approved and assigned. After approval, the issue is considered scope-frozen: further revisions that change deliverables require re-approval.
29
33
30
-
### Self-assignment on start
34
+
### Assignments
31
35
32
-
Unassigned means available. On starting work, self-assign. Multiple assignees (>1) require intentionality verification.
36
+
Unassigned means available. Assignment may happen via self-assignment, directed assignment by another agent/human, or priority-based pickup (inspect open tasks for highest priority + earliest predecessor). Multiple assignees (>1) require intentionality verification.
33
37
34
38
### Issue body as primary directive
35
39
@@ -47,10 +51,16 @@ Before implementation, the assigned contributor must:
47
51
48
52
**Priority evaluation:** Identify priority (`p0`/`p1`/`p2`). If asked to work a lower-priority item while higher-priority items are unassigned, challenge: "Should I work on #X (p0) instead?"
49
53
50
-
**Predecessor validation:** If predecessors are incomplete, unassigned, and not in a stacked PR — challenge: "Steps 1-3 are incomplete. Starting step 4 may cause rework."
54
+
**Predecessor validation (GraphQL dependency graph is authoritative):**
55
+
- Query the issue's `blockedBy` field via GraphQL — if any blocking issue is open, this issue is **not ready** (hard gate)
56
+
- Check `parent`/`subIssues` ordering — verify prior siblings are complete or in-flight
57
+
- Reconcile graph vs. prose — graph is authoritative for enforcement; prose explains rationale
58
+
- If predecessors are incomplete, unassigned, and not in a stacked PR — challenge: "Steps 1-3 are incomplete. Starting step 4 may cause rework."
51
59
52
60
**Cross-reference audit:** Search open issues for duplicates. Search open PRs (including drafts) for conflicts. Flag overlaps. Check the full dependency graph. Forward-look into downstream actions to ensure alignment.
53
61
62
+
**Dependency graph maintenance:** When creating/modifying issues with dependencies, use GraphQL mutations (`addBlockedBy`, `addSubIssue`) to maintain the machine-enforceable graph. Update prose to explain rationale. If they diverge, fix the wrong one (usually prose — graph is set programmatically).
63
+
54
64
**Final gate:** If all checks pass, comment "Starting implementation."
55
65
56
66
### Identity and attribution
@@ -65,20 +75,55 @@ Provide progress signals at checkpoints. If blocked or abandoning, comment and u
65
75
66
76
CI passes before requesting review. After merge, verify acceptance criteria and close. Create follow-up issues for discovered work before closing.
67
77
78
+
### Conversational approval is NOT issue approval
79
+
80
+
A user saying "yes, do it" or "go ahead" in a conversation does NOT satisfy the governance gate. The correct response to conversational approval is:
81
+
82
+
1. Create an issue with acceptance criteria
83
+
2. Request the `approved` label from an admin
84
+
3. Self-assign once approved
85
+
4. Then begin implementation
86
+
87
+
**Known failure mode:** Agents interpret conversational momentum ("Yes start with X") as authorization to skip issue creation. This is the most common governance bypass — it feels like permission because the user explicitly directed the work, but the governance requires a *durable, reviewable artifact* (the issue), not a transient conversation.
88
+
89
+
**Why this matters:** Conversations are ephemeral. Issues are auditable. If an agent creates work based on a conversation and that conversation is lost (context compaction, session end), no record exists of what was authorized, what the acceptance criteria were, or why the work was started.
90
+
91
+
### Enforcement mechanisms (planned)
92
+
93
+
Prose governance is necessary but insufficient. The following enforcement points are planned to prevent bypass progressively. Mechanisms are deployed incrementally — see #186 for implementation tracking.
94
+
95
+
| Mechanism | Layer | What it catches | Status |
96
+
|-----------|-------|-----------------|--------|
97
+
| AGENTS.md directive | Agent prompt | Explicit instruction: "Do NOT begin implementation without an approved issue, even if the user says 'go ahead' in conversation" | Implemented |
98
+
| Branch name convention | Git workflow | Branch must match `(feat|fix|chore|docs)/<issue-number>-*` — rejects branches without issue reference | Planned |
99
+
| Commit-msg hook (Tier 0) | Pre-commit | Rejects commits without `Refs #N` or `Fixes #N`| Planned |
100
+
| Pre-push hook (Tier 1) | Pre-push | Validates referenced issue exists and has `approved` label via `gh` API | Planned |
101
+
| Claude Code hook (`PreToolUse: Write`) | Agent runtime | Blocks file creation in governed paths without declared issue context | Planned |
102
+
| Skill gate: `pickup-issue`| Agent workflow | Agent must invoke before implementation — hard-fails without valid issue | Planned |
103
+
104
+
**Transition:** 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.
105
+
106
+
**Progressive enforcement:** Start with the commit-msg hook (cheapest, catches all contributors). Add pre-push validation next. Skill gates enforce at the agent-workflow level (see ADR-012, proposed, for the skill model).
# ADR-005: Feedback loop — PR reviews propagate to issues and ADRs
2
+
3
+
**Status:** proposed
4
+
**Date:** 2026-05-19
5
+
6
+
## Context
7
+
8
+
PR review comments are addressed locally (fix the code) but systemic issues they reveal are not propagated upstream. A reviewer says "this approach is wrong" but the issue still says "use this approach." ADRs are treated as immutable when they should be living decisions that evolve with implementation experience.
9
+
10
+
Without a feedback protocol, review insights are lost, issue bodies rot, and architectural mistakes persist across stacked PR chains.
# ADR-006: Feature flags for concurrent development
2
+
3
+
**Status:** proposed
4
+
**Date:** 2026-05-19
5
+
6
+
## Context
7
+
8
+
Multiple agents working on related features in the same area must serialize — one waits for the other to merge. Incomplete features either block the main branch or require long-lived branches that diverge. SRE needs kill switches without reverting commits.
9
+
10
+
Feature flags enable trunk-based development where incomplete work merges safely behind toggles, and concurrent contributors avoid blocking each other.
11
+
12
+
## Decision
13
+
14
+
### When to use flags
15
+
16
+
| Situation | Use a flag? |
17
+
|-----------|-------------|
18
+
| Feature spans multiple PRs, incomplete state is unsafe | Yes |
19
+
| Two contributors touch the same module for different purposes | Yes |
20
+
| SRE needs a kill switch for a new capability | Yes |
21
+
| Simple refactor with no behavioral change | No |
22
+
| Bug fix | No |
23
+
| One-PR feature, complete on merge | No |
24
+
25
+
### Flag ownership
26
+
27
+
- Every flag has an owner (the issue that introduced it)
28
+
- Every flag has an expiration (the issue/PR that removes it)
29
+
- Flags without a removal plan are rejected in review
30
+
31
+
### Separation of concerns
32
+
33
+
-**Planners** decide which features get flags (issue/RFC level)
34
+
-**Implementors** add/use flags in code (PR level)
35
+
-**SRE/operators** toggle flags in production (runtime level)
36
+
-**No self-approval** — the person who introduces a flag cannot approve its removal
37
+
38
+
### Flag lifecycle
39
+
40
+
1.**Proposed** — issue identifies the need for a flag
41
+
2.**Introduced** — PR adds the flag (default: off)
42
+
3.**Active** — feature behind flag is in development
43
+
4.**Verified** — feature complete, flag toggled on in testing
44
+
5.**Permanent** — flag removed, feature is always-on (or removed entirely)
| Actual removal date | — | Auto when flag deleted |
58
+
| Days active | — | Computed |
59
+
60
+
### Maximum lifetime
61
+
62
+
Flags must be removed within the declared max lifetime (default: 4 weeks) of the feature being verified. The max lifetime can be overridden per-flag with justification in the issue. Stale flags are treated as technical debt and surfaced in periodic reviews.
63
+
64
+
### Mechanism constraint
65
+
66
+
Flags MUST be resolvable at synth time for infrastructure flags and at runtime for behavior flags. The specific storage mechanism (CDK context, DynamoDB, SSM Parameter Store, env vars) is context-dependent and follows from this split — it is not prescribed by this ADR.
67
+
68
+
## Consequences
69
+
70
+
- (+) Concurrent work proceeds without blocking
71
+
- (+) Trunk-based development: main stays deployable
72
+
- (+) SRE can disable features without code changes
73
+
- (+) Partial features merge safely
74
+
- (-) Flag management overhead
75
+
- (-) Combinatorial testing complexity if many flags exist simultaneously
76
+
- (!) Maximum lifetime must be enforced or flags accumulate indefinitely
77
+
78
+
## References
79
+
80
+
- Issue #137 — full RFC with open questions on mechanism (CDK context vs. DynamoDB vs. env vars)
# ADR-007: Knowledge acquisition through progressive failure
2
+
3
+
**Status:** proposed
4
+
**Date:** 2026-05-19
5
+
6
+
## Context
7
+
8
+
Agents with fresh context (tabula rasa) attempt to follow documentation and hit gaps they cannot resolve. These gaps are silently worked around (agent asks a human) rather than systematically fixed. The system cannot self-improve its onboarding because failures are not captured.
9
+
10
+
Knowledge acquisition starts from zero. Each iteration creates the roadmap to better knowledge by discovering gaps through actual failures.
11
+
12
+
## Decision
13
+
14
+
### Zero-context execution attempts
15
+
16
+
Periodically, an agent with no project memory attempts to follow guides end-to-end. The agent follows ONLY what is written — no inference, no training data knowledge, no asking colleagues.
17
+
18
+
### Failure capture protocol
19
+
20
+
At each failure point, the agent:
21
+
1.**Stops** — does not attempt to work around or guess
22
+
2.**Documents** — creates an issue: which document, which step, what was missing
23
+
3.**Continues** — attempts the next step (if possible) to find additional gaps
24
+
25
+
### Retrospectives
26
+
27
+
After completing a task, project milestone, or sprint, agents produce a retrospective artifact:
28
+
- What worked well (patterns to repeat)
29
+
- What failed or caused friction (patterns to avoid)
30
+
- Actionable experiments for future workflows
31
+
32
+
Retrospectives are a first-class knowledge artifact — they feed into documentation improvements, inform ADR amendments, and surface systemic issues that individual task failures cannot.
33
+
34
+
### Knowledge artifacts (interim)
35
+
36
+
Until documentation meets ADR-004, agents may create ephemeral artifacts:
37
+
- Semantic indices of the codebase (call graphs, dependency maps)
38
+
- Annotated walkthroughs of successful executions
39
+
- "What I learned" summaries after completing a task
40
+
- Retrospectives (see above)
41
+
42
+
These are scaffolding that informs documentation improvements, not documentation themselves.
43
+
44
+
### Maturity model
45
+
46
+
| Level | State | Agent capability |
47
+
|-------|-------|-----------------|
48
+
| 0 | No docs | Cannot start; files issue for missing docs |
0 commit comments