create-agent-rig 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,134 @@
+# Changelog
+
+Notable changes per release. The generated projects are the product, so an entry
+says what a **newly scaffolded project** gains or loses — not what moved inside
+the generator.
+
+Versions are published to npm as [`create-agent-rig`](https://www.npmjs.com/package/create-agent-rig);
+`npx github:serhii-baksheiev/create-agent-rig` keeps working for either path.
+
+## 0.3.0
+
+The factory extraction: a scaffolded project now arrives with a working
+autonomous loop and the mechanisms that watch it, rather than an empty `.claude/`.
+
+### Added
+
+- **`guard-bash` hook** — the "Never" tier made mechanical: force-pushing or
+  deleting a shared branch, a direct push to the default branch, a production
+  deploy trigger, a catastrophic delete. It **parses** the command (quotes
+  honoured) instead of pattern-matching, so a commit message that mentions a
+  forbidden flag is prose, not a bypass.
+- **A kill switch that is a real file.** `touch ~/.claude/<project>-loop-STOP`
+  and no merge lands until it is removed. Everything short of the merge stays
+  allowed on purpose — stopping cleanly must not mean losing work.
+- **The queue seam.** `loop` no longer reads one tracker: selection goes through
+  `.claude/scripts/queue/`, with a pure core (filters, blocker resolution, tier
+  ration, sort, stop conditions) and three adapters — `plan-md` (the default; the
+  only one that works before a project has a remote), `github-issues`, `jira`.
+- **Two sweeps that run outside any session** — `detect-missed-gate` finds merges
+  that crossed an elevated path with no recorded reviewer verdict;
+  `reconcile-external-prs` accounts for work that reached the default branch
+  outside the queue. Both exist because a run cannot report its own missed gate.
+- **`preflight`** — the pre-run checks, which also print the items it did _not_
+  check, every time.
+- **Skills** — `worktree-task` (isolation when a second session may run) and
+  `new-invariant` (a generator for the invariant→hook→test pattern, with a
+  working example and its test).
+- **`rules/invariants.md`** — the pattern behind every hook here, stated once, so
+  the hooks read as examples rather than as laws.
+- **`aws-cdk` target extras** — the `ro-debug` skill (read-only runtime
+  investigation, with the traps that produce confident wrong diagnoses) and the
+  transferable AWS rules.
+- **`elevated-paths`** — a declaration in `CLAUDE.md`, composed with any block in
+  `.claude/rules/`, naming the paths where Tier-2 changes live.
+
+### Changed
+
+- The governance summary counts `.mjs` hooks only — a config file listed as an
+  enforced hook overstated the one number this tool exists to make credible.
+- `autonomy.md`: the tier is decided by what a change **touches**, not by what
+  the task predicted it would touch.
+
+### Fixed
+
+Four review rounds, ten reviewers, on this release's own code. What they caught,
+each reproduced before the fix and re-verified after:
+
+- a PR body could **forge its own reviewer verdict** and suppress the gate sweep
+  — the body is written by the actor being audited, so only the `human-review`
+  label (which needs repository permission) suppresses now;
+- the `plan-md` adapter's close **deleted the wrong line**, destroying a human's
+  Operator-queue entry and leaving the shipped item selectable;
+- every `github-issues` write **threw on success** (those `gh` subcommands print
+  text, not JSON) — `escalate` posted its diagnosis and then died before applying
+  the label that stops the item being re-picked;
+- the kill switch could be **disarmed by an env variable**, and was fixed in the
+  hook while the identical hole sat in `preflight` — the brake now has one
+  implementation;
+- three **total bypasses** in the guard, each an exception inside its own work
+  that the fail-open catch turned into "allow": an unbounded spread, a recursive
+  brace expansion, and a quadratic path collapse;
+- a heredoc pre-pass that could **hide any command** from every rule;
+- a ReDoS in the blocker parser reachable by anyone able to open an issue.
+
+Rounds 4 and 5, on the fixes themselves:
+
+- a here-string (`cat <<<X`) and an arithmetic left shift (`$((1<<n))`) were each
+  read as heredoc markers, **hiding every command up to the next matching line**;
+- `git commit -nm "msg"` bypassed the pre-commit gate outright — the one thing
+  that hook exists to stop, in the spelling people actually type;
+- with the kill switch armed, `git merge feat/x && git push` still landed a merge
+  on the default branch; a push must now name its ref while stopped;
+- pointing `HOME` at an empty directory disarmed the brake; it is now found
+  through the password database as well as the environment;
+- `gh --json files` truncates at 100 with **no marker**, and the gate sweep read
+  the short list as "touched nothing elevated" — a PR padded past 100 files hid
+  its elevated change. The sweep now compares against `changedFiles`;
+- declaring `.claude/` elevated was a no-op, because every `.md` under it counted
+  as inert — so a merge rewriting the autonomy tiers passed the gate meant to
+  catch exactly that;
+- a quadratic reviewer-name regex cost ~4 s per crafted PR body, minutes across a
+  sweep that reports nothing when killed.
+
+The README's enforcement claims were overstated and are now scoped to what the
+guard actually inspects, with the omissions listed in the hook itself: only `rm`
+for deletes, only a workflow dispatch for deploys, only a push that names its
+branch, and nothing carried as a flag value.
+
+The lesson that generalises is now a rule (`invariants.md`): **a guard that fails
+open must do provably bounded work**, because fail-open makes every line of work
+a potential total bypass — and prefer deleting a rule to adding one.
+
+## 0.2.0
+
+Distribution hardening (file modes, the `gitignore`→`.gitignore` trick, a
+pack-path e2e per target), agent-os v2 (`pr-ship`, `post-deploy-verify`,
+`cdk-diff-reviewer`, review-context isolation, session staleness), the `apps/web`
+frontend proving core purity across the wire, the `gate-stop-dod` and
+`inject-rules` hooks, `agent-rig init`, the `loop` skill, and the dev deploy
+workflows.
+
+## 0.1.0
+
+First release: the CLI, `agent-os/universal` + the `node-ts`/`aws-cdk` stack
+layers, and the `aws-serverless` and `node-service` targets.
+
+---
+
+## Releasing
+
+`npm publish` needs 2FA and cannot be undone, so an agent prepares a release and
+**stops at that command**. Everything before it is mechanical:
+
+1. `pnpm test` — the full suite, including the e2e that generates both targets
+   cold and runs their own checks through the git path **and** the pack path.
+2. `npm pack --dry-run` — confirm the templates, including the dotted `.claude/`
+   tree, are in the tarball. This is where scaffolders break, and the git path
+   cannot catch it.
+3. Version in `package.json` (and the private inner package, kept in step).
+4. This file, and `PLAN.md` if the plan's claims changed.
+5. `git tag v<version> && git push --tags`.
+6. **Owner:** `npm publish`.
+7. **Owner:** smoke the published artifact — `npx create-agent-rig@<version>` in
+   an empty directory, then `pnpm install && pnpm check` inside it.

package/README.md

@@ -4,38 +4,102 @@ Scaffold a project that ships with an **agent operating system** — rules,
 gates, and hooks that hold the architecture mechanically, not by prose.
 
 ```sh
-npx create-agent-rig my-app
+npx create-agent-rig my-app                        # choose a target interactively
+npx create-agent-rig my-app --target node-service  # or name it up front
 ```
 
+Two coherent targets — `aws-serverless` (the default) and `node-service`. On a
+terminal the CLI prompts; in CI it wants `--target` explicitly. `--no-git`
+skips the initial baseline commit; `--no-color` (and `NO_COLOR`) plainens the
+output.
+
+Already have a repo? Install just the **process layer** into it — no
+architecture assumptions, no skeleton:
+
+```sh
+npx create-agent-rig init            # rules, gates, stop rules into the current repo
+npx create-agent-rig init --dry-run  # print the plan, write nothing
+```
+
+`init` drops in the autonomy tiers, stop rules, workflow, and the enforcement
+hooks, and refuses to clobber an existing `CLAUDE.md`.
+
 ## What you get
 
 **A system of boundaries, each held by tooling.** An agent (or a human using
-one) cannot talk its way past them:
+one) cannot talk its way past them — each guard is a pre-write scan that stops
+the normal path cold (review and tests back it; the claim is stated exactly,
+never inflated). The hooks live in `.claude/hooks/` and are wired in
+`.claude/settings.json`:
 
 - **`guard-core-purity`** — refuses any edit that puts I/O, clock, randomness,
