create-agent-rig 0.6.2 → 0.7.0

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

@@ -45,7 +45,7 @@ composed file:
 
 ```bash
 node .claude/scripts/queue/index.mjs board        # the active board and the declared ones
-node .claude/scripts/queue/index.mjs board RP     # switch this checkout: writes .claude/queue.board
+node .claude/scripts/queue/index.mjs board <board-id>  # switch this checkout: writes .claude/queue.board
 ```
 
 The selector is per-checkout runtime state, the same class as
@@ -79,13 +79,14 @@ state-vs-queue split exists to prevent.
 node .claude/scripts/preflight.mjs
 ```
 
-Four items are scripted (kill switch absent · `RIG_RUN_DIR` not already
-exported · local default branch matches the remote · the last deploy concluded
-successfully) and the script **prints the ones it did not check, every time**. Paste the block into the journal: a checklist that
+Five items are scripted (kill switch absent · `RIG_RUN_DIR` not already
+exported · the versioned revalidation detection contract is supported · local
+default branch matches the remote · the last deploy concluded successfully)
+and the script **prints the ones it did not check, every time**. Paste the block into the journal: a checklist that
 leaves no record cannot tell you it was skipped.
 
 Verdicts: **STOP** → do not start, deal with the cause. **CAUTION** → start,
-knowing which ground is soft. **GO** → the scripted four are clean; the rest are
+knowing which ground is soft. **GO** → the scripted five are clean; the rest are
 still yours.
 
 **An `unknown` never becomes a `pass`.** A probe that could not run tells you
@@ -118,9 +119,31 @@ mkdir -p "$RIG_RUN_DIR"
 never with a variable the session exported — pinned in the generator's
 `test/template/guard-rulebook.test.ts` (absent in a generated rig) › "only a
 flag arms it — an exported RIG_UNATTENDED=1 with no flag changes nothing" —
-and in some harnesses the export does not even survive to the next Bash call,
-which is why every command in this skill can also take the run directory per
-invocation. What a hook CAN see is a file, so the unattended signal is one:
+and in some harnesses the export does not even survive to the next Bash call.
+
+🔴 **So re-export it in every call that needs it.** `RIG_RUN_DIR` is how the run
+directory reaches the commands that read it from the environment — and two of
+the commands this skill invokes read it from somewhere else instead.
+`unattended-flag.mjs` does not read the variable; it takes the directory as
+`--run-dir`, which is why the call below passes it explicitly.
+`revalidation-report.mjs` does not read it either; it takes `--runs <dir>`.
+For every other command this skill invokes the variable is the whole of it, and
+passing the flag is not a fallback but an unrecognised argument — after which a
+command writes into a run directory nobody declared, or refuses for want of one
+while the caller believes it was told. Modules this skill *imports* rather than
+invokes are a third case again: `run-journal.mjs` and `queue/state.mjs` are
+handed a `runDir` by their caller, which is why §9 lists it among the details
+that must be copied rather than re-derived.
+
+`--run-dir` is taken by `unattended-flag.mjs`, and by no other script under
+`.claude/scripts/`. That is measured over the whole tree rather than against a
+list, in both directions, by the generator's
+`test/template/correspondence.test.ts` (absent in a generated rig) › "names
+exactly the commands that take --run-dir, and only those" — so a script anywhere
+in that tree that gains the flag without this sentence gaining its name goes
+red.
+
+What a hook CAN see is a file, so the unattended signal is one:
 
 ```bash
 # at claim time, from the paths the item names (repo-relative prefixes, with
@@ -141,12 +164,11 @@ rig — › "blocks a hook-config edit with an empty allow-list, naming path, it
 
 ⚠ **The export outlives the run's own calls.** Everything the session spawns
 inherits it — and a test suite that spawns the queue CLI would write fixture
-records into this run's trace (AR-139: 38 fixture selections and 22 fixture
-revalidation events in one session, two tests exiting 1). So preflight refuses
-to start on a `RIG_RUN_DIR` already exported. The generator's own test harness
+records into this run's trace. So preflight refuses to start on a
+`RIG_RUN_DIR` already exported. The generator's own test harness
 also scrubs the variable before any test file loads — its `test/setup-env.ts`,
