@agentsfleet/orly 0.10.5 → 0.10.6

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
 
@@ -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/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

package/audits/spec-template.ts

@@ -0,0 +1,193 @@
+import { existsSync } from "node:fs";
+import { isAbsolute, join, normalize, resolve } from "node:path";
+
+type MarkdownElement = { type?: unknown; props: { children?: MarkdownNode[] } };
+type MarkdownNode = string | MarkdownElement;
+type Section = { title: string; nodes: MarkdownNode[] };
+type Commands = Record<string, string[][]>;
+
+const CONFIG_PATH = ".oracle/orly.json";
+const SPEC_LINE_LIMIT = 320;
+const BACKTICK = "`";
+const EMPTY = "";
+const PIPE_OUTPUT = "pipe";
+const TABLE_ROW = "tr";
+const TEST_HEADING = /^Test Specification/;
+const RUBRIC_HEADING = /^Acceptance (Rubric|Criteria)/;
+const REQUIRED = [
+  /^Overview/, /^PR Intent/, /^Implementing agent/, /^Files Changed/, /^Applicable Rules/,
+  /^Applicable Gates/, /^(Prior-Art|Reference Implementation)/, /^Sections/,
+  /^Interfaces/, /^Failure Modes/, /^Invariants/, /^Metrics.*Observability/,
+  TEST_HEADING, RUBRIC_HEADING, /^Dead Code Sweep/, /^Out of Scope/,
+  /^Product Clarity/, /^(Decomposition|Alternatives)/, /^Discovery/,
+];
+const RESIDUE = /<!--\s*tpl:|\{\{fill:|\{unresolved_[^}]+\}|path\/to\/file\.ext|path\/to\/spec_or_doc\.md|test_<short_name>|\{one-line reason\}|\{Slice title\}|\{smallest verifiable behaviour\}|\{one-line behavioural claim\}/;
+const STAGED_MODES = new Set(["--staged", "staged"]);
+const EXPECTED_COLUMN = "Expected";
+
+function sectionsOf(text: string): Section[] {
+  const sections: Section[] = [];
+  const document = Bun.markdown.react(text) as MarkdownElement;
+  for (const node of children(document)) {
+    if (!isString(node) && node.type === "h2") sections.push({ title: textOf(node), nodes: [] });
+    else if (sections.length) sections[sections.length - 1]!.nodes.push(node);
+  }
+  return sections;
+}
+
+function section(sections: Section[], heading: RegExp): MarkdownNode[] {
+  return sections.find((entry) => heading.test(entry.title))?.nodes ?? [];
+}
+
+function children(node: MarkdownNode): MarkdownNode[] {
+  return isString(node) ? [] : node.props.children ?? [];
+}
+
+function elements(nodes: MarkdownNode[], type: string): MarkdownElement[] {
+  return nodes.filter((node): node is MarkdownElement => !isString(node) && node.type === type);
+}
+
+function textOf(node: MarkdownNode): string {
+  if (isString(node)) return node;
+  const text = children(node).map(textOf).join(EMPTY);
+  return node.type === "code" ? `${BACKTICK}${text}${BACKTICK}` : text;
+}
+
+function table(nodes: MarkdownNode[]): { columns: string[]; rows: string[][] } {
+  const groups = elements(nodes, "table").flatMap(children);
+  const headers = elements(groups, "thead").flatMap(children);
+  const bodies = elements(groups, "tbody").flatMap(children);
+  return {
+    columns: elements(headers, TABLE_ROW).flatMap(children).map((node) => textOf(node).trim()),
+    rows: elements(bodies, TABLE_ROW).map((row) => children(row).map((node) => textOf(node).trim())),
+  };
+}
+
+function testMappings(sections: Section[]): string[] {
+  const errors: string[] = [];
+  const items = elements(section(sections, /^Sections/), "ul").flatMap(children).map(textOf);
+  const declared = items.filter((item) => item.startsWith("Dimension "));
+  const dimensions = declared.flatMap((item) => [...item.matchAll(/^Dimension (\d+\.\d+)\b[^\n]*?→ Test `([^`]+)`/g)]);
+  if (!dimensions.length || dimensions.length !== declared.length) errors.push("every Dimension must name its proof with → Test `name`");
+  const ids = dimensions.map((match) => match[1]);
+  if (new Set(ids).size !== ids.length) errors.push("Dimension identifiers must be unique");
+  const tests = table(section(sections, TEST_HEADING));
+  const tier = tests.columns.indexOf("Tier");
+  const name = tests.columns.indexOf("Test");
+  const assertion = tests.columns.findIndex((column) => column.startsWith("Asserts"));
+  const id = tests.columns.indexOf("Dimension");
+  if ([tier, name, assertion, id].some((index) => index < 0)) return [...errors, "Test Specification needs Dimension, Tier, Test, and Asserts columns"];
+  for (const dimension of dimensions) {
+    if (!tests.rows.some((row) => row[id] === dimension[1] && row[name]?.replaceAll(BACKTICK, EMPTY) === dimension[2] && row[tier] && row[assertion])) {
+      errors.push(`Dimension ${dimension[1]} has no matching tiered test and assertion`);
+    }
+  }
+  for (const row of tests.rows) {
+    if (row[id] && !ids.includes(row[id])) errors.push(`test row references unknown Dimension ${row[id]}`);
+  }
+  return errors;
+}
+
+function readFirst(sections: Section[], exists: (path: string) => boolean): string[] {
+  const items = elements(section(sections, /^Implementing agent/), "ol").flatMap(children).map(textOf);
+  const references = items.flatMap((item) => [...item.matchAll(/^(?:`([^`]+)`|(https?:\/\/\S+))/g)]);
+  if (!references.length) return ["read-first section needs existing repository paths or URLs"];
+  const errors: string[] = [];
+  for (const reference of references) {
+    const path = reference[1] ?? reference[2] ?? EMPTY;
+    if (/^https?:\/\//.test(path)) continue;
+    const normalized = normalize(path.split("#")[0] ?? EMPTY);
+    if (isAbsolute(normalized) || normalized.startsWith("..") || normalized.includes("{")) {
+      errors.push(`read-first pointer must name a repository file: ${path}`);
+    } else if (!exists(normalized)) {
+      errors.push(`read-first pointer does not resolve: ${path}`);
+    }
+  }
+  return errors;
+}
+
+function git(argv: string[], root: string): { ok: boolean; text: string } {
+  const result = Bun.spawnSync(["git", ...argv], { cwd: root, stdout: PIPE_OUTPUT, stderr: PIPE_OUTPUT });
+  return { ok: result.exitCode === 0, text: result.stdout.toString() };
+}
+
+async function commands(staged: boolean, root: string): Promise<Commands> {
+  const text = staged ? git(["show", `:${CONFIG_PATH}`], root) : { ok: true, text: await Bun.file(join(root, CONFIG_PATH)).text() };
+  if (!text.ok) throw new Error(`cannot read ${CONFIG_PATH} from the index`);
+  const config: unknown = JSON.parse(text.text);
+  if (!object(config) || !object(config.commands)) throw new Error(`${CONFIG_PATH} needs declared commands`);
+  const result: Commands = {};
+  for (const [name, invocations] of Object.entries(config.commands)) {
+    if (!Array.isArray(invocations) || !invocations.length) throw new Error(`empty command group: ${name}`);
+    result[name] = invocations.map((argv: unknown) => {
+      if (!Array.isArray(argv) || !argv.length || !argv.every(isString)) throw new Error(`invalid arguments for ${name}`);
+      return argv;
+    });
+  }
+  if (!Object.keys(result).length) throw new Error(`${CONFIG_PATH} needs declared commands`);
+  return result;
+}
+
+function object(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isString(value: unknown): value is string {
+  return typeof value === "string";
+}
+
+function rubricCommands(sections: Section[], declared: Commands): string[] {
+  const rubric = table(section(sections, RUBRIC_HEADING));
+  const verify = rubric.columns.findIndex((column) => column.startsWith("Verify"));
+  const expected = rubric.columns.indexOf(EXPECTED_COLUMN);
+  if (verify < 0 || expected < 0) return ["Acceptance Rubric needs Verify and Expected columns"];
+  const errors: string[] = [];
+  for (const [name, invocations] of Object.entries(declared)) {
+    if (name !== "conform" && !name.startsWith("verify.")) continue;
+    for (const argv of invocations) {
+      const command = argv.join(" ");
+      if (!rubric.rows.some((row) => row[verify] === `${BACKTICK}${command}${BACKTICK}` && row[expected])) {
+        errors.push(`rubric misses declared command verbatim: ${command}`);
+      }
+    }
+  }
+  return errors;
+}
+
+export function validateSpec(text: string, declared: Commands, exists: (path: string) => boolean): string[] {
+  const sections = sectionsOf(text);
+  const errors: string[] = [];
+  const count = text.trimEnd().split(/\r?\n/).length;
+  if (count > SPEC_LINE_LIMIT) errors.push(`spec has ${count} lines; cap ${SPEC_LINE_LIMIT}`);
+  for (const heading of REQUIRED) {
+    if (!section(sections, heading).map(textOf).join(EMPTY).trim()) errors.push(`missing or empty required section: ${heading.source}`);
+  }
+  if (RESIDUE.test(text)) errors.push("unfilled template placeholder or authoring guidance");
+  errors.push(...readFirst(sections, exists), ...testMappings(sections), ...rubricCommands(sections, declared));
+  return errors;
+}
+
+export async function auditSpec(args: string[], root: string): Promise<string[]> {
+  const [spec, path, mode] = args;
+  if (!spec || !path || !mode) throw new Error("expected spec path, content path, and audit mode");
+  const staged = STAGED_MODES.has(mode);
+  const exists = (reference: string) => staged ? git(["cat-file", "-e", `:${reference}`], root).ok : existsSync(join(root, reference));
+  return validateSpec(await Bun.file(resolve(root, path)).text(), await commands(staged, root), exists);
+}
+
+if (import.meta.main) {
+  try {
+    const errors = await auditSpec(Bun.argv.slice(2), process.cwd());
+    for (const error of errors) {
+      // logging: audit findings are the command-line interface.
+      console.error(`FAIL: ${Bun.argv[2]} — ${error}`);
+    }
+    if (errors.length) process.exitCode = 1;
+    // logging: report structural checks without claiming semantic readiness.
+    else console.log(`OK: ${Bun.argv[2]} — sections, references, test mappings, and declared commands checked`);
+  } catch (error) {
+    // logging: unavailable audit inputs must fail, never silently skip checks.
+    console.error(`FAIL: spec readiness check — ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+  }
+}

package/core/operating-model.md

@@ -173,7 +173,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. |
 <!-- oracle-packs:end -->
 
 ---
@@ -188,14 +188,14 @@ 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.
 
 <!-- oracle-packs:start workflow.specifications -->
 ### 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.
 <!-- oracle-packs:end -->
 
 ### PLAN
@@ -222,9 +222,9 @@ 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.
+**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.
 <!-- oracle-packs:start product.agentsfleet -->
-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.
+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.
 <!-- oracle-packs:end -->
 
 ### REVIEW