-  or environment access into the pure domain core;
+  environment access, or a non-allowlisted import into the pure domain core;
 - **`guard-web-boundary`** — refuses `db`/service imports from the frontend;
   the web talks to the backend over HTTP only;
 - **`block-no-verify`** — refuses bypassing pre-commit checks (and knows the
-  difference between using the flag and merely mentioning it in a message).
-
-Around the hooks, the operating system: **autonomy tiers** (what an agent does
-alone / after review / never), **stop rules** (three strikes, flaky ≠ retry,
-session staleness), **subagent gates** (`test-writer`, `code-reviewer`,
-`security-scanner`, `cdk-diff-reviewer`), **skills** (`pr-ship` pre-merge
-gate; `post-deploy-verify` with its binary HEALTHY/REGRESSION verdict), and a
-one-page `CLAUDE.md` map a fresh session orients by.
+  difference between using the `--no-verify`/`-n` flag and merely mentioning it
+  in a message);
+- **`guard-bash`** — refuses the part of the "Never" tier a text scan can decide:
+  a force-push or `--delete` naming a shared branch, a push that names the default
+  branch, `gh workflow run`/`gh api …/dispatches` against a production workflow,
+  and `rm` on a catastrophic target. It **parses** the command rather than
+  pattern-matching it, so a commit message mentioning a forbidden flag is prose,
+  not a bypass — and the file states exactly what it does **not** inspect
+  (`cdk deploy`, `find -delete`, a bare `git push`, and more);
+- **`gate-stop-dod`** — refuses to end the session while a Definition-of-Done
+  check is red; it fails open (a missing or corrupt config never makes the
+  session unquittable) and never blocks twice in a row;
+- **`inject-rules`** — re-injects the autonomy rules at session start, so they
+  survive compaction and resumes.
+
+**A brake that is a real file.** `touch ~/.claude/<project>-loop-STOP` and no
+merge lands until it is removed — enforced at the tool layer, so it holds even if
+nothing reads the rule. Everything short of the merge stays allowed on purpose:
+finish the task, push the branch, open the PR, write the journal. Stopping
+cleanly must not mean losing work.
+
+**Two sweeps meant to run outside any session** — nothing schedules them for you;
+that is deliberate, because a check a run performs on itself is one a hurried run
+skips. `detect-missed-gate` finds merges
+that crossed an elevated path with no recorded reviewer verdict;
+`reconcile-external-prs` accounts for work that reached the default branch outside
+the queue. They exist because the one failure a run cannot report is its own
+missed gate — the run that skipped it is exactly the run that will not mention it.
+
+**A queue behind an adapter.** The `loop` driver selects through
+`.claude/scripts/queue/`: a pure core (filters in order, blocker resolution, the
+elevated-tier ration, stop conditions) with adapters for `PLAN.md` (the default,
+working before a project has a remote), GitHub Issues, and Jira. Two rules are
+load-bearing and tested from both directions — **blockers resolve from links,
+never labels**, and **the agent never files its own work items**.
+
+Around all of it: **autonomy tiers** (what an agent does alone / after review /
+never), **stop rules** (three strikes, flaky ≠ retry, session staleness),
+**subagent gates** (`test-writer`, `code-reviewer`, `security-scanner`, and
+`cdk-diff-reviewer` on the AWS target), **skills** (`pr-ship` pre-merge gate;
+`loop` queue driver; `worktree-task` for concurrent sessions; `new-invariant`, a
+generator for the invariant→hook→test pattern; `post-deploy-verify` and
+`ro-debug` on the AWS target), and a one-page `CLAUDE.md` map a fresh session
+orients by.
+
+**The hooks are examples, not laws.** `.claude/rules/invariants.md` states the
+pattern behind each one — a stated invariant, a mechanical check, a test for the
+check — so you can delete the ones whose invariant your project does not have and
+spend the slot on one it does. An inherited rule nobody chose is worse than an
+empty rule file: the empty one is visibly incomplete, the inherited one is
+invisibly wrong.
 
 The skeleton around it is real and runnable — pure core shared by server _and_
 browser (one schema validates on both sides of the wire), a mandatory usecase
