toolroll 0.9.104 → 0.9.105

package/dist/contracts/route.js

@@ -1,50 +1,25 @@
-/**
- * A sealed route (phase-routing.ts): which exact agent plans, builds, repairs and reviews a task, as a scope's
- * `proposed_route_json` / `approved_route_json` and a standing order's route keep it. One schema covering both versions
- * a route has been saved in — version 1 (sealed before sizing: no `size`, routine and strong tiers) and version 2 —
- * plus the override list and the task size it carries. The rules JSON Schema cannot state run in plain code after
- * parsing, each with a path-named error: the legs run plan, build, repair, review in that order; the posture is what
- * the legs actually run; one override per phase.
- *
- * Reading never rewrites: a version 1 route stays version 1 (its digest domain and bytes are its own), and reads with
- * no size. phase-routing.ts `canonicalRouteJson` / `routeDigestOf` encode the parsed value, so a sealed route's digest
- * is what it always was.
- */
 import { z } from "zod";
 import { EVIDENCE_KINDS } from "./acceptance-terms.js";
 import { limited, parseContract, versioned } from "./contract.js";
 import { selectionSchema } from "./route-results.js";
-/** The phases a route has a leg for, in the order its legs run. */
 export const ROUTE_PHASES = ["plan", "build", "repair", "review"];
-/** provider.ts's provider ids, restated (provider.ts sits above phase-routing.ts in the module graph) and pinned to
- * them by the test suite. */
 export const ROUTE_PROVIDERS = ["claude", "codex", "openrouter", "gemini", "opencode", "cursor", "cline", "qwen", "goose"];
-/** provider.ts's MODEL_ID, restated for the same reason: an exact model id is argv-safe — no leading dash, no
- * whitespace or control bytes. */
 export const MODEL_ID_SHAPE = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/;
 export const RISKS = ["routine", "elevated", "high"];
 export const TASK_SIZE_WORDS = ["small", "medium", "large"];
-/** The newest route version this code seals (docs/plans/results-routing.md, slice 2): version 3 adds the build leg's
- * sealed `selection`, and is sealed only for a build leg that carries one (an earned rule's). Every other route still
- * seals as version 2 (PLAIN_ROUTE_VERSION), so its bytes and digest are what they always were; version 1 (before
- * sizing) still reads. */
 export const ROUTE_VERSION = 3;
-/** The version a route with no selection seals as. */
 export const PLAIN_ROUTE_VERSION = 2;
-/** The newest route version this code reads. */
 export const READ_ROUTE_VERSION = ROUTE_VERSION;
 const phase = z.enum(ROUTE_PHASES);
 const provider = z.enum(ROUTE_PROVIDERS);
 const model = z.string().regex(MODEL_ID_SHAPE, { error: "must be an exact model id: letters, digits and . _ : / -, not starting with a dash" });
 const text = z.string().min(1);
-/** How big a change the task is, as it was sized (by the classifier, the description, or a person). */
 export const taskSizingSchema = z.strictObject({
     size: z.enum(TASK_SIZE_WORDS),
     risky: z.boolean(),
     source: z.enum(["classifier", "heuristic", "person"]),
     reason: limited("size reason", "sizeReason"),
 });
-/** An approver's explicit per-phase choice, recorded with attribution. */
 export const routeOverrideSchema = z.strictObject({ phase, provider, model, by: text, at: text });
 function legSchema(tiers) {
     const tier = z.enum(tiers);
@@ -59,9 +34,7 @@ function legSchema(tiers) {
         problem: text.nullable(),
     });
 }
-/** One leg of a version 2 route: the light tier exists. */
 export const routeLegSchema = legSchema(["light", "routine", "strong"]);
