toolroll 0.9.34 → 0.9.37

package/dist/contracts/lead-tools.js

@@ -0,0 +1,265 @@
+/**
+ * The lead's tools (docs/plans/zod-revamp.md, item 5): one input schema per tool, and one output schema for what each
+ * returns when it succeeds. The input schema supplies the JSON Schema the lead is given (`toModelSchema`) and the
+ * compatible reader used before any handler runs (mate-tools.ts), so a refusal names the paths it reads next step.
+ * What JSON Schema can't say — a repo the operator may reach, plain text without secrets, an ISO time, a decision read
+ * in an earlier step — is still checked in plain code after parsing, with its own words.
+ *
+ * Output schemas describe a result's top level. They are checked in tests and logged when a result disagrees; a call
+ * that succeeds is never refused because of one (an output schema is a record of the contract, not a gate).
+ */
+import { z } from "zod";
+import { CHAT_ACTIONS } from "../chat-actions.js";
+import { RESULT_IMAGES_PER_TURN_CAP } from "../chat-evidence.js";
+import { CHAT_CONTROLS } from "../chat-controls.js";
+import { CHAT_TASK_ACTIONS } from "../chat-task-actions.js";
+import { LIMITS } from "../decision.js";
+import { CHECK_RESULTS, RUN_OUTCOMES, TASK_STATES } from "../lead-commitments.js";
+import { PERSON_ID } from "../lead-people.js";
+import { RISK_LEVELS, TASK_SIZES } from "../phase-routing.js";
+import { ACCEPTANCE_LIMITS } from "../scope.js";
+import { TEAMMATE_TEMPLATES } from "../teammates.js";
+import { TEXT_LIMITS } from "../text-limits.js";
+import { parseContract } from "./contract.js";
+import { FLOW_ALIASES } from "./flow.js";
+import { proposeFlowInputSchema } from "./flow-propose.js";
+import { acceptanceCriterionSchema } from "./plan.js";
+const enumOf = (values) => z.enum(values);
+const text = (key) => z.string().max(TEXT_LIMITS[key]);
+const id = z.int().min(1);
+const offset = z.int().min(0);
+/** Text a model is told is "refused with its length, not cut": the refusal says how long it was. */
+function overBy(limit, input) {
+    const count = (n) => n.toLocaleString("en-US");
+    return `over ${count(limit)} characters (it is ${typeof input === "string" ? count(input.length) : "longer"}): shorten it and call again`;
+}
+/** A task as a tool names it: its id. */
+export const taskRef = z.string().min(1).max(TEXT_LIMITS.taskRef);
+/** A project as list_repos names it (r1, r2). */
+export const repoId = z.string().regex(/^r[0-9]{1,3}$/);
+/** A task's goal or what it leaves out: the length a model is told before it writes, and refused (not cut) beyond. */
+export const scopeText = z.string().max(TEXT_LIMITS.goal, { error: issue => overBy(TEXT_LIMITS.goal, issue.input) })
+    .describe(`At most ${TEXT_LIMITS.goal.toLocaleString("en-US")} characters (UTF-16 code units) and ${TEXT_LIMITS.goalBytes.toLocaleString("en-US")} UTF-8 bytes; no control or disguised text. Longer text is refused with its length, not cut: shorten it and call again.`);
+/** The paths a task expects to touch. */
+export const touches = z.array(text("taskTouch")).max(50);
+/** The rubric a task is accepted against: the plan's own criterion schema; duplicate ids and byte limits are checked after. */
+export const acceptance = z.array(acceptanceCriterionSchema).min(1).max(ACCEPTANCE_LIMITS.criteria);
+/** A note the operator's own words fill (revise feedback, steering, a flow card's note). */
+const note = z.string().max(LIMITS.note, { error: issue => overBy(LIMITS.note, issue.input) }).describe(`At most ${LIMITS.note} characters; longer is refused with its length, not cut.`);
+/** Task states a list filters by. */
+export const LISTED_TASK_STATES = ["queued", "running", "done", "failed", "cancelled"];
+/** The shared actions the lead proposes with propose_action; flows and teammates have their own tools. */
+const ACTION_OPERATIONS = Object.keys(CHAT_ACTIONS).filter(one => !one.startsWith("flow_") && !one.startsWith("teammate_"));
+export const LEAD_TOOL_INPUTS = {
+    get_brief: z.strictObject({ repo: repoId.optional() }),
+    get_project_context: z.strictObject({ repo: repoId, query: text("contextQuery").min(1), mode: z.enum(["search", "impact"]).optional() }),
+    get_action_status: z.strictObject({ proposal: id }),
+    get_actions: z.strictObject({}),
+    propose_action: z.strictObject({
+        operation: enumOf(ACTION_OPERATIONS), repo: z.string().optional(), task: taskRef.optional(), version: z.string().optional(), restore: id.optional(),
+        sample: text("actionSample").optional(), content: text("actionContent").optional(), instructions: text("flowInstructions").optional(),
+        title: text("actionTitle").optional(), id: z.string().optional(), run: id.optional(), note: note.optional(), catalog: text("actionName").optional(),
+        name: text("actionName").optional(), command: text("actionCommand").optional(), args: z.array(text("actionCommand")).max(40).optional(),
+        url: text("actionUrl").optional(), secrets: z.array(text("actionSecret")).max(12).optional(), about: text("actionAbout").optional(),
+    }),
+    propose_task_action: z.strictObject({ task: taskRef, operation: enumOf(Object.keys(CHAT_TASK_ACTIONS)), dependency: taskRef.optional(), run: id.optional() }),
+    get_controls: z.strictObject({}),
+    show_control: z.strictObject({ control: enumOf(Object.keys(CHAT_CONTROLS)), task: taskRef.optional(), repo: repoId.optional(), run: id.optional() }),
+    get_result: z.strictObject({ task: taskRef, run: id.optional(), feedback_offset: offset.optional() }),
+    get_diff: z.strictObject({ task: taskRef, run: id.optional(), file: text("diffPath").min(1).optional(), offset: offset.optional() }),
+    get_check_log: z.strictObject({ task: taskRef, run: id.optional(), search: text("logSearch").min(2).optional(), offset: offset.optional() }),
+    get_acceptance_evidence: z.strictObject({ task: taskRef, run: id.optional(), offset: offset.optional() }),
+    get_result_images: z.strictObject({ task: taskRef, run: id.optional(), offset: offset.optional(), images: z.array(id).min(1).max(RESULT_IMAGES_PER_TURN_CAP).optional() }),
+    propose_review: z.strictObject({
+        run: id, operation: z.enum(["note", "revise"]),
+        // A note, path or line left as null reads as left out, as it always has.
+        note: z.string().max(LIMITS.note).nullable().optional(), path: text("diffPath").nullable().optional(),
+        line: z.int().min(1).max(1_000_000).nullable().optional(),
+        saved_notes: z.array(id).max(100).optional(),
+    }),
+    recap: z.strictObject({ since: text("recapSince").optional() }),
+    list_repos: z.strictObject({}),
+    get_project_tools: z.strictObject({ repo: repoId }),
+    get_flows: z.strictObject({ repo: repoId.optional(), flow: id.optional(), card: id.optional() }),
+    // The flow contract's own schema (src/contracts/flow-propose.ts), never a second one here.
+    propose_flow: proposeFlowInputSchema,
+    get_teammates: z.strictObject({ repo: repoId.optional(), teammate: id.optional() }),
+    propose_teammate: z.strictObject({
+        operation: z.enum(["create", "edit_section", "edit_soul", "pause", "resume", "remove", "note", "answer", "use_tool", "stop_tool", "tool_rule", "forget", "edit_memory", "add_routine", "stop_routine", "undo"]),
+        section: text("teammateSection").optional(), schedule: text("teammateSchedule").optional(), routine: id.optional(), memory: id.optional(),
+        tool: text("teammateTool").optional(), action: text("teammateAction").optional(), undoWith: text("teammateAction").optional(), call: id.optional(),
+        use: z.enum(["free", "ask", "never"]).optional(), limitField: text("teammateAction").optional(), limitOver: z.number().min(0).optional(),
+        repo: repoId.optional(), teammate: id.optional(), template: enumOf(TEAMMATE_TEMPLATES.map(one => one.id)).optional(),
+        name: text("teammateName").optional(), soul: text("teammateSoul").optional(), note: text("teammateNote").optional(),
+        question: id.optional(), choice: text("teammateChoice").optional(), text: text("teammateText").optional(),
+    }),
+    get_flow_insights: z.strictObject({ repo: repoId.optional(), flow: id.optional(), days: z.int().min(1).max(90).optional(), card: id.optional(), entry: id.optional() }),
+    get_skills: z.strictObject({ repo: repoId, version: z.string().regex(/^[a-f0-9]{20}$/).optional(), offset: offset.optional() }),
+    get_project_knowledge: z.strictObject({ repo: repoId, reference: text("knowledgeReference").optional(), decision: id.optional() }),
+    get_task_conversation: z.strictObject({ task: taskRef, limit: z.int().min(1).max(30).optional() }),
+    commit_to: z.strictObject({
+        what: text("promise").min(3), when: z.enum(["task", "run", "check", "time"]), task: taskRef.optional(), run: id.optional(),
+        states: z.array(enumOf(TASK_STATES)).min(1).max(6).optional(), outcome: z.enum(RUN_OUTCOMES).optional(),
+        result: z.enum(CHECK_RESULTS).optional(), at: z.string().optional(), checkAfter: z.string().optional(),
+    }),
+    release_commitment: z.strictObject({ commitment: id, reason: text("promise").min(3) }),
+    remember: z.strictObject({
+        repo: repoId.optional(), kind: z.enum(["decision", "instruction", "about-you"]), text: text("rememberText").min(3), why: text("rememberWhy").optional(),
+        source: text("rememberSource").optional(), revision: offset.optional(), replaces: z.int().min(1).max(20).optional(),
+    }),
+    get_person: z.strictObject({ id: z.string().regex(PERSON_ID).optional(), name: text("personName").min(1).optional() }),
+    get_integrations: z.strictObject({}),
+    get_capabilities: z.strictObject({ repo: repoId.optional() }),
+    ask_owner: z.strictObject({ question: text("ownerQuestion").min(3), options: z.array(text("ownerOption").min(1)).min(2).max(4) }),
+    search_project_memory: z.strictObject({ query: text("memorySearch").min(2), repo: repoId.optional() }),
+    get_models: z.strictObject({}),
+    list_tasks: z.strictObject({ repo: repoId.optional(), state: z.enum(LISTED_TASK_STATES).optional(), limit: z.int().min(1).max(50).optional(), search: text("taskSearch").optional() }),
+    get_task: z.strictObject({ task: taskRef }),
+    get_agents: z.strictObject({ task: taskRef }),
+    list_decisions: z.strictObject({}),
+    get_decision: z.strictObject({ decision: id }),
+    queue: z.strictObject({ repo: repoId }),
+    propose_task: z.strictObject({
+        repo: repoId, title: text("taskTitle"), goal: scopeText,
+        // Exclusions left as null read as none, as they always have.
+        not: scopeText.nullable().optional(), touches: touches.optional(), acceptance,
+        planning: z.enum(["auto", "required", "skip"]).optional(), report: z.boolean().optional(), checks: text("checksWords").optional(),
+    }),
+    propose_next: z.strictObject({ task: taskRef }),
+    propose_reserve: z.strictObject({ task: taskRef, worker: text("workerName").nullable() }),
+    propose_hold: z.strictObject({ task: taskRef, reason: text("proposalReason") }),
+    propose_unhold: z.strictObject({ task: taskRef }),
+    propose_steer: z.strictObject({ task: taskRef, note }),
+    propose_dependency_repair: z.strictObject({ task: taskRef, blocker: taskRef, operation: z.enum(["retry", "unlink", "replace"]), replacement: taskRef.optional() }),
+    propose_scope: z.strictObject({ task: taskRef, goal: scopeText, not: scopeText.nullable().optional(), touches: touches.optional(), acceptance }),
+    propose_agents: z.strictObject({
+        task: taskRef, risk: z.enum(RISK_LEVELS).optional(),
+        size: z.enum(TASK_SIZES).optional(), risky: z.boolean().optional(),
+        role: z.enum(["planner", "builder", "repair"]).optional(),
+        agent: z.strictObject({ provider: text("agentProvider"), model: text("agentModel") }).optional(),
+        clear: z.boolean().optional(), why: text("agentWhy").optional(),
+    }),
+    propose_answer: z.strictObject({ decision: id, option: text("answerOption").min(1), rationale: text("answerRationale") }),
+    propose_cancel: z.strictObject({ task: taskRef, reason: text("proposalReason") }),
+};
+/**
+ * Read the same calls the 0.9.36 handlers accepted. Derive readers from the advertised contracts, leaving these
+ * optional values to their existing clamp/fallback code. Unknown top-level keys are stripped by the tool registry,
+ * except for flow proposals, whose strict contract predates item 5. The gateway also keeps its strict schemas.
+ */
+export const LEAD_TOOL_READ_INPUTS = {
+    ...LEAD_TOOL_INPUTS,
+    list_tasks: LEAD_TOOL_INPUTS.list_tasks.extend({ limit: z.unknown().optional() }),
+    get_task_conversation: LEAD_TOOL_INPUTS.get_task_conversation.extend({ limit: z.unknown().optional() }),
+    // 0.9.36 read a null repo as every project.
+    get_flow_insights: LEAD_TOOL_INPUTS.get_flow_insights.extend({ repo: repoId.nullable().optional(), days: z.unknown().optional() }),
+    get_person: LEAD_TOOL_INPUTS.get_person.extend({ id: z.unknown().optional(), name: z.unknown().optional() }),
+    propose_agents: LEAD_TOOL_INPUTS.propose_agents.extend({ agent: LEAD_TOOL_INPUTS.propose_agents.shape.agent.unwrap().strip().optional() }),
+};
+/** How a tool's call names a key it doesn't know: propose_flow suggests the flow vocabulary's own words. */
+export const LEAD_TOOL_OPTIONS = { propose_flow: FLOW_ALIASES };
+// ------------------------------------------------------------- outputs
+const str = z.string();
+const int = z.number().int();
+const list = z.array(z.unknown());
+const nullable = (schema) => schema.nullable();
+const rows = (shape) => z.array(z.looseObject(shape));
+/** A proposal drafted as a card the operator confirms (propose_action, propose_flow, propose_teammate). */
+const cardDrafted = z.looseObject({ proposal: int, label: str, awaiting: str, executed: z.literal(false) });
+/** A proposal row drafted by one of the queue, hold, scope and answer tools. */
+const proposed = (kind, shape = {}) => z.looseObject({ proposal: int, kind: z.literal(kind), awaiting: str, ...shape });
+/** A repository-context read (repository-context.ts `RepositoryContext`). */
+export const repositoryContextOutput = z.looseObject({ version: z.literal(1), readOnly: z.boolean(), query: str, mode: z.enum(["search", "impact"]), asOf: str, excerpts: list });
+/** The local catch-up (assignment-brief.ts `AssignmentCatchUp`). */
+export const catchUpOutput = z.looseObject({ version: z.literal(1), asOf: str, readOnly: z.literal(true), assignments: list, projects: list, omissions: z.looseObject({}) });
+/** How things stand per repository (mate-tools.ts `recapOver`), its repos labelled. */
+export const recapOutput = z.looseObject({ since: nullable(str), repos: list, waitsOnYou: z.looseObject({ decisions: list, incidents: int, scopesAwaitingApproval: list }), running: list, truncated: z.boolean() });
+/** Open decisions (`decisionsOver`). */
+export const decisionsOutput = z.looseObject({ decisions: rows({ decision: int, task: str, question: str, options: list, ageHours: z.number() }), truncated: z.boolean() });
+/** One decision in full (`decisionOver`), without the builder's recommendation. */
+export const decisionOutput = z.looseObject({ repo: str, decision: int, task: str, state: str, question: str, options: rows({ id: str, label: str, reversible: z.boolean(), consequence: str }), ageHours: z.number() });
+/** One repository's queue by column (`queueOver`). */
+export const queueColumnsOutput = { columns: rows({ column: str, tasks: list }) };
+export const LEAD_TOOL_OUTPUTS = {
+    get_brief: catchUpOutput,
+    get_project_context: repositoryContextOutput,
+    get_action_status: z.looseObject({ proposal: int, operation: str, state: str, outcome: z.unknown(), finishedAt: nullable(str) }),
+    get_actions: z.looseObject({ actions: rows({ operation: str, label: str, secureReview: z.boolean(), inputs: z.array(str) }), notice: str }),
+    propose_action: cardDrafted,
+    propose_task_action: z.looseObject({ proposal: int, action: str, awaiting: str }),
+    get_controls: z.looseObject({ confirmedInChat: z.array(str), existingControls: rows({ id: str, label: str, needsTask: z.boolean(), needsProject: z.boolean() }), rule: str }),
+    show_control: z.looseObject({ card: int, label: str, action: str }),
+    get_result: z.looseObject({
+        task: str, root: str, currentExecution: str, run: int, title: str, feedback: list, feedbackTotal: int, nextFeedbackOffset: nullable(int),
+        changes: str, changesShortened: z.boolean(), verification: str, accepted: z.boolean(), evidenceTool: str, canRevise: z.boolean(),
+    }),
+    get_diff: z.looseObject({ task: str, run: int, files: rows({ path: str, added: int, removed: int }).optional(), file: str.optional(), diff: str.optional(), nextOffset: nullable(int).optional(), notice: nullable(str) }),
+    get_check_log: z.looseObject({ task: str, run: int, log: str, notice: nullable(str) }),
+    get_acceptance_evidence: z.looseObject({ task: str, run: int }),
+    get_result_images: z.looseObject({
+        task: str, run: int, imageCount: int, images: rows({ id: int, position: int, selected: z.boolean() }), selected: z.array(int), selectedCount: int,
+        sendCount: int, nextImageOffset: nullable(int), nextImageIds: z.array(int), unavailable: list, delivery: str,
+    }),
+    propose_review: proposed("review", { operation: z.enum(["note", "revise"]) }),
+    recap: recapOutput,
+    list_repos: z.looseObject({ repos: rows({ repo: str }) }),
+    get_project_tools: z.looseObject({ rule: str, tools: rows({ name: str }), connectBySigningIn: list, commonTools: list, foundOnThisComputer: list, notice: str }),
+    get_flows: z.union([
+        z.looseObject({ flow: int, name: str, steps: rows({ id: str, title: str, kind: str }), cards: rows({ card: int, title: str }), scripts: list, triggers: list, rule: str }),
+        z.looseObject({ flows: rows({ flow: int, name: str, cards: int, needYou: int, triggers: int }), templates: list, scripts: list, rule: str }),
+    ]),
+    propose_flow: cardDrafted,
+    get_teammates: z.looseObject({ teammates: rows({ teammate: int, name: str, working: z.boolean(), soul: str }), templates: list, rule: str }),
+    propose_teammate: cardDrafted,
+    get_flow_insights: z.union([
+        z.looseObject({ days: int, flows: rows({ flow: int, name: str }) }),
+        z.looseObject({ card: int, entry: int, state: str, log: str }),
+        z.looseObject({ runs: list, rule: str }),
+    ]),
+    get_skills: z.union([
+        z.looseObject({ version: str, instructions: str, nextOffset: nullable(int), notice: str }),
+        z.looseObject({ skills: list, nextOffset: nullable(int) }),
+    ]),
+    get_project_knowledge: z.looseObject({ revision: int }),
+    get_task_conversation: z.looseObject({ task: str, messages: rows({ from: z.enum(["operator", "lead"]), text: str, at: str }), notice: nullable(str) }),
+    commit_to: z.looseObject({ commitment: int, condition: str, expires: str, report: str }),
+    release_commitment: z.looseObject({ commitment: int, state: z.literal("cancelled") }),
+    remember: z.looseObject({ proposal: int, label: str, awaiting: str, executed: z.literal(false), next: str }),
+    get_person: z.union([z.looseObject({ person: z.looseObject({}) }), z.looseObject({ several: list, next: str })]),
+    get_integrations: z.looseObject({ integrations: rows({ name: str, kind: str, state: str }), settings: str }),
+    get_capabilities: z.looseObject({ projects: rows({ repo: str }), workers: z.unknown(), integrations: z.unknown(), rule: str }),
+    ask_owner: z.looseObject({ asked: str, options: z.array(str), shown: str }),
+    search_project_memory: z.looseObject({ hits: list, notice: str }),
+    get_models: z.looseObject({ roles: rows({ role: str }), tools: list, newModels: list, change: str }),
+    list_tasks: z.looseObject({ tasks: rows({ repo: str, task: str, execution: str, title: str, state: str, ageHours: z.number(), strikes: int }), truncated: z.boolean() }),
+    get_task: z.looseObject({
+        repo: str, task: str, root: str, currentExecution: str, title: str, state: str, deliverable: str, scope: str,
+        queue: nullable(z.looseObject({ position: int, of: int, column: str })), holds: list, attempts: int, decisionsOpen: int, dependencies: list,
+    }),
+    get_agents: z.looseObject({ repo: str, task: str, risk: z.looseObject({ level: str }), standing: str, agents: list, choices: z.looseObject({}), approval: str, organisationPolicy: z.looseObject({}) }),
+    list_decisions: decisionsOutput,
+    get_decision: decisionOutput,
+    queue: z.looseObject({ repo: str, queueRevision: int, ...queueColumnsOutput }),
+    propose_task: proposed("task", { repo: str, deliverable: z.enum(["branch", "report"]), planning: str }),
+    propose_next: proposed("next", { task: str }),
+    propose_reserve: proposed("reserve", { task: str, worker: nullable(str) }),
+    propose_hold: proposed("hold", { task: str }),
+    propose_unhold: proposed("unhold", { task: str }),
+    propose_steer: proposed("steer", { task: str }),
+    propose_dependency_repair: proposed("repair", { task: str, blocker: str, operation: z.enum(["retry", "unlink", "replace"]) }),
+    propose_scope: proposed("scope", { task: str }),
+    propose_agents: proposed("agents", { task: str }),
+    propose_answer: proposed("answer", { decision: int, option: str }),
+    propose_cancel: proposed("cancel", { task: str }),
+};
+/**
+ * Report a result that disagrees with its output schema without hiding the actual result, including under Vitest.
+ * Contract tests assert output shapes directly; executing a tool always writes the diagnostic and returns its result.
+ */
+export function reportToolOutput(surface, tool, schema, body) {
+    const read = parseContract(schema, body);
+    if (read.ok)
+        return;
+    const line = `${surface} tool ${tool}: its result disagrees with its output schema — ${read.issues.map(one => one.line).join("; ")}`;
+    process.stderr.write(`${line}\n`);
+}

