tickmarkr 1.81.0 → 1.84.0

package/README.md

@@ -1,8 +1,8 @@
 ```
-              ▄▄████
-          ▄▄████▀▀
-████▄▄▄▄████▀▀     tickmarkr
-  ▀▀████▀▀         spec in, verified work out.
+       ▄▖
+     ▄█▀
+▗▄ ▄█▀             tickmarkr
+ ▝█▛               spec in, verified work out.
 ```
 
 # tickmarkr

package/dist/brand.d.ts

@@ -1,4 +1,7 @@
 import type { OwnedName } from "./drivers/types.js";
+export declare const MARK_BITMAP: readonly ["..................", "..............###.", "............####..", "..........####....", "........####......", ".###..####........", "...#####..........", "....###...........", "..................", ".................."];
+export declare const PLAIN_MARK: string;
+export declare const MARK: string;
 export declare const BANNER: string;
 /** ANSI-stripped, trailing-space-trimmed twin of BANNER — README hero and other plain surfaces. */
 export declare const PLAIN_BANNER: string;
@@ -15,7 +18,7 @@ export declare const TICKMARKR_EXIT_TRAILER = "printf '\\nTICKMARKR_''EXIT:%s\\n
 export declare function paneDispatchScript(body: string[]): string;
 /** OBS-50: one short herdr pane-run line; bootstrap lives in the script file beside the prompt. */
 export declare function paneDispatchCommand(scriptPath: string): string;
-/** The settled brand green ramp (256-color), bright → deep — the BANNER hues. */
+/** The settled brand green ramp (256-color), bright → deep. */
 export declare const BRAND_RAMP: readonly [84, 78, 41, 35];
 /** Brand green (ramp anchor 41) — the tickmark hue; also the ok/pass/authed verdict color. */
 export declare const brand: (s: string) => string;

package/dist/brand.js

@@ -1,13 +1,52 @@
 import { shq } from "./adapters/types.js";
-// TTY-only pixel-tick logo (assets/mark.svg is the image twin — same block geometry).
+// TTY-only pixel-tick logo (assets/mark.svg is generated as the image twin of this bitmap).
 // Never printed to pipes — the non-TTY stdout surface is byte-pinned by tests and consumed by machines.
 const B = "\x1b[1m", R = "\x1b[0m";
-const g = (n, s) => `\x1b[38;5;${n}m${s}${R}`; // 256-color green ramp, bright → deep
+export const MARK_BITMAP = [
+    "..................",
+    "..............###.",
+    "............####..",
+    "..........####....",
+    "........####......",
+    ".###..####........",
+    "...#####..........",
+    "....###...........",
+    "..................",
+    "..................",
+];
+const QUADRANTS = [
+    " ", "▘", "▝", "▀", "▖", "▌", "▞", "▛",
+    "▗", "▚", "▐", "▜", "▄", "▙", "▟", "█",
+];
+function packMark(bitmap) {
+    const rows = [];
+    for (let y = 0; y < bitmap.length; y += 2) {
+        let row = "";
+        for (let x = 0; x < bitmap[y].length; x += 2) {
+            const mask = (bitmap[y][x] === "#" ? 1 : 0)
+                | (bitmap[y][x + 1] === "#" ? 2 : 0)
+                | (bitmap[y + 1][x] === "#" ? 4 : 0)
+                | (bitmap[y + 1][x + 1] === "#" ? 8 : 0);
+            row += QUADRANTS[mask];
+        }
+        rows.push(row);
+    }
+    return rows.join("\n");
+}
+// The ruled silhouette, packed from the 18x10 bitmap into a 9x5 quadrant-cell grid.
+export const PLAIN_MARK = packMark(MARK_BITMAP);
+// Near-black ANSI 233 knockout ink on the solid ANSI 41 brand tile.
+export const MARK = PLAIN_MARK.split("\n")
+    .map((row) => `\x1b[38;5;233;48;5;41m${row}${R}`)
+    .join("\n");
+// Retain the reviewed 28-column compact row so narrow-header copy wraps unchanged.
+const BANNER_COPY_GAP = " ".repeat(10);
 export const BANNER = [
-    `              ${g(84, "▄▄████")}`,
-    `          ${g(78, "▄▄████▀▀")}`,
-    `${g(41, "████▄▄▄▄████▀▀")}     ${B}tickmarkr${R}`,
-    `  ${g(35, "▀▀████▀▀")}         spec in, verified work out.`,
+    // The fifth packed row is tile-only padding; the composed header stays four rows
+    // so setup retains every detected state at the contracted 24-row height.
+    ...MARK.split("\n").slice(0, -1).map((row, index) => index === 2 ? `${row}${BANNER_COPY_GAP}${B}tickmarkr${R}`
+        : index === 3 ? `${row}${BANNER_COPY_GAP}spec in, verified work out.`
+            : row),
     "",
 ].join("\n");
 /** ANSI-stripped, trailing-space-trimmed twin of BANNER — README hero and other plain surfaces. */
