tickmarkr 2.1.4 → 2.1.6

package/dist/cli/commands/stats.d.ts

@@ -0,0 +1,21 @@
+export declare const STATS_COLUMNS: readonly ["author", "reviewer", "dispatches", "deliveries", "delivery rate", "attempts to green", "real reds", "infra reds", "within-task rescues"];
+export interface ChannelStats {
+    author: string;
+    reviewers: string[];
+    dispatches: number;
+    deliveries: number;
+    deliveryRate: number;
+    /** Mean journal-recorded attempts among this channel's delivered tasks; null when it delivered none. */
+    attemptsToGreen: number | null;
+    realReds: number;
+    infraReds: number;
+    rescues: string[];
+}
+export interface StatsReport {
+    runs: number;
+    channels: ChannelStats[];
+}
+/** Reduce every readable run journal under the repository's state directory. */
+export declare function collectChannelStats(cwd?: string): StatsReport;
+export declare function renderStats(report: StatsReport): string;
+export declare function stats(argv: string[], cwd?: string): Promise<string>;

package/dist/cli/commands/stats.js

@@ -0,0 +1,210 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { classifyFailureOutput } from "../../gates/baseline.js";
+import { stateDirName } from "../../graph/graph.js";
+import { Journal } from "../../run/journal.js";
+// The operator-facing schema is deliberately closed. Adding a fact to the table therefore requires
+// adding it here as a conscious compatibility change, rather than letting incidental journal fields
+// leak into an analytics surface.
+export const STATS_COLUMNS = [
+    "author",
+    "reviewer",
+    "dispatches",
+    "deliveries",
+    "delivery rate",
+    "attempts to green",
+    "real reds",
+    "infra reds",
+    "within-task rescues",
+];
+const assignmentAuthor = (data) => {
+    const assignment = data.assignment;
+    if (!assignment || typeof assignment !== "object")
+        return undefined;
+    const { adapter, model } = assignment;
+    return typeof adapter === "string" && typeof model === "string"
+        ? `${adapter}:${model}`
+        : undefined;
+};
+// Current journals write the reviewer into review prose; the structured field is also accepted so
+// journals produced through gateResultJournalData retain their stronger identity representation.
+const reviewerFrom = (data) => {
+    if (typeof data.reviewer === "string" && data.reviewer.trim())
+        return data.reviewer.trim();
+    if (typeof data.details !== "string")
+        return undefined;
+    return /\breviewer(?:\s+|:\s*)([\w@./+-]+:[\w@./+-]+)/iu.exec(data.details)?.[1];
+};
+const redEvidence = (data) => {
+    const fingerprints = Array.isArray(data.fingerprints)
+        ? data.fingerprints.filter((value) => typeof value === "string")
+        : [];
+    const prose = [data.details, data.error, data.reason]
+        .filter((value) => typeof value === "string");
+    return [...fingerprints, ...prose].join("\n");
+};
+const historyFor = (tasks, taskId) => {
+    let history = tasks.get(taskId);
+    if (!history) {
+        history = { dispatches: [], deliveries: [] };
+        tasks.set(taskId, history);
+    }
+    return history;
+};
+const dispatchedAuthorFor = (history, data) => {
+    const attempt = typeof data.attempt === "number" && Number.isInteger(data.attempt)
+        ? data.attempt
+        : undefined;
+    if (attempt !== undefined) {
+        const matched = [...history.dispatches].reverse().find((dispatch) => dispatch.attempt === attempt);
+        if (matched)
+            return matched.author;
+    }
+    return history.dispatches.at(-1)?.author;
+};
+const runIdsWithJournals = (cwd) => {
+    const runsDir = join(cwd, stateDirName(cwd), "runs");
+    if (!existsSync(runsDir))
+        return [];
+    return readdirSync(runsDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && entry.name.startsWith("run-")
+        && existsSync(join(runsDir, entry.name, "journal.jsonl")))
+        .map((entry) => entry.name)
+        .sort();
+};
+/** Reduce every readable run journal under the repository's state directory. */
+export function collectChannelStats(cwd = process.cwd()) {
+    const runIds = runIdsWithJournals(cwd);
+    const channels = new Map();
+    const channelFor = (author) => {
+        let channel = channels.get(author);
+        if (!channel) {
+            channel = {
+                author, reviewers: new Set(), dispatches: 0, deliveries: 0,
+                attemptsToGreen: 0, realReds: 0, infraReds: 0, rescues: new Set(),
+            };
+            channels.set(author, channel);
+        }
+        return channel;
+    };
+    for (const runId of runIds) {
+        const events = Journal.open(cwd, runId).read();
+        const tasks = new Map();
+        for (const [eventIndex, event] of events.entries()) {
+            if (!event.taskId)
+                continue;
+            const history = historyFor(tasks, event.taskId);
+            if (event.event === "task-dispatch") {
+                const author = assignmentAuthor(event.data);
+                if (!author)
+                    continue;
+                channelFor(author).dispatches += 1;
+                history.dispatches.push({
+                    author,
+                    ...(typeof event.data.attempt === "number" && Number.isInteger(event.data.attempt)
+                        ? { attempt: event.data.attempt }
+                        : {}),
+                    eventIndex,
+                });
+                continue;
+            }
+            if (event.event === "task-done") {
+                const author = assignmentAuthor(event.data) ?? history.dispatches.at(-1)?.author;
+                if (!author)
+                    continue;
+                const channel = channelFor(author);
+                channel.deliveries += 1;
+                const recordedAttempts = typeof event.data.attempts === "number"
+                    && Number.isInteger(event.data.attempts) && event.data.attempts >= 0
+                    ? event.data.attempts
+                    : history.dispatches.filter((dispatch) => dispatch.eventIndex < eventIndex).length;
+                channel.attemptsToGreen += recordedAttempts;
+                history.deliveries.push({ author, eventIndex });
+                continue;
+            }
+            if (event.event === "review-retry") {
+                const author = dispatchedAuthorFor(history, event.data);
+                if (!author)
+                    continue;
+                for (const reviewer of [event.data.flaked, event.data.retried]) {
+                    if (typeof reviewer === "string" && reviewer.trim())
+                        channelFor(author).reviewers.add(reviewer.trim());
+                }
+                continue;
+            }
+            if (event.event !== "gate-result")
+                continue;
+            const author = dispatchedAuthorFor(history, event.data);
+            if (!author)
+                continue;
+            const channel = channelFor(author);
+            if (event.data.gate === "review") {
+                const reviewer = reviewerFrom(event.data);
+                if (reviewer)
+                    channel.reviewers.add(reviewer);
+            }
+            if (event.data.pass !== false)
+                continue;
+            const infra = event.data.infra === true || classifyFailureOutput(redEvidence(event.data)) === "infra";
+            if (infra)
+                channel.infraReds += 1;
+            else
+                channel.realReds += 1;
+        }
+        // A rescue is task-matched, not attempt-matched: one edge says the failed author and delivering
+        // author faced the same task in the same run. Repeated attempts on the failed author do not make
+        // the task easier and therefore do not manufacture extra controlled comparisons.
+        for (const [taskId, history] of tasks) {
+            for (const delivery of history.deliveries) {
+                const failedAuthors = new Set(history.dispatches
+                    .filter((dispatch) => dispatch.eventIndex < delivery.eventIndex && dispatch.author !== delivery.author)
+                    .map((dispatch) => dispatch.author));
+                for (const failedAuthor of failedAuthors) {
+                    channelFor(delivery.author).rescues.add(`${failedAuthor} → ${delivery.author} (${runId}/${taskId})`);
+                }
+            }
+        }
+    }
+    return {
+        runs: runIds.length,
+        channels: [...channels.values()]
+            .sort((a, b) => a.author.localeCompare(b.author, "en"))
+            .map((channel) => ({
+            author: channel.author,
+            reviewers: [...channel.reviewers].sort((a, b) => a.localeCompare(b, "en")),
+            dispatches: channel.dispatches,
+            deliveries: channel.deliveries,
+            deliveryRate: channel.dispatches === 0 ? 0 : channel.deliveries / channel.dispatches,
+            attemptsToGreen: channel.deliveries === 0 ? null : channel.attemptsToGreen / channel.deliveries,
+            realReds: channel.realReds,
+            infraReds: channel.infraReds,
+            rescues: [...channel.rescues].sort((a, b) => a.localeCompare(b, "en")),
+        })),
+    };
+}
+const percent = (rate) => `${Number((rate * 100).toFixed(1))}%`;
+export function renderStats(report) {
+    const lines = [`tickmarkr stats — ${report.runs} run${report.runs === 1 ? "" : "s"}`];
+    if (report.channels.length === 0)
+        return [...lines, "no channels"].join("\n");
+    lines.push(STATS_COLUMNS.join(" | "));
+    for (const channel of report.channels) {
+        lines.push([
+            channel.author,
+            channel.reviewers.join(", ") || "—",
+            channel.dispatches,
+            channel.deliveries,
+            percent(channel.deliveryRate),
+            channel.attemptsToGreen === null ? "—" : Number(channel.attemptsToGreen.toFixed(2)),
+            channel.realReds,
+            channel.infraReds,
+            channel.rescues.join("; ") || "—",
+        ].join(" | "));
+    }
+    return lines.join("\n");
+}
+export async function stats(argv, cwd = process.cwd()) {
+    if (argv.length > 0)
+        throw new Error("stats takes no run id — it reads every run in the state directory");
+    return renderStats(collectChannelStats(cwd));
+}