package/dist/contracts/memory-pass.d.ts

@@ -0,0 +1,158 @@
+/**
+ * The memory pass (memory-pass.ts): one schema for the verdict a model returns on one session — the analyser's
+ * `--json-schema` (Codex's output schema), with a tolerant read side for older answers — the verdict each session keeps
+ * (`memory_session.verdict`), and a proposal with its evidence (`memory_proposal`). What JSON Schema cannot state —
+ * a quote really in the trace, an instruction id on the surface audited — is checked in plain code after parsing.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+export declare const MEMORY_EFFECTS: readonly ["harm", "non-compliance", "irrelevant"];
+export declare const MEMORY_DOMAINS: readonly ["project", "orchestration"];
+export declare const MEMORY_PROPOSAL_KINDS: readonly ["instruction-add", "instruction-remove", "decision-add"];
+/** The verdict a model returns on one session. */
+export declare const memoryVerdictSchema: z.ZodObject<{
+    positive: z.ZodArray<z.ZodObject<{
+        instruction: z.ZodString;
+        effect: z.ZodString;
+        quote: z.ZodString;
+    }, z.core.$strict>>;
+    negative: z.ZodArray<z.ZodObject<{
+        instruction: z.ZodString;
+        effect: z.ZodString;
+        class: z.ZodEnum<{
+            harm: "harm";
+            irrelevant: "irrelevant";
+            "non-compliance": "non-compliance";
+        }>;
+        quote: z.ZodString;
+    }, z.core.$strict>>;
+    gaps: z.ZodArray<z.ZodObject<{
+        mistake: z.ZodString;
+        proposedInstruction: z.ZodString;
+        domain: z.ZodEnum<{
+            orchestration: "orchestration";
+            project: "project";
+        }>;
+        quote: z.ZodString;
+        matchesGap: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** What the analyser is told to return: `--json-schema` for Claude, the output schema for Codex, and the prompt for
+ * every other provider. */
+export declare const MEMORY_VERDICT_MODEL_SCHEMA: Record<string, unknown>;
+export type Verdict = z.infer<typeof memoryVerdictSchema>;
+export declare const memoryVerdictReadSchema: z.ZodObject<{
+    positive: z.ZodCatch<z.ZodArray<z.ZodCatch<z.ZodNullable<z.ZodPipe<z.ZodObject<{
+        quote: z.ZodString;
+    }, z.core.$loose>, z.ZodTransform<{
+        quote: string;
+        claim: {
+            quote: string;
+            instruction: string;
+            effect: string;
+        } | null;
+    }, {
+        [x: string]: unknown;
+        quote: string;
+    }>>>>>>;
+    negative: z.ZodCatch<z.ZodArray<z.ZodCatch<z.ZodNullable<z.ZodPipe<z.ZodObject<{
+        quote: z.ZodString;
+    }, z.core.$loose>, z.ZodTransform<{
+        quote: string;
+        claim: {
+            quote: string;
+            instruction: string;
+            effect: string;
+            class: "harm" | "irrelevant" | "non-compliance";
+        } | null;
+    }, {
+        [x: string]: unknown;
+        quote: string;
+    }>>>>>>;
+    gaps: z.ZodCatch<z.ZodArray<z.ZodCatch<z.ZodNullable<z.ZodPipe<z.ZodObject<{
+        quote: z.ZodString;
+    }, z.core.$loose>, z.ZodTransform<{
+        quote: string;
+        claim: {
+            quote: string;
+            mistake: string;
+            proposedInstruction: string;
+            domain: "orchestration" | "project";
+            matchesGap: string | null;
+        } | null;
+    }, {
+        [x: string]: unknown;
+        quote: string;
+    }>>>>>>;
+}, z.core.$strip>;
+export declare const MEMORY_VERDICT_VERSION = 1;
+/** A verdict as a session keeps it. */
+export declare const savedVerdictSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    positive: z.ZodArray<z.ZodObject<{
+        instruction: z.ZodString;
+        effect: z.ZodString;
+        quote: z.ZodString;
+    }, z.core.$strict>>;
+    negative: z.ZodArray<z.ZodObject<{
+        instruction: z.ZodString;
+        effect: z.ZodString;
+        class: z.ZodEnum<{
+            harm: "harm";
+            irrelevant: "irrelevant";
+            "non-compliance": "non-compliance";
+        }>;
+        quote: z.ZodString;
+    }, z.core.$strict>>;
+    gaps: z.ZodArray<z.ZodObject<{
+        mistake: z.ZodString;
+        proposedInstruction: z.ZodString;
+        domain: z.ZodEnum<{
+            orchestration: "orchestration";
+            project: "project";
+        }>;
+        quote: z.ZodString;
+        matchesGap: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type SavedVerdict = z.infer<typeof savedVerdictSchema>;
+/**
+ * A verdict kept before it carried `version` (through 0.9.36), as version 1. Those left a gap's `matchesGap` out when
+ * there was none; that reads as null. Values are never rewritten.
+ */
+export declare function upgradeVerdictV0(body: Record<string, unknown>): Record<string, unknown>;
+export declare const MEMORY_VERDICT_UPGRADES: {
+    readonly 0: typeof upgradeVerdictV0;
+};
+/** Read a kept verdict: version 1 as itself, an unversioned one upgraded, a newer one refused plainly. */
+export declare function readSavedVerdict(input: unknown): ContractResult<SavedVerdict>;
+/** One corroborating sighting: the session and its verbatim quote. A proposal keeps at most six. */
+export declare const memoryEvidenceSchema: z.ZodArray<z.ZodObject<{
+    session: z.ZodString;
+    quote: z.ZodString;
+}, z.core.$strict>>;
+export type MemoryEvidence = z.infer<typeof memoryEvidenceSchema>;
+/** A proposal as its row reads; its evidence is a JSON list (an older runtime reads it as one, so it has no envelope). */
+export declare const memoryProposalSchema: z.ZodObject<{
+    id: z.ZodInt;
+    repo: z.ZodString;
+    kind: z.ZodEnum<{
+        "decision-add": "decision-add";
+        "instruction-add": "instruction-add";
+        "instruction-remove": "instruction-remove";
+    }>;
+    fingerprint: z.ZodString;
+    title: z.ZodString;
+    rationale: z.ZodString;
+    beforeText: z.ZodNullable<z.ZodString>;
+    afterText: z.ZodString;
+    evidence: z.ZodArray<z.ZodObject<{
+        session: z.ZodString;
+        quote: z.ZodString;
+    }, z.core.$strict>>;
+    sessions: z.ZodInt;
+    status: z.ZodString;
+    createdAt: z.ZodString;
+    surface: z.ZodString;
+}, z.core.$strict>;
+export type MemoryProposal = z.infer<typeof memoryProposalSchema>;

package/dist/contracts/memory-pass.js

@@ -0,0 +1,102 @@
+/**
+ * The memory pass (memory-pass.ts): one schema for the verdict a model returns on one session — the analyser's
+ * `--json-schema` (Codex's output schema), with a tolerant read side for older answers — the verdict each session keeps
+ * (`memory_session.verdict`), and a proposal with its evidence (`memory_proposal`). What JSON Schema cannot state —
+ * a quote really in the trace, an instruction id on the surface audited — is checked in plain code after parsing.
+ */
+import { z } from "zod";
+import { TEXT_LIMITS } from "../text-limits.js";
+import { limited, readVersioned, toModelSchema, versioned } from "./contract.js";
+export const MEMORY_EFFECTS = ["harm", "non-compliance", "irrelevant"];
+export const MEMORY_DOMAINS = ["project", "orchestration"];
+export const MEMORY_PROPOSAL_KINDS = ["instruction-add", "instruction-remove", "decision-add"];
+const bounded = limited;
+const saved = () => z.string();
+const verdictShape = (text) => {
+    const instruction = z.string().describe("An instruction's id from INSTRUCTIONS, such as IN-001.");
+    const quote = text("quote", "memoryTrace").describe("Copied verbatim from the trace, at least 12 characters.");
+    return {
+        positive: z.array(z.strictObject({ instruction, effect: text("effect", "memoryEffect"), quote })),
+        negative: z.array(z.strictObject({ instruction, effect: text("effect", "memoryEffect"), class: z.enum(MEMORY_EFFECTS), quote })),
+        gaps: z.array(z.strictObject({
+            mistake: text("mistake", "memoryMistake"),
+            proposedInstruction: text("proposed instruction (one imperative sentence)", "memoryInstruction"),
+            domain: z.enum(MEMORY_DOMAINS),
+            quote,
+            matchesGap: z.string().nullable().describe("The key of a gap already on the books when it is the same underlying gap, otherwise null."),
+        })),
+    };
+};
+/** The verdict a model returns on one session. */
+export const memoryVerdictSchema = z.strictObject(verdictShape(bounded));
+/** What the analyser is told to return: `--json-schema` for Claude, the output schema for Codex, and the prompt for
+ * every other provider. */
+export const MEMORY_VERDICT_MODEL_SCHEMA = toModelSchema(memoryVerdictSchema);
+/** Parse-side compatibility with the pre-Zod analyser: clip with the same trailing ellipsis, coerce effects and
+ * instruction ids, default gap metadata, ignore unknown keys and discard bad claims individually. These transforms
+ * never enter the strict model schema. */
+const clipped = (key) => z.string().transform(text => text.length > TEXT_LIMITS[key] ? `${text.slice(0, TEXT_LIMITS[key])}…` : text);
+const readShape = verdictShape(saved);
+const effectFields = {
+    instruction: z.coerce.string(),
+    effect: z.preprocess(value => String(value ?? ""), clipped("memoryEffect")),
+};
+/** Keep the quote even when a claim is bad: the old reader applied its twenty-quote cap before dropping bad claims. */
+function readClaims(schema) {
+    return z.array(z.looseObject({ quote: z.string() }).transform(input => {
+        const parsed = schema.safeParse(input);
+        return { quote: input.quote, claim: parsed.success ? parsed.data : null };
+    }).nullable().catch(null)).catch([]);
+}
+export const memoryVerdictReadSchema = memoryVerdictSchema.strip().extend({
+    positive: readClaims(readShape.positive.element.strip().extend(effectFields)),
+    negative: readClaims(readShape.negative.element.strip().extend({
+        ...effectFields,
+        class: z.coerce.string().pipe(readShape.negative.element.shape.class),
+    })),
+    gaps: readClaims(readShape.gaps.element.strip().extend({
+        mistake: clipped("memoryMistake"),
+        proposedInstruction: clipped("memoryInstruction"),
+        domain: z.preprocess(value => value === "orchestration" ? value : "project", readShape.gaps.element.shape.domain),
+        matchesGap: readShape.gaps.element.shape.matchesGap.catch(null),
+    })),
+});
+export const MEMORY_VERDICT_VERSION = 1;
+/** A verdict as a session keeps it. */
+export const savedVerdictSchema = versioned(MEMORY_VERDICT_VERSION, verdictShape(saved));
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * A verdict kept before it carried `version` (through 0.9.36), as version 1. Those left a gap's `matchesGap` out when
+ * there was none; that reads as null. Values are never rewritten.
+ */
+export function upgradeVerdictV0(body) {
+    const gaps = body["gaps"];
+    return {
+        version: MEMORY_VERDICT_VERSION,
+        ...body,
+        ...(Array.isArray(gaps) ? { gaps: gaps.map(gap => (isRecord(gap) && !Object.prototype.hasOwnProperty.call(gap, "matchesGap") ? { ...gap, matchesGap: null } : gap)) } : {}),
+    };
+}
+export const MEMORY_VERDICT_UPGRADES = { 0: upgradeVerdictV0 };
+/** Read a kept verdict: version 1 as itself, an unversioned one upgraded, a newer one refused plainly. */
+export function readSavedVerdict(input) {
+    return readVersioned(savedVerdictSchema, input, MEMORY_VERDICT_UPGRADES);
+}
+/** One corroborating sighting: the session and its verbatim quote. A proposal keeps at most six. */
+export const memoryEvidenceSchema = z.array(z.strictObject({ session: z.string(), quote: z.string() })).max(6);
+/** A proposal as its row reads; its evidence is a JSON list (an older runtime reads it as one, so it has no envelope). */
+export const memoryProposalSchema = z.strictObject({
+    id: z.int(),
+    repo: z.string(),
+    kind: z.enum(MEMORY_PROPOSAL_KINDS),
+    fingerprint: z.string(),
+    title: z.string(),
+    rationale: z.string(),
+    beforeText: z.string().nullable(),
+    afterText: z.string(),
+    evidence: memoryEvidenceSchema,
+    sessions: z.int(),
+    status: z.string(),
+    createdAt: z.string(),
+    surface: z.string(),
+});

package/dist/contracts/project-knowledge.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Project knowledge (project-knowledge.ts): one schema for the saved knowledge (instructions and references, every
+ * revision in `knowledge_change` and the current one in `project_knowledge`), and for the selection a run is given and
+ * keeps (`knowledge_snapshot`). The rules JSON Schema cannot state — UTF-8 byte limits, control characters, secrets,
+ * the selection's total size — run in plain code when knowledge is written. A saved payload's digest is checked
+ * against its stored bytes before it is parsed, and it is upgraded only in memory: stored bytes are never rewritten.
+ */
+import { z } from "zod";
+import type { RepositoryContext } from "../repository-context.js";
+import { type ContractResult } from "./contract.js";
+/** How many references a project keeps, and how many a run is given. Text limits live in TEXT_LIMITS. */
+export declare const KNOWLEDGE_COUNTS: {
+    readonly references: 12;
+    readonly selected: 3;
+    readonly decisions: 8;
+};
+export declare const KNOWLEDGE_VERSION = 1;
+/** Knowledge as it is written. */
+export declare const knowledgeSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    instructions: z.ZodString;
+    references: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        content: z.ZodString;
+        path: z.ZodNullable<z.ZodString>;
+        sourceSha: z.ZodNullable<z.ZodString>;
+        sourceRevision: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Knowledge as it is read back. */
+export declare const savedKnowledgeSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    instructions: z.ZodString;
+    references: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        content: z.ZodString;
+        path: z.ZodNullable<z.ZodString>;
+        sourceSha: z.ZodNullable<z.ZodString>;
+        sourceRevision: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Knowledge as every reader returns it: the payload without its envelope. */
+export type Knowledge = Omit<z.infer<typeof knowledgeSchema>, "version">;
+export type KnowledgeReference = Knowledge["references"][number];
+/**
+ * Knowledge saved before it carried `version` (through 0.9.36: `{instructions, references}`), as version 1. Its
+ * readers took the fields they knew, so this keeps exactly those; values are never rewritten.
+ */
+export declare function upgradeKnowledgeV0(body: Record<string, unknown>): Record<string, unknown>;
+export declare const KNOWLEDGE_UPGRADES: {
+    readonly 0: typeof upgradeKnowledgeV0;
+};
+/** Read saved knowledge: version 1 as itself, an unversioned one upgraded, a newer one refused plainly. */
+export declare function readKnowledge(input: unknown): ContractResult<Knowledge>;
+/** What a person drafts on the Knowledge page or the CLI; each action reads the fields it needs. */
+export declare const knowledgeDraftSchema: z.ZodObject<{
+    instructions: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    content: z.ZodOptional<z.ZodString>;
+    path: z.ZodOptional<z.ZodString>;
+    id: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type KnowledgeDraft = z.infer<typeof knowledgeDraftSchema>;
+/** A source a run was not given, and why. */
+export declare const knowledgeOmissionSchema: z.ZodObject<{
+    title: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strict>;
+export declare const KNOWLEDGE_SELECTION_VERSION = 1;
+/** The selection a run is given, as it is frozen. The keys are in the order a selection has always been written. */
+export declare const knowledgeSelectionSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    revision: z.ZodInt;
+    instructions: z.ZodString;
+    references: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        content: z.ZodString;
+        path: z.ZodNullable<z.ZodString>;
+        sourceSha: z.ZodNullable<z.ZodString>;
+        sourceRevision: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    omitted: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strict>>;
+    inheritedFrom: z.ZodNullable<z.ZodInt>;
+    decisions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodInt;
+        claim: z.ZodString;
+        decidedAt: z.ZodString;
+    }, z.core.$strict>>>;
+    repository: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
+}, z.core.$strict>;
+/** A frozen selection as it is read back. */
+export declare const savedKnowledgeSelectionSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    revision: z.ZodInt;
+    instructions: z.ZodString;
+    references: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        content: z.ZodString;
+        path: z.ZodNullable<z.ZodString>;
+        sourceSha: z.ZodNullable<z.ZodString>;
+        sourceRevision: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    omitted: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strict>>;
+    inheritedFrom: z.ZodNullable<z.ZodInt>;
+    decisions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodInt;
+        claim: z.ZodString;
+        decidedAt: z.ZodString;
+    }, z.core.$strict>>>;
+    repository: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
+}, z.core.$strict>;
+export type KnowledgeSelection = Omit<z.infer<typeof knowledgeSelectionSchema>, "repository"> & {
+    repository?: RepositoryContext;
+};
+/** Read a frozen selection: version 1 (every selection ever frozen) as itself, a newer one refused plainly. */
+export declare function readKnowledgeSelection(input: unknown): ContractResult<KnowledgeSelection>;