tickmarkr 1.84.0 → 1.86.0

package/dist/compile/native.js

@@ -1,7 +1,61 @@
+import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname } from "node:path";
 import picomatch from "picomatch";
 import { GATE_NAMES, GRAPH_ROUTING_MODES, ORACLES, SHAPES, TIERS, validateGraph } from "../graph/schema.js";
 import { CompileError, inferShape, sha256 } from "./common.js";
+// OBS-170/OBS-184: `context:` is a promise to the worker, and nothing ever checked it could be kept.
+// Workers run in `git worktree add <baseRef>` (run/git.ts:169-176), which materialises the base
+// TREE and copies nothing in — so the oracle is that tree, and NEVER two things that look like it:
+//   · existsSync reads the AUTHOR's checkout. Measured on v1.85: 10 of 16 unreachable entries are
+//     plainly present there (.overseer/ is 21 tracked files out of 480 on disk).
+//   · `git ls-files` reads the INDEX. `git add -f` writes the index, so a staged-uncommitted file
+//     reports present while still being invisible to every worker — the lint would then certify
+//     exactly the failure it exists to catch (RULING 2026-08-03 rider; the absent-vs-empty shape
+//     again, cf. fileBytes). Hence the opt-in is "add AND commit", and the resolver reads HEAD.
+// `ls-tree -r HEAD` enumerates that tree once; per-path `cat-file -e HEAD:<path>` is the same oracle
+// one path at a time, and one spawn beats N.
+function trackedAtHead(dir) {
+    const git = (...args) => spawnSync("git", ["-C", dir, ...args], { encoding: "utf8", maxBuffer: 1 << 28 });
+    const top = git("rev-parse", "--show-toplevel");
+    // --full-tree is load-bearing: without it `ls-tree` scopes to the CWD's subtree and prints paths
+    // relative to it, so a spec in specs/ would see only specs/-relative names and misjudge every
+    // path outside it. Caught only by a fixture whose spec is NOT at the repo root.
+    const r = git("ls-tree", "--full-tree", "-r", "--name-only", "HEAD");
+    // not a repo, or no commits yet — fail open, so non-repo fixtures and fresh inits stay silent
+    if (top.status !== 0 || r.status !== 0 || typeof r.stdout !== "string")
+        return undefined;
+    return { root: top.stdout.trim(), tracked: new Set(r.stdout.split("\n").filter(Boolean)) };
+}
+const GLOB_CHARS = /[*?{[]/;
+/**
+ * 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 function classifyContextPath(entry, tracked, repoDir) {
+    if (GLOB_CHARS.test(entry))
+        return { kind: "ok" }; // a glob is not a promise about one file
+    const q = entry.replace(/\/+$/, "");
+    if (tracked.has(q))
+        return { kind: "ok" };
+    for (const t of tracked)
+        if (t.startsWith(`${q}/`))
+            return { kind: "ok" }; // directory with tracked children
+    if (existsSync(`${repoDir}/${q}`))
+        return { kind: "untracked" };
+    // Measured: 5 of v1.85's 6 absent entries are a tracked file written without its directory
+    // (`V185-SEEDS.md` for `.overseer/V185-SEEDS.md`) — the opt-in had worked, only the check was
+    // missing. Suggest ONLY on an unambiguous basename: two candidates is a guess, not a repair.
+    const base = basename(q);
+    const hits = [...tracked].filter((t) => basename(t) === base);
+    return hits.length === 1 ? { kind: "missing", suggestion: hits[0] } : { kind: "missing" };
+}
 // OBS-97: mirror of the vitest.config.ts suite include — the only path class vitest collects.
 export const COLLECTABLE_TESTS = "tests/**/*.test.ts";
 export const LEGACY_PREFIX = ["dro", "vr"].join("");
@@ -31,7 +85,7 @@ export function compileNative(file) {
     for (const line of content.split("\n")) {
         const heading = line.match(HEAD_RE);
         if (heading) {
-            drafts.push({ id: heading[1], title: heading[2].trim(), fields: {}, acceptance: [], gates: [], hasGates: false, list: null, goalContinuation: false });
+            drafts.push({ id: heading[1], title: heading[2].trim(), fields: {}, acceptance: [], gates: [], hasGates: false, list: null, continuationField: null });
             continue;
         }
         const draft = drafts.at(-1);
@@ -59,29 +113,42 @@ export function compileNative(file) {
                 draft.list = name;
                 if (name === "gates")
                     draft.hasGates = true;
-                draft.goalContinuation = false;
+                draft.continuationField = null;
             }
             else {
                 if (name === "goal" && !value)
                     invalid(draft.id, field[1], "must not be empty");
                 draft.fields[name] = value;
-                // OBS-60: carry every indented continuation line after `- goal:` into the compiled goal.
-                draft.goalContinuation = name === "goal";
+                // OBS-60/OBS-308: carry wrapped physical lines for prose and comma-separated fields. A
+                // worker must receive the whole logical field, regardless of the author's editor width.
+                draft.continuationField = name === "goal" || name === "deps" || name === "files" || name === "context"
+                    ? name
+                    : null;
                 draft.list = null;
             }
             continue;
         }
-        // OBS-60: multiline goals — indented prose after `- goal:` is appended until the next field.
-        if (draft.goalContinuation) {
+        // OBS-60/OBS-308: indented physical lines continue the preceding logical field until the next
+        // field/list/heading. List continuations join with a space so the existing comma parser sees the
+        // exact same value it would have received on one line.
+        if (draft.continuationField) {
+            const continuation = draft.continuationField;
             if ((line.startsWith(" ") || line.startsWith("\t")) && !NESTED_RE.test(line)) {
-                draft.fields.goal += `\n${line.trim()}`;
-                continue;
+                const value = line.trim();
+                if (continuation === "goal") {
+                    draft.fields.goal += `\n${value}`;
+                    continue;
+                }
+                if (value) {
+                    draft.fields[continuation] += ` ${value}`;
+                    continue;
+                }
             }
-            if (!line.trim()) {
+            if (continuation === "goal" && !line.trim()) {
                 draft.fields.goal += "\n";
                 continue;
             }
-            draft.goalContinuation = false;
+            draft.continuationField = null;
         }
         const nested = line.match(NESTED_RE);
         if (nested && draft.list) {
@@ -124,12 +191,16 @@ export function compileNative(file) {
     }
     // v1.62 (OBS-97): commas inside {a,b} alternatives are part of one glob entry, not separators —
     // split only at brace depth 0 so a brace glob reaches the lint (and the scope gate) intact.
+    // OBS-170/OBS-184: the same is true of a citation annotation. `.planning/OBSERVATIONS.md (OBS-262,
+    // OBS-263)` split at the inner comma into two bullets, and workers were dispatched a context line
+    // reading `OBS-263)`. Track paren depth alongside brace depth for exactly the OBS-97 reason.
     const splitTop = (value) => {
         const parts = [];
         let depth = 0;
+        let paren = 0;
         let current = "";
         for (const ch of value) {
-            if (ch === "," && depth === 0) {
+            if (ch === "," && depth === 0 && paren === 0) {
                 parts.push(current);
                 current = "";
                 continue;
@@ -138,11 +209,34 @@ export function compileNative(file) {
                 depth++;
             else if (ch === "}" && depth > 0)
                 depth--;
+            else if (ch === "(")
+                paren++;
+            else if (ch === ")" && paren > 0)
+                paren--;
             current += ch;
         }
         return [...parts, current];
     };
-    const csv = (value) => (value && value.toLowerCase() !== "none" ? splitTop(value).map((item) => item.trim()).filter(Boolean) : []);
+    // Keeping the comma is only half of it: the merged entry still carries the annotation, so it
+    // resolves no better than the fragments did (measured: 24 → 19 unresolvable, zero rescued).
+    // Strip one trailing parenthetical so the entry is the path its author meant.
+    const stripAnnotation = (item) => {
+        const trimmed = item.trim();
+        if (!trimmed.endsWith(")"))
+            return trimmed;
+        let paren = 0;
+        for (let i = trimmed.length - 1; i >= 0; i--) {
+            if (trimmed[i] === ")")
+                paren++;
+            else if (trimmed[i] === "(") {
+                paren--;
+                if (paren === 0)
+                    return trimmed.slice(0, i).trim();
+            }
+        }
+        return trimmed;
+    };
+    const csv = (value) => value && value.toLowerCase() !== "none" ? splitTop(value).map((item) => stripAnnotation(item.trim())).filter(Boolean) : [];
     // OBS-97: a typed test: oracle needs a collectable home. vitest only collects COLLECTABLE_TESTS
     // paths, so a task whose non-empty files[] cannot host one makes scope-green and acceptance-green
     // mutually exclusive by construction — run-20260719-210434 burned two dispatch attempts before a
@@ -281,6 +375,31 @@ export function compileNative(file) {
             }
         }
     }
+    // OBS-170/OBS-184: warn per unreachable context: entry, classified by the action its author must
+    // take. Warn-only by operator ruling (2026-08-03) — fail-closed would have refused to compile the
+    // spec that shipped green. Fails open when git cannot answer, so non-repo fixtures stay silent.
+    const repo = trackedAtHead(dirname(file));
+    if (repo) {
+        const unreachable = [];
+        for (const t of tasks) {
+            for (const entry of t.context) {
+                const { kind, suggestion } = classifyContextPath(entry, repo.tracked, repo.root);
+                if (kind === "untracked") {
+                    // Permanent, by ruling: the per-file force-add IS the opt-in, so this stays a standing
+                    // prompt. "and commit" is load-bearing — staging alone leaves it out of the base tree.
+                    console.warn(`tickmarkr: OBS-170: task ${t.id} context ${JSON.stringify(entry)} exists in your checkout but is NOT in a worker's worktree. To make it worker context: git add -f ${entry} && git commit. Staging alone is not enough.`);
+                }
+                else if (kind === "missing") {
+                    unreachable.push(`  ${t.id}: ${JSON.stringify(entry)}${suggestion ? `\n      → did you mean ${suggestion} ?` : "\n      → not found in the repository, and not a path."}`);
+                }
+            }
+        }
+        if (unreachable.length) {
+            throw new CompileError(`context: paths that do not exist in ${file}:\n${unreachable.join("\n")}\n\n` +
+                `A context: entry is a promise the worker can read it. These resolve to nothing in the repository,\n` +
+                `so the worker would be told to read a file that is not there. Fix the paths and recompile.`);
+        }
+    }
     return result;
 }
 // Commented native spec written to tickmarkr.spec.md by `tickmarkr init`. Documented via HTML comments (which the
@@ -319,6 +438,36 @@ acceptance is required on every task (a nested list of observable outcomes).
                  - test: <name>       (oracle: test — named test)
                  - judge: <rubric>    (oracle: judge — LLM-judged, free text)
                  - <plain text>       (compat: compiles as judge oracle, warns)
+
+  HARD BOUNDS — these FAIL the compile, they do not warn:
+    - at most 6 acceptance items per task (no exception path)
+    - at most 8 files[] patterns; a {a,b} brace group counts as ONE pattern
+    - acceptance items x files[] patterns must be <= 24 ("surface")
+    - at most 60 goal words per acceptance criterion ("density")
+    Density is goal words DIVIDED BY items, so REMOVING a criterion RAISES it. Compress the goal in the
+    same edit, or a task that was comfortably inside the bound breaches it while you are tidying up.
+
+  WHAT MAKES A CRITERION REAL:
+    - "test:" must name a real test asserting on recorded state, journal lines, or drawn frames, and its
+      title must match the criterion string verbatim. It also needs a collectable test path in files[].
+    - NO criterion may be satisfiable by an absence, a rename, a source-text grep, or an empty collection.
+      "no file references X" is not a criterion — it passes in a repo where the feature was never built.
+    - "goal:" is NEVER verification. Prose in the goal enforces nothing: every obligation needs an
+      acceptance item, or a NAMED independent gate that actually applies. A gate is not independent of a
+      task that owns both the thing it checks and the fixture it checks against.
+    - A source-only obligation (a comment or doc that a change makes false) has no lawful "test:" — verify
+      it with "judge:", which reads the DIFF and must cite a changed line in a file the task owns.
+
+  ORDERING AND OWNERSHIP:
+    - Every path has exactly ONE owning task. Two tasks writing one file must be ORDERED by deps, or the
+      loser's work is silently dropped when the integration tip advances.
+    - A file one task CREATES cannot be "context:" for another — only deps: carries it, and that extends to
+      the task that PRODUCES a value, not just the file's existence.
+    - Deleting or renaming a symbol is a cross-task contract. Sweep for consumers by symbol AND by what the
+      mechanism DOES for them; the most dangerous consumer is a file no task owns, because nothing fixes it
+      and no edge can order it.
+
+  "timeout:" IS A KILL CEILING, NOT AN ESTIMATE. Never read a sum of timeouts as a predicted duration.
 -->
 
 ## T1: Scaffold the feature

package/dist/config/config.d.ts

@@ -7,6 +7,7 @@ declare const TierEnum: z.ZodEnum<{
 export type Tier = z.infer<typeof TierEnum>;
 export declare const TIER_RANK: Record<Tier, number>;
 export declare const DEFAULT_DIFF_CAP = 60000;
+export declare const MODEL_WINDOW_PLAUSIBILITY_FLOOR = 1024;
 export declare const ROUTING_MODES: readonly ["partner-led", "risk-based", "staff-led"];
 declare const ModeEnum: z.ZodEnum<{
     "partner-led": "partner-led";
@@ -26,7 +27,7 @@ export declare const MapEntrySchema: z.ZodObject<{
 }, z.core.$strip>;
 export type MapEntry = z.infer<typeof MapEntrySchema>;
 export declare const TierEntrySchema: z.ZodObject<{
-    vendor: z.ZodString;
+    vendor: z.ZodNullable<z.ZodString>;
     channel: z.ZodEnum<{
         sub: "sub";
         api: "api";
@@ -36,6 +37,13 @@ export declare const TierEntrySchema: z.ZodObject<{
         mid: "mid";
         frontier: "frontier";
     }>>;
+    modelOverrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        vendor: z.ZodOptional<z.ZodString>;
+        channel: z.ZodOptional<z.ZodEnum<{
+            sub: "sub";
+            api: "api";
+        }>>;
+    }, z.core.$strip>>>;
     windows: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
 }, z.core.$strip>;
 export type TierEntry = z.infer<typeof TierEntrySchema>;
@@ -52,6 +60,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<{
@@ -116,7 +181,7 @@ export declare const TickmarkrConfigSchema: z.ZodObject<{
         }, z.core.$strip>>;
     }, z.core.$strip>;
     tiers: z.ZodRecord<z.ZodString, z.ZodObject<{
-        vendor: z.ZodString;
+        vendor: z.ZodNullable<z.ZodString>;
         channel: z.ZodEnum<{
             sub: "sub";
             api: "api";
@@ -126,6 +191,13 @@ export declare const TickmarkrConfigSchema: z.ZodObject<{
             mid: "mid";
             frontier: "frontier";
         }>>;
+        modelOverrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            vendor: z.ZodOptional<z.ZodString>;
+            channel: z.ZodOptional<z.ZodEnum<{
+                sub: "sub";
+                api: "api";
+            }>>;
+        }, z.core.$strip>>>;
         windows: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
     }, z.core.$strip>>;
     pricing: z.ZodRecord<z.ZodString, z.ZodNumber>;
@@ -173,6 +245,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;
@@ -239,8 +316,8 @@ export type InitConfigOverlay = {
     };
 };
 export declare function configTemplate(overlay?: InitConfigOverlay): string;
-export { FLEET_OVERLAY_KEYS, fleetEditableEquals, fleetRepoOverlayFromDelta, harvestFleetProvenance, repoOverlayYaml, serializeFleetOverlay, unifiedYamlDiff, } from "./fleet-overlay.js";
-export type { FleetDenyNotes, HarvestedProvenance } from "./fleet-overlay.js";
+export { FLEET_OVERLAY_KEYS, fleetEditableEquals, fleetRepoOverlayFromDelta, renderFleetOverlayWrite, repoOverlayYaml, serializeFleetOverlay, unifiedYamlDiff, } from "./fleet-overlay.js";
+export type { FleetOverlayWrite } from "./fleet-overlay.js";
 export type FleetTierAssignment = {
     tier: Tier;
     provenance?: string;
@@ -254,7 +331,7 @@ export type FleetEditable = {
 };
 export declare function repoOverlayPath(repoRoot: string): string;
 export declare function readOverlayFile(path: string): Record<string, unknown>;
-export declare function fleetEditableFromConfig(cfg: TickmarkrConfig, provenance?: Record<string, Record<string, string>>): FleetEditable;
+export declare function fleetEditableFromConfig(cfg: TickmarkrConfig): FleetEditable;
 /** Resolve which layer last set a dotted fleet path (defaults < global < repo). */
 export declare function fleetKeyLayer(repoRoot: string, dotted: string, opts?: {
     globalDir?: string;