create-agent-rig 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -7,6 +7,107 @@ 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.2
+
+Numbered as a patch by the owner's call; the content below is additive, so
+nothing that shipped in 0.3.1 changed shape.
+
+A generated project gains two review gates it did not have — one before the work
+starts, one over the prose that instructs it — and three more queue-hygiene
+checks.
+
+**Upgrading an existing rig: `init` alone is not enough, and here is exactly
+why.** `create-agent-rig init` installs files that are not there and **keeps
+every file that is** — `--force` replaces `CLAUDE.md` and nothing else
+(`packages/cli/src/commands/init.ts`). Re-running it on a 0.3.1 rig therefore
+delivers the two new files, `.claude/agents/prose-reviewer.md` and
+`.claude/skills/check-premises/SKILL.md`, and **none of their wiring**: the
+skill arrives with nothing calling it, and the agent arrives with `pr-ship`
+never launching it. Six files below changed rather than appeared, and `init`
+will not touch them:
+
+```
+.claude/agents/code-reviewer.md          # the sixth blocking item
+.claude/skills/loop/SKILL.md             # calls check-premises, and §3/§6/§8
+.claude/skills/pr-ship/SKILL.md          # fans out prose-reviewer, passes the item
+.claude/scripts/queue/core.mjs           # the three hygiene checks + Ticket.body
+.claude/scripts/detect-missed-gate.mjs   # sees a rulebook outside the repo root
+.claude/hooks/gate-stop-dod.mjs          # judges the tree it is in
+```
+
+Delete those six and re-run `init`, or copy them across by hand. A proper
+upgrade command is queued, not shipped — and until it exists this note tells you
+the manual steps rather than an easy sentence that leaves half the release
+inert. That failure mode is the whole subject of 0.3.1, immediately below.
+
+### Added
+
+- **`check-premises` skill** — a queue item is a _claim about the code_, written
+  by someone who was not reading the code at the time, and nothing downstream
+  re-checks it: the failing test is written against the item, the implementation
+  against the test, and the reviewer compares the diff to the item. A false
+  premise therefore produces work that is correct, tested, reviewed and useless.
+  The skill runs between taking the item and the Red step, is read-only by
+  frontmatter so it cannot start implementing, and returns `PREMISES HOLD` /
+  `PREMISE FALSE` / `UNVERIFIABLE`. Its two boundaries are the point: a false
+  load-bearing premise is **stop and report**, never a silent re-aim of the task,
+  and only load-bearing claims are checked — an audit is what makes the step
+  expensive enough to skip. The `loop` skill calls it, and treats `PREMISE FALSE`
+  as a per-task escalation rather than a licence to rewrite the item.
+- **`prose-reviewer` agent** — a fourth gate, read-only. In this layer the prose
+  _is_ the implementation: a rule that overstates its own enforcement fails
+  exactly like broken code, silently and in the direction of false confidence. It
+  blocks on five things — enforcement claimed beyond the mechanism, a dead
+  reference, two rules that contradict each other, stated limits gone stale in
+  either direction, and domain that must not travel (a vendor name, a host path,
+  a tracker key or a credential in a layer meant to be neutral) — and its
+  boundary comes before its checklist: it is **not
+  a literary editor**, and prose that is merely clumsy is not a finding. Wired
+  into the `pr-ship` fan-out and named in both maps.
+- **A sixth blocking item for `code-reviewer`** — a change that contradicts the
+  queue item it claims to implement. The instruction is to report the mismatch,
+  never to decide which side "must have been meant": a reviewer who reconciles
+  the two silently turns a visible mismatch into an invisible one. Where no item
+  was supplied, it says so rather than reconstructing one from the PR body —
+  which is evidence `autonomy.md` refuses by name. `pr-ship` now passes the item.
+- **Three queue-hygiene checks** — a parent that says it was split up and is
+  still open; a dependency line naming a blocker no link carries (worse than a
+  stale label: selection reads the item as unblocked); and a document link that
+  is broken on its face. The neutral `Ticket` shape gains a **nullable `body`**
+  so these live in one pure function instead of once per adapter — and `null`
+  means "this adapter cannot answer", never "checked, found nothing".
+
+### Fixed
+
+- **The baseline commit of a generated project could land in the caller's
+  repository.** Git hands its hooks an absolute `GIT_DIR`, and the CLI spawned
+  git with the environment intact — so `git init` re-initialised the caller's
+  repo, `add -A` staged its tree, and the commit landed on whatever branch it had
+  checked out, while the generated project got no `.git` at all. A redirected
+  `git init` can also flip the caller's repository to `core.bare=true`. The path
+  that triggers it is a pre-commit hook running a suite that generates projects —
+  which is what made the `worktree-task` skill unusable. Every git call site now
+  strips the variables that locate a repository, including the shipped
+  `gate-stop-dod` hook (which asked git whether _which_ tree was clean) and
+  `preflight`.
+- **The Tier-2 gate sweep could not see a rulebook outside the repository root.**
+  `detect-missed-gate` exempts the rulebook from its inert-file rule so a merge
+  rewriting the autonomy tiers cannot pass as "just prose" — but the exemption
+  was anchored at `CLAUDE.md` / `.claude/`. Any project that vendors, templates
+  or nests a rig keeps its rulebook elsewhere, and every `.md` there was dropped
+  before the elevated-path test ran. It is now recognised wherever it sits, and
+  the sweep's verdict vocabulary knows the words `pr-ship` actually emits.
+
+### Deferred, and on what condition
+
+Two pieces of the source brief did **not** travel, because shipping an unproven
+gate into other people's projects is worse than not having one:
+
+- the queue-closing discipline for blocked dependents — enters when it has been
+  merged and used in the project it came from;
+- the clarify-gate (`C-0…C-2`) — enters once that gate has fired at least once
+  anywhere. Until then there is nothing to copy but an intention.
+
 ## 0.3.1
 
 `create-agent-rig init` shipped a rig that looked installed and enforced

package/README.md

