tickmarkr 1.83.0 → 1.85.0

package/dist/compile/collateral.js

@@ -1,6 +1,7 @@
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import { extname, join, relative } from "node:path";
 import picomatch from "picomatch";
+import { criticalPathHits, DEFAULT_CONFIG, DEFAULT_REVIEW_CRITICAL_PATHS, effectiveReviewPolicy, loadConfig, } from "../config/config.js";
 import { renderAcceptanceItem } from "../graph/schema.js";
 // Advisory plan-time scan only (OBS-12/13/14/21, OBS-76). NEVER expands files[], fails compile,
 // or feeds the scope gate — a warning the author acts on. Plain-text (no AST), capped + sorted.
@@ -320,7 +321,297 @@ export function taskBudgetErrors(tasks) {
     }
     return errors;
 }
-/** Every Task Unit Contract violation in one pass, ready to throw. */
-export function taskUnitContractErrors(tasks) {
-    return [...separabilityErrors(tasks), ...taskBudgetErrors(tasks)];
+// ── R2 velocity lints (OVERSEER-RULING-20260731-velocity) ───────────────────────────────────
+// v1.84's T1 cost nine review rounds enforcing law the compiler could have refused at authoring
+// time. These three bounds are that refusal: a bounded task surface, goal prose forced down into
+// judge/test criteria, and criteria that may not name symbols owned outside the task's files[].
+/**
+ * Max acceptance × files[] surface per task (OVERSEER-RULING-20260731-velocity, R2:
+ * `surface = acceptance.length × files.length > 24` fails compile). EVERY criterion counts —
+ * a judge item is still a thing one worker must satisfy and one reviewer must verify in the
+ * same pass, and counting only test oracles let judge-heavy tasks bypass the bound (the first
+ * T6 attempt was rejected for exactly that narrowing). The calibration corpus pins the bound:
+ * v1.84's original T1 measures 6×5=30 and fails; v1.79's tasks pass — its widest, T5 at
+ * 4×7=28, rides the recorded exception below rather than redefining the metric.
+ */
+export const MAX_TASK_SURFACE = 24;
+/**
+ * Max goal words per acceptance criterion (v1.84's T1 measured 75). Gameable only by adding
+ * criteria — which is the point: every law migrated from goal prose to a criterion moves its
+ * enforcement from the 40-minute review round to the 2-minute judge.
+ */
+export const MAX_GOAL_WORDS_PER_CRITERION = 60;
+export const SURFACE_CONTRACT_EXCEPTIONS = [
+    {
+        id: "T5",
+        acceptance: 4,
+        files: [
+            "src/adapters/prompt.ts", "src/gates/acceptance.ts", "src/gates/llm.ts", "src/gates/review.ts",
+            "tests/gates/acceptance.test.ts", "tests/gates/judge-retry.test.ts", "tests/gates/review.test.ts",
+        ],
+        reason: "v1.79 T5 (4×7=28) — the velocity ruling's own fast baseline (7/7 in 89 min), shipped green "
+            + "before R2 existed; the bound was calibrated FROM this corpus, not retroactively enforced on it.",
+    },
+    {
+        id: "T4",
+        acceptance: 5,
+        files: [
+            "src/gates/run-gates.ts", "src/run/daemon.ts",
+            "tests/gates/pipeline.test.ts", "tests/gates/review-retry.test.ts", "tests/gates/run-gates.test.ts",
+        ],
+        reason: "v1.85 T4 (5×5=25) — recorded in specs/v1.85-speed-truth.spec.md's Not-in-scope block: the two "
+            + "retry-seam test pins are non-negotiable collateral and splitting the pipeline task would "
+            + "re-serialize it.",
+    },
+];
+function matchesSurfaceException(t, exceptions) {
+    const files = (t.files ?? []).map((f) => f.replace(/^\.\//, "")).sort();
+    const items = t.acceptance?.length ?? 0;
+    for (const ex of exceptions) {
+        if (ex.id !== t.id || ex.acceptance !== items)
+            continue;
+        const exFiles = [...ex.files].sort();
+        if (exFiles.length === files.length && exFiles.every((f, i) => f === files[i]))
+            return ex;
+    }
+    return undefined;
+}
+/**
+ * R2 surface bound: acceptance criteria × files[] patterns, one error per offending task.
+ * `exceptions` defaults to the recorded contract amendments; tests pass [] to prove an
+ * exception is load-bearing.
+ */
+export function surfaceErrors(tasks, exceptions = SURFACE_CONTRACT_EXCEPTIONS) {
+    const errors = [];
+    for (const t of tasks) {
+        const items = t.acceptance?.length ?? 0;
+        const files = t.files?.length ?? 0;
+        const surface = items * files;
+        if (surface <= MAX_TASK_SURFACE)
+            continue;
+        if (matchesSurfaceException(t, exceptions))
+            continue; // recorded contract amendment
+        errors.push(`${t.id} has an acceptance×files surface of ${surface} (${items} criteria × ${files} files[] `
+            + `patterns), above the ${MAX_TASK_SURFACE} bound — split the task so one worker builds and one `
+            + `reviewer verifies a smaller unit in a single pass (R2).`);
+    }
+    return errors;
+}
+/** Words carrying at least one letter or digit in ANY script — bare dashes and bullets are not words. */
+function goalWordCount(goal) {
+    return goal.split(/\s+/).filter((w) => /[\p{L}\p{N}]/u.test(w)).length;
+}
+/** R2 goal-density bound: goal words per acceptance criterion, one error per offending task. */
+export function goalDensityErrors(tasks) {
+    const errors = [];
+    for (const t of tasks) {
+        const items = t.acceptance?.length ?? 0;
+        if (!items || !t.goal)
+            continue;
+        const words = goalWordCount(t.goal);
+        const ratio = Math.round((words / items) * 10) / 10;
+        if (ratio > MAX_GOAL_WORDS_PER_CRITERION) {
+            errors.push(`${t.id} carries a goal of ${ratio} words per acceptance criterion (${words} words ÷ ${items} `
+                + `criteria), above the ${MAX_GOAL_WORDS_PER_CRITERION} bound — move goal prose into judge/test `
+                + `criteria; law that lives only in prose is enforced by a 40-minute review round instead of the `
+                + `2-minute judge (R2).`);
+        }
+    }
+    return errors;
+}
+// planFrame class (OBS-248): `export function NAME`, `export const NAME =`, `class NAME` etc.
+// Token heuristic like criteriaSymbols — definition keywords only, no AST, no method/property forms.
+function definitionRe(symbol) {
+    return new RegExp(`(?:^|\\n)[ \\t]*(?:export\\s+(?:default\\s+)?)?(?:async\\s+)?`
+        + `(?:function\\*?\\s+|const\\s+|let\\s+|var\\s+|class\\s+|interface\\s+|type\\s+|enum\\s+)${symbol}\\b`);
+}
+/**
+ * The blocking ownership lint gets its own index, NOT walkCode: walkCode is a capped, fail-open
+ * ADVISORY scan (400 files, src/ only, skips giant and unreadable files) — the right shape for
+ * plan-time warnings, wrong for a compile error. A unique definition hiding in the 401st file,
+ * another code root (tests/, scripts/, a root-level config), or a skipped file would silently
+ * pass. This walk is complete: every code file under the repo root, no count cap, no size cap,
+ * and anything unreadable is reported so the lint can fail closed instead of trusting a
+ * partial scan. Generated mirrors are not definition sites: dist/ is tsc's copy of src/
+ * (rebuilt by the test gate's pretest), so indexing it would double every definition and read
+ * every unique site as ambiguous — the ownership rule indexes SOURCE only.
+ */
+function walkAllCode(repoRoot) {
+    const files = [];
+    const unreadable = [];
+    const rel = (full) => relative(repoRoot, full).split("\\").join("/") || ".";
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            unreadable.push(rel(dir));
+            return;
+        }
+        entries.sort((a, b) => a.name.localeCompare(b.name));
+        for (const e of entries) {
+            if (e.name === "node_modules" || e.name === ".git" || e.name === "dist" || e.name.startsWith("."))
+                continue;
+            const full = join(dir, e.name);
+            if (e.isDirectory()) {
+                walk(full);
+                continue;
+            }
+            if (!e.isFile() || !CODE_EXT.test(e.name))
+                continue;
+            files.push(rel(full));
+        }
+    };
+    try {
+        if (!statSync(repoRoot).isDirectory())
+            return { files, unreadable }; // no root: empty index
+    }
+    catch {
+        return { files, unreadable };
+    }
+    walk(repoRoot);
+    return { files, unreadable };
+}
+/**
+ * R2 symbol ownership: a code identifier named in a judge or test criterion that resolves uniquely
+ * to a definition OUTSIDE the task's files[] is unsatisfiable by construction — the v1.84 T1
+ * planFrame defect, which burned two review rounds because the enabling symbol lived in another
+ * task's file. Zero definition sites (plain-language false positive, external symbol, or a file
+ * the task itself creates) and ambiguous tokens (multiple definition sites) stay silent. The index
+ * must be COMPLETE: any code path that cannot be read is its own error — the rule fails closed
+ * rather than trust a partial scan.
+ */
+export function symbolOwnershipErrors(tasks, repoRoot) {
+    const perTask = tasks
+        .map((t) => ({ t, symbols: criteriaSymbols(t.acceptance ?? []) }))
+        .filter((x) => x.symbols.length);
+    if (!perTask.length)
+        return [];
+    const { files: codeFiles, unreadable } = walkAllCode(repoRoot);
+    const errors = [];
+    const incomplete = (path) => `cannot prove the symbol-ownership rule for ${perTask.map((x) => x.t.id).join(", ")}: ${path} `
+        + `is unreadable, so the code index is incomplete — restore read access (or remove the path) and `
+        + `recompile; the ownership lint fails closed rather than trust a partial scan (OBS-248).`;
+    for (const u of unreadable)
+        errors.push(incomplete(u));
+    // resolve each symbol to its definition site(s) once, shared across tasks
+    const allSymbols = [...new Set(perTask.flatMap((x) => x.symbols))];
+    const res = new Map(allSymbols.map((s) => [s, definitionRe(s)]));
+    const sites = new Map(allSymbols.map((s) => [s, []]));
+    for (const cf of codeFiles) {
+        let text;
+        try {
+            text = readFileSync(join(repoRoot, cf), "utf8"); // no size cap — a skipped file is a blind spot
+        }
+        catch {
+            errors.push(incomplete(cf));
+            continue;
+        }
+        for (const sym of allSymbols) {
+            if (text.includes(sym) && res.get(sym).test(text))
+                sites.get(sym).push(cf);
+        }
+    }
+    for (const { t, symbols } of perTask) {
+        // OBS-22: scopeGate accepts picomatch globs; ownership must agree.
+        const scoped = picomatch(t.files.map((f) => f.replace(/^\.\//, "")), { dot: true });
+        for (const sym of symbols) {
+            const defs = sites.get(sym) ?? [];
+            if (defs.length !== 1)
+                continue; // unknown or ambiguous — silent by ruling
+            const site = defs[0];
+            if (scoped(site))
+                continue; // defined inside the task's own write surface
+            errors.push(`${t.id}: criterion identifier "${sym}" is defined only in ${site}, which is not in files[] — `
+                + `add ${site} to files[] or reword the criterion; a worker scoped to files[] cannot satisfy a `
+                + `criterion whose enabling symbol lives outside it (OBS-248).`);
+        }
+    }
+    return errors;
+}
+/**
+ * R3 review participation (OVERSEER-RULING-20260731-velocity; OBS-186). The compiler assigns
+ * `reviewPolicy` from the DECLARED files[] — `judge-only` only when every declared path is provably
+ * docs/CHANGELOG/RELEASING/version-mirror leaf work — and the operator's floor may raise it. A task
+ * that would SKIP review while touching `review.criticalPaths` is the exact shape OBS-186 caught in
+ * the field: the riskiest task in the bundle silently declining the one gate that exists for it. That
+ * cannot be a warning, because nothing downstream would stop it — the gate would honour the policy.
+ */
+export function reviewParticipationErrors(tasks, review) {
+    // The shipped critical paths are a FLOOR, not a default that a config replaces: this lint resolves
+    // its config from a repo root the compile seam cannot always name (see taskUnitContractErrors), and
+    // the one direction that must never happen is a wrong root lowering enforcement below what tickmarkr
+    // ships. Union is monotone — a repo-local list can only add.
+    const critical = [...new Set([...DEFAULT_REVIEW_CRITICAL_PATHS, ...(review.criticalPaths ?? [])])];
+    const errors = [];
+    for (const t of tasks) {
+        const files = t.files ?? [];
+        const policy = effectiveReviewPolicy(files, review);
+        // The non-monotone switch, caught at the only seam that can still refuse the graph. A shape
+        // override cannot demote a task the paths assigned `full` — that is precisely the demotion
+        // review.policy is structurally incapable of, arriving through a second door.
+        const shapeOff = t.shape !== undefined && review.byShape?.[t.shape]?.review === false;
+        if (policy === "full" && shapeOff) {
+            errors.push(`${t.id} declares full-review work (reviewPolicy full — at least one declared path is not `
+                + `leaf-class) while gates.byShape.${t.shape}.review: false would omit the review gate — `
+                + `remove that override, or narrow files[] to docs/CHANGELOG/RELEASING/version-mirror leaf `
+                + `work; participation is decided by paths, and config may raise a policy, never lower one (R3).`);
+            continue;
+        }
+        if (policy !== "judge-only" && !shapeOff)
+            continue; // full review actually runs — nothing skips
+        const hits = criticalPathHits(files, critical);
+        if (!hits.length)
+            continue;
+        const why = policy === "judge-only"
+            ? "reviewPolicy judge-only — every declared path is leaf-class work"
+            : `gates.byShape.${t.shape}.review: false`;
+        errors.push(`${t.id} would skip cross-vendor review (${why}) `
+            + `while touching review.criticalPaths ${hits.join(", ")} — narrow files[] out `
+            + `of the critical path, or set review.policy: full so the task is reviewed; participation is `
+            + `decided by paths, and a critical path may never be reviewed by the judge alone (R3).`);
+    }
+    return errors;
+}
+/**
+ * The ACTIVE participation config for a compile rooted at `repoRoot`. Same default-argument contract
+ * as `repoRoot` itself: the CLI and daemon compile from inside the target repo, so the repo's own
+ * config (plus the global overlay) is the config the run will gate under. A config the loader cannot
+ * read degrades to the shipped defaults rather than crashing the compile — every command that reaches
+ * this seam loads the same config itself and reports a malformed one loudly.
+ */
+function activeReviewParticipation(repoRoot) {
+    try {
+        const cfg = loadConfig(repoRoot);
+        return { ...cfg.review, byShape: cfg.gates.byShape };
+    }
+    catch {
+        return { ...DEFAULT_CONFIG.review, byShape: DEFAULT_CONFIG.gates.byShape };
+    }
+}
+/**
+ * Every Task Unit Contract violation in one pass, ready to throw. `repoRoot` backs the
+ * symbol-ownership lint and the participation config, and defaults to the invocation directory —
+ * correct for the CLI/daemon, which compile from inside the target repo.
+ *
+ * KNOWN GAP (R2 review, T6/T7 scope): the compile seam in src/compile/index.ts
+ * (`enforceTaskUnitContract`) does not thread `compileSource`'s `root` argument into this call, so a
+ * PROGRAMMATIC compile whose target repo differs from process.cwd() resolves the wrong root and can
+ * miss that repo's own `review.criticalPaths`. Threading it is one line in src/compile/index.ts,
+ * outside this task's file scope. Two things bound the exposure meanwhile, both live: the critical
+ * set here is the UNION with the shipped defaults, so a wrong root can never lower enforcement below
+ * the shipped floor; and the review GATE — which is handed the run's real config — refuses to skip a
+ * critical path itself (src/gates/review.ts), so a lint this seam misses costs a late verdict rather
+ * than an unreviewed one. The compile lint is the early warning; the gate is the fail-closed backstop.
+ */
+export function taskUnitContractErrors(tasks, repoRoot = process.cwd(), review = activeReviewParticipation(repoRoot)) {
+    return [
+        ...separabilityErrors(tasks),
+        ...taskBudgetErrors(tasks),
+        ...surfaceErrors(tasks),
+        ...goalDensityErrors(tasks),
+        ...symbolOwnershipErrors(tasks, repoRoot),
+        ...reviewParticipationErrors(tasks, review),
+    ];
 }

package/dist/config/config.d.ts

@@ -52,6 +52,63 @@ export declare const SubPricingSchema: z.ZodObject<{
     windowsPerMonthHigh: z.ZodNumber;
 }, z.core.$strip>;
 export type SubPricing = z.infer<typeof SubPricingSchema>;
+export declare const REVIEW_POLICIES: readonly ["full", "judge-only"];
+export type ReviewPolicy = (typeof REVIEW_POLICIES)[number];
+/**
+ * The leaf class: work a judge alone can carry because there is no behaviour to review. It is CLOSED
+ * and enumerated here — documentation pages, the changelog, the release runbook, and the version
+ * mirrors a release bump rewrites. Everything else, including tests and scripts, is full-review work.
+ */
+export declare const REVIEW_LEAF_GLOBS: readonly ["docs/**", "CHANGELOG.md", "RELEASING.md", "package.json", "package-lock.json"];
+/**
+ * The version mirrors a release bump rewrites — and ONLY at the repo root: `docs/package.json` is a
+ * real manifest for something, not a mirror. Membership here is still a claim about paths, and a
+ * manifest diff that moves more than the version field leaves the class; the gate re-tests that
+ * against the actual diff content (src/gates/review.ts) because a path cannot say it by itself.
+ */
+export declare const REVIEW_VERSION_MIRRORS: ReadonlySet<string>;
+/**
+ * Paths whose review may never be skipped (R3): the gate/run/driver/adapter surface — lifecycle,
+ * demux, and everything that reaches a shell. Shipped as the default so the compile lint that
+ * enforces them is live in a repo that never configures anything.
+ */
+export declare const DEFAULT_REVIEW_CRITICAL_PATHS: readonly ["src/gates/**", "src/run/**", "src/drivers/**", "src/adapters/**"];
+/**
+ * True when `path` — an ACTUAL path a diff touched — is provably leaf-class work. Enumerated, closed,
+ * and positive: the two named root files, the two root version mirrors, and documentation formats
+ * under `docs/`. Everything else, including a `.vue`/`.svelte`/`Makefile`/`package.json` parked under
+ * `docs/`, is behaviour and draws a full review.
+ */
+export declare function isReviewLeafPath(path: string): boolean;
+/**
+ * True when a DECLARED pattern may claim leaf work. A declaration is a claim about a directory, not
+ * a file: `docs/**` is how a documentation task declares itself and has to stay claimable, so a glob
+ * rooted at `docs/` reads leaf here while `docs/tool.ts` does not read leaf above. The claim is never
+ * the last word — reviewGate re-tests it against what the diff actually touched and promotes when the
+ * diff leaves the class. A glob rooted anywhere else can claim nothing.
+ */
+export declare function isReviewLeafDeclaration(pattern: string): boolean;
+/** full beats judge-only. The join is monotone by construction: nothing here can LOWER a policy. */
+export declare function raiseReviewPolicy(...policies: ReadonlyArray<ReviewPolicy | undefined>): ReviewPolicy;
+/**
+ * The compiler's assignment, from the task's DECLARED files[]. judge-only only when EVERY declared
+ * path is provably leaf work — one non-leaf pattern (or an empty files[]) makes it full.
+ */
+export declare function declaredReviewPolicy(files: ReadonlyArray<string>): ReviewPolicy;
+/** The declared assignment after the operator's floor is applied — config may raise it, never lower it. */
+export declare function effectiveReviewPolicy(files: ReadonlyArray<string>, review: {
+    policy?: ReviewPolicy;
+}): ReviewPolicy;
+/**
+ * Declared patterns that intersect a critical path. Directional containment is the certain half — a
+ * critical `src/gates/**` contains a declared `src/gates/review.ts`, and a declared `docs/**` contains
+ * a critical `docs/security/**`. It is NOT intersection: two globs can overlap without either matching
+ * the other as a literal string, which is how a judge-only task declaring `docs/**\/README.md` slipped
+ * past a critical `docs/security/*.md`. When BOTH sides are globs the conservative overlap test above
+ * decides, and it decides toward flagging — an over-flagged task is narrowed by its author, an
+ * under-flagged one skips the only gate that exists for it.
+ */
+export declare function criticalPathHits(files: ReadonlyArray<string>, criticalPaths?: ReadonlyArray<string>): string[];
 export declare const TickmarkrConfigSchema: z.ZodObject<{
     concurrency: z.ZodNumber;
     driver: z.ZodEnum<{
@@ -173,6 +230,11 @@ export declare const TickmarkrConfigSchema: z.ZodObject<{
         complexityThreshold: z.ZodNumber;
         required: z.ZodBoolean;
         prefer: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        policy: z.ZodOptional<z.ZodEnum<{
+            full: "full";
+            "judge-only": "judge-only";
+        }>>;
+        criticalPaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>;
     consult: z.ZodObject<{
         adapter: z.ZodString;

package/dist/config/config.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import picomatch from "picomatch";
 import { parse, stringify } from "yaml";
 import { z } from "zod";
 import { stateDirName } from "../graph/graph.js";
@@ -73,6 +74,143 @@ export const SubPricingSchema = z
     windowsPerMonthHigh: z.number().int().positive(),
 })
     .refine((s) => s.windowsPerMonthLow <= s.windowsPerMonthHigh, "windowsPerMonthLow must be ≤ windowsPerMonthHigh");
+// ── Review participation (R3 of OVERSEER-RULING-20260731-velocity; OBS-186) ────────────────────
+// Participation is keyed on PATHS — what a task DECLARES at compile time and what its diff ACTUALLY
+// touches at gate time — never on complexity. `complexityThreshold` capped participation at a number
+// the authoring law forbade tasks from reaching, so cross-vendor review was unreachable by
+// construction while `required: true` claimed the opposite. Paths cannot drift out from under the
+// gate that way: the same predicate decides both ends.
+export const REVIEW_POLICIES = ["full", "judge-only"];
+/**
+ * The leaf class: work a judge alone can carry because there is no behaviour to review. It is CLOSED
+ * and enumerated here — documentation pages, the changelog, the release runbook, and the version
+ * mirrors a release bump rewrites. Everything else, including tests and scripts, is full-review work.
+ */
+export const REVIEW_LEAF_GLOBS = [
+    "docs/**", "CHANGELOG.md", "RELEASING.md", "package.json", "package-lock.json",
+];
+/**
+ * Membership is a POSITIVE rule, not a blacklist. A blacklist of source extensions is a list of the
+ * formats someone thought of, and everything nobody thought of — `docs/widget.vue`, `docs/site.svelte`,
+ * `docs/Makefile`, `docs/package.json`, an extensionless script — falls into the leaf class and skips
+ * its review. That direction of failure is the whole defect OBS-186 names, so the rule is inverted:
+ * under `docs/` a path is leaf work only when its extension is a DOCUMENTATION format. An unknown
+ * format is behaviour until proven otherwise, which is the fail-closed direction.
+ */
+const REVIEW_DOC_EXT_RE = /\.(?:md|mdx|markdown|txt|rst|adoc|asciidoc)$/i;
+/**
+ * The version mirrors a release bump rewrites — and ONLY at the repo root: `docs/package.json` is a
+ * real manifest for something, not a mirror. Membership here is still a claim about paths, and a
+ * manifest diff that moves more than the version field leaves the class; the gate re-tests that
+ * against the actual diff content (src/gates/review.ts) because a path cannot say it by itself.
+ */
+export const REVIEW_VERSION_MIRRORS = new Set(["package.json", "package-lock.json"]);
+/** The changelog and the release runbook, at the repo root, by exact name. */
+const REVIEW_LEAF_FILES = new Set(["CHANGELOG.md", "RELEASING.md"]);
+/**
+ * Paths whose review may never be skipped (R3): the gate/run/driver/adapter surface — lifecycle,
+ * demux, and everything that reaches a shell. Shipped as the default so the compile lint that
+ * enforces them is live in a repo that never configures anything.
+ */
+export const DEFAULT_REVIEW_CRITICAL_PATHS = [
+    "src/gates/**", "src/run/**", "src/drivers/**", "src/adapters/**",
+];
+const GLOB_META_RE = /[*?[\]{}]/;
+const normPath = (p) => p.replace(/^\.\//, "").trim();
+/**
+ * True when `path` — an ACTUAL path a diff touched — is provably leaf-class work. Enumerated, closed,
+ * and positive: the two named root files, the two root version mirrors, and documentation formats
+ * under `docs/`. Everything else, including a `.vue`/`.svelte`/`Makefile`/`package.json` parked under
+ * `docs/`, is behaviour and draws a full review.
+ */
+export function isReviewLeafPath(path) {
+    const p = normPath(path);
+    if (!p.length)
+        return false;
+    if (REVIEW_LEAF_FILES.has(p) || REVIEW_VERSION_MIRRORS.has(p))
+        return true;
+    return p.startsWith("docs/") && REVIEW_DOC_EXT_RE.test(p);
+}
+/**
+ * True when a DECLARED pattern may claim leaf work. A declaration is a claim about a directory, not
+ * a file: `docs/**` is how a documentation task declares itself and has to stay claimable, so a glob
+ * rooted at `docs/` reads leaf here while `docs/tool.ts` does not read leaf above. The claim is never
+ * the last word — reviewGate re-tests it against what the diff actually touched and promotes when the
+ * diff leaves the class. A glob rooted anywhere else can claim nothing.
+ */
+export function isReviewLeafDeclaration(pattern) {
+    const p = normPath(pattern);
+    if (!p.length)
+        return false;
+    return isReviewLeafPath(p) || (GLOB_META_RE.test(p) && p.startsWith("docs/"));
+}
+/** full beats judge-only. The join is monotone by construction: nothing here can LOWER a policy. */
+export function raiseReviewPolicy(...policies) {
+    return policies.includes("full") ? "full" : "judge-only";
+}
+/**
+ * The compiler's assignment, from the task's DECLARED files[]. judge-only only when EVERY declared
+ * path is provably leaf work — one non-leaf pattern (or an empty files[]) makes it full.
+ */
+export function declaredReviewPolicy(files) {
+    const declared = files.map(normPath).filter((f) => f.length > 0);
+    return declared.length > 0 && declared.every(isReviewLeafDeclaration) ? "judge-only" : "full";
+}
+/** The declared assignment after the operator's floor is applied — config may raise it, never lower it. */
+export function effectiveReviewPolicy(files, review) {
+    return raiseReviewPolicy(declaredReviewPolicy(files), review.policy);
+}
+/** The literal head of a pattern — everything before its first glob metacharacter. */
+const literalPrefix = (p) => {
+    const i = p.search(GLOB_META_RE);
+    return i < 0 ? p : p.slice(0, i);
+};
+/** The literal tail of a pattern — everything after its last glob metacharacter. */
+const literalSuffix = (p) => p.replace(/^.*[*?[\]{}]/s, "");
+const eitherWay = (a, b, rel) => rel(a, b) || rel(b, a);
+/**
+ * Do two GLOBS have a path in common? Exact glob-vs-glob intersection is undecidable in general, so
+ * this fails CLOSED: the pair is treated as intersecting unless their literal heads or their literal
+ * tails prove they cannot meet. `docs/**\/README.md` vs `docs/security/*.md` share the head `docs/`
+ * and the tail `.md` is a tail of `/README.md`, so `docs/security/README.md` is correctly flagged;
+ * `src/**\/*.ts` vs `src/**\/*.md` share a head but neither tail contains the other, so they are not.
+ */
+const globsMayIntersect = (a, b) => eitherWay(literalPrefix(a), literalPrefix(b), (x, y) => x.startsWith(y))
+    && eitherWay(literalSuffix(a), literalSuffix(b), (x, y) => x.endsWith(y));
+/**
+ * Declared patterns that intersect a critical path. Directional containment is the certain half — a
+ * critical `src/gates/**` contains a declared `src/gates/review.ts`, and a declared `docs/**` contains
+ * a critical `docs/security/**`. It is NOT intersection: two globs can overlap without either matching
+ * the other as a literal string, which is how a judge-only task declaring `docs/**\/README.md` slipped
+ * past a critical `docs/security/*.md`. When BOTH sides are globs the conservative overlap test above
+ * decides, and it decides toward flagging — an over-flagged task is narrowed by its author, an
+ * under-flagged one skips the only gate that exists for it.
+ */
+export function criticalPathHits(files, criticalPaths = []) {
+    const hits = new Set();
+    for (const raw of files) {
+        const f = normPath(raw);
+        if (!f)
+            continue;
+        for (const rawCritical of criticalPaths) {
+            const critical = normPath(rawCritical);
+            if (!critical)
+                continue;
+            if (f === critical || picomatch(critical, { dot: true })(f) || picomatch(f, { dot: true })(critical)
+                || (GLOB_META_RE.test(f) && GLOB_META_RE.test(critical) && globsMayIntersect(f, critical))) {
+                hits.add(f);
+            }
+        }
+    }
+    return [...hits].sort();
+}
+// R3 (OBS-186): `review: false` here is a SECOND participation switch, and unlike review.policy it is
+// not monotone — it can omit the review gate from a task the path rules assigned `full`. Participation
+// is decided by paths, so the two are JOINED at the one seam that can still refuse the graph:
+// reviewParticipationErrors (src/compile/collateral.ts) fails compile when a shape's `review: false`
+// would demote a full-review task or silence a critical path. The key itself stays parseable (a run's
+// own config, the setup cockpit and the shipped template all round-trip it); what it can no longer do
+// is take effect behind the policy's back.
 const ShapeGateParticipationSchema = z
     .object({ acceptance: z.boolean().optional(), review: z.boolean().optional() })
     .passthrough()
@@ -157,7 +295,22 @@ export const TickmarkrConfigSchema = z.object({
     judge: z.object({ adapter: z.string(), model: z.string() }),
     // v1.53 T2: prefer — ordered reviewer preference (entry grammar: adapter | adapter:model, same as
     // routing.map.prefer). Reorders diversity-eligible channels only; never widens or narrows eligibility.
-    review: z.object({ complexityThreshold: z.number(), required: z.boolean(), prefer: z.array(z.string()).optional() }),
+    review: z.object({
+        // RETIRED as a participation switch (R3 / OBS-186, v1.85): review participation is decided by the
+        // paths a task declares and the paths its diff touches — never by complexity. The key survives
+        // because routing hints and the setup cockpit still read it as a complexity landmark; NOTHING in
+        // src/gates/review.ts reads it any more, and a value here can no longer disable a review.
+        complexityThreshold: z.number(),
+        required: z.boolean(),
+        prefer: z.array(z.string()).optional(),
+        // R3: the operator's participation floor. "full" forces a cross-vendor review on every task;
+        // "judge-only" is the neutral floor (it leaves the compiler's per-task assignment standing).
+        // Config may RAISE a task's policy and can never lower one — see raiseReviewPolicy.
+        policy: z.enum(REVIEW_POLICIES).optional(),
+        // R3: globs no task may skip review on (input/demux/lifecycle, gates/run/drivers/adapters, anything
+        // reaching a shell). A judge-only task intersecting one of these fails COMPILE, never silently skips.
+        criticalPaths: z.array(z.string()).optional(),
+    }),
     // v1.54 T1: prefer — ranked consult seat failover. Entries MUST be adapter:model (unlike
     // review.prefer's adapter|adapter:model grammar): a consult seat has no channel to inherit a
     // model from, so a bare adapter is meaningless and fails config load fail-closed. The pinned
@@ -303,7 +456,9 @@ export const DEFAULT_CONFIG = {
     pricing: { cheap: 0.1, mid: 0.5, frontier: 2.5 },
     gates: { diffCap: DEFAULT_DIFF_CAP },
     judge: { adapter: "claude-code", model: "fable" },
-    review: { complexityThreshold: 7, required: true },
+    // R3: no `policy` floor — the neutral floor leaves the compiler's per-task assignment standing, so
+    // the path-keyed rule is reachable out of the box rather than raised to full by construction.
+    review: { complexityThreshold: 7, required: true, criticalPaths: [...DEFAULT_REVIEW_CRITICAL_PATHS] },
     consult: { adapter: "claude-code", model: "fable", stallMinutes: 15 },
     // v1.4: gate LLM calls (judge/review/consult) run headless by default; pane opts back into visible agents.
     // v1.2: workers are the real agent TUI in the pane; "print" restores the -p-rendered-in-pane path.

package/dist/drivers/herdr.d.ts

@@ -2,6 +2,7 @@ import { type ExecutorDriver, type NotifyOpts, type Slot, type SlotOpts } from "
 export declare const TRAILER_SAFE_FLOOR_COLS = 108;
 export declare const TRAILER_WIDTH_MARGIN = 2;
 export declare const DELIVERY_ATTEMPTS = 3;
+export declare const DISPATCH_START_PREFIX = "TICKMARKR_START_";
 export interface HerdrTimeSource {
     now: () => number;
     sleep: (ms: number) => Promise<void>;
@@ -12,12 +13,20 @@ export declare class DeliveryReadinessError extends Error {
     readonly phase = "READINESS";
     constructor(waitedMs: number, transcript: string);
 }
+export declare class DeliveryCorruptedError extends Error {
+    readonly pane: string;
+    readonly transcript: string;
+    readonly phase = "DISPATCH";
+    constructor(pane: string, reason: string, transcript: string);
+}
+export type DriverJournal = (event: string, slotName: string, data: Record<string, unknown>) => void;
 /** First-generation join direction from measured trailer-safe floor (43-MEASUREMENT.md). */
 export declare function workerSplitDirection(paneCols: number | null, safeFloor?: number, margin?: number): "right" | "down";
 export declare class HerdrDriver implements ExecutorDriver {
     private bin;
     private workersPerTab;
     private time;
+    private journal?;
     id: string;
     interactive: boolean;
     private groups;
@@ -26,16 +35,18 @@ export declare class HerdrDriver implements ExecutorDriver {
     private dispatchLeases;
     private deliveredPanes;
     private inputBoxes;
+    private bootstraps;
+    private journalRoots;
     private ws;
     private callerPane;
     private watches;
-    constructor(bin?: string, workersPerTab?: number, time?: HerdrTimeSource);
+    constructor(bin?: string, workersPerTab?: number, time?: HerdrTimeSource, journal?: DriverJournal | undefined);
+    private appendDispatchRetry;
     private serial;
     private deliveryQueue;
     private reserveDispatch;
     private verifyPaneIdentityBinding;
     private deliveryMatches;
-    private shellExecutionEchoed;
     private submissionRegistered;
     static available(): boolean;
     private herdr;
@@ -52,7 +63,13 @@ export declare class HerdrDriver implements ExecutorDriver {
     private glyphFor;
     private joinGroup;
     run(slot: Slot, cmd: string): Promise<void>;
-    private deliver;
+    private dispatchWithRetry;
+    private isTuiTurn;
+    private dispatch;
+    private deliverAtomic;
+    private awaitDispatchAck;
+    private freshPane;
+    private deliverTyped;
     nudge(slot: Slot, message: string): Promise<boolean>;
     private deliverPersistentShellCommand;
     private submitVerifiedDelivery;