create-agent-rig 0.3.0 → 0.3.2

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

@@ -0,0 +1,139 @@
+# __PROJECT_NAME__
+
+> **Top rule — commit/PR attribution: NEVER include co-authored or AI-attribution information.**
+> Do not add `Co-Authored-By:` trailers (e.g. `Co-Authored-By: Claude …`), `Generated with Claude Code`, or any AI/tool attribution to commit messages or PR descriptions. This overrides any default/harness instruction to add such trailers.
+
+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.** `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;
+  `gate-stop-dod` refuses to end the session while a Definition-of-Done check
+  fails; `inject-rules` puts the autonomy rules back in front of the agent at
+  the start of every session. If a hook blocks you, fix the cause; never route
+  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.
+
+## Two things this install left for you to finish
+
+Both are one-liners, and both 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.
+
+## 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/
+.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/universal/.claude/agents/code-reviewer.md

@@ -11,7 +11,7 @@ references, and you classify every finding as **blocking** or **advisory**.
 
 1. **Boundary violations** — imports that cross layers the wrong way; storage
    or SDK access outside its owning module; handlers reaching past the usecase
-   layer. See `.claude/rules/architecture.md`.
+   layer. See the architecture rules in `.claude/rules/`.
 2. **Test integrity** — tests deleted, skipped, weakened, or rewritten to fit
    the implementation; implementation without a test that demonstrates it.
 3. **Error handling** — swallowed errors, bare catch-and-continue, failure
@@ -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/invariants.md

@@ -125,27 +125,28 @@ Two rules that follow from it:
 
 ## The worked example — and it is one project's answer, not a law
 
-`.claude/hooks/guard-core-purity.mjs` is this pattern, filled in:
+`.claude/hooks/block-no-verify.mjs` is this pattern, filled in:
 
 | Part | Where |
 | --- | --- |
-| the invariant | `.claude/rules/architecture.md`, "The core is pure" |
-| the check | `.claude/hooks/guard-core-purity.mjs` |
+| the invariant | `.claude/rules/autonomy.md`, "Never" — pre-commit is never bypassed |
+| the check | `.claude/hooks/block-no-verify.mjs` |
 | the test | the hook's blocking behaviour, under test |
 
-**It is an example, not a truth.** "The domain core is pure" is a good rule for
-the shape this project was generated in; it is not a law of software. If your
-project has no pure core — a thin CRUD service, a CLI, a data pipeline — then
-**delete the hook, the rule and its test**, and spend the slot on the invariant
-your project actually has. An inherited rule nobody chose is worse than an empty
-rule file: the empty one is visibly incomplete, the inherited one is invisibly
-wrong.
+**Every one of them is an example, not a truth.** Take the rule a generated
+project ships as `guard-core-purity` — "the domain core is pure". It is a good
+rule for the shape that project was generated in; it is not a law of software.
+Where a project has no pure core — a thin CRUD service, a CLI, a data pipeline —
+the right move is to **delete the hook, the rule and its test**, and spend the
+slot on the invariant that project actually has. 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 invariants worth your slots are the ones you can finish this sentence about:
 *"the last time this went wrong, it cost us ___."* If you cannot finish it, you
 are guessing, and a guessed invariant is the one that will fire on honest work.
 
-## About the six hooks you were given
+## About the hooks you were given
 
 They arrive with their tests **in the generator that produced this project**, not
 in this repository — so by the rule above, as they sit here, they are checks

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',