create-agent-rig 0.9.1 → 0.10.1

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

@@ -1,201 +0,0 @@
-# __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. **Five 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. If any are missing, add only the missing entries:
-
-   ```
-   # the tier the last close recorded
-   .claude/queue.state.json
-   # the board this checkout runs on, when the config declares several
-   .claude/queue.board
-   # 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,201 +0,0 @@
-# __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. **Five 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. If any are missing, add only the missing entries:
-
-   ```
-   # the tier the last close recorded
-   .claude/queue.state.json
-   # the board this checkout runs on, when the config declares several
-   .claude/queue.board
-   # 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/stack/aws-cdk/.agents/skills/post-deploy-verify/SKILL.md

@@ -1,105 +0,0 @@
----
-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.

package/templates/agent-os/stack/aws-cdk/.agents/skills/ro-debug/SKILL.md

@@ -1,117 +0,0 @@
----
-name: ro-debug
-description: Investigate the deployed runtime read-only — Lambda logs and error rates, DLQ depth and message age, table reads — with the traps that have produced confidently-wrong diagnoses before. Use when something on the deployed stage misbehaves, and before writing any fix.
-allowed-tools: Bash, Read, Grep
----
-
-# Read-only runtime investigation
-
-A fix is always a code change through a PR. This skill only **looks** — and it is
-scoped read-only so that a session diagnosing an incident cannot become a session
-mutating production state under pressure, which is when that decision is worst.
-
-## The role this assumes, and the honest caveat
-
-Every command below wants a **read-only profile**: permission to read logs,
-metrics, queue attributes and table items, and nothing else. No decrypt, no
-secret reads, no mutations — so a credential cannot leak through this path even
-by accident.
-
-⚠ **The skeleton does not provision that role.** It ships the application, not
-your account's access model, and minting a role is an **owner action** (a Tier-2
-decision — it is IAM). Until it exists, either create it once with those four
-read scopes, or accept that you are investigating with wider credentials than the
-task needs and say so in the write-up. Do not silently upgrade to an admin
-profile and carry on.
-
-```sh
-export AWS_PROFILE=<your read-only profile>
-export AWS_REGION=__REGION__
-```
-
-## Before reading ANY code to explain a runtime behaviour
-
-```sh
-git fetch origin && git rev-parse HEAD "origin/$(git symbolic-ref --short HEAD)"
-```
-
-**If the local branch differs from its remote, diagnose from the remote**
-(`git show origin/<branch>:<file>`, or a worktree). **A fetch does not move your
-checkout** — reading stale local code while describing deployed behaviour is
-the single most reliable way to produce a confident, wrong diagnosis, and it has
-happened more than once. See `.claude/rules/autonomy.md`, "Session staleness".
-
-## Recipes
-
-**Find the function first** — CDK generates the physical names, so never guess one:
-
-```sh
-aws lambda list-functions \
-  --query "Functions[?contains(FunctionName,'Notes')].FunctionName" --output text
-```
-
-**Errors in a window:**
-
-```sh
-aws logs filter-log-events --log-group-name "/aws/lambda/<fn>" \
-  --start-time <epoch-ms> --filter-pattern "ERROR" \
-  --max-items 20 --query 'events[].message' --output text
-```
-
-**DLQ depth, then message age.** Depth comes from the queue; **age does not** —
-`ApproximateAgeOfOldestMessage` is a **CloudWatch metric, not an SQS attribute**,
-and asking for it as an attribute fails with `InvalidAttributeName`:
-
-```sh
-aws sqs get-queue-attributes --queue-url <notes-dlq-url> \
-  --attribute-names ApproximateNumberOfMessages
-
-aws cloudwatch get-metric-statistics --namespace AWS/SQS \
-  --metric-name ApproximateAgeOfOldestMessage \
-  --dimensions Name=QueueName,Value=<notes-dlq-name> \
-  --start-time <iso> --end-time <iso> --period 300 --statistics Maximum
-```
-
-Age is what tells you whether a non-empty DLQ **predates** the thing you are
-investigating. A days-old backlog is not your regression, and treating it as one
-sends the whole diagnosis in the wrong direction.
-
-**Table reads** — key by whatever `packages/db` composes; nothing else knows the
-key shape:
-
-```sh
-aws dynamodb query --table-name <NotesTable output> \
-  --key-condition-expression "pk = :pk" \
-  --expression-attribute-values '{":pk":{"S":"NOTE#<id>"}}' --max-items 3
-```
-
-**Error rate:** `AWS/Lambda` `Errors`, `Sum`, by `FunctionName`, over the suspect
-window.
-
-## Interpretation rules — where wrong diagnoses actually come from
-
-- 🔴 **An empty metric result is "no signal", never "healthy".** Zero datapoints
-  means **no invocations in the window** — the function was not exercised, so the
-  metric says nothing about whether it works. Report it as no signal and go find
-  a window with traffic. This is the same rule the `post-deploy-verify` skill
-  states, and for the same reason: a vacuous pass is worse than a missing one,
-  because it gets believed.
-- 🔴 **`StackStatus: UPDATE_COMPLETE` is stale evidence.** It persists from the
-  previous deploy, so it is true of a stack whose latest deploy failed. The
-  authoritative signals are the **deploy job's conclusion**
-  (`gh run list --workflow deploy`) and the stack's `LastUpdatedTime` freshness.
-- **DNS and asset-upload failures are infrastructure flakes, not code
-  regressions.** A deploy that died at asset publish or checkout tells you nothing
-  about the change. Your own read-only calls can hit the same flake — a failed
-  probe is `unknown`, not a finding.
-- **Never work around the profile's denials — that is the point of the profile.**
-  Needing a decrypt, a secret or a mutation means the investigation has reached
-  its boundary: escalate to the human with what you found
-  (`.claude/rules/autonomy.md`, "Escalation format").
-
-## What to hand back
-
-What was observed (verbatim, not summarised), which window, which signals were
-**unavailable** and why, the current hypothesis, and the narrowest reproduction.
-A read-only investigation that ends in a named uncertainty is a good outcome; one
-that ends in a confident story built on a stale read is not.