-pinned by its `test/template/rig-run-dir-scrub.test.ts` › "holds with the
-variable exported around the whole vitest process" — and **neither file ships
+pinned by its `test/template/rig-run-dir-scrub.test.ts` (absent in a generated
+rig) › "holds with the variable exported around the whole vitest process" — and **neither file ships
 into a generated rig**: here, nothing scrubs it, and a rig's own test setup is
 the place to do the same.
 
@@ -198,12 +220,12 @@ reported by `hygiene` as `owner-mismatch`. It clears the way `trigger-human`
 does: a human moves the item or re-marks it. An unmarked item is unconditional.
 Two items of another product once entered this queue as normal spacers and
 escalated `PREMISE FALSE` back to back — a run-level stop spent on work that
-was never this checkout's (AR-132). Pinned in the generator's
+was never this checkout's. Pinned in the generator's
 `test/template/queue-owner.test.ts` — absent in a generated rig — › "holds an
 item whose owner is another repository, with the cause named".
 
 🔴 **An item's lifecycle is a label a human wrote, and the loop infers none of
-it** (AR-144). Four words, read by `lifecycleOf` in `core.mjs` so every adapter
+it**. Four words, read by `lifecycleOf` in `core.mjs` so every adapter
 means the same thing — three of lifecycle, one of scheduling:
 
 - `keep-core` — the problem and the responsibility are valid and the item is
@@ -285,59 +307,72 @@ 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.
 
-**Selection also revalidates the item against its last take-up.** `next`
-records the selected item's `updatedAt` marker in the run state (`takeUps`) and,
-when the item is offered again, compares the two — against this run's take-up
-when it has one, otherwise against the newest earlier run's under `.claude/runs/`
-(AR-138: before that, an item taken up yesterday compared against nothing and
-read as a first sight). A proposal the loop files carries its own baseline: the
-`jira` and `github-issues` adapters record the filed item's marker as a take-up
-in the run that filed it. The event names which it used — `baseline:
-this-run | previous-run | null` — pinned in the generator's
-`test/template/revalidation-baseline.test.ts` — absent in a generated rig — ›
-"holds when the marker moved past the earlier run’s take-up, and names that
-baseline". A marker that
-moved prints a `revalidate:` line and the JSON carries `revalidation.changed:
-true`: **re-read the item before acting on it**, then record what the re-read
-concluded — whether the change altered the action is the evidence this exists to
-collect, and the comparison alone cannot supply it:
+**Selection is the first point of the one revalidation chain.** On the first
+successful SELECT, `next` creates a versioned content-blind baseline at
+`.rig/claims/<item-id>.json` and reports `BASELINE_CREATED`. Add that record to
+the task's branch: a later SELECT, BEFORE_PR or BEFORE_CLOSE refuses an
+untracked record, and a resumed checkpoint with no record is `UNVERIFIABLE`.
+The `scope` fingerprint set is authoritative at SELECT and BEFORE_PR and
+includes workflow state normalised to the state that checkpoint expects;
+`commentary` is observed there but becomes hold-authoritative only at
+BEFORE_CLOSE. Neither set stores title, description or comment bodies.
+For Jira and GitHub issues, the adapter's successful `claim` writes its
+observable `in-progress` transition into that same record as `workflowClaim`.
+Only that durable acknowledgement makes the claimed state expected at a resumed
+SELECT, BEFORE_PR or BEFORE_CLOSE; the same tracker state reached without it is
+external drift and HOLDs. PLAN.md remains `open` because it has no observable
+claim transition. The checkpoint-aware edge is pinned in the generator's
+`test/template/content-blind-revalidation.test.ts` (absent in a generated rig)
+› "keeps a resumed SELECT current after the Jira adapter records its own claim
+transition", › "GitHub claim records the durable transition that makes
+in-progress CURRENT", › "holds claim:scope at resumed SELECT for the same transition
+made outside the adapter", › "accepts an in-progress transition performed by
+the Jira adapter claim operation", and › "holds claim:scope when an external
+actor moves the item to the expected claimed state".
+The durable/evidence boundary and rollback rule are recorded in
+`docs/decisions/content-blind-revalidation.md`.
+
+`takeUps` and `updatedAt` remain in run state and in the event's `task` field as
+evidence/compatibility state. They do not decide `CURRENT`, `CHANGED`,
+`CONFLICT` or `UNVERIFIABLE`, do not decide whether a first baseline may be
+created, and never appear as a drift source. The event may still name
+`baseline: this-run | previous-run | null` so older evidence remains readable.
+First sight versus resume comes only from the SELECT events in the current and
+bounded sibling run journals. If those journals cannot prove first sight, a
+missing claim is `UNVERIFIABLE`; an `updatedAt` marker can neither create nor
+withhold the claim. Hitting the sibling entry/read cap makes that proof
+incomplete and therefore fails closed; "not found in the bounded subset" never
+means "never selected".
+
+On `CHANGED`, `CONFLICT` or `UNVERIFIABLE`, **re-read before acting**, then
+record what the re-read concluded:
 
 ```bash
 node .claude/scripts/revalidate.mjs outcome --point SELECT --ticket <item-id> --action-changed <true | false> --note '<what changed, or why it changes nothing>'
 ```
 