@@ -83,8 +83,8 @@ 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;
+**subagent gates** (`test-writer`, `code-reviewer`, `security-scanner`,
+`prose-reviewer`, 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agent-rig",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Scaffold a new project with an agent operating system (rules, gates, hooks) and a runnable code skeleton",
   "keywords": [
     "create",

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

@@ -5,6 +5,7 @@ import { promisify } from 'node:util';
 import { copyTree, listTree } from '../lib/copy-tree.js';
 import { ALLOWED_OVERWRITES, detectCollisions } from '../lib/composition.js';
 import { substituteContent, substituteFileName } from '../lib/substitute.js';
+import { gitEnv } from '../lib/git-env.js';
 import { DEFAULT_TARGET, TARGETS, TARGET_NAMES } from '../lib/targets.js';
 import { agentOsStackDir, agentOsUniversalDir, skeletonDir } from '../templates.js';
 /** A user-facing failure: message is printed as-is, no stack trace. */
@@ -72,9 +73,10 @@ async function initGitBaseline(projectDir) {
     // .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'];
+    const where = { cwd: projectDir, env: gitEnv() };
     try {
-        await run('git', [...quiet, 'init', '--quiet'], { cwd: projectDir });
-        await run('git', [...quiet, 'add', '-A'], { cwd: projectDir });
+        await run('git', [...quiet, 'init', '--quiet'], where);
+        await run('git', [...quiet, 'add', '-A'], where);
         // 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
@@ -90,7 +92,7 @@ async function initGitBaseline(projectDir) {
             '--no-verify',
             '-m',
             'Pristine template (create-agent-rig)',
-        ], { cwd: projectDir });
+        ], where);
     }
     catch {
         // git missing or unusable — generation never fails on this.

package/packages/cli/dist/lib/git-env.js

@@ -0,0 +1,48 @@
+/**
+ * Variables that point git at a repository other than the one at `cwd`.
+ *
+ * Inherited, they silently redirect a git command into the CALLER's repository:
+ * `git init` re-initialises it, `add -A` stages the caller's tree, and a commit
+ * lands on whatever branch the caller has checked out — while the directory the
+ * command was aimed at ends up with no `.git` at all.
+ *
+ * This is not hypothetical. Git sets `GIT_DIR` and `GIT_INDEX_FILE` — absolute —
+ * for the hooks it runs, so a `git commit` from a linked worktree whose
+ * pre-commit runs a suite that shells out to git writes one junk commit per
+ * invocation onto the branch being committed. Observed twice in this repo, from
+ * two different call sites, which is why this lives in one module: a second copy
+ * of this list is a second chance to fix one and forget the other.
+ *
+ * The list is explicit rather than a `GIT_*` sweep on purpose — `GIT_SSH_COMMAND`
+ * or `GIT_TERMINAL_PROMPT` are the caller's environment and none of our business.
+ * Only repository *location* is stripped.
+ *
+ * 🔴 Limit, stated: this strips repository *location*, not every way git can be
+ * redirected. The config-injection family (`GIT_CONFIG_COUNT`/`_KEY_n`/`_VALUE_n`,
+ * `GIT_CONFIG_PARAMETERS`, `GIT_CONFIG_GLOBAL`/`_SYSTEM`) can carry `core.worktree`
+ * or `core.bare` and is deliberately out of scope: git never sets those for the
+ * hooks that cause this problem, and stripping a caller's deliberate config
+ * overrides would be its own surprise.
+ *
+ * 🔴 And it protects exactly the call sites that use it. It does not make git
+ * safe to call from a hook-invoked process in general, and a spawn that forgets
+ * `gitEnv()` is unprotected — nothing in this module can detect that. The sweep
+ * in `test/template/git-env.test.ts` is what watches for it.
+ */
+export const GIT_LOCATION_VARS = [
+    'GIT_DIR',
+    'GIT_WORK_TREE',
+    'GIT_INDEX_FILE',
+    'GIT_COMMON_DIR',
+    'GIT_OBJECT_DIRECTORY',
+    'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+    'GIT_NAMESPACE',
+    'GIT_PREFIX',
+];
+/** The caller's environment minus anything that re-points git at another repo. */
+export function gitEnv(env = process.env) {
+    const sanitised = { ...env };
+    for (const key of GIT_LOCATION_VARS)
+        delete sanitised[key];
+    return sanitised;
+}

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

@@ -10,5 +10,19 @@ export const TARGETS = {
     },
 };
 export const TARGET_NAMES = Object.keys(TARGETS);
-/** Zero options at the personal stage: one implicit target (PLAN.md §6). */
+/**
+ * The pre-selected entry in the interactive menu, and the API-level default.
+ *
+ * 🔴 **Not the fallback for a non-interactive run.** A run with no TTY and no
+ * `--target` is *refused* (`index.ts`) — never prompt into a pipe, and never
+ * guess a whole project shape for a script that did not say. This constant is
+ * what `Enter`, an out-of-range number or an unrecognised name resolve to at the
+ * prompt (`prompts.ts`), plus what `createProject` uses when called as a library
+ * with no target.
+ *
+ * The comment this replaces said "one implicit target", which was stale from
+ * when there was one. Its first correction claimed the CLI defaults silently in
+ * CI — the opposite of what it does, in the file a maintainer would open to
+ * check exactly that.
+ */
 export const DEFAULT_TARGET = 'aws-serverless';

package/scripts/prepare.mjs

@@ -5,25 +5,62 @@ import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const root = path.dirname(fileURLToPath(import.meta.url)) + '/..';
 