package/dist/cli/commands/status.js

@@ -7,7 +7,7 @@ import { formatOwnedName, parseOwnedName, } from "../../drivers/types.js";
 import { blockedTasks, graphDefinitionHash, loadGraph, stateDirName } from "../../graph/graph.js";
 import { GATE_NAMES } from "../../graph/schema.js";
 import { foldActivity } from "../../run/activity.js";
-import { Journal, engagementComparable, isQualityFailureParkKind, recordedTaskFailureKind, runHasEnded, } from "../../run/journal.js";
+import { Journal, engagementComparable, isQualityFailureParkKind, preservedRefsByTask, recordedTaskFailureKind, runHasEnded, upheldFeedbackByTask, } from "../../run/journal.js";
 import { isPidLive } from "../../run/lock.js";
 import { normalizeGateOutcome } from "../../run/outcome.js";
 import { desiredPanes } from "../../run/reconcile.js";
@@ -979,6 +979,21 @@ binaryVersion, now = Date.now(), animationFrame = 0, workerLiveness = new Map(),
         if (!taskIds.has(taskId))
             phases.delete(taskId);
     const hotPhase = [...phases.values()].sort((a, b) => a.order - b.order).at(-1);
+    // OBS-738: recovery facts stay on the journal's two established reducers. The prefix fold keeps an
+    // older journal equally readable by asking upheldFeedbackByTask what was active at that exact
+    // restore boundary; current resume-restore rows additionally carry the same task for narration.
+    const preservedRefs = preservedRefsByTask(events);
+    const restoredUpheldFeedback = new Set(events.flatMap((event, index) => event.event === "resume-restore" && event.taskId
+        && upheldFeedbackByTask(events.slice(0, index)).has(event.taskId)
+        ? [event.taskId]
+        : []));
+    const recoveryLinesForTask = (taskId) => [
+        ...(preservedRefs.get(taskId) ?? []).flatMap(({ ref, diffCommand }) => [
+            `preserved worktree — ${taskId} — ${ref}`,
+            `  ${diffCommand}`,
+        ]),
+        ...(restoredUpheldFeedback.has(taskId) ? [`upheld feedback restored for ${taskId}`] : []),
+    ].map(sanitizeTaskText);
     const cells = renderedTasks.map((t) => {
         const folded = journalRowsOnly && comparable ? taskRows.get(t.id) : undefined;
         const st = folded?.state ?? replayed?.get(t.id) ?? t.status;
@@ -1011,7 +1026,7 @@ binaryVersion, now = Date.now(), animationFrame = 0, workerLiveness = new Map(),
     if (!unicode) {
         // machine/CI surface — journals without phase-start stay byte-identical; new phase-aware frames
         // use an ASCII spinner so pipes never receive terminal-only braille/ANSI.
-        const rows = cells.map(({ t, st, merged, label, assignCol, livePhase, states, priorGraph, pane }) => {
+        const rows = cells.flatMap(({ t, st, merged, label, assignCol, livePhase, states, priorGraph, pane }) => {
             const chain = gateChain(states, false);
             const prefix = livePhase ? `  ${ASCII_SPINNER[animationFrame % ASCII_SPINNER.length]} ${t.id} ` : `  ${surfaceTaskBox(st, merged)} ${t.id} `;
             const suffix = `  ${chain}${priorGraph ? ` ${PRIOR_GRAPH_MARKER}` : ""}  ${livePhase ? "running" : surfaceStatusWord(st)}${label}  ${assignCol}${pane ? `  pane ${pane}` : ""}`;
@@ -1020,7 +1035,10 @@ binaryVersion, now = Date.now(), animationFrame = 0, workerLiveness = new Map(),
             // can exceed the terminal width, and the pre-floor math paid for it out of the TITLE — 20 of
             // 41 rows in a live 41-task run named no task at all. These rows already overflow `width`
             // (a pane name is 60 columns on its own), so the floor costs wrapping, never the graph.
-            return `${prefix}${shortGoal(t.title, Math.max(MACHINE_TITLE_FLOOR, width - prefix.length - suffix.length))}${suffix}`;
+            return [
+                `${prefix}${shortGoal(t.title, Math.max(MACHINE_TITLE_FLOOR, width - prefix.length - suffix.length))}${suffix}`,
+                ...recoveryLinesForTask(t.id).map((line) => `    ${line}`),
+            ];
         });
         const zone = journalRowsOnly ? `${divider}zone ${localZoneLabel(zoneReference)}` : "";
         const header = runId
@@ -1210,6 +1228,12 @@ binaryVersion, now = Date.now(), animationFrame = 0, workerLiveness = new Map(),
         return [legend(headerRow), dim(ruleRow), ...rows];
     };
     const gatesLegend = legend(`    gates   ${GATE_NAMES.map((gate) => `${gate.slice(0, 2)} ${gate}`).join("  ")}`);
+    const recoveryLines = cells.flatMap((cell) => recoveryLinesForTask(cell.t.id));
+    const recoverySection = recoveryLines.length === 0 ? [] : [
+        "",
+        `  ${ok("▌")} ${title("RECOVERY")}`,
+        ...recoveryLines.map((line) => legend(`    ${line}`)),
+    ];
     const effort = effortPanel(g.tasks, record && !comparable ? undefined : events, boardColumns);
     return {
         content: boardRows([
@@ -1220,6 +1244,7 @@ binaryVersion, now = Date.now(), animationFrame = 0, workerLiveness = new Map(),
             taskSection,
             "",
             ...tableRows(),
+            ...recoverySection,
             gatesLegend,
             "",
             rule(boardColumns),

package/dist/cli/index.d.ts

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

package/dist/cli/index.js

@@ -14,6 +14,7 @@ import { report } from "./commands/report.js";
 import { resume } from "./commands/resume.js";
 import { run } from "./commands/run.js";
 import { scope } from "./commands/scope.js";
+import { stats } from "./commands/stats.js";
 import { status } from "./commands/status.js";
 import { ui } from "./commands/ui.js";
 import { unlock } from "./commands/unlock.js";
@@ -21,7 +22,7 @@ import { verify } from "./commands/verify.js";
 import { version } from "./commands/version.js";
 const normalize = (r) => typeof r === "string" ? { out: r, code: 0 } : r;
 export const COMMANDS = {
-    init, doctor, fleet, compile, scope, plan, run, status, resume, report, profile, ui, unlock, approve, beat, version, verify, eval: evalCommand,
+    init, doctor, fleet, compile, scope, plan, run, status, stats, resume, report, profile, ui, unlock, approve, beat, version, verify, eval: evalCommand,
 };
 const VERSION_FLAGS = new Set(["version", "--version", "-v"]);
 const HELP_CMDS = new Set(["help", "-h", "--help"]);
@@ -37,6 +38,7 @@ usage: tickmarkr <command>
   eval          run checked-in fixtures against every channel in isolated temp repos
   run           execute the graph (--concurrency N --driver auto|herdr|subprocess|orca --route-strict; orca runs only when named)
   status        live run state
+  stats         all-run channel delivery, red, rescue, author and reviewer statistics
   verify        run the gate battery standalone against merge-base(--base, HEAD)..HEAD — no daemon, one verdict (--base main --criteria <file> | --task <id> [--files <glob>] [--author adapter:model] [--no-review] [--json])
   resume <id>   continue a run from its journal
   report <id>   cost/quality report (--md for committable execution record)

package/dist/compile/collateral.d.ts

@@ -30,6 +30,22 @@ export declare function classifyScopeOffenders(taskId: string, hard: ReadonlyArr
  * Each line names the task id and at least one missing collateral test path.
  */
 export declare function collateralLints(tasks: ReadonlyArray<Pick<Task, "id" | "files">>, repoRoot: string): string[];
+/**
+ * Does every mention of `target` have an explicit, target-local READ relation?
+ *
+ * A `context:` entry grants READ authority and nothing else, so both blocking paths have to ask this
+ * before honouring one. Fail-closed by construction: every occurrence must match one of the narrow
+ * read forms below. Absence from a write-verb list is never evidence. Thus `ownedTable returns two`
+ * and the unlisted `ownedTable sorts the rows it already publishes` are refused, while an unrelated
+ * write in `the consumer adds a cache while reading ownedTable` does not revoke ownedTable's read
+ * authority. A target mentioned twice, once for reading and once ambiguously, is refused.
+ *
+ * This is intentionally a lexical representation rather than prose understanding. Keyed on NAMES:
+ * only the literal target is classified, so a dependency described conceptually stays invisible and
+ * an unfamiliar read phrasing stays refused. That closes the false-positive direction only; widen
+ * the affirmative grammar only with a control that goes red first.
+ */
+export declare function criterionReadsOnly(text: string, target: string): boolean;
 export declare function newDirectoryLints(tasks: ReadonlyArray<Pick<Task, "id" | "files">>, repoRoot: string): string[];
 /**
  * OBS-76 class: sweep src/ for out-of-scope source files that reference a symbol the acceptance
@@ -104,7 +120,7 @@ export declare function goalDensityErrors(tasks: ReadonlyArray<Pick<Task, "id" |
  * 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 declare function symbolOwnershipErrors(tasks: ReadonlyArray<Pick<Task, "id" | "files" | "acceptance">>, repoRoot: string): string[];
+export declare function symbolOwnershipErrors(tasks: ReadonlyArray<Pick<Task, "id" | "files" | "acceptance"> & Partial<Pick<Task, "context">>>, repoRoot: string): string[];
 /**
  * The participation half of the config — everything the review-policy rules read. `byShape` rides
  * along because `gates.byShape.<shape>.review: false` is a second, NON-monotone participation switch:
@@ -128,6 +144,11 @@ export declare function reviewParticipationErrors(tasks: ReadonlyArray<Pick<Task
  * 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.
  *
+ * The read declaration (`context:`) rides on this parameter, on the task objects themselves — the
+ * aggregator never infers it from the repo, the config, or a sibling task. It is OPTIONAL: a caller
+ * whose task objects carry no `context` gets byte-identical verdicts to the ones it got before the
+ * field existed, because an absent declaration grants no authority at all.
+ *
  * KNOWN GAP (R2 review, T6/T7 scope): the compile seam in src/compile/index.ts
  * (`enforceTaskUnitContract`) does not thread `compileSource`'s `root` argument into this call, so a
  * PROGRAMMATIC compile whose target repo differs from process.cwd() resolves the wrong root and can
@@ -138,4 +159,4 @@ export declare function reviewParticipationErrors(tasks: ReadonlyArray<Pick<Task
  * 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 declare function taskUnitContractErrors(tasks: ReadonlyArray<Pick<Task, "id" | "goal" | "files" | "deps" | "acceptance" | "shape">>, repoRoot?: string, review?: ReviewParticipation): string[];
+export declare function taskUnitContractErrors(tasks: ReadonlyArray<Pick<Task, "id" | "goal" | "files" | "deps" | "acceptance" | "shape"> & Partial<Pick<Task, "context">>>, repoRoot?: string, review?: ReviewParticipation): string[];

package/dist/compile/collateral.js

@@ -171,15 +171,95 @@ export function collateralLints(tasks, repoRoot) {
 // v1.53 T4 (OBS-76): needles are code-shaped tokens only (camelCase / snake_case) — plain prose
 // words never match, so prose-only criteria yield zero needles instead of alarm-fatigue noise.
 // ponytail: token heuristic, not AST symbol resolution — promote after a version of precision data.
-function criteriaSymbols(acceptance) {
-    const out = new Set();
+function criteriaSymbolTexts(acceptance) {
+    const out = new Map();
     for (const item of acceptance) {
-        for (const tok of renderAcceptanceItem(item).match(/\b[A-Za-z_][A-Za-z0-9_]*\b/g) ?? []) {
-            if (tok.includes("_") || /[a-z][A-Z]/.test(tok))
-                out.add(tok);
+        const text = renderAcceptanceItem(item);
+        for (const tok of text.match(/\b[A-Za-z_][A-Za-z0-9_]*\b/g) ?? []) {
+            if (!tok.includes("_") && !/[a-z][A-Z]/.test(tok))
+                continue;
+            const texts = out.get(tok) ?? [];
+            if (!texts.includes(text))
+                texts.push(text);
+            out.set(tok, texts);
         }
     }
-    return [...out].sort();
+    return out;
+}
+function criteriaSymbols(acceptance) {
+    return [...criteriaSymbolTexts(acceptance).keys()].sort();
+}
+// These are affirmative READ relations, not a list of things that are not writes. The distinction
+// is the fail-closed boundary: an unknown predicate never earns context[] authority. A target is
+// readable when it is the object of an explicit observation (`reading ownedTable`) or the subject
+// of an explicitly pre-existing state (`ownedTable already publishes`). An unqualified declarative
+// predicate (`ownedTable returns two rows`) is deliberately absent because it can demand a change.
+const DIRECT_READ_BEFORE = /\b(?:consult|consults|consulting|inspect|inspects|inspecting|read|reads|reading|reference|references|referencing)\s+(?:(?:the|an?)\s+)?(?:(?:current|existing|unchanged)\s+)?$/i;
+const PREEXISTING_STATE_AFTER = /^\s*(?:(?:and|or)\s+\S+\s+)*(?:(?:,\s*)?which\s+)?(?:already|currently)\s+(?:carries|carry|contains?|declares?|defines?|exposes?|holds?|owns?|provides?|publish|publishes|returns?|supplies|supply|yields?)\b/i;
+const PASSIVE_READ_AFTER = /^\s+(?:is|remains)\s+(?:read|referenced|unchanged|untouched|as[- ]is)\b/i;
+// Once a target-local read has been established, a same-clause continuation can revoke it. These
+// vetoes are structural rather than an attempted exhaustive list of write verbs: an action followed
+// by `it` / `them` / `the same ...` is target-directed but ambiguous, and a coordinated passive
+// participle inherits the target as its subject. Both therefore fail closed. The scan stops at an
+// actual sentence/clause boundary; a dot inside a later path is not one.
+const TARGET_ANAPHOR_AFTER_COORDINATOR = /\b(?:and|or|then|before|after|while)\b[^,;.!?\n]{0,80}\b(?:it|them|those|the\s+same(?:\s+[A-Za-z][A-Za-z0-9_-]*)?)\b/i;
+const TARGET_PASSIVE_AFTER_SUBJECT_READ = /\b(?:and|or|then|before|after)\s+(?:then\s+)?(?:(?:is|gets?|becomes?|being)\s+)?[A-Za-z]+(?:ed|en)\b/i;
+function sameClauseAfterTarget(after) {
+    const boundary = after.search(/[;!?\n]|\.(?=\s|$)/);
+    return boundary === -1 ? after : after.slice(0, boundary);
+}
+function targetOccurrences(text, target) {
+    if (!target)
+        return [];
+    const out = [];
+    const wordAtStart = /[A-Za-z0-9_]/.test(target[0]);
+    const wordAtEnd = /[A-Za-z0-9_]/.test(target[target.length - 1]);
+    for (let at = text.indexOf(target); at !== -1; at = text.indexOf(target, at + target.length)) {
+        const before = text[at - 1];
+        const after = text[at + target.length];
+        if (wordAtStart && before !== undefined && /[A-Za-z0-9_]/.test(before))
+            continue;
+        if (wordAtEnd && after !== undefined && /[A-Za-z0-9_]/.test(after))
+            continue;
+        out.push(at);
+    }
+    return out;
+}
+/**
+ * Does every mention of `target` have an explicit, target-local READ relation?
+ *
+ * A `context:` entry grants READ authority and nothing else, so both blocking paths have to ask this
+ * before honouring one. Fail-closed by construction: every occurrence must match one of the narrow
+ * read forms below. Absence from a write-verb list is never evidence. Thus `ownedTable returns two`
+ * and the unlisted `ownedTable sorts the rows it already publishes` are refused, while an unrelated
+ * write in `the consumer adds a cache while reading ownedTable` does not revoke ownedTable's read
+ * authority. A target mentioned twice, once for reading and once ambiguously, is refused.
+ *
+ * This is intentionally a lexical representation rather than prose understanding. Keyed on NAMES:
+ * only the literal target is classified, so a dependency described conceptually stays invisible and
+ * an unfamiliar read phrasing stays refused. That closes the false-positive direction only; widen
+ * the affirmative grammar only with a control that goes red first.
+ */
+export function criterionReadsOnly(text, target) {
+    const occurrences = targetOccurrences(text, target);
+    return occurrences.length > 0 && occurrences.every((at) => {
+        // Backticks quote the target, not the relation, so discard only the adjacent delimiters.
+        const before = text.slice(Math.max(0, at - 96), at).replace(/`$/, "");
+        const after = text.slice(at + target.length).replace(/^`/, "");
+        const preexisting = PREEXISTING_STATE_AFTER.exec(after);
+        const passive = PASSIVE_READ_AFTER.exec(after);
+        if (!DIRECT_READ_BEFORE.test(before) && !preexisting && !passive)
+            return false;
+        const clause = sameClauseAfterTarget(after);
+        if (TARGET_ANAPHOR_AFTER_COORDINATOR.test(clause))
+            return false;
+        // A subject-position read (`target is read` / `target already publishes`) leaves the target as
+        // the inherited subject of a coordinated passive: `... and then rewritten by the consumer` is
+        // a change demand, not a read. Object-position reads need the anaphor veto above instead.
+        const subjectRead = preexisting ?? passive;
+        return !subjectRead
+            || !TARGET_PASSIVE_AFTER_SUBJECT_READ.test(clause.slice(subjectRead[0].length));
+    });
 }
 const ARCH_PAGES = ["docs/codebase/ARCHITECTURE.md", "docs/codebase/STRUCTURE.md"];
 function topLevelSrcDir(file) {
@@ -519,8 +599,8 @@ function walkAllCode(repoRoot) {
  */
 export function symbolOwnershipErrors(tasks, repoRoot) {
     const perTask = tasks
-        .map((t) => ({ t, symbols: criteriaSymbols(t.acceptance ?? []) }))
-        .filter((x) => x.symbols.length);
+        .map((t) => ({ t, bySymbol: criteriaSymbolTexts(t.acceptance ?? []) }))
+        .filter((x) => x.bySymbol.size);
     if (!perTask.length)
         return [];
     const { files: codeFiles, unreadable } = walkAllCode(repoRoot);
@@ -531,7 +611,7 @@ export function symbolOwnershipErrors(tasks, repoRoot) {
     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 allSymbols = [...new Set(perTask.flatMap((x) => [...x.bySymbol.keys()]))];
     const res = new Map(allSymbols.map((s) => [s, definitionRe(s)]));
     const sites = new Map(allSymbols.map((s) => [s, []]));
     for (const cf of codeFiles) {
@@ -548,16 +628,46 @@ export function symbolOwnershipErrors(tasks, repoRoot) {
                 sites.get(sym).push(cf);
         }
     }
-    for (const { t, symbols } of perTask) {
+    for (const { t, bySymbol } of perTask) {
         // OBS-22: scopeGate accepts picomatch globs; ownership must agree.
         const scoped = filesGlob(t.files.map((f) => f.replace(/^\.\//, "")));
-        for (const sym of symbols) {
+        // THE RULE AT THIS SITE: a `context:`
+        // entry declares a path the worker may READ, so it answers "can the worker satisfy a criterion
+        // that only reads this symbol" (yes) and never "may the worker change it" (no — that authority
+        // comes from files[] alone). Hence the exemption is conditional on the criteria that actually
+        // name the symbol, and it is asked of the SYMBOL, not of the sentence: `criterionReadsOnly` fails
+        // closed, so a criterion demanding the symbol CHANGE — and any phrasing that does not prove it
+        // reads the symbol — is still refused, and still told to widen files[] where the change is what
+        // it asks for. An unrelated in-scope write does not change that per-symbol answer. Keyed on NAMES:
+        // only a path literally written in context[] is seen here, so a
+        // read dependency an author described in prose remains invisible to this lint. That closes the
+        // false-positive direction only — nothing here narrows what the rule refuses.
+        const declaredContext = (t.context ?? []).map((f) => f.replace(/^\.\//, ""));
+        const readable = declaredContext.length ? filesGlob(declaredContext) : () => false;
+        for (const [sym, texts] of bySymbol) {
             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
+            const writes = !texts.every((text) => criterionReadsOnly(text, sym));
+            if (readable(site) && !writes)
+                continue; // read authority is declared and read authority is all it needs
+            if (readable(site)) {
+                errors.push(`${t.id}: criterion identifier "${sym}" is defined only in ${site}, which is declared in `
+                    + `context[] but not in files[] — a context: entry grants READ authority only, and this `
+                    + `criterion requires changing "${sym}"; add ${site} to files[] or reword the criterion to `
+                    + `require only reading it (OBS-248).`);
+                continue;
+            }
+            if (!writes) {
+                errors.push(`${t.id}: criterion identifier "${sym}" is defined only in ${site}, which is in neither `
+                    + `files[] nor context[] — the criterion only reads "${sym}", so declare ${site} in `
+                    + `context[]; widening files[] would grant write authority this criterion never asks for `
+                    + `(OBS-248).`);
+                continue;
+            }
             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).`);
@@ -630,6 +740,11 @@ function activeReviewParticipation(repoRoot) {
  * 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.
  *
+ * The read declaration (`context:`) rides on this parameter, on the task objects themselves — the
+ * aggregator never infers it from the repo, the config, or a sibling task. It is OPTIONAL: a caller
+ * whose task objects carry no `context` gets byte-identical verdicts to the ones it got before the
+ * field existed, because an absent declaration grants no authority at all.
+ *
  * KNOWN GAP (R2 review, T6/T7 scope): the compile seam in src/compile/index.ts
  * (`enforceTaskUnitContract`) does not thread `compileSource`'s `root` argument into this call, so a
  * PROGRAMMATIC compile whose target repo differs from process.cwd() resolves the wrong root and can

package/dist/compile/native.js

@@ -4,6 +4,7 @@ import { basename, dirname, join, resolve } from "node:path";
 import { filesGlob } from "../graph/files-glob.js";
 import picomatch from "picomatch";
 import { GATE_NAMES, GRAPH_ROUTING_MODES, ORACLES, renderAcceptanceItem, SHAPES, TIERS, validateGraph, } from "../graph/schema.js";
+import { criterionReadsOnly } from "./collateral.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
@@ -169,20 +170,51 @@ function renderedObservables(text) {
 function criterionScopeFinding(task, text, criterion, id, tests) {
     if (task.files.length === 0)
         return undefined; // empty files[] is deliberately unrestricted
-    const inScope = filesGlob(task.files.map((entry) => entry.replace(/^\.\//, ""))); // Q120s shared matcher
+    const strip = (entry) => entry.replace(/^\.\//, ""); // Q120s shared matcher below
+    const inFiles = filesGlob(task.files.map(strip));
+    const context = (task.context ?? []).map(strip);
+    const inContext = context.length ? filesGlob(context) : () => false;
+    // THE RULE AT THIS SITE: `files:` clears a named path outright, because it is write authority and
+    // write authority covers reading too. `context:` clears one ONLY for a criterion that reads it and
+    // does not change it — a read declaration is not a second write surface, and unioning it in unconditionally
+    // would promote read authority to write authority for exactly the criterion that asks for the
+    // change. The question is asked per PATH — each occurrence of each declared path must carry its own
+    // affirmative read relation. A write elsewhere in the criterion therefore cannot revoke a named
+    // dependency's read exemption, and a read elsewhere cannot confer one on a path being changed. It
+    // is the same target-specific question the symbol-ownership rule asks (collateral.ts), and it fails
+    // closed: any phrasing that does not prove the criterion reads the path is refused, as it was before
+    // this check consulted the declaration at all. Keyed on NAMES: only a path literally written in files[]
+    // or context[] is matched, so a dependency the author described conceptually and never wrote out
+    // stays invisible to this check. That closes the false-positive direction only — a path in neither
+    // declaration is refused exactly as before.
+    const declared = (path) => inFiles(path) || (inContext(path) && criterionReadsOnly(text, path));
     const named = namedCriterionPaths(text, tests);
     const { exact, denominators } = renderedObservables(text);
     const asserting = tests.filter((test) => exact.some((token) => test.text.includes(token))
         || denominators.some((denominator) => new RegExp(`(?:^|\\D)\\d+/${denominator}(?:\\D|$)`).test(test.text))).map((test) => test.path);
-    const missing = [...new Set([...named, ...asserting])].filter((path) => !inScope(path));
+    const missing = [...new Set([...named, ...asserting])].filter((path) => !declared(path));
     if (missing.length === 0)
         return undefined;
+    // The remedy names the authority the criterion actually needs. A criterion that only READS the
+    // producer is repaired by context[]; instructing its author to widen files[] is the product
+    // emitting the unsafe workaround itself. Only a criterion that requires CHANGING the producer is
+    // told to widen the write surface.
+    const readMissing = missing.filter((path) => criterionReadsOnly(text, path));
+    const writeMissing = missing.filter((path) => !criterionReadsOnly(text, path));
+    const remedy = [
+        readMissing.length === 0 ? "" : `the criterion only reads ${readMissing.length === 1 ? "it" : "them"} `
+            + `(${readMissing.join(", ")}), so add ${readMissing.length === 1 ? "it" : "them"} to context[] — `
+            + `files[] would grant write authority this criterion never asks for`,
+        writeMissing.length === 0 ? "" : `the criterion requires changing ${writeMissing.length === 1 ? "it" : "them"} `
+            + `(or does not establish a read-only relation) (${writeMissing.join(", ")}), so add `
+            + `${writeMissing.length === 1 ? "it" : "them"} to files[]`,
+    ].filter(Boolean).join("; ");
     return {
         code: "criterion-scope",
         fixtureId: id,
         taskId: task.id,
         criterion,
-        detail: `criterion names asserting file${missing.length === 1 ? "" : "s"} outside expanded files[]: ${missing.join(", ")}`,
+        detail: `criterion names asserting file${missing.length === 1 ? "" : "s"} outside expanded files[] and context[]: ${missing.join(", ")} — ${remedy}`,
     };
 }
 function exportedIdentifier(root, files, identifier) {