docs: ADR-003 contribution governance + ADR-004 tabula rasa documentation

docs/decisions/003-contribution-governance.md

@@ -0,0 +1,83 @@
+# ADR-003: Contribution governance for async agents and humans
+
+**Status:** accepted
+**Date:** 2026-05-19
+
+## Context
+
+ABCA is designed for multiple autonomous agents to work concurrently on the codebase. Without explicit governance rules, agents duplicate effort, start unapproved work, ignore priority order, miss predecessors, and create merge conflicts that require human intervention to untangle.
+
+The rules below define how any contributor — human or AI — picks up, owns, and delivers work. They prevent priority inversion, wasted rework, unauthorized scope creep, and silent conflicts at scale.
+
+## Decision
+
+### No PRs without an Issue
+
+Every PR references an issue. The issue provides rationale, sufficient context for the solution to be obvious, and verifiable acceptance criteria.
+
+### Issue quality bar
+
+An issue is "ready for work" when the body, together with its linked context — comments, replies, predecessor issues, related PRs (open and merged), and downstream goals — gives the implementer enough to proceed without ambiguity. The body is the primary directive; comments and threads add solution-space context; predecessors establish environmental architecture; downstream issues inform alignment.
+
+### Roadmap alignment
+
+Issues align to the [product roadmap](https://github.com/aws-samples/sample-autonomous-cloud-coding-agents/blob/main/docs/guides/ROADMAP.md). Issues that do not align require explicit admin approval.
+
+### Admin approval gate
+
+Only `admin` users can mark an issue `approved`. Unapproved and unassigned issues are not workable. A GitHub Actions workflow prevents non-admins from adding the `approved` label.
+
+### Self-assignment on start
+
+Unassigned means available. On starting work, self-assign. Multiple assignees (>1) require intentionality verification.
+
+### Issue body as primary directive
+
+The issue body provides the primary directive for implementation. Comments, replies, and clarifying answers add context to the solution space. Ideally the body is sufficient, but it need not be the exclusive source — the reviewer for implementation readiness should synthesize comments and replies with the body to surface inconsistencies and resolve ambiguities before commencing work.
+
+Unresolved conflicts are marked explicitly:
+- `**UNRESOLVED:** <question>` — blocks implementation
+- `**DEFERRED:** <question> — tracked in #N` — does not block
+
+### Pre-start review
+
+Before implementation, the assigned contributor must:
+
+**Synthesize context:** Read all comments and replies. Review predecessor issues and PRs (both merged and in-flight). Consider downstream goals and adjacent state (other open PRs, recent merges, dependency changes). Surface inconsistencies between body and thread before proceeding.
+
+**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?"
+
+**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."
+
+**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.
+
+**Final gate:** If all checks pass, comment "Starting implementation."
+
+### Identity and attribution
+
+Agents use identifiable credentials. The prompting user and acting agent must be distinguishable. PRs include `Co-Authored-By` for AI contributors.
+
+### Work-in-progress discipline
+
+Provide progress signals at checkpoints. If blocked or abandoning, comment and unassign. Do not start multiple issues simultaneously unless explicitly parallelizable or serializable with declared ordering (where context from one directly informs the next).
+
+### Completion and handoff
+
+CI passes before requesting review. After merge, verify acceptance criteria and close. Create follow-up issues for discovered work before closing.
+
+## Consequences
+
+- (+) Prevents duplicate effort — assignment signals ownership
+- (+) Prevents priority inversion — agents challenge low-priority requests
+- (+) Prevents rework — predecessor validation catches out-of-order work
+- (+) Issue body stays current — threads are folded back
+- (+) Cross-reference audit catches duplicates early
+- (-) Pre-start overhead for small tasks
+- (-) Requires discipline to fold threads into body
+- (!) Assumes priority labels exist and are maintained
+
+## References
+
+- Issue #134 — full RFC with open questions and automation requirements
+- Roadmap: Scale and collaboration (Agent swarm, Multi-user and teams)
+- ADR-001 — delivery methodology referenced by completion rules

docs/decisions/004-tabula-rasa-documentation.md

@@ -0,0 +1,90 @@
+# ADR-004: Tabula rasa documentation standard
+
+**Status:** accepted
+**Date:** 2026-05-19
+
+## Context
+
+Documentation written by people with deep project knowledge assumes readers share that knowledge. Acronyms go unexpanded, prerequisite steps are skipped as "obvious," and instructions break for anyone starting from zero — including autonomous agents with fresh context windows.
+
+This is especially damaging for a platform designed to be operated by agents: every documentation gap becomes a hard failure point. Agents cannot guess, infer from memory, or ask a colleague what "bootstrap the toolkit" means.
+
+## Decision
+
+### The Tabula Rasa Test
+
+Every document must pass: **Can someone with zero project knowledge, following only what is written, complete the described outcome?** If any step requires knowledge not present in the document or explicitly linked, the document fails.
+
+### Minimally sufficient
+
+Write the minimum that makes the reader succeed — not the minimum words, but the minimum *sufficient* content.
+
+- Novice needs explanation: one-sentence "what this does" before each step
+- Expert needs speed: scannable structure (numbered steps, headers, tables)
+- Both need confidence: expected output or success criteria after key steps
+
+### Progressive disclosure
+
+```
+Layer 1: What (one paragraph — what this helps you do)
+Layer 2: Steps (numbered, self-contained, runnable)
+Layer 3: Further reading (links with one-sentence descriptions)
+```
+
+Never force a novice to read expert material to proceed. Never force an expert to wade through explanations to find the command.
+
+### International English
+
+- Simple sentence structure (subject-verb-object)
+- No idioms or colloquialisms
+- Concrete words ("run this command" not "execute the following")
+- One idea per sentence
+- Active voice
+
+### Self-contained references
+
+When referencing another document:
+- State what the reader gets from it: "See [Deployment Guide](link) for AWS account setup (required before this step)"
+- Never assume the reader has read it
+- Never use "as mentioned above" — each section must stand alone after context compaction
+
+### Testable documentation
+
+- Commands are copy-pasteable (no hidden dependencies)
+- Expected output shown after non-trivial commands
+- Prerequisites listed at the top, not discovered mid-flow
+- Error states documented: "If you see X, it means Y. Fix: Z"
+
+### Terminology consistency
+
+- Use the same term for the same concept everywhere
+- Bold on first use with parenthetical definition
+- Maintain a project glossary for machine and human consumption
+
+### Quality checklist (per document)
+
+- First paragraph answers: "What does this help me do?"
+- Prerequisites listed at top
+- Every command includes directory context
+- Acronyms expanded on first use
+- No dangling references
+- Expected output shown after key steps
+- Error states documented for common failures
+- Further reading links have descriptions
+- Passes the tabula rasa test
+
+## Consequences
+
+- (+) New users complete guides without external help
+- (+) Agents execute workflows without human clarification
+- (+) Documentation gaps are discoverable (ADR-007 progressive failure protocol)
+- (+) International accessibility improves
+- (-) More writing effort per document
+- (-) Experts may find some material overly explicit (mitigated by progressive disclosure)
+- (!) Existing documentation does not meet this standard — improvement is incremental, not a rewrite
+
+## References
+
+- Issue #135 — full RFC with application matrix and open questions
+- Roadmap: Documentation and specifications
+- ADR-007 — knowledge acquisition protocol (complements this standard)

docs/src/content/docs/decisions/003-contribution-governance.md

@@ -0,0 +1,87 @@
+---
+title: 003 contribution governance
+---
+
+# ADR-003: Contribution governance for async agents and humans
+
+**Status:** accepted
+**Date:** 2026-05-19
+
+## Context
+
+ABCA is designed for multiple autonomous agents to work concurrently on the codebase. Without explicit governance rules, agents duplicate effort, start unapproved work, ignore priority order, miss predecessors, and create merge conflicts that require human intervention to untangle.
+
+The rules below define how any contributor — human or AI — picks up, owns, and delivers work. They prevent priority inversion, wasted rework, unauthorized scope creep, and silent conflicts at scale.
+
+## Decision
+
+### No PRs without an Issue
+
+Every PR references an issue. The issue provides rationale, sufficient context for the solution to be obvious, and verifiable acceptance criteria.
+
+### Issue quality bar
+
+An issue is "ready for work" when the body, together with its linked context — comments, replies, predecessor issues, related PRs (open and merged), and downstream goals — gives the implementer enough to proceed without ambiguity. The body is the primary directive; comments and threads add solution-space context; predecessors establish environmental architecture; downstream issues inform alignment.
+
+### Roadmap alignment
+
+Issues align to the [product roadmap](https://github.com/aws-samples/sample-autonomous-cloud-coding-agents/blob/main/docs/guides/ROADMAP.md). Issues that do not align require explicit admin approval.
+
+### Admin approval gate
+
+Only `admin` users can mark an issue `approved`. Unapproved and unassigned issues are not workable. A GitHub Actions workflow prevents non-admins from adding the `approved` label.
+
+### Self-assignment on start
+
+Unassigned means available. On starting work, self-assign. Multiple assignees (>1) require intentionality verification.
+
+### Issue body as primary directive
+
+The issue body provides the primary directive for implementation. Comments, replies, and clarifying answers add context to the solution space. Ideally the body is sufficient, but it need not be the exclusive source — the reviewer for implementation readiness should synthesize comments and replies with the body to surface inconsistencies and resolve ambiguities before commencing work.
+
+Unresolved conflicts are marked explicitly:
+- `**UNRESOLVED:** <question>` — blocks implementation
+- `**DEFERRED:** <question> — tracked in #N` — does not block
+
+### Pre-start review
+
+Before implementation, the assigned contributor must:
+
+**Synthesize context:** Read all comments and replies. Review predecessor issues and PRs (both merged and in-flight). Consider downstream goals and adjacent state (other open PRs, recent merges, dependency changes). Surface inconsistencies between body and thread before proceeding.
+
+**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?"
+
+**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."
+
+**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.
+
+**Final gate:** If all checks pass, comment "Starting implementation."
+
+### Identity and attribution
+
+Agents use identifiable credentials. The prompting user and acting agent must be distinguishable. PRs include `Co-Authored-By` for AI contributors.
+
+### Work-in-progress discipline
+
+Provide progress signals at checkpoints. If blocked or abandoning, comment and unassign. Do not start multiple issues simultaneously unless explicitly parallelizable or serializable with declared ordering (where context from one directly informs the next).
+
+### Completion and handoff
+
+CI passes before requesting review. After merge, verify acceptance criteria and close. Create follow-up issues for discovered work before closing.
+
+## Consequences
+
+- (+) Prevents duplicate effort — assignment signals ownership
+- (+) Prevents priority inversion — agents challenge low-priority requests
+- (+) Prevents rework — predecessor validation catches out-of-order work
+- (+) Issue body stays current — threads are folded back
+- (+) Cross-reference audit catches duplicates early
+- (-) Pre-start overhead for small tasks
+- (-) Requires discipline to fold threads into body
+- (!) Assumes priority labels exist and are maintained
+
+## References
+
+- Issue #134 — full RFC with open questions and automation requirements
+- Roadmap: Scale and collaboration (Agent swarm, Multi-user and teams)
+- ADR-001 — delivery methodology referenced by completion rules

docs/src/content/docs/decisions/004-tabula-rasa-documentation.md

@@ -0,0 +1,94 @@
+---
+title: 004 tabula rasa documentation
+---
+
+# ADR-004: Tabula rasa documentation standard
+
+**Status:** accepted
+**Date:** 2026-05-19
+
+## Context
+
+Documentation written by people with deep project knowledge assumes readers share that knowledge. Acronyms go unexpanded, prerequisite steps are skipped as "obvious," and instructions break for anyone starting from zero — including autonomous agents with fresh context windows.
+
+This is especially damaging for a platform designed to be operated by agents: every documentation gap becomes a hard failure point. Agents cannot guess, infer from memory, or ask a colleague what "bootstrap the toolkit" means.
+
+## Decision
+
+### The Tabula Rasa Test
+
+Every document must pass: **Can someone with zero project knowledge, following only what is written, complete the described outcome?** If any step requires knowledge not present in the document or explicitly linked, the document fails.
+
+### Minimally sufficient
+
+Write the minimum that makes the reader succeed — not the minimum words, but the minimum *sufficient* content.
+
+- Novice needs explanation: one-sentence "what this does" before each step
+- Expert needs speed: scannable structure (numbered steps, headers, tables)
+- Both need confidence: expected output or success criteria after key steps
+
+### Progressive disclosure
+
+```
+Layer 1: What (one paragraph — what this helps you do)
+Layer 2: Steps (numbered, self-contained, runnable)
+Layer 3: Further reading (links with one-sentence descriptions)
+```
+
+Never force a novice to read expert material to proceed. Never force an expert to wade through explanations to find the command.
+
+### International English
+
+- Simple sentence structure (subject-verb-object)
+- No idioms or colloquialisms
+- Concrete words ("run this command" not "execute the following")
+- One idea per sentence
+- Active voice
+
+### Self-contained references
+
+When referencing another document:
+- State what the reader gets from it: "See [Deployment Guide](link) for AWS account setup (required before this step)"
+- Never assume the reader has read it
+- Never use "as mentioned above" — each section must stand alone after context compaction
+
+### Testable documentation
+
+- Commands are copy-pasteable (no hidden dependencies)
+- Expected output shown after non-trivial commands
+- Prerequisites listed at the top, not discovered mid-flow
+- Error states documented: "If you see X, it means Y. Fix: Z"
+
+### Terminology consistency
+
+- Use the same term for the same concept everywhere
+- Bold on first use with parenthetical definition
+- Maintain a project glossary for machine and human consumption
+
+### Quality checklist (per document)
+
+- First paragraph answers: "What does this help me do?"
+- Prerequisites listed at top
+- Every command includes directory context
+- Acronyms expanded on first use
+- No dangling references
+- Expected output shown after key steps
+- Error states documented for common failures
+- Further reading links have descriptions
+- Passes the tabula rasa test
+
+## Consequences
+
+- (+) New users complete guides without external help
+- (+) Agents execute workflows without human clarification
+- (+) Documentation gaps are discoverable (ADR-007 progressive failure protocol)
+- (+) International accessibility improves
+- (-) More writing effort per document
+- (-) Experts may find some material overly explicit (mitigated by progressive disclosure)
+- (!) Existing documentation does not meet this standard — improvement is incremental, not a rewrite
+
+## References
+
+- Issue #135 — full RFC with application matrix and open questions
+- Roadmap: Documentation and specifications
+- ADR-007 — knowledge acquisition protocol (complements this standard)