@@ -47,7 +86,7 @@ export function paneDispatchCommand(scriptPath) {
 // Every cockpit surface styles through these tokens/glyphs/helpers. Styled only
 // on a real TTY with NO_COLOR unset; otherwise output is the plain text itself
 // (non-TTY surfaces stay byte-pinned and machine-consumable).
-/** The settled brand green ramp (256-color), bright → deep — the BANNER hues. */
+/** The settled brand green ramp (256-color), bright → deep. */
 export const BRAND_RAMP = [84, 78, 41, 35];
 const visual = () => process.stdout.isTTY === true && process.env.NO_COLOR === undefined;
 const sgr = (code) => (s) => visual() ? `\x1b[${code}m${s}${R}` : s;

package/dist/cli/commands/approve.js

@@ -1,6 +1,6 @@
 import { userInfo } from "node:os";
 import { GATE_NAMES } from "../../graph/schema.js";
-import { ATTEMPT_CAP_RELEASE, GATE_SATISFIED_RELEASE, Journal } from "../../run/journal.js";
+import { ATTEMPT_CAP_RELEASE, GATE_SATISFIED_RELEASE, Journal, RECHECK_RELEASE, REVIEW_UPHELD_RELEASE } from "../../run/journal.js";
 // GATE-08 (v1.12): approve a parked human gate so the next `tickmarkr resume <runId>` dispatches it.
 //
 // The approval is a JOURNAL EVENT (task-approved) carrying who and when — it touches ONLY the
@@ -18,8 +18,13 @@ import { ATTEMPT_CAP_RELEASE, GATE_SATISFIED_RELEASE, Journal } from "../../run/
 //
 // Who/when is truthful, not dressed-up auth (D-03): default actor os.userInfo().username; --by overrides
 // for delegated approval; optional --reason; the event's ts (stamped by Journal.append) is the when.
+// OBS-189: `--uphold` is the second decision a review park offers. Plain approve accepts the diff the
+// reviewer rejected (gate-satisfied); --uphold sides WITH the reviewer and funds ONE fixed worker
+// attempt carrying the findings — the park costs an attempt, never the run.
 export async function approve(argv, cwd = process.cwd()) {
-    const { runId, taskId, by, reason } = parseArgs(argv);
+    const { runId, taskId, by, reason, uphold, recheck } = parseArgs(argv);
+    if (uphold && recheck)
+        throw new Error("--uphold and --recheck are different decisions — pass one");
     // Journal.open throws `no journal for <runId> at <dir>` on an unknown run — that IS the refusal.
     const journal = Journal.open(cwd, runId);
     const status = journal.replayStatuses().get(taskId);
@@ -41,8 +46,39 @@ export async function approve(argv, cwd = process.cwd()) {
         }
     }
     const lastHuman = events[lastHumanIndex];
+    if (uphold) {
+        // Fail-closed on the DATA: uphold applies only when the newest failed gate is the review gate —
+        // any other gate has no reviewer to uphold. Never inferred from the park's prose.
+        const lastFailed = events.slice(0, lastHumanIndex).reverse().find((e) => e.event === "gate-result" && e.taskId === taskId && e.data.pass === false
+            && typeof e.data.gate === "string" && GATE_NAMES.includes(e.data.gate))?.data.gate;
+        if (lastFailed !== "review") {
+            throw new Error(`--uphold applies to a review rejection; ${taskId}'s last failed gate is ${lastFailed ?? "none"} — refusing`);
+        }
+        journal.append("task-approved", taskId, {
+            by,
+            ...(reason ? { reason } : {}),
+            via: "cli",
+            release: REVIEW_UPHELD_RELEASE,
+            gate: "review",
+        });
+        return `upheld the reviewer for ${taskId} in ${runId} — by ${by}; run \`tickmarkr resume ${runId}\` to dispatch a fixed attempt carrying the findings`;
+    }
     const capPark = lastHuman?.data.kind === ATTEMPT_CAP_RELEASE;
     const gateFailPark = lastHuman?.data.kind === "gate-fail";
+    if (recheck) {
+        // OBS-203: fail-closed on the PARK KIND — only a gate-fail park has a gate to re-run. Refusing
+        // elsewhere keeps --recheck from becoming a silent budget reset on a pre-dispatch human gate.
+        if (!gateFailPark) {
+            throw new Error(`--recheck applies to a gate-fail park; ${taskId}'s park kind is ${lastHuman?.data.kind ?? "none"} — refusing`);
+        }
+        journal.append("task-approved", taskId, {
+            by,
+            ...(reason ? { reason } : {}),
+            via: "cli",
+            release: RECHECK_RELEASE,
+        });
+        return `re-checking ${taskId} in ${runId} — by ${by}; no gate marked satisfied, run \`tickmarkr resume ${runId}\` to re-dispatch against the full gate suite`;
+    }
     const failedGate = gateFailPark
         ? events.slice(0, lastHumanIndex).reverse().find((e) => e.event === "gate-result" && e.taskId === taskId && e.data.pass === false
             && typeof e.data.gate === "string" && GATE_NAMES.includes(e.data.gate))?.data.gate
@@ -59,23 +95,32 @@ export async function approve(argv, cwd = process.cwd()) {
     });
     return `approved ${taskId} in ${runId} — by ${by}; run \`tickmarkr resume ${runId}\` to ${failedGate ? "continue past the approved gate" : "dispatch it"}`;
 }
