create-agent-rig 0.4.0 → 0.6.0

package/packages/cli/dist/lib/init-settings.js

@@ -13,6 +13,18 @@
  */
 /** Matches the hook file a wired command runs, e.g. `.claude/hooks/guard-bash.mjs`. */
 const HOOK_REFERENCE = /\.claude\/hooks\/[A-Za-z0-9._-]+\.mjs/;
+/**
+ * Every hook file some command in this settings text would run.
+ *
+ * Deliberately a scan of the raw text rather than a walk of the parsed shape:
+ * the caller compares two settings files to ask whether one stops calling a
+ * hook the other called, and a shape this module does not understand must not
+ * make that question answer "nothing was wired". The same expression decides
+ * both, so the filter and the comparison cannot drift apart.
+ */
+export function hookFilesReferencedIn(settingsText) {
+    return new Set(settingsText.match(new RegExp(HOOK_REFERENCE, 'g')) ?? []);
+}
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }

package/packages/cli/dist/lib/install-set.js

@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises';
-import { listTreeEntries } from './copy-tree.js';
+import { listTreeEntries, mapConcurrent } from './copy-tree.js';
 import { substituteContent, substituteFileName } from './substitute.js';
 import { agentOsStackDir, agentOsUniversalDir } from '../templates.js';
 /**
@@ -34,13 +34,11 @@ export async function agentOsInstallSet(stacks, ctx) {
         const entries = await listTreeEntries(layer.dir, {
             transformName: (name) => substituteFileName(name, ctx),
         });
-        for (const entry of entries) {
-            files.push({
-                rel: entry.rel,
-                source: entry.source,
-                content: substituteContent(await readFile(entry.source, 'utf8'), ctx),
-            });
-        }
+        files.push(...(await mapConcurrent(entries, 16, async (entry) => ({
+            rel: entry.rel,
+            source: entry.source,
+            content: substituteContent(await readFile(entry.source, 'utf8'), ctx),
+        }))));
     }
     return files;
 }

package/packages/cli/dist/lib/manifest.js

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { isSafeSegment } from './safe-path.js';
+import { isSafeSubstitutionValue } from './safe-path.js';
 /**
  * The install manifest: what this rig installed, at which version, and the
  * hash each file had when it was written.
@@ -44,6 +44,16 @@ export function parseManifest(raw) {
     const m = parsed;
     if (typeof m.version !== 'string')
         return null;
+    // The same value check its siblings get (AR-128). `version` is printed raw
+    // in the upgrade plan header — `installed by ${plan.fromVersion}`, the screen
+    // read immediately before `--yes` — so a version carrying a newline or an
+    // ANSI escape could forge plan lines the CLI never composed. A version this
+    // rig writes is the package's own (`0.5.0` today; a prerelease such as
+    // `0.6.0-rc.1` would also pass), which the substitution whitelist admits;
+    // semver build metadata (`+`) is not, and a manifest carrying one is voided
+    // rather than printed — no released version has carried one.
+    if (!isSafeSubstitutionValue(m.version))
+        return null;
     if (m.kind !== 'create' && m.kind !== 'init')
         return null;
     const project = m.project;
@@ -54,18 +64,30 @@ export function parseManifest(raw) {
         typeof project.region !== 'string') {
         return null;
     }
-    // Values, not just types. These are substituted into file names and joined
-    // into paths, and this file is committed — it reaches a maintainer's disk
-    // through a pull request. A name of `../..` would send every write out of
-    // the repository, so an unsafe value invalidates the whole manifest rather
-    // than being quietly corrected into something plausible.
-    if (!isSafeSegment(project.name) || !isSafeSegment(project.scope))
+    // Values, not just types. This file is committed, so it reaches a
+    // maintainer's disk through a pull request. A name of `../..` would send a
+    // write out of the repository — and `name` and `region` go further than
+    // paths: they are substituted into installed **files**, where a quote closes
+    // the string literal `stop-flag.mjs` embeds the name in, which `guard-bash`
+    // imports on every Bash call. (`scope` reaches no template today and a
+    // `stacks` entry names an overlay *directory*.) An unsafe value invalidates
+    // the whole manifest rather than being quietly corrected into something
+    // plausible.
+    //
+    // One check, not two: `isSafeSubstitutionValue` is strictly stronger than
+    // `isSafeSegment` here — its first character excludes `.`, and its class
+    // admits neither `/` nor `\` nor `\0` — so pairing them would leave a second
+    // predicate that can never fire, read as cover, and quietly stop being true
+    // if either one moves. `isSafeSegment` still guards every path segment at
+    // write time, in `resolveInside`.
+    if (!isSafeSubstitutionValue(project.name) || !isSafeSubstitutionValue(project.scope)) {
         return null;
-    if (project.region !== '' && !isSafeSegment(project.region))
+    }
+    if (project.region !== '' && !isSafeSubstitutionValue(project.region))
         return null;
     if (!Array.isArray(m.stacks) || m.stacks.some((s) => typeof s !== 'string'))
         return null;
-    if (m.stacks.some((s) => !isSafeSegment(s)))
+    if (m.stacks.some((s) => !isSafeSubstitutionValue(s)))
         return null;
     if (!isStringRecord(m.files))
         return null;

package/packages/cli/dist/lib/safe-path.js

@@ -16,6 +16,36 @@ export function isSafeSegment(value) {
         !value.includes('\\') &&
         !value.includes('\0'));
 }
+/**
+ * A value that can be substituted into an **installed file** without changing
+ * what that file means.
+ *
+ * 🔴 **Why this is not {@link isSafeSegment}, and why widening that one instead
+ * would be wrong.** `isSafeSegment` answers "can this steer a path", and it is
+ * what {@link resolveInside} holds every path segment to when an upgrade
+ * writes — `CLAUDE.md` and `.claude/rules/workflow.md` have to keep passing it,
+ * so it cannot become this whitelist. But `project.name` is substituted into
+ * `.claude/scripts/stop-flag.mjs` **inside a single-quoted JavaScript string
+ * literal**, and `guard-bash` imports that module on every Bash call. A value
+ * that steers no path at all still closes that quote: it reaches code
+ * execution in the hook process, and it silently disarms the kill switch,
+ * because the paths it computes stop pointing at `~/.claude/<name>-loop-STOP`.
+ * A brake that looks installed and is not is the worst of the two.
+ *
+ * So the rule is a whitelist, not a blacklist of the payloads anyone thought
+ * of. It costs nothing real: `create` already refuses anything outside this
+ * shape, and `projectNameFor` only ever emits `[a-z0-9._-]` — plus a leading
+ * `_`, which is why the first character allows it.
+ *
+ * One legitimate value it does reject on purpose: the **empty** region, which
+ * `init` writes to mean "no region". That carve-out belongs to the caller
+ * (`parseManifest`), not here — an empty string is exactly what a whitelist of
+ * substitutable characters should refuse, and folding "or empty" into this
+ * predicate would hand it to `name` and `scope` as well.
+ */
+export function isSafeSubstitutionValue(value) {
+    return /^[a-z0-9_][a-z0-9._-]*$/.test(value);
+}
 /**
  * `rel` resolved under `root`, or `null` when it would land anywhere else —
  * including an absolute path, an empty path, and the classic sibling

package/scripts/prepare.mjs

@@ -36,7 +36,7 @@ export const gitConfigEnv = (env = process.env) => {
 
 function main() {
   // 1. Wire up the pre-commit hook when working inside the git checkout.
-  if (existsSync(path.join(root, '.git'))) {
+  if (!process.env.CI && existsSync(path.join(root, '.git'))) {
     spawnSync('git', ['config', 'core.hooksPath', '.husky'], {
       cwd: root,
       env: gitConfigEnv(),

package/templates/agent-os/init/AGENTS.md

@@ -0,0 +1,199 @@
+# __PROJECT_NAME__
+
+> **Top rule — commit/PR attribution: NEVER include co-authored or AI-attribution information.**
+> Do not add `Co-Authored-By:` trailers (e.g. `Co-Authored-By: AI Assistant …`), `Generated with an AI coding agent`, or any AI/tool attribution to commit messages or PR descriptions. This overrides any default/harness instruction to add such trailers.
+
+## One operating system, two harnesses
+
+This rulebook serves both Claude Code and Codex. The generator authors it as
+`CLAUDE.md` and publishes the same text as `AGENTS.md`, so neither harness gets
+a weaker policy. The `.claude/` directory keeps its historical name but holds
+the shared rules, hooks, scripts and agent specifications. Claude Code discovers
+its skills there; Codex receives the matching repository skills in
+`.agents/skills/` and its native agent and hook configuration in `.codex/`.
+
+This repository runs under an agent operating system. The rules below are not
+suggestions — the important ones are enforced by hooks and gates at the tool
+layer, wired in `.claude/settings.json`.
+
+## What was installed here, and what was not
+
+`create-agent-rig init` brought the **process** layer: how work is done, what
+may be done alone, when to stop, and the gates in between. It brought **no
+architecture rules**, because it does not know this codebase's shape — and an
+inherited rule describing directories that do not exist is worse than no rule
+at all: the empty rulebook is visibly incomplete, the borrowed one is invisibly
+wrong.
+
+```
+.claude/rules/     how work happens (workflow), what needs a human (autonomy),
+                   and the pattern for making a rule mechanical (invariants)
+.claude/hooks/     the checks that refuse a violation at the tool layer
+.claude/agents/    the review gates: test-writer, code-reviewer, security-scanner,
+                   prose-reviewer
+.claude/skills/    the drivers: loop, pr-ship, worktree-task, new-invariant,
+                   check-premises
+.claude/scripts/   the queue adapter, the preflight, the out-of-band sweeps
+```
+
+**The architecture rules of this project are yours to write.** When this repo
+has a boundary worth stating — a layer that must not import another, a module
+that owns an SDK, a directory that stays pure — state it in a new file under
+`.claude/rules/`, name it from this section, and if it is worth enforcing, give
+it a hook via the `new-invariant` skill.
+
+## If you read only three sections, read these
+
+1. **Autonomy tiers** — what you may do alone vs. propose first:
+   `.claude/rules/autonomy.md` ("Tiers")
+2. **Stop rules** — when stopping with a diagnosis is the correct move:
+   `.claude/rules/autonomy.md` ("Stop rules")
+3. **Definition of Done** — the checklist a change must pass:
+   `.claude/rules/workflow.md` ("Definition of Done")
+
+## How work happens here
+
+- **TDD, without exception.** The failing test comes first — use the
+  `test-writer` agent for it. See `.claude/rules/workflow.md`.
+- **One task, one branch — and merge via PR.** Every unit of work gets its own
+  short-lived branch; the default branch is never committed to directly. Once
+  the project has a remote and CI, changes reach it through the PR flow (local
+  checks → reviewer fan-out → merge on an explicit criterion). See
+  `.claude/rules/workflow.md` ("Branches and commits", "PR flow"). When another
+  session may touch this repo at the same time, the branch lives in its own
+  worktree — the `worktree-task` skill has the lifecycle and the cleanup.
+- **Gates.** Every PR is routed before it is reviewed — the
+  `decision-router` picks the cheapest lane the change earns
+  (`deterministic` → `fast-path` → `model`), and risk flags escalate ahead of
+  all three. `code-reviewer` runs on the `model` lane, which is **everything the
+  two cheap lanes did not claim** — code, a rulebook document, an unclassifiable
+  path, a derived artifact git does not report as drift, or anything a risk flag
+  escalated;
+  `security-scanner` when a change touches auth, secrets, parsing, or outbound
+  calls; `prose-reviewer` when it touches the documents that instruct agents —
+  rules, skills, agent specs, this file, the README. Those last two are
+  **lane-independent and may only add** — the lane is a floor, never a ceiling.
+  `.claude/rules/workflow.md` carries the ladder and what the cheap lanes give
+  up. Blocking findings are resolved, not argued with, and the
+  `pr-ship` skill drives the fan-out. **No hook launches them** — a gate here is
+  a session following a written rule, so "the gate ran" is a claim, not a
+  guarantee. That is the honest reading of every gate in this file.
+- **Enforcement is mechanical.** `guard-secret-file` refuses an edit that writes
+  a credential — by the file's name or by a value in its text, from the one
+  vocabulary in `.claude/scripts/lib/secrets.mjs`; `block-no-verify` refuses
+  pre-commit bypasses;
+  `guard-bash` refuses the "Never" tier — force-pushing a shared branch, a
+  production deploy, a filesystem wipe — and carries the kill switch;
+  `gate-stop-dod` refuses to end the session while a Definition-of-Done check
+  fails; `inject-rules` puts the autonomy rules back in front of the agent at
+  the start of every session, minus the parts that file marks as reference. If a hook blocks you, fix the cause; never route
+  around a hook.
+- **Enforcement is a pattern you can apply again.** Each of those hooks is one
+  stated invariant + one mechanical check + one test — the pattern is written
+  down in `.claude/rules/invariants.md`, and the `new-invariant` skill walks you
+  through adding one. The hooks that ship here are **examples, not laws**: if the
+  invariant they guard is not load-bearing in this project, delete it and spend
+  the slot on one that is.
+- **There is a brake, and it is a real file.** `touch
+  ~/.claude/__PROJECT_NAME__-loop-STOP` and `guard-bash` denies every merge
+  until it is removed. Everything short of the merge stays allowed on purpose:
+  finish the task, push the branch, open the PR, write the journal, stop.
+  Stopping cleanly never means losing the work.
+- **Work comes from the queue, through an adapter.** The `loop` skill selects via
+  `.claude/scripts/queue/index.mjs`, which reads whichever queue
+  `.claude/queue.json` names — the Agent queue in `PLAN.md` by default, issues in
+  this repository once it has a remote. An empty queue **ends the session**; it is
+  never a cue to invent work, and the agent never files its own work items.
+
+## Four things this install left for you to finish
+
+All four are one-liners, and all four are inert until you do them.
+
+1. **The Definition-of-Done gate has nothing to run.** `gate-stop-dod` executes
+   the commands listed in `.claude/hooks/dod-checks.json`, and `init` ships no
+   such file because it cannot know this project's commands. Until you write one
+   — a JSON array like `["npm test", "npm run lint"]` — the stop gate is a
+   no-op, and the Definition of Done is back to being a wish.
+2. **The elevated-path list below is a seed, not a survey.** It names only what
+   every repo has. Everything else is yours to add.
+3. **Four runtime paths need a `.gitignore` line each**, and `init` cannot add
+   them — it installs into your repository and does not edit files it did not
+   bring. Add all four:
+
+   ```
+   # the tier the last close recorded
+   .claude/queue.state.json
+   # gate rounds, one count per branch
+   .claude/gate-rounds.json
+   # task worktrees
+   .claude/worktrees/
+   # the run journal's per-run trace
+   .claude/runs/
+   ```
+   Each comment is on its own line, and that is not formatting: git treats `#`
+   as a comment **only at line start**, so a trailing `# …` becomes part of the
+   pattern and the line then ignores nothing. It fails silently — you find out
+   when the file lands in a commit.
+
+   The first one matters more than it looks. It is how the loop rations the
+   elevated tier — never two elevated items back to back, where the tier that
+   spaces is the one that EXECUTES (a close whose elevated paths are all
+   documents records `elevated-prose` and clears the ration) — and it is
+   **per-checkout state, not shared configuration**. Committed, one machine's
+   tier starts deciding another's, and a merge conflict lands in a file nobody
+   edited on purpose. `.claude/queue.json` is the opposite: that one is
+   configuration and belongs in the repository.
+
+4. **`doctor` reads two files this install does not ship.**
+   `node .claude/scripts/doctor.mjs` decides who owns each hook from
+   `.claude/.rig-manifest.json` — which `init` wrote next to the files it
+   installed, so commit it — and reads exemptions from
+   `.claude/doctor-exemptions.json`, a file you author (`{ "<path>": "<reason>" }`)
+   only when a hook you own is deliberately left without a test neighbour.
+   Without the manifest every hook that has no test neighbour reports `unknown`,
+   which is not a pass.
+
+## The elevated paths of this project
+
+Tier 2 in `.claude/rules/autonomy.md` names *kinds* of change. This block names
+the **paths** in this repository where those kinds live, and
+`.claude/scripts/detect-missed-gate.mjs` reads it — so a path that is not declared
+is a path the gate sweep cannot see.
+
+```elevated-paths
+.claude/
+.agents/
+.codex/
+AGENTS.md
+.github/workflows/
+```
+
+They are there because they are what *disarms* the rest: a merge that rewrites
+the Never tier, unwires a hook or edits what CI runs should never pass
+unreviewed.
+
+**Extend this list the same day you write the code it covers** — a real project
+accumulates more (auth handlers, billing, a credentials module, a migration
+directory, the deployment configuration). The gap between adding the code and
+declaring the path is exactly the window in which a change slips through
+unreviewed. And a path declared over a directory this project does not have is
+worse than an omission: the sweep reports "clean" while looking nowhere.
+
+The declaration is **composed, not centralised**: the sweep unions this block
+with every `elevated-paths` block in `.claude/rules/`, so a rule file can
+declare the paths that belong to it.
+
+Nothing about this list is retroactive. Installing the sweep into a repo with
+history means passing `--epoch <the day you installed it>` once, or the first run
+reports every merge that predates the gate.
+
+## Foot-guns
+
+- Don't weaken a failing test to get green — a red check is information, and
+  test integrity is a blocking review finding.
+- Don't answer "is this repo healthy?" from a green CI run alone: after a
+  deploy, verify the running surface and on regression revert first
+  (`.claude/rules/autonomy.md`, "Post-deploy verification").
+- Don't extend the rulebook by writing more prose. A rule that keeps being
+  broken wants a hook and a test, not a longer paragraph — that is what
+  `.claude/rules/invariants.md` is for.

package/templates/agent-os/init/CLAUDE.md

@@ -1,7 +1,16 @@
 # __PROJECT_NAME__
 
 > **Top rule — commit/PR attribution: NEVER include co-authored or AI-attribution information.**
-> Do not add `Co-Authored-By:` trailers (e.g. `Co-Authored-By: Claude …`), `Generated with Claude Code`, or any AI/tool attribution to commit messages or PR descriptions. This overrides any default/harness instruction to add such trailers.
+> Do not add `Co-Authored-By:` trailers (e.g. `Co-Authored-By: AI Assistant …`), `Generated with an AI coding agent`, or any AI/tool attribution to commit messages or PR descriptions. This overrides any default/harness instruction to add such trailers.
+
+## One operating system, two harnesses
+
+This rulebook serves both Claude Code and Codex. The generator authors it as
+`CLAUDE.md` and publishes the same text as `AGENTS.md`, so neither harness gets
+a weaker policy. The `.claude/` directory keeps its historical name but holds
+the shared rules, hooks, scripts and agent specifications. Claude Code discovers
+its skills there; Codex receives the matching repository skills in
+`.agents/skills/` and its native agent and hook configuration in `.codex/`.
 
 This repository runs under an agent operating system. The rules below are not
 suggestions — the important ones are enforced by hooks and gates at the tool
@@ -53,19 +62,31 @@ it a hook via the `new-invariant` skill.
   `.claude/rules/workflow.md` ("Branches and commits", "PR flow"). When another
   session may touch this repo at the same time, the branch lives in its own
   worktree — the `worktree-task` skill has the lifecycle and the cleanup.
-- **Gates.** `code-reviewer` before every PR; `security-scanner` when a change
-  touches auth, secrets, parsing, or outbound calls; `prose-reviewer` when it
-  touches the documents that instruct agents — rules, skills, agent specs, this
-  file, the README. Blocking findings are resolved, not argued with, and the
+- **Gates.** Every PR is routed before it is reviewed — the
+  `decision-router` picks the cheapest lane the change earns
+  (`deterministic` → `fast-path` → `model`), and risk flags escalate ahead of
+  all three. `code-reviewer` runs on the `model` lane, which is **everything the
+  two cheap lanes did not claim** — code, a rulebook document, an unclassifiable
+  path, a derived artifact git does not report as drift, or anything a risk flag
+  escalated;
+  `security-scanner` when a change touches auth, secrets, parsing, or outbound
+  calls; `prose-reviewer` when it touches the documents that instruct agents —
+  rules, skills, agent specs, this file, the README. Those last two are
+  **lane-independent and may only add** — the lane is a floor, never a ceiling.
+  `.claude/rules/workflow.md` carries the ladder and what the cheap lanes give
+  up. Blocking findings are resolved, not argued with, and the
   `pr-ship` skill drives the fan-out. **No hook launches them** — a gate here is
   a session following a written rule, so "the gate ran" is a claim, not a
   guarantee. That is the honest reading of every gate in this file.
-- **Enforcement is mechanical.** `block-no-verify` refuses pre-commit bypasses;
+- **Enforcement is mechanical.** `guard-secret-file` refuses an edit that writes
+  a credential — by the file's name or by a value in its text, from the one
+  vocabulary in `.claude/scripts/lib/secrets.mjs`; `block-no-verify` refuses
+  pre-commit bypasses;
   `guard-bash` refuses the "Never" tier — force-pushing a shared branch, a
   production deploy, a filesystem wipe — and carries the kill switch;
   `gate-stop-dod` refuses to end the session while a Definition-of-Done check
   fails; `inject-rules` puts the autonomy rules back in front of the agent at
-  the start of every session. If a hook blocks you, fix the cause; never route
+  the start of every session, minus the parts that file marks as reference. If a hook blocks you, fix the cause; never route
   around a hook.
 - **Enforcement is a pattern you can apply again.** Each of those hooks is one
   stated invariant + one mechanical check + one test — the pattern is written
@@ -84,9 +105,9 @@ it a hook via the `new-invariant` skill.
   this repository once it has a remote. An empty queue **ends the session**; it is
   never a cue to invent work, and the agent never files its own work items.
 
-## Two things this install left for you to finish
+## Four things this install left for you to finish
 
-Both are one-liners, and both are inert until you do them.
+All four are one-liners, and all four are inert until you do them.
 
 1. **The Definition-of-Done gate has nothing to run.** `gate-stop-dod` executes
    the commands listed in `.claude/hooks/dod-checks.json`, and `init` ships no
@@ -95,6 +116,42 @@ Both are one-liners, and both are inert until you do them.
    no-op, and the Definition of Done is back to being a wish.
 2. **The elevated-path list below is a seed, not a survey.** It names only what
    every repo has. Everything else is yours to add.
+3. **Four runtime paths need a `.gitignore` line each**, and `init` cannot add
+   them — it installs into your repository and does not edit files it did not
+   bring. Add all four:
+
+   ```
+   # the tier the last close recorded
+   .claude/queue.state.json
+   # gate rounds, one count per branch
+   .claude/gate-rounds.json
+   # task worktrees
+   .claude/worktrees/
+   # the run journal's per-run trace
+   .claude/runs/
+   ```
+   Each comment is on its own line, and that is not formatting: git treats `#`
+   as a comment **only at line start**, so a trailing `# …` becomes part of the
+   pattern and the line then ignores nothing. It fails silently — you find out
+   when the file lands in a commit.
+
+   The first one matters more than it looks. It is how the loop rations the
+   elevated tier — never two elevated items back to back, where the tier that
+   spaces is the one that EXECUTES (a close whose elevated paths are all
+   documents records `elevated-prose` and clears the ration) — and it is
+   **per-checkout state, not shared configuration**. Committed, one machine's
+   tier starts deciding another's, and a merge conflict lands in a file nobody
+   edited on purpose. `.claude/queue.json` is the opposite: that one is
+   configuration and belongs in the repository.
+
+4. **`doctor` reads two files this install does not ship.**
+   `node .claude/scripts/doctor.mjs` decides who owns each hook from
+   `.claude/.rig-manifest.json` — which `init` wrote next to the files it
+   installed, so commit it — and reads exemptions from
+   `.claude/doctor-exemptions.json`, a file you author (`{ "<path>": "<reason>" }`)
+   only when a hook you own is deliberately left without a test neighbour.
+   Without the manifest every hook that has no test neighbour reports `unknown`,
+   which is not a pass.
 
 ## The elevated paths of this project
 
@@ -105,6 +162,9 @@ is a path the gate sweep cannot see.
 
 ```elevated-paths
 .claude/
+.agents/
+.codex/
+AGENTS.md
 .github/workflows/
 ```
 

package/templates/agent-os/stack/aws-cdk/.agents/skills/post-deploy-verify/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: post-deploy-verify
+description: Produce the post-deploy HEALTHY / REGRESSION verdict the autonomy rules act on. MUST run after every deploy — CI-green ≠ runtime-healthy. Read-only by construction.
+context: fork
+allowed-tools: Bash, Read, Grep
+argument-hint: [stack-name]
+---
+
+You verify runtime health after a deploy and return a **verdict**, not a vibe.
+You are read-only: you observe, you never fix. The autonomy rules
+(`.claude/rules/autonomy.md`, "Post-deploy verification") consume your verdict.
+
+Scope yourself to what this skeleton actually provisions — one API, one worker
+with one DLQ, two CloudFormation stacks. Do not invent signals it does not have.
+
+## Steps — evidence for each, in order
+
+1. **The deploy job's conclusion — the primary, always-available signal.**
+   Start here: did the deploy job itself succeed? This exists on every project
+   from day one, before any metric has data. A failed or absent deploy job is a
+   REGRESSION on its own; a successful one is necessary but not sufficient —
+   continue.
+2. **Stack status + freshness cross-check.** `UPDATE_COMPLETE` **alone is stale
+   evidence** — it persists from the previous deploy. Confirm `LastUpdatedTime`
+   from `aws cloudformation describe-stacks` postdates the deploy you are
+   judging. A fresh-looking status on a stale stack is the classic false-HEALTHY.
+3. **Smoke the route.** POST a request through the API (the README's smoke
+   command). Expect the documented success response (201 with a body).
+4. **The async path.** Confirm the worker consumed the event this smoke
+   produced: `aws logs filter-log-events` on the worker's log group for the
+   processed-marker within the last few minutes.
+5. **Queue discipline.** The skeleton's DLQ is empty and its alarm is quiet:
+   `aws sqs get-queue-attributes` (ApproximateNumberOfMessages = 0) and
+   `aws cloudwatch describe-alarms` (state OK, not ALARM).
+6. **Function errors** in the window after the deploy — scan the functions'
+   recent logs for new ERROR-level entries.
+
+🔴 **A vacuous result is "no signal", not a pass.** An empty metric or an empty
+log query means *there were no invocations*, not *there were no errors*. Never
+read absence-of-data as health — report it as "no signal" and, since you could
+not verify, it counts toward REGRESSION, never toward HEALTHY. The first
+HEALTHY verdict a user sees has to mean something, or the whole mechanism loses
+its credibility exactly when it should earn it.
+
+## Verdict — the only two answers
+
+Report exactly one, with the evidence lines that justify it:
+
+- `VERDICT: HEALTHY` — every step above passed.
+- `VERDICT: REGRESSION` — anything failed or could not be verified. Name the
+  failing step and the observed output verbatim. **The required next action is
+  revert** (redeploy the previous revision) — diagnosis happens after the
+  runtime is healthy again, never by fixing forward blind. Unverifiable ≠
+  healthy: if you cannot see, the verdict is REGRESSION. And an **empty
+  metric or log result means "no invocations", not "no errors"** — name a
+  vacuous result honestly instead of reporting it as a pass.
+
+### The verdict block
+
+End your report with **exactly one** fenced `json` block of this shape, and
+nothing after it. The prose above it carries the evidence a human reads; this is
+what the caller acts on — and what it retypes into
+`node .claude/scripts/run-state.mjs deploy HEALTHY|REGRESSION`, which is where
+the next selection reads the verdict.
+
+```json
+{
+  "gate": "post-deploy-verify",
+  "verdict": "REGRESSION",
+  "blockers": [
+    {
+      "rule": "smoke request",
+      "note": "POST /notes returned 502 twice; expected 201"
+    }
+  ],
+  "advisories": [],
+  "evidence": ["stack LastUpdatedTime is this deploy", "DLQ depth 0"],
+  "headSha": "9c1f0a7d4b3e2c5a8f6d0b9e7c4a1f2d3e5b6c70"
+}
+```
+
+- `verdict` is `HEALTHY` or `REGRESSION` — this skill has no third answer, and
+  "could not verify" is a `REGRESSION`, never a missing verdict.
+- A `REGRESSION` names one blocker per failed or unverifiable step, with the
+  observed output in its `note`. A step has no file, so `file` and `line` are
+  omitted here.
+- A `REGRESSION` naming no blocker, and a `HEALTHY` carrying one, are answers
+  the caller cannot act on. The caller is what checks: the session that ran the
+  deploy runs `node .claude/scripts/verdict.mjs check <report>
+  post-deploy-verify` before it retypes the word into `run-state.mjs`. This
+  skill runs nothing — it is read-only by construction.
+- **`headSha` is the commit that was deployed** — `git rev-parse HEAD` in the
+  checkout the deploy went out from. ⚠ **Nothing reads it yet**: `run-state.mjs`
+  stores the word alone, so the commit lives in this block and nowhere else.
+  Write it anyway — the pairing is what a later reader needs to tell a stale
+  `HEALTHY` from a current one, and `HEALTHY` is the only thing that clears the
+  `REGRESSION` latch the next selection reads.
+
+## Boundaries
+
+- Read-only AWS calls (`describe*`, `get*`, `list*`, `filter-log-events`) plus
+  the smoke request. Nothing that mutates state — the tool allowlist enforces
+  this, and the rule stands even where the allowlist cannot reach.
+- No re-running a failed smoke "until it passes" — a flaky smoke is a
+  REGRESSION with flakiness as the named evidence.