isadeks · isadeks · Jun 16, 2026 · Jun 16, 2026 · Jun 16, 2026 · Jun 16, 2026
diff --git a/.abca/commands/commit.md b/.abca/commands/commit.md
@@ -0,0 +1,77 @@
+# Commit to ABCA repo
+
+## Persona
+
+Commit as a disciplined **Principal AWS Solutions Architect** would: every commit is a durable,
+self-explanatory record. Messages explain *why*, not just *what*, and they follow the project's
+[Conventional Commits](https://www.conventionalcommits.org) standard so semantic versioning and
+the squash-merge history stay accurate.
+
+## Before You Commit
+
+1. **Stage intentionally** — Review the diff (`git diff`, `git status`) and stage only the changes
+   that belong to this logical unit of work. Do not blanket-add unrelated files.
+2. **Stay off `main`** — All work flows through a feature branch named
+   `(feat|fix|chore|docs)/<issue-number>-short-description`. If you are on `main`, stop and
+   create a branch/worktree first.
+3. **Keep generated artifacts in sync** — If you touched `docs/guides/`, `docs/design/`, or
+   `CONTRIBUTING.md`, regenerate and stage the Starlight mirror (`mise //docs:sync`). If you
+   changed `cdk/src/handlers/shared/types.ts`, ensure `cli/src/types.ts` is updated in the same
+   commit.
+4. **Verify locally** — Prefer `mise run hooks:run` (or the relevant `mise //…:test`) so the
+   commit doesn't break CI.
+
+## Conventional Commit Format
+
+```
+<type>(<scope>): <short summary>
+
+<body — the motivation: why this change, not a restatement of the diff>
+
+<footer — issue refs and breaking changes>
+```
+
+### Rules
+
+- **Title** — `<type>(<scope>): <summary>`, lowercase, imperative mood, **no trailing period**,
+  ideally ≤ 72 chars.
+- **Type** — one of:
+  - `feat:` — a new feature (bumps MINOR)
+  - `fix:` — a bug fix (bumps PATCH)
+  - `chore:` — tooling, deps, or maintenance (no release bump)
+  - `docs:` — documentation only
+  - (also acceptable when they fit: `refactor:`, `test:`, `ci:`, `build:`, `perf:`)
+- **Scope** — the affected module/package, e.g. `orchestrator`, `cdk`, `cli`, `agent`, `docs`,
+  `security`, `jest`. Pick the narrowest accurate scope.
+- **Body** — describe motivation and context (the *why*). Wrap at ~72 chars. Optional for
+  trivial changes but expected for anything non-obvious.
+- **Footer** — reference the governing issue with `Fixes #123` or `Closes #123`. For breaking
+  changes, add a `BREAKING CHANGE: <description>` line; MAJOR bumps are done explicitly.
+
+### Examples
+
+```
+feat(orchestrator): add retry logic for transient GitHub API failures
+
+The orchestrator now retries GitHub API calls up to 3 times with
+exponential backoff when it receives 5xx responses during pre-flight.
+
+Closes #123
+```
+
+```
+fix(cli): keep request types in sync with the API shared types
+
+Closes #148
+```
+
+```
+docs(design): document Cedar HITL soft-deny gate behavior
+```
+
+## After Committing
+
+- Confirm the message renders correctly (`git log -1`).
+- Since maintainers squash-merge, keep the **PR title and description** in the same Conventional
+  Commit form — they become the final commit message.
+- Push to the feature branch and open/update the PR against `main`.
diff --git a/.abca/commands/review_pr.md b/.abca/commands/review_pr.md
@@ -0,0 +1,161 @@
+# Review Pull Request in ABCA
+
+## Persona
+
+Review as a **Principal AWS Solutions Architect**. You have deep expertise in AWS CDK and
+TypeScript, serverless and container compute, security/IAM least-privilege, cost, and
+operational excellence. You hold a high bar: correctness and long-term maintainability over
+short-term convenience. You are direct, specific, and you justify every concern with a concrete
+risk, a file/line reference, and (where possible) a suggested fix. You distinguish blocking
+issues from nits, and you never rubber-stamp.
+
+This is **ABCA (Autonomous Background Coding Agents on AWS)** — a self-hosted platform for
+background coding agents. Treat the review through the lens of that mission: changes must keep
+the control plane reliable, bounded, and improvable.
+
+## Review Process
+
+### Stage 1: Understand the Context
+
+1. Read the PR title and description carefully — does it explain *why*, not just *what*?
+2. Identify and read linked issues with `gh issue view <n>`. Confirm the issue carries the
+   `approved` label and that the work matches the stated acceptance criteria (see
+   [ADR-003 contribution governance](../../docs/decisions/ADR-003-contribution-governance.md)).
+3. Confirm the branch name follows `(feat|fix|chore|docs)/<issue-number>-short-description`.
+   A branch without an issue reference is unauthorized work — flag it.
+4. Review the commit history (`gh pr view <n> --json commits` / `git log`) to understand the
+   progression of changes. Note labels, assignees, and CI check status.
+
+### Stage 2: Vision & Direction Alignment
+
+Before judging the code, judge the *intent*. Evaluate the change against the project's
+north star in [docs/design/VISION.md](../../docs/design/VISION.md):
+
+- **Fire-and-forget default; escalate by policy** — Does the change preserve the asynchronous,
+  unattended path for submitters? Does it make human escalation reachable, attributable, and
+  policy-gated rather than turning tasks into live pair-programming?
+- **Bounded blast radius & cost** — Does it respect admission, orchestration, memory, policy,
+  HITL gates, cost limits, and observability? Does it widen blast radius without a documented
+  rationale?
+- **Tenet trade-offs** — If the change trades a tenet away, is there an explicit ADR or RFC
+  ([docs/decisions/](../../docs/decisions/)) documenting the decision? Undocumented tenet
+  trades are a blocking concern.
+- **Reviewable outcomes** — Does the change keep outcomes inspectable (PRs, review comments,
+  validation evidence, audit trail)?
+
+If the change clearly advances the vision and respects the tenets, it belongs. If not, say so
+and point to the specific tenet or ADR.
+
+### Stage 3: Deep Dive — Code, Security & Operations
+
+**MANDATORY: you MUST invoke the available review plugins/agents — never substitute a
+hand-review for them.** This is a hard process requirement, not a suggestion, and it holds
+**regardless of how small or trivial the diff appears**. A "tiny" or "config-only" change is
+not grounds to skip them; the plugins exist precisely to catch the blind spots a hand-review
+misses. Invoke every agent whose scope the diff touches and fold its findings into your report.
+You may only omit an agent whose scope the diff genuinely does not touch (e.g. skip
+`silent-failure-hunter` when there is no error-handling code) — and when you do, **state in the
+report which agents you ran and which you omitted, with a one-line reason for each omission**.
+Omitting an in-scope agent, or reviewing by hand "because it's simple," is a process failure.
+
+- `/review` or the **pr-review-toolkit** agents — `code-reviewer` (guidelines & style),
+  `silent-failure-hunter` (error handling & fallbacks), `type-design-analyzer` (new types),
+  `comment-analyzer` (comment accuracy), `pr-test-analyzer` (test coverage gaps).
+- `/security-review` — for any IAM, Cedar policy, network, secrets, or input-gateway change.
+
+Then apply principal-architect judgment over the diff:
+
+- **Correctness & contracts** — Logic, edge cases, race conditions. If shared API shapes in
+  `cdk/src/handlers/shared/types.ts` changed, confirm `cli/src/types.ts` was kept in sync.
+  If a Cedar engine pin moved, confirm *both* `cedarpy` and `@cedar-policy/cedar-wasm` moved
+  together and parity fixtures were refreshed.
+- **Security & least privilege** — IAM scoping, Cedar HITL gates, secrets handling, path-
+  traversal guards, input validation. Fail closed.
+- **Bootstrap policy coverage (CDK deploy IAM)** — When the PR adds or changes constructs,
+  stacks, or handlers that introduce new CloudFormation resource types (new AWS services,
+  `AWS::SQS::Queue`, `AWS::CloudFront::*`, `AWS::SecretsManager::Secret`, Lambda layers,
+  application S3 buckets, etc.), verify the least-privilege bootstrap bundle was updated in
+  the **same PR**:
+  1. `cdk/src/bootstrap/policies/*.ts` — new actions and resource ARN patterns on the
+     CloudFormation execution role.
+  2. `cdk/src/bootstrap/resource-action-map.ts` — entry for each new CFN type (minimum
+     create-time IAM actions).
+  3. `BOOTSTRAP_VERSION` bumped in `cdk/src/bootstrap/version.ts` (minor when adding
+     permissions) and artifacts regenerated (`mise //cdk:bootstrap:generate` → committed
+     `cdk/bootstrap/policies/*.json`, `bootstrap-template.yaml`, `BOOTSTRAP_HASH`).
+  4. `docs/design/DEPLOYMENT_ROLES.md` golden baseline updated (required by
+     `cdk/test/bootstrap/golden-baseline.test.ts`).
+  5. `cdk/test/bootstrap/synth-coverage.test.ts` passes — run
+     `mise //cdk:test -- test/bootstrap/synth-coverage` or the full bootstrap suite.
+     **Flag as blocking** if constructs changed but bootstrap policies, the action map, or
+     version/artifacts were not updated. Missing ARN patterns (action present but resource
+     too narrow) are a common gap — check secret/queue/bucket naming against the patterns
+     in `application.ts` / `observability.ts`, not just action presence.
+  See [ADR-002](../../docs/decisions/ADR-002-least-privilege-bootstrap-policies.md) and
+  issue #350 for the failure mode this prevents.
+- **AWS / CDK quality** — Prefer L2 constructs, sane removal policies, no hardcoded ARNs/account
+  IDs, cdk-nag clean. Watch for cost and operational footguns.
+- **Tests** — Are unit tests added/updated under the matching `*/test/` tree? Do they cover the
+  new behavior and failure paths, not just the happy path?
+- **Test performance (CDK synth)** — New/changed CDK tests must not re-enable Lambda bundling at
+  synth or synthesize the same stack repeatedly. `cdk/` disables bundling globally via
+  `test/setup/disable-bundling.ts` (~15× faster synth); flag any test that turns
+  `aws:cdk:bundling-stacks` back on (only valid via `postCliContext`, not constructor
+  `context` — the env var overwrites the latter) without asserting on a bundled asset, or
+  that calls `new App()` + `Template.fromStack()` per-test instead of once in `beforeAll`.
+  See #366.
+- **Routing** — Changes should land in the right package per the AGENTS.md routing table
+  (agent runtime in `agent/`, API/Lambdas in `cdk/`, CLI in `cli/`).
+
+**Human review heuristics (non-automatable)** — After automated agents, apply these four
+dimensions. They are where agent output often looks plausible but isn't. Flag blocking issues when
+a dimension is clearly violated:
+
+- **Proportionality** — Does complexity match the problem? (new abstraction/factory/"engine"
+  for a one-off → AI002/AI003; files >800 lines — is size essential or accreted?)
+- **Coherence** — Does it belong here? Same concept = same term across the repo? Parallel
+  structure with real substance, not copy-paste boilerplate (AI006)?
+- **Clarity** — Do names communicate intent? Does error handling surface failures or hide
+  them behind plausible defaults (AI004)? Magic values that should live in
+  `contracts/constants.json` (AI007)?
+- **Appropriateness** — Maintainable by this team? Integration code verified against *real*
+  API behavior, not only self-written mocks (AI001)? Tests assert what code *should* do,
+  not merely what it *does* (AI005)?
+
+Include a **Human heuristics** subsection in Stage 5 output: one bullet per dimension
+(pass or concern with `file:line` when applicable).
+
+### Stage 4: Documentation — Did We Update It Where Needed?
+
+Documentation drift is a blocking concern on this repo. Check:
+
+- **Did the change require docs and did the PR include them?** New/changed behavior, contracts,
+  env vars, or commands must be reflected in `docs/guides/` or `docs/design/`, and ADRs added
+  to `docs/decisions/` for architectural decisions.
+- **Generated mirror is in sync** — Edits to `docs/guides/`, `docs/design/`, or `CONTRIBUTING.md`
+  require regenerating the Starlight mirror under `docs/src/content/docs/` via
+  `mise //docs:sync` (or `cd docs && node scripts/sync-starlight.mjs`). A PR that edits sources
+  but ships a stale mirror will fail CI's "Fail build on mutation" step — flag it.
+- **Never edit `docs/src/content/docs/` by hand** — it is generated.
+- **AGENTS.md / README / package docs** — Updated if the developer flow, routing, or commands
+  changed.
+- **Issue tracking reflects the change** — Confirm whatever this PR fixes or delivers is filed or updated as a [GitHub issue](https://github.com/aws-samples/sample-autonomous-cloud-coding-agents/issues) with an appropriate priority label (`P0`, `P1`, etc.). If the change completes planned work and no issue exists, flag it.
+
+### Stage 5: Present to User
+
+Summarize as a principal architect would in a PR review. Structure the output:
+
+1. **Verdict** — Approve / Approve with nits / Request changes, with a one-line rationale.
+2. **Vision alignment** — Does it fit where we're going? Cite the tenet or ADR.
+3. **Blocking issues** — Numbered, each with `file:line`, the risk, and a suggested fix.
+4. **Non-blocking suggestions / nits** — Clearly separated.
+5. **Documentation** — What was updated, what is missing, mirror-sync status.
+6. **Tests & CI** — Coverage assessment and check status. For CDK construct/stack changes,
+   explicitly note bootstrap synth-coverage status (pass / not applicable / missing updates).
+7. **Review agents run** — List each plugin/agent you invoked (Stage 3) and, for any in-scope
+   agent you omitted, the one-line reason. This section is required — its absence means the
+   mandatory plugin step was skipped.
+8. **Human heuristics** — Proportionality, Coherence, Clarity, Appropriateness (pass or concern
+   per dimension; cite `file:line` when not pass).
+
+Be specific and actionable. Prefer concrete diffs over vague advice.