-// hand-parsed argv — no CLI framework (house style). Flags --by <name> and --reason <text>; positionals
-// are runId then taskId. Throws usage on missing positionals (mirrors resume.ts/unlock.ts).
+const USAGE = "usage: tickmarkr approve <run-id> <task-id> [--uphold|--recheck] [--by <name>] [--reason <text>]";
+// hand-parsed argv — no CLI framework (house style). Flags --uphold, --by <name>, --reason <text>;
+// positionals are runId then taskId. Throws usage on missing positionals (mirrors resume.ts/unlock.ts).
 function parseArgs(argv) {
     const positionals = [];
     let by;
     let reason;
+    let uphold = false;
+    let recheck = false;
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === "--by") {
             by = argv[++i];
             if (!by)
-                throw new Error("usage: tickmarkr approve <run-id> <task-id> [--by <name>] [--reason <text>]");
+                throw new Error(USAGE);
         }
         else if (a === "--reason") {
             reason = argv[++i];
             if (!reason)
-                throw new Error("usage: tickmarkr approve <run-id> <task-id> [--by <name>] [--reason <text>]");
+                throw new Error(USAGE);
+        }
+        else if (a === "--uphold") {
+            uphold = true;
+        }
+        else if (a === "--recheck") {
+            recheck = true;
         }
         else {
             positionals.push(a);
@@ -83,7 +128,7 @@ function parseArgs(argv) {
     }
     const [runId, taskId] = positionals;
     if (!runId || !taskId) {
-        throw new Error("usage: tickmarkr approve <run-id> <task-id> [--by <name>] [--reason <text>]");
+        throw new Error(USAGE);
     }
-    return { runId, taskId, by: by ?? userInfo().username, reason };
+    return { runId, taskId, by: by ?? userInfo().username, reason, uphold, recheck };
 }

package/dist/cli/commands/plan.js