-It appends one `revalidation-outcome` record whose `answers` names the
-revalidation it resolves, so the report can pair the two without guessing. The
+It appends one typed `revalidation-outcome` record whose `detectionId` names the
+stable detection it resolves (and retains the legacy `answers` sequence), so
+the report can pair the two across harness runs without guessing. The
 note is stored verbatim from argv, so keep it in single quotes: inside double
 quotes the shell expands a backtick or a `$` before the command sees it.
 Nothing forces this record — a `revalidation` event with no matching outcome is
 counted as `unresolved`, which is the honest word for a re-read the run skipped.
 
-Under a declared run directory, every selection logs one `revalidation` event
-`{ticket, point: SELECT, changed, source, action, task}` — the same shape the
-BEFORE_PR and BEFORE_CLOSE points write. **No-change is always recorded**, one
-line per selection and no sampling: the rule is explicit so the report's
-`opportunities` is a count and not an estimate. An adapter with no marker
-(`plan-md`) logs `changed: null`, never "unchanged". ⚠ The marker also moves on
-the run's own claim and comments. The `jira` and `github-issues` adapters
-re-record the take-up after each write they make — claim, comment, close,
-escalate — so a move made through the adapter is not a hold (AR-140, from the
-journal's RX3/RX4 entry: every BEFORE_PR catch of that run was the run's own
-comment, counted by `revalidation-report.mjs`); a
-comment posted by any other route — a REST call by hand, a connector — still
-moves it like anyone else's, and a `true` can still be self-inflicted that way
-— the re-read decides, which is why the outcome is recorded separately, and a
-hold the re-read overturns is counted as a false hold with its source named.
-Pinned in the generator's `test/template/self-inflicted-marker.test.ts` — absent
-in a generated rig — › "%s leaves the take-up at the marker the write produced",
-an `it.each` over claim, comment, close and escalate. The
+Under a declared run directory, every selection logs one versioned
+`revalidation` detection — the same shape BEFORE_PR and BEFORE_CLOSE write.
+**No-change is always recorded**, one line per selection and no sampling: the
+rule is explicit so the report's `opportunities` is a count and not an estimate.
+The `jira` and `github-issues` adapters still re-record take-ups after their own
+writes for compatibility and attribution evidence; that state is never the
+fingerprint baseline. The
 four-week view is `node .claude/scripts/revalidation-report.mjs --since <date>`,
 over this rig's `.claude/runs/` (or a `--runs <dir>`). The behaviour is pinned in the
-generator's `test/template/queue-revalidation.test.ts` — absent in a generated
-rig — › "an adapter with no marker records a blind spot, not \"unchanged\"", ›
-"a moved marker holds on task:updatedAt, re-snapshots, and journals the change"
-and › "the loop skill's outcome command records what the re-read concluded", and
-in `test/template/revalidation-evidence.test.ts`.
+generator's `test/template/content-blind-revalidation.test.ts` (absent in a generated rig) › "creates a
+versioned content-blind claim and returns BASELINE_CREATED" and › "defers an
+added comment through SELECT and BEFORE_PR, then holds at BEFORE_CLOSE", plus
+`test/template/revalidation-evidence.test.ts` (absent in a generated rig) › "the journaled events of SELECT,
+BEFORE_PR and BEFORE_CLOSE share exactly the common keys and value types".
 
 **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
