tickmarkr 1.87.0 → 1.90.0

package/dist/gates/run-gates.js

@@ -143,12 +143,76 @@ export async function runGates(task, ctx) {
             heldTest = undefined;
             await ctx.onGate?.({ phase: "end", gate: "test", result: held });
         }
-        return {
-            results: [...results].sort((a, b) => GATE_NAMES.indexOf(a.gate) - GATE_NAMES.indexOf(b.gate)),
-            commits,
-        };
+        const sorted = [...results].sort((a, b) => GATE_NAMES.indexOf(a.gate) - GATE_NAMES.indexOf(b.gate));
+        // v1.87 T5: no round returns a MERGEABLE GREEN on a dirty tree. The battery is not the only gate
+        // that executes shell in this worktree — the acceptance gate runs command and named-test oracles
+        // (acceptance.ts:264,275) and both verdict gates dispatch a vendor CLI here — so the last word on
+        // cleanliness has to be the round's last act rather than the battery's. `results` is what the
+        // daemon merges on (daemon.ts `results.every(gateSatisfied)`), so the withdrawal lands there; the
+        // journal keeps both the green and its retraction, the honest record of a verdict that did not
+        // survive its own round.
+        const last = sorted[sorted.length - 1];
+        if (last && sorted.every((r) => r.pass || r.meta?.skipped === true)) {
+            const dirt = await dirtyWorktree();
+            if (dirt) {
+                const refusal = dirtyRoundRefusal(last.gate, dirt);
+                results[results.indexOf(last)] = refusal;
+                sorted[sorted.length - 1] = refusal;
+                await ctx.onGate?.({ phase: "end", gate: refusal.gate, result: refusal });
+            }
+        }
+        return { results: sorted, commits };
     };
     const toolGates = ["build", "test", "lint"].filter(enabled);
