@agentsfleet/orly 0.10.5 → 0.10.7

package/AGENTS.md

@@ -168,7 +168,7 @@ Guards fire pre-hoc regardless of lifecycle stage. Override: `<GATE>: SKIPPED pe
 | Begin implementation OR branch carries spec changes in `pending/` | CHORE(open): `pending/`→`active/`, `Status: IN_PROGRESS` + `Branch:`, create worktree, commit on feature branch. **No code until 4 steps committed.** |
 | Every commit during implementation | Mark completed Dimensions/Sections `DONE` same commit as the code. |
 | All work complete, before PR | CHORE(close). |
-| Branch with spec in `active/` after any COMMIT | CHORE(close) is mandatory next action. |
+| Final implementation commit, or explicit request to park a spec | CHORE(close) is mandatory next action; Section commits continue the stream. |
 
 ---
 
@@ -182,13 +182,13 @@ Non-trivial (full lifecycle) if it: touches >1 file · new abstraction · data m
 
 **Anchor invariant — `orly gate` proves the boundary.** No PR opens unless every `orly gate pr` criterion is green or carries an `Orly-Override` trailer the user recorded with a reason.
 
-**One gate per cadence, each tier run once.** `work` = the declared `conform` command, no git state (a commit hook's tree is dirty by construction). `verify` = spec dimensions, docs language, the fast `verify.*` set. `pr` = branch shape, clean tree, pushed branch, every spec criterion, the slow suites. `orly gate pr` is the command CHORE(close) runs; `git.pushed` proves HEAD is exactly what the pre-push `orly gate verify` already graded. A bare `orly gate` chains all three, for a branch whose earlier gates never ran. Stage map: `dispatch/lifecycle.md`. Both stop at the first red group and only read; green unlocks CHORE(close) but never performs it. No spec → spec criteria skip, quality gates still run. Slow suites (`verify.integration`, `verify.memory`) run only when the branch carries code. A user-surface change without a docs change is red until docs land or an override says why not.
+**Gate ownership.** `work` runs the declared `conform` command at commit. `verify` runs documentation checks and non-test `verify.*` commands at push; it permits unfinished Sections. `pr` checks branch shape, exact upstream revision, spec completeness, and every declared `verify.*` command itself. `orly gate pr` is the command CHORE(close) runs; a push is never proof that tests ran. Unit and integration baselines are measured before the Pull Request against the recorded comparison revision. Full unit and integration suites run at the PR boundary, not at opening or every push. Integration and memory suites skip only on branches with no code. The authoritative sequence is `dispatch/lifecycle.md`; no spec means only spec criteria skip. A user-surface change without a docs change is red until docs land or an override says why not.
 
 **LAND (after merge, or when the user confirms it merged):** pull the default branch, prune the merged worktree + branch, `make down` where defined.
 
 ### CHORE (open)
 
-Spec `pending/`→`active/`; `Status: IN_PROGRESS`; `Branch:` set; **`Test Baseline:` recorded** (declared `verify.*` counts → `**Test Baseline:** unit=<N> integration=<M>`; VERIFY's Test Delta compares against it); committed. Worktree created, CWD inside (verify `pwd` + `git worktree list`). No code until the 4 steps are committed.
+Spec `pending/`→`active/`; `Status: IN_PROGRESS`; `Branch:` set; **`Test Baseline:` declared pending; `Baseline revision:` records the full comparison commit** (unit and integration counts plus evidence are due before the Pull Request); committed. Worktree created, CWD inside (verify `pwd` + `git worktree list`), carrying the base checkout's uncommitted work in with it. No code until the 4 steps are committed.
 
 ### PLAN
 
@@ -197,7 +197,7 @@ Required: one-paragraph goal · explicit assumptions · file/task impact list ·
 ### EXECUTE
 
 Read what the selected dispatch names — **sectioned, not whole-file**: scan headers (`grep -nE "^##+ "`), read the sections the diff shape touches, cite them.
-The full `agentsfleet` trigger map lives in `docs/EXECUTE_DOC_READS.md`. At EXECUTE start read the **Rule-code gloss legend** of `docs/greptile-learnings/RULES.md` plus the sections the spec's "Applicable Rules" names — never the full file. On sub-task shape change, section-scan (`grep -n "^## "`) and re-read only the sections the new shape touches. DOC READ GATE emits one `📖 DOC READ: <path>` proof-line **per triggered document per turn** before the turn's first triggering edit, citing the applied section or a cited skip; auto-mode and prior-turn reads never excuse it. **Record it, don't just claim it:** `bash audits/doc-read.sh log <path>` — any runtime; Claude Code's Read hook does it for you; pre-commit compares the record to the staged diff.
+The full `agentsfleet` trigger map lives in `docs/EXECUTE_DOC_READS.md`. At EXECUTE start read the **Rule-code gloss legend** of `docs/greptile-learnings/RULES.md` plus the sections the spec's "Applicable Rules" names — never the full file. On sub-task shape change, section-scan (`grep -n "^## "`) and re-read only the sections the new shape touches. DOC READ GATE emits one `📖 DOC READ: <path>` proof-line **per triggered document per turn** before the turn's first triggering edit, citing the applied section or a cited skip; auto-mode and prior-turn reads never excuse it. **Record it, don't just claim it:** `bash audits/doc-read.sh log <path> "<section applied>"` — any runtime; Claude Code's Read hook does it for you; pre-commit compares the record to the staged diff. **Log each page as you read it, and cite the section**: a loop writes the same rows, and once did — nine façades in one second, `check` green, violations from a section nobody opened. `check` counts citations and names any bulk second.
 
 Edit only approved scope; no opportunistic refactors. Stay in active worktree. Cross-repo writes to `~/Projects/docs/` need explicit per-session ask.
 
@@ -210,8 +210,8 @@ In `agentsfleet` this stage is `make harness-verify`; its output block and end-o
 
 ### VERIFY
 
-**Two cadences, one boundary.** Inside a Section, run CONFORM plus the declared lane covering the surface the Section touched — enough to prove a Section, reported as a Section claim. The repository's full declared `verify.*` set runs ONCE, at the milestone boundary, before the PR. A package-scoped command never replaces a listed one at either cadence, and a Section lane never satisfies a "tests pass" claim about the repository.
-The `agentsfleet` output block and both cadences live in `docs/VERIFY_TIERS.md`. **FIRST: `/orly-write-unit-test`** audits diff coverage. **LAST: the Test Delta row** compares against the CHORE(open) baseline; zero or negative unit growth on a code-adding diff needs justification or a return to EXECUTE. Paste memory-leak evidence into PR Session Notes or cite its Continuous Integration (CI) URL. After refactors, list newly dead code before removing it.
+**Section proof and final verification.** Follow `dispatch/lifecycle.md` for command timing. Section checks prove the changed Dimensions; the final gate runs the full declared verification set. A package-scoped command never replaces a declared boundary command, and a Section result never satisfies a repository-wide "tests pass" claim.
+The `agentsfleet` output block and both cadences live in `docs/VERIFY_TIERS.md`. **FIRST: `/orly-write-unit-test`** audits diff coverage. **LAST: the Test Delta row** compares against the recorded comparison revision, measured before the Pull Request; zero or negative unit growth on a code-adding diff needs justification or a return to EXECUTE. Paste memory-leak evidence into PR Session Notes or cite its Continuous Integration (CI) URL. After refactors, list newly dead code before removing it.
 
 ### REVIEW
 

package/README.md

@@ -61,15 +61,33 @@ Works with Claude Code, Codex, OpenCode, and Amp.
 Run this inside the repository you want governed.
 
 ```bash