-// 1. Wire up the pre-commit hook when working inside the git checkout.
-if (existsSync(path.join(root, '.git'))) {
-  spawnSync('git', ['config', 'core.hooksPath', '.husky'], { cwd: root, stdio: 'inherit' });
+/**
+ * The environment `git config` runs under, minus anything that could point it
+ * at another repository's config file.
+ *
+ * This script runs from `pnpm install`, and a pre-commit hook can reach an
+ * install — a hook-started process inherits an absolute `GIT_DIR`, and
+ * `core.hooksPath` would then be written into somebody ELSE's repository.
+ *
+ * ⚠ The canonical list lives in `packages/cli/src/lib/git-env.ts` and this is a
+ * deliberate second copy, because `prepare` step 1 runs *before* step 2 builds
+ * the TypeScript that would make it importable. The subset is not a smaller
+ * opinion about that list: `git config --local` resolves its target file only
+ * through `GIT_DIR`/`GIT_COMMON_DIR`, and `GIT_CONFIG` names a config file
+ * outright. `GIT_WORK_TREE` and `GIT_INDEX_FILE` cannot move it, so stripping
+ * them here would be noise.
+ *
+ * Exported so the behaviour is testable — importing this module must not build
+ * anything, hence the entry-point guard at the bottom.
+ */
+export const gitConfigEnv = (env = process.env) => {
+  const sanitised = { ...env };
+  for (const key of ['GIT_DIR', 'GIT_COMMON_DIR', 'GIT_CONFIG']) delete sanitised[key];
+  return sanitised;
+};
+
+function main() {
+  // 1. Wire up the pre-commit hook when working inside the git checkout.
+  if (existsSync(path.join(root, '.git'))) {
+    spawnSync('git', ['config', 'core.hooksPath', '.husky'], {
+      cwd: root,
+      env: gitConfigEnv(),
+      stdio: 'inherit',
+    });
+  }
+
+  // 2. Build the CLI so the `bin` entry exists (required for git/tarball installs).
+  const require = createRequire(import.meta.url);
+  const tscPath = path.join(
+    path.dirname(require.resolve('typescript/package.json')),
+    'lib',
+    'tsc.js',
+  );
+  const result = spawnSync(
+    process.execPath,
+    [tscPath, '-p', path.join(root, 'packages/cli/tsconfig.build.json')],
+    { cwd: root, stdio: 'inherit' },
+  );
+  process.exit(result.status ?? 1);
 }
 
-// 2. Build the CLI so the `bin` entry exists (required for git/tarball installs).
-const require = createRequire(import.meta.url);
-const tscPath = path.join(
-  path.dirname(require.resolve('typescript/package.json')),
-  'lib',
-  'tsc.js',
-);
-const result = spawnSync(
-  process.execPath,
-  [tscPath, '-p', path.join(root, 'packages/cli/tsconfig.build.json')],
-  { cwd: root, stdio: 'inherit' },
-);
-process.exit(result.status ?? 1);
+// Run only when executed, never when imported: a test that imports this module
+// to check one exported function must not trigger a build or touch git config.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main();
+}

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