+    /**
+     * v1.87 T5: the shell gates run their commands against the WORKING TREE, while evidence, scope,
+     * the judged diff and the merge all read COMMITS. Uncommitted work is therefore visible to
+     * build/test/lint and invisible to everything that decides what ships — a green battery on a dirty
+     * tree certifies a tree nobody will ever merge, and the committed diff it stands for was never run.
+     *
+     * That is not gatable-with-a-caveat, so the battery refuses it rather than gating it and hoping.
+     * An unreadable `git status` is refused on the same rule: a tree that cannot be proven clean is not
+     * proven clean. Returns the dirt (porcelain lines) to name in the refusal, or undefined when clean.
+     *
+     * The one exemption is tickmarkr's OWN droppings — root-level `.tickmarkr-*` (the adapters' usage
+     * record). The harness wrote those, not the worker; they are not work anyone meant to merge, and
+     * refusing a tree for the harness's own litter would fail every metered run. Nothing else is
+     * exempt: an untracked source file is uncommitted work by every reading git offers.
+     */
+    const dirtyWorktree = async () => {
+        const r = await shGit("GIT_OPTIONAL_LOCKS=0 git status --porcelain", ctx.worktree);
+        if (r.code !== 0)
+            return `git status failed (exit ${r.code}) — the worktree cannot be proven clean`;
+        const entries = r.stdout
+            .split("\n")
+            .map((l) => l.trimEnd())
+            .filter((l) => l.trim() && !/^.. \.tickmarkr-[^/]*$/.test(l));
+        return entries.length ? entries.join("\n") : undefined;
+    };
+    const DIRTY_WHY = `refusing to gate a dirty worktree: the shell gates run against the working tree while `
+        + `evidence, scope and the merge read commits, so these uncommitted changes would be gated `
+        + `and never merged (and the committed diff would never be run)`;
+    // `left` names the command that CREATED the dirt when one did; a round-entry refusal has no culprit.
+    const dirtyRefusal = (gate, dirt, left) => ({
+        gate,
+        pass: false,
+        details: DIRTY_WHY
+            + (left ? `. The ${gate} command (${left}) left them behind, so every gate after it would judge a tree nobody will merge:\n` : `:\n`)
+            + dirt,
+        meta: { dirtyWorktree: true, ...(left ? { dirtiedBy: gate } : {}) },
+    });
+    // The round-end withdrawal (see `done`). It blames no command: whatever dirtied the tree ran after
+    // the last cleanliness check, and naming a culprit this function cannot identify would be a worse
+    // record than naming the fact. `gate` is the verdict being withdrawn, not an accusation about who wrote.
+    const dirtyRoundRefusal = (gate, dirt) => ({
+        gate,
+        pass: false,
+        details: `${DIRTY_WHY}. Every gate of this round was satisfied and the round ended dirty — something after `
+            + `the last cleanliness check (the acceptance gate's command/test oracles, or a verdict gate's `
+            + `vendor CLI) wrote into the worktree — so this mergeable result is withdrawn rather than merged. `
+            + `Uncommitted at round end:\n${dirt}`,
+        meta: { dirtyWorktree: true, dirtyAtRoundEnd: true },
+    });
     // build/test/lint vs the shared baseline
     const runBattery = async (commands, selected) => {
         if (!toolGates.length)
@@ -158,9 +222,15 @@ export async function runGates(task, ctx) {
             // not at true execution start. They are collectively sub-second (measured), so the debounce
             // suppresses them anyway; split compareToBaseline only if a tool gate ever gets slow.
             const toolResults = await compareToBaseline(ctx.worktree, commands, ctx.baseline, toolGates);
+            // The same refusal AFTER the commands, because a green command can dirty the tree the check
+            // above just proved clean. Batched, legacy cannot say WHICH command did it, so the refusal
+            // lands on the last gate that had one — the round dies there either way. A red battery is
+            // reported as the red it is: the round already ends, and the command output is the better lead.
+            const dirt = toolResults.every((r) => r.pass) ? await dirtyWorktree() : undefined;
+            const blame = dirt ? [...toolGates].reverse().find((g) => commands[g]) : undefined;
             for (const r of toolResults) {
                 await emitStart(r.gate);
-                await record(r);
+                await record(r.gate === blame ? dirtyRefusal(blame, dirt, commands[blame]) : r);
             }
             return;
         }
@@ -169,6 +239,18 @@ export async function runGates(task, ctx) {
         for (const g of toolGates) {
             await emitStart(g);
             const [r] = await compareToBaseline(ctx.worktree, commands, ctx.baseline, [g]);
+            // The pre-battery check proves the tree clean ONCE; a command that exits 0 having rewritten a
+            // tracked file makes it dirty again, and every gate after it — including the next shell gate,
+            // which would then run against bytes HEAD does not hold — inherits that. So re-check after each
+            // command, the last one included, and fail the gate whose command did it. (A red command needs
+            // no check: it already ends the round, and its own output is the truer verdict.)
+            if (r.pass && commands[g]) {
+                const dirt = await dirtyWorktree();
+                if (dirt) {
+                    await record(dirtyRefusal(g, dirt, commands[g]));
+                    return;
+                }
+            }
             if (g === "test" && selected) {
                 const screened = { ...r, meta: { ...r.meta, selectedTests: selected } };
                 // green: held (see heldTest) so the full suite below can supersede it with ONE verdict.
@@ -194,7 +276,23 @@ export async function runGates(task, ctx) {
         commits = e.commits;
         return { gate: e.gate, pass: e.pass, details: e.details };
     };
-    const scopeResult = () => scopeGate(ctx.worktree, ctx.baseRef, task.files, ctx.result, ctx.cfg.scope?.allowDeviations ?? []);
+    /**
+     * v1.87 T5: the allowlist is read ONCE — at entry, before any gate of this round runs — copied out
+     * of `ctx.cfg` and frozen. Both halves are the enforcement: the copy means a later write to the
+     * daemon's live config object cannot reach the gate mid-round (the screen at line ~296 and the
+     * canonical scope gate below are two separate reads of it), and the freeze means nothing this file
+     * hands to `scopeGate` can be widened in flight either. Nothing anywhere writes it back.
+     *
+     * The boundary, stated rather than implied: this binds the allowlist for the lifetime of a round,
+     * which is the largest unit this function owns. It cannot speak for a `tickmarkr resume`, which is
+     * a new process whose config the daemon resolves afresh (src/run/daemon.ts) — binding an allowlist
+     * across a restart would have to live there, is outside this task's file scope, and is claimed
+     * neither here nor in the worker prompt. What the prompt does claim is what holds: a WORKER has no
+     * way to change this list, mid-round or otherwise.
+     */
+    const allowDeviations = [...(ctx.cfg.scope?.allowDeviations ?? [])];
+    Object.freeze(allowDeviations);
+    const scopeResult = () => scopeGate(ctx.worktree, ctx.baseRef, task.files, ctx.result, allowDeviations);
     const runGate = async (gate, compute) => {
         await emitStart(gate);
         await record(await compute());
@@ -337,6 +435,19 @@ export async function runGates(task, ctx) {
         }
         return rv;
     };
+    // v1.87 T5: the refusal is the FIRST thing a round does, whatever that round is configured to run.
+    // Guarding only the configured build/test/lint commands left the hole this repairs: the battery is
+    // not the only gate that executes shell in this worktree — the acceptance gate runs command and
+    // named-test oracles — so a task with NO tool command configured skipped the check entirely and its
+    // oracles judged uncommitted state, on a commit whose diff nobody had run. One check at the top, and
+    // no shell-executing gate path is reachable on a dirty tree. It lands on the first gate of this
+    // round's sequence: the round dies there, exactly as it does on a red command.
+    const entryDirt = sequence.length ? await dirtyWorktree() : undefined;
+    if (entryDirt) {
+        await emitStart(sequence[0]);
+        await record(dirtyRefusal(sequence[0], entryDirt));
+        return done();
+    }
     if (v185 && await screenBlocks())
         return done();
     // A non-final round may run only the tests covering its own diff; the merge-candidate round below
@@ -404,8 +515,14 @@ export async function runGates(task, ctx) {
     // stream, and `fullSuite` says which suite spoke while `selectedTests` keeps what the screen ran.
     if (selected) {
         await emitStart("test");
+        // This is the last shell command a round can run — the judge's named-test oracle (acceptance.ts)
+        // may have run one before it, and every gate between the battery and here reads commits only, so
+        // a clean tree HERE is what makes "the gated commit is the tested tree" true at merge time.
         const [full] = await compareToBaseline(ctx.worktree, ctx.commands, ctx.baseline, ["test"]);
-        const merged = { ...full, meta: { ...full.meta, fullSuite: true, selectedTests: selected } };
+        const dirt = full.pass ? await dirtyWorktree() : undefined;
+        const merged = dirt
+            ? dirtyRefusal("test", dirt, ctx.commands.test)
+            : { ...full, meta: { ...full.meta, fullSuite: true, selectedTests: selected } };
         results[results.findIndex((r) => r.gate === "test")] = merged;
         heldTest = undefined;
         await ctx.onGate?.({ phase: "end", gate: "test", result: merged });

package/dist/gates/scope.js

@@ -1,4 +1,4 @@
-import picomatch from "picomatch";
+import { filesGlob } from "../graph/files-glob.js";
 import { shGitOk } from "../run/git.js";
 // OBS-61: the live integration tip can advance between attempts (sibling merge) while a resumed
 // worktree stays parented on the old base — merge-base(tip, HEAD) pins the diff to the worktree's
@@ -11,7 +11,7 @@ export async function scopeDiffBase(worktree, integrationTip) {
 }
 /** Pure offender split — corpus-replay oracle exercises this exact decision logic. */
 export function dispositionOffenders(offenders, allowDeviations) {
-    const allowedMatch = allowDeviations.length ? picomatch(allowDeviations, { dot: true }) : () => false;
+    const allowedMatch = allowDeviations.length ? filesGlob(allowDeviations) : () => false;
     const allowed = [];
     const hard = [];
     for (const f of offenders) {
@@ -27,7 +27,7 @@ export async function scopeGate(worktree, integrationTip, files, result, allowDe
         return { gate: "scope", pass: true, details: "no file scope declared — unrestricted" };
     const baseRef = await scopeDiffBase(worktree, integrationTip);
     const changed = (await shGitOk(`git diff --name-only '${baseRef}..HEAD'`, worktree)).trim().split("\n").filter(Boolean);
-    const inScope = picomatch(files, { dot: true }); // byte-identical options to assertWriteScope in src/compile/common.ts
+    const inScope = filesGlob(files); // the ONE files[] matcher — src/graph/files-glob.ts (Q120s)
     const offenders = changed.filter((f) => !inScope(f));
     if (!offenders.length)
         return { gate: "scope", pass: true, details: `all ${changed.length} changed files in scope` };

package/dist/graph/files-glob.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The ONE matcher for files[] / scope.allowDeviations semantics (Q120s, TRIAL T-OBS-4).
+ *
+ * Parens in a files[] entry are LITERAL path characters. Expo Router and Next.js name
+ * group directories `(app)`, `(marketing)` — but picomatch compiles a bare `(app)` to a
+ * regex CAPTURE GROUP matching `app`, so a pattern naming such a path can never match it
+ * (SentioQ run-1: T3 burned 3 dispatches on a scope red unwinnable by construction).
+ * Brackets need no help: this picomatch already compiles `[id]` to the alternation
+ * `(?:\[id\]|[id])`, literal-or-class.
+ *
+ * The price is extglobs (`@(a|b)` etc.) become literal text in files[] entries — they
+ * have no recorded use in any spec, and a scope allowlist wants boring, predictable
+ * matching over regex power. Every consumer of files[]-shaped patterns MUST match
+ * through this module; a second picomatch call with hand-rolled options is how the
+ * gate and the compiler drift apart.
+ */
+export declare const literalParens: (pattern: string) => string;
+export declare function filesGlob(patterns: string | string[]): (path: string) => boolean;

package/dist/graph/files-glob.js

@@ -0,0 +1,22 @@
+import picomatch from "picomatch";
+/**
+ * The ONE matcher for files[] / scope.allowDeviations semantics (Q120s, TRIAL T-OBS-4).
+ *
+ * Parens in a files[] entry are LITERAL path characters. Expo Router and Next.js name
+ * group directories `(app)`, `(marketing)` — but picomatch compiles a bare `(app)` to a
+ * regex CAPTURE GROUP matching `app`, so a pattern naming such a path can never match it
+ * (SentioQ run-1: T3 burned 3 dispatches on a scope red unwinnable by construction).
+ * Brackets need no help: this picomatch already compiles `[id]` to the alternation
+ * `(?:\[id\]|[id])`, literal-or-class.
+ *
+ * The price is extglobs (`@(a|b)` etc.) become literal text in files[] entries — they
+ * have no recorded use in any spec, and a scope allowlist wants boring, predictable
+ * matching over regex power. Every consumer of files[]-shaped patterns MUST match
+ * through this module; a second picomatch call with hand-rolled options is how the
+ * gate and the compiler drift apart.
+ */
+export const literalParens = (pattern) => pattern.replace(/\\?[()]/g, (m) => (m.length === 2 ? m : `\\${m}`));
+export function filesGlob(patterns) {
+    const list = (Array.isArray(patterns) ? patterns : [patterns]).map(literalParens);
+    return picomatch(list, { dot: true });
+}

package/dist/graph/schema.d.ts

@@ -4,11 +4,13 @@ export declare const GRAPH_ROUTING_MODES: readonly ["partner-led", "risk-based",
 export declare const STATUSES: readonly ["pending", "running", "gated", "failed", "done", "human"];
 export declare const GATE_NAMES: readonly ["build", "test", "lint", "evidence", "scope", "acceptance", "review"];
 export declare const TIERS: readonly ["cheap", "mid", "frontier"];
+export declare const SPEC_SOURCES: readonly ["speckit", "gsd", "prd", "native"];
 export declare const ORACLES: readonly ["command", "test", "judge"];
 export type Shape = (typeof SHAPES)[number];
 export type TaskStatus = (typeof STATUSES)[number];
 export type GateName = (typeof GATE_NAMES)[number];
 export type Oracle = (typeof ORACLES)[number];
+export type SpecSource = (typeof SPEC_SOURCES)[number];
 export declare const AcceptanceItemSchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
     oracle: z.ZodLiteral<"command">;
     command: z.ZodString;
@@ -110,10 +112,10 @@ export declare const RunGraphSchema: z.ZodObject<{
             gsd: "gsd";
             prd: "prd";
             native: "native";
-            taskmaster: "taskmaster";
         }>;
         paths: z.ZodArray<z.ZodString>;
         hash: z.ZodString;
+        base: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     tasks: z.ZodArray<z.ZodObject<{
         id: z.ZodString;

package/dist/graph/schema.js

@@ -7,6 +7,7 @@ export const STATUSES = ["pending", "running", "gated", "failed", "done", "human
 export const GATE_NAMES = ["build", "test", "lint", "evidence", "scope", "acceptance", "review"];
 const MANDATORY_GATES = ["build", "test", "lint", "evidence", "scope"];
 export const TIERS = ["cheap", "mid", "frontier"];
+export const SPEC_SOURCES = ["speckit", "gsd", "prd", "native"];
 // v1.19 acceptance oracles: command (exit code), test (named test), judge (LLM, free-text rubric).
 // A plain string is the read-old/write-new compat form — semantically a judge oracle (spec §2).
 export const ORACLES = ["command", "test", "judge"];
@@ -98,9 +99,11 @@ export const RunGraphSchema = z
     // precedence: run flag > this > repo config > global config > default (risk-based).
     mode: z.enum(GRAPH_ROUTING_MODES).optional(),
     spec: z.object({
-        source: z.enum(["speckit", "gsd", "prd", "native", "taskmaster"]),
+        source: z.enum(SPEC_SOURCES),
         paths: z.array(z.string()),
         hash: z.string(),
+        // Q11 compile half: an author-declared ref only. Runtime Git resolution/enforcement is later.
+        base: z.string().min(1).optional(),
     }),
     tasks: z.array(TaskSchema).min(1),
 })

package/dist/run/daemon.d.ts

@@ -1,6 +1,8 @@
 import { type WorkerAdapter } from "../adapters/types.js";
 import { type ModeResolution, type RoutingMode, type TickmarkrConfig } from "../config/config.js";
 import { type ExecutorDriver } from "../drivers/types.js";
+import { type Baseline } from "../gates/baseline.js";
+import type { GateResult } from "../gates/types.js";
 import { Journal, type JournalEvent } from "./journal.js";
 export interface RunOptions {
     runId?: string;
@@ -15,6 +17,7 @@ export interface RunOptions {
     mode?: RoutingMode;
     narrate?: (event: JournalEvent) => void;
     exit?: (code: number) => void;
+    supervise?: boolean;
 }
 export type ModeSource = "run flag" | "spec" | "repo config" | "global config" | "default";
 export interface ResolvedRunMode {
@@ -40,8 +43,45 @@ export interface RunSummary {
     blocked: string[];
     tipVerify?: "passed" | "failed";
     lastMergedTask?: string;
+    /** T14: did every approval this run accepted actually get enacted, or did the run end over one? */
+    approvalDisposition?: "complete" | "outstanding";
+    /** the accepted approvals that never reached a dispatch — named, never left to the park buckets */
+    outstandingApprovals?: string[];
 }
+/**
+ * T14: approvals the run accepted and never acted on. `approved` above is built ONCE at startup —
+ * deliberately, replay determinism depends on it — so an approval written while the daemon is live is
+ * inert for that run. Without this the run-end record stated only buckets and tipVerify, both
+ * accurate, over a milestone that was silently incomplete: run …230 ended tipVerify "passed" with two
+ * upheld approvals and zero subsequent dispatches. Scored per task on its NEWEST approval: a later
+ * approval is the live decision, and the events that answer it are the ones after it.
+ */
+export declare function outstandingApprovals(events: JournalEvent[]): string[];
 export declare function formatSummary(s: RunSummary): string;
+/**
+ * R3 (OBS-186): a gate that DECLINED to run is not a gate that failed. The review gate's skip branch
+ * no longer forges `pass: true` to buy passage, so the merge decision has to read the same predicate
+ * the run surfaces already read (src/run/activity.ts): pass, or an honest declared skip. Without this
+ * the honesty change would silently park every judge-only task at merge — an unrun gate blocking work
+ * it was never asked to review. `skipped` is set only by a gate that says so about ITSELF; a red
+ * verdict from a review that actually ran still fails here, exactly as before.
+ *
+ * ONE pair of predicates, every fold. `!g.pass` was correct only while the sole `pass:false` producer
+ * was a gate that actually failed; the moment a decline can be recorded red, every `!g.pass` in this
+ * file — the retry feedback brief, the review-fix eligibility test, the failing-battery list the
+ * ladder and the fingerprint cap are scored on, the structured findings attached to a blocking
+ * verdict — reads an unrun gate as a defect. `gateFailed` is the seam they now share, and the journal
+ * write below is the seam every OUT-of-file fold shares.
+ */
+/**
+ * T9: `meta.infra === true` overrides BOTH clauses above. A runner that died on the machine
+ * (spawn EAGAIN, OOM) without completing a suite answered nothing about the work, so the honest
+ * report of that fact must not double as authorization to merge — and it is the merge predicate,
+ * not the gate, that has to say so: classifying the failure into infra metadata while still
+ * reporting `pass: true` is exactly how a run that never verified anything gets merged. A declared
+ * skip stays satisfied; a gate that ran and passed stays satisfied.
+ */
+export declare const gateSatisfied: (g: GateResult) => boolean;
 /**
  * T4 (OBS-265): the journal with the review objections a round did NOT hinge on removed. Judge and
  * review are now launched together, so a round can journal a failed review that the serial walk would
@@ -92,9 +132,13 @@ export declare function commandsHash(commands: Record<string, string>): string;
  */
 export declare function verifyIntegrationTipCached(intWt: string, commands: Record<string, string>, journal: Journal, opts?: {
     lastMergedTask?: string;
+    baseline?: Baseline;
 }): Promise<boolean>;
 export declare function workerTreeCpuMs(marker: string, cwd: string): Promise<{
     ms: number;
     resolutionMs: number;
 } | undefined>;
+/** Test seam — exercise the production observer's total read bound with a small real tree. */
+export declare function setObserveBudgetBytesForTests(bytes: number): void;
+export declare function resetObserveBudgetBytesForTests(): void;
 export declare function runDaemon(repoRoot: string, opts?: RunOptions): Promise<RunSummary>;