create-agent-rig 0.9.1 → 0.10.0

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

@@ -28,7 +28,7 @@ same four steps with the diff as the code, and §4 carries what is different.
 
 **What "rulebook prose" means here is not a new list** — it is the set
 `.claude/rules/workflow.md` already uses for the `prose-reviewer` trigger: a rule
-file, a skill, an agent spec, a decision record, `CLAUDE.md`, the README. Where a
+file, a skill, an agent spec, a decision record, `CLAUDE.md`, `AGENTS.md`, the README. Where a
 rulebook file exists twice (a template source and a generated copy), check the
 **source**; the copy is composed from it. A comment in a test or a hook is in scope
 too when it asserts behaviour — the file it lives in does not change what a claim is.
@@ -36,8 +36,8 @@ too when it asserts behaviour — the file it lives in does not change what a cl
 🔴 **`PREMISE FALSE` belongs to the first entry point only.** At the second one the
 claims are your own and the remedy is an edit, so a false one is not an escalation:
 it is `UNMEASURED`'s neighbour — delete or correct the sentence and carry on. Reading
-it as the escalation `loop` §6 defines would send a finished branch back to the queue
-over one sentence.
+it as the escalation `loop` §6 (opt-in workflow layer) defines would send a
+finished branch back to the queue over one sentence.
 
 ## Why it sits here and not in review
 
@@ -185,9 +185,13 @@ inside the block; both forms are the contract.
   actually says, and `file`/`line` is the citation §3 requires.
 - `PREMISES_HOLD` carries an empty `blockers` list; the other three name at
   least one. A stop verdict without one is not an answer the caller can act on,
-  and the caller is what checks: the `loop` skill runs
-  `node .claude/scripts/verdict.mjs check <report> check-premises` on what you
-  return. Nothing in this skill runs it — this skill writes nothing at all.
+  and the caller is what checks: `node .claude/scripts/verdict.mjs check
+  <report> check-premises` on what you return — `verdict.mjs` is Core and runs
+  standalone, so the caller is whichever session invoked this skill (this is a
+  Core skill, meant to run with no queue and no loop); the `loop` skill (opt-in
+  workflow layer) runs the same command the same way when it is the one that
+  invoked you. Nothing in this skill runs it — this skill writes nothing at
+  all.
 - **`headSha` is the commit you read** — `git rev-parse HEAD` in the checkout
   you examined. A premise check answers about a tree, and the tree moves.
 
@@ -231,6 +235,6 @@ is invisible to every gate downstream.
   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.
