toolroll 0.9.32 → 0.9.34

package/dist/operate.js

@@ -48,7 +48,7 @@ import { loadSlackCredentials } from "./slack-api.js";
 import { followSlack } from "./slack.js";
 import { validateScopeText } from "./task-text.js";
 import { runMemoryCommand } from "./memory-cli.js";
-import { runKnowledgeCommand } from "./knowledge-cli.js";
+import { runKnowledgeApply, runKnowledgeCommand } from "./knowledge-cli.js";
 import { FLOWS_VALUE_FLAGS, runFlowsCommand } from "./flows-cli.js";
 import { runAssignmentCommand } from "./assignment-adapters.js";
 import { applyProjectProfile, runProjectCommand } from "./project-cli.js";
@@ -93,6 +93,7 @@ import { pushPass } from "./push.js";
 import { chmodSync, closeSync, constants as fsConstants, existsSync, fstatSync, fsyncSync, openSync, readFileSync, readSync, realpathSync, renameSync, unlinkSync, writeSync, writeFileSync, mkdirSync } from "node:fs";
 import { BRANCH_PREFIX, envTwins, envValue, existingOrFirst, namedPath, taskBranches } from "./names.js";
 import { claimActor, currentActor, parseLeadToken, withActor } from "./actor.js";
+import { admissionRecorded, admitProject, commandLineActor } from "./project-admission.js";
 import { leadClaim, leadSay, noteLeadWork } from "./lead-voice.js";
 import { createServer as createNetServer } from "node:net";
 import { spawn as spawnChild } from "node:child_process";
@@ -162,7 +163,7 @@ import { attendedLivenessState } from "./liveness.js";
 import { HeldSessionCoordinator, sweepHeldOrphans } from "./held.js";
 import { proposeGrant, describeGrant, describeWithheld, permits, MUTATION_CLASSES, DEFAULT_MUTATIONS, } from "./grant.js";
 import { builtIn, guarded } from "./backend.js";
-import { register, authenticate, heartbeat as heartbeatRunner, isAlive, recoverDead, recoveredAnything, acquireWatchLeaseAuthed, heartbeatWatchLeaseAuthed, addRunnerReposAuthed, registerRunnerIfIdle, retireRunnerIfCurrent, normalizeRunnerName, validRunnerName, canonicalRepos, RUNNER_NAME_MAX, RUNNER_CAPACITY_MAX, parseRunnerCapacity, } from "./runner.js";
+import { register, authenticate, heartbeat as heartbeatRunner, isAlive, recoverDead, recoveredAnything, acquireWatchLeaseAuthed, heartbeatWatchLeaseAuthed, addRunnerReposAuthed, removeRunnerRepoAuthed, registerRunnerIfIdle, retireRunnerIfCurrent, normalizeRunnerName, validRunnerName, canonicalRepos, RUNNER_NAME_MAX, RUNNER_CAPACITY_MAX, parseRunnerCapacity, } from "./runner.js";
 import { mintCoordinator, revokeCoordinator, listCoordinators } from "./coordinator.js";
 import { serveMcp } from "./mcp.js";
 import { createInterface } from "node:readline";