@@ -371,7 +406,7 @@ exits 1 whatever the reviewer said. Save the whole answer to a file under the ru
 directory — `$RIG_RUN_DIR/check-premises.md`, one file per gate so two answers
 never overwrite each other — and pass that path (`-` reads stdin instead). The
 same holds for every `<report>` in this skill, as `pr-ship` already does for its
-reviewers (AR-117). Pinned in the generator's `test/template/loop-report-file.test.ts`
+reviewers. Pinned in the generator's `test/template/loop-report-file.test.ts`
 — absent in a generated rig — › "states that the report is a file the session
 writes from the subagent answer, before the first check".
 
@@ -416,8 +451,8 @@ reviewer verdict, an exhausted gate-round cap, a false premise in the item itsel
 
 The run-level conditions are in `stopConditionOf` in `core.mjs`, checked in
 severity order: **queue unreadable** · **runtime regression** · **kill switch** ·
-**two escalations in a row** · **budget** · **nothing selectable** · **queue
-empty**.
+**revalidation hold** · **two escalations in a row** · **budget** · **nothing
+selectable** · **queue empty**.
 
 🔴 **Their inputs come from a file, not from your memory — and that is why they
 fire at all.** `escalations` and `lastDeployVerdict` live in
@@ -567,7 +602,7 @@ inventory of findings** — and this had to be settled, because the two readings
 disagreed the first time a stop arrived without an inventory. An exhausted
 gate-round cap names its stage (the gate) and its wall (the branch's rounds are
 spent — the count, not a verdict on whether the fixes were converging, which the
-counter never measured; AR-115), while the individual blockers behind it are not persisted anywhere until
+counter never measured), while the individual blockers behind it are not persisted anywhere until
 per-round verdicts exist. That is a `documented-stall`: the record locates the wall
 and the next reader knows where to look.
 
@@ -703,10 +738,13 @@ declared in §1. Five things about it are worth knowing before relying on it:
   so a stale record cannot read as the current one — which is the whole failure a
   journal exists to prevent.
 - ⚠ **The trace can stop before the run does, and the two failures part ways
-  here.** A journal that can no longer accept records — a sequence already
-  broken, a file that will not parse, a run already marked ended — is a lost
-  trace, **not** a reason to withhold work the queue can still hand out: the
-  selection prints, stderr carries a `run journal:` line, the exit code stays 0.
+  here.** After a durable claim exists, a journal that can no longer accept
+  records — a sequence already broken, a file that will not parse, a run already
+  marked ended — is a lost trace, **not** by itself a reason to withhold work the
+  queue can still hand out: the selection prints, stderr carries a `run journal:`
+  line, and the claim still decides drift. Before the first claim, the boundary
+  is stricter: an unreadable current or bounded sibling journal means SELECT
+  cannot prove first sight, so an absent claim is `UNVERIFIABLE` and exits 2.
   The refusals are the ones where nothing has happened yet and a second fixes
   it, and there are **four**: the declaration is empty, its directory does not
   exist, the path is not a directory, or the journal module is missing. Each
@@ -793,10 +831,10 @@ node --input-type=module -e '
 
 A proposal missing any of the four parts is refused rather than filed half-formed.
 
-**A finding can say what it measured and what it inferred, as two paired fields**
-(AR-142). A proposal whose premise was never true had no check at filing, only at
-take-up — AR-124 was filed, promoted and claimed before its platform conclusion
-was traced to a probe that had touched one hook. So `measured` and `inferred`
+**A finding can say what it measured and what it inferred, as two paired fields.**
+A proposal whose premise was never true had no check at filing, only at take-up
+— one such proposal was filed, promoted and claimed before its platform
+conclusion was traced to a probe that had touched one hook. So `measured` and `inferred`
 are separate, and `validateProposal` refuses an `inferred` that cites a path
 `measured` does not, naming both fields and the path; one field without the
 other is refused too, and neither files as before. The surface is a cited path
@@ -805,7 +843,7 @@ catches the path-shaped overreach and nothing subtler.
 
 ⚠ **The pair is how a proposal opts into the check, and a proposal filed without
 it is not checked at all** — `validateProposal` keeps the four-part contract, so
-the AR-124 shape with neither field still files as it always did. That is the
+that shape with neither field still files as it always did. That is the
 stated limit, not an oversight: making the fields mandatory would refuse every
 proposal the three adapters already file, and the loop is the author this rule
 is for. So **every proposal this loop files carries both fields** — the snippet