@@ -20,8 +20,10 @@ 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
-.claude/skills/    the drivers: loop, pr-ship, worktree-task, new-invariant
+.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
 ```
 
@@ -51,9 +53,13 @@ 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` runs before every PR; `security-scanner` runs when
-  a change touches auth, secrets, parsing, or outbound calls. Blocking findings
-  are resolved, not argued with. The `pr-ship` skill drives the gate.
+- **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
+  `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;
   `guard-bash` refuses the "Never" tier — force-pushing a shared branch, a
   production deploy, a filesystem wipe — and carries the kill switch;

package/templates/agent-os/universal/.claude/agents/code-reviewer.md

@@ -21,6 +21,21 @@ references, and you classify every finding as **blocking** or **advisory**.
 5. **Autonomy breaches** — Tier-2 territory (schema, auth, new dependency,
    public API) entered without a recorded decision. See
    `.claude/rules/autonomy.md`.
+6. **Contradicts the item it claims to implement** — the change does something
+   the queue item did not ask for, drops a stated requirement, or quietly
+   re-aims the task into an adjacent one. Read the item first, then the diff.
+   **Report the contradiction; never reconcile the two yourself** by deciding
+   which one "must have been meant" — that is the author's call, and a reviewer
+   who makes it silently turns a visible mismatch into an invisible one. A
+   change that is well-built and not the change that was asked for is the one
+   failure the rest of this checklist cannot see.
+
+   **If the item was not handed to you, say so and stop there.** Do not
+   reconstruct it from the branch name or the PR description: those are written
+   by whoever opened the PR — including the run being reviewed — and this
+   rulebook already refuses that evidence elsewhere (`.claude/rules/autonomy.md`).
+   "Item not supplied, item 6 not checked" is a useful line in a report; a
+   guess dressed as a verdict is worse than the silence it replaces.
 
 ## Advisory findings
 

package/templates/agent-os/universal/.claude/agents/prose-reviewer.md

@@ -0,0 +1,104 @@
+---
+name: prose-reviewer
+description: Reviews the documents that instruct agents — rule files, skills, agent specs, CLAUDE.md, the README — for claims the code does not support, dead references, and rules that contradict each other. Use when a change touches any of them, before the PR.
+tools: Read, Grep, Glob, Bash
+---
+
+In this project the prose **is** the implementation. A rule file is what an agent
+reads before it acts; a skill is a procedure; `CLAUDE.md` is the map. When one of
+them says something untrue, nothing fails — the next session simply acts on it,
+confidently, and the failure surfaces somewhere unrelated hours later.
+
+You review that layer the way `code-reviewer` reviews code: findings with
+`file:line`, each classified **BLOCKER** or **advisory**, and no fixes. You do
+not edit anything.
+
+## 🔴 The boundary — read this before the checklist
+
+**You are not a literary editor.** Wording, voice, rhythm, repetition, a
+paragraph that runs long, a heading you would have phrased differently: none of
+these is a finding. Prose that is merely clumsy is **not a finding** and must not
+appear in your report, not even as advisory. Every one of them you report costs
+the next reader the attention that should have gone to the ones that matter, and
+a gate that fires on taste gets ignored, then removed.
+
+You have exactly one question: **would a competent agent, acting on this text,
+do the wrong thing?** If no, it is not yours.
+
+Style in this layer is not forbidden ground, it is simply not yours: it lands in
+`code-reviewer`'s advisory bucket like any other readability note. Say nothing
+about it here, so the two gates never file competing opinions on one paragraph.
+
+## Checklist (blocking findings)
+
+1. **An overstated claim of enforcement.** The text says something is refused,
+   blocked, guaranteed or verified, and the mechanism behind it does not do that
+   — or does not exist. Read the hook, the script, the CI job, and quote what it
+   actually does. This is the most expensive failure in the layer: a rule trusted
+   past its reach is worse than no rule, because it stops anyone from looking.
+2. **A dead reference.** A file, hook, script, agent, skill, section or command
+   that is named but no longer exists, or has been renamed. Check it resolves —
+   a path is cheap to verify and a reader who hits a missing file learns to
+   distrust every other pointer in the document.
+3. **Two rules that contradict each other.** Same subject, incompatible
+   instructions, in different files or in different sections of one. Report both
+   locations and say which reading a session would most likely take. Do **not**
+   pick the winner: the resolution belongs in the rules, not in your report.
+4. **A stated limit that has gone stale — in either direction.** A guard that
+   lists limits it no longer has understates itself and invites work nobody
+   needs; one whose limits were never written, or were written before its last
+   two bypasses, sells cover it does not have. Both are blocking, and both are
+   found the same way: read the mechanism, then read what the text claims about
+   it.
+5. **Domain that must not travel.** In a layer meant to be neutral: a provider or
+   vendor name, a host-specific absolute path, a tracker key, a company or
+   product name, credentials or personal data in an example. State which layer
+   the file belongs to and why the mention breaks it.
+
+   🔴 **A seam built to name a vendor is not a leak.** An adapter, a driver, a
+   provider-specific module — its whole job is to name the thing it adapts, and
+   so is the documentation of it. The finding is a vendor name in text that
+   claims to be neutral, not a vendor name anywhere in a neutral directory.
+   Check what the file is for before reporting it; this is the item most likely
+   to fire on deliberate, tested code.
+
+## Advisory findings
+
+An instruction that is genuinely ambiguous — two readings that lead to different
+actions, where you cannot tell which was meant. A rule with no stated reason,
+where the reason is not obvious and the rule is the kind that gets deleted by
+whoever inherits it. A document that has grown to where the load-bearing part is
+no longer findable.
+
+That is the whole advisory list, on purpose. If a note does not fit one of those
+three, it belongs in your head, not in the report.
+
+## How you work
+
+- **Diff first** (`git diff`, `git log`), then read the surrounding document —
+  a claim is only judgeable in the context that qualifies it. Review what
+  changed, not the whole rulebook.
+- **Verify against the mechanism, never against your memory of it.** Every
+  blocking finding of type 1, 2 or 4 requires you to have opened the hook, the
+  script or the workflow file and quoted the line. A finding you could not check
+  is reported as unverified, or not at all.
+- **Quote the checklist item** each blocking finding violates, and give the
+  `file:line` of both the text and the mechanism that contradicts it.
+- **"No blocking findings" is a valid and useful verdict.** Say it plainly when
+  it is true; a gate that always finds something teaches everyone to discount it.
+
+## What you cannot see, stated so nobody relies on it
+
+🔴 **Nothing launches you.** No hook fires this review; a session reads a rule
+and decides to. So a change that skipped this gate and a change that passed it
+look identical afterwards, and any text — including this file — that says this
+review "runs" is describing a convention, not a mechanism. Report a claim of
+enforcement that rests on you the same way you would report any other: as an
+overstatement, item 1, including when the file making it is a rulebook you are
+named in.
+
+You read text and the mechanisms it names. You cannot tell whether a rule is
+*worth having*, whether the process it describes is the right one, or whether a
+claim about the world outside this repository is true. Those are the owner's
+questions, and answering them from this seat would be exactly the overreach
+item 1 exists to catch.

package/templates/agent-os/universal/.claude/hooks/gate-stop-dod.mjs

@@ -25,9 +25,29 @@ function main() {
   if (input.stop_hook_active) return 0;
 
   try {
+    // The environment loses the variables that locate a repository first. A
+    // process started under a git hook inherits an absolute GIT_DIR, and this
+    // question — "is the tree clean?" — would then be answered about a
+    // different repository entirely: gated on somebody else's uncommitted
+    // work, or waved through despite its own.
+    //
+    // Four of the eight variables that can relocate a repository, because
+    // these are the four git itself hands its hooks — and this file ships into
+    // generated projects, so it cannot import the canonical list from the
+    // generator. A shorter list that says why it is shorter beats a copy that
+    // silently drifts.
+    //
+    // 🔴 Limit: only THIS command is sanitised. The Definition-of-Done checks
+    // below run with the environment as given, because they are the project's
+    // own commands and their environment is the project's business.
+    const env = { ...process.env };
+    for (const key of ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_COMMON_DIR']) {
+      delete env[key];
+    }
     const status = execSync('git status --porcelain', {
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'ignore'],
+      env,
     });
     if (status.trim() === '') return 0;
   } catch {

package/templates/agent-os/universal/.claude/rules/workflow.md

@@ -51,6 +51,10 @@ travels one path to merge, in this order:
    - the `code-reviewer` agent **always**;
    - `security-scanner` when it touches auth, secrets/configuration, input
      parsing, file handling, or outbound calls;
+   - `prose-reviewer` when it touches the documents that instruct agents — a
+     rule file, a skill, an agent spec, `CLAUDE.md`, the README. In this layer
+     the prose *is* the implementation, and it fails the same way code does:
+     silently, in the direction of false confidence;
    - an infrastructure review when it touches infrastructure (the stack layer
      names the reviewing agent for the target).
 

package/templates/agent-os/universal/.claude/scripts/detect-missed-gate.mjs

@@ -109,8 +109,21 @@ export const parseElevatedPaths = (markdown) => {
  * in — EXCEPT the rulebook itself. Declaring `.claude/` as elevated was a no-op
  * for every `.md` under it, so a merged PR rewriting the autonomy tiers or the
  * Never list passed the gate meant to catch exactly that.
+ *
+ * 🔴 A rulebook is recognised **wherever it sits**, not only at the repository
+ * root. The root-anchored version of this test was true of a project this tool
+ * generates and false of the tool itself: a generator keeps rulebooks under
+ * `templates/`, every one of them is a `.md`, and all of them were dropped as
+ * inert — so two merges that changed agent specs, skills and an init map were
+ * reported clean, while a third that also touched a `.mjs` was caught for that
+ * reason alone. Any repository that vendors, templates or nests a rig has the
+ * same shape.
  */
-const isRulebook = (path) => path === 'CLAUDE.md' || path.startsWith('.claude/');
+const isRulebook = (path) =>
+  path === 'CLAUDE.md' ||
+  path.endsWith('/CLAUDE.md') ||
+  path.startsWith('.claude/') ||
+  path.includes('/.claude/');
 
 const isInert = (path) =>
   !isRulebook(path) &&
@@ -149,7 +162,16 @@ export const elevatedPathsIn = (files = [], elevatedPaths = []) => {
 // reads 100 PR bodies, so a crafted set costs minutes of CPU on a scheduled job
 // that reports nothing when it is killed.
 const REVIEWERS = /\b(code-reviewer|security-scanner|[a-z][a-z0-9-]{0,48}-reviewer)\b/i;
-const VERDICT = /\b(clean|passed|pass|approved|no blocking|green)\b/i;
+// SHIP and HOLD are what `pr-ship` actually emits, and their absence here meant
+// a PR body recording a real verdict registered as no evidence at all — so the
+// weaker "someone says a gate ran, go check" observation never fired on this
+// rulebook's own PRs, only on bodies phrased in somebody else's vocabulary.
+//
+// 🔴 Widening this list widens what is *observed*, never what is *permitted*.
+// `body-claim` is still a finding; only the `human-review` label suppresses one.
+// Adding a word must never move a PR from "reported" to "clean" — if a change
+// here could do that, it is the wrong change.
+const VERDICT = /\b(clean|passed|pass|approved|no blocking|green|ship|hold)\b/i;
 
 /**
  * 🔴 The body is NOT authority, and this is the security core of the file.
@@ -284,8 +306,14 @@ export const classifyPr = (pr, { elevatedPaths = [], epoch = null } = {}) => {
           'claims a reviewer verdict, but the body is written by the author — it is ' +
           'not verifiable after the fact. Only the human-review label, which needs ' +
           'repository permission, records the gate. Confirm the gate ran and label it.'
-        : `merged touching ${elevatedFiles.length} elevated-tier path(s) with ` +
-          'no human-review label and no reviewer verdict recorded anywhere',
+        : // "anywhere" claimed more than this sweep can see: it reads the label
+          // and scans the body for a reviewer name next to a passing word. A
+          // verdict phrased any other way — or recorded in a review thread, a
+          // journal, a chat — is invisible here, and saying otherwise taught the
+          // reader to treat absence of evidence as evidence of absence.
+          `merged touching ${elevatedFiles.length} elevated-tier path(s) with ` +
+          'no human-review label, and no reviewer verdict this sweep could ' +
+          'recognise in the body',
   };
 };
 

package/templates/agent-os/universal/.claude/scripts/preflight.mjs

@@ -32,8 +32,41 @@ export const UNCHECKED = [
   'a budget is declared for this run, and it is written down somewhere the run can re-read',
 ];
 
+/**
+ * The environment loses the variables that locate a git repository.
+ *
+ * A process started under a git hook inherits an absolute `GIT_DIR`, and every
+ * probe below would then answer about a DIFFERENT repository — `fetch` writing
+ * into it, `rev-parse` comparing its refs. This file's whole point is that an
+ * `unknown` never becomes a `pass`; a confident answer about the wrong repo is
+ * worse than either.
+ *
+ * 🔴 Limit: only repository *location* is stripped. `gh` inherits the rest of
+ * the environment on purpose — its credentials live there.
+ */
+export const withoutGitLocation = (env = process.env) => {
+  const sanitised = { ...env };
+  for (const key of [
+    'GIT_DIR',
+    'GIT_WORK_TREE',
+    'GIT_INDEX_FILE',
+    'GIT_COMMON_DIR',
+    'GIT_OBJECT_DIRECTORY',
+    'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+    'GIT_NAMESPACE',
+    'GIT_PREFIX',
+  ]) {
+    delete sanitised[key];
+  }
+  return sanitised;
+};
+
 const run = (command, args) =>
-  execFileSync(command, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+  execFileSync(command, args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: withoutGitLocation(),
+  }).trim();
 
 /** The kill switch must be absent before a run starts. */
 export const checkKillSwitch = () => {

package/templates/agent-os/universal/.claude/scripts/queue/core.mjs

@@ -22,7 +22,32 @@
 //     createdAt: ISO string | null,
 //     triage:    boolean,                        // a proposal — never selectable
 //     trigger:   'auto' | 'human' | null,        // null means unconditional
+//     body:      string | null,                  // the item's text — see below
+//     raw:       string | undefined,             // adapter-private; not read here
 //   }
+//
+// 🔴 **Why `body` is on the neutral shape, decided rather than drifted into.**
+// Two hygiene checks need the item's text: a body that claims a blocker the
+// links do not carry, and a document link that is broken on its face. The
+// alternative was to implement them inside each adapter — the same invariant in
+// three places, which `.claude/rules/invariants.md` says will disagree, with the
+// copy nobody is looking at being the wrong one. Here they are one function,
+// testable on fixtures, and the adapters stay thin.
+//
+// The item that asked for these called one of them "body vs labels". It is
+// **body vs links**, deliberately: invariant 1 in this same file says a label is
+// never decisive, so a check that compared the body against labels would be
+// asking the one source the rest of the module refuses to trust. Recorded here
+// rather than silently substituted.
+//
+// **`null` is a real answer and it is not `''`.** `plan-md` is a flat list with
+// no per-item body; it must say "I cannot answer" rather than "checked, found
+// nothing", because the second one silently converts a blind spot into a pass.
+// Every check below therefore returns `null` — no finding — when `body` is not
+// a non-empty string.
+//
+// `raw` is the adapter's own record of the line or record it parsed. It is
+// deliberately NOT read by this file: it exists for the adapter's writes.
 
 /**
  * The operations every adapter provides. A second tracker is an adapter, not a
@@ -127,9 +152,109 @@ export const hygieneOf = (ticket) => {
       why: `labelled ready while ${open.map((b) => b.id).join(', ')} still blocks it`,
     };
   }
+
+  const links = ticket.blockedBy ?? [];
+  const body = typeof ticket.body === 'string' ? ticket.body : '';
+
+  // Everything below needs the item's text. `null`/'' means the adapter has none
+  // (plan-md), which is "cannot answer" and never a pass — see the shape note at
+  // the top of this file.
+  if (body.trim() === '') return null;
+
+  if (
+    SPLIT_IN_BODY.test(body) &&
+    links.length >= 2 &&
+    open.length === 0 &&
+    ticket.state !== 'closed'
+  ) {
+    return {
+      kind: 'split-parent-left-open',
+      id: ticket.id,
+      why:
+        'its body says it was split up, every part it links to is resolved, and it ' +
+        'is still open — either it wants closing, or the work it kept is written ' +
+        'down nowhere',
+      // 🔴 Limit, and the reason this reads the body at all: "every dependency
+      // resolved and still open" describes EVERY healthy multi-dependency item
+      // from the moment its last blocker lands — including one the queue is about
+      // to hand out, and one the loop is working right now. A check that fires on
+      // those gets muted, and a muted check reports nothing about anything. The
+      // body is the only place the neutral shape carries the word "split", so an
+      // adapter without one (plan-md) cannot raise this finding at all.
+    };
+  }
+
+  if (BLOCKER_IN_BODY.test(body) && links.length === 0) {
+    return {
+      kind: 'body-claims-unlinked-blocker',
+      id: ticket.id,
+      why:
+        'a dependency line in the body names a blocker the item carries no link ' +
+        'for, so selection sees it as unblocked. Either the link is missing or the ' +
+        'adapter failed to parse it — worse than a stale label, because this one ' +
+        'takes work whose blocker may still be open',
+    };
+  }
+
+  const broken = brokenLinkIn(body);
+  if (broken) {
+    return {
+      kind: 'broken-document-link',
+      id: ticket.id,
+      why:
+        `the body links to a document with no destination (${broken}) — the item ` +
+        'points at context nobody can reach',
+      // 🔴 Limit: this core is pure, so it cannot fetch or stat anything. It
+      // catches a link that is broken ON ITS FACE — empty, or a placeholder.
+      // A link that is well-formed and dead is invisible here, by design.
+    };
+  }
+
   return null;
 };
 
+/**
+ * A dependency **line**, matching the convention `github-issues.mjs` parses.
+ *
+ * Anchoring to the line start is what makes it honest rather than merely narrow.
+ * Unanchored, it fired on "this WAS blocked by #7 last week, and #7 landed" and
+ * on "nothing is blocked by this item" — then printed a finding asserting a live
+ * blocker the body had just denied. A check that reports the opposite of what the
+ * text says is worse than no check.
+ *
+ * Linear: the bounded classes on either side of each boundary are disjoint, so
+ * there is no ambiguous split to backtrack over.
+ */
+const BLOCKER_IN_BODY = /^[-*\t ]{0,4}(?:blocked by|depends on|blocker)[ \t:]{0,8}[#A-Za-z0-9]/im;
+
+/** The item saying, in its own words, that it was broken into other items. */
+const SPLIT_IN_BODY = /\b(?:split into|split up into|broken into|broken up into|superseded by|subtasks?:)/i;
+
+/**
+ * A markdown link, destination captured for a plain-string test afterwards.
+ *
+ * 🔴 The destination is ONE bounded quantifier on purpose. The obvious regex —
+ * `\(\s*(?:TODO|TBD)?\s*\)` — puts two unbounded quantifiers around an optional
+ * group, which is `\s*\s*`: a whitespace run with no closing paren is re-split at
+ * every position. Measured on this module at 1.7s for 32k spaces and ~7s at the
+ * 64k body cap, in a function the loop runs for every item in the queue. That is
+ * the same defect, in the same shape, that `github-issues.mjs` records fixing —
+ * written out here because remembering it once evidently was not enough.
+ */
+const LINK = /\[[^\]]{0,120}\]\(([^)]{0,40})\)/;
+const PLACEHOLDER = /^(?:TODO|TBD|link|url)$/i;
+
+/** Control bytes stripped: this string is printed to a terminal. */
+const printable = (text) => text.replace(/[^\x20-\x7E]/g, '').slice(0, 40);
+
+const brokenLinkIn = (body) => {
+  const match = LINK.exec(body);
+  if (!match) return null;
+  const destination = String(match[1] ?? '').trim();
+  if (destination !== '' && !PLACEHOLDER.test(destination)) return null;
+  return printable(match[0]);
+};
+
 /**
  * The sort among survivors.
  *

package/templates/agent-os/universal/.claude/scripts/queue/github-issues.mjs

@@ -74,6 +74,12 @@ export const toTicket = (issue, states = {}) => {
     blocks: [],
     priority: priorityLabel ? Number(priorityLabel[1]) : 999,
     createdAt: issue.createdAt ?? null,
+    // The body travels on the neutral shape so the hygiene checks live in one
+    // place (core.mjs) instead of once per adapter. This adapter also parses it
+    // internally for blocker links — the two readings are independent on
+    // purpose: that is exactly the disagreement `body-claims-unlinked-blocker`
+    // exists to surface.
+    body: typeof issue.body === 'string' ? issue.body : null,
     triage: labels.includes('triage'),
     trigger: labels.includes('trigger-auto')
       ? 'auto'

package/templates/agent-os/universal/.claude/scripts/queue/jira.mjs

@@ -96,6 +96,9 @@ export const toTicket = (issue) => {
     blocks,
     priority: PRIORITY[String(fields.priority?.name ?? '').toLowerCase()] ?? 999,
     createdAt: toIso(fields.created),
+    // Flattened from the document description — the same text this adapter
+    // already reads internally, now visible to the shared hygiene checks.
+    body: descriptionTextOf(issue) || null,
     triage: labels.includes('triage'),
     trigger: labels.includes('trigger-auto')
       ? 'auto'

package/templates/agent-os/universal/.claude/scripts/queue/plan-md.mjs

@@ -91,6 +91,12 @@ export const parsePlan = (plan) => {
       raw,
       line: index, // the identity a write uses — never the text
       url: null,
+      // 🔴 `null`, not `''`: a flat list has no per-item body, and the hygiene
+      // checks must read that as "this adapter cannot answer" rather than
+      // "checked, found nothing". An empty string would silently turn a blind
+      // spot into a clean bill of health. `raw` above is the line itself, kept
+      // for writes — it is not a body and core does not read it as one.
+      body: null,
       state: 'open',
       labels: [],
       tier: MARKERS.elevated.test(raw) ? 'elevated' : 'normal',

package/templates/agent-os/universal/.claude/skills/check-premises/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: check-premises
+description: Check a queue item's claims about the code before building on them. Use immediately after taking an item and before the failing test — whenever the item asserts that something exists, is missing, is broken, or works a particular way.
+context: fork
+allowed-tools: Read, Grep, Glob, Bash
+argument-hint: <the queue item's text>
+---
+
+A queue item is a **claim about the code**, written by someone who was not
+reading the code at the time. "The retry path swallows the error", "there is no
+validation on that field", "the worker never gets the second message" — each of
+those is a premise, and the work that follows is only worth doing if it is true.
+
+This skill checks the premises. It runs **after selection, before the Red step**,
+and it produces one of three verdicts. It writes nothing.
+
+## Why it sits here and not in review
+
+A false premise is not caught later. Review reads the diff against the item, and
+both are wrong in the same direction: the item said the validation was missing,
+the diff adds validation, the reviewer sees a diff that does what the item asked.
+Nobody re-reads the file that had the validation all along. The cost lands as a
+duplicate implementation, a "fix" for a bug that was somewhere else entirely, or
+a refactor of a path that no caller reaches — all of it green, reviewed, merged.
+
+The check is cheap because it is narrow, and the next section is that narrowness.
+
+## 1. Write out the claims — as claims
+
+List what the item asserts about the code as it exists **now**. Two to five
+lines. Keep them in the item's own terms; do not repair them while transcribing
+— a claim you have already improved is one you will not test.
+
+Separate the claims from the request. "Add a `GET /notes/:id` route" asserts
+nothing; "the route handler bypasses the usecase layer" does.
+
+An item that asserts nothing is done here: verdict `PREMISES HOLD`, one line
+saying there were none. That is a common and perfectly good outcome.
+
+## 2. Mark the load-bearing ones
+
+🔴 **A claim is load-bearing when its falsity changes what gets built.** Only
+those get verified. **This is not an audit** of the item, the file, or the
+codebase — the moment it becomes one, it stops being cheap, gets skipped under
+time pressure, and the whole step is lost.
+
+| Load-bearing | Not |
+| --- | --- |
+| "there is no X" — if X exists, the task is already done | a stale line number in the item's description |
+| "X is called from Y" — if it is not, the fix goes in the wrong place | a misspelled symbol you can resolve at a glance |
+| "X handles the empty case by Z" — the fix is designed against Z | a claim about a file this task will not touch |
+| "nothing enforces X" — the whole task is the enforcement | a claim the task's own failing test would immediately expose |
+
+That last row is the one worth internalising: a premise the Red step would
+falsify in the next five minutes does not need checking here. This step exists
+for the premises a passing test **would not** catch — the ones about code the
+task never touches.
+
+## 3. Verify each, against the code, with a citation
+
+Read the code. Not the tests, not the docs, not another queue item — those are
+claims too. Each verified premise gets a `file:line` citation; a premise you
+believe but cannot cite is not verified, it is remembered.
+
+## 4. The verdict
+
+| Verdict | When | What happens next |
+| --- | --- | --- |
+| `PREMISES HOLD` | every load-bearing claim checked out, or there were none | proceed to the Red step |
+| `PREMISE FALSE` | a load-bearing claim is contradicted by the code | **stop and report** |
+| `UNVERIFIABLE` | a load-bearing claim could not be decided from the code | report it as unverifiable, name what would decide it, and proceed only under a **labelled assumption** |
+
+🔴 **On `PREMISE FALSE` the answer is stop and report — never quietly work around
+the false premise by building something adjacent that seems useful.** Write what
+the item claimed, what the code actually says with its citation, and what the
+task might become instead. Then let a human re-aim it. The item is wrong, and an
+agent that silently repairs a wrong item produces work nobody asked for, in a
+branch named after a task that does not exist.
+
+`UNVERIFIABLE` is not a soft pass. A probe that could not run tells you nothing —
+so the assumption travels in the open, in the item and in the PR description,
+where the next reader can see which part of the work rests on it.
+
+## Examples — the three shapes this actually catches
+
+**The thing already exists.** Item: "the payload schema does not reject an empty
+title". The schema does reject it, three lines into the validator; the reported
+bug came from a caller that never invoked the validator. Building "the missing
+check" would have added a second, divergent rule and left the real defect —
+the caller — in place. Verdict `PREMISE FALSE`; the task becomes a caller fix.
+
+**The thing is somewhere else.** Item: "the worker retries forever because the
+retry budget is not applied". The budget is applied, and correctly; the message
+returns to the queue from a path above it that never consumed the budget at all.
+The fix designed against the item would have been written in a file that was not
+the problem. Verdict `PREMISE FALSE`.
+
+**Nothing enforces it — except something does.** Item: "nothing stops a handler
+importing the storage layer directly". A hook does exactly that, and has since
+before the item was filed. Two hours of building a second enforcement mechanism,
+which would then have disagreed with the first. Verdict `PREMISE FALSE`.
+
+Note what all three have in common: the resulting work would have been correct,
+tested, reviewable, and useless. That is the failure mode this catches, and it
+is invisible to every gate downstream.
+
+## Limits — stated, because a check trusted past its reach is worse than none
+
+- **It reads the code, so it only catches what the code can contradict.** A claim
+  about runtime behaviour ("this times out in production"), about intent, or
+  about a system this repository does not contain is `UNVERIFIABLE` here, not
+  false — say so rather than guessing.
+- **It is one pass, before the work.** A premise that becomes false while the
+  task runs (a merge lands, a dependency moves) is a staleness stop rule
+  (`.claude/rules/autonomy.md`), not this skill.
+- **It has no opinion on whether the task is worth doing.** True premises and a
+  pointless task is a perfectly consistent state, and it belongs to whoever fills
+  the queue.
+- 🔴 **Nothing makes this run, and the verdict is a self-report.** No hook fires
+  when a task starts building on an unchecked claim, and no artifact outlives the
+  step — so a run that skipped it and a run that passed it look identical
+  afterwards. That is the honest description of every rule of this shape here
+  (the `loop` skill says the same about its own no-hand-feeding rule), and it is
+  why the citation matters: a `file:line` in the report is the one part of this a
+  later reader can re-check.

package/templates/agent-os/universal/.claude/skills/loop/SKILL.md

@@ -10,9 +10,9 @@ boundaries; the **queue** holds the work; `PLAN.md` holds state, standing
 decisions and the journal. This skill is the driver in between: what gets picked,
 what keeps the loop going, what stops it, and where the report goes.
 
-Per-task procedure is unchanged: (worktree if another session may run) → failing
-test first → implement → `pr-ship` → merge on the named criterion → verify the
-deployed surface if one changed.
+Per-task procedure is unchanged: (worktree if another session may run) →
+`check-premises` → failing test first → implement → `pr-ship` → merge on the
+named criterion → verify the deployed surface if one changed.
 
 ## 0. The queue is behind an adapter
 
@@ -102,11 +102,18 @@ and the work turns out to touch an elevated path (`CLAUDE.md` →
 `elevated-paths`), run the gate anyway, record the verdict on the PR, and treat it
 as this run's elevated item for spacing.
 
+**Then, before the Red step: `check-premises`.** The item was written by someone
+who was not reading the code at the time, and everything downstream — the failing
+test, the implementation, the reviewer comparing diff to item — inherits its
+claims rather than checking them. On `PREMISE FALSE` the item is escalated (§6),
+not repaired in place: a run that silently re-aims its own task has authored work
+for itself, which is the one thing this loop does not do (§8).
+
 ## 3. What keeps the loop running, and what stops it
 
 Per-task stops (three strikes, attempt budget, invariant conflict, a blocking
-reviewer verdict) **do not end the run**: escalate that item (§5) and take the
-next one.
+reviewer verdict, a false premise in the item itself) **do not end the run**:
+escalate that item (§5) and take the next one.
 
 The run-level conditions are in `stopConditionOf` in `core.mjs`, checked in
 severity order: **queue unreadable** · **runtime regression** · **kill switch** ·
@@ -204,10 +211,14 @@ mechanises fully (`missed`, `.claude/rules/autonomy.md`) needs no self-report.
 ## 6. Escalation — two channels, by scope
 
 **Task-scoped — the item is the home, and the loop continues.** Three strikes, the
-attempt budget, an invariant conflict, or a blocking reviewer verdict:
+attempt budget, an invariant conflict, a blocking reviewer verdict, or a
+`PREMISE FALSE` verdict from `check-premises` — the last one is a
+`documented-stall` (§5), and its diagnosis is already written: what the item
+claimed, what the code says, and the citation:
 
 1. Comment the diagnosis on the queue item: what fails, what was tried, the
-   current hypothesis, links to the PR and the failing run. **Name the outcome
+   current hypothesis, and links to the PR and the failing run where they exist
+   — a premise stop has neither, and its citation stands in for both. **Name the outcome
    state in the same comment** — `incomplete` if the diagnosis cannot say which
    stage needed what. Writing `incomplete` on your own task is uncomfortable and
    is the point: the run that produced it is the only witness.
@@ -274,6 +285,7 @@ three poisons the only channel by which this project learns.
 | Does not | Why |
 | --- | --- |
 | **Create its own work items** | The queue is human-filled. Self-authored work drifts scope, and unattended it drifts unwatched |
+| **Re-aim an item whose premise turned out false** | Same rule wearing a disguise: an item silently rewritten into "what it should have said" is a work item the agent authored. Escalate it (§6) |
 | Take items needing a human decision | It cannot unblock itself; those wait in the Operator queue |
 | Take a `trigger-human` item | It would build for scale that does not exist |
 | Take two elevated items back to back | One unreviewed schema/permissions change is recoverable; a chain overnight is not |

package/templates/agent-os/universal/.claude/skills/pr-ship/SKILL.md

@@ -19,10 +19,20 @@ blockers.
    (see its README / package scripts). Any failure is an instant HOLD — never
    argue with a red check, never rerun flakiness to green
    (`.claude/rules/workflow.md`).
-3. **Reviewer fan-out.** Launch the `code-reviewer` agent on the diff — always.
+3. **Reviewer fan-out.** Launch the `code-reviewer` agent on the diff — always,
+   and **pass it the text of the queue item this branch implements**. Its
+   checklist blocks on a change that contradicts its item, and a reviewer given
+   only a diff cannot run that check: a cold context has no way to know what was
+   asked, and reconstructing it from the PR description would mean trusting the
+   run under review. If there is no item — owner-directed work, a hotfix — say
+   so when launching, and the reviewer skips that item openly instead of
+   guessing at it.
    Launch `security-scanner` as well when the diff touches its triggers: auth,
    secrets or configuration, input parsing, file handling, new outbound calls,
-   dependency changes. Run them as subagents, in parallel — a fresh context
+   dependency changes. Launch `prose-reviewer` when the diff touches a rule
+   file, a skill, an agent spec, `CLAUDE.md` or the README — a rulebook that
+   overstates its own enforcement fails silently and in the direction of false
+   confidence. Run them as subagents, in parallel — a fresh context
    reviews better than the session that wrote the code (see
    `.claude/rules/workflow.md`, "Review-context isolation").
 4. **DoD walk.** Check the Definition of Done list in

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

@@ -42,6 +42,10 @@ them all; they are one rulebook.
 
 - **TDD, without exception.** The failing test comes first — use the
   `test-writer` agent for it. See `.claude/rules/workflow.md`.
+- **Check the task's premises before the test.** A queue item is a claim about
+  the code, and nothing downstream re-reads the file it was wrong about — the
+  `check-premises` skill runs between taking the item and the failing test, and
+  a false load-bearing claim stops the task instead of quietly re-aiming it.
 - **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
@@ -49,9 +53,14 @@ them all; they are one rulebook.
   `.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` runs before every PR; `security-scanner` runs when
-  a change touches auth, secrets, parsing, or outbound calls. Blocking findings
-  are resolved, not argued with. The `pr-ship` skill drives the gate.
+- **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
+  `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. The mechanical enforcement below is a different thing, and the
+  difference is worth keeping straight.
 - **Enforcement is mechanical.** `guard-core-purity` catches an impure edit to
   the core the moment it lands; `guard-web-boundary` keeps the frontend off the
   backend; `block-no-verify` refuses pre-commit bypasses; `guard-bash` refuses

package/templates/agent-os/universal/layers.json

@@ -9,12 +9,14 @@
     ".claude/agents/test-writer.md",
     ".claude/agents/code-reviewer.md",
     ".claude/agents/security-scanner.md",
+    ".claude/agents/prose-reviewer.md",
     ".claude/hooks/block-no-verify.mjs",
     ".claude/hooks/guard-bash.mjs",
     ".claude/hooks/gate-stop-dod.mjs",
     ".claude/hooks/inject-rules.mjs",
     ".claude/skills/pr-ship/SKILL.md",
     ".claude/skills/loop/SKILL.md",
+    ".claude/skills/check-premises/SKILL.md",
     ".claude/skills/worktree-task/SKILL.md",
     ".claude/scripts/detect-missed-gate.mjs",
     ".claude/scripts/reconcile-external-prs.mjs",