@agentsfleet/orly 0.10.5 → 0.10.7

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
@@ -206,7 +206,7 @@ Required: one-paragraph goal · explicit assumptions · file/task impact list ·
 
 Read what the selected dispatch names — **sectioned, not whole-file**: scan headers (`grep -nE "^##+ "`), read the sections the diff shape touches, cite them.
 <!-- oracle-packs:start product.agentsfleet -->
-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.
 <!-- oracle-packs:end -->
 
 Edit only approved scope; no opportunistic refactors. Stay in active worktree. Cross-repo writes to `~/Projects/docs/` need explicit per-session ask.
@@ -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

package/dispatch/lifecycle.md

@@ -12,55 +12,108 @@ are entering, not the whole file.
 
 ## What runs at each stage
 
-The mechanical half of the lifecycle, in one table. Everything in the "runs"
-column is a command, not a claim — `orly gate` reads the repository's declared
-`.oracle/orly.json` commands and never invents one.
+This is the authoritative sequence. Commands come from the repository's
+`.oracle/orly.json`; the engine contains no product-specific build recipes.
 
-| Stage | Runs | Fired by |
+| Stage | Runs | Owner |
 |---|---|---|
-| CHORE(open) | the declared `verify.unit` once, to record `Test Baseline:` | the agent |
-| PLAN | nothing — no file mutations | — |
-| EXECUTE | the dispatch façade for each edited file type; DOC READ recorded via `audits/doc-read.sh log` | the agent, and the runtime's read hook where it has one |
-| CONFORM | the declared `conform` command | `orly gate work` — the generated pre-commit hook |
-| VERIFY (Section) | `conform` plus the declared lane covering the surface touched | the agent |
-| VERIFY (milestone) | the fast `verify.*` set: lint, unit, version | `orly gate verify` — the generated pre-push hook |
-| REVIEW | gstack `/review` over the diff | the agent |
-| DOCUMENT | nothing mechanical | — |
-| COMMIT | `conform` again, on the staged tree | the pre-commit hook |
-| CHORE(close) | every spec criterion, branch shape, clean tree, pushed branch, docs surface, and the slow `verify.*` suites | `orly gate pr`, by hand, before `gh pr create` |
-| LAND | nothing gated | — |
-
-Three properties hold this together. A gate only asks what it can answer
-honestly at that moment: `work` judges no git state, because a commit hook's
-tree is dirty by construction and a new spec is committed on the default branch.
-Each tier runs once per cadence — `conform` at commit, the fast set at push, the
-slow set at the close. And `orly gate pr` can skip the fast set because
-`git.pushed` proves HEAD is the commit pre-push already graded.
+| CHORE(open) | Record the comparison commit and pending baseline; create the tree, carry owned changes, commit metadata | Agent; commit hook still runs |
+| PLAN | Resolve references, scope, decisions, and proof mapping; no application build | Agent |
+| EXECUTE | Read triggered rules; implement one Section and its tests | Agent |
+| First Section verification | Hydrate only the touched surfaces; format, lint, and execute Section proofs | Agent |
+| Later Section verification | Reuse the tree; repeat affected formatting, lint, and proof commands | Agent |
+| COMMIT | Declared `conform` over staged changes | `orly gate work` in pre-commit |
+| Push | Documentation check and declared non-test verification commands | `orly gate verify` in generated pre-push |
+| Before PR | Measure the comparison revision's unit and integration lanes; review results and fix final-branch failures | Agent |
+| CHORE(close) | Branch and spec criteria, exact upstream revision, every declared `verify.*` command | `orly gate pr` |
+| LAND | Pull and clean up the merged stream | Agent after merge |
+
+`verify.unit`, `verify.integration`, and `verify.memory` belong to the PR
+boundary. Other `verify.*` commands also run at push and are checked again at
+that independent boundary. Full suites run once per PR-gate invocation;
+failures or later changes require a new invocation. No verification cache is
+kept, and a custom hook cannot silently remove final verification.
+`conform` remains the commit hook's responsibility because it may read the
+index. A bare `orly gate` runs all groups and stops at the first red group.
+
+Formatting and lint do not prove behavior. A Section is complete only when its
+Dimensions have passing proofs. Use existing repository test lanes; if a lane
+runs a whole workspace, describe it honestly and add a supported filter to that
+recipe when narrower Section checks are needed. Boundary commands remain
+unfiltered. Rust projects run `cargo fmt` in their Rust workspace, followed by
+the declared lint wrapper covering Clippy and the shipping build configuration.
+Other languages use their own declared formatter and lint commands.
 
 ## CHORE (open) — runbook
 
 1. Spec `docs/v*/pending/` → `active/`; `Status: IN_PROGRESS`; `Branch:` set.