@@ -51,9 +51,14 @@ export async function plan(argv, cwd = process.cwd(), adapters = allAdapters())
     const health = cached ?? (await probeAll(adapters));
     const channels = discoverChannels(cfg, adapters, health);
     // VIS-04 trust ramp (VALIDATION 13-01-11): preview:true bypasses the routing.learned:off short-circuit so
-    // the static-vs-learned column renders even when the daemon's learned routing is off. Cold ⇒ undefined ⇒
+    // the static-vs-learned comparison renders even when the daemon's learned routing is off. Cold ⇒ undefined ⇒
     // output byte-identical to today.
     const profile = loadRoutingProfile(cwd, cfg, { preview: true });
+    // T10: the headline row names the channel the run would actually DISPATCH. The daemon builds its profile
+    // without preview, so routing.learned: off means it dispatches the static pick — the preview profile may
+    // only feed the "learned would pick" comparison line below, never the row itself. Scoped to the switch:
+    // with learned on, dispatchProfile === profile and the surface is byte-identical to before.
+    const dispatchProfile = cfg.routing.learned === "off" ? undefined : profile;
     let deviations = 0;
     // v1.51 T4: the mode is never invisible — the header names the resolved mode, its winning
     // source, and the explore posture; each task row carries a floor-derivation line below.