+  (the `loop` skill — opt-in workflow layer — 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/.agents/skills/loop/SKILL.md

@@ -12,7 +12,7 @@ decisions. 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: (worktree if another session may run) → `check-premises` on the
-item → failing test first → implement → **`check-premises` again, on your own prose**
+item → failing test first (`test-writer`) → implement (`implementation-agent`) → **`check-premises` again, on your own prose**
 → `pr-ship` → merge on the named criterion → verify the deployed surface if one
 changed.
 
@@ -344,7 +344,7 @@ it only here. A tier outside that vocabulary **holds**, never releases
 (`docs/decisions/spacing-rations-mechanisms.md`).
 
 **The tier marker is a pre-filter, not the authority.** If an item passed as normal
-and the work turns out to touch an elevated path (`CLAUDE.md` →
+and the work turns out to touch an elevated path (`AGENTS.md` →
 `elevated-paths`), run the gate anyway, record the verdict on the PR, and treat it
 as this run's elevated item for spacing.
 
@@ -842,8 +842,8 @@ unbounded improvement list is another diary, and three forces a choice. Each nam
 four things, and a proposal missing any of them is not ready to file:
 
 1. the finding it came from, cited as the journal line it appears on;
-2. the part to change — a skill, an agent spec, a hook, a rule file, `CLAUDE.md`,
-   the CI workflow;
+2. the part to change — a skill, an agent spec, a hook, a rule file, `AGENTS.md`,
+   `CLAUDE.md`, the CI workflow;
 3. the change, concretely enough to diff;
 4. how the next run would prove it worked — the observation that would differ.
 
@@ -858,7 +858,7 @@ node --input-type=module -e '
   const a = await import("./.claude/scripts/queue/plan-md.mjs");   // or github-issues / jira
   console.log(await a.proposeTriage({
     finding: "<the journal line it came from>",
-    part:    "<skill | agent | hook | rule | CLAUDE.md | workflow>",
+    part:    "<skill | agent | hook | rule | AGENTS.md | CLAUDE.md | workflow>",
     change:  "<concretely enough to diff>",
     proof:   "<the observation that would differ next run>",
     // a pair: what the probe touched, and what is concluded from it. The
@@ -961,9 +961,34 @@ three poisons the only channel by which this project learns.
   underneath it:
 
   ```bash
-  node .claude/scripts/revalidate.mjs --point BEFORE_CLOSE --ticket <item-id>
+  node .claude/scripts/revalidate.mjs --point BEFORE_CLOSE --ticket <item-id> \
+    --merge-commit "$(gh pr view <pr> --json mergeCommit -q .mergeCommit.oid)"
   ```
 
+  `--merge-commit` names the exact SHA the tracker's own PR metadata records as
+  THIS item's merge commit — one piece of evidence among several that let a
+  `targetSha` move which is nothing but that merge read as `CURRENT` instead
+  of `claim:scope` drift. Resolve it from the PR just merged, by name, never by
+  reading `git log` text, and only after the merge has landed and been
+  fetched. Omitting it (the item has not merged yet, or an older loop that
+  predates this flag) leaves any target movement holding exactly as it did
+  before this flag existed — it is purely additive to that default. Naming the
+  SHA is necessary but never sufficient: the exemption also requires the
+  target to have advanced by EXACTLY ONE commit — a genuine squash merge; a
+  merge commit or any multi-commit range still holds
+  (`test/template/revalidate.test.ts` (absent in a generated rig) › "a foreign
+  commit plus the real merge in the same range, --merge-commit correctly
+  naming the real one") — and it binds to THIS checkout: the named commit's
+  tree must equal `HEAD`'s tree here, and `HEAD` must still be the pre-merge
+  checkout, not one already fast-forwarded onto the merge
+  (`test/template/revalidate.test.ts` (absent in a generated rig) › "a single
+  FOREIGN commit named as --merge-commit does not exempt it — reproduces the
+  gate-hold attack and proves it now holds" and › "HEAD already at the merge
+  commit is vacuous, and still holds (a fast-forwarded checkout must not
+  self-satisfy the exemption)"). That binding stops a lazy or mistaken flag,
+  not an adversary who controls this run's own checkout — see
+  `isOwnMergeAdvance` in `claim-records.mjs` for the exact limit.
+
   It compares the tracked claim's `scope` and `commentary` fingerprint sets;
   commentary becomes hold-authoritative only here. Marker/take-up movement is
   retained in evidence but cannot decide drift. A missing claim is

package/templates/agent-os/universal/.agents/skills/new-invariant/SKILL.md

@@ -94,9 +94,9 @@ is a booby trap: someone will hit it, not understand it, and route around it.
 - [ ] The rule is written down, with the hook named next to it
 - [ ] The hook guards **one** invariant, and its scope is as narrow as the rule
 
-## A candidate that is already sitting there
+## Choosing a candidate
 
-The stack rules say service code logs through the shared structured logger, never
-`console.log` — and nothing enforces it. That is the invariant the shipped example
-encodes, so if the rule matters in your project, promoting the example into a real
-hook is a copy, a rename and a wiring line.
+Start from a rule that already matters in this project and has been violated or
+missed in review. Do not invent a sample architecture rule just to exercise this
+skill: the hook must protect a real local invariant, and its test must demonstrate
+the exact violation it blocks.

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

@@ -257,7 +257,7 @@ blockers.
    - `security-scanner` when the diff touches auth, secrets or configuration,
      input parsing, file handling, new outbound calls, dependency changes;
    - `prose-reviewer` when the diff touches a rule file, a skill, an agent spec,
-     a decision record under `docs/decisions/`, `CLAUDE.md` or the README — a
+     a decision record under `docs/decisions/`, `CLAUDE.md`, `AGENTS.md` or the README — a
      rulebook that overstates its own enforcement fails silently and in the
      direction of false confidence;
    - an infrastructure review when it touches infrastructure (the stack layer

package/templates/agent-os/universal/.agents/skills/worktree-task/SKILL.md

@@ -12,9 +12,9 @@ directories, with one `.git`. Without it, an unattended run and a hand-driven
 session share a working tree and overwrite each other's edits.
 
 **Use one when** anything else may touch this repo while you work — an
-unattended `loop` run, a colleague, a second Claude session. A single attended
-session on a quiet repo can just use a branch; the discipline that is never
-optional is the branch, not the worktree.
+unattended `loop` run (opt-in workflow layer), a colleague, a second Claude
+session. A single attended session on a quiet repo can just use a branch; the
+discipline that is never optional is the branch, not the worktree.
 
 ## Start
 

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

@@ -1,6 +1,6 @@
 ---
 name: code-reviewer
-description: Reviews a completed change against the checklist before a PR is opened or merged. Use after any non-trivial implementation work, and always before opening a PR the decision-router puts on its `model` lane, which is everything its two cheap lanes did not claim — code, a rulebook document, an unclassifiable path, a derived artifact git does not report as drift, or anything a risk flag escalated. Blocking findings must be resolved, not argued with.
+description: Reviews a completed change against the checklist before a PR is opened or merged. Use after any non-trivial implementation work, and always before opening a PR that reaches the `model` lane — everything the two cheap lanes do not claim (code, a rulebook document, an unclassifiable path, a derived artifact git does not report as drift, or anything a risk flag escalated), decided by `decision-router.mjs` where the opt-in workflow layer is installed, or by the same rule applied by hand otherwise. Blocking findings must be resolved, not argued with.
 tools: Read, Grep, Glob, Bash
 model: claude-opus-5
 effort: high
@@ -11,9 +11,9 @@ references, and you classify every finding as **blocking** or **advisory**.
 
 ## Checklist (blocking findings)
 
-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 the architecture rules in `.claude/rules/`.
+1. **Boundary violations** — changes that bypass module ownership or layer
+   boundaries the repository itself declares. See any applicable 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
@@ -88,5 +88,7 @@ reads; a report that never writes one is read as whatever the caller expected.
   checkout you read. It is what lets `node .claude/scripts/verdict.mjs coverage
   <commit>` tell "this gate answered for the commit being merged" from "it
   answered two pushes ago". A verdict naming no commit is counted as neither
-  covered nor missing, so `pr-ship` holds on it — and only `pr-ship`: no hook
-  runs that check, so a session that skips the gate skips this with it.
+  covered nor missing, so whoever runs that check holds on it —
+  `pr-ship` where the opt-in workflow layer is installed, the session itself
+  running `node .claude/scripts/verdict.mjs coverage` by hand otherwise: no
+  hook runs it either way, so skipping the gate skips this with it.

package/templates/agent-os/universal/.claude/agents/implementation-agent.md

@@ -0,0 +1,41 @@
+---
+name: implementation-agent
+description: Writes the minimum production code that makes an existing failing test pass — the Green step of TDD, and the Refactor that follows it. Use for ordinary implementation work once test-writer has produced the failing test.
+tools: Read, Grep, Glob, Write, Edit, Bash
+model: claude-sonnet-5
+effort: high
+---
+
+You make a failing test pass. You are the Green step of TDD, and the Refactor
+that keeps it green — never the Red step, and never the reviewer of your own
+work.
+
+## Scope — hard boundaries
+
+- You start from a failing test that already exists. If there is none, stop
+  and say so: the test comes first, from `test-writer`.
+- You never delete, skip, weaken or rewrite a test to make it pass. If a test
+  looks wrong, stop and surface the conflict instead of editing it.
+- You change only what the task needs. Unrelated files, formatting sweeps and
+  speculative abstractions are out of scope.
+- You do not commit, push, merge or open pull requests; the session that
+  dispatched you owns the branch and the gates.
+
+## How you work
+
+1. Read the failing test and the code around it; follow the repository's
+   rules in `AGENTS.md` and `.claude/rules/`.
+2. Write the smallest change that makes the test pass, in the style of the
+   surrounding code.
+3. Run the new test, then the suite, lint and typecheck the rules name.
+   Report a red check as information; never retry it until it passes.
+4. Refactor only with the tests green, then run them again.
+5. Report back: what you changed and why, which checks you ran with their
+   results, and anything you found but did not change.
+
+## Judgment lines
+
+- When the change reaches an elevated area the task was not already tiered
+  for, stop and say so before changing it.
+- When two rules in the repository conflict, stop and name both.
+- Prefer deleting code to adding it when both satisfy the test.

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

@@ -1,13 +1,15 @@
 ---
 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.
+description: Reviews the documents that instruct agents — rule files, skills, agent specs, AGENTS.md, 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
 model: claude-sonnet-5
 effort: high
 ---
 
 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
+reads before it acts; a skill is a procedure; `AGENTS.md` is the map (`CLAUDE.md`
+is its short Claude Code shim — see `docs/decisions/agents-md-canonical.md`).
+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.
 
@@ -177,5 +179,7 @@ calling gate reads.
   checkout you read. It is what lets `node .claude/scripts/verdict.mjs coverage
   <commit>` tell "this gate answered for the commit being merged" from "it
   answered two pushes ago". A verdict naming no commit is counted as neither
-  covered nor missing, so `pr-ship` holds on it — and only `pr-ship`: no hook
-  runs that check, so a session that skips the gate skips this with it.
+  covered nor missing, so whoever runs that check holds on it —
+  `pr-ship` where the opt-in workflow layer is installed, the session itself
+  running `node .claude/scripts/verdict.mjs coverage` by hand otherwise: no
+  hook runs it either way, so skipping the gate skips this with it.

package/templates/agent-os/universal/.claude/agents/security-scanner.md

@@ -78,5 +78,7 @@ the human who has to fix the finding.
   checkout you read. It is what lets `node .claude/scripts/verdict.mjs coverage
   <commit>` tell "this gate answered for the commit being merged" from "it
   answered two pushes ago". A verdict naming no commit is counted as neither
-  covered nor missing, so `pr-ship` holds on it — and only `pr-ship`: no hook
-  runs that check, so a session that skips the gate skips this with it.
+  covered nor missing, so whoever runs that check holds on it —
+  `pr-ship` where the opt-in workflow layer is installed, the session itself
+  running `node .claude/scripts/verdict.mjs coverage` by hand otherwise: no
+  hook runs it either way, so skipping the gate skips this with it.

package/templates/agent-os/universal/.claude/agents/test-writer.md

@@ -31,8 +31,8 @@ step of TDD, and only the Red step.
 
 ## Judgment lines
 
-- Test behavior through public entry points (usecases, handlers), not private
-  internals.
+- Test behavior through public entry points and documented interfaces, not
+  private internals.
 - One behavior per test; shared setup in fixtures, not copy-paste.
 - If the requested behavior contradicts an existing test, stop and surface the
   conflict instead of overwriting the old test.

package/templates/agent-os/universal/.claude/hooks/inject-rules.mjs

@@ -28,6 +28,22 @@
 // the whole file pays for it twice. That is harness behaviour, observable but
 // not pinned here. Where it does not hold, this is a plain subtraction — which
 // is why every ambiguity resolves toward injecting more.
+//
+// The output on stdout is a single JSON object —
+// `{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":…}}`
+// — not the plain text an earlier version of this hook wrote directly. Both
+// Claude Code and Codex document that shape as valid SessionStart output
+// (Claude Code: code.claude.com/docs/en/hooks; Codex:
+// learn.chatgpt.com/docs/hooks), and Codex additionally documents plain text
+// as accepted for `session_start` — this hook always emits the JSON form
+// anyway, so one code path satisfies both without guessing which harness is
+// asking. The change exists because Codex 0.154.0 on Windows was measured
+// reporting this hook's OLD plain-text banner as invalid SessionStart JSON,
+// so the rules refresh never reached the session; Claude Code was unaffected.
+// The mechanism Codex used to reach that verdict is not published — a leading
+// `[` is a plausible trigger, not a confirmed one. See
+// `docs/decisions/session-start-wire-format.md` for what was measured and
+// what each harness's own documentation says.
 import { readFileSync, realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { readHookInput } from './lib/hook-input.mjs';
@@ -187,15 +203,78 @@ function main() {
       ? 'This is `.claude/rules/autonomy.md` in full.\n\n'
       : 'This is `.claude/rules/autonomy.md` with the sections it marks as ' +
         'reference removed — read the file itself for those: how the Tier-2 ' +
-        'gate is swept from outside, how external work is reconciled, ' +
-        'post-deploy verification, and the escalation format.\n\n';
+        'gate is swept from outside (opt-in workflow layer), how external ' +
+        'work is reconciled, post-deploy verification, and the escalation ' +
+        'format.\n\n';
+
+  const additionalContext =
+    `[agent-os] Autonomy rules refresh — in force regardless of compaction.\n${notice}${body}\n`;
 
+  // `hookSpecificOutput.additionalContext` is the JSON shape both harnesses'
+  // hooks documentation gives an example of for SessionStart output — see the
+  // file header and `docs/decisions/session-start-wire-format.md`. No leading
+  // or trailing byte outside the object, and no trailing newline: Claude Code's
+  // OWN documented detection reads "starts with `{` ends with `}`", literally
+  // (code.claude.com/docs/en/hooks) — Codex's JSON-vs-plain-text detection is
+  // not published, so this satisfies the one contract that IS written down
+  // rather than guessing at the one that is not.
+  // A reader that vanishes mid-write — a closed pipe, a harness that tears
+  // this process down before reading — turns the queued write into an EPIPE.
+  // That specific error is silenced: it means the reader is gone and there is
+  // nothing left to report to, so failing loudly would turn an absent reader
+  // into a noisy non-zero SessionStart exit for no one to read. Anything ELSE
+  // stdout can fail with (ENOSPC, EIO, a redirect to a full or broken device)
+  // is a real write failure with an actual reader still attached, and this
+  // file does not get to treat that as a healthy session: it is reported on
+  // stderr and the exit is marked non-zero, the same "say what happened"
+  // stance the excerpt path takes by injecting MORE rather than dropping
+  // content quietly. Measured (security review, RP-185 gate): a blanket
+  // handler here made a genuine stdout write failure (stdout redirected to
+  // /dev/full) exit 0 with nothing delivered and no diagnostic — exactly the
+  // silent-loss shape this whole file exists to avoid, just moved one write
+  // call over. Pinned in hooks.test.ts (absent in a generated rig) ›
+  // "silently exits 0 when the reader is gone before the write starts
+  // (EPIPE)" and › "reports a genuine stdout write failure on stderr and
+  // marks the exit non-zero, rather than looking like a healthy session".
+  process.stdout.on('error', (err) => {
+    if (err && err.code === 'EPIPE') return;
+    process.stderr.write(`inject-rules: stdout write failed: ${err}\n`);
+    process.exitCode = 1;
+  });
   process.stdout.write(
-    `[agent-os] Autonomy rules refresh — in force regardless of compaction.\n${notice}${body}\n`,
+    JSON.stringify({
+      hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext },
+    }),
   );
   return 0;
 }
 
 if (invokedDirectly()) {
-  process.exit(main());
+  // NOT process.exit(main()): exit() tears the process down without waiting
+  // for a queued stdout write to drain, and this hook's payload (the whole
+  // rules excerpt, wrapped in one JSON object) can be large enough to miss a
+  // pipe's buffer in one write. A write that process.exit() cuts off mid-object
+  // is not a short excerpt, the way the old plain-text form degraded — it is
+  // invalid JSON, which is exactly the failure this hook exists to avoid.
+  // Every path through main() returns 0, so setting exitCode changes nothing
+  // about the exit STATUS. What it does change is whether the process
+  // terminates AT ALL before the write finishes: exitCode lets the event
+  // loop drain naturally, and a reader that never drains at all no longer
+  // gets a fast, wrong exit 0 — it gets a hook that stays alive, waiting on
+  // the write, for as long as the harness lets it. A probe that refuses to
+  // read until the child would already have exited measurably DEADLOCKS this
+  // version where process.exit() would have terminated (truncated). Nothing
+  // in this file bounds that wait; the calling harness's own hook timeout
+  // does. Pinned in hooks.test.ts (absent in a generated rig) ›
+  // "delivers the whole envelope even when the reader does not drain until
+  // process.exit(main()) would already have torn the process down".
+  //
+  // That is the trade made on purpose — a loud hang, bounded by the
+  // harness's timeout, over a silent truncated "success" — and it is worth
+  // stating plainly rather than leaving to be discovered: not reachable at
+  // the size this hook ships today (a few KB, done in well under a second),
+  // but a real behaviour change on a project whose autonomy.md grows large
+  // enough, or whose harness stops reading a hook's stdout at all. See
+  // `docs/decisions/session-start-wire-format.md` for the fuller record.
+  process.exitCode = main();
 }

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

@@ -37,10 +37,10 @@ area *is* Tier 2 from that moment: run the gate, record the verdict on the PR,
 and say in the description that the tier changed mid-work.
 
 **Where the elevated paths of this project are written down:** the
-`elevated-paths` block in `CLAUDE.md`, plus any such block in `.claude/rules/` —
-the gate sweep reads them all and unions the result, so a stack layer declares the
-paths that exist only in its shape. A path declared in none of them is a path
-nothing checks.
+`elevated-paths` block in `AGENTS.md` (the canonical rulebook), plus
+any such block in `.claude/rules/` — the gate sweep reads them all and unions
+the result, so a stack layer declares the paths that exist only in its shape.
+A path declared in none of them is a path nothing checks.
 
 <!-- inject:skip -->
 <!-- `inject-rules` puts this WHOLE FILE into every session's context, minus
@@ -55,7 +55,13 @@ nothing checks.
      rules for whoever performs the sweep, which is not the run. If that stops
      being true, move them out rather than arguing with the marker. -->
 
-#### The gate is swept from outside, because a run cannot report this on itself
+#### The gate is swept from outside (opt-in workflow layer), because a run cannot report this on itself
+
+**`detect-missed-gate.mjs` and `reconcile-external-prs.mjs` below ship with
+the opt-in workflow layer** (`init --layer workflow`) — see `AGENTS.md`'s "The
+opt-in workflow layer" section. Without that layer, sweep merged PRs against
+the elevated-paths block by hand; the rule they enforce — a Tier-2 change
+needs a `human-review` label — does not change with or without the script.
 
 A run that continued past the Tier-2 gate is exactly the run that **will not
 report it** — a run that had known was a run that would have run the gate. So the
@@ -123,11 +129,16 @@ own cost figures are read next to the lane they do not cover.
   from proper-prefix widening". An entry
   outside the set — ordinary source — is not widening and is accepted. A second
   copy in prose is a copy that goes stale, and this one did. Mechanical:
-  the hook refuses the edit while the unattended flag the `loop` skill writes
-  at claim time is on disk (`.claude/scripts/unattended-flag.mjs`), and does
-  nothing in an attended session. ⚠ It sees edit tool calls only — a
-  shell redirect into a protected file is not one — and the flag, not
-  the run, is what arms it; its header states the rest of its limits.
+  the hook refuses the edit while the unattended flag is on disk
+  (`.claude/scripts/unattended-flag.mjs`, Core — usable by hand on any rig),
+  and does nothing in an attended session. **On a Core-only rig nothing arms
+  this flag automatically** — the `loop` skill, opt-in workflow layer, is
+  what writes it at claim time; without that layer the flag is only ever set
+  by someone running `unattended-flag.mjs on` directly, so `guard-rulebook`'s
+  unattended-only refusal stays dormant unless an operator arms it by hand.
+  ⚠ It sees edit tool calls only — a shell redirect into a protected file is
+  not one — and the flag, not the run, is what arms it; its header states
+  the rest of its limits.
 
 ## Stop rules — by work-state, not by feelings
 
@@ -153,16 +164,23 @@ these lines is the failure mode:
   stop, write a short summary of state and intent, and **start fresh** from
   the summary. Resuming a stale session is how agents edit files that are not
   there anymore.
-- **A deploy that regressed.** A green pipeline is not a healthy runtime, so
-  every deploy ends in a verdict and **both words get recorded**:
+- **A deploy that regressed.** A green pipeline is not a healthy runtime:
+  verify runtime health after every deploy, and on a regression, **revert
+  first, diagnose second** — never fix-forward blind on a broken runtime.
+  **With the opt-in workflow layer installed** (`init --layer workflow`;
+  `run-state.mjs` ships only with it — a Core-only rig has no such file),
+  both words also get recorded as a mechanical verdict:
   `node .claude/scripts/run-state.mjs deploy HEALTHY` or `… deploy REGRESSION`.
-  On a regression, **revert first, diagnose second**. `REGRESSION` is what
-  makes the next selection refuse to build on it, and `HEALTHY` is the only
-  thing that clears one — a run that reverts, redeploys, verifies and then
-  stops at "healthy → done" has left the refusal latched behind it. The
-  procedure behind the verdict is further down this file; the verdict is here
-  because a compacted run has to carry it at the moment it is under the most
-  pressure.
+  `REGRESSION` is what makes the next selection refuse to build on it, and
+  `HEALTHY` is the only thing that clears one — a run that reverts, redeploys,
+  verifies and then stops at "healthy → done" has left the refusal latched
+  behind it. Without the layer, there is no automated selection to gate, and
+  no journal either (workflow layer only, `PLAN.md`) — the verify-then-revert
+  rule still applies, and the record of it is whatever this project's own
+  operational notes are (a PR description, a commit message, telling the
+  human directly), never a file `queue/index.mjs next` reads. The procedure
+  behind the verdict is further down this file; the verdict is here because a
+  compacted run has to carry it at the moment it is under the most pressure.
 
 <!-- inject:skip -->
 <!-- Not carried into a session's context (see the note on the first marked
@@ -181,19 +199,29 @@ logs — the target's README says which). The verdict is binary:
 - Regression → **revert first**, diagnose second. Never fix-forward blind on a
   broken runtime.
 
-**Record the verdict where the next selection reads it**, or it stops nothing —
-an unattended run's memory of "the deploy went badly" does not survive a
-compaction, and the queue hands out the next item regardless:
+**`run-state.mjs` and the mechanism below ship with the opt-in workflow
+layer** (`init --layer workflow`). The rule — verify before calling a deploy
+done, revert first on a regression — applies regardless; without this layer
+there is no automated selection to gate, and no journal either (workflow
+layer only, `PLAN.md`) — recording the verdict is whatever this project's own
+operational notes are (a PR description, a commit message, telling the human
+directly), never a file the next `queue/index.mjs next` reads.
+
+**Record the verdict where the next selection reads it** (opt-in workflow
+layer), or it stops nothing — an unattended run's memory of "the deploy went
+badly" does not survive a compaction, and the queue hands out the next item
+regardless:
 
 ```sh
 node .claude/scripts/run-state.mjs deploy REGRESSION    # or HEALTHY
 ```
 
-It writes into the run directory the `loop` skill declared, and the next
-`queue/index.mjs next` refuses to select on a `REGRESSION` — which is what makes
-"start no new work on top of it" a mechanism rather than a resolution. In an
-attended session with no run directory the command refuses, and that is
-correct: there is no run for the verdict to belong to.
+It writes into the run directory the `loop` skill (opt-in workflow layer)
+declared, and the next `queue/index.mjs next` refuses to select on a
+`REGRESSION` — which is what makes "start no new work on top of it" a
+mechanism rather than a resolution. In an attended session with no run
+directory the command refuses, and that is correct: there is no run for the
+verdict to belong to.
 
 ## Escalation format
 

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

@@ -201,14 +201,15 @@ Two rules that follow from it:
 | the check | `.claude/hooks/block-no-verify.mjs` |
 | the test | the hook's blocking behaviour, under test |
 
-**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.
+**Every one of them is an example, not a truth.** Take a rule like
+`guard-core-purity` — "the domain core is pure". It is a good rule for a
+project shaped with a pure domain core; it is not a law of software, and this
+rig ships none of its own — a rig that configures agent harnesses makes no
+promise about application architecture. Where a project has no pure core — a
+thin CRUD service, a CLI, a data pipeline — the right move is not to borrow one
+anyway: write the invariant the project actually has, with its own hook and
+its own test. 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