-2. **Test Baseline** — run the repository's declared `verify.unit` (and
-   `verify.integration` where declared) from `.oracle/orly.json`; copy the
-   reported counts into the spec header as `**Test Baseline:** unit=<N>
-   integration=<M>` (VERIFY's Test Delta row compares against it; a product
-   pack may name a dedicated counter — see the product block below).
-3. Create the worktree; verify CWD is inside it (`pwd` + `git worktree list`).
+2. **Test Baseline** — record `**Baseline revision:** <full commit>` and
+   `**Test Baseline:** pending — measured before the Pull Request`. Run no
+   application suite at opening. Before the PR, obtain both declared baseline
+   lanes (`verify.unit` and `verify.integration`) for that exact revision from
+   matching successful run evidence or an isolated checkout of that revision.
+   Never assume the default checkout stayed at the comparison commit. Keep
+   baseline and final integration environments separate; neither may reset a
+   shared deployment. Record passed, failed, and skipped counts per lane in a
+   report, with commands, revision, and environment; put totals in the header
+   and the report path or run URL in `**Baseline evidence:**`.
+   A missing or failed baseline run is recorded honestly; fix failures in the
+   implementation branch and keep the historical result unchanged. Baseline
+   failures never permit final failures. Compare like-for-like lanes and report
+   added, removed, or changed test selections rather than inventing a delta.
+   `n/a — <reason>` is valid only when there is no code or no baseline lane.
+   The gate validates counts, revision ancestry, and the evidence reference;
+   the agent reviews the report's contents. Performance baselines required by
+   a spec remain due before the changes they measure.
+3. Create the worktree and carry the base checkout's uncommitted work into it;
+   verify CWD is inside it (`pwd` + `git worktree list`).
 4. Commit the four steps on the feature branch. No code until the commit lands.
 
+**The base checkout's uncommitted work moves with the stream.** A worktree cut
+from a dirty base strands that work on the default branch, where it is neither
+committed, nor reviewed, nor in the tree the stream is about to gate — and the
+next `git status` there reads as drift nobody owns. So step 3 moves it, before
+any spec edit:
+
+```bash
+git -C <base> status --porcelain -uall            # nothing? the step is a no-op
+git -C <base> stash push --include-untracked -m "chore(open): <branch>"
+git -C <worktree> stash pop
+```
+
+`git stash` is per-repository, not per-worktree, so the entry the base pushes is
+the entry the worktree pops. **Move, never copy** — work left in both places is
+committed twice and conflicts on the merge. Name what came across in the
+CHORE(open) report; a carry-over nobody announced is indistinguishable from
+scope that wandered in. A pop that conflicts KEEPS the stash: stop there and
+resolve before step 4, because a half-applied carry-over is worse than a dirty
+base. Work that does not belong to this stream is the one exception — leave it,
+and say so.
+
 <!-- oracle-packs:start product.agentsfleet -->
 ## Worktree recipe (agentsfleet)
 