-/** One leg of a version 3 route: a version 2 leg, and the build leg may say how it was selected. */
 export const routeLegV3Schema = routeLegSchema.extend({ selection: selectionSchema.optional() });
 const terms = {
     risk: z.enum(RISKS),
@@ -88,26 +61,21 @@ export const sealedRouteV3Schema = versioned(READ_ROUTE_VERSION, {
     overrides: z.array(routeOverrideSchema),
     size: taskSizingSchema.nullable(),
 });
-/** A sealed route as saved, in any version. */
 export const sealedRouteSchema = z.discriminatedUnion("version", [sealedRouteV1Schema, sealedRouteV2Schema, sealedRouteV3Schema]);
-/** The posture legs actually run under: strong only when a leg runs a configured strong agent as recommended. */
 export function postureOf(legs) {
     return legs.some(leg => leg.chosen === "recommended" && leg.tier === "strong") ? "strong" : "economy";
 }
 const issue = (path, what) => ({ path, kind: "bad-value", line: `${path}: ${what}` });
-/** Overrides as read: one per phase (a second is named by path), in phase order. */
 function overridesOf(overrides, at) {
     const issues = overrides.flatMap((one, index) => overrides.findIndex(other => other.phase === one.phase) === index ? [] : [issue(`${at}[${index}].phase`, `${JSON.stringify(one.phase)} appears twice`)]);
     if (issues.length > 0)
         return { ok: false, issues };
     return { ok: true, value: [...overrides].sort((a, b) => ROUTE_PHASES.indexOf(a.phase) - ROUTE_PHASES.indexOf(b.phase)) };
 }
-/** Read a task's recorded override list (a list on its own, as `route_overrides_json` keeps it). */
 export function readRouteOverrides(input) {
     const parsed = parseContract(z.object({ overrides: z.array(routeOverrideSchema) }), { overrides: input });
     return parsed.ok ? overridesOf(parsed.value.overrides, "overrides") : parsed;
 }
-/** Read a sealed route: either version as itself, every leg, override and the size proved, nothing unknown. */
 export function readSealedRoute(input) {
     const version = typeof input === "object" && input !== null ? input["version"] : undefined;
     if (typeof version === "number" && Number.isInteger(version) && version > READ_ROUTE_VERSION) {
@@ -118,7 +86,6 @@ export function readSealedRoute(input) {
         return parsed;
     const route = parsed.value;
     const issues = route.legs.flatMap((leg, index) => (leg.phase === ROUTE_PHASES[index] ? [] : [issue(`legs[${index}].phase`, `must be ${JSON.stringify(ROUTE_PHASES[index])} (legs run plan, build, repair, review)`)]));
-    // Version 3: only the build leg says how it was selected, and what it says agrees with how it was chosen.
     route.legs.forEach((leg, index) => {
         const selection = leg.selection;
         if (selection === undefined)

package/dist/contracts/scope.js

@@ -1,17 +1,3 @@
-/**
- * A task's scope: its goal, what is out of it, the paths it expects to touch and the acceptance rubric an operator
- * signs. One schema for the terms and one for a criterion, both made from the plan contract's own fields
- * (src/contracts/plan.ts) rather than restated; a scope may name 50 paths where a plan names 32. The rules JSON Schema
- * cannot state — UTF-8 byte limits, control characters, duplicate criterion ids and evidence kinds — run in plain code
- * after parsing, each with a path-named error.
- *
- * Reading keeps what every release accepted: a criterion's unknown keys are ignored, a null or empty `how` reads as
- * null, and an absent or empty rubric reads as none (whether that is allowed is the caller's question). The digest
- * (scope.ts `digestOf`) reads the parsed values, so a saved scope's digest is what it always was.
- *
- * The schemas are built lazily: plan.ts reads the evidence kinds through scope.ts, which reads this module, so in
- * either load order plan.ts may still be loading when this module is.
- */
 import { z } from "zod";
 import { hasForbiddenControls } from "../decision.js";
 import { TEXT_LIMITS } from "../text-limits.js";
@@ -19,22 +5,16 @@ import { ACCEPTANCE_LIMITS } from "./acceptance-terms.js";
 import { contractProblemOf, parseContract } from "./contract.js";
 import { acceptanceCriterionSchema as planCriterionSchema, planSchema } from "./plan.js";
 import { isRecord } from "../is-record.js";
-/** A criterion as saved and as every reader returns it: the plan's criterion with `how` always present (null for none). */
 export const savedCriterionSchema = z.lazy(() => planCriterionSchema.extend({ how: planCriterionSchema.shape.how.unwrap() }));
-/** A rubric as saved: at most twelve criteria (an empty one is a scope filed before rubrics, or by a road with none). */
 export const rubricSchema = z.lazy(() => z.array(savedCriterionSchema).max(ACCEPTANCE_LIMITS.criteria));
-/** A rubric as a row stores it: exactly the keys this code writes (`how` may be absent on an older row). */
 export const storedRubricSchema = z.lazy(() => z.array(planCriterionSchema).max(ACCEPTANCE_LIMITS.criteria));
-/** What a model drafts as a rubric (the lead's proposals): the plan's criteria, one to twelve. */
 export const rubricInputSchema = z.lazy(() => z.array(planCriterionSchema).min(1).max(ACCEPTANCE_LIMITS.criteria));
-/** A scope's terms as filed: the plan's goal, out-of-scope text and touch paths (up to 50), and its rubric. */
 export const scopeTermsSchema = z.lazy(() => z.strictObject({
     goal: planSchema.shape.goal,
     outOfScope: planSchema.shape.outOfScope,
     touches: z.array(planSchema.shape.touches.unwrap().element).max(TEXT_LIMITS.scopeTouches).optional(),
     acceptance: rubricSchema.optional(),
 }));
-/** A criterion as the reader takes it: only the fields it knows, a null or empty `how` as null. Anything else as is. */
 function criterionBody(entry) {
     if (!isRecord(entry))
         return entry;
@@ -45,7 +25,6 @@ function criterionBody(entry) {
     out["how"] = entry["how"] === undefined || entry["how"] === "" ? null : entry["how"];
     return out;
 }
-/** The plain-code rules for one criterion JSON Schema cannot state: UTF-8 bytes and control characters. */
 function criterionTextProblems(criterion, at) {
     const out = [];
     for (const [field, limit] of [["id", ACCEPTANCE_LIMITS.id], ["statement", ACCEPTANCE_LIMITS.statement], ["how", ACCEPTANCE_LIMITS.how]]) {
@@ -61,18 +40,12 @@ function criterionTextProblems(criterion, at) {
     return out;
 }
 const named = (problems, path) => problems.some(one => one.message.startsWith(`${path}:`));
-/**
- * Read a rubric from already-JSON-parsed input (a console form, the CLI, a routine or template, a model's proposal,
- * a saved row): every problem at once, each naming its path. Absent or empty is `[]` with no problems. A criterion
- * that reads cleanly is kept even when another does not, as before; any problem means the rubric is refused.
- */
 export function readAcceptance(value) {
     if (value === undefined || value === null)
         return { criteria: [], problems: [] };
     const body = Array.isArray(value) ? value.map(criterionBody) : value;
     const parsed = parseContract(z.object({ acceptance: rubricSchema }), { acceptance: body });
     const issues = parsed.ok ? [] : parsed.issues;
-    // The list itself is wrong (not a list, too long): nothing in it is read.
     if (!Array.isArray(body) || issues.some(one => one.path === "acceptance"))
         return { criteria: [], problems: issues.map(contractProblemOf) };
     const criteria = [];
@@ -86,7 +59,6 @@ export function readAcceptance(value) {
         const kinds = read?.success === true ? read.data.evidence : [];
         const twice = kinds.flatMap((kind, k) => (kinds.indexOf(kind) === k ? [] : [{ reason: `${at}-duplicate-evidence-kind`, message: `${at}.evidence[${k}]: "${kind}" appears twice` }]));
         problems.push(...own, ...text, ...twice);
-        // A duplicate id is a problem with the rubric, not with either criterion: both stay readable, as before.
         const id = isRecord(entry) ? entry["id"] : undefined;
         const idClean = typeof id === "string" && !named(own, `${at}.id`) && !named(text, `${at}.id`);
         if (idClean && seen.has(id))
@@ -98,7 +70,6 @@ export function readAcceptance(value) {
     });
     return { criteria, problems };
 }
-/** Read a scope's terms as a person or a model files them; the first field refused names the refusal. */
 export function readScopeTerms(input) {
     if (!isRecord(input))
         return { ok: false, field: "payload", problems: [{ reason: "bad-payload", message: "payload: must be an object" }] };

package/dist/contracts/scout-report.js

@@ -1,18 +1,8 @@
-/**
- * The scout's report: one schema for the report a scout writes (its report file, or Claude's structured output), the
- * JSON Schema a Claude scout is given (`--json-schema`, `SCOUT_OUTPUT_JSON_SCHEMA`) and the reader that takes it back
- * (`parseReport` in scout-report.ts), which also reads every report already kept as evidence. The rules JSON Schema
- * cannot state — UTF-8 byte limits, blank text, control characters, one-line titles, a one-paragraph summary, safe
- * links, duplicate screenshots and items naming them — run in plain code after parsing, each with a path-named error.
- */
 import { z } from "zod";
 import { limitRule, TEXT_LIMITS } from "../text-limits.js";
 import { limited, readVersioned, toModelSchema, versioned } from "./contract.js";
 import { isRecord } from "../is-record.js";
-/** How many follow-ups, items and screenshots a report may carry. */
 export const REPORT_COUNTS = { followUps: 5, items: 6, images: 8 };
-/** Caps are BYTES of UTF-8 (v4 review, finding 11): a 64 KiB report is 64 KiB whatever script it is written in. They
- * hold what a scout writes; a stored report is read without them (`storedReportSchema`). */
 export const REPORT_LIMITS = {
     payload: TEXT_LIMITS.reportPayloadBytes,
     title: TEXT_LIMITS.reportTitleBytes,
@@ -20,7 +10,6 @@ export const REPORT_LIMITS = {
     document: TEXT_LIMITS.reportDocumentBytes,
     followUps: REPORT_COUNTS.followUps,
     followUpTitle: TEXT_LIMITS.reportTitleBytes,
-    /** A follow-up files as a task: its goal is held to the task goal limit, in bytes of the same count. */
     followUpGoal: TEXT_LIMITS.goal,
     items: REPORT_COUNTS.items,
     itemTitle: TEXT_LIMITS.reportTitleBytes,
@@ -29,9 +18,7 @@ export const REPORT_LIMITS = {
     images: REPORT_COUNTS.images,
     caption: TEXT_LIMITS.reportCaptionBytes,
 };
-/** A screenshot's name in the scout's output folder: one plain file name, PNG or JPEG, never a path. */
 export const REPORT_IMAGE_FILE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}\.(?:png|jpe?g)$/i;
-/** Each text field, the limit it is written within, and whether it is one line or a web address. */
 export const REPORT_TEXT_FIELDS = {
     title: { limit: "reportTitleBytes", oneLine: true },
     summary: { limit: "reportSummary" },
@@ -39,11 +26,9 @@ export const REPORT_TEXT_FIELDS = {
 };
 export const FOLLOW_UP_TEXT_FIELDS = { title: { limit: "reportTitleBytes", oneLine: true }, goal: { limit: "goal" } };
 export const ITEM_TEXT_FIELDS = { title: { limit: "reportTitleBytes", oneLine: true }, why: { limit: "reportWhyBytes" }, url: { limit: "reportUrlBytes", link: true } };
-// The image's file is any one line here: the runner refuses one that isn't a plain file name in its output folder, not the report.
 export const IMAGE_TEXT_FIELDS = { file: { limit: "reportCaptionBytes", oneLine: true }, caption: { limit: "reportCaptionBytes", oneLine: true }, url: { limit: "reportUrlBytes", link: true } };
 export const REPORT_VERSION = 1;
 function reportSchemaOf(text) {
-    // Limits named without "Bytes" that a report still counts in bytes: the model is told so.
     const bytes = (field, limit) => text(field, limit).describe(limitRule(field, TEXT_LIMITS[limit], "bytes"));
     const followUp = z.strictObject({
         title: text("follow-up title", "reportTitleBytes").min(1),
@@ -59,7 +44,6 @@ function reportSchemaOf(text) {
         file: text("image file", "reportCaptionBytes").min(1),
         caption: text("image caption", "reportCaptionBytes").min(1),
         url: text("image url", "reportUrlBytes").min(1),
-        /** Added by Toolroll once the screenshot is stored: its bytes' sha256 and the evidence that holds them. */
         sha256: z.string().regex(/^[0-9a-f]{64}$/, { error: "must be a sha256 hex digest" }).optional().describe("set by Toolroll when it keeps the screenshot; leave out"),
         artifact: z.int().positive().optional().describe("set by Toolroll when it keeps the screenshot; leave out"),
     });
@@ -72,12 +56,8 @@ function reportSchemaOf(text) {
         images: z.array(image).max(REPORT_COUNTS.images).optional(),
     });
 }
-/** A report as a scout writes it now. */
 export const scoutReportSchema = reportSchemaOf(limited);
-/** A report kept as evidence: the same, except text keeps the length it was stored with. */
 export const storedReportSchema = reportSchemaOf(() => z.string());
-/** The park mailbox's decision as a scout hands it back: the same fields `parseDecision` reads, which stays its
- * validator until the decision contract (docs/plans/zod-revamp.md, item 7) gives it one schema. */
 export const scoutDecisionSchema = z.strictObject({
     urgency: z.literal("blocking"),
     recap: z.string(),
@@ -85,12 +65,6 @@ export const scoutDecisionSchema = z.strictObject({
     options: z.array(z.strictObject({ id: z.string(), label: z.string(), consequence: z.string(), reversible: z.boolean() })),
     recommendation: z.string(),
 });
-/**
- * The scout's handback for Claude's `--json-schema` (run 2334's fix): plan mode only lets a session write its own plan
- * file, so a Claude scout returns a report — or a question for the operator — as structured output on the terminal
- * result event. The report branch is the report schema itself; the byte limits and rules JSON Schema cannot state are
- * `parseReport`'s (and `parseDecision`'s), applied to the branch as handed back.
- */
 export const scoutHandbackSchema = z.strictObject({
     kind: z.enum(["report", "question"]),
     report: scoutReportSchema.optional(),
@@ -110,11 +84,6 @@ const ENTRY_FIELDS = {
     items: [...Object.keys(ITEM_TEXT_FIELDS), "image"],
     images: [...Object.keys(IMAGE_TEXT_FIELDS), "sha256", "artifact"],
 };
-/**
- * Known reports keep the old parser's field-picking, whether unversioned (including `version: null`) or version 1:
- * unknown fields in the report, follow-ups, items and images are ignored, and a null list means none. Known field
- * values are never rewritten, and anything that is not an object is left for the schema to refuse by path.
- */
 function normalizeReportV1(body) {
     const out = { version: REPORT_VERSION, ...pick(body, [...Object.keys(REPORT_TEXT_FIELDS), "followUps", "items", "images"]) };
     for (const list of ["followUps", "items", "images"]) {
@@ -126,7 +95,6 @@ function normalizeReportV1(body) {
     return out;
 }
 export const REPORT_UPGRADES = { 0: normalizeReportV1 };
-/** Normalize current and unversioned reports; leave other versions for readVersioned to check. */
 export function reportPayloadBody(input) {
     if (!isRecord(input))
         return null;
@@ -134,8 +102,6 @@ export function reportPayloadBody(input) {
         ? normalizeReportV1(input)
         : input;
 }
-/** Read current and unversioned reports with the same field-picking, then the strict schema; refuse newer versions
- * plainly. `stored`: one kept as evidence, read without the length limits. */
 export function readReportPayload(input, options = {}) {
     return readVersioned(options.stored === true ? storedReportSchema : scoutReportSchema, reportPayloadBody(input) ?? input, REPORT_UPGRADES);
 }

package/dist/contracts/slack-callback.js

@@ -1,18 +1,9 @@
-/**
- * A Slack button tap (slack-chat.ts `receiveSlack`): the `block_actions` interaction Slack sends, and the button data
- * Toolroll put on it. The interaction is Slack's, so fields Toolroll doesn't read are ignored; the button (its
- * `action_id` and one-time token `value`) is Toolroll's. A tap from the paired person whose button can't be read is
- * answered with why (`actions[0].value: must be a Toolroll button token`), and nothing is done.
- */
 import { z } from "zod";
 import { parseContract } from "./contract.js";
 import { CHAT_BUTTON_TOKEN } from "./chat-content.js";
-/** Toolroll's buttons: toolroll_* since the rename; standing_orders_* buttons on older messages still work. */
 export const SLACK_BUTTON_ACTION = /^(?:toolroll|standing_orders)_(?:confirm|dismiss|yes|cancel|flow_approve|flow_edit|flow_send_back|flow_choose_[0-3]|flow_note_(?:yes|no)|question_choice|question_words|decide_[0-9]{1,2})$/;
-/** A link button opens its page in Slack's own client; Slack still reports the tap, and there is nothing to do. */
 export const SLACK_LINK_ACTION = /^(?:toolroll|standing_orders)_link(?:_[0-9]+)?$/;
 const token = z.string().regex(CHAT_BUTTON_TOKEN, { error: "must be a Toolroll button token" });
-/** The interaction around a tap: who, and the message the button is on. */
 export const slackBlockActionsSchema = z.object({
     type: z.literal("block_actions"),
     user: z.object({ id: z.string() }),
@@ -20,7 +11,6 @@ export const slackBlockActionsSchema = z.object({
     message: z.object({ thread_ts: z.string().optional() }).optional(),
     actions: z.array(z.object({ action_id: z.string().optional(), value: z.string().optional(), action_ts: z.string().optional() })),
 });
-/** The one tapped button, as Toolroll made it. */
 export const slackButtonSchema = z.object({
     action_id: z.string().regex(SLACK_BUTTON_ACTION, { error: "not a Toolroll button" }),
     value: token,
@@ -29,7 +19,6 @@ export const slackButtonSchema = z.object({
 export function readSlackBlockActions(body) {
     return parseContract(slackBlockActionsSchema, body);
 }
-/** The tapped button: exactly one, Toolroll's (`actions[0].action_id: not a Toolroll button`). */
 export function readSlackButton(interaction) {
     const read = parseContract(z.object({ actions: z.array(slackButtonSchema).length(1) }), { actions: interaction.actions });
     return read.ok ? { ok: true, value: read.value.actions[0] } : read;

package/dist/contracts/sort-answer.js

@@ -1,44 +1,26 @@
-/**
- * A Sort zone's answer (flow-sort.ts): what Jev, through OpenRouter's Decisions API, says about a card, and what a
- * sort step keeps of it. The Decisions API takes questions, not a JSON Schema, so there is no model-facing schema:
- * the request's keys come from the flow contract (`SORT_ROUTE_KEY`, `sortNoteKeyOf`, `sortKeyOf` in flow.ts), and
- * `jevReplySchema` is how the reply is read before anything routes on it.
- *
- * The reply is an outside service's: keys Toolroll does not read (ids, token counts) are ignored rather than refused.
- * Optional metadata can have any type, as before: the reader defaults non-numeric confidences/chances to zero,
- * skips non-numeric notes, and defaults the model and cost. The route choice must still be text.
- *
- * `sortDecisionSchema` is the decision a sort step keeps (`flow_step_run.decision_json`), unversioned as every release
- * has written it; the card, Insights and spend read saved ones as before.
- */
 import { z } from "zod";
 import { parseContract } from "./contract.js";
 import { flowSortAnswerSchema, flowSortNoteSchema, SORT_ROUTE_KEY } from "./flow.js";
-/** Jev's answer to the zone's question: the key of the answer it picked, how sure it is (0–1), and every answer's chance. */
 export const jevChoiceSchema = z.object({
     choice: z.string(),
     confidence: z.unknown().optional(),
     probabilities: z.unknown().optional(),
 });
-/** Jev's answer to something else the zone notes: a score's level (as a number) or a yes/no's chance of yes. */
 export const jevNoteSchema = z.object({
     score: z.unknown().optional(),
     noul: z.unknown().optional(),
     confidence: z.unknown().optional(),
 });
-/** What Toolroll reads of Jev's reply. */
 export const jevReplySchema = z.object({
     model: z.unknown().optional(),
     answers: z.object({ [SORT_ROUTE_KEY]: jevChoiceSchema }).catchall(jevNoteSchema),
     usage: z.unknown().optional(),
 });
-/** Read Jev's reply, or path-named lines saying what it lacks (`answers.route.choice: required`). */
 export function readJevReply(input) {
     if (typeof input === "object" && input !== null && !Array.isArray(input)) {
         const body = input;
         const answers = body["answers"];
         if (typeof answers === "object" && answers !== null && !Array.isArray(answers)) {
-            // Extra answers are not necessarily notes. Non-objects have no note fields to read, so ignore them.
             input = { ...body, answers: Object.fromEntries(Object.entries(answers).map(([key, value]) => [key,
                     key === SORT_ROUTE_KEY || (typeof value === "object" && value !== null && !Array.isArray(value)) ? value : {},
                 ])) };
@@ -47,7 +29,6 @@ export function readJevReply(input) {
     return parseContract(jevReplySchema, input);
 }
 const noteShape = flowSortNoteSchema.options[0].shape;
-/** One thing the zone also noted, as the card shows it: the level or yes/no, and how sure (0–1). */
 export const sortNoteAnswerSchema = z.strictObject({
     id: noteShape.id,
     question: noteShape.question.describe("The question the zone also notes."),
@@ -55,23 +36,18 @@ export const sortNoteAnswerSchema = z.strictObject({
     answer: z.string(),
     sure: z.number().min(0).max(1),
 });
-/** What a sort step decided, kept on its run (decision_json) and shown on the card. */
 export const sortDecisionSchema = z.strictObject({
     model: z.string(),
-    /** The answer as the zone names it, and how sure Jev was (0–1). */
     answer: flowSortAnswerSchema.shape.answer.describe("The zone's chosen answer."),
     sure: z.number().min(0).max(1),
     sureAt: z.number(),
-    /** Sure enough to act alone, and where the card went (null: it waited in the zone). */
     confident: z.boolean(),
     to: flowSortAnswerSchema.shape.to.nullable(),
-    /** Every answer's chance, by name. */
     chances: z.object({}).catchall(z.number()),
     notes: z.array(sortNoteAnswerSchema),
     cost: z.number().nullable(),
     ms: z.number(),
 });
-/** Read a sort decision as a step keeps it. */
 export function readSortDecision(input) {
     return parseContract(sortDecisionSchema, input);
 }

package/dist/contracts/stage-output.js

@@ -1,48 +1,23 @@
-/**
- * What a finished zone hands the zones after it (docs/plans/zod-revamp.md, item 8): its `{{stage.<id>}}` words and, by
- * kind, more fields (a research zone's `{{stage.<id>.items}}` and `{{stage.<id>.report}}`), kept on the card as one
- * versioned payload (`flow_card.outputs_json`) with any output too long to pass on attached whole.
- *
- * - `stageHandoffSchema` is one zone's handoff; `STAGE_HANDOFFS` says which of its fields each zone kind hands on. A
- *   template's `{{stage.<id>.<field>}}` is checked against it when a flow is saved (`stageReferenceProblems`), so a
- *   refusal names the path: `stages[1].instructions: stage.research.unknown is not available`.
- * - `cardOutputsSchema` is what the card keeps: every handoff's fields flat (`<zone>`, `<zone>.items`, `<zone>.report`,
- *   as `{{stage.…}}` names them) and, for a zone whose output was over TEXT_LIMITS.stageOutput, the output whole: its
- *   `{{stage.<zone>}}` says where it is kept, and a task filed after it is given it whole (flowGoalCuts).
- *
- * Saved before this contract (version 0), a card's outputs were the flat map alone; they read exactly as every release
- * read them: the string values, anything else skipped.
- */
 import { z } from "zod";
 import { parseContract, readVersioned, versioned } from "./contract.js";
-/** One zone's handoff to the zones after it. */
 export const stageHandoffSchema = z.strictObject({
     text: z.string().describe("{{stage.<id>}}: what the zone produced, whole up to TEXT_LIMITS.stageOutput characters; a longer one says where it is kept whole."),
     items: z.string().optional().describe("{{stage.<id>.items}}: what a research zone found, as a numbered list (title, why, link)."),
     report: z.string().optional().describe("{{stage.<id>.report}}: a research zone's whole report (REPORT_FILL_LIMIT)."),
 });
 const words = stageHandoffSchema.pick({ text: true });
-/**
- * What each zone kind hands on, or null when it hands nothing on (it holds, asks, messages or ends). A sort hands on its
- * decision in words (`sortWords` of the small-answers contract's SortDecision, src/contracts/sort-answer.ts), and a
- * Send to me zone what it sent.
- */
 export const STAGE_HANDOFFS = {
     inbox: null, task: words, report: stageHandoffSchema, approval: null, check: words, "pull-request": words, update: words, notify: null,
     sort: words, draft: words, request: words, email: words, tool: words, wait: words, subagent: words, send: words, choose: null, done: null,
 };
-/** The extra `{{stage.<id>.<field>}}` fields a zone kind hands on. */
 export function stageFieldsOf(kind) {
     const schema = STAGE_HANDOFFS[kind];
     return schema === null ? [] : Object.keys(schema.shape).filter(field => field !== "text");
 }
-/** One zone's handoff, read from the card's flat outputs (a field it never wrote is left out; no words read as ""). */
 export function stageHandoffOf(outputs, zone) {
     const fields = Object.keys(stageHandoffSchema.shape).filter(field => field !== "text");
     return { text: outputs[zone] ?? "", ...Object.fromEntries(fields.flatMap(field => outputs[`${zone}.${field}`] === undefined ? [] : [[field, outputs[`${zone}.${field}`]]])) };
 }
-/** The card's flat outputs with one zone's handoff in place of its last: a field this visit didn't hand on is gone, so
- * nothing stale is left behind. */
 export function withStageHandoff(outputs, zone, handoff) {
     const read = stageHandoffSchema.parse(handoff);
     const next = { ...outputs, [zone]: read.text };
@@ -55,28 +30,19 @@ export function withStageHandoff(outputs, zone, handoff) {
     }
     return next;
 }
-// ------------------------------------------------------------------ what the card keeps
 export const CARD_OUTPUTS_VERSION = 1;
 export const cardOutputsSchema = versioned(CARD_OUTPUTS_VERSION, {
     outputs: z.object({}).catchall(z.string()).describe("Every {{stage.…}} value by its name: <zone>, and a research zone's <zone>.items and <zone>.report."),
     attached: z.object({}).catchall(z.string()).describe("A zone's output in full when it was over TEXT_LIMITS.stageOutput characters, by zone."),
 });
-/** Version 0, the flat map every release before wrote: its string values, as they read them; anything else is skipped. */
 export function upgradeFlatOutputs(raw) {
     const outputs = raw !== null && typeof raw === "object" ? Object.fromEntries(Object.entries(raw).filter((entry) => typeof entry[1] === "string")) : {};
     return { version: CARD_OUTPUTS_VERSION, outputs, attached: {} };
 }
-/**
- * Read a card's outputs. Version 1 as itself and a newer version refused plainly. Anything without a numeric `version`
- * was saved before outputs carried one (a zone may be called `version`; its words were a string), and is read as the
- * flat map it is.
- */
 export function readCardOutputs(input) {
     const legacy = input === null || typeof input !== "object" || Array.isArray(input) || typeof input["version"] !== "number";
     return legacy ? parseContract(cardOutputsSchema, upgradeFlatOutputs(input)) : readVersioned(cardOutputsSchema, input);
 }
-/** A card's outputs as the store keeps them: unreadable JSON is the empty card it always was; `newer` is a row a newer
- * Toolroll wrote, which this one reads as empty and never writes over. */
 export function cardOutputsFromStore(json) {
     let raw;
     try {
@@ -90,14 +56,10 @@ export function cardOutputsFromStore(json) {
         return { outputs: read.value.outputs, attached: read.value.attached, issues: [], newer: false };
     return { outputs: {}, attached: {}, issues: read.issues, newer: read.issues.some(one => one.kind === "newer-version") };
 }
-/** A card's outputs as the store saves them. A zone's attachment is kept only while its output is the pointer to it. */
 export function cardOutputsForStore(outputs, attached) {
     const kept = Object.fromEntries(Object.entries(attached).filter(([zone]) => outputs[zone] !== undefined));
     return JSON.stringify(cardOutputsSchema.parse({ version: CARD_OUTPUTS_VERSION, outputs, attached: kept }));
 }
-// ------------------------------------------------------------------ template references, checked at save
-/** Where a zone's words take fill-ins, by the drawing's path: its instructions and message, a request's address,
- * headers and body, an email's fields and a tool's arguments. */
 export function templateFields(stage) {
     const fields = [];
     const add = (path, text) => { if (typeof text === "string")
@@ -119,12 +81,10 @@ export function templateFields(stage) {
         add("tool.args", stage.tool.args);
     return fields;
 }
-/** Every `{{stage.…}}` in some words, as written between the braces (`stage.research.items`). */
 const STAGE_REFERENCE = /\{\{\s*(stage\.[^{}]*?)\s*\}\}/g;
 export function stageReferences(text) {
     return [...text.matchAll(STAGE_REFERENCE)].map(match => match[1]);
 }
-/** What one `{{stage.…}}` reference can't be, against the drawing: null when its zone hands that field on. */
 export function stageReferenceProblem(definition, reference) {
     const [zone = "", ...rest] = reference.slice("stage.".length).split(".");
     const field = rest.join(".");
@@ -141,12 +101,6 @@ export function stageReferenceProblem(definition, reference) {
     const offered = [`{{stage.${zone}}}`, ...fields.map(one => `{{stage.${zone}.${one}}}`)];
     return `${reference} is not available (${stage.title} hands on ${offered.length === 1 ? offered[0] : `${offered.slice(0, -1).join(", ")} and ${offered.at(-1)}`})`;
 }
-/**
- * Template references a save adds that its zones don't hand on, each named by its path
- * (`stages[1].instructions: stage.research.unknown is not available ...`). A reference the flow already had before
- * this save (`previous`, the saved drawing) is never refused, nor is any reference when a flow is only read or run:
- * this checks new and changed words alone.
- */
 export function stageReferenceProblems(definition, previous) {
     const had = new Set((previous?.stages ?? []).flatMap(stage => templateFields(stage).flatMap(field => stageReferences(field.text))));
     const problems = [];

package/dist/contracts/storage.js

@@ -1,12 +1,4 @@
-/**
- * The checkout cleanup setting (storage.ts, Settings → Storage): when a finished task's clean checkout is removed.
- * One schema for the four values `checkout_cleanup_setting.cleanup` may hold, and `CheckoutCleanup` derived from it.
- * The words a person types ("week", "off", "2 days") become a value in plain code (storage.ts `parseCleanup`) and
- * are then checked by this schema. The saved row is read by the store (item 18's to move onto `checkoutCleanupRowSchema`).
- */
 import { z } from "zod";
 export const checkoutCleanupSchema = z.enum(["finished", "2d", "7d", "never"]);
-/** How long a task stays idle before its clean folder goes (v151, checkout-cleanup.ts). A saved row's NULL is the default. */
 export const checkoutIdleSchema = z.enum(["7d", "14d", "30d", "never"]);
-/** A saved `checkout_cleanup_setting` row (at most one; none means the default), unknown columns ignored. */
 export const checkoutCleanupRowSchema = z.object({ cleanup: checkoutCleanupSchema, idle: checkoutIdleSchema.nullable().optional() });