@@ -826,7 +864,7 @@ reports one whose cited paths changed since its `asOf` as
 one git cannot diff from as `proposal-asof-unanswerable` — never as clean. Two
 proposals in a row once escalated `PREMISE FALSE` because the merge that
 falsified each landed after it was filed, and selection hands out the oldest
-first (AR-116). The behaviour is pinned in the generator's
+first. The behaviour is pinned in the generator's
 `test/template/proposal-asof.test.ts` — absent in a generated rig — ›
 "names the overtaken one, the unanswerable one, and stays silent on the current one".
 
@@ -843,7 +881,7 @@ the selection query cannot reach. Add the heading — never the Agent queue.
 
 One adapter needs the second argument the snippet above carries: `jira` requires
 `options.project` and throws rather than filing without it — loudly, so nothing
-is lost, but a call that drops it files nothing (AR-117).
+is lost, but a call that drops it files nothing.
 
 🔴 **The loop proposes; the owner patches.** Self-applying a change to its own
 rulebook is how an unattended run drifts irreversibly, and it collides head-on
@@ -879,20 +917,19 @@ three poisons the only channel by which this project learns.
   the very next query.
 - **Closing:** first ask whether the item is still the item you took up — a
   late comment or a status somebody else moved is not published as `Done`
-  underneath it (AR-135):
+  underneath it:
 
   ```bash
   node .claude/scripts/revalidate.mjs --point BEFORE_CLOSE --ticket <item-id>
   ```
 
-  It compares the item's marker against the newer of this run's last
-  validation and its take-up — an adapter re-records the take-up after each
-  write of its own (§2, AR-140), so a comment posted after BEFORE_PR does not
-  hold the close; pinned in the generator's
-  `test/template/self-inflicted-marker.test.ts` (absent in a generated rig) › "continues when the run’s own
-  write moved the marker after the last validation" — and its
-  state against the `in-progress` a close expects, journals one `revalidation`
-  event at `point: BEFORE_CLOSE`, and lists the item's dependants with each
+  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
+  `UNVERIFIABLE` and stops the close. The adapter's expected claimed state is
+  part of the same `claim:scope` comparison rather than a second state-drift
+  decision. The check journals one `revalidation` event at `point:
+  BEFORE_CLOSE` and lists the item's dependants with each
   one's state re-read for the write-back below — pinned in the generator's
   `test/template/revalidate.test.ts` (absent in a generated rig) › "appends
   exactly one BEFORE_CLOSE revalidation event after the BEFORE_PR one, and does

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

@@ -35,7 +35,7 @@ blockers.
      flow, and this gate with it, begins when the project has a remote
      (`workflow.md`, "PR flow"). The refusal exists because two rounds were once counted ahead of a
      commit pre-commit then refused, so the counter and the fan-out's verdicts
-     named a head that never shipped (AR-141) — pinned in the generator's
+     named a head that never shipped — pinned in the generator's
      `test/template/gate-rounds.test.ts` — absent in a generated rig — ›
      "refuses to count a round on a dirty tree, and counts nothing".
 
@@ -57,26 +57,33 @@ blockers.
    confidently-wrong reviews. Everything below is scoped to this diff.
 
    Then, on the fetched ref, ask whether the branch is still the branch the run
-   took up (AR-134):
+   took up:
 
    ```sh
    node .claude/scripts/revalidate.mjs --point BEFORE_PR --ticket <item-id> --base origin/<default>
    ```
 
-   It compares two sources and names each one that moved: the item's `updatedAt`
-   against the take-up snapshot `next` recorded (`task:updatedAt`), and what the
-   default branch changed since this branch forked, on the paths the branch
-   touches or a `check-premises` record in this run cited (`main:<path>`). It
+   It runs the existing revalidation chain against the tracked, versioned
+   `.rig/claims/<item-id>.json`: the content-blind `scope` fingerprint set is
+   authoritative here, while `takeUps` / `updatedAt` remain evidence only. It
+   also names what the default branch changed since this branch forked on paths
+   the branch touches or a `check-premises` record cited (`main:<path>`). It
    journals one `revalidation` event at `point: BEFORE_PR`; **exit code 2 is a HOLD**, with one blocker per named source: re-read the item, or the default
    branch on that path, record what the re-read concluded —
    `node .claude/scripts/revalidate.mjs outcome --point BEFORE_PR --ticket <item-id> --action-changed <true | false> --note '…'`
    — and come back through step 0. A hold with no outcome is counted by the
