tickmarkr 2.2.1 → 2.4.0

package/dist/cli/commands/verify.js

@@ -1,16 +1,18 @@
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { allAdapters, probeAll, readDoctor, rolePools } from "../../adapters/registry.js";
 import { channelKey } from "../../adapters/types.js";
 import { loadConfig } from "../../config/config.js";
 import { captureBaseline, detectGateCommands } from "../../gates/baseline.js";
+import { modelProvider } from "../../gates/review.js";
 import { runGates } from "../../gates/run-gates.js";
 import { getTask, loadGraph } from "../../graph/graph.js";
 import { GATE_NAMES } from "../../graph/schema.js";
 import { linkNodeModules, removeWorktree, shGit, shGitOk } from "../../run/git.js";
+import { Journal } from "../../run/journal.js";
 /**
  * tickmarkr verify — the gate battery as a standalone command (OPERATING-MODEL-2026-08-11 item 3).
  *
@@ -59,7 +61,76 @@ const DIRTY_WHY = `refusing to gate a dirty worktree: the shell gates run agains
 export function verifyStateDir(cwd) {
     return join(realpathSync(tmpdir()), "tickmarkr-verify", createHash("sha256").update(cwd).digest("hex").slice(0, 12));
 }
+const STATE_FILES = ["graph.json", "doctor.json", "config.yaml"];
+const LOCKFILES = ["package-lock.json", "npm-shrinkwrap.json", "pnpm-lock.yaml", "yarn.lock", "bun.lock", "bun.lockb"];
+/** Linked worktrees share operational state with the repository that owns the common git dir. */
+export async function verifyStateRoot(cwd) {
+    const commonDir = resolve(cwd, (await shGitOk("git rev-parse --git-common-dir", cwd)).trim());
+    const commonRoot = realpathSync(dirname(commonDir));
+    if (commonRoot === realpathSync(cwd))
+        return cwd;
+    const localState = join(cwd, ".tickmarkr");
+    const commonState = join(commonRoot, ".tickmarkr");
+    return STATE_FILES.some((file) => !existsSync(join(localState, file)) && existsSync(join(commonState, file)))
+        ? commonRoot
+        : cwd;
+}
+const hashParts = (parts) => {
+    const hash = createHash("sha256");
+    for (const part of parts)
+        hash.update(part);
+    return hash.digest("hex").slice(0, 12);
+};
+/** Cache identity is repository content, never a checkout path. */
+export function baselineCachePath(cwd, baseSha, commands) {
+    const lockParts = [];
+    for (const file of LOCKFILES) {
+        const path = join(cwd, file);
+        lockParts.push(file, existsSync(path) ? readFileSync(path) : "<absent>");
+    }
+    const commandParts = Object.entries(commands).sort(([a], [b]) => a.localeCompare(b)).map(([name, command]) => `${name}\0${command}\0`);
+    return join(realpathSync(tmpdir()), "tickmarkr-verify", "cache", `baseline-${baseSha.slice(0, 12)}-${hashParts(lockParts)}-${hashParts(commandParts)}.json`);
+}
+const verdictlessCommands = (baseline, commands) => Object.keys(commands).filter((name) => baseline.commands[name]?.exitCode === undefined);
+export function excludeAuthorProvider(channels, author) {
+    const provider = modelProvider(author.model, author.vendor);
+    return [author, ...channels.filter((candidate) => candidate !== author && modelProvider(candidate.model, candidate.vendor) !== provider)];
+}
+function recordedMerges(repoRoot) {
+    const runs = join(repoRoot, ".tickmarkr", "runs");
+    if (!existsSync(runs))
+        return [];
+    const rows = [];
+    for (const runId of readdirSync(runs).filter((name) => name.startsWith("run-")).sort().reverse()) {
+        const path = join(runs, runId, "journal.jsonl");
+        if (!existsSync(path))
+            continue;
+        for (const line of readFileSync(path, "utf8").split("\n").filter(Boolean)) {
+            try {
+                const row = JSON.parse(line);
+                if (row.event === "merge" && row.taskId && row.data?.commit)
+                    rows.push({ runId, taskId: row.taskId, commit: row.data.commit });
+            }
+            catch { /* torn journal tail is not a merge record */ }
+        }
+    }
+    return rows;
+}
+async function warnWideTaskRange(cwd, stateRoot, taskId, mergeBase) {
+    const inRange = new Set((await shGitOk(`git rev-list --merges '${mergeBase}..HEAD'`, cwd)).trim().split("\n").filter(Boolean));
+    const merges = recordedMerges(stateRoot).filter((row) => inRange.has(row.commit));
+    const own = merges.find((row) => row.taskId === taskId);
+    const others = own ? merges.filter((row) => row.taskId !== taskId) : [];
+    if (own && others.length) {
+        console.error(`verify: WARNING --task ${taskId} range also carries merge commit(s) for ${others.map((row) => `${row.taskId} ${row.commit.slice(0, 12)}`).join(", ")}; ${taskId}'s own merge ${own.commit} is the intended HEAD`);
+    }
+}
+export const VERIFY_HELP = `usage: tickmarkr verify [--base <ref>] [--criteria <file> | --task <id>] [--json]
+The final verdict and JSON result are written to stdout; progress and diagnostics are written to stderr.
+Do not merge stdout and stderr (for example with 2>&1): doing so corrupts the verdict stream.`;
 export async function verify(argv, cwd = process.cwd()) {
+    if (argv.some((arg) => arg === "--help" || arg === "-h"))
+        return { out: VERIFY_HELP, code: 0 };
     const { values } = parseArgs({
         args: argv,
         options: {
@@ -69,13 +140,18 @@ export async function verify(argv, cwd = process.cwd()) {
             files: { type: "string", multiple: true },
             author: { type: "string" },
             baseline: { type: "string" },
+            record: { type: "string" },
             json: { type: "boolean", default: false },
             "no-review": { type: "boolean", default: false },
             "no-acceptance": { type: "boolean", default: false },
         },
         allowPositionals: false,
     });
-    const cfg = loadConfig(cwd);
+    const stateRoot = await verifyStateRoot(cwd);
+    if (resolve(stateRoot) !== resolve(cwd)) {
+        console.error(`verify: state files graph.json, doctor.json and config.yaml resolved read-only from ${join(stateRoot, ".tickmarkr")} (linked worktree)`);
+    }
+    const cfg = loadConfig(stateRoot);
     const head = (await shGitOk("git rev-parse HEAD", cwd)).trim();
     const baseTip = (await shGitOk(`git rev-parse '${values.base}'`, cwd).catch(() => {
         throw new Error(`--base ${values.base} is not a resolvable ref — pass --base <ref> naming the branch this diff targets`);
@@ -89,9 +165,7 @@ export async function verify(argv, cwd = process.cwd()) {
     let files = values.files ?? [];
     let goal = `independent verification of the ${values.base}..HEAD diff`;
     if (values.task) {
-        const t = getTask(loadGraph(cwd), values.task);
-        if (!t)
-            throw new Error(`--task ${values.task}: no such task in .tickmarkr/graph.json`);
+        const t = getTask(loadGraph(stateRoot), values.task);
         acceptance = t.acceptance;
         if (!files.length)
             files = t.files;
@@ -102,6 +176,8 @@ export async function verify(argv, cwd = process.cwd()) {
         if (!acceptance.length)
             throw new Error(`--criteria ${values.criteria}: no criteria found (bullets or command:/test:/judge: lines)`);
     }
+    if (values.task)
+        await warnWideTaskRange(cwd, stateRoot, values.task, mergeBase);
     const wantAcceptance = acceptance.length > 0 && !values["no-acceptance"];
     const wantReview = !values["no-review"];
     // A gate that enforced nothing must not print a green row. `files` has exactly three sources —
@@ -145,7 +221,7 @@ export async function verify(argv, cwd = process.cwd()) {
     let author = HUMAN_AUTHOR;
     const adapters = allAdapters();
     if (wantAcceptance || wantReview) {
-        const health = readDoctor(cwd) ?? (await probeAll(adapters));
+        const health = readDoctor(stateRoot) ?? (await probeAll(adapters));
         const pools = rolePools(cfg, adapters, health);
         judgeChannels = pools.judge;
         channels = pools.review;
@@ -157,6 +233,7 @@ export async function verify(argv, cwd = process.cwd()) {
                 throw new Error(`--author ${values.author} does not name a discoverable review channel — one of: ${channels.map(channelKey).join(", ") || "(none)"}`);
             }
             author = { adapter: c.adapter, model: c.model, channel: c.channel, tier: c.tier };
+            channels = excludeAuthorProvider(channels, c);
         }
         else {
             channels = [...channels, HUMAN_CHANNEL];
@@ -173,28 +250,56 @@ export async function verify(argv, cwd = process.cwd()) {
     const stateDir = verifyStateDir(cwd);
     mkdirSync(stateDir, { recursive: true });
     let baseline;
-    const cachePath = join(stateDir, `baseline-${mergeBase.slice(0, 12)}.json`);
+    const cachePath = baselineCachePath(cwd, mergeBase, commands);
+    const verdictlessMarker = `${cachePath}.verdictless`;
+    mkdirSync(dirname(cachePath), { recursive: true });
     if (values.baseline) {
         baseline = JSON.parse(readFileSync(values.baseline, "utf8"));
     }
-    else if (existsSync(cachePath)) {
-        console.error(`verify: reusing cached baseline for ${mergeBase.slice(0, 12)} (${cachePath})`);
-        baseline = JSON.parse(readFileSync(cachePath, "utf8"));
-    }
     else {
-        const baseDir = join(stateDir, `base-${mergeBase.slice(0, 12)}`);
-        console.error(`verify: capturing baseline at merge-base ${mergeBase.slice(0, 12)} (one-time per base; cached at ${cachePath})`);
-        await shGit(`git worktree remove --force '${baseDir}'`, cwd); // stale leftover from an interrupted run
-        await shGitOk(`git worktree add --detach '${baseDir}' '${mergeBase}'`, cwd);
-        try {
-            linkNodeModules(cwd, baseDir, { force: true });
-            baseline = await captureBaseline(baseDir, commands);
-            writeFileSync(cachePath, JSON.stringify(baseline, null, 2));
+        let cached;
+        if (existsSync(cachePath)) {
+            cached = JSON.parse(readFileSync(cachePath, "utf8"));
+            const missing = verdictlessCommands(cached, commands);
+            if (missing.length) {
+                console.error(`verify: cached baseline recorded no verdict for ${missing.join(", ")}; it was not reusable and will be recaptured`);
+                rmSync(cachePath, { force: true });
+                cached = undefined;
+            }
         }
-        finally {
-            await removeWorktree(cwd, baseDir);
+        if (cached) {
+            console.error(`verify: reusing cached baseline for ${mergeBase.slice(0, 12)} (${cachePath})`);
+            baseline = cached;
+        }
+        else {
+            if (existsSync(verdictlessMarker)) {
+                console.error(`verify: prior baseline recorded no verdict and was not cached; recapturing merge-base ${mergeBase.slice(0, 12)}`);
+            }
+            else {
+                console.error(`verify: capturing baseline at merge-base ${mergeBase.slice(0, 12)} (cached by base, lockfile and command hashes at ${cachePath})`);
+            }
+            const baseDir = join(stateDir, `base-${mergeBase.slice(0, 12)}`);
+            await shGit(`git worktree remove --force '${baseDir}'`, cwd); // stale leftover from an interrupted run
+            await shGitOk(`git worktree add --detach '${baseDir}' '${mergeBase}'`, cwd);
+            try {
+                linkNodeModules(cwd, baseDir, { force: true });
+                baseline = await captureBaseline(baseDir, commands);
+                const missing = verdictlessCommands(baseline, commands);
+                if (missing.length) {
+                    writeFileSync(verdictlessMarker, JSON.stringify({ base: mergeBase, commands: missing }) + "\n");
+                    rmSync(cachePath, { force: true });
+                }
+                else {
+                    writeFileSync(cachePath, JSON.stringify(baseline, null, 2));
+                    rmSync(verdictlessMarker, { force: true });
+                }
+            }
+            finally {
+                await removeWorktree(cwd, baseDir);
+            }
         }
     }
+    const recordJournal = values.record ? Journal.open(stateRoot, values.record) : undefined;
     const artifactDir = join(stateDir, new Date().toISOString().replace(/[:.]/g, "-"));
     mkdirSync(artifactDir, { recursive: true });
     const { results } = await runGates(task, {
@@ -212,12 +317,27 @@ export async function verify(argv, cwd = process.cwd()) {
         },
     });
     const green = results.length > 0 && results.every((r) => r.pass || r.meta?.skipped === true);
+    const reviewRows = results.filter((result) => result.gate === "review");
+    const reviewFindings = reviewRows.flatMap((result) => result.details.split("\n").flatMap((line) => {
+        const match = /^- \[([^\]]+)\] (.*)$/.exec(line);
+        return match ? [{ classification: match[1], note: match[2], reviewer: result.meta?.reviewer }] : [];
+    }));
+    const artifactPath = join(artifactDir, "verify-results.json");
+    writeFileSync(artifactPath, JSON.stringify({ base: baseTip, head, mergeBase, green, gateRows: results, reviewFindings }, null, 2) + "\n");
+    console.error(`verify: artifacts written to ${artifactPath}`);
+    const review = reviewRows.at(-1);
+    if (recordJournal && review) {
+        recordJournal.append("review-leg2", values.task ?? "VERIFY", {
+            base: baseTip, head, mergeBase, author: channelKey(author), artifactPath,
+            ...review,
+        });
+    }
     if (values.json) {
-        return { out: JSON.stringify({ base: baseTip, head, mergeBase, green, results }, null, 2), code: green ? 0 : 2 };
+        return { out: JSON.stringify({ base: baseTip, head, mergeBase, green, artifactPath, results }, null, 2), code: green ? 0 : 2 };
     }
     const lines = results.map((r) => `${r.pass ? "PASS" : "FAIL"} ${r.gate}\n${r.details.split("\n").map((l) => `  ${l}`).join("\n")}`);
     const verdict = green
-        ? `verify GREEN — ${results.length} gate(s) passed on ${mergeBase.slice(0, 12)}..${head.slice(0, 12)} (merge is a human decision)`
-        : `verify RED — first failure decides; artifacts in ${artifactDir}`;
+        ? `verify GREEN — ${results.length} gate(s) passed on ${mergeBase.slice(0, 12)}..${head.slice(0, 12)} (merge is a human decision; artifacts: ${artifactPath})`
+        : `verify RED — first failure decides; artifacts: ${artifactPath}`;
     return { out: [...lines, "", verdict].join("\n"), code: green ? 0 : 2 };
 }

package/dist/cli/index.d.ts

@@ -5,7 +5,7 @@ export type CommandResult = string | {
 };
 export type CommandMap = Record<string, (argv: string[]) => Promise<CommandResult>>;
 export declare const COMMANDS: CommandMap;
-export declare const USAGE = "tickmarkr \u2014 spec-driven orchestration harness for AI coding agents\nusage: tickmarkr <command>\n  init          guided setup + doctor; init --agent [--force] [--docs] adds agent skills/docs\n  doctor        re-probe adapters, herdr, auth; print capability matrix (--fix writes the test-runner ignore when a safe edit exists)\n  fleet         interactive fleet editor (fleet --print for CI drift checks)\n  compile <src> spec \u2192 .tickmarkr/graph.json (fails without acceptance criteria)\n  scope <intent> draft a compiled native spec beside an answered intent (--force to overwrite)\n  plan          dry-run routing table + cost estimate + floor lints\n  eval          run checked-in fixtures against every channel in isolated temp repos\n  run           execute the graph (--concurrency N --driver auto|herdr|subprocess|orca --route-strict; orca runs only when named)\n  status        live run state\n  stats         all-run channel delivery, red, rescue, author and reviewer statistics\n  verify        run the gate battery standalone against merge-base(--base, HEAD)..HEAD \u2014 no daemon, one verdict (--base main --criteria <file> | --task <id> [--files <glob>] [--author adapter:model] [--no-review] [--json])\n  resume <id>   continue a run from its journal\n  report <id>   cost/quality report (--md for committable execution record)\n  profile       show learned routing profile (profile reset = forget history via cursor, keeps telemetry)\n  ui            open the Fleet Studio TUI (full-screen tabbed cockpit)\n  unlock        remove a stale/garbage run lock (refuses if the holder is alive)\n  beat <tier>   record one supervision beat for orchestrator|orchestrator-context|overseer|overseer-context|watch, --seat <identity> required (--stand-down to hand off); a supervising seat's own watcher loop calls it, and status reads the tier STALE once the beats stop\n  approve <id> <task>  release a park (--uphold sides with the reviewer and funds a fixed attempt; --by <name> --reason <text>); takes effect on resume";
+export declare const USAGE = "tickmarkr \u2014 spec-driven orchestration harness for AI coding agents\nusage: tickmarkr <command>\n  init          guided setup + doctor; init --agent [--force] [--docs] adds agent skills/docs\n  doctor        re-probe adapters, herdr, auth; print capability matrix (--fix writes the test-runner ignore when a safe edit exists)\n  fleet         interactive fleet editor (fleet --print for CI drift checks)\n  compile <src> spec \u2192 .tickmarkr/graph.json (fails without acceptance criteria)\n  scope <intent> draft a compiled native spec beside an answered intent (--force to overwrite)\n  plan          dry-run routing table + cost estimate + floor lints\n  eval          run checked-in fixtures against every channel in isolated temp repos\n  run           execute the graph (--concurrency N --driver auto|herdr|subprocess|orca --route-strict; orca runs only when named)\n  status        live run state (--watch --events: JSON documents on stdout, keepalives on stderr; 2>&1 corrupts the stream)\n  stats         all-run channel delivery, red, rescue, author and reviewer statistics\n  verify        run the gate battery standalone against merge-base(--base, HEAD)..HEAD \u2014 verdict/JSON on stdout, progress on stderr; 2>&1 corrupts the verdict stream (--base main --criteria <file> | --task <id> [--files <glob>] [--author adapter:model] [--no-review] [--json])\n  resume <id>   continue a run from its journal\n  report <id>   cost/quality report (--md for committable execution record)\n  profile       show learned routing profile (profile reset = forget history via cursor, keeps telemetry)\n  ui            open the Fleet Studio TUI (full-screen tabbed cockpit)\n  unlock        remove a stale/garbage run lock (refuses if the holder is alive)\n  beat <tier>   record one supervision beat for orchestrator|orchestrator-context|overseer|overseer-context|watch, --seat <identity> required (--stand-down to hand off); a supervising seat's own watcher loop calls it, and status reads the tier STALE once the beats stop\n  approve <id> <task>  release a park (--uphold sides with the reviewer and funds a fixed attempt; --by <name> --reason <text>); takes effect on resume";
 export declare function dispatch(cmd: string | undefined, argv: string[], commands?: CommandMap): Promise<{
     out: string;
     code: number;

package/dist/cli/index.js

@@ -37,9 +37,9 @@ usage: tickmarkr <command>
   plan          dry-run routing table + cost estimate + floor lints
   eval          run checked-in fixtures against every channel in isolated temp repos
   run           execute the graph (--concurrency N --driver auto|herdr|subprocess|orca --route-strict; orca runs only when named)
-  status        live run state
+  status        live run state (--watch --events: JSON documents on stdout, keepalives on stderr; 2>&1 corrupts the stream)
   stats         all-run channel delivery, red, rescue, author and reviewer statistics
-  verify        run the gate battery standalone against merge-base(--base, HEAD)..HEAD — no daemon, one verdict (--base main --criteria <file> | --task <id> [--files <glob>] [--author adapter:model] [--no-review] [--json])
+  verify        run the gate battery standalone against merge-base(--base, HEAD)..HEAD — verdict/JSON on stdout, progress on stderr; 2>&1 corrupts the verdict stream (--base main --criteria <file> | --task <id> [--files <glob>] [--author adapter:model] [--no-review] [--json])
   resume <id>   continue a run from its journal
   report <id>   cost/quality report (--md for committable execution record)
   profile       show learned routing profile (profile reset = forget history via cursor, keeps telemetry)

package/dist/compile/collateral.d.ts

@@ -149,14 +149,7 @@ export declare function reviewParticipationErrors(tasks: ReadonlyArray<Pick<Task
  * whose task objects carry no `context` gets byte-identical verdicts to the ones it got before the
  * field existed, because an absent declaration grants no authority at all.
  *
- * 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.
+ * The compile seam in src/compile/index.ts threads `compileSource`'s repo root here, so CLI tests
+ * and programmatic compiles check the same repository overlay the later run will use.
  */
 export declare function taskUnitContractErrors(tasks: ReadonlyArray<Pick<Task, "id" | "goal" | "files" | "deps" | "acceptance" | "shape"> & Partial<Pick<Task, "context">>>, repoRoot?: string, review?: ReviewParticipation): string[];

package/dist/compile/collateral.js

@@ -1,4 +1,4 @@
-import { readdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { extname, join, relative } from "node:path";
 import { filesGlob } from "../graph/files-glob.js";
 import { criticalPathHits, DEFAULT_CONFIG, DEFAULT_REVIEW_CRITICAL_PATHS, effectiveReviewPolicy, loadConfig, } from "../config/config.js";
@@ -15,6 +15,7 @@ const MAX_WALK_FILES = 400;
 const MAX_HITS_PER_TASK = 20;
 /** Skip giant fixtures / snapshots. */
 const MAX_READ_BYTES = 512 * 1024;
+const EXPORT_MANIFEST_TEST = "tests/repo/export-manifest.test.ts";
 const SRC_EXT = /\.(ts|tsx|js|jsx|mts|cts)$/;
 const CODE_EXT = /\.(ts|tsx|js|jsx|mts|cts)$/;
 function isSrcPath(p) {
@@ -112,15 +113,20 @@ export function collateralHits(tasks, repoRoot) {
     const read = makeReader(repoRoot);
     for (const t of tasks) {
         // OBS-22: scopeGate accepts picomatch globs; advisory collateral warnings must agree.
-        const scoped = filesGlob(t.files.map((f) => f.replace(/^\.\//, "")));
-        const srcFiles = t.files.map((f) => f.replace(/^\.\//, "")).filter(isSrcPath);
-        if (!srcFiles.length)
-            continue;
+        const files = t.files.map((f) => f.replace(/^\.\//, ""));
+        const scoped = filesGlob(files);
+        const srcFiles = files.filter(isSrcPath);
+        const hits = [];
+        // Exact-enumerated scripts are an export-set contract: a new path has no name or symbol for the
+        // ordinary sweep to find, but the manifest test will reject it unless the task owns that oracle.
+        if (testFiles.includes(EXPORT_MANIFEST_TEST)
+            && !scoped(EXPORT_MANIFEST_TEST)
+            && files.some((path) => path.startsWith("scripts/") && !/[?*{[]/.test(path) && !existsSync(join(repoRoot, path))))
+            hits.push(EXPORT_MANIFEST_TEST);
         // needles unioned across all src files in this task
         const needles = [...new Set(srcFiles.flatMap(needlesFor))];
-        const hits = [];
         for (const tf of testFiles) {
-            if (scoped(tf))
+            if (scoped(tf) || hits.includes(tf))
                 continue;
             const text = read(tf);
             if (text === null)
@@ -128,9 +134,9 @@ export function collateralHits(tasks, repoRoot) {
             if (mentions(text, needles))
                 hits.push(tf);
         }
-        // deterministic: walk already sorted; stable list
+        // deterministic: the special hit and walk are stable; sort their union for one canonical map.
         if (hits.length)
-            map.set(t.id, hits);
+            map.set(t.id, hits.sort());
     }
     return map;
 }
@@ -890,15 +896,8 @@ function activeReviewParticipation(repoRoot) {
  * whose task objects carry no `context` gets byte-identical verdicts to the ones it got before the
  * field existed, because an absent declaration grants no authority at all.
  *
- * 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.
+ * The compile seam in src/compile/index.ts threads `compileSource`'s repo root here, so CLI tests
+ * and programmatic compiles check the same repository overlay the later run will use.
  */
 export function taskUnitContractErrors(tasks, repoRoot = process.cwd(), review = activeReviewParticipation(repoRoot)) {
     return [

package/dist/compile/index.d.ts

@@ -10,6 +10,9 @@ export type PlanIR = {
     tasks: RunGraph["tasks"];
 };
 export type PlanFinalizationHook = (plan: PlanIR) => PlanIR;
+export type CompileOptions = {
+    strict?: boolean;
+};
 export declare function finalizePlan(plan: PlanIR, src: string, repoRoot?: string): RunGraph;
-export declare function compileSource(src: string, type?: SourceType, root?: string, beforeFinalize?: PlanFinalizationHook): RunGraph;
+export declare function compileSource(src: string, type?: SourceType, root?: string, beforeFinalize?: PlanFinalizationHook, options?: CompileOptions): RunGraph;
 export {};

package/dist/compile/index.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { parse } from "yaml";
 import { validateGraph } from "../graph/schema.js";
 import { taskUnitContractErrors } from "./collateral.js";
 import { blocksCompile, ownershipFindings, renderOwnershipFinding } from "./ownership.js";
@@ -33,8 +34,40 @@ function detect(src) {
 // tasks are too large to converge. A violation is a compile error, never a warning — the failures it
 // prevents (silently dropped commits, a 28-dispatch task) are invisible until they have already cost
 // hours, which is exactly the class of thing that has to fail at authoring time.
-function enforceTaskUnitContract(g, src) {
-    const errors = taskUnitContractErrors(g.tasks);
+function repoOverlayMode(repoRoot) {
+    if (!repoRoot)
+        return undefined;
+    try {
+        const cfg = parse(readFileSync(join(repoRoot, ".tickmarkr", "config.yaml"), "utf8"));
+        return typeof cfg?.routing?.mode === "string" ? cfg.routing.mode : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function hasModeOverride(src) {
+    try {
+        for (const line of readFileSync(src, "utf8").split("\n")) {
+            if (/^##\s+T\d+:/i.test(line))
+                return false;
+            if (/^mode-override:\s*true\s*(?:#.*)?$/.test(line))
+                return true;
+        }
+    }
+    catch { /* unreadable specs fail elsewhere */ }
+    return false;
+}
+function enforceModeOverlay(graph, src, repoRoot) {
+    if (graph.spec.source !== "native" || graph.mode === undefined)
+        return;
+    const overlayMode = repoOverlayMode(repoRoot);
+    if (overlayMode === undefined || overlayMode === graph.mode || hasModeOverride(src))
+        return;
+    throw new CompileError(`${src} front-matter mode ${graph.mode} disagrees with repository routing.mode ${overlayMode}; `
+        + `write mode-override: true beside the mode line to make the override explicit.`);
+}
+function enforceTaskUnitContract(g, src, repoRoot) {
+    const errors = taskUnitContractErrors(g.tasks, repoRoot);
     if (errors.length > 0) {
         throw new CompileError(`${src} violates the task unit contract (${errors.length} error${errors.length > 1 ? "s" : ""}):\n`
             + errors.map((e) => `  - ${e}`).join("\n"));
@@ -52,7 +85,8 @@ export function finalizePlan(plan, src, repoRoot) {
             ...(plan.base !== undefined ? { base: plan.base } : {}),
         },
         tasks: plan.tasks,
-    }), src);
+    }), src, repoRoot);
+    enforceModeOverlay(graph, src, repoRoot);
     // overseer-217 removal condition, now paid: on this milestone's authored graph the conventional
     // name map emitted 21 raw unowned-test findings; review found 1 real and 20 false, while intersecting
     // with a direct import or command-entry spawn retained the real one and left 0 false positives. That
@@ -73,11 +107,11 @@ export function finalizePlan(plan, src, repoRoot) {
     }
     return graph;
 }
-function compilePlan(src, type, root) {
+function compilePlan(src, type, root, options = {}) {
     const kind = type ?? detect(src);
     const graph = kind === "speckit" ? compileSpecKit(src)
         : kind === "gsd" ? compileGsd(src, root)
-            : kind === "native" ? compileNative(src)
+            : kind === "native" ? compileNative(src, { strict: options.strict })
                 : kind === "prd" ? compilePrd(src)
                     : null;
     if (!graph) {
@@ -93,6 +127,6 @@ function compilePlan(src, type, root) {
         tasks: graph.tasks,
     };
 }
-export function compileSource(src, type, root, beforeFinalize = (plan) => plan) {
-    return finalizePlan(beforeFinalize(compilePlan(src, type, root)), src, root);
+export function compileSource(src, type, root, beforeFinalize = (plan) => plan, options = {}) {
+    return finalizePlan(beforeFinalize(compilePlan(src, type, root, options)), src, root);
 }

package/dist/compile/native.d.ts

@@ -17,7 +17,7 @@ export declare const COLLECTABLE_TESTS = "tests/**/*.test.ts";
 export declare const LEGACY_PREFIX: string;
 export declare const TICKMARKR_NATIVE_MARKER: RegExp;
 export declare const NATIVE_MARKER: RegExp;
-export declare const AUTHORING_LINT_CODES: readonly ["criterion-scope", "dependency-closure", "dependency-coupling", "proxy-metric", "external-referent", "closed-enumeration", "one-behavior", "concern-bundle", "seam-exists"];
+export declare const AUTHORING_LINT_CODES: readonly ["criterion-scope", "dependency-closure", "dependency-coupling", "proxy-metric", "external-referent", "closed-enumeration", "one-behavior", "concern-bundle", "seam-exists", "fence-symbol-absent"];
 export type AuthoringLintCode = (typeof AUTHORING_LINT_CODES)[number];
 export interface AuthoringLintFinding {
     code: AuthoringLintCode;
@@ -31,5 +31,7 @@ export interface AuthoringLintFinding {
  * compile boundary; the remaining checks are review findings, emitted by compileNative below.
  */
 export declare function authoringLintFindings(tasks: readonly Task[], file: string): AuthoringLintFinding[];
-export declare function compileNative(file: string): RunGraph;
+export declare function compileNative(file: string, options?: {
+    strict?: boolean;
+}): RunGraph;
 export declare function specTemplate(): string;

package/dist/compile/native.js

@@ -83,6 +83,7 @@ export const AUTHORING_LINT_CODES = [
     "one-behavior",
     "concern-bundle",
     "seam-exists",
+    "fence-symbol-absent",
 ];
 // The authoring frame's observable oracle is the branch-tip test corpus, never the mutable index or
 // an author's untracked checkout. Load it once per repository: one bounded git read replaces a grep
@@ -217,6 +218,31 @@ function criterionScopeFinding(task, text, criterion, id, tests) {
         detail: `criterion names asserting file${missing.length === 1 ? "" : "s"} outside expanded files[] and context[]: ${missing.join(", ")} — ${remedy}`,
     };
 }
+// OBS-898: the fence lint's corpus is listed ONCE per compile by git (tracked plus untracked-not-ignored,
+// the same set a checkout walk sees minus the ignored trees) and filtered per task. The walk it replaces
+// descended every dot-directory (.tickmarkr/runs alone held 3 799 files here) once PER TASK, so a
+// 20-task spec compiled in seconds and the committed-spec corpus test timed out. Fail-open like
+// testsAtHead: no git answer means no corpus, and the lint stays quiet rather than wrong.
+function repoFileList(root) {
+    const ls = spawnSync("git", ["-C", root, "ls-files", "-z", "--cached", "--others", "--exclude-standard"], { encoding: "utf8", maxBuffer: 1 << 25 });
+    if (ls.status !== 0 || typeof ls.stdout !== "string")
+        return [];
+    return ls.stdout.split("\0").filter(Boolean).sort();
+}
+function repoFiles(files, entries) {
+    const scoped = filesGlob(entries.map((entry) => entry.replace(/^\.\//, "")));
+    return files.filter(scoped);
+}
+const PRESERVATION_RE = /\b(?:keeps?|preserves?|retains?|does\s+not\s+weaken|do\s+not\s+weaken|not\s+weaken)\b/i;
+const IDENTIFIER_SHAPED_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function fencedIdentifiers(text) {
+    if (!PRESERVATION_RE.test(text))
+        return [];
+    return [...new Set([...text.matchAll(/`([^`\n]{1,120})`/g)]
+            .map((match) => match[1].trim())
+            .filter((token) => IDENTIFIER_SHAPED_RE.test(token) && /[A-Z0-9_$]/.test(token)))]
+        .sort();
+}
 function exportedIdentifier(root, files, identifier) {
     const escaped = identifier.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
     const declaration = new RegExp(`\\bexport\\s+(?:(?:declare|default|async)\\s+)*(?:function|class|const|let|var|interface|type)\\s+${escaped}\\b|\\bexport\\s*\\{[^}]*\\b${escaped}\\b`);
@@ -240,14 +266,33 @@ export function authoringLintFindings(tasks, file) {
     const root = repositoryRoot(file);
     let indexedTests;
     const testIndex = () => indexedTests ??= root ? testsAtHead(root) : [];
+    let indexedFiles;
+    const fileIndex = () => indexedFiles ??= root ? repoFileList(root) : [];
     const findings = [];
     for (const task of tasks) {
         const criteria = criterionTexts(task);
+        const taskFiles = root && task.files.length ? repoFiles(fileIndex(), task.files) : [];
+        const taskTexts = new Map(taskFiles.map((path) => {
+            try {
+                return [path, readFileSync(join(root, path), "utf8")];
+            }
+            catch {
+                return [path, ""];
+            }
+        }));
         for (const [index, text] of criteria.entries()) {
             const needsTestIndex = /`[^`\n]{2,120}`|\b\d+\s*(?:\/|of)\s*\d+\b|\b[A-Za-z0-9_.-]+\.test\.ts\b/.test(text);
             const scope = criterionScopeFinding(task, text, index + 1, id, needsTestIndex ? testIndex() : []);
             if (scope)
                 findings.push(scope);
+            for (const symbol of fencedIdentifiers(text)) {
+                if (!taskTexts.size || [...taskTexts.values()].some((body) => body.includes(symbol)))
+                    continue;
+                findings.push({
+                    code: "fence-symbol-absent", fixtureId: id, taskId: task.id, criterion: index + 1,
+                    detail: `preservation fence cites \`${symbol}\` but that symbol has zero hits in this task's files[] (${taskFiles.join(", ")}) — OBS-604`,
+                });
+            }
             if (/line[- ]count|physical line|not greater than (?:the|\d)|no larger than|at most \d+ (?:lines|bytes)/i.test(text)) {
                 findings.push({ code: "proxy-metric", fixtureId: id, taskId: task.id, criterion: index + 1, detail: "criterion uses a proxy size metric; state the structural intent instead" });
             }
@@ -308,7 +353,7 @@ function renderAuthoringFinding(finding) {
     const criterion = finding.criterion === undefined ? "" : ` criterion ${finding.criterion}`;
     return `tickmarkr: authoring-lint[${finding.code}] fixture ${finding.fixtureId} task ${finding.taskId}${criterion}: ${finding.detail}`;
 }
-export function compileNative(file) {
+export function compileNative(file, options = {}) {
     if (!existsSync(file))
         throw new CompileError(`no such native spec file: ${file}`);
     const content = readFileSync(file, "utf8");
@@ -638,13 +683,17 @@ export function compileNative(file) {
         tasks,
     });
     const authoringFindings = authoringLintFindings(result.tasks, file);
-    for (const finding of authoringFindings.filter(({ code }) => code !== "criterion-scope")) {
+    const blockingCodes = new Set(["criterion-scope", "fence-symbol-absent"]);
+    const blockingFindings = authoringFindings.filter((finding) => options.strict || blockingCodes.has(finding.code));
+    for (const finding of authoringFindings.filter((finding) => !blockingFindings.includes(finding))) {
         console.warn(renderAuthoringFinding(finding));
     }
-    const scopeErrors = authoringFindings.filter(({ code }) => code === "criterion-scope");
-    if (scopeErrors.length > 0) {
-        throw new CompileError(`${file} violates the criterion-scope authoring lint (${scopeErrors.length} error${scopeErrors.length === 1 ? "" : "s"}):\n`
-            + scopeErrors.map((finding) => `  - ${renderAuthoringFinding(finding)}`).join("\n"));
+    if (blockingFindings.length > 0) {
+        const strict = options.strict ? " under --strict" : "";
+        const onlyCriterionScope = blockingFindings.every(({ code }) => code === "criterion-scope");
+        const label = onlyCriterionScope && !options.strict ? "the criterion-scope authoring lint" : `authoring lints${strict}`;
+        throw new CompileError(`${file} violates ${label} (${blockingFindings.length} error${blockingFindings.length === 1 ? "" : "s"}):\n`
+            + blockingFindings.map((finding) => `  - ${renderAuthoringFinding(finding)}`).join("\n"));
     }
     // v1.19 read-old/write-new: a plain-string acceptance item compiles as a judge oracle. This is the
     // one-time nudge toward typed oracles (command/test/judge); PRD/Spec Kit/GSD stay silent (untouched).
@@ -805,9 +854,9 @@ acceptance is required on every task (a nested list of observable outcomes).
       set closed — this milestone paid a halted run to learn that the two populations are not identical.
     - SPIKE-THE-CONTRACT-THEN-SCOPE trigger question: COULD A TEST THIS TASK DOES NOT OWN BE ASSERTING THE
       THING I AM CHANGING? "I'D HAVE TO GREP TO KNOW" IS YES. This applies to observable contracts:
-      execution order, event-stream order, diagnostics/output sets, CLI surface, serialised formats, or
-      timing measurements. If yes, implement the change as a throwaway spike, run the full suite, read the
-      reds, THEN scope files[].
+      execution order, event-stream order, diagnostics/output sets, CLI surface, serialised formats,
+      timing measurements, or adding or removing a shipped file. If yes, implement the change as a
+      throwaway spike, run the full suite, read the reds, THEN scope files[].
     - Caveat: a spike measures ONE implementation. It converts unknown collateral into
       measured-for-one-specimen collateral; it does NOT make its reds the closed blocker set for every
       route. A worker taking a different route can still red on unowned collateral; that remains a PLAN