toolroll 0.9.55 → 0.9.57

package/dist/subscription-chat.js

@@ -1,5 +1,5 @@
 /**
- * Subscription-backed transport for the mate.
+ * Subscription-backed transport for the lead.
  *
  * The direct API transport owns dollar reservations and native function
  * calls. A cached Codex or Claude login has neither an API key nor a
@@ -7,16 +7,16 @@
  * temporary directory and asks for the same tool-call envelope as strict
  * structured JSON. The harness receives no repository path, no project
  * instructions, no MCP servers, and no executable tool surface. Tool calls
- * are still interpreted and executed by mate.ts, where every act remains a
+ * are still interpreted and executed by lead.ts, where every act remains a
  * proposal that needs a human confirmation card.
  */
 import { Buffer } from "node:buffer";
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { MATE_MAX_CALLS_PER_STEP, MATE_STEP_TEXT_CAP_BYTES, MATE_TOOL_CALL_CAP_BYTES, MATE_TOOL_CALL_ID_CAP_BYTES, strictJsonParse, tokenCount, } from "./converse.js";
+import { LEAD_MAX_CALLS_PER_STEP, LEAD_STEP_TEXT_CAP_BYTES, LEAD_TOOL_CALL_CAP_BYTES, LEAD_TOOL_CALL_ID_CAP_BYTES, strictJsonParse, tokenCount, } from "./converse.js";
 import { run } from "./exec.js";
-import { claudeStreamReader } from "./mate-progress.js";
+import { claudeStreamReader } from "./lead-progress.js";
 import { ALL_CREDENTIAL_ENV } from "./provider.js";
 import { claudeLimitsOf, noteLimits } from "./provider-limits.js";
 import { claudeBillingFrom } from "./spend.js";