-bunx @agentsfleet/orly init
+bun add -g @agentsfleet/orly
+orly init
 ```
 
 orly scans your source, detects your languages, and installs only the rules that apply.
 
 > [!TIP]
-> Try `bunx @agentsfleet/orly init --dry-run` first. It prints everything it would write and changes nothing.
+> Try `orly init --dry-run` first. It previews the generated rules and changes nothing.
 
-Then commit what it wrote. Teammates get the rules on clone.
+The Git hooks use the installed `orly` executable. Keep it on `PATH`.
+Complete any setup items printed by `init`, then run `orly doctor` and commit the generated files.
+Teammates get the rules on clone and run `orly init` to install their hooks.
+
+Declare `conform` and at least one `verify.*` command in `.oracle/orly.json`.
+Orly runs your repository's commands; the verification name does not require a particular language or test runner.
+For a documentation repository whose Makefile provides `test` and `lint`:
+
+```json
+"commands": {
+  "conform": [["make", "test"]],
+  "verify.docs": [["make", "lint"]]
+}
+```
+
+Here `test` checks documentation during work, and `lint` validates the site and links before the pull request.
+Markdown and Markdown JSX (MDX) repositories do not need application unit or integration suites.
+`orly doctor` checks configuration and installed files; run the gates to verify the commands themselves.
 
 ---
 
@@ -120,8 +138,8 @@ Three checkpoints, all running your own declared commands:
 | Checkpoint | When | Effect |
 |---|---|---|
 | `pre-commit` | every commit | stops at the first failing check |
-| `pre-push` | every push | same gates, before anything leaves the machine |
-| `orly gate pr` | opening the Pull Request | refuses until each criterion is green, or carries a recorded override |
+| `pre-push` | every push | documentation and declared non-test verification checks |
+| `orly gate pr` | opening the Pull Request | runs all declared verification commands and checks the branch and spec |
 
 ---
 
@@ -144,7 +162,7 @@ flowchart TB
     subgraph active["⚙️ docs/v1/active/"]
         direction TB
 
-        plan["PLAN<br/><small>understand spec · record baseline</small>"]
+        plan["PLAN<br/><small>understand spec · resolve decisions</small>"]
         execute["EXECUTE<br/><small>make the change</small>"]
         conform["CONFORM<br/><small>apply matching rule pages</small>"]
         verify["VERIFY<br/><small>run deterministic gates</small>"]
@@ -171,7 +189,7 @@ flowchart TB
 | Directory | Meaning |
 |---|---|
 | `docs/v1/pending/` | the spec is written and committed on `main` |
-| `docs/v1/active/` | branch cut, baseline recorded, no code until it commits |
+| `docs/v1/active/` | branch cut, comparison revision recorded, measurement pending; no code until it commits |
 | `docs/v1/done/` | gates green, Pull Request opens |
 
 Inside `active/`, work runs through the stages: **PLAN → EXECUTE → CONFORM → VERIFY → REVIEW → DOCUMENT → COMMIT**.
@@ -216,7 +234,7 @@ The last two files exist because installing a rules file is not the same as deli
 | `orly update --with <pack>` | add an opt-in pack, recorded for every clone |
 | `orly gate` | run your declared checks in order, stopping at the first failure |
 | `orly override <criterion> --reason <why>` | record a gate exception as an empty commit that rides into the Pull Request |
-| `orly doctor` | compare what is installed against what orly would write today |
+| `orly doctor` | check installed files and required command configuration |
 
 ---
 

package/audits/agents-md.md

@@ -107,7 +107,7 @@ The questionnaire is organised by scenario. Each scenario corresponds to a momen
 |---|---|---|
 | 5.1 | Is the agent required to verify CWD is inside the active worktree before resuming (`pwd` + `git worktree list`)? | YES |
 | 5.2 | Must the agent re-read RULES.md when sub-task shape changes (new layer/language/resume after break)? | YES |
-| 5.3 | If the spec is in `active/`, is CHORE(close) the mandatory next action after any COMMIT? | YES |
+| 5.3 | If the spec is in `active/`, does CHORE(close) follow the final implementation commit or an explicit request to park, while Section commits continue implementation? | YES |
 | 5.4 | If unexpected changes appear in files the agent is editing, must the agent stop and ask (not overwrite as stale)? | YES |
 
 ### Scenario 6 — Conformance and verification lifecycle
@@ -122,8 +122,11 @@ The questionnaire is organised by scenario. Each scenario corresponds to a momen
 | 6.6 | Is at least one declared `verify.integration` run from clean state required per branch before ship-ready (where the repository declares one)? | YES |
 | 6.7 | Are package-scoped runners (`bun run test`, `vitest <file>`, `zig build test` w/o integration) explicitly **not** verification? | YES |
 | 6.8 | Must memleak evidence (last 3 lines verbatim) appear in PR Session Notes when touching `src/http/**` / `src/cmd/serve.zig` / allocator wiring? | YES |
-| 6.9 | Does CHORE(open) record a `Test Baseline:` line (unit + integration counts from the repository's declared `verify.*` commands; a product pack may name a dedicated counter) in the spec header? | YES |
-| 6.10 | Does VERIFY end with a Test Delta row (growth vs the CHORE(open) baseline) plus a lacking-areas verdict, with zero/negative unit delta on a code-adding diff requiring justification or a return to EXECUTE? | YES |
+| 6.9 | Does CHORE(open) DECLARE the `Test Baseline:` line in the spec header while measuring nothing, with the counts from the repository's declared `verify.*` commands landing before the Pull Request (a product pack may name a dedicated counter)? | YES |
+| 6.9a | Does the baseline identify the full comparison commit, with matching run evidence or an isolated checkout, declared unit and integration counts, and a report reference? | YES |
+| 6.9b | Does `orly gate pr` reject missing declared baseline counts, allow reasoned `n/a` only without code or baseline lanes, and run all declared verification commands independently of custom hooks? | YES |
+| 6.9c | Does setup require `conform` and a named `verify.*` command, allowing `verify.docs` without application test suites while reporting incomplete configuration? | YES |
+| 6.10 | Does VERIFY end with a Test Delta row (growth vs the branch point's baseline) plus a lacking-areas verdict, with zero/negative unit delta on a code-adding diff requiring justification or a return to EXECUTE? | YES |
 | 6.11 | Do the lifecycle stage runbooks (CHORE(open/close) checklists, PLAN expansions, deferral quote format, pre-PR gates, LAND) resolve from `dispatch/lifecycle.md`, with AGENTS.md keeping each stage's binding essence? | YES |
 
 ### Scenario 7 — Review discipline before merge
@@ -233,6 +236,7 @@ The questionnaire is organised by scenario. Each scenario corresponds to a momen
 | 18.1 | Must `gitleaks` pass before any `git commit` / `git push`? | YES |
 | 18.2 | Is the rule "one worktree per active stream — no edits outside, no reads from siblings, merge only after REVIEW and the final commit" preserved? | YES |
 | 18.3 | Are cross-worktree edits explicitly forbidden without explicit user approval? | YES |
+| 18.4 | Does CHORE(open) MOVE the base checkout's uncommitted work into the new worktree — never copy it, naming what came across, and stopping on a conflicting `git stash pop` — so a stream is never cut from a dirty base that then reads as unowned drift? | YES |
 
 ### Scenario 19 — CONFORM combined audit
 

package/audits/doc-read.sh

@@ -1,14 +1,32 @@
 #!/usr/bin/env bash
 # doc-read.sh — turn the 📖 DOC READ proof-line into a set comparison.
 #
-#   audits/doc-read.sh log <path>   record that a file was read (hook target)
-#   audits/doc-read.sh check        staged source vs recorded reads
+#   audits/doc-read.sh log <path> [section]   record that a file was read
+#   audits/doc-read.sh check                  staged source vs recorded reads
 #
 # The DOC READ GATE asks an agent to read the façade its edit triggers, and
 # then asks the same agent whether it did. That is a claim about itself
 # compared against nothing. `log` records the read and `check` compares the
 # record against the façades the staged files trigger.
 #
+# `log` is still an assertion, and a loop can make nine of them in one second.
+# That happened: an agent ran `log` over its whole trigger list before opening
+# most of the pages, `check` reported green, and two rule violations reached the
+# diff from a section it had skipped. Two things answer it, and neither can
+# block, because neither is provable:
+#
+#   - The optional `section` argument records WHAT the read applied — "§Error
+#     discipline: composed with #[from]". A loop cannot produce that line; only
+#     reading can. `check` reports how many triggered façades carry one.
+#   - Rows for different façades sharing one timestamp are reported as a bulk
+#     assertion. A read hook fires per read and spreads across seconds; a
+#     scripted loop lands them together. An agent that genuinely read three
+#     short pages inside one second is possible too, which is exactly why this
+#     is a number in the output and never a red.
+#
+# Partial mechanisation stated honestly beats a red that means nothing — the
+# same argument the missing-record branch below already makes.
+#
 # NOTHING HERE MAY DEPEND ON AN AGENT RUNTIME. `log` is a shell command any
 # agent can run; a runtime that also has a read hook (Claude Code today) can
 # call it automatically, and a runtime that removes that feature tomorrow
@@ -37,7 +55,12 @@ source "$HERE/rule-ledger-lib.sh"
 MODE_LOG="log"
 MODE_CHECK="check"
 LOG_RELATIVE_PATH="orly/doc-reads.jsonl"
-USAGE="usage: $0 log <path> | $0 check"
+USAGE="usage: $0 log <path> [section] | $0 check"
+
+# How many façades recorded in one second read as a loop rather than as reading.
+# Two is a plausible pair of short pages; three in the same second is a list
+# being walked.
+BULK_ASSERTION_THRESHOLD=3
 
 if [[ -t 1 ]]; then G=$'\033[32m'; R=$'\033[31m'; Y=$'\033[33m'; X=$'\033[0m'
 else G=''; R=''; Y=''; X=''; fi
@@ -65,7 +88,7 @@ repo_relative() {
 # invocation is why two agents in two sessions cannot corrupt each other: the
 # order rows land in does not change which paths the set contains.
 run_log() {
-  local path="$1" relative log blob
+  local path="$1" section="${2:-}" relative log blob
   relative="$(repo_relative "$path")" || return 0
   [ -n "$relative" ] || return 0
   log="$(read_log_path)" || return 0
@@ -75,7 +98,11 @@ run_log() {
   # Recording it would let two failures compare equal and validate a read of a
   # file that is no longer there.
   [ -n "$blob" ] || return 0
-  printf '{"ts":%s,"path":"%s","blob":"%s"}\n' "$(date +%s)" "$(json_escape "$relative")" "$blob" >> "$log"
+  # The section rides the SAME row rather than a second file: a citation that
+  # could be written without a read beside it would be a third assertion to
+  # reconcile, and the pair is what carries meaning.
+  printf '{"ts":%s,"path":"%s","blob":"%s","section":"%s"}\n' \
+    "$(date +%s)" "$(json_escape "$relative")" "$blob" "$(json_escape "$section")" >> "$log"
   return 0
 }
 
@@ -115,22 +142,43 @@ json_unescape() {
   printf '%s' "$1" | sed -e 's/\\"/"/g' -e 's/\\\\/\\/g'
 }
 
-# Paths whose recorded read saw the content that is on disk now. A row written
-# against an older version of the document proves the agent read something
-# else, so it does not count — and rows from before this milestone, which carry
-# no blob, cannot prove anything and are ignored.
+# Paths whose recorded read saw the content that is on disk now, one
+# `path<TAB>ts<TAB>section` row each. A row written against an older version of
+# the document proves the agent read something else, so it does not count — and
+# rows from before this milestone, which carry no blob, cannot prove anything
+# and are ignored.
+#
+# The path is cut at the first `","blob":"` rather than by stripping a fixed
+# tail: the row gained a trailing `section` field, and a suffix strip that
+# spelled the old shape would have silently yielded a path that matches nothing
+# — reading as "never read" for every document.
 current_reads() {
-  local log="$1" line path blob
+  local log="$1" line path blob ts section
   while IFS= read -r line; do
     case "$line" in *'"blob":"'*) ;; *) continue ;; esac
-    blob="${line##*\"blob\":\"}"; blob="${blob%%\"*}"
+    blob="${line#*\"blob\":\"}"; blob="${blob%%\"*}"
     [ -n "$blob" ] || continue
-    path="${line#*\"path\":\"}"; path="${path%\",\"blob\":\"$blob\"\}}"
+    path="${line#*\"path\":\"}"; path="${path%%\",\"blob\":\"*}"
     path="$(json_unescape "$path")"
-    [ "$blob" = "$(content_hash "$path")" ] && printf '%s\n' "$path"
+    ts="${line#*\"ts\":}"; ts="${ts%%,*}"
+    section=""
+    case "$line" in
+      *'"section":"'*) section="${line#*\"section\":\"}"; section="${section%%\"*}" ;;
+    esac
+    [ "$blob" = "$(content_hash "$path")" ] &&
+      printf '%s\t%s\t%s\n' "$path" "$ts" "$(json_unescape "$section")"
   done < "$log"
 }
 
+# Timestamps carrying BULK_ASSERTION_THRESHOLD or more distinct façades, one
+# `ts<TAB>count` row each. See the header: reported, never blocking.
+bulk_seconds() {
+  cut -f1,2 "$1" | sort -u | cut -f2 | sort | uniq -c |
+    while read -r count ts; do
+      [ "$count" -ge "$BULK_ASSERTION_THRESHOLD" ] && printf '%s\t%s\n' "$ts" "$count"
+    done
+}
+
 # File-scope so the EXIT trap can still see them: a trap fires after a
 # function's locals are gone, and `set -u` turns that into a spurious error on
 # the way out of a clean run.
@@ -164,18 +212,51 @@ run_check() {
   current_reads "$log" | sort -u > "$recorded"
 
   while IFS= read -r page; do
-    grep -qxF "$page" "$recorded" && continue
+    grep -qF "$(printf '%s\t' "$page")" "$recorded" && continue
     printf '  %s🔴%s DOC READ: %s triggered by the staged diff, not read at its current content\n' "$R" "$X" "$page"
     unread=1
   done < "$expected"
   [ "$unread" -eq 0 ] && printf '  %s🟢%s DOC READ: every triggered façade was read at its current content\n' "$G" "$X"
+  report_citations "$expected" "$recorded"
+  report_bulk "$recorded"
   return "$unread"
 }
 
+# How many of the triggered façades carry a cited section. A record with one
+# says what the read APPLIED; a record without says only that a read happened,
+# which is the claim a loop can also make.
+report_citations() {
+  local expected="$1" recorded="$2" page total=0 cited=0 section
+  while IFS= read -r page; do
+    total=$((total + 1))
+    section="$(grep -F "$(printf '%s\t' "$page")" "$recorded" | cut -f3 | grep -c '[^[:space:]]')"
+    [ "$section" -gt 0 ] && cited=$((cited + 1))
+  done < "$expected"
+  [ "$total" -eq 0 ] && return 0
+  if [ "$cited" -eq "$total" ]; then
+    printf '  %s🟢%s DOC READ: all %s triggered façade(s) cite the section applied\n' "$G" "$X" "$total"
+    return 0
+  fi
+  printf '  %s🟠%s DOC READ: %s of %s triggered façade(s) cite a section; the rest record\n' \
+    "$Y" "$X" "$cited" "$total"
+  printf '     only that a read happened — pass it: doc-read.sh log <path> "<section applied>"\n'
+}
+
+# Says when rows look like a list being walked rather than pages being read.
+report_bulk() {
+  local recorded="$1" ts count
+  while IFS="$(printf '\t')" read -r ts count; do
+    [ -n "$ts" ] || continue
+    printf '  %s🟠%s DOC READ: %s façades recorded in one second (ts %s) — that is a bulk\n' \
+      "$Y" "$X" "$count" "$ts"
+    printf '     assertion, not %s reads; log each at the moment it is read\n' "$count"
+  done < <(bulk_seconds "$recorded")
+}
+
 case "${1:-}" in
   "$MODE_LOG")
-    [ "$#" -eq 2 ] || { printf '%s\n' "$USAGE" >&2; exit 2; }
-    run_log "$2"
+    { [ "$#" -eq 2 ] || [ "$#" -eq 3 ]; } || { printf '%s\n' "$USAGE" >&2; exit 2; }
+    run_log "$2" "${3:-}"
     ;;
   "$MODE_CHECK")
     [ "$#" -eq 1 ] || { printf '%s\n' "$USAGE" >&2; exit 2; }

package/audits/spec-template.sh

@@ -8,12 +8,12 @@
 #   2. REQUIRED-PRESENT + NO-PLACEHOLDER (positive space) — the determinism
 #      sections the agent-facing template mandates (PR Intent, Applicable Gates,
 #      Prior-Art, Metrics, Decomposition, tiered Test Spec, Product Clarity,
-#      Discovery, …) must EXIST and be FILLED: no unfilled {slot} sentinels and
+#      Discovery, …) must EXIST and carry content: no known unfilled slots and
 #      no surviving "tpl:" guidance comments (template fill grammar). A spec
 #      that omits them forces the executing agent to guess intent. This is the
 #      half that makes a spec "built for the agent".
 #   2b. DECLARED-COMMAND PARITY — a pending/active spec's Acceptance Rubric
-#      must quote the repository's declared conform + verify.unit commands
+#      must quote the repository's declared conform + applicable verify.* commands
 #      (.oracle/orly.json) verbatim: the rubric and `orly gate` grade one
 #      boundary. Staged/file scope only; done/ specs stay historical.
 #
@@ -25,7 +25,7 @@
 #   --all            (default) pending+active specs only — current/in-flight work
 #   --include-done   adds done/ specs to the scan (one-time sweep tool)
 #
-# Family 2 runs ONLY in --staged scope — the spec being authored/edited right
+# Family 2 runs in --staged and --file scope — the spec being authored/edited right
 # now, which is exactly the agent's own output. The bulk scans (--all /
 # --include-done) run Family 1 only, so they behave identically over the whole
 # corpus and never break an existing spec. No legacy carve-out, no heuristics:
@@ -37,6 +37,7 @@
 set -euo pipefail
 
 MODE="${1:-${SCOPE:-all}}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT="$(git rev-parse --show-toplevel)"
 cd "$ROOT"
 
@@ -116,93 +117,8 @@ PATTERNS=(
 # Carve-outs — lines that look prohibited but are legitimate. Skip any match.
 SAFE_LINES_RE='^\*\*Date:\*\*|^\s*```|<!--|^\s*//|"[0-9]+\s*(h|hour|day|min)"'
 