-layer, a queue with DLQ discipline, tests at every layer.
+layer (`payload → handler → usecase → model`), a queue with DLQ discipline,
+tests at every layer.
 
 ## Targets
 
-| Target           | One line                                                                                                                                  |
-| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `aws-serverless` | DynamoDB single-table, SQS + DLQ + alarm, three Lambdas behind an HTTP API, static web via S3 + CloudFront, CDK with least-privilege IAM  |
-| `node-service`   | `node:http` server that also serves the web bundle, JSON-file store behind the same model boundary, spool-directory queue, worker process |
+| Target           | One line                                                                                                                                                                                          |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `aws-serverless` | DynamoDB single-table, SQS + DLQ + CloudWatch alarm, three Lambdas (POST/GET `/notes` behind an HTTP API, plus an SQS worker), static web on S3 + CloudFront, CDK with least-privilege IAM grants |
+| `node-service`   | `node:http` server that also serves the built web bundle, atomic JSON-file store behind the same model boundary, spool-directory queue + DLQ, worker process                                      |
 
 Coherent alternatives, not a parameterized abstraction. Flexibility is
 **subtraction**: the generated project is yours — delete what you don't need.
@@ -56,9 +120,10 @@ gets fought. If you need one of these, add it — the project is yours.
 ./demo.sh   # from a clone of this repo
 ```
 
-generate → the generated project's own gates pass → **an attempted core-purity
-violation is refused live by the hook** → the service runs, a smoke request
-travels every layer, the worker drains the queue, the DLQ stays empty:
+generates the `node-service` target → the generated project's own gates pass →
+**an attempted core-purity violation is refused live by the hook** → the
+service runs, a smoke request travels every layer, the worker drains the queue,
+the DLQ stays empty:
 
 ```
 == 3/4 an agent tries to put I/O and clock access into the pure core… ==