-   report as a re-read the run skipped. Exit 0 with
-   `unverifiable` means the task side could not be compared — no take-up
-   snapshot in this run, or no marker — and is stated in the evidence, not read
-   as a pass. Exit 1 is the command refusing (unknown point, no ticket, a base
-   that is not a revision): fix the call. Its limits are its own header's; the
-   cited-path set is a labelled assumption, not a recorded fact.
+   report as a re-read the run skipped. A missing, untracked, unreadable or
+   unsupported claim is `UNVERIFIABLE`, exits 2, and stops automatic progress;
+   so is a tracker whose adapter the command cannot READ, which means the
+   question was never put rather than that the claim record is unreadable.
+   Neither is ever read as a pass. Exit 1 is the command refusing (unknown
+   point, no ticket, a base that is not a revision, or a queue config that does
+   not resolve): fix the call or the config — the message says which. Its limits are its own header's; the
+   cited-path set is a labelled assumption, not a recorded fact. Pinned in the
+   generator's `test/template/revalidate.test.ts` (absent in a generated rig) ›
+   "continues when only updatedAt moved and still reports the marker evidence"
+   and `test/template/content-blind-revalidation.test.ts` › "refuses a deleted
+   tracked claim in a fresh run without take-up markers".
 2. **Route the diff before you spend on it.** This gate always ran its most
    expensive path, so a typo fix in a README bought the same fan-out as a
    rewrite of the storage layer. The dispatcher decides which lane the change

package/templates/agent-os/universal/.codex/hooks.json