-`git checkout main && git branch feat/mNN-name && git worktree add ../agentsfleet-mNN-name feat/mNN-name && cd ../agentsfleet-mNN-name && bun install && (cd cli && bun install && bun run build)`.
-The root `bun install` hydrates the workspace (`ui/packages/*`); `cli/` is its
-own Bun project needing install + build. `git worktree add` fires
-`.githooks/post-checkout` → symlinks `~/.config/agentsfleet/{ui,runner}.env.local`
-into the tree; on 🟠 run `provision-env-1password`, re-link. Post-merge:
-`git worktree remove ../agentsfleet-mNN-name`.
-
-**Test Baseline counter.** A repository whose declared `verify.unit` does not
-print a total names its own counter here. Without one, record the count the
-declared command reports.
+```bash
+cd ~/Projects/agentsfleet && git checkout main
+git status --porcelain -uall     # dirty? carry it over — the two stash lines below
+git stash push --include-untracked -m "chore(open): feat/mNN-name"
+git branch feat/mNN-name
+git worktree add ../agentsfleet-mNN-name feat/mNN-name
+cd ../agentsfleet-mNN-name && git stash pop
+```
+
+Omit stash operations when the base is clean. Identify the saved stash entry
+explicitly when other streams exist, restore its staged state, and remove only
+that entry after successful restoration. Leave changes owned by another stream
+in place and report them. No application installation or build runs here.
+`git worktree add` may run the repository's cheap environment-link hook.
+
+At first Section verification, install dependencies for the surfaces being
+verified: root `bun install` for the JavaScript workspace; `cli/` has its own
+install and build. Rust checks run from `rustd/` using `make lint-rustd` after
+`cargo fmt`. The first compilation resolves Rust dependencies; later Sections
+reuse the build artifacts. Missing environment links follow the repository's
+provisioning instructions before a check that needs them.
 
 **agentsfleet CHORE(close) paths:** the `<Update>` lands in
 `~/Projects/docs/changelog.mdx` (template + version-bump matrix:
@@ -99,8 +152,9 @@ into a separate tree.
   guesses `surfaces`.
   First session in a repository whose config is still that seed:
   1. Read the build files properly. Fill every `verify.*` the repository really
-     has — the tiering is fixed (`conform` + `verify.unit` are the fast tier,
-     every other `verify.*` is slow and skips on prose-only branches).
+     has — the gate ownership is fixed: `conform` at commit, non-test checks at
+     push, all `verify.*` at the PR boundary; only integration and memory
+     skip on branches with no code.
   2. Set `surfaces.user` and `surfaces.docs` to real path prefixes, or the docs
      gate can never fire and a user-visible change ships undocumented.
   3. Add any opt-in pack the repository's own sources cannot imply
@@ -108,8 +162,10 @@ into a separate tree.
      `orly update` so they materialise.
   4. Commit it. Every teammate and every later session reads this file, and
      `orly` never rewrites it — so an edit here is permanent.
-  A seeded-but-uncompleted config is why `orly gate` reports a repository with
-  no declared commands: the fix is this list, not another `orly init`.
+  Setup requires `conform` and at least one named `verify.*` command.
+  A documentation repository can declare `verify.docs` for its site and link
+  checks without application unit or integration suites. `init` reports
+  missing commands; `doctor` and the gates reject incomplete setup.
 - **Priming:** (1) Human runs `playbooks/founding/01_bootstrap/001_playbook.md`.
   (2) Agent runs `./playbooks/founding/02_preflight/00_gate.sh` (green before
   next). (3) Agent runs `playbooks/founding/03_priming_infra/001_playbook.md`.

package/dispatch/verify.md

@@ -25,58 +25,40 @@ Only when a target is genuinely unrunnable (e.g. Docker missing for integration
 tests). Surface the limitation in the done message — never dress a skip as "tests
 pass".
 
-## Why `make` is canonical
+## Repository commands are canonical
 
-Package-scoped runners (`bun run test`, `vitest <file>`, `cargo test -p <crate>`)
-are **not** verification — they skip every other package's lint and tests and the
-cross-language gates. The declared `make` targets are the canonical gates.
+The commands in `.oracle/orly.json` define full verification. Use repository
+Make targets where declared; a repository may also declare its native tools
+directly. A narrower package run never substitutes for a declared full check.
+Documentation repositories may use `verify.docs` for site and link checks;
+application test suites are required only when the repository declares them.
 
 ## Two cadences, one boundary
 
-"Always" is not a cadence. A Section closing and a milestone closing are
-different claims, and running the whole declared set at both spends the
-wall-clock of the comprehensive tier to answer a question the scoped lane
-already answered.
-
-The gates match those cadences: `orly gate work` runs the declared `conform`
-alone (every commit, seconds), `orly gate verify` runs the fast `verify.*` set
-(every push), and `orly gate pr` runs the whole-branch criteria and the slow
-suites (the close). Each tier runs once per cadence.
-
-**Section lane (per Section, and per done-claim inside one).** `make
-harness-verify` — the declared `conform`, seconds — plus the lane that covers
-the surface the Section touched (`make test-unit-rustd`, `make test-unit-app`,
-…). This proves a Section. It is not a repository claim and never satisfies a
-VERIFY row on its own.
-
-**Milestone boundary (once, at CHORE(close), before the PR).** Every command
-`.oracle/orly.json` declares, in one pass: `conform`, `verify.lint`,
-`verify.unit`, `verify.version`, and the slow tier (`verify.integration`,
-`verify.memory`). This is the repository claim, and it is what the done-message
-below reports.
-
-Run `orly gate pr` at the close. It does not re-run the fast tier, and it does
-not need to: its own `git.pushed` criterion proves HEAD is exactly the commit
-the pre-push `orly gate verify` already graded. A bare `orly gate` chains all
-three gates — use it on a branch whose earlier gates never ran.
-
-| Target | When |
-|---|---|
-| `make harness-verify` | Section lane and boundary. The declared `conform` — the deterministic gate audit. |
-| `make lint-all` | Boundary. The declared `verify.lint`. |
-| `make test-unit-all` | Boundary. The declared `verify.unit` — the cargo workspace plus every package coverage gate. |
-| `make check-version` | Boundary. The declared `verify.version`. |
-| `make test-integration-rustd` | Boundary. The declared `verify.integration` — live Postgres and Redis; `orly gate pr` skips it on a branch carrying no code. |
-| `make wire-fixtures` | The `/v1/runners` wire types changed. Regenerate, then review the diff — a changed fixture IS the wire change. |
-| `make bench` (local) | Diff touches request-path code, allocator wiring, or startup/shutdown sequencing. |
-| `API_BENCH_URL=https://api-dev.agentsfleet.net/healthz make bench` | After branch deploys to dev. |
-| `/orly-write-integration-test` (skill) | With `/orly-write-unit-test` at VERIFY when the diff crosses module boundaries with real I/O; otherwise record `N/A — <reason>`. |
-| Acceptance e2e (live tier) | Diff touches a surface the live/acceptance tier covers — relevant suites green, or their opt-in skip matrix recorded. |
-
-The declared set in `.oracle/orly.json` is the source of truth for what exists,
-and a lane listed there is a lane that runs at the boundary — including the slow
-tier. A package-scoped runner (`cargo test -p afd_wire`, `bun run test` inside a
-package) proves that package and never the repository, at either cadence.
+The command ownership and chronological sequence live in
+`dispatch/lifecycle.md` §What runs at each stage. Read that table before
+verification; this page defines what counts as evidence.
+
+- **Section proof:** format, lint, and run the tests covering the changed
+  Dimensions. Hydrate the required application dependencies at the first
+  Section verification, then reuse that worktree. Passing lint alone never
+  marks a behavior DONE.
+- **Baseline:** before the Pull Request, measure the recorded comparison
+  revision's declared unit and integration lanes. Keep commands, counts, and
+  output in an evidence report. Compare equivalent selections; explain removed
+  tests. A historical failure never exempts the final branch.
+- **Final verification:** `orly gate pr` runs every declared `verify.*` command
+  itself. It does not infer success from a pushed branch or an installed hook.
+  Capture full command output and the decisive counts, not only exit codes.
+  Custom hooks may run additional checks but cannot replace the final gate.
+- **Repeat only for cause:** a failure or a subsequent change invalidating the
+  result requires a rerun. Run the final gate once per candidate; do not also
+  launch its full suites manually as an unrecorded duplicate.
+
+Use repository-owned Make targets where declared. A narrower package run is
+Section evidence only, never a substitute for the full declared boundary.
+When a diff crosses a module boundary with real input/output, apply
+`orly-write-integration-test`; otherwise record why it does not apply.
 
 ## Wire-fixture evidence rule