@@ -71,17 +136,34 @@ Move the impure part behind the usecase layer or into an adapter.
 
 ## Requirements
 
-- Node ≥ 20 (pnpm recommended for the generated workspace)
+- Node ≥ 20 (pnpm recommended for the generated workspace). The CLI itself
+  carries zero runtime dependencies — the `npx github:…`, tarball, and
+  published-package paths all work.
 
 ## How it stays honest
 
-Every template is a real project tested in place on every push; every e2e run
-generates a project cold and runs the generated project's own full checks
-(install → lint → typecheck → test → build → synth); a grep-test keeps the
-universal rules free of any provider mention; the hook-blocking behavior
-itself is under test; and a weekly lockfile-free run catches upstream breakage
-early. This repo dogfoods its own rulebook — `CLAUDE.md` and `.claude/` are
-composed from the templates, and drift fails the suite.
-
-Development: `pnpm test` (full), `pnpm test:unit` (fast loop),
-`pnpm template:check` (templates in place). The plan of record is `PLAN.md`.
+Every template is a real project, installed with a frozen lockfile and run in
+place on every push. Every e2e run generates a project cold and runs the
+generated project's own checks (install → lint → typecheck → test, plus
+`cdk synth` on the AWS target); the pack-path and git-path installs are both
+under test, because that is exactly where scaffolders break. A grep-test keeps
+the universal rules free of any provider mention; the hook-blocking behavior
+itself is under test; and a weekly lockfile-free run resolves each template's
+dependencies fresh to catch upstream breakage early. This repo dogfoods its own
+rulebook — `CLAUDE.md` and `.claude/` are composed from the templates, and
+drift fails the suite.
+
+**And the enforcement layer is adversarially reviewed, not just tested.** The
+Bash guard went through four review rounds with ten reviewers, who executed it
+rather than read it. They found a PR body that could forge its own reviewer
+verdict, a queue write that deleted the wrong line, and three ways to make the
+guard crash into permitting everything. Each round's findings — including the
+ones introduced by the previous round's _fix_ — are in the git history and in
+`CHANGELOG.md`. The rule that came out of it is now part of what ships: a guard
+that fails open must do provably bounded work, because fail-open turns every line
+of its own work into a potential bypass.
+
+Development (from a clone — `PLAN.md` and `demo.sh` live in the repository, not
+in the published tarball): `pnpm test` (full), `pnpm test:unit` (fast loop),
+`pnpm template:check` (templates in place). The plan of record is `PLAN.md`;
+release notes and the release checklist ship in `CHANGELOG.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agent-rig",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Scaffold a new project with an agent operating system (rules, gates, hooks) and a runnable code skeleton",
   "keywords": [
     "create",
@@ -15,6 +15,12 @@
     "node-service"
   ],
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/serhii-baksheiev/create-agent-rig.git"
+  },
+  "homepage": "https://github.com/serhii-baksheiev/create-agent-rig#readme",
+  "bugs": "https://github.com/serhii-baksheiev/create-agent-rig/issues",
   "type": "module",
   "bin": {
     "create-agent-rig": "packages/cli/dist/index.js"
@@ -22,7 +28,8 @@
   "files": [
     "packages/cli/dist",
     "templates",
-    "scripts/prepare.mjs"
+    "scripts/prepare.mjs",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=20"

package/packages/cli/dist/commands/create.js

@@ -67,14 +67,20 @@ export async function createProject(dirArg, options) {
 }
 const run = promisify(execFile);
 async function initGitBaseline(projectDir) {
+    // Disable git's background maintenance for these one-shot commands: a commit
+    // can otherwise fork an auto-gc / maintenance process that keeps writing to
+    // .git/objects/pack after we return — a non-deterministic tail that races any
+    // caller cleaning up the directory, and pointless work on a one-commit repo.
+    const quiet = ['-c', 'gc.auto=0', '-c', 'maintenance.auto=false'];
     try {
-        await run('git', ['init', '--quiet'], { cwd: projectDir });
-        await run('git', ['add', '-A'], { cwd: projectDir });
+        await run('git', [...quiet, 'init', '--quiet'], { cwd: projectDir });
+        await run('git', [...quiet, 'add', '-A'], { cwd: projectDir });
         // Explicit identity: the baseline must commit even where git has no
         // global user configured (fresh machines, CI). --no-verify here shields
         // the baseline from the USER'S global hooks only — the generated
         // project's own gates do not exist yet, so nothing is being bypassed.
         await run('git', [
+            ...quiet,
             '-c',
             'user.name=create-agent-rig',
             '-c',

package/packages/cli/dist/commands/init.js

@@ -0,0 +1,72 @@
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { agentOsUniversalDir } from '../templates.js';
+/** A user-facing failure: message is printed as-is, no stack trace. */
+export class InitError extends Error {
+}
+async function loadManifest() {
+    const raw = await readFile(path.join(agentOsUniversalDir(), 'layers.json'), 'utf8');
+    return JSON.parse(raw);
+}
+/**
+ * `init` installs only the PROCESS layer (hooks-and-reach brief §3/§4): rules
+ * that assume nothing about the codebase shape. Architecture rules reference
+ * `packages/core` and friends — installing them into an arbitrary repo would
+ * describe a structure that does not exist, which is worse than no rule.
+ *
+ * CLAUDE.md is the meta file we bring, but never over an existing one.
+ */
+async function processFiles(manifest) {
+    // the process layer, plus CLAUDE.md as the map (guarded separately)
+    return [...manifest.process, 'CLAUDE.md'];
+}
+async function exists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function planInit(repoDir) {
+    const manifest = await loadManifest();
+    const files = await processFiles(manifest);
+    const conflicts = [];
+    for (const rel of files) {
+        if (await exists(path.join(repoDir, rel)))
+            conflicts.push(rel);
+    }
+    return { files: files.map((p) => ({ path: p })), conflicts };
+}
+export async function initProject(repoDir, options) {
+    const manifest = await loadManifest();
+    const files = await processFiles(manifest);
+    const universal = agentOsUniversalDir();
+    // Refuse to clobber an existing CLAUDE.md unless forced — init edits
+    // someone's working repository (brief §4, non-negotiable).
+    if (!options.force && files.includes('CLAUDE.md')) {
+        if (await exists(path.join(repoDir, 'CLAUDE.md'))) {
+            throw new InitError('This repo already has a CLAUDE.md. Refusing to overwrite it. ' +
+                'Merge the agent-os map in by hand, or re-run with --force to replace it.');
+        }
+    }
+    const written = [];
+    const skipped = [];
+    const plannedCount = files.length;
+    for (const rel of files) {
+        const dest = path.join(repoDir, rel);
+        const isForceableMeta = rel === 'CLAUDE.md';
+        if ((await exists(dest)) && !(isForceableMeta && options.force)) {
+            // never overwrite a file init did not write (a user's own copy)
+            skipped.push(rel);
+            continue;
+        }
+        if (options.dryRun)
+            continue;
+        await mkdir(path.dirname(dest), { recursive: true });
+        await writeFile(dest, await readFile(path.join(universal, rel)));
+        written.push(rel);
+    }
+    return { written, skipped, plannedCount };
+}

package/packages/cli/dist/index.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 import { CreateError, createProject } from './commands/create.js';
+import { InitError, initProject, planInit } from './commands/init.js';
 import { makePalette } from './lib/colors.js';
 import { promptTarget } from './lib/prompts.js';
 import { collectGovernance, renderSummary } from './lib/summary.js';
@@ -20,7 +21,11 @@ Options
   --no-git          skip git init + the pristine-template baseline commit
   --no-color        plain output (NO_COLOR is respected too)
   --version         print the version
-  -h, --help        this text`;
+  -h, --help        this text
+
+Also: create-agent-rig init [--dry-run] [--force]
+  Install the process layer (rules, gates, stop rules — no architecture
+  assumptions) into the CURRENT existing repo. Refuses to clobber CLAUDE.md.`;
 async function packageVersion() {
     // dist/index.js lives three levels under the package root — same walk as
     // the templates resolver, valid in the repo and in the published package.
@@ -28,7 +33,44 @@ async function packageVersion() {
     const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
     return pkg.version;
 }
+async function runInit(rawArgs) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args: rawArgs,
+            options: { 'dry-run': { type: 'boolean' }, force: { type: 'boolean' } },
+            allowPositionals: false,
+        }));
+    }
+    catch (error) {
+        process.stderr.write(`${error.message}\n\n${USAGE}\n`);
+        return 1;
+    }
+    const cwd = process.cwd();
+    const dryRun = values['dry-run'] === true;
+    const plan = await planInit(cwd);
+    process.stdout.write(`agent-rig init — process layer into ${cwd}\n\n` +
+        plan.files.map((f) => `  + ${f.path}`).join('\n') +
+        '\n');
+    if (plan.conflicts.length > 0) {
+        process.stdout.write(`\nAlready present (kept, not overwritten):\n` +
+            plan.conflicts.map((c) => `  · ${c}`).join('\n') +
+            '\n');
+    }
+    const result = await initProject(cwd, { dryRun, force: values.force === true });
+    if (dryRun) {
+        process.stdout.write(`\nDry run — nothing written (${result.plannedCount} files planned).\n`);
+        return 0;
+    }
+    process.stdout.write(`\nInstalled ${result.written.length} files` +
+        (result.skipped.length ? `, kept ${result.skipped.length} existing` : '') +
+        '.\n');
+    return 0;
+}
 async function main() {
+    if (process.argv[2] === 'init') {
+        return runInit(process.argv.slice(3));
+    }
     let positionals;
     let values;
     try {
@@ -92,7 +134,7 @@ main()
     process.exitCode = code;
 })
     .catch((error) => {
-    if (error instanceof CreateError) {
+    if (error instanceof CreateError || error instanceof InitError) {
         process.stderr.write(`${error.message}\n`);
     }
     else {

package/packages/cli/dist/lib/copy-tree.js

@@ -16,6 +16,8 @@ export const DEFAULT_IGNORE = [
     '.next',
     'out',
     'next-env.d.ts',
+    // the init-manifest of the universal layer — tooling metadata, not payload
+    'layers.json',
 ];
 /** A file is treated as binary if its first bytes contain a NUL byte. */
 function isBinary(buffer) {

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

@@ -1,21 +1,35 @@
 import { readdir } from 'node:fs/promises';
 import path from 'node:path';
-const names = async (dir, strip) => {
+const names = async (dir, strip, keep) => {
     try {
-        return (await readdir(dir)).map((entry) => entry.replace(strip, '')).sort();
+        return (await readdir(dir))
+            .filter((entry) => !keep || keep.test(entry))
+            .map((entry) => entry.replace(strip, ''))
+            .sort();
     }
     catch {
         return [];
     }
 };
+/**
+ * Hooks whose filename names the *tool* they intercept rather than the
+ * invariant they enforce. Stripping the prefix would print "bash", which tells
+ * the reader nothing — and a screen that sells enforcement may not be vague.
+ */
+const HOOK_LABELS = {
+    'guard-bash': 'never tier',
+};
 export async function collectGovernance(projectDir) {
     const claude = path.join(projectDir, '.claude');
     return {
         rules: await names(path.join(claude, 'rules'), /\.md$/),
         agents: await names(path.join(claude, 'agents'), /\.md$/),
-        hooks: (await names(path.join(claude, 'hooks'), /\.mjs$/))
-            // guard-core-purity → "core purity": the mechanism, not the filename
-            .map((hook) => hook.replace(/^(guard|block)-/, '').replaceAll('-', ' ')),
+        // `.mjs` only: the stack layer also drops config (dod-checks.json) in this
+        // directory, and counting a config file as an enforced hook would make the
+        // screen overstate the one thing this tool actually sells.
+        hooks: (await names(path.join(claude, 'hooks'), /\.mjs$/, /\.mjs$/)).map(
+        // guard-core-purity → "core purity": the mechanism, not the filename
+        (hook) => HOOK_LABELS[hook] ?? hook.replace(/^(guard|block)-/, '').replaceAll('-', ' ')),
         skills: await names(path.join(claude, 'skills'), /$^/),
     };
 }

package/templates/agent-os/stack/aws-cdk/.claude/rules/aws-cdk.md

@@ -3,6 +3,17 @@
 How the universal boundaries land on AWS. If a rule here seems to fight a
 universal rule, that is an invariant conflict — stop and surface it.
 
+## The elevated paths this layer adds
+
+`CLAUDE.md` declares the project's own elevated paths; this block adds the ones
+that exist only because this layer does. The gate sweep
+(`.claude/scripts/detect-missed-gate.mjs`) unions every declaration it finds, so a
+target without infrastructure never declares a directory it does not have.
+
+```elevated-paths
+infra/
+```
+
 ## Infrastructure is code, and only code
 
 - Everything lives in the CDK app under `infra/`. A console change ("click-ops")
@@ -17,6 +28,24 @@ universal rule, that is an invariant conflict — stop and surface it.
   teardown; flip to RETAIN before real data arrives — that flip is a Tier-2
   decision.
 
+## Stacks: what may move, and what may never
+
+- 🔴 **Never move a stateful construct between stacks.** A Table, Bucket, Secret
+  or user pool that changes stack is **deleted and recreated** by
+  CloudFormation — that is data loss, not a refactor, and it passes review as
+  "tidying" if nobody knows this rule. Stateful constructs stay put and are
+  referenced cross-stack.
+- **A stack has a hard resource ceiling (500).** One HTTP route costs several
+  resources, so a growing API stack approaches it long before it looks big. When
+  it does, split out the least-coupled domain as a **stateless-only** stack —
+  functions, roles, routes — attached to the same API cross-stack, with a
+  **one-way** dependency. Splitting stateless costs nothing; splitting stateful
+  costs the data (above).
+- **Fleet-wide function defaults live in one module, not in a stack.**
+  Architecture, runtime, `NODE_OPTIONS`, tracing: one edit there reaches every
+  function. A per-stack override of a fleet default is the thing to reject in
+  review — it is invisible from anywhere except that stack.
+
 ## IAM: least privilege, by construction
 
 - Use the narrow grant for the operation actually performed
@@ -48,6 +77,23 @@ universal rule, that is an invariant conflict — stop and surface it.
   clients constructed once, handler exported. Nothing else imports an entry.
 - Functions stay single-purpose — one route or one event source each. Fan-out
   belongs to infrastructure (queues, topics), not to in-process branching.
+- **SDK clients are constructed at module top level, never inside the handler.**
+  Containers are reused across warm invocations, so a client built in the handler
+  body is paid on every invocation and defeats connection reuse — the most common
+  Lambda performance bug, and invisible in tests because tests are always cold.
+  The same applies to anything expensive and stateless: build once per container.
+- Environment is parsed **once, at module scope**, through `loadEnv(zod)`. A
+  misconfigured function then fails its cold start loudly instead of misbehaving
+  quietly per request, and no code below the entry file reads the environment
+  directly.
+
+## When the deployed runtime misbehaves
+
+Investigate before writing anything: the **`ro-debug` skill** has the read-only
+recipes and, more usefully, the traps that have produced confident wrong
+diagnoses — a stale local branch read as current, `UPDATE_COMPLETE` left over
+from the previous deploy, an empty metric read as healthy when it means the
+function was never invoked.
 
 ## Post-deploy verification (target-specific means)