@@ -129,7 +134,7 @@ export async function plan(argv, cwd = process.cwd(), adapters = allAdapters())
     const routed = [];
     for (const t of g.tasks) {
         try {
-            const r = route(t, cfg, channels, profile);
+            const r = route(t, cfg, channels, dispatchProfile);
             routed.push({ taskId: t.id, adapter: r.assignment.adapter, model: r.assignment.model });
             for (const l of r.lints) {
                 const suf = exclusionReason(l);
@@ -146,6 +151,16 @@ export async function plan(argv, cwd = process.cwd(), adapters = allAdapters())
                 const d = r.deviation;
                 lines.push(`    ⇄ static would pick ${d.static} — learned picked ${d.chosen} (score ${d.score.toFixed(3)} n=${d.n} vs ${d.staticScore.toFixed(3)})`);
             }
+            else if (dispatchProfile !== profile && profile) {
+                // learned off: the row above already names the static dispatch pick; the preview keeps its
+                // value by naming what learned routing WOULD have picked instead (same scores, same shape).
+                const pv = route(t, cfg, channels, profile);
+                if (pv.deviation) {
+                    deviations++;
+                    const d = pv.deviation;
+                    lines.push(`    ⇄ learned would pick ${d.chosen} (score ${d.score.toFixed(3)} n=${d.n} vs ${d.staticScore.toFixed(3)}) — routing.learned: off keeps the static pick`);
+                }
+            }
         }
         catch (e) {
             if (!(e instanceof RoutingError))

package/dist/cli/commands/report.js

@@ -4,7 +4,7 @@ import { ttyVisual } from "../../adapters/model-lints.js";
 import { addUsage } from "../../adapters/types.js";
 import { dim, rule, title } from "../../brand.js";
 import { loadConfig } from "../../config/config.js";
-import { buildProofBundle } from "../../report/bundle.js";
+import { buildProofBundle, gateDeclined } from "../../report/bundle.js";
 import { compareRuns } from "../../report/compare.js";
 import { estimateCosts } from "../../report/cost.js";
 import { cellsOf, cellSummary } from "../../route/profile.js";
@@ -97,6 +97,11 @@ const wallClock = (start, end) => {
     return minutes ? `${minutes}m ${seconds % 60}s` : `${seconds}s`;
 };
 const detail = (value) => typeof value === "string" || typeof value === "number" ? String(value) : EM;
+// T11: a gate that declined never ran. Drop those before the comparison metrics so the pass rate
+// counts only gates that actually ran — a declined gate is never a pass and never pads the base.
+// Declines are pass:true, so the gate-failure count is untouched. Reporting only: the unfiltered
+// events still feed the record and the proof bundle, and no gate outcome changes.
+const ranGatesOnly = (events) => events.filter((e) => e.event !== "gate-result" || !gateDeclined(e.data));
 // v1.53 T5: supersession is derived from the run's OWN journal only — `superseded by` from the
 // appended superseded event (last wins), `supersedes` from the run-start stamp. No cross-run scan.
 const supersession = (events) => {
@@ -212,7 +217,8 @@ export function renderMarkdownRecord(runId, events, prices = [], rows = []) {
         lines.push("- **tickmarks:**");
         if (gates.length) {
             for (const g of gates) {
-                const pass = g.data.pass === true ? "pass" : g.data.pass === false ? "fail" : EM;
+                // T11: a declined gate never ran — report it as declined, never as a pass.
+                const pass = gateDeclined(g.data) ? "declined" : g.data.pass === true ? "pass" : g.data.pass === false ? "fail" : EM;
                 const gate = typeof g.data.gate === "string" ? g.data.gate : EM;
                 lines.push(`  - ${gate}: ${pass} — ${firstLine(g.data.details)}`);
             }
@@ -279,7 +285,10 @@ function textReport(runId, events, rows, cwd) {
             return `  ${shape.padEnd(10)} ${chKey.padEnd(28)} ${channel.padEnd(4)} raw=${s.nRaw} n_eff=${s.nEff} disp=${s.dispatches} q=${s.quality === undefined ? "-" : s.quality.toFixed(2)} quota=${s.quotaHits} explore-left=${s.exploreRemaining}${s.cold ? "  cold (neutral)" : ""}`;
         });
     const gateResults = events.filter((e) => e.event === "gate-result");
-    const gatePass = gateResults.filter((e) => e.data.pass).length;
+    // T11: gates that declined never ran — out of both the pass count and the rate base.
+    const declinedCount = gateResults.filter((e) => gateDeclined(e.data)).length;
+    const gateRan = gateResults.length - declinedCount;
+    const gatePass = gateResults.filter((e) => e.data.pass && !gateDeclined(e.data)).length;
     const escalations = events.filter((e) => e.event === "escalation").length;
     const consults = events.filter((e) => e.event === "consult-verdict").length;
     const failovers = events.filter((e) => e.event === "quota-failover").length;
@@ -292,7 +301,7 @@ function textReport(runId, events, rows, cwd) {
         "engagement summary — audit trail:",
         ...[...groups.entries()].map(([k, g]) => `  ${k.padEnd(30)} tasks ${g.rows.length}, attempts ${g.rows.reduce((s, r) => s + r.attempts, 0)}, done ${g.rows.filter((r) => r.outcome === "done").length}`),
         "",
-        `tickmark rate: ${gateResults.length ? Math.round((100 * gatePass) / gateResults.length) : 0}% (${gatePass}/${gateResults.length})`,
+        `tickmark rate: ${gateRan ? Math.round((100 * gatePass) / gateRan) : 0}% (${gatePass}/${gateRan})${declinedCount ? ` · declined: ${declinedCount}` : ""}`,
         `escalations: ${escalations} · National Office consults: ${consults} · quota failovers: ${failovers}`,
         "",
         "spend — tokens (measured where observed):",
@@ -349,8 +358,8 @@ export async function report(argv, cwd = process.cwd()) {
         const outcome = compareRuns({
             runId,
             baselineRunId,
-            events,
-            baselineEvents: baseline.read(),
+            events: ranGatesOnly(events),
+            baselineEvents: ranGatesOnly(baseline.read()),
             rows,
             baselineRows: baseline.readTelemetry(),
             cost: cfg.cost,

package/dist/cli/commands/ui.js

@@ -1,4 +1,10 @@
 const NON_TTY_MSG = "tickmarkr ui: the cockpit requires a TTY — use `tickmarkr fleet --print` or `tickmarkr status --watch` for line-mode output";
+/**
+ * The setup surface's own flag. `tickmarkr ui --setup [run-id]` opens the one
+ * surface that writes — parked human decisions, approved or upheld through the
+ * production command path behind an explicit confirm.
+ */
+const SETUP_FLAG = "--setup";
 export async function ui(argv, io = {}, cwd = process.cwd()) {
     const input = io.input ?? process.stdin;
     const output = io.output ?? process.stdout;
@@ -15,7 +21,8 @@ export async function ui(argv, io = {}, cwd = process.cwd()) {
         });
         return "ui: closed";
     }
-    const unknownFlag = argv.find((arg) => arg.startsWith("-"));
+    const setup = argv.includes(SETUP_FLAG);
+    const unknownFlag = argv.find((arg) => arg.startsWith("-") && arg !== SETUP_FLAG);
     if (unknownFlag) {
         return { out: `tickmarkr ui: unknown flag ${unknownFlag}`, code: 1 };
     }
@@ -47,6 +54,11 @@ export async function ui(argv, io = {}, cwd = process.cwd()) {
             code: 1,
         };
     }
+    if (setup) {
+        const { runSetupDecisionsCockpit } = await import("../../tui/cockpit/setup-cockpit.js");
+        await runSetupDecisionsCockpit({ input, output, cwd, runId });
+        return "ui: closed";
+    }
     await live.runLiveCockpit({ input, output, cwd, runId, binaryVersion });
     return "ui: closed";
 }

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\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 herdr|subprocess --route-strict)\n  status        live run state\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  approve <id> <task>  approve a parked human gate (--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\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 herdr|subprocess --route-strict)\n  status        live run state\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  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

@@ -40,7 +40,7 @@ usage: tickmarkr <command>
   profile       show learned routing profile (profile reset = forget history via cursor, keeps telemetry)
   ui            open the Fleet Studio TUI (full-screen tabbed cockpit)
   unlock        remove a stale/garbage run lock (refuses if the holder is alive)
-  approve <id> <task>  approve a parked human gate (--by <name> --reason <text>); takes effect on resume`;
+  approve <id> <task>  release a park (--uphold sides with the reviewer and funds a fixed attempt; --by <name> --reason <text>); takes effect on resume`;
 // pure, testable dispatcher: resolves a command, forwards argv, shapes the result — no side effects.
 // unknown/missing cmd → USAGE (exit 1 if a cmd was typed, 0 for bare `tickmarkr`); a handler throw becomes
 // a one-line `tickmarkr <cmd>: <message>` (never a raw stack) at exit 1.

package/dist/compile/collateral.d.ts

@@ -11,3 +11,22 @@ export declare function newDirectoryLints(tasks: ReadonlyArray<Pick<Task, "id" |
  * Advisory plan output only, same contract as collateralLints.
  */
 export declare function sourceScopeLints(tasks: ReadonlyArray<Pick<Task, "id" | "files" | "acceptance">>, repoRoot: string): string[];
+/** Max acceptance items per task. Consult-converged (copus/csol/cfable R2). */
+export declare const MAX_ACCEPTANCE_ITEMS = 6;
+/** Max files[] patterns per task. */
+export declare const MAX_FILES_PATTERNS = 8;
+/**
+ * OBS-212: two tasks with no dependency path between them may run concurrently and are recreated
+ * onto a moving integration tip. If they write the same file, the graph's independence claim is
+ * false — and it comes due in the carry plumbing, which resets the task branch to the advanced tip
+ * and silently drops whatever will not cherry-pick. run-20260728-110135 lost 32 verified commits in
+ * two events that way (T2 17/17, T1 15/15), each after a sibling that shared its files merged.
+ */
+export declare function separabilityErrors(tasks: ReadonlyArray<Pick<Task, "id" | "files" | "deps">>): string[];
+/**
+ * OBS-214: a task too large to converge is not a task. T1 of v1.83 carried 8 acceptance items and a
+ * diff at the 130k cap; it took 28 dispatches and never passed review, while T3 (4 items) took 5.
+ */
+export declare function taskBudgetErrors(tasks: ReadonlyArray<Pick<Task, "id" | "files" | "acceptance">>): string[];
+/** Every Task Unit Contract violation in one pass, ready to throw. */
+export declare function taskUnitContractErrors(tasks: ReadonlyArray<Pick<Task, "id" | "files" | "deps" | "acceptance">>): string[];

package/dist/compile/collateral.js

@@ -234,3 +234,93 @@ export function sourceScopeLints(tasks, repoRoot) {
     }
     return [...newDirLints, ...lines];
 }
+// ── Task Unit Contract (OBS-212 / OBS-214) ────────────────────────────────────────────────────
+// These are ERRORS, not advisories. Everything above this line is a plan-time warning the author
+// may ignore; a graph that violates the rules below is not a graph the harness can run honestly.
+/** Max acceptance items per task. Consult-converged (copus/csol/cfable R2). */
+export const MAX_ACCEPTANCE_ITEMS = 6;
+/** Max files[] patterns per task. */
+export const MAX_FILES_PATTERNS = 8;
+/** Tasks reachable from `id` through deps (transitive). */
+function reachable(id, byId) {
+    const seen = new Set();
+    const stack = [...(byId.get(id) ?? [])];
+    while (stack.length) {
+        const next = stack.pop();
+        if (seen.has(next))
+            continue;
+        seen.add(next);
+        stack.push(...(byId.get(next) ?? []));
+    }
+    return seen;
+}
+// Conservative overlap: identical patterns, or a glob that matches the other's literal path. Two
+// globs that merely COULD intersect are not flagged — false negatives are acceptable here, false
+// positives would reject legitimate graphs.
+function overlappingPatterns(a, b) {
+    const hits = new Set();
+    const isGlob = (p) => /[*?[\]{}]/.test(p);
+    for (const pa of a) {
+        for (const pb of b) {
+            if (pa === pb) {
+                hits.add(pa);
+                continue;
+            }
+            if (isGlob(pa) && !isGlob(pb) && picomatch(pa)(pb))
+                hits.add(`${pb} ⊂ ${pa}`);
+            else if (isGlob(pb) && !isGlob(pa) && picomatch(pb)(pa))
+                hits.add(`${pa} ⊂ ${pb}`);
+        }
+    }
+    return [...hits].sort();
+}
+/**
+ * OBS-212: two tasks with no dependency path between them may run concurrently and are recreated
+ * onto a moving integration tip. If they write the same file, the graph's independence claim is
+ * false — and it comes due in the carry plumbing, which resets the task branch to the advanced tip
+ * and silently drops whatever will not cherry-pick. run-20260728-110135 lost 32 verified commits in
+ * two events that way (T2 17/17, T1 15/15), each after a sibling that shared its files merged.
+ */
+export function separabilityErrors(tasks) {
+    const byId = new Map(tasks.map((t) => [t.id, t.deps ?? []]));
+    const errors = [];
+    for (let i = 0; i < tasks.length; i++) {
+        for (let j = i + 1; j < tasks.length; j++) {
+            const a = tasks[i], b = tasks[j];
+            if (reachable(a.id, byId).has(b.id) || reachable(b.id, byId).has(a.id))
+                continue; // ordered
+            const shared = overlappingPatterns(a.files ?? [], b.files ?? []);
+            if (shared.length > 0) {
+                errors.push(`${a.id} and ${b.id} both write ${shared.join(", ")} but neither depends on the other — `
+                    + `add a dependency edge to order them, or split the shared path out. Concurrent tasks that `
+                    + `write the same file are not independent, and the loser's committed work is silently `
+                    + `dropped when the integration tip advances (OBS-212).`);
+            }
+        }
+    }
+    return errors;
+}
+/**
+ * OBS-214: a task too large to converge is not a task. T1 of v1.83 carried 8 acceptance items and a
+ * diff at the 130k cap; it took 28 dispatches and never passed review, while T3 (4 items) took 5.
+ */
+export function taskBudgetErrors(tasks) {
+    const errors = [];
+    for (const t of tasks) {
+        const items = t.acceptance?.length ?? 0;
+        if (items > MAX_ACCEPTANCE_ITEMS) {
+            errors.push(`${t.id} declares ${items} acceptance items (max ${MAX_ACCEPTANCE_ITEMS}) — split it. `
+                + `Every item is a thing one worker must satisfy at once and one reviewer must verify in one pass.`);
+        }
+        const files = t.files?.length ?? 0;
+        if (files > MAX_FILES_PATTERNS) {
+            errors.push(`${t.id} declares ${files} files[] patterns (max ${MAX_FILES_PATTERNS}) — split it. `
+                + `A wide write surface is what makes tasks collide and diffs exceed the review cap.`);
+        }
+    }
+    return errors;
+}
+/** Every Task Unit Contract violation in one pass, ready to throw. */
+export function taskUnitContractErrors(tasks) {
+    return [...separabilityErrors(tasks), ...taskBudgetErrors(tasks)];
+}

package/dist/compile/index.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { taskUnitContractErrors } from "./collateral.js";
 import { CompileError } from "./common.js";
 import { compileGsd, isGsdPhaseDir } from "./gsd.js";
 import { compileNative, TICKMARKR_NATIVE_MARKER } from "./native.js";
@@ -25,15 +26,28 @@ function detect(src) {
     }
     return null;
 }
+// OBS-212/214: the Task Unit Contract is enforced for EVERY front-end here, at the one seam they all
+// pass through, so no spec dialect can author a graph whose independence claim is false or whose
+// 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);
+    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"));
+    }
+    return g;
+}
 export function compileSource(src, type, root) {
     const kind = type ?? detect(src);
     if (kind === "speckit")
-        return compileSpecKit(src);
+        return enforceTaskUnitContract(compileSpecKit(src), src);
     if (kind === "gsd")
-        return compileGsd(src, root);
+        return enforceTaskUnitContract(compileGsd(src, root), src);
     if (kind === "native")
-        return compileNative(src);
+        return enforceTaskUnitContract(compileNative(src), src);
     if (kind === "prd")
-        return compilePrd(src);
+        return enforceTaskUnitContract(compilePrd(src), src);
     throw new CompileError(`cannot detect spec type for ${src} — pass a Spec Kit feature dir (with tasks.md), a GSD phase dir (with *-PLAN.md), or a marked native/generic PRD .md file, or use --type speckit|prd|gsd|native`);
 }

package/dist/drivers/herdr.d.ts

@@ -53,6 +53,7 @@ export declare class HerdrDriver implements ExecutorDriver {
     private joinGroup;
     run(slot: Slot, cmd: string): Promise<void>;
     private deliver;
+    nudge(slot: Slot, message: string): Promise<boolean>;
     private deliverPersistentShellCommand;
     private submitVerifiedDelivery;
     private settleDeliveryLine;

package/dist/drivers/herdr.js

@@ -524,6 +524,25 @@ export class HerdrDriver {
     // The narrator launches a perpetual shell watch, not an adapter-backed input interface. Keep
     // OBS-85's readiness + paste read-back and the historical single Enter, while worker/gate runs
     // continue through positive post-Enter evidence in submitVerifiedDelivery.
+    // OBS-201: liveness nudge — deliver one message into the live worker TUI through the exact
+    // pincer every dispatch uses (readiness stable-frame, type-without-Enter, read-back, C-u clear
+    // on corruption, verified submit), serialized on the deliveryQueue so it can never interleave
+    // with a concurrent dispatch's paste. Targets ONLY the pinned delivered pane: the pin exists so
+    // liveness cannot drift to a label rebound onto another pane (herdr.ts paneId contract) — if no
+    // pin exists the dispatch never verifiably landed, and nudging a resolved-by-label pane would
+    // reopen that hole. Best-effort: false on any failure, never a throw.
+    async nudge(slot, message) {
+        const pinned = this.deliveredPanes.get(slot);
+        if (!pinned)
+            return false;
+        try {
+            await this.deliveryQueue(() => this.deliver(slot, message, pinned));
+            return true;
+        }
+        catch {
+            return false; // the daemon journals worker-nudge-failed and falls back to the stall window
+        }
+    }
     async deliverPersistentShellCommand(slot, cmd) {
         return this.deliveryQueue(async () => {
             const pane = await this.paneId(slot);

package/dist/drivers/types.d.ts

@@ -72,6 +72,7 @@ export interface ExecutorDriver {
     status(slot: Slot): Promise<string>;
     read(slot: Slot, lines: number): Promise<string>;
     sendKey?(slot: Slot, key: string): Promise<void>;
+    nudge?(slot: Slot, message: string): Promise<boolean>;
     notify(msg: string, opts?: NotifyOpts): Promise<void>;
     close(slot: Slot): Promise<void>;
     worktree(repo: string, branch: string, baseRef: string): Promise<string>;