-# ---------------------------------------------------------------------------
-# Family 2 — Required determinism sections (agent-facing docs/TEMPLATE.md).
-# Each entry: <heading ERE>:<human description>
-# ---------------------------------------------------------------------------
-REQUIRED_SECTIONS=(
-  '^#+ .*PR Intent:PR Intent & comprehension handshake'
-  '^#+ .*Applicable Rules:Applicable Rules'
-  '^#+ .*Applicable Gates:Applicable Gates'
-  '^#+ .*Overview:Overview'
-  '^#+ .*(Prior-Art|Reference Implementation):Prior-Art / Reference Implementations'
-  '^#+ .*Files Changed:Files Changed (blast radius)'
-  '^#+ .*(Decomposition|Alternatives):Decomposition & alternatives (patch vs refactor)'
-  '^#+ .*Sections:Sections (implementation slices)'
-  '^#+ .*Metrics.*Observability:Metrics & Observability'
-  '^#+ .*Interfaces:Interfaces'
-  '^#+ .*Failure Modes:Failure Modes'
-  '^#+ .*Invariants:Invariants'
-  '^#+ .*Test Specification:Test Specification'
-  '^#+ .*Acceptance (Criteria|Rubric):Acceptance Rubric (legacy heading Acceptance Criteria accepted)'
-  '^#+ .*Product Clarity:Product Clarity (authoring record)'
-  '^#+ .*Discovery:Discovery (consult log)'
-)
-
-# Template residue — strings that exist ONLY in the unfilled template. Their
-# survival in a pending/active spec means the section was never filled. The
-# "<!-- tpl:" marker is the template's fill grammar: every guidance comment is
-# deleted at authoring, so any survivor is residue by construction.
-PLACEHOLDER_SENTINELS=(
-  '<!-- tpl:'
-  'Title — testable, not vague'
-  'one-line reason}'
-  'Slice title}'
-  'path/to/file.ext'
-  'test_<short_name>'
-  'why this is the right pattern to mirror'
-  '{outcome the user can observe}'
-  '{exit 0 / substring / 0 matches}'
-  'path/to/spec_or_doc.md'
-  '{path/to/old_file.ext}'
-  '{old_symbol}'
-  '{one sentence that could be a test name}'
-  '{smallest verifiable behaviour}'
-  '{one-line behavioural claim}'
-  '{conform command from .oracle/orly.json'
-  '{verify.unit command from .oracle/orly.json'
-  "{gate from this repository's AGENTS.md dispatch index}"
-)
-
-# ---------------------------------------------------------------------------
-# Family 2b — declared-command parity (TEMPLATE.md "Command source rule").
-# A pending/active spec's Acceptance Rubric must quote the repository's
-# declared conform + verify.unit commands VERBATIM — the same set `orly gate`
-# runs — so the spec's ship gate and the mechanical PR gate grade one
-# boundary. Reads .oracle/orly.json with bun (orly's own runtime). Done specs
-# are historical records and are never retrofitted. No config, no bun, or no
-# declared commands → NOTE and skip; this check never guesses.
-# ---------------------------------------------------------------------------
-scan_commands() {
-  local spec="$1" cfg=".oracle/orly.json" cmds
-  case "$spec" in
-    */pending/*|*/active/*) ;;
-    *) return 0 ;;
-  esac
-  [[ -f "$cfg" ]] || { note "$spec — no $cfg; declared-command parity skipped"; return 0; }
-  command -v bun >/dev/null 2>&1 || { note "$spec — bun unavailable; declared-command parity skipped"; return 0; }
-  cmds="$(bun -e '
-    const cfg = await Bun.file(".oracle/orly.json").json().catch(() => null);
-    const commands = cfg && typeof cfg.commands === "object" && cfg.commands !== null ? cfg.commands : {};
-    for (const key of ["conform", "verify.unit"]) {
-      for (const argv of Array.isArray(commands[key]) ? commands[key] : []) {
-        if (Array.isArray(argv) && argv.length > 0) console.log(argv.join(" "));
-      }
-    }' 2>/dev/null || true)"
-  [[ -n "$cmds" ]] || { note "$spec — no declared conform/verify.unit commands; parity skipped"; return 0; }
-  local miss=0 cmd
-  while IFS= read -r cmd; do
-    [[ -z "$cmd" ]] && continue
-    grep -qF "$cmd" "$spec" && continue
-    fail "$spec — rubric misses declared command verbatim: \"$cmd\" (.oracle/orly.json — the set orly gate runs)"
-    miss=$((miss + 1))
-  done <<<"$cmds"
-  if [[ $miss -eq 0 ]]; then ok "$spec — rubric quotes the declared conform/verify.unit commands"; fi
-  return 0
-}
-
 scan_spec() {
-  local spec="$1"
+  local spec="$1" content_file="$2"
   local hits=0
   local pattern desc severity line content
   while IFS=: read -r severity desc pattern; do
@@ -221,36 +137,37 @@ scan_spec() {
         note "$spec:$line — $desc"
       fi
       hits=$((hits + 1))
-    done < <(grep -nE "$pattern" "$spec" 2>/dev/null || true)
+    done < <(grep -nE "$pattern" "$content_file" 2>/dev/null || true)
   done < <(printf '%s\n' "${PATTERNS[@]}")
   if [[ $hits -eq 0 ]]; then ok "$spec — no prohibited patterns"; fi
   return 0
 }
 
-# Family 2 — required determinism sections present + no template residue.
-# BLOCK only; called solely in --staged scope (a spec being authored now).
-scan_required() {
-  local spec="$1"
-  local miss=0 entry sec desc sentinel
-  for entry in "${REQUIRED_SECTIONS[@]}"; do
-    sec="${entry%%:*}"; desc="${entry#*:}"
-    grep -qE "$sec" "$spec" && continue
-    fail "$spec — missing required section: $desc"
-    miss=$((miss + 1))
-  done
-  for sentinel in "${PLACEHOLDER_SENTINELS[@]}"; do
-    grep -qF "$sentinel" "$spec" || continue
-    fail "$spec — unfilled template placeholder: \"$sentinel\""
-    miss=$((miss + 1))
-  done
-  if [[ $miss -eq 0 ]]; then ok "$spec — required sections present, no placeholders"; fi
-  return 0
-}
-
+# Staged checks grade the index, including files removed only from the worktree.
+CONTENT_DIR="$(mktemp -d)"
+trap 'rm -rf "$CONTENT_DIR"' EXIT
 for spec in "${SPECS[@]}"; do
-  [[ -f "$spec" ]] || continue
-  scan_spec "$spec"
-  case "$MODE" in --staged|staged|--file|file) scan_required "$spec"; scan_commands "$spec" ;; esac
+  content_file="$spec"
+  case "$MODE" in
+    --staged|staged)
+      content_file="$CONTENT_DIR/spec.md"
+      if ! git show ":$spec" > "$content_file"; then
+        fail "$spec — cannot read staged content"
+        continue
+      fi
+      ;;
+  esac
+  [[ -f "$content_file" ]] || { fail "$spec — cannot read spec"; continue; }
+  scan_spec "$spec" "$content_file"
+  case "$MODE" in
+    --staged|staged|--file|file)
+      if ! command -v bun >/dev/null 2>&1; then
+        fail "$spec — Bun is required for spec readiness checks"
+      elif ! bun "$SCRIPT_DIR/spec-template.ts" "$spec" "$content_file" "$MODE"; then
+        FAIL=1
+      fi
+      ;;
+  esac
 done
 
 if [[ $FAIL -ne 0 ]]; then