@@ -25,18 +25,18 @@ function outputSchema(tools) {
     return {
         type: "object",
         properties: {
-            text: { type: "string", maxLength: MATE_STEP_TEXT_CAP_BYTES },
+            text: { type: "string", maxLength: LEAD_STEP_TEXT_CAP_BYTES },
             // With no tools offered there is nothing to name: an empty enum is not
             // a valid schema, so the calls array is simply required to be empty.
             calls: tools.length === 0 ? { type: "array", maxItems: 0 } : {
                 type: "array",
-                maxItems: MATE_MAX_CALLS_PER_STEP,
+                maxItems: LEAD_MAX_CALLS_PER_STEP,
                 items: {
                     type: "object",
                     properties: {
-                        id: { type: "string", minLength: 1, maxLength: MATE_TOOL_CALL_ID_CAP_BYTES },
+                        id: { type: "string", minLength: 1, maxLength: LEAD_TOOL_CALL_ID_CAP_BYTES },
                         name: { type: "string", enum: tools.map(tool => tool.name) },
-                        argumentsJson: { type: "string", maxLength: MATE_TOOL_CALL_CAP_BYTES },
+                        argumentsJson: { type: "string", maxLength: LEAD_TOOL_CALL_CAP_BYTES },
                     },
                     required: ["id", "name", "argumentsJson"],
                     additionalProperties: false,
@@ -47,8 +47,8 @@ function outputSchema(tools) {
         additionalProperties: false,
     };
 }
-/** The model-visible request. Tool results are already redacted by mateView. */
-export function composeSubscriptionMatePrompt(request) {
+/** The model-visible request. Tool results are already redacted by leadView. */
+export function composeSubscriptionLeadPrompt(request) {
     return [
         request.system,
         "SUBSCRIPTION HARNESS PROTOCOL:",
@@ -68,7 +68,7 @@ function exactKeys(value, keys) {
     return actual.length === keys.length && [...keys].sort().every((key, index) => actual[index] === key);
 }
 /** Strictly turn the harness's structured output into the provider-neutral answer. */
-export function parseSubscriptionMateAnswer(text, usage = {}) {
+export function parseSubscriptionLeadAnswer(text, usage = {}) {
     const parsed = strictJsonParse(Buffer.from(text, "utf8"), RESPONSE_CAP_BYTES, 8);
     if (!parsed.ok || typeof parsed.value !== "object" || parsed.value === null || Array.isArray(parsed.value)) {
         return { ok: false, problem: parsed.ok ? "not-an-object" : parsed.problem };
@@ -77,7 +77,7 @@ export function parseSubscriptionMateAnswer(text, usage = {}) {
     if (!exactKeys(body, ["text", "calls"]) || typeof body["text"] !== "string" || !Array.isArray(body["calls"])) {
         return { ok: false, problem: "wrong-shape" };
     }
-    if (Buffer.byteLength(body["text"], "utf8") > MATE_STEP_TEXT_CAP_BYTES || body["calls"].length > MATE_MAX_CALLS_PER_STEP) {
+    if (Buffer.byteLength(body["text"], "utf8") > LEAD_STEP_TEXT_CAP_BYTES || body["calls"].length > LEAD_MAX_CALLS_PER_STEP) {
         return { ok: false, problem: "over-cap" };
     }
     const calls = [];
@@ -87,20 +87,20 @@ export function parseSubscriptionMateAnswer(text, usage = {}) {
         const call = raw;
         if (!exactKeys(call, ["id", "name", "argumentsJson"]))
             return { ok: false, problem: "bad-tool-call" };
-        if (typeof call["id"] !== "string" || call["id"] === "" || Buffer.byteLength(call["id"], "utf8") > MATE_TOOL_CALL_ID_CAP_BYTES) {
+        if (typeof call["id"] !== "string" || call["id"] === "" || Buffer.byteLength(call["id"], "utf8") > LEAD_TOOL_CALL_ID_CAP_BYTES) {
             return { ok: false, problem: "bad-tool-call" };
         }
         if (typeof call["name"] !== "string" || call["name"] === "" || call["name"].length > 64 || typeof call["argumentsJson"] !== "string") {
             return { ok: false, problem: "bad-tool-call" };
         }
         const argumentsBytes = Buffer.from(call["argumentsJson"], "utf8");
-        if (argumentsBytes.byteLength > MATE_TOOL_CALL_CAP_BYTES)
+        if (argumentsBytes.byteLength > LEAD_TOOL_CALL_CAP_BYTES)
             return { ok: false, problem: "bad-tool-call" };
-        const args = strictJsonParse(argumentsBytes, MATE_TOOL_CALL_CAP_BYTES, 6);
+        const args = strictJsonParse(argumentsBytes, LEAD_TOOL_CALL_CAP_BYTES, 6);
         if (!args.ok || typeof args.value !== "object" || args.value === null || Array.isArray(args.value))
             return { ok: false, problem: "bad-tool-call" };
         const normalized = { id: call["id"], name: call["name"], args: args.value };
-        if (Buffer.byteLength(JSON.stringify(normalized), "utf8") > MATE_TOOL_CALL_CAP_BYTES)
+        if (Buffer.byteLength(JSON.stringify(normalized), "utf8") > LEAD_TOOL_CALL_CAP_BYTES)
             return { ok: false, problem: "bad-tool-call" };
         calls.push(normalized);
     }
@@ -186,10 +186,10 @@ function lastResultLine(stdout) {
     return "";
 }
 /** Production runner; injectable so tests never consume a subscription turn. */
-export async function performSubscriptionMateRequest(request, runner = run) {
+export async function performSubscriptionLeadRequest(request, runner = run) {
     const dir = mkdtempSync(join(tmpdir(), "standing-orders-mate-"));
     try {
-        const prompt = composeSubscriptionMatePrompt(request);
+        const prompt = composeSubscriptionLeadPrompt(request);
         const streaming = request.provider !== "codex-subscription" && request.onText !== undefined;
         const schema = request.outputSchema ?? outputSchema(request.tools);
         let command;
@@ -274,7 +274,7 @@ export async function performSubscriptionMateRequest(request, runner = run) {
         if (request.outputSchema !== undefined) {
             return { ok: true, answer: { text: output.text, calls: [], tokensIn: output.tokensIn, tokensOut: output.tokensOut, reportedCostMicrousd: null } };
         }
-        return parseSubscriptionMateAnswer(output.text, output);
+        return parseSubscriptionLeadAnswer(output.text, output);
     }
     finally {
         rmSync(dir, { recursive: true, force: true });

package/dist/surface.d.ts

@@ -1,10 +1,27 @@
+/**
+ * The declared command guide (arc 5): the agent-facing surface as data,
+ * dumped by `contract --commands`. This is DOCUMENTATION with a stable
+ * shape, not authority — legacy verbs do not execute from it,
+ * and the runtime envelope remains the truth. Its honest limits ride the
+ * envelope itself as SURFACE_NOTES, because a source comment is invisible
+ * to consumers (arc-5 review, finding 1).
+ *
+ * What the tests DO hold to the code: every root here is a routed verb
+ * and every routed verb appears here; every declared flag lives in the
+ * parser's global vocabulary with the declared arity; the subcommand
+ * inventories for task/publish/config/approver match the
+ * exported action lists their dispatchers consult; keyed mutations
+ * declare --key; notableReasons come from DOCUMENTED_REASONS. What they
+ * CANNOT prove — that a given flag is read by a given handler — is why
+ * SURFACE_NOTES.flags says "intended".
+ */
 import { type CommandFlag, type CommandRow, type RemotePolicy } from './contracts/cli.js';
 /** A guide row and its flags are derived from their schemas in src/contracts/cli.ts. */
 export type { CommandFlag, CommandRow, RemotePolicy };
 /** The guide's limits, stated machine-readably in every dump. */
 export declare const SURFACE_NOTES: {
-    readonly authority: "documentation is not permission; session descriptors also drive parser and request validation; legacy entries remain advisory";
-    readonly flags: "session flags are exact per operation; legacy flags are intended per command and may use a global parser vocabulary";
+    readonly authority: "documentation is not permission; legacy entries remain advisory";
+    readonly flags: "flags are intended per command and may use a global parser vocabulary";
     readonly reasons: "curated, not exhaustive — the runtime `reason` field is the truth; ignore tokens you do not recognize";
     readonly database: "local database commands wait up to 15 seconds for another writer; an exhausted wait returns database-busy and names the selected file";
 };

package/dist/surface.js

@@ -19,13 +19,11 @@ import { FLOWS_DESCRIPTORS } from "./flows-cli.js";
  * CANNOT prove — that a given flag is read by a given handler — is why
  * SURFACE_NOTES.flags says "intended".
  */
-import { SESSION_DESCRIPTORS } from './session-contract.js';
-import { sessionCliFlags } from './session-cli.js';
 import { commandEntries } from './contracts/cli.js';
 /** The guide's limits, stated machine-readably in every dump. */
 export const SURFACE_NOTES = {
-    authority: "documentation is not permission; session descriptors also drive parser and request validation; legacy entries remain advisory",
-    flags: "session flags are exact per operation; legacy flags are intended per command and may use a global parser vocabulary",
+    authority: "documentation is not permission; legacy entries remain advisory",
+    flags: "flags are intended per command and may use a global parser vocabulary",
     reasons: "curated, not exhaustive — the runtime `reason` field is the truth; ignore tokens you do not recognize",
     database: "local database commands wait up to 15 seconds for another writer; an exhausted wait returns database-busy and names the selected file",
 };
@@ -66,22 +64,9 @@ const GUIDE_ROWS = [
     { invocation: "graph", synopsis: "report which work graph is already here", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag] },
     { invocation: "repos", synopsis: "list connected repositories", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag] },
     operator("proposals", "what coordinators proposed over the MCP gateway — list, confirm <id> [--yes], dismiss <id>; confirming runs the plane's own door under your password"),
-    operator("chat", "with a saved profile, --lead <id> --conversation <id> opens central chat; --say sends one message, --follow only reads updates, --authorize --terms-digest enables the displayed paid terms; --local uses the existing local coordinator, where --follow enables crew updates and --no-follow pauses them; proposals keep their approval requirements"),
-    operator('connect', 'save an authenticated central HTTPS profile with --as and --token-stdin or --token-file; --local-login explicitly uses the existing private local sign-in; secrets never belong in arguments or URLs'),
-    operatorRead('lead list', 'list central leads available to the signed-in account; --profile selects a saved connection'),
-    operator('lead create', 'create a central lead with --name, --instructions and repeatable --project paths admitted by the server'),
-    operator('lead update', 'change --name, --instructions or --status for --lead at --revision; projects remain fixed'),
-    operator('lead member', 'set --account membership on --lead with --role, --active true|false and the current --revision'),
-    operator('lead transfer', 'move ownership of --task to --lead at --revision; existing execution authority remains unchanged'),
-    operatorRead('conversation list', 'list admitted conversations, optionally within --lead; attachment never starts model work'),
-    operator('conversation create', 'create a conversation with --lead, --title, --visibility private|team and repeatable --project paths'),
-    operatorRead('conversation show', 'read --conversation messages and saved work; no model call or read-marker mutation'),
-    operator('conversation member', 'set --account membership on --conversation with --role, --active true|false and the current --revision; lead membership must already permit the role'),
-    operator('conversation edit', 'edit your queued --message in --conversation at --revision using --text; running messages cannot be edited'),
-    operator('conversation withdraw', 'withdraw your queued --message in --conversation at --revision; an active turn requires stop'),
-    operator('conversation read', 'explicitly record your read position at --message within --conversation'),
-    operator('conversation follow', 'enable or pause automatic lead summaries with --conversation and --enabled true|false, within the existing paid chat authorization; passive chat --follow only reads updates'),
-    operator('conversation stop', 'request stopping the exact --message in --conversation; retain uncertain work until its owner settles it'),
+    // D5: the central team service (connect, the central lead verbs, conversation …) and native coding sessions are
+    // deprecated: they still run this release, with a warning, but are no longer declared here.
+    operator("chat", "talk to your lead: one conversation across every project; --say sends one message; --follow enables crew updates and --no-follow pauses them; proposals keep their approval requirements"),
     { invocation: "repos add", synopsis: "add a project: a Git repository, in the console at once; the lead adds with its token", audience: "agent", agentMayInvoke: true, mutation: "identity-idempotent",
         positionals: [{ name: "path", required: false, meaning: "the repository (default: the one you are in)" }],
         flags: [jsonFlag, { name: "token", takesValue: true, meaning: "the lead token (or TOOLROLL_LEAD_TOKEN)" }],
@@ -126,12 +111,6 @@ const GUIDE_ROWS = [
             { name: "yes", takesValue: false, meaning: "with --release-gate: lift that one pause once it is proved" }],
         notableReasons: ["usage", "ambiguous", "drift", "timeout", "check-failed", "ci-failed", "tree-mismatch", "conflict", "mixed-runtime", "gate-held", "after-swap"] },
     operator("demo", "a seeded throwaway sandbox"),
-    { invocation: 'session capabilities', synopsis: 'Show executable session schemas and operator authority requirements; no credentials needed', audience: 'agent', agentMayInvoke: true, mutation: 'none', flags: [jsonFlag] },
-    ...SESSION_DESCRIPTORS.map(spec => ({
-        invocation: `session ${spec.operation}`, synopsis: spec.synopsis, audience: spec.audience, agentMayInvoke: spec.agentMayInvoke,
-        mutation: spec.mutation ? 'keyed' : 'none', inputSchema: spec.inputSchema,
-        flags: Object.entries(sessionCliFlags(spec)).map(([name, arity]) => ({ name, takesValue: arity === 'value', meaning: name === 'key' ? 'keep the same key when reconciling; inspect after unknown delivery, never blind-retry' : `see session ${spec.operation} --help` })),
-    })),
     ...KNOWLEDGE_DESCRIPTORS.map(spec => ({ invocation: `knowledge ${spec.action}`, synopsis: spec.synopsis, audience: "audience" in spec ? spec.audience : "agent", agentMayInvoke: !("audience" in spec), mutation: spec.mutation, flags: spec.flags, ...(spec.takesQuery ? { positionals: [{ name: "query", required: true, meaning: "search text or source file for impact" }] } : {}) })),
     ...MEMORY_DESCRIPTORS.map(spec => ({ invocation: `memory ${spec.action}`, synopsis: spec.synopsis, audience: "agent", agentMayInvoke: true, mutation: spec.mutation, flags: spec.flags, ...(spec.takesQuery ? { positionals: [{ name: "query", required: true, meaning: "search text, a decision id, or the decision sentence" }] } : {}) })),
     // Flow writes carry an approver's credential: an agent runs them only as the person asked, after showing the preview.
@@ -144,7 +123,7 @@ const GUIDE_ROWS = [
     { invocation: "integrations", synopsis: "every integration as Connected, Not set up or Broken, with its last success and error, what uses it and what to do; --saved skips new checks; never a secret", audience: "agent", agentMayInvoke: true, mutation: "none",
         flags: [jsonFlag, dbFlag, { name: "saved", takesValue: false, meaning: "show the last checks without checking again" }] },
     { invocation: "ready", synopsis: "what could be dispatched right now (rows carry reservedFor)", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
-    { invocation: "brief", synopsis: "with a saved central profile, --lead <id> --conversation <id> reads messages, proposals and saved work; --request-id inspects your saved receipt without resending; --local uses local DB catch-up, where --history selects the older operational report", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
+    { invocation: "brief", synopsis: "the lead's catch-up from the local database; --history selects the older operational report", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
     { invocation: "gaps", synopsis: "requirement gaps blocking dispatch", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag, repoFlag] },
     { invocation: "grants", synopsis: "list authority grants", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
     { invocation: "audit", synopsis: "what people did on this server with their API tokens, newest first: when, who, which token, from the CLI (api) or an agent (mcp), the command or tool, the project and the outcome (ok, refused, error); an approver sees everyone in their projects, anyone else only themselves",
@@ -439,10 +418,7 @@ const GUIDE_ROWS = [
 const REMOTE_NO = [
     // Answered by the local CLI, or a client of a central server itself.
     "", "pulls", "graph", "repos", "repos add", "repos remove", "repos add-from-github", "contract", "skills list", "skills get", "skills install",
-    "link", "unlink", "update", "release", "demo", "chat", "connect", "lead list", "lead create", "lead update", "lead member", "lead transfer",
-    "conversation list", "conversation create", "conversation show", "conversation member", "conversation edit", "conversation withdraw",
-    "conversation read", "conversation follow", "conversation stop",
-    "session capabilities", "session list", "session show", "session changes", "session start", "session send", "session stop", "session resume", "session recover",
+    "link", "unlink", "update", "release", "demo", "chat",
     // This machine's checkout, saved profile, credentials and catch-up.
     "project show", "project use", "brief", "lead token", "lead say", "health",
     "assignment show", "assignment updates", "assignment claim", "assignment check", "assignment brief", "assignment inbox", "assignment ack",

package/dist/task-outcome-cli.js

@@ -82,7 +82,9 @@ export async function runTaskOutcomeCommand(action, positional, flags, context)
             if (!changed.ok)
                 return emit(changed);
             const assignment = 'body' in changed ? changed.body : changed.assignment;
-            return emit({ ok: true, result: assignment }, [`${current.rootId} · Complete`, `Result: ${current.activeTaskId} · run ${current.receipt.runId} · ${current.receipt.head ?? 'no commit'}`, current.receipt.checks.detail]);
+            // Checks deliberately Off: nothing to say about them here.
+            return emit({ ok: true, result: assignment }, [`${current.rootId} · Complete`, `Result: ${current.activeTaskId} · run ${current.receipt.runId} · ${current.receipt.head ?? 'no commit'}`,
+                ...(current.readiness?.checksOff ? [] : [current.receipt.checks.detail])]);
         }
         const feedback = flags.get('feedback'), runFlag = flags.get('run'), sourceFlag = flags.get('source'), keyFlag = flags.get('key');
         if (typeof feedback !== 'string' || !feedback.trim())

package/dist/task-status.d.ts

@@ -56,6 +56,24 @@ export type ChecksFact = {
     running?: "quick" | "full" | null;
     /** A batch check (batch-checks.ts): waiting for its batch, or how it was checked. */
     batch?: ChecksBatch | null;
+    /** Off: the passing full release check whose commit contains this one (release-coverage.ts), read at read time. */
+    release?: {
+        run: number;
+        head: string;
+    } | null;
+};
+/** What checks Off leaves for a release: `pending` until a passing full release check contains the commit, then
+ * `covered`. `running`: a check is waiting for its batch or running on this commit. */
+export type ReleaseState = "pending" | "covered" | "running";
+export declare const CHECKED_AT_RELEASE = "Checked at release";
+export declare function releaseStateOf(checks: Pick<ChecksFact, "status" | "level" | "release"> | null | undefined): ReleaseState | undefined;
+/** How the project check stands for requirements that rest on it, read now: `covered` once a check passed on this
+ * commit (its own, a follow-up, or a release check containing it), `pending` while checks Off wait for a release. */
+export declare function checkBackingOf(checks: Pick<ChecksFact, "status" | "level" | "release" | "running" | "batch"> | null | undefined): ReleaseState | undefined;
+/** What stands between a finished result and Complete (`completionBlockersOf`): each with the exact next step. */
+export type CompletionBlocker = {
+    key: "check-failed" | "check-missing" | "criteria" | "high";
+    message: string;
 };
 /** `waiting`: the result waits to be checked with others. Otherwise how its check ran: `together` on the
  * temporary batch commit `tested` with `peers`; `split` (its batch failed), `conflict` or `alone` on its own commit. */
@@ -94,14 +112,22 @@ export type TaskStatusFacts = {
     checks?: ChecksFact | null;
     pullRequest?: PullRequestFact | null;
     /** `unverified`: the report is refuted, so no requirement counts as met however it was marked. `missed`: the ones it
-     * failed or left unanswered. */
+     * failed or left unanswered. `atRelease`: checks Off, waiting for a release check. `unshown`: a required screenshot
+     * is missing. `ask`: what a person is asked to look at first (a requirement they check, or a missing screenshot). */
     requirements?: {
         met: number;
         total: number;
         yours: number;
         missed?: number;
         unverified?: boolean;
+        atRelease?: number;
+        unshown?: number;
+        ask?: string | null;
     } | null;
+    /** A person accepted this result's proof: their own check and a recorded exception need nothing more. */
+    accepted?: boolean;
+    /** What refuses Complete (`completionBlockersOf`); the first one is the sentence when it holds the result back. */
+    blockers?: readonly CompletionBlocker[];
     evidence?: {
         shortened: number;
         missing: number;
@@ -124,11 +150,14 @@ export type TaskStatusFacts = {
     /** What the person calls their lead (Settings → Lead); "Lead" when unnamed. */
     leadName?: string;
 };
-export declare function headlineOf(facts: Pick<TaskStatusFacts, "stage" | "checks" | "report">): Headline;
+export declare function headlineOf(facts: Pick<TaskStatusFacts, "stage" | "checks" | "report" | "requirements" | "accepted" | "blockers">): Headline;
 /** What the lead's claim says, in place of "waits for you" (lead-voice.ts). */
 export declare const leadOnIt: (name?: string) => string;
 export declare const leadLapsed: (name?: string) => string;
-export declare function taskStatusOf(facts: TaskStatusFacts): TaskStatus;
+/** The one status every surface shows (console list, task and result pages, CLI, chat, phone, `status`). */
+export declare function statusOf(facts: TaskStatusFacts): TaskStatus;
+/** The name most surfaces already import. */
+export declare const taskStatusOf: typeof statusOf;
 export declare function plainReasonOf(stage: TaskStage, code: string, detail: string | null | undefined): string | null;
 export declare function stageOfCode(code: string, options?: {
     needsPerson?: boolean;
@@ -165,18 +194,41 @@ export declare function assignmentStageOf(assignment: Pick<AssignmentSnapshot, "
     wait?: WaitKey;
 };
 type RequirementRow = {
+    id?: string;
+    statement?: string;
     state: string;
+    requiredEvidence?: readonly string[];
+    answered?: readonly {
+        kind: string;
+    }[];
+    detail?: readonly string[];
     assessment?: {
         evidenceState?: string;
+        detail?: readonly string[];
     } | undefined;
     review?: unknown;
 };
 /** One requirement's state in words: the card's Requirements row and the Checks tab read this one source, so they
- * can't disagree. A refuted report verifies none of its requirements, so each reads Unverified, as the card does. */
-export type RequirementWord = "Met" | "You check" | "Not shown yet" | "Not met" | "Unverified";
-export declare function requirementWordOf(row: RequirementRow, verdict?: string | null): RequirementWord;
+ * can't disagree. A refuted report verifies none of its requirements, so each reads Unverified, as the card does.
+ * With checks Off, a requirement that waits only on the check reads Checked at release, then Met once a passing full
+ * release check contains the commit. */
+export type RequirementWord = "Met" | "You check" | "Not shown yet" | "Checked at release" | "Waiting for checks" | "Not met" | "Unverified";
+export declare function requirementWordOf(row: RequirementRow, verdict?: string | null, release?: ReleaseState): RequirementWord;
 /** Requirements from the stored matrix: met, the ones only a person confirms, and the total. */
-export declare function requirementsOf(matrix: readonly RequirementRow[] | null | undefined): NonNullable<TaskStatusFacts["requirements"]> | null;
+export declare function requirementsOf(matrix: readonly RequirementRow[] | null | undefined, release?: ReleaseState): NonNullable<TaskStatusFacts["requirements"]> | null;
+/** What refuses Complete, for `task complete`, the console and chat completion and deploy-candidate alike: a failed
+ * check; a required check that is missing (checks deliberately Off are not missing: they are checked at release);
+ * an unresolved requirement (a person's own check is theirs to give by completing; a recorded acceptance resolves
+ * the rest); an unresolved HIGH review finding. A release check that covers the commit counts as passed. */
+export declare function completionBlockersOf(f: {
+    report: boolean;
+    checks: Pick<ChecksFact, "status" | "exitCode" | "level" | "release" | "running" | "batch"> | null;
+    checkRequired: boolean;
+    matrix: readonly RequirementRow[] | null | undefined;
+    verdict: string | null | undefined;
+    accepted: boolean;
+    high: number;
+}): CompletionBlocker[];
 /** A refuted report verifies none of its requirements, whatever it marked met (a person's acceptance doesn't change that). */
 export declare function unverifiedWhenRefuted(requirements: NonNullable<TaskStatusFacts["requirements"]> | null, verdict: string | null | undefined): NonNullable<TaskStatusFacts["requirements"]> | null;
 /** Saved evidence health from the receipt's artifact list and its caveats. */

package/dist/task-status.js

@@ -27,6 +27,17 @@ export const CHECKS_LABEL = "Project checks";
 export const PR_CI_LABEL = "PR CI";
 /** The one verb for opening a saved result, on every surface. */
 export const OPEN_RESULT = "Open result";
+export const CHECKED_AT_RELEASE = "Checked at release";
+export function releaseStateOf(checks) {
+    if (checks?.level !== "off" || checks.status === "passed" || checks.status === "failed")
+        return undefined;
+    return checks.release != null ? "covered" : "pending";
+}
+/** How the project check stands for requirements that rest on it, read now: `covered` once a check passed on this
+ * commit (its own, a follow-up, or a release check containing it), `pending` while checks Off wait for a release. */
+export function checkBackingOf(checks) {
+    return checks?.status === "passed" ? "covered" : checksUnderway(checks) ? "running" : releaseStateOf(checks);
+}
 /** "T2", "T2 and T3", "T2, T3 and 2 more": short enough for one line. The full list is on the result. */
 export function peerWords(peers, shown = 2) {
     if (peers.length <= shown)
@@ -43,6 +54,23 @@ const BATCH_WHY = {
     conflict: "It conflicted with another result when merged for a batch check, so it was checked on its own.",
 };
 const short = (sha) => sha !== null && /^[a-f0-9]{7,40}$/.test(sha) ? sha.slice(0, 7) : null;
+/** A check waiting for its batch or running on this commit: the result reads Ready meanwhile, not Needs you. */
+const checksUnderway = (checks) => checks?.batch?.state === "waiting" || checks?.running != null;
+/** A finished result a person still has to act on before it can be complete: an unresolved HIGH finding or unmet
+ * requirement, a missing check, or a requirement only they can confirm. Failed checks read Failed instead. */
+function resultAsk(facts) {
+    if (facts.report || facts.checks?.status === "failed")
+        return null;
+    const blocker = facts.blockers?.find(one => one.key !== "check-failed" && !(one.key === "check-missing" && checksUnderway(facts.checks)));
+    if (blocker !== undefined)
+        return blocker.message;
+    const req = facts.requirements;
+    if (req == null || facts.accepted === true || req.unverified === true)
+        return null;
+    if ((req.yours > 0 || (req.unshown ?? 0) > 0) && req.ask != null)
+        return req.ask;
+    return null;
+}
 export function headlineOf(facts) {
     switch (facts.stage) {
         case "queued": return "Queued";
@@ -57,7 +85,10 @@ export function headlineOf(facts) {
                 return "Ready for review";
             if (facts.checks?.status === "failed")
                 return "Failed";
-            // Off: ready like any build; the sentence and the Checks row say no check ran.
+            // A requirement a person checks, a missing screenshot, an unmet requirement or a HIGH finding: Needs you, with the ask.
+            if (resultAsk(facts) !== null)
+                return "Needs you";
+            // Off: ready like any build; the sentence and the Checks row say it is checked at release.
             return "Ready for review";
         case "complete": return "Complete";
         case "failed": return "Failed";
@@ -71,15 +102,17 @@ function sentenceOf(headline, facts) {
         case "Queued": return reason ?? "Waiting for a worker.";
         case "Planning": return reason ?? "The lead is writing the plan.";
         // One plain sentence per need (needs-you.ts); a recorded reason only where the need keeps one.
-        case "Needs you": return needSentence(facts.need ?? "other", reason, facts.needContext);
+        case "Needs you": return facts.stage === "finished" ? resultAsk(facts) ?? needSentence("review-result", reason, facts.needContext) : needSentence(facts.need ?? "other", reason, facts.needContext);
         case "Waiting": return waitSentence(facts.wait, reason, facts.needContext);
         case "Building": return facts.stage === "checking" ? "Checks are running on the change."
             : facts.stage === "reviewing" ? "Reviewing the change before it reaches you." : reason ?? "An agent is working on it.";
         case "Ready for review":
             if (facts.report)
                 return "The report is ready to read. Read it, then mark it complete.";
+            if (releaseStateOf(facts.checks) === "covered")
+                return `Checked at release on ${short(facts.checks.release.head) ?? "its release"}. Review the change, then mark it complete.`;
             if (facts.checks?.level === "off" && facts.checks.status !== "passed")
-                return "Checks are off for this project. Review the change, then mark it complete.";
+                return "Checked at release. Review the change, then mark it complete.";
             if (facts.checks?.status === "passed") {
                 // The Checks row names the others and the batch commit; the sentence doesn't repeat them.
                 const peers = facts.checks.batch?.state === "together" ? facts.checks.batch.peers.length : 0;
@@ -135,8 +168,10 @@ function detailsOf(headline, facts) {
             row("checks", CHECKS_LABEL, `${quick ? "Quick checks failed" : "Failed"}${checks.exitCode === null ? "" : ` (exit ${checks.exitCode})`}`, problem(headline), headline === "Failed" ? { href: checksHref } : { action: { label: "See what failed", href: checksHref } });
         else if (checks.status === "running")
             row("checks", CHECKS_LABEL, "Running", "running");
+        else if (checks.level === "off" && checks.release != null)
+            row("checks", CHECKS_LABEL, `Passed at release on ${short(checks.release.head) ?? `build #${checks.release.run}`}`, "ok", { href: checksHref });
         else if (checks.level === "off")
-            row("checks", CHECKS_LABEL, "Off for this project", "none", runChecks === null ? {} : { action: runChecks });
+            row("checks", CHECKS_LABEL, CHECKED_AT_RELEASE, "none", runChecks === null ? {} : { action: runChecks });
         else if (checks.status === "not-run")
             row("checks", CHECKS_LABEL, "Didn't run", "none", runChecks === null ? {} : { action: runChecks });
         // A saved check that can't be read is run again where that is possible.
@@ -173,8 +208,9 @@ function detailsOf(headline, facts) {
     else if (req != null && req.total > 0 && req.unverified === true)
         row("requirements", "Requirements", "Unverified", "none");
     else if (req != null && req.total > 0) {
-        const unmet = req.total - req.met - req.yours;
-        const text = `${req.met} of ${req.total} met${req.yours > 0 ? ` · You check ${req.yours}` : ""}`;
+        const atRelease = req.atRelease ?? 0;
+        const unmet = req.total - req.met - req.yours - atRelease;
+        const text = `${req.met} of ${req.total} met${atRelease > 0 ? ` · ${atRelease} at release` : ""}${req.yours > 0 ? ` · You check ${req.yours}` : ""}`;
         row("requirements", "Requirements", text, unmet > 0 ? problem(headline) : req.met === req.total ? "ok" : "none", unmet > 0 && headline !== "Failed" ? { action: { label: "See which", href: facts.links?.checks ?? facts.links?.result ?? null } } : {});
     }
     const evidence = facts.evidence;
@@ -203,19 +239,23 @@ function leadSentence(headline, facts) {
         return `${facts.checks.level === "quick" ? "Quick checks" : "Checks"} failed${sha === null ? "" : ` on ${sha}`}. ${leadOnIt(facts.leadName)}`;
     return leadOnIt(facts.leadName);
 }
-export function taskStatusOf(facts) {
+/** The one status every surface shows (console list, task and result pages, CLI, chat, phone, `status`). */
+export function statusOf(facts) {
     const read = headlineOf(facts);
     const lead = facts.lead != null && LEAD_HEADLINES.has(read) ? facts.lead : null;
     // The lead has it: nothing waits on the person, so a Needs you reads Waiting.
     const headline = lead === "on-it" && read === "Needs you" ? "Waiting" : read;
-    // Every Needs you carries the one action that resolves it, worded the same everywhere.
-    const need = headline === "Needs you" ? { key: facts.need ?? "other", action: NEEDS[facts.need ?? "other"].action } : null;
+    // Every Needs you carries the one action that resolves it, worded the same everywhere; a finished result's is Open result.
+    const needKey = facts.stage === "finished" ? "review-result" : facts.need ?? "other";
+    const need = headline === "Needs you" ? { key: needKey, action: NEEDS[needKey].action } : null;
     const ownWords = need !== null && (need.key === "other" || need.key === "review-result") && facts.action != null;
     const primaryAction = need === null || ownWords ? facts.action ?? null : { label: need.action.label, href: facts.action?.href ?? null };
     const sentence = lead === "on-it" ? leadSentence(headline, facts) : lead === "lapsed" ? `${leadLapsed(facts.leadName)} ${sentenceOf(headline, facts)}` : sentenceOf(headline, facts);
     return { headline, tone: HEADLINE_TONE[headline], sentence, details: detailsOf(headline, facts),
         primaryAction, why: [...new Set(facts.why ?? [])].filter(one => one.trim() !== ""), need };
 }
+/** The name most surfaces already import. */
+export const taskStatusOf = statusOf;
 // ---- reading the existing projections ----------------------------------------
 /** Every dispatch or work-index code, as the stage it means. Unknown codes that
  * wait on a person stay Needs you; everything else waits in the queue. */
@@ -316,19 +356,93 @@ export function assignmentStageOf(assignment, work, planning = false) {
 }
 /** Evidence that passed and only awaits the retired assessment step is met. */
 const requirementMet = (row) => row.state === "pass" || (row.assessment?.evidenceState === "pass" && (row.review ?? null) === null);
-export function requirementWordOf(row, verdict) {
+/** A requirement whose only gap is the project check: every other kind it needs was shown, none is a person's check. */
+const onlyCheckMissing = (row) => {
+    const needs = row.requiredEvidence ?? [];
+    const answered = new Set((row.answered ?? []).map(one => one.kind));
+    if (row.state !== "missing" || row.review != null || row.assessment?.evidenceState === "failed" ||
+        !needs.includes("check") || needs.includes("manual-review") || !needs.every(kind => kind === "check" || answered.has(kind)))
+        return false;
+    // `answered` contains claims, not validated evidence. In legacy matrices a missing
+    // check takes precedence over an invalid screenshot/changed path in `state`.
+    // Only the stored validator's check-only gaps establish that every other
+    // reference resolved. Direct assessment keeps these outcomes in its own detail.
+    const detail = row.assessment?.detail ?? row.detail ?? [];
+    const checkGaps = new Set([
+        `criterion "${row.id}" requires check evidence, which the proof does not reference`,
+        `criterion "${row.id}" is waiting for the final check`,
+        `criterion "${row.id}" needs a passing approved project check`,
+    ]);
+    return (needs.every(kind => kind === "check") || detail.length > 0) && detail.every(one => checkGaps.has(one));
+};
+/** A required screenshot nobody captured. */
+const screenshotMissing = (row) => (row.requiredEvidence ?? []).includes("screenshot") && !(row.answered ?? []).some(one => one.kind === "screenshot");
+export function requirementWordOf(row, verdict, release) {
     if (verdict === "refuted")
         return "Unverified";
     if (requirementMet(row))
         return "Met";
-    return row.state === "manual-review" ? "You check" : row.state === "missing" ? "Not shown yet" : "Not met";
+    if (release !== undefined && onlyCheckMissing(row))
+        return release === "covered" ? "Met" : release === "running" ? "Waiting for checks" : CHECKED_AT_RELEASE;
+    if (row.state === "manual-review")
+        return "You check";
+    return row.state === "missing" || screenshotMissing(row) ? "Not shown yet" : "Not met";
+}
+const ASK_STATEMENT = 140;
+const quoted = (statement) => {
+    const one = (statement ?? "").replace(/\s+/g, " ").trim();
+    return one.length > ASK_STATEMENT ? `${one.slice(0, ASK_STATEMENT - 1)}…` : one;
+};
+/** The ask for one unresolved requirement: what is wrong with it, and the two ways on. */
+function unresolvedAsk(row, word) {
+    const what = word === "Not shown yet" && screenshotMissing(row) ? "A screenshot is missing for"
+        : word === "Not shown yet" ? "Nothing shows this requirement is met" : word === "Unverified" ? "This requirement couldn't be verified" : "This requirement isn't met";
+    return `${what}: ${quoted(row.statement) || row.id || "a requirement"}. Ask for changes, or accept the result with a reason.`;
 }
 /** Requirements from the stored matrix: met, the ones only a person confirms, and the total. */
-export function requirementsOf(matrix) {
+export function requirementsOf(matrix, release) {
     if (!matrix || matrix.length === 0)
         return null;
-    return { met: matrix.filter(requirementMet).length, total: matrix.length, yours: matrix.filter(row => requirementWordOf(row) === "You check").length,
-        missed: matrix.filter(row => !requirementMet(row) && (row.state === "failed" || row.state === "missing")).length };
+    const words = matrix.map(row => requirementWordOf(row, null, release));
+    const yours = matrix.find((_, index) => words[index] === "You check");
+    const unshown = matrix.filter((row, index) => words[index] === "Not shown yet" && screenshotMissing(row));
+    const ask = yours !== undefined ? `Check this requirement yourself, then mark it complete: ${quoted(yours.statement)}`
+        : unshown.length > 0 ? unresolvedAsk(unshown[0], "Not shown yet") : null;
+    return { met: words.filter(word => word === "Met").length, total: matrix.length, yours: words.filter(word => word === "You check").length,
+        missed: words.filter(word => word === "Not met" || word === "Not shown yet").length,
+        ...(release !== "pending" ? {} : { atRelease: words.filter(word => word === CHECKED_AT_RELEASE).length }),
+        ...(unshown.length === 0 ? {} : { unshown: unshown.length }),
+        ...(ask === null ? {} : { ask }) };
+}
+/** What refuses Complete, for `task complete`, the console and chat completion and deploy-candidate alike: a failed
+ * check; a required check that is missing (checks deliberately Off are not missing: they are checked at release);
+ * an unresolved requirement (a person's own check is theirs to give by completing; a recorded acceptance resolves
+ * the rest); an unresolved HIGH review finding. A release check that covers the commit counts as passed. */
+export function completionBlockersOf(f) {
+    const blockers = [];
+    const release = releaseStateOf(f.checks);
+    const backing = checkBackingOf(f.checks);
+    if (!f.report && f.checks?.status === "failed") {
+        blockers.push({ key: "check-failed", message: `Checks failed${f.checks.exitCode === null ? "" : ` (exit ${f.checks.exitCode})`}. Fix them and run checks again, or ask for changes.` });
+    }
+    else if (!f.report && f.checkRequired && f.checks?.status !== "passed" && release === undefined) {
+        blockers.push({ key: "check-missing", message: checksUnderway(f.checks) ? "Its project check hasn't finished yet. Mark it complete once it passes."
+                : "No passing project check is recorded for this result. Run checks on it, then mark it complete." });
+    }
+    if (!f.accepted && f.checks?.status !== "failed") {
+        const refuted = f.verdict === "refuted";
+        const unresolved = (f.matrix ?? []).map(row => ({ row, word: requirementWordOf(row, refuted ? "refuted" : null, backing) }))
+            .filter(one => one.word === "Not met" || one.word === "Not shown yet" || one.word === "Unverified");
+        if (unresolved.length === 1)
+            blockers.push({ key: "criteria", message: unresolvedAsk(unresolved[0].row, unresolved[0].word) });
+        else if (unresolved.length > 1) {
+            const ids = unresolved.map(one => one.row.id ?? "?");
+            blockers.push({ key: "criteria", message: `${unresolved.length} requirements ${unresolved.every(one => one.word === "Unverified") ? "couldn't be verified" : "aren't met yet"} (${ids.slice(0, 6).join(", ")}${ids.length > 6 ? ", …" : ""}). Ask for changes, or accept the result with a reason.` });
+        }
+    }
+    if (f.high > 0)
+        blockers.push({ key: "high", message: `The automatic review found ${f.high === 1 ? "a high-severity problem" : `${f.high} high-severity problems`}. Ask for changes before marking it complete.` });
+    return blockers;
 }
 /** A refuted report verifies none of its requirements, whatever it marked met (a person's acceptance doesn't change that). */
 export function unverifiedWhenRefuted(requirements, verdict) {
@@ -355,7 +469,7 @@ export function assignmentStatusFacts(assignment, options = {}) {
     const checks = receipt === null || !withResult ? null
         : { status: receipt.checks.status, exitCode: receipt.checks.exitCode, head: receipt.head,
             ...(receipt.checks.level == null ? {} : { level: receipt.checks.level }), ...(receipt.checks.running == null ? {} : { running: receipt.checks.running }),
-            ...(receipt.checks.batch == null ? {} : { batch: receipt.checks.batch }) };
+            ...(receipt.checks.batch == null ? {} : { batch: receipt.checks.batch }), ...(receipt.checks.release == null ? {} : { release: receipt.checks.release }) };
     const publication = assignment.publication;
     const pullRequest = options.pullRequest !== undefined ? options.pullRequest
         : publication === null ? (withResult && !report ? { state: "none", number: null, url: null, ci: null, error: null } : null)
@@ -368,7 +482,9 @@ export function assignmentStatusFacts(assignment, options = {}) {
         stage, ...(need === undefined ? {} : { need }), ...(wait === undefined ? {} : { wait }), ...(build === null ? {} : { needContext: { build } }), reason, report,
         checks,
         pullRequest: withResult ? pullRequest : null,
-        requirements: withResult ? unverifiedWhenRefuted(requirementsOf(receipt?.proof?.matrix), receipt?.proof?.verdict) : null,
+        requirements: withResult ? unverifiedWhenRefuted(requirementsOf(receipt?.proof?.matrix, checkBackingOf(checks)), assignment.readiness?.verdict ?? receipt?.proof?.verdict) : null,
+        ...(withResult && receipt?.proofAcceptance != null ? { accepted: true } : {}),
+        ...(withResult && (assignment.readiness?.blockers.length ?? 0) > 0 ? { blockers: assignment.readiness.blockers } : {}),
         evidence: withResult ? options.evidence ?? evidenceOf(receipt, [...(receipt?.caveats ?? []), ...assignment.attention]) : null,
         completedBy: assignment.completion === null ? null : assignment.completion.lead === true ? "the lead" : assignment.completion.actor.replace(/^(?:operator|coordinator|lead):/, ""),
         action: options.action ?? null,