tickmarkr 1.84.0 → 1.86.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/compile/gsd.d.ts

@@ -1,3 +1,4 @@
-import { type RunGraph } from "../graph/schema.js";
+import { type AcceptanceItem, type RunGraph } from "../graph/schema.js";
 export declare function isGsdPhaseDir(dir: string): boolean;
+export declare function parseTruths(file: string, raw: unknown): AcceptanceItem[] | undefined;
 export declare function compileGsd(src: string, root?: string): RunGraph;

package/dist/compile/gsd.js

@@ -1,7 +1,7 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative } from "node:path";
 import { parse as parseYaml } from "yaml";
-import { TIERS, validateGraph } from "../graph/schema.js";
+import { AcceptanceItemSchema, TIERS, validateGraph } from "../graph/schema.js";
 import { CompileError, assertWriteScope, inferShape, sha256 } from "./common.js";
 // GSD artifact front-end (spec v1.3): one GSD *plan* is one tickmarkr *task* — a plan is
 // worktree-sized; its inner <task> steps stay in the worker prompt via context[0] = the plan file.
@@ -16,6 +16,72 @@ export function isGsdPhaseDir(dir) {
     }
 }
 const strings = (v) => (Array.isArray(v) ? v.map(String) : []);
+// Cycle-safe by construction: a recursive YAML alias (`&a [*a]`) is a legal value the parser hands
+// back as a circular object, and a bare JSON.stringify throws a native TypeError on it — which would
+// REPLACE the indexed CompileError this module owes the author with an unrelated crash. Every value
+// the YAML parser can produce renders here. (A repeated non-recursive alias also renders [circular];
+// this is a diagnostic string, not a round-trippable encoding.)
+const show = (v) => {
+    const seen = new WeakSet();
+    const cycleSafe = (_k, x) => {
+        if (typeof x !== "object" || x === null)
+            return x;
+        if (seen.has(x))
+            return "[circular]";
+        seen.add(x);
+        return x;
+    };
+    return JSON.stringify(v, cycleSafe) ?? String(v);
+};
+// A truth IS an acceptance item, not a string to coerce. strings()' `.map(String)` turned a typed
+// object truth into the literal "[object Object]" — schema-legal in the judge-compat string form, so
+// it passed validateGraph, reached the worker prompt verbatim and became a judge rubric item; a YAML
+// scalar `- 2.0` silently became "2". Nothing downstream catches either. So fail closed (house
+// precedent: the routing block in compileOne) on anything that is not text and not a typed oracle.
+// The CONTAINER is reported, not collapsed: an absent key returns undefined (nothing was declared) and
+// a present-but-empty list returns [] (declared, contributed nothing) — strings() flattened both, plus
+// a non-list, into the same silent []. Only the non-list fails closed; `truths: []` is real producer
+// output whose plan can still be carried by its <done> lines, and compileOne already rejects a task
+// whose acceptance ends up genuinely empty.
+// Parser liberal, template strict: a string truth stays exactly what strings() made of it — the GSD
+// planner template teaches prose-only and lives in another repo, so this parser must never be
+// stricter than the thing that produced its input. A non-string must satisfy AcceptanceItemSchema
+// EXACTLY — accepted with nothing dropped — which is where the dual-key `text:` beside
+// `command:`/`test:` is DECLARED (schema.ts:25-30); being declared is what makes it survive
+// loadGraph's revalidation, so nothing is ever reattached after.
+export function parseTruths(file, raw) {
+    if (raw === undefined)
+        return undefined; // key absent: nothing was declared
+    if (!Array.isArray(raw)) {
+        throw new CompileError(`${file} has a must_haves.truths that is not a list (got ${show(raw)}).\n` +
+            `  remedy: write each truth as a "- " list entry, or drop the key.`);
+    }
+    return raw.map((v, i) => {
+        if (typeof v === "string")
+            return v;
+        const parsed = AcceptanceItemSchema.safeParse(v);
+        if (!parsed.success) {
+            throw new CompileError(`${file} has a must_haves.truths[${i}] that is neither prose nor a typed acceptance oracle: ${show(v)}\n` +
+                `  remedy: write it as plain text, or as {oracle: command, command: <shell>} / {oracle: test, test: <name>} /\n` +
+                `  {oracle: judge, text: <rubric>} — command and test may carry a "text:" beside the oracle.`);
+        }
+        // A SUCCESSFUL parse is lossy too: z.object strips undeclared keys, so {oracle, command, text,
+        // severity} validates and compiles with `severity` gone — the same silent coercion in the other
+        // direction, and invisible because nothing downstream ever saw the key. Accepting less than the
+        // author supplied is not acceptance, so fail closed on whatever validation dropped.
+        // Object.hasOwn, never `k in`: the YAML parser hands back `constructor`, `toString`,
+        // `hasOwnProperty` and `__proto__` as OWN keys, but `in` finds all four on Object.prototype of the
+        // validated output, so each read as "kept" and was stripped in silence — the exact coercion this
+        // check exists to stop.
+        const dropped = Object.keys(v).filter((k) => !Object.hasOwn(parsed.data, k));
+        if (dropped.length) {
+            throw new CompileError(`${file} has a must_haves.truths[${i}] carrying key(s) no acceptance oracle declares: ${dropped.join(", ")}\n` +
+                `  remedy: drop ${dropped.length === 1 ? "that key" : "those keys"}, or fold the intent into "text:" — a\n` +
+                `  compile that kept ${dropped.length === 1 ? "it" : "them"} would discard ${dropped.length === 1 ? "it" : "them"} at the next graph load, unread.`);
+        }
+        return parsed.data;
+    });
+}
 const WRITE_DIRECTIVE = /\b(?:Create|Write|Add|Emit|Generate)\s+`([^`\s]+)`/gi;
 const isPathish = (s) => /^[\w./*-]+$/.test(s) && /\.[a-z]{2,4}$/i.test(s);
 const stripFences = (s) => s.replace(/^```[\s\S]*?^```/gm, "");
@@ -89,7 +155,7 @@ function compileOne(file, storedPath) {
         .trim();
     const title = firstSentence || key;
     const dones = [...body.matchAll(/<done>\s*([\s\S]*?)\s*<\/done>/g)].map((m) => m[1].replace(/\s+/g, " ").trim());
-    const truths = strings(fm.must_haves?.truths);
+    const truths = parseTruths(file, fm.must_haves?.truths) ?? [];
     const acceptance = [...dones, ...truths].filter(Boolean);
     if (!acceptance.length) {
         throw new CompileError(`${file} has no acceptance criteria — every tickmarkr task needs them.\n` +

package/dist/compile/native.d.ts

@@ -1,4 +1,18 @@
 import { type RunGraph } from "../graph/schema.js";
+/**
+ * Classify one `context:` entry against the tree a worker's worktree is built from.
+ *   ok        — reachable
+ *   untracked — in the author's checkout, invisible to every worker. WARNS, permanently: per-file
+ *               force-add is the deliberate opt-in, so this is a standing prompt, not a migration.
+ *   missing   — absent from both. FAILS compile; carries a repair when exactly one tracked file
+ *               shares the basename (ambiguous matches suggest nothing rather than guess).
+ * RULING 2026-08-03 (.overseer/OVERSEER-RULING-20260803-context-visibility.md): OBS-170's
+ * fail-closed-on-untracked is retired — oracle upheld, policy overruled (it blocked 11 of 13).
+ */
+export declare function classifyContextPath(entry: string, tracked: Set<string>, repoDir: string): {
+    kind: "ok" | "untracked" | "missing";
+    suggestion?: string;
+};
 export declare const COLLECTABLE_TESTS = "tests/**/*.test.ts";
 export declare const LEGACY_PREFIX: string;
 export declare const TICKMARKR_NATIVE_MARKER: RegExp;