@@ -28,7 +28,7 @@
         ]
       },
       {
-        "matcher": "Bash",
+        "matcher": "Bash|PowerShell",
         "hooks": [
           {
             "type": "command",

package/templates/agent-os/universal/.rig/revalidation.json

@@ -0,0 +1,10 @@
+{
+  "schemaVersion": 1,
+  "detection": {
+    "mode": "pull",
+    "sources": ["run-state", "journal"],
+    "acceptedLatency": "24h",
+    "push": false
+  },
+  "pairedFacts": []
+}

package/templates/agent-os/universal/docs/decisions/codex-adapter.md

@@ -94,8 +94,9 @@ names the platform never sends. The guards therefore accept
 that documented string form. A command that is ABSENT still fails open — a
 payload the hook does not understand — while one that is present and is not a
 shape the normalizer reads is REFUSED, because that is a condition it detects
-and can report rather than an error it threw. See `codex.test.ts` › "refuses,
-rather than failing open, when apply_patch command is supplied as %s".
+and can report rather than an error it threw. See the generator's
+`codex.test.ts` (absent in a generated rig) › "refuses, rather than failing
+open, when apply_patch command is supplied as %s".
 Hook output is the JSON `description` plus event arrays accepted by
 `.codex/hooks.json`; command portability is carried by generated POSIX and
 Windows commands. In this generated project, `.claude/settings.json` and

package/templates/agent-os/universal/docs/decisions/content-blind-revalidation.md

@@ -0,0 +1,144 @@
+# Content-blind revalidation claims
+
+Status: accepted
+
+## Decision
+
+SELECT, BEFORE_PR and BEFORE_CLOSE remain the only revalidation checkpoints.
+They share one implementation and one durable baseline: a versioned JSON record
+at `.rig/claims/<ticket>.json`.
+
+The first successful SELECT creates the record and reports
+`BASELINE_CREATED`. The task branch must add it to Git. An existing but
+untracked record, or an absent tracked record, is `UNVERIFIABLE`; so is an
+absent record on a resumed SELECT, BEFORE_PR or BEFORE_CLOSE. Each case stops
+automatic progress. Pinned in the generator's
+`test/template/content-blind-revalidation.test.ts` (absent in a generated rig)
+› "creates a versioned content-blind claim and returns BASELINE_CREATED" and ›
+"refuses to resume from an existing claim until Git tracks it", › "refuses a
+deleted tracked claim in a fresh run without take-up markers", and › "refuses
+to recreate a deleted untracked baseline with a %s" (parameterized over a
+readable and a corrupt prior journal), plus
+`test/template/queue-revalidation.test.ts` (absent in a generated rig) ›
+"without a run directory it creates the durable baseline but no run evidence".
+
+The record contains SHA-256 fingerprint sets, not source content:
+
+- `scope` covers stable ticket scope, workflow state, dependency links and
+  configured paired repository facts. Workflow state is fingerprinted against
+  the state expected at each checkpoint. The first SELECT expects `open`.
+  A successful Jira or GitHub adapter `claim` then writes its observable state
+  (`in-progress`) into the same durable claim record as `workflowClaim`; only
+  that acknowledgement authorises the state at a resumed SELECT, BEFORE_PR or
+  BEFORE_CLOSE. The same state reached without the acknowledgement is external
+  drift and moves `scope`. PLAN.md remains `open` because its claim has no
+  observable workflow transition. A rollback or any other state also moves it.
+- `commentary` covers comment identifiers and count. It is observed at SELECT
+  and BEFORE_PR and becomes hold-authoritative only at BEFORE_CLOSE.
+
+Pinned in the generator suite (absent in a generated rig),
+`test/template/content-blind-revalidation.test.ts` › "stays CURRENT
+for marker-only movement and holds on changed scope", › "holds when the target
+branch SHA moves without a tracker edit", › "adapters declare their observable
+claimed workflow state", › "keeps a resumed SELECT current after the Jira
+adapter records its own claim transition", › "GitHub claim records the durable
+transition that makes in-progress CURRENT", › "holds claim:scope at resumed
+SELECT for the same transition made outside the adapter", › "accepts an
+in-progress transition performed by the Jira adapter claim operation", ›
+"holds claim:scope when an external actor moves the item to the expected
+claimed state", › "holds claim:scope when workflow state returns to open after
+the Rig claim transition", and › "defers an added comment through SELECT and
+BEFORE_PR, then holds at BEFORE_CLOSE".
+
+`.rig/revalidation.json` is the versioned detection contract. Version 1 is a
+pull model over run-state and journal evidence, with 24-hour accepted latency,
+no push channel, and an explicit list of paired facts. Preflight stops when the
+contract is absent or unsupported. Pinned in the generator suite (absent in a
+generated rig),
+`test/template/content-blind-revalidation.test.ts` › "preflight hard-refuses a
+%s contract as no-detection-contract" and › "accepts the default
+pull/run-state+journal/24h/no-push contract".
+
+`updatedAt` take-up markers remain in run state and revalidation events for
+compatibility and attribution. They do not decide drift, baseline creation or
+checkpoint action. `.claude/runs/<run-id>/decisions.jsonl` and `events.jsonl`
+remain append-only evidence for a particular run; the sibling `state.json` is a
+mutable stop-state cache, and none of them is the cross-harness claim store.
+Pinned in the generator suite (absent in a generated rig),
+`test/template/queue-revalidation.test.ts` › "a moved marker stays
+evidence-only while the tracked claim remains CURRENT". First sight versus
+resume is reconstructed from SELECT events in the current and bounded sibling
+run journals. An unreadable bounded journal cannot prove first sight and
+therefore cannot authorise recreation of a missing claim. Neither can a scan
+truncated by its entry or candidate cap: incompleteness is explicit and fails
+closed rather than turning subset absence into first sight.
+
+Every blocking detection has a stable content-blind id. A typed outcome names
+that id, records whether action was required and clears only its matching
+run-level hold. An outcome without a boolean `actionRequired` or legacy
+`actionChanged` verdict is malformed and resolves nothing. Filesystem failures
+are reduced to stable logical evidence before they enter a detection id, so
+identical failures have identical ids across harness
+checkouts. The report joins by detection id across runs and retains the
+legacy same-run sequence join for older evidence. Pinned in the generator suite
+(absent in a generated rig),
+`test/template/content-blind-revalidation.test.ts` › "reuses a stable detection
+id for the same drift at the same checkpoint", › "journals a typed resolution
+through the existing outcome command", › "derives false-HOLD from result !=
+CURRENT and actionRequired false, only after resolution", and › "joins a typed
+resolution to its detection across run directories".
+
+The run-state hold is a cache of that append-only evidence, not a deletion
+escape hatch. Before selection, the same temporal resolver used by the report
+reconstructs the newest unresolved blocking detection from the current run
+journal when `state.json` has no hold. Revalidation-hold writers use the same
+fail-closed state reader as selection, so a corrupt, symlinked or oversized
+state file cannot be replaced while it may conceal another stop input. Contract
+and paired-fact reads classify a pathname before opening it, stay anchored to
+the opened file descriptor, and reject identity changes during validation.
+Existing claim bytes are read through a bounded no-follow
+descriptor and compared with the tracked Git object; first-baseline creation is
+anchored to the validated claim-directory working directory so a pathname swap
+cannot redirect the write outside the repository.
+The directory's real path and filesystem identity are carried into the writer
+and checked again with the persisted bytes before SELECT reports
+`BASELINE_CREATED`; redirecting it elsewhere inside the repository is refused
+too. Jira commentary declares whether its returned IDs cover `comment.total`;
+an incomplete set is `UNVERIFIABLE`, never a hash of unseen IDs. GitHub CLI's
+unpaginated `comments(first: 100)` window has no total beside it, so exactly 100
+returned comments is also `UNVERIFIABLE`; fewer than the cap proves completion.
+Pinned in the generator's
+`test/template/content-blind-revalidation.test.ts` (absent in a generated rig)
+› "stops with %s when the unresolved journal result is %s", › "%s refuses a
+present %s state instead of replacing unknown stop inputs", › "does not accept
+an external contract swapped in after containment validation", › "classifies a
+contract symlink before attempting to open it", › "rejects a tracked claim %s
+only in the worktree", and › "does not write a baseline outside
+after the claim directory passes containment", plus › "keeps a detection
+unresolved with %s state when its typed outcome has no boolean verdict", › "uses
+the same id for the same missing-contract condition in two absolute roots", ›
+"returns UNVERIFIABLE when the %s truncates prior SELECT evidence", › "refuses
+SELECT when comment.total exceeds the returned comment ids", › "refuses SELECT
+when the transport returns exactly its 100-comment window without a total", and
+› "does not write through an in-repository claim-directory symlink swapped after
+validation".
+
+BEFORE_CLOSE proves the tracker state it observed; the later tracker transition
+is a separate API operation. Without a tracker-supplied conditional transition
+or transaction token, this mechanism cannot make those two remote operations
+atomic. A future adapter may consume such a native primitive, but this decision
+does not invent one or treat `updatedAt` as a substitute authority.
+
+## Why
+
+Tracker timestamps conflate scope edits, comments and workflow transitions.
+They caused false holds on the rig's own writes and cannot survive a harness or
+run boundary as a durable semantic claim. Content-blind sets preserve privacy,
+make each kind of drift explicit and keep the existing checkpoint chain as the
+single authority.
+
+## Rollback
+
+Revert the mechanism, contract and claim records together. Do not restore
+`updatedAt` as a second authority beside claims: two engines can disagree at a
+checkpoint, which makes neither result safe to automate.

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

@@ -47,9 +47,12 @@
     ".claude/scripts/revalidate.mjs",
     ".claude/scripts/revalidation-report.mjs",
     ".claude/scripts/lib/gate-coverage.mjs",
+    ".claude/scripts/lib/claim-records.mjs",
+    ".claude/scripts/lib/revalidation-evidence.mjs",
     ".claude/scripts/lib/revalidation-points.mjs",
     ".claude/scripts/lib/verdict.mjs",
     ".claude/scripts/lib/secrets.mjs",
+    ".claude/scripts/lib/shell-tools.mjs",
     ".claude/scripts/queue/core.mjs",
     ".claude/scripts/queue/plan-md.mjs",
     ".claude/scripts/queue/github-issues.mjs",
@@ -60,12 +63,14 @@
     ".claude/scripts/queue/state.mjs",
     ".claude/scripts/queue/gate-rounds.mjs",
     ".claude/queue.json",
+    ".rig/revalidation.json",
     "PLAN.md",
     "journal/README.md",
     "docs/decisions/gate-coverage.md",
     "docs/decisions/fail-open-guards.md",
     "docs/decisions/codex-adapter.md",
     "docs/decisions/closing-a-task.md",
+    "docs/decisions/content-blind-revalidation.md",
     "docs/decisions/review-lanes.md",
     "docs/decisions/run-directory.md",
     "docs/decisions/spacing-rations-mechanisms.md",