@@ -1009,8 +1010,18 @@ async function dispatch(command, positional, flags, context) {
             if (positional[0] === "claim" && currentActor()?.lead === true && !flags.has("token-env") && !flags.has("token-file"))
                 return leadClaimCommand(positional, flags, context);
             return runAssignmentCommand(positional, flags, context);
-        case "knowledge":
-            return runKnowledgeCommand(positional, flags, { ...context, now: context.clock() });
+        case "knowledge": {
+            if (positional[0] !== "apply")
+                return runKnowledgeCommand(positional, flags, { ...context, now: context.clock() });
+            if (positional.length !== 1)
+                return fail(context.write, context.json, "knowledge apply", "usage", "knowledge apply takes no query.", EXIT.usage);
+            // A person's password, never the lead's token: the lead may not carry knowledge forward.
+            const acting = currentActor()?.lead === true ? null : await askCredentials(flags, context);
+            const repo = text(flags, "repo");
+            const lead = acting !== null && parseLeadToken(acting.token) !== null;
+            const verified = acting === null || lead ? null : authenticateApprover(context.store, acting.name, acting.token, repo === undefined ? null : resolve(repo));
+            return runKnowledgeApply(flags, { ...context, now: context.clock(), actor: verified !== null && verified.ok ? acting.name : null });
+        }
         case "models": {
             const acting = await askCredentials(flags, context);
             const verified = acting === null ? null : authenticateApprover(context.store, acting.name, acting.token);
@@ -4924,6 +4935,7 @@ async function startConsole(options) {
         ...(options.repos === undefined ? {} : { repos: options.repos }),
         ...(options.projectRoots === undefined ? {} : { projectRoots: options.projectRoots }),
         ...(options.currentRepos === undefined ? {} : { currentRepos: options.currentRepos }),
+        ...(options.admittedRepos === undefined ? {} : { admittedRepos: options.admittedRepos }),
         ...(options.publicUrl === undefined ? {} : { publicUrl: options.publicUrl }),
         ...(options.registryPath === undefined ? {} : { registryPath: options.registryPath }),
         ...(options.upConsole === undefined ? {} : { upConsole: options.upConsole }),
@@ -8350,12 +8362,15 @@ async function onboardCommand(flags, context) {
             return !("error" in registry) && registry.repos.includes(repo);
         },
         enroll: async (repo) => {
+            // The same admission as `repos add` and the console's Add a project.
+            const actor = commandLineActor(store, { databaseFile: context.databaseFile });
+            if ("ok" in actor)
+                return { ok: false, message: actor.message };
             const before = await loadProjectRegistry(registryPath);
-            const enrolled = await updateRepos(registryPath, repos => addRepos(repos, [repo]));
-            if (!enrolled.ok)
-                return { ok: false, message: enrolled.message };
-            store.upsertProject(repo, projectName(repo), clock());
-            return { ok: true, added: "error" in before || !before.repos.includes(repo) };
+            const admitted = await admitProject(store, { registryFile: registryPath, path: repo, actor, now: clock() });
+            if (!admitted.ok)
+                return { ok: false, message: admitted.message };
+            return { ok: true, added: "error" in before || !before.repos.includes(admitted.repo) };
         },
         checkConnection: seams.checkConnection ?? (agent => checker(agent)),
         pullRequests: seams.pullRequests ?? (async (repo) => {
@@ -8485,6 +8500,9 @@ async function upCommand(flags, context) {
         }
     }
     const explicitRepos = context.repoList ?? [];
+    // Repositories this start was told to serve stay served while it runs: removing one from the saved list takes
+    // effect at the next start, never under the process that was pinned to it.
+    const pinnedRepos = new Set();
     if (explicitRepos.length > 0) {
         for (const input of explicitRepos) {
             const root = await proveRepo(input);
@@ -8493,12 +8511,15 @@ async function upCommand(flags, context) {
             }
             if (!repos.includes(root))
                 repos.push(root);
+            pinnedRepos.add(root);
         }
     }
     else if (context.inferProjectFromCwd !== false) {
         const cwdRepo = await proveRepo(process.cwd());
         if (cwdRepo !== null && !repos.includes(cwdRepo))
             repos.push(cwdRepo);
+        if (cwdRepo !== null)
+            pinnedRepos.add(cwdRepo);
     }
     if (repos.length === 0 && projectRoots.length === 0) {
         return fail(write, json, "up", "no-projects", "choose where your projects live once: `toolroll up --project-root <dir>`", EXIT.refused);
@@ -8650,6 +8671,7 @@ async function upCommand(flags, context) {
             poolRoot: pool,
             repos,
             currentRepos: () => [...activeRepos],
+            admittedRepos: () => [...activeRepos],
             upConsole: true,
             attended: {
                 runner: runnerName,
@@ -8742,6 +8764,8 @@ async function upCommand(flags, context) {
     // One record of project passes for the whole service: fair scheduling
     // across its projects (project-concurrency.ts).
     const projectPasses = new ProjectPasses();
+    // Projects removed while running: each one's watch stops admitting work, finishes what it holds, then lets go.
+    const releasedRepos = new Set();
     const launchRepo = async (repo, bind) => {
         if (loopResults.has(repo) || stopping)
             return;
@@ -8766,7 +8790,7 @@ async function upCommand(flags, context) {
             token: runnerToken,
             repo,
             progress: line => progress(`${prefix(repo)}${line}`),
-            isStopping: () => stopping,
+            isStopping: () => stopping || releasedRepos.has(repo),
             onFollowController: controller => followControllers.push(controller),
             containmentLines,
             passes: projectPasses,
@@ -8779,6 +8803,19 @@ async function upCommand(flags, context) {
         }).then(result => ({ repo, result }), error => ({ repo, result: { ok: false, reason: "loop-failed", detail: describe(error), ticks: 0, built: 0, broke: 0 } }));
         loopResults.set(repo, loop);
         void loop.then(({ repo: endedRepo, result }) => {
+            if (releasedRepos.has(endedRepo) && !stopping) {
+                // A removed project's watch has stopped: only now does the builder let go of it.
+                const unbound = removeRunnerRepoAuthed(store, { name: runnerName, token: runnerToken, repo: endedRepo }, clock());
+                if (!unbound.ok) {
+                    fatal = `the builder identity changed while removing ${endedRepo} (${unbound.reason})`;
+                    stop();
+                }
+                loopResults.delete(endedRepo);
+                releasedRepos.delete(endedRepo);
+                progress(`project removed — ${projectName(endedRepo)} is no longer built here`);
+                markReady();
+                return;
+            }
             // A loop that dies while its siblings live must not leave a partial
             // cockpit standing silently (finding 5).
             if (!result.ok && !stopping) {
@@ -8832,19 +8869,34 @@ async function upCommand(flags, context) {
                 stop();
                 break;
             }
+            // Removed from the saved list: stop building it and take it out of the console. A pinned start keeps its own.
+            const saved = new Set(loaded.repos.map(one => canonicalProject(one) ?? one));
+            for (const repo of [...activeRepos]) {
+                if (stopping || pinnedRepos.has(repo) || saved.has(repo))
+                    continue;
+                activeRepos.delete(repo);
+                releasedRepos.add(repo);
+                if (!loopResults.has(repo))
+                    releasedRepos.delete(repo);
+            }
             for (const candidate of loaded.repos) {
                 if (stopping)
                     break;
                 const canonical = canonicalProject(candidate);
-                if (canonical !== null && activeRepos.has(canonical))
+                // Still letting go of an earlier removal: it rejoins on the next pass after its watch has stopped.
+                if (canonical !== null && (activeRepos.has(canonical) || releasedRepos.has(canonical)))
                     continue;
                 const approvedAdditions = context.additionalProjectRepos?.() ?? [];
                 const admittedCeiling = resolveCeiling([...dynamicCeiling.repos, ...approvedAdditions], dynamicCeiling.roots).ceiling;
-                const allowed = canonical !== null && (await authorizedProject(admittedCeiling, canonical)) && (await proveRepo(canonical)) === canonical;
+                // A project added after this start (`repos add`, the lead, the console) carries its recorded admission; a
+                // registry line alone is not authority. Either way the folder is proved to be that Git checkout again.
+                const allowed = canonical !== null &&
+                    ((await authorizedProject(admittedCeiling, canonical)) || admissionRecorded(store, canonical)) &&
+                    (await proveRepo(canonical)) === canonical;
                 if (!allowed) {
                     if (!rejected.has(candidate)) {
                         rejected.add(candidate);
-                        progress(`project not connected — ${candidate} is not a Git repository inside a saved projects folder`);
+                        progress(`project not connected — ${candidate} isn't a Git repository added with \`toolroll repos add\` or the console`);
                     }
                     continue;
                 }

package/dist/plan.d.ts

@@ -6,6 +6,7 @@
  * the scope proposal is authority-bearing, so it gets the park discipline).
  */
 import { type AcceptanceCriterion } from "./scope.js";
+import type { ContractIssue } from "./contracts/contract.js";
 export type PlanProblem = {
     reason: string;
     message: string;
@@ -69,18 +70,17 @@ export type PlanParseResult = {
     ok: false;
     problems: PlanProblem[];
 };
-/** Caps matching the scope ritual's fields, plus the document itself. The goal and out-of-scope text share the
- * task's own limit: a plan reproduces the filed contract exactly, so a lower cap here would refuse every plan for a
- * long goal. */
-export declare const PLAN_LIMITS: {
-    readonly payload: number;
-    readonly goal: 8000;
-    readonly outOfScope: 8000;
-    readonly touch: 200;
-    readonly touches: 32;
-    readonly document: number;
-    readonly amendment: 1000;
-};
+/**
+ * A contract issue as a plan problem: the path-named line is the message, and the reason keeps the codes the rest of
+ * the code relies on — `missing-goal`, `bad-touches`, `plan-too-long`, `amendment-too-long`, `acceptance-too-many` —
+ * so repair eligibility (document-only problems) and durable outcomes read the same as before the contract.
+ */
+export declare function planProblemOf(issue: ContractIssue): PlanProblem;
+/**
+ * The planner's handoff, read against the plan contract (src/contracts/plan.ts): fail closed, every problem at once,
+ * each one naming its path (`acceptance[0].evidence[0]: must be one of ...`). A plan saved before plans carried
+ * `version` reads as it always did.
+ */
 export declare function parsePlan(raw: string): PlanParseResult;
 export type MilestoneState = "pending" | "current" | "completed" | "blocked";
 export type Milestone = {

package/dist/plan.js

@@ -9,16 +9,17 @@ import { createHash } from "node:crypto";
 import { hasForbiddenControls } from "./decision.js";
 import { parseAcceptanceCriteria } from "./scope.js";
 import { TEXT_LIMITS } from "./text-limits.js";
+import { planPayloadBody, readPlanPayload } from "./contracts/plan.js";
 const EXECUTION_PLAN_SECTIONS = ["approach", "milestones", "dependencies", "risks", "proof"];
 const EXECUTION_PLAN_LIST_CAP = 12;
-const EXECUTION_PLAN_ITEM_CAP = 600;
+const EXECUTION_PLAN_ITEM_CAP = TEXT_LIMITS.planItem;
 /** Parse the planner's human-readable artifact without executing Markdown.
  * Older free-form plan artifacts remain renderable through the caller's
  * fallback, while every newly accepted planner handoff uses this shape. */
 export function parseExecutionPlanDocument(raw) {
     const problems = [];
-    if (Buffer.byteLength(raw, "utf8") > PLAN_LIMITS.document) {
-        return { ok: false, problems: [{ reason: "plan-too-long", message: `plan is over ${PLAN_LIMITS.document} bytes` }] };
+    if (Buffer.byteLength(raw, "utf8") > TEXT_LIMITS.planDocumentBytes) {
+        return { ok: false, problems: [{ reason: "plan-too-long", message: `plan is over ${TEXT_LIMITS.planDocumentBytes} bytes` }] };
     }
     const normalized = raw.replace(/\r\n?/g, "\n");
     if (hasForbiddenControls(normalized)) {
@@ -63,8 +64,8 @@ export function parseExecutionPlanDocument(raw) {
     const approach = (sections.get("approach") ?? []).join("\n").trim();
     if (approach === "")
         problems.push({ reason: "plan-empty-approach", message: "Approach must say how the work will be done" });
-    if (approach.length > 2_000)
-        problems.push({ reason: "plan-approach-too-long", message: "Approach is over 2000 characters" });
+    if (approach.length > TEXT_LIMITS.planApproach)
+        problems.push({ reason: "plan-approach-too-long", message: `Approach is over ${TEXT_LIMITS.planApproach} characters` });
     const list = (name) => {
         const items = [];
         for (const line of sections.get(name) ?? []) {
@@ -128,18 +129,6 @@ export function renderExecutionPlanDocument(document) {
         "",
     ].join("\n");
 }
-/** Caps matching the scope ritual's fields, plus the document itself. The goal and out-of-scope text share the
- * task's own limit: a plan reproduces the filed contract exactly, so a lower cap here would refuse every plan for a
- * long goal. */
-export const PLAN_LIMITS = {
-    payload: 64 * 1024,
-    goal: TEXT_LIMITS.goal,
-    outOfScope: TEXT_LIMITS.goal,
-    touch: 200,
-    touches: 32,
-    document: 16 * 1024,
-    amendment: 1_000,
-};
 function refuse(reason, message) {
     return { ok: false, problems: [{ reason, message }] };
 }
@@ -152,6 +141,7 @@ function describe(value) {
         return `a ${value.length}-char string`;
     return `a ${Array.isArray(value) ? "array" : typeof value}`;
 }
+/** A progress note or revision field, checked by hand (those payloads are not on the plan contract yet). */
 function prose(value, field, cap, required, problems) {
     if (value === undefined || value === null || value === "") {
         if (required)
@@ -172,75 +162,142 @@ function prose(value, field, cap, required, problems) {
     }
     return value;
 }
-export function parsePlan(raw) {
-    if (Buffer.byteLength(raw, "utf8") > PLAN_LIMITS.payload) {
-        return refuse("too-large", `the payload is over ${PLAN_LIMITS.payload} bytes`);
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
+/**
+ * A contract issue as a plan problem: the path-named line is the message, and the reason keeps the codes the rest of
+ * the code relies on — `missing-goal`, `bad-touches`, `plan-too-long`, `amendment-too-long`, `acceptance-too-many` —
+ * so repair eligibility (document-only problems) and durable outcomes read the same as before the contract.
+ */
+export function planProblemOf(issue) {
+    const at = issue.path;
+    const reason = (() => {
+        switch (issue.kind) {
+            case "required":
+            case "empty":
+            case "too-few":
+                return `missing-${at}`;
+            case "too-long":
+                return `${at}-too-long`;
+            case "too-many":
+                return `${at}-too-many`;
+            case "unknown-key":
+                return `${at}-unknown-key`;
+            case "newer-version":
+                return "newer-version";
+            default:
+                return `bad-${at}`;
+        }
+    })();
+    return { reason, message: issue.line };
+}
+/** scope.ts's rubric problem as a path-named line: `acceptance[0].id: is over 40 bytes`. */
+function acceptanceLine(problem) {
+    const named = /^(acceptance(?:\[\d+\])?(?:\.[A-Za-z]+)?) (.*)$/.exec(problem.message);
+    if (named !== null)
+        return `${named[1]}: ${named[2]}`;
+    const at = /^(acceptance\[\d+\])-/.exec(problem.reason)?.[1] ?? "acceptance";
+    return `${at}: ${problem.message}`;
+}
+/** True when `problems` name `field` or anything under it. */
+const touched = (problems, field) => problems.some(problem => problem.message.startsWith(`${field}:`) || problem.message.startsWith(`${field}[`) || problem.message.startsWith(`${field}.`));
+/**
+ * The rules JSON Schema cannot state, in plain code with named errors: control characters, one-line touches, the
+ * document's byte cap and sections, the acceptance rubric's byte limits and duplicate ids (scope.ts's own parser),
+ * and the Proof naming every criterion. Fields the contract already refused are skipped, so every problem is
+ * reported once and all at once.
+ */
+function planRuleProblems(body, contract) {
+    const problems = [];
+    const text = (field) => {
+        const value = body[field];
+        return typeof value === "string" && !touched(contract, field) ? value : null;
+    };
+    for (const field of ["goal", "outOfScope", "plan", "amendment"]) {
+        const value = text(field);
+        if (value !== null && hasForbiddenControls(value)) {
+            problems.push({ reason: `${field}-controls`, message: `${field}: carries control characters that could become terminal escapes` });
+        }
     }
-    catch (error) {
-        return refuse("not-json", `the payload is not JSON: ${error instanceof Error ? error.message : String(error)}`);
+    const touches = body["touches"];
+    if (Array.isArray(touches) && !touched(contract, "touches")) {
+        for (const [index, path] of touches.entries()) {
+            if (typeof path !== "string")
+                continue;
+            const field = `touches[${index}]`;
+            if (hasForbiddenControls(path))
+                problems.push({ reason: `${field}-controls`, message: `${field}: carries control characters that could become terminal escapes` });
+            else if (/[\n\t]/.test(path))
+                problems.push({ reason: `${field}-multiline`, message: `${field}: must be one line` });
+        }
     }
-    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-        return refuse("not-an-object", "the payload must be one JSON object");
+    let criteria = [];
+    let acceptanceOk = false;
+    if (!touched(contract, "acceptance")) {
+        const acceptance = parseAcceptanceCriteria(body["acceptance"]);
+        problems.push(...acceptance.problems.map(problem => ({ reason: problem.reason, message: acceptanceLine(problem) })));
+        criteria = acceptance.criteria;
+        acceptanceOk = acceptance.problems.length === 0;
     }
-    const body = parsed;
-    const problems = [];
-    const goal = prose(body["goal"], "goal", PLAN_LIMITS.goal, true, problems);
-    const outOfScope = prose(body["outOfScope"], "outOfScope", PLAN_LIMITS.outOfScope, false, problems);
-    const document = prose(body["plan"], "plan", PLAN_LIMITS.document, true, problems);
-    const amendment = prose(body["amendment"], "amendment", PLAN_LIMITS.amendment, false, problems);
-    const touches = [];
-    if (body["touches"] !== undefined && body["touches"] !== null) {
-        if (!Array.isArray(body["touches"])) {
-            problems.push({ reason: "bad-touches", message: `touches must be an array of paths (got ${describe(body["touches"])})` });
-        }
-        else if (body["touches"].length > PLAN_LIMITS.touches) {
-            problems.push({ reason: "touches-too-many", message: `touches lists ${body["touches"].length} paths — cap is ${PLAN_LIMITS.touches}` });
+    const document = text("plan");
+    if (document !== null && document !== "") {
+        if (Buffer.byteLength(document, "utf8") > TEXT_LIMITS.planDocumentBytes) {
+            problems.push({ reason: "plan-too-long", message: `plan: over ${TEXT_LIMITS.planDocumentBytes.toLocaleString("en-US")} bytes` });
         }
-        else {
-            for (const [index, one] of body["touches"].entries()) {
-                const path = prose(one, `touches[${index}]`, PLAN_LIMITS.touch, true, problems);
-                if (path !== null) {
-                    if (/[\n\t]/.test(path)) {
-                        problems.push({ reason: `touches[${index}]-multiline`, message: `touches[${index}] must be one line` });
-                    }
-                    else {
-                        touches.push(path);
+        else if (!hasForbiddenControls(document)) {
+            const execution = parseExecutionPlanDocument(document);
+            if (!execution.ok) {
+                problems.push(...execution.problems.map(problem => ({ reason: problem.reason, message: `plan: ${problem.message}` })));
+            }
+            else if (acceptanceOk) {
+                const proof = execution.document.proof.join("\n");
+                for (const criterion of criteria) {
+                    const mentioned = new RegExp(`(^|[^A-Za-z0-9_-])${criterion.id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}([^A-Za-z0-9_-]|$)`).test(proof);
+                    if (!mentioned) {
+                        problems.push({ reason: `plan-proof-missing-${criterion.id}`, message: `plan: Proof must name acceptance criterion ${criterion.id}` });
                     }
                 }
             }
         }
     }
-    const acceptanceParse = parseAcceptanceCriteria(body["acceptance"]);
-    for (const problem of acceptanceParse.problems) {
-        problems.push({ reason: problem.reason, message: problem.message });
+    return { problems, criteria };
+}
+/**
+ * The planner's handoff, read against the plan contract (src/contracts/plan.ts): fail closed, every problem at once,
+ * each one naming its path (`acceptance[0].evidence[0]: must be one of ...`). A plan saved before plans carried
+ * `version` reads as it always did.
+ */
+export function parsePlan(raw) {
+    if (Buffer.byteLength(raw, "utf8") > TEXT_LIMITS.planPayloadBytes) {
+        return refuse("too-large", `payload: over ${TEXT_LIMITS.planPayloadBytes.toLocaleString("en-US")} bytes`);
     }
-    if (acceptanceParse.problems.length === 0 && acceptanceParse.criteria.length === 0) {
-        problems.push({ reason: "missing-acceptance", message: "acceptance is required — at least one signed criterion the build will be judged against" });
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
     }
-    if (document !== null) {
-        const execution = parseExecutionPlanDocument(document);
-        if (!execution.ok) {
-            problems.push(...execution.problems);
-        }
-        else if (acceptanceParse.problems.length === 0) {
-            const proof = execution.document.proof.join("\n");
-            for (const criterion of acceptanceParse.criteria) {
-                const mentioned = new RegExp(`(^|[^A-Za-z0-9_-])${criterion.id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}([^A-Za-z0-9_-]|$)`).test(proof);
-                if (!mentioned) {
-                    problems.push({ reason: `plan-proof-missing-${criterion.id}`, message: `Proof must name acceptance criterion ${criterion.id}` });
-                }
-            }
-        }
+    catch (error) {
+        return refuse("not-json", `the payload is not JSON: ${error instanceof Error ? error.message : String(error)}`);
     }
-    if (problems.length > 0)
+    const body = planPayloadBody(parsed);
+    if (body === null)
+        return refuse("not-an-object", "payload: must be one JSON object");
+    const read = readPlanPayload(parsed);
+    const contract = read.ok ? [] : read.issues.map(planProblemOf);
+    if (contract.some(problem => problem.reason === "newer-version" || problem.reason === "bad-version"))
+        return { ok: false, problems: contract };
+    const rules = planRuleProblems(body, contract);
+    const problems = [...contract, ...rules.problems];
+    if (!read.ok || problems.length > 0)
         return { ok: false, problems };
+    const payload = read.value;
     return {
         ok: true,
-        plan: { goal: goal, outOfScope, touches, acceptance: acceptanceParse.criteria, plan: document, amendment },
+        plan: {
+            goal: payload.goal,
+            outOfScope: payload.outOfScope === undefined || payload.outOfScope === null || payload.outOfScope === "" ? null : payload.outOfScope,
+            touches: payload.touches ?? [],
+            acceptance: rules.criteria,
+            plan: payload.plan,
+            amendment: payload.amendment === undefined || payload.amendment === null || payload.amendment === "" ? null : payload.amendment,
+        },
     };
 }
 const MILESTONE_STATES = ["pending", "current", "completed", "blocked"];
@@ -371,7 +428,7 @@ export function parsePlanRevisionProposal(raw) {
     const problems = [];
     const reason = prose(body["reason"], "reason", REVISION_LIMITS.reason, true, problems);
     const evidenceLink = prose(body["evidenceLink"], "evidenceLink", REVISION_LIMITS.evidenceLink, true, problems);
-    const planText = prose(body["plan"], "plan", PLAN_LIMITS.document, true, problems);
+    const planText = prose(body["plan"], "plan", TEXT_LIMITS.planDocumentBytes, true, problems);
     let document = null;
     if (planText !== null) {
         const execution = parseExecutionPlanDocument(planText);

package/dist/planner-source.js

@@ -37,6 +37,7 @@
  */
 import { createHash } from "node:crypto";
 import { EVIDENCE_CAPS, readVerifiedArtifact } from "./evidence.js";
+import { TEXT_LIMITS } from "./text-limits.js";
 export const PLANNER_SOURCE_VERSION = 1;
 export const PLANNER_SOURCE_LIMITS = {
     /** The whole recorded source before lossless prompt fencing. Equal to
@@ -44,7 +45,7 @@ export const PLANNER_SOURCE_LIMITS = {
      * truncated: what the record holds is exactly what the planner read. */
     bytes: EVIDENCE_CAPS["plan-contract"],
     /** A planner's amendment note: why the filed contract must change. */
-    amendment: 1_000,
+    amendment: TEXT_LIMITS.planAmendment,
     /** Earlier answers quoted into the brief. */
     answers: 5,
 };