@juzser/blacksmith 0.1.0 → 0.1.1

package/factory/orchestrator/dist/judges.js

@@ -232,6 +232,36 @@ export async function recordJudgeDispatch(input, ctx, opts = {}) {
         declared_artifact: input.artifactPath,
     }, input.taskId, ctx, opts);
 }
+/** The one judge whose artifact is a verdict document rather than a findings list. */
+const GRADER_ROLE = 'grader';
+/**
+ * Count what a grader's result document holds against the task.
+ *
+ * The grader's contract is `state/results/<task-id>.grader-r<round>.json`:
+ * `{run_status, structured_output: {round, criteria[], overall}}`, the file
+ * `gate run --grader` reads. Its findings are the criteria it did not pass —
+ * `fail` and `partial` both send the task back — so that is the count the
+ * report carries. A `dead` grader is the grader's own word for "nothing here
+ * is gradable" (`checkGraderVerdict`): it reported, and found nothing to
+ * count. Anything else that is not a `criteria` array is some other shape and
+ * gets `undefined`, so the caller refuses it the way it refuses every other
+ * non-list. Schema validation stays with the gate: this decides whether the
+ * grader *reported*, not whether its verdict holds.
+ */
+function graderFindingCount(parsed) {
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return undefined;
+    const document = parsed;
+    if (document.run_status === 'dead')
+        return 0;
+    const structured = document.structured_output;
+    if (typeof structured !== 'object' || structured === null)
+        return undefined;
+    const criteria = structured.criteria;
+    if (!Array.isArray(criteria))
+        return undefined;
+    return criteria.filter((c) => !(typeof c === 'object' && c !== null && c.status === 'pass')).length;
+}
 /**
  * Read a judge's artifact and answer how many findings it holds.
  *
@@ -239,10 +269,16 @@ export async function recordJudgeDispatch(input, ctx, opts = {}) {
  * different things to do about it: the file is not there (re-poke the agent),
  * it is there and is prose (the agent narrated instead of reporting), it is
  * there and parses but is not a findings list (the agent wrote some other
- * shape — a grader verdict, say, which is P9-14's business and needs its own
- * schema before anything here can accept it).
+ * shape).
+ *
+ * The grader is the one role whose declared shape is not a list: it writes a
+ * verdict document, and refusing that document left its turn closable only by
+ * a hand-written evidence file (FD-1, csb-audit-1). For `role === 'grader'`
+ * the grader result document is accepted beside the list, and the count is
+ * its non-pass criteria. No other role gets that reading — a reviewer that
+ * wrote a verdict wrote the wrong shape.
  */
-export function readJudgeArtifact(artifactPath) {
+export function readJudgeArtifact(artifactPath, role) {
     let raw;
     try {
         raw = readFileSync(artifactPath, 'utf8');
@@ -257,10 +293,15 @@ export function readJudgeArtifact(artifactPath) {
     catch (err) {
         throw new JudgeError('judges.artifact-unparseable', `Judge artifact "${artifactPath}" is not JSON. Prose in the artifact slot is the wave-4 failure exactly: fluent text that reads like a verdict and is not one.`, { artifact_path: artifactPath, cause: err instanceof Error ? err.message : String(err) });
     }
-    if (!Array.isArray(parsed)) {
-        throw new JudgeError('judges.artifact-not-a-list', `Judge artifact "${artifactPath}" parsed to ${parsed === null ? 'null' : typeof parsed}, not a findings-evidence array. An empty review is "[]", written out.`, { artifact_path: artifactPath });
-    }
-    return parsed;
+    if (Array.isArray(parsed))
+        return parsed.length;
+    const graderCount = role === GRADER_ROLE ? graderFindingCount(parsed) : undefined;
+    if (graderCount !== undefined)
+        return graderCount;
+    const accepted = role === GRADER_ROLE
+        ? 'a findings-evidence array or the grader result document ({run_status, structured_output: {criteria: [...]}})'
+        : 'a findings-evidence array';
+    throw new JudgeError('judges.artifact-not-a-list', `Judge artifact "${artifactPath}" parsed to ${parsed === null ? 'null' : typeof parsed}, not ${accepted}. An empty review is "[]", written out.`, { artifact_path: artifactPath, agent_role: role ?? null });
 }
 function notDispatchedMessage(input, turn, forRole) {
     if (forRole.length > 1) {
@@ -291,7 +332,7 @@ export async function recordJudgeReport(input, ctx, opts = {}) {
         });
     }
     const artifactPath = input.noFindings ? null : (input.artifactPath ?? turn.declaredArtifact);
-    const findingCount = artifactPath === null ? 0 : readJudgeArtifact(artifactPath).length;
+    const findingCount = artifactPath === null ? 0 : readJudgeArtifact(artifactPath, input.role);
     await emit(JUDGE_REPORT_EVENT_TYPE, {
         agent_role: input.role,
         round: turn.round,

package/factory/orchestrator/dist/lessons.js

@@ -9,7 +9,7 @@
 //       a small fixed marker list (never/not/don't/...) — a
 //       same-shingle-shape contradiction phrased another way (e.g. "avoid"
 //       vs "prefer") still auto-novelty-rejects silently. Documented, not
-//       hidden — see docs/guide/operator-guide.md.
+//       hidden — see docs/guide/operator-guide/lessons-and-daemon.md.
 //   (b) compileLessons() — approved lessons -> factory/policies/lessons.md,
 //       round-tripping through severity.ts's parseLessons() (the same-mistake
 //       gate's own reader). Every bullet value is rendered through
@@ -33,7 +33,7 @@ import { isOperatorActor } from './actors.js';
 import { foldLessons } from './db/projector.js';
 import { SmithError } from './errors.js';
 import { appendEvent, readLineageEvents } from './events.js';
-import { AGENTS_DIR, LESSONS_MD_PATH } from './paths.js';
+import { AGENTS_DIR, lessonsReadPath } from './paths.js';
 import { LESSON_SCOPES, parseLessons } from './severity.js';
 import { loadTaxonomy, validateTag } from './taxonomy.js';
 export class LessonsError extends SmithError {
@@ -128,7 +128,7 @@ export function effectiveNoveltyThreshold(a, b, threshold, shingleSize = DEFAULT
  * This is NOT real negation detection — it will miss a prohibition phrased
  * without one of these words (e.g. "avoid" vs "prefer"). Residual limitation,
  * documented rather than hidden: see this file's header comment and
- * docs/guide/operator-guide.md.
+ * docs/guide/operator-guide/lessons-and-daemon.md.
  *
  * What is compared is WHETHER a statement prohibits, not which word it
  * prohibits with. English spells a prohibition four ways in this list alone,
@@ -588,7 +588,7 @@ export function renderLessonBlock(role, scopes, lessons) {
  */
 export function lessonsForDispatch(role, claimPaths, opts = {}) {
     const scopes = scopesForRole(role, opts);
-    const lessonsPath = opts.lessonsPath ?? LESSONS_MD_PATH;
+    const lessonsPath = opts.lessonsPath ?? lessonsReadPath();
     let markdown;
     try {
         markdown = readFileSync(lessonsPath, 'utf8');

package/factory/orchestrator/dist/mcp.js

@@ -18,9 +18,10 @@
 import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { SmithError } from './errors.js';
-import { PROJECTS_DIR, ROADMAP_PATH, SCAFFOLD_DIR, WORKSPACES_DIR } from './paths.js';
+import { PROJECTS_DIR, roadmapReadPath, SCAFFOLD_DIR, WORKSPACES_DIR } from './paths.js';
 import { loadRoadmap, ownsEpic, readRoadmapText, roadmapDeclaresId, } from './roadmap.js';
 import { copyTemplateDir, mergePackageJson, PACKAGE_FRAGMENT_NAME, validateProjectName, } from './scaffold.js';
+import { ensureWritableRoadmap } from './workroot.js';
 export class McpError extends SmithError {
 }
 /**
@@ -293,7 +294,7 @@ export function addMcpSurface(opts) {
  * before the project's final milestone, and `smith epic close` refuses while
  * checkManifest is red.
  */
-export function registerMcpMilestone(projectName, roadmapPath = ROADMAP_PATH) {
+export function registerMcpMilestone(projectName, roadmapPath = ensureWritableRoadmap()) {
     const id = `${projectName}-${MCP_MILESTONE_SUFFIX}`;
     const text = readRoadmapText(roadmapPath);
     // roadmapDeclaresId, not `text.includes('- id: ' + id)`: the substring is
@@ -450,7 +451,7 @@ export function runMcpCheck(opts) {
     validateProjectName(opts.projectName);
     const { targetDir, source } = resolveMcpTarget(opts);
     const manifestPath = path.join(targetDir, MANIFEST_NAME);
-    const roadmapPath = opts.roadmapPath ?? ROADMAP_PATH;
+    const roadmapPath = opts.roadmapPath ?? roadmapReadPath();
     if (!existsSync(manifestPath)) {
         throw new McpError('mcp.no-surface', `${manifestPath} does not exist. Run \`smith mcp init ${opts.projectName}\` before checking the surface.`, { manifestPath, projectName: opts.projectName });
     }

package/factory/orchestrator/dist/paths.js

@@ -1,33 +1,159 @@
+import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 // factory/orchestrator/src/paths.ts -> repo root is three levels up.
 const here = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * What the factory *is*: the policies, schemas, scaffold, migrations and role
+ * templates the CLI reads and never writes. Derived from this module's own
+ * location, so under an npm install it is the package directory inside
+ * `node_modules` -- which is the right answer, because every one of those
+ * assets ships in the tarball. `packaging.test.ts` holds that claim.
+ */
 export const REPO_ROOT = path.resolve(here, '..', '..', '..');
 /**
- * The repo's own `.env`, read at CLI start by `loadDotEnv`. Gitignored, and
+ * Is this module running out of the blacksmith clone, or out of an installed
+ * copy of the package?
+ *
+ * `.git` is the signal because a tarball never carries one: npm strips it, and
+ * `package.json#files` could not ship it if it tried. A linked worktree spells
+ * it as a file rather than a directory, which `existsSync` reads either way.
+ */
+const IS_CLONE = existsSync(path.join(REPO_ROOT, '.git'));
+/**
+ * Where the work root goes when the CLI is not standing in a clone.
+ *
+ * A dot-directory rather than a bare `state/` and `factory/`, because under an
+ * install the operator's own project is the working directory and two
+ * top-level directories appearing in it are the tool making itself at home in
+ * somebody else's repo. One is enough, and it is the same name the audit store
+ * already uses (`<project>/.blacksmith/findings.jsonl`).
+ */
+const WORK_DIR_NAME = '.blacksmith';
+/**
+ * Where everything this CLI *writes* is rooted -- state, epic plans, the
+ * operator's `.env`.
+ *
+ * Pure, and exported for the test: the constants below call it once at module
+ * load, but the install case can only be stated by a test that passes its own
+ * roots in. `env.SMITH_HOME` wins outright; otherwise a clone keeps writing
+ * into itself, and an install writes beside the operator instead of into
+ * `node_modules/@juzser/blacksmith`, which the next `npm i` replaces wholesale.
+ *
+ * The layout *under* the root is identical in both cases on purpose. A path
+ * like `state/events/<session>.jsonl` is spelled in runbooks, in agent
+ * templates and in `guardrails.yml`'s write roots, and all of those stay true
+ * if only the anchor moves.
+ */
+export function resolveWorkRoot(repoRoot, cwd, env, isClone) {
+    const declared = env.SMITH_HOME?.trim();
+    // An empty `SMITH_HOME=` is how an unset variable gets spelled by accident in
+    // a shell profile or a CI matrix; resolved literally it would mean cwd.
+    if (declared)
+        return path.resolve(cwd, declared);
+    return isClone ? repoRoot : path.join(cwd, WORK_DIR_NAME);
+}
+/**
+ * Where `smith new` puts a project when `--target-dir` says nothing.
+ *
+ * Beside the clone, never inside it (D-42) -- but the parent of an *installed*
+ * package is `node_modules/@juzser`, which is not a place a project may be
+ * written. Without a clone "beside the clone" has no referent, and the honest
+ * substitute is the directory the operator is standing in.
+ */
+export function resolveProjectsDir(repoRoot, cwd, isClone) {
+    return isClone ? path.dirname(repoRoot) : cwd;
+}
+/**
+ * The third kind of path: a file the factory *ships a default of* and the
+ * operator then edits.
+ *
+ * Most constants below are one thing or the other -- an asset the CLI only
+ * reads, which ships and hangs off REPO_ROOT, or state the CLI writes, which
+ * must not ship and hangs off WORK_ROOT. `factory/specs/roadmap.md` and
+ * `factory/policies/stack.yml` are both: each ships as a starting point and is
+ * then written, the roadmap by `smith new` and stack.yml by the operator
+ * answering INSTALL.md Step 5 "in place".
+ *
+ * Anchored on REPO_ROOT, as both were, those writes land inside the installed
+ * package, which the next `npm i` replaces wholesale -- so the answers an
+ * operator typed survive until their first upgrade and then silently do not.
+ *
+ * So each is declared twice: `X_DEFAULT_PATH` under REPO_ROOT, which ships and
+ * is only ever read, and `X_PATH` under WORK_ROOT, which is written. This
+ * function is the read side -- the operator's copy when it exists, the shipped
+ * default before anyone has answered. `exists` is a parameter because the
+ * install case is only statable by a test that supplies its own.
+ *
+ * In a clone the two roots are one directory, so both halves name the same
+ * file and every read and write goes where it always went.
+ */
+export function resolveOverlayRead(personal, shipped, exists = existsSync) {
+    return exists(personal) ? personal : shipped;
+}
+/**
+ * Which root the *written* half of an overlay hangs off -- and the one place
+ * the work root is deliberately not it.
+ *
+ * `SMITH_HOME` beats `isClone` in `resolveWorkRoot`, on purpose: it is how an
+ * operator says "keep one fixed home for several projects", and state is
+ * exactly the thing that should follow them there. The two overlay files are
+ * not state. `factory/specs/roadmap.md` and `factory/policies/stack.yml` are
+ * tracked files in this repo -- declarations about *this* checkout, committed
+ * beside the code they describe -- and a clone that redirected them to
+ * `$SMITH_HOME` would leave its own tracked copies still sitting in the editor
+ * looking authoritative while every reader had quietly moved on. Split brain,
+ * no error.
+ *
+ * So a clone keeps its declarations, whatever `SMITH_HOME` says about its
+ * state, and only an install -- which has no tracked copy to orphan, and whose
+ * REPO_ROOT is a directory `npm i` replaces -- moves them to the work root.
+ * This is what makes "an existing checkout changes nothing" true without a
+ * condition attached to it.
+ */
+export function resolveOverlayRoot(repoRoot, workRoot, isClone) {
+    return isClone ? repoRoot : workRoot;
+}
+export const WORK_ROOT = resolveWorkRoot(REPO_ROOT, process.cwd(), process.env, IS_CLONE);
+/** Where the operator's copy of a shipped-then-edited file lives. */
+export const OVERLAY_ROOT = resolveOverlayRoot(REPO_ROOT, WORK_ROOT, IS_CLONE);
+/**
+ * The operator's own `.env`, read at CLI start by `loadDotEnv`. Gitignored, and
  * the one place `docs/runbooks/providers.md` tells an operator to put a
- * provider key. Anchored on this module, not on cwd: an agent runs `smith`
- * from a worktree, and the key belongs to the clone.
+ * provider key. Anchored on the work root, not on cwd: an agent runs `smith`
+ * from a worktree, and the key belongs to the operator's clone -- and not on
+ * REPO_ROOT either, since under an install that is a file `npm i` deletes.
  */
-export const DOTENV_PATH = path.join(REPO_ROOT, '.env');
+export const DOTENV_PATH = path.join(WORK_ROOT, '.env');
 export const TAXONOMY_PATH = path.join(REPO_ROOT, 'factory', 'policies', 'taxonomy.yml');
 export const SCHEMA_DIR = path.join(REPO_ROOT, 'factory', 'specs', 'schema');
-export const SPECS_ACTIVE_DIR = path.join(REPO_ROOT, 'factory', 'specs', 'active');
-export const STATE_EVENTS_DIR = path.join(REPO_ROOT, 'state', 'events');
+export const SPECS_ACTIVE_DIR = path.join(WORK_ROOT, 'factory', 'specs', 'active');
+export const STATE_EVENTS_DIR = path.join(WORK_ROOT, 'state', 'events');
 /** Where a task's declared artifacts must live: `state/artifacts/<task-id>/` (P9-22). */
-export const STATE_ARTIFACTS_DIR = path.join(REPO_ROOT, 'state', 'artifacts');
+export const STATE_ARTIFACTS_DIR = path.join(WORK_ROOT, 'state', 'artifacts');
 export const WORKTREE_POLICY_PATH = path.join(REPO_ROOT, 'factory', 'policies', 'worktree.yml');
-export const STATE_DB_PATH = path.join(REPO_ROOT, 'state', 'smith.db');
+export const STATE_DB_PATH = path.join(WORK_ROOT, 'state', 'smith.db');
 /** The background watcher's lock and last tick: `state/daemon/{daemon.pid,status.json}`. */
-export const STATE_DAEMON_DIR = path.join(REPO_ROOT, 'state', 'daemon');
+export const STATE_DAEMON_DIR = path.join(WORK_ROOT, 'state', 'daemon');
 export const DB_MIGRATIONS_DIR = path.join(REPO_ROOT, 'factory', 'orchestrator', 'drizzle');
-export const ROADMAP_PATH = path.join(REPO_ROOT, 'factory', 'specs', 'roadmap.md');
+/**
+ * The roadmap as it ships: one heading per milestone, and the file `smith new`
+ * appends to. Read-only under this name; see ROADMAP_PATH for the copy that is
+ * written and `resolveOverlayRead` for why there are two.
+ */
+export const ROADMAP_DEFAULT_PATH = path.join(REPO_ROOT, 'factory', 'specs', 'roadmap.md');
+/** The operator's roadmap -- the one `registerProjectInRoadmap` writes into. */
+export const ROADMAP_PATH = path.join(OVERLAY_ROOT, 'factory', 'specs', 'roadmap.md');
+/** The roadmap to read: the operator's if they have one, the shipped one if not. */
+export function roadmapReadPath() {
+    return resolveOverlayRead(ROADMAP_PATH, ROADMAP_DEFAULT_PATH);
+}
 export const SCAFFOLD_DIR = path.join(REPO_ROOT, 'factory', 'scaffold');
 /**
  * `workspaces/` inside this clone. Still a legal place to keep a project, and
  * still searched for ones already there -- no longer where a new one goes.
  */
-export const WORKSPACES_DIR = path.join(REPO_ROOT, 'workspaces');
+export const WORKSPACES_DIR = path.join(WORK_ROOT, 'workspaces');
 /**
  * Where a project lands when nothing says otherwise: beside this clone.
  *
@@ -39,9 +165,25 @@ export const WORKSPACES_DIR = path.join(REPO_ROOT, 'workspaces');
  * it there on their own, since worktree.ts places them next to the project it
  * is handed rather than at a path of its own choosing.
  */
-export const PROJECTS_DIR = path.dirname(REPO_ROOT);
+export const PROJECTS_DIR = resolveProjectsDir(REPO_ROOT, process.cwd(), IS_CLONE);
 export const SCHEDULER_POLICY_PATH = path.join(REPO_ROOT, 'factory', 'policies', 'scheduler.yml');
-export const LESSONS_MD_PATH = path.join(REPO_ROOT, 'factory', 'policies', 'lessons.md');
+/**
+ * The compiled lessons as they ship. Read-only under this name; see
+ * LESSONS_MD_PATH for the copy `smith lessons compile` writes.
+ */
+export const LESSONS_MD_DEFAULT_PATH = path.join(REPO_ROOT, 'factory', 'policies', 'lessons.md');
+/**
+ * The operator's compiled lessons -- the third file that is both shipped and
+ * written. Nobody types it, so it is not an answer in the sense the other two
+ * are; it is this factory's accumulated memory, compiled from the operator's
+ * own event log by `smith lessons compile`, and an upgrade that resets it
+ * loses exactly as much.
+ */
+export const LESSONS_MD_PATH = path.join(OVERLAY_ROOT, 'factory', 'policies', 'lessons.md');
+/** The lessons to read: the operator's if they have compiled any, the shipped set if not. */
+export function lessonsReadPath() {
+    return resolveOverlayRead(LESSONS_MD_PATH, LESSONS_MD_DEFAULT_PATH);
+}
 /** The shipped role templates — read at dispatch for their `<!-- LESSONS:<scope> -->` markers (P9-2). */
 export const AGENTS_DIR = path.join(REPO_ROOT, '.claude', 'agents');
 export const CROSSCHECK_POLICY_PATH = path.join(REPO_ROOT, 'factory', 'policies', 'crosscheck.yml');
@@ -70,7 +212,17 @@ export const SEVERITY_POLICY_PATH = path.join(REPO_ROOT, 'factory', 'policies',
  * and the scaffolder reads it instead of the prose in docs/standards/stack.md
  * — which described one operator's stack as if it were everyone's.
  */
-export const STACK_POLICY_PATH = path.join(REPO_ROOT, 'factory', 'policies', 'stack.yml');
+export const STACK_POLICY_DEFAULT_PATH = path.join(REPO_ROOT, 'factory', 'policies', 'stack.yml');
+/**
+ * The operator's own answers. INSTALL.md Step 5 has them change the values in
+ * place, so this is the copy that gets edited -- under the work root, where an
+ * upgrade cannot reach it.
+ */
+export const STACK_POLICY_PATH = path.join(OVERLAY_ROOT, 'factory', 'policies', 'stack.yml');
+/** The stack answers to read: the operator's if they have any, the shipped questionnaire if not. */
+export function stackPolicyReadPath() {
+    return resolveOverlayRead(STACK_POLICY_PATH, STACK_POLICY_DEFAULT_PATH);
+}
 /**
  * Open judge sandbox leases, one file per worktree (sandbox.ts).
  *
@@ -79,4 +231,4 @@ export const STACK_POLICY_PATH = path.join(REPO_ROOT, 'factory', 'policies', 'st
  * judge cannot revoke its own guard by deleting a file it is not allowed to
  * reach.
  */
-export const SANDBOX_LEASE_DIR = path.join(REPO_ROOT, 'state', 'sandboxes');
+export const SANDBOX_LEASE_DIR = path.join(WORK_ROOT, 'state', 'sandboxes');

package/factory/orchestrator/dist/plan.js

@@ -204,7 +204,7 @@ export function validatePlan(plan, opts = {}) {
         for (const field of unreadTaskBudgetFields(budget)) {
             errors.push({
                 path: `/tasks/${t.task_id}/budget/${field}`,
-                message: `Budget field "${field}" has no mechanical reader: nothing in the factory can enforce it, so declaring it here states a limit the task will never be held to. Carry the number in the dispatch prompt instead, where it reads as the request it is (agent-interviews.md M-4).`,
+                message: `Budget field "${field}" has no mechanical reader: nothing in the factory can enforce it per task, so declaring it here states a limit the task will never be held to. The turn ceiling is the role template's maxTurns (.claude/agents/<role>.md), enforced by the harness per role; the dispatch prompt restates that number (agent-interviews.md M-4, corrected 2026-09-11).`,
             });
         }
         // D-7: the ref is what result.schema.json defers structured_output's shape

package/factory/orchestrator/dist/planQuorum.js

@@ -1,7 +1,7 @@
 import { loadBudgetPolicy } from './budgets.js';
 import { loadCrosscheckPolicy, } from './crosscheck.js';
 import { appendEvent } from './events.js';
-import { livePlanTasks, loadPlan, planRefTaskId, } from './plan.js';
+import { livePlanTasks, loadPlan, PlanError, planRefTaskId, } from './plan.js';
 import { enabledExternalProviders, nativeProviderName, runQuorumCase, } from './quorum.js';
 // Defensive field readers: TaskSpecRecord is Record<string, unknown>-ish
 // (schema-validated elsewhere, not here), so every field read below narrows
@@ -27,6 +27,10 @@ function taskNonfunctionalClauses(t) {
     const clauses = contract.nonfunctional_clauses;
     return Array.isArray(clauses) ? clauses.filter((c) => typeof c === 'string') : [];
 }
+function taskAcceptanceCriteria(t) {
+    const criteria = t.acceptance_criteria;
+    return Array.isArray(criteria) ? criteria.filter((c) => typeof c === 'string') : [];
+}
 function taskConfidence(t) {
     return typeof t.confidence === 'number' ? t.confidence : undefined;
 }
@@ -185,11 +189,16 @@ const DEFAULT_JUDGE_BUDGET = { timeout_ms: 120_000, max_output_bytes: 262_144 };
  * Pure prompt builder, mirrors quorum.ts's findingJudgeRequest() and
  * epic.ts's epicVerdictJudgeRequest() style and trust boundary: the prompt
  * carries the CLAIM ONLY (epic id, plan version, task ids/objectives/
- * case/token budgets, edge count, fired triggers with their evidence) —
- * never file contents, never a diff. The tasks it lists are `livePlanTasks`,
- * not `plan.tasks`: this prompt is the whole of what the critic sees, so a
- * superseded record listed here is an objective the plan withdrew, offered to
- * a judge as the plan's current ask (D-185). Carries
+ * case/token budgets, each task's acceptance criteria and nonfunctional
+ * clauses, edge count, fired triggers with their evidence) — never file
+ * contents, never a diff. The criteria are part of the claim, not evidence
+ * for it: FD-46 (csb-signing-policy-1) had both external critics refute
+ * plan-v1 for missing a case its task already listed as a criterion, because
+ * the prompt showed them the objective and nothing under it. The tasks it
+ * lists are `livePlanTasks`, not `plan.tasks`: this prompt is the whole of
+ * what the critic sees, so a superseded record listed here is an objective
+ * the plan withdrew, offered to a judge as the plan's current ask (D-185).
+ * Carries
  * asymmetric_roles.critic_mandate ("refute, not confirm"): the judge's
  * mandate is to REFUTE the plan's soundness; it critiques the plan, it does
  * not authorize any change to it.
@@ -201,7 +210,18 @@ export function planQuorumJudgeRequest(plan, triggers, budget) {
             .map((t) => {
             const caseValue = taskCase(t) ?? '(no case)';
             const objective = typeof t.objective === 'string' ? t.objective : '(no objective)';
-            return `  ${t.task_id} [${caseValue}, ${taskTokens(t)} tokens]: ${objective}`;
+            const criteria = taskAcceptanceCriteria(t);
+            const clauses = taskNonfunctionalClauses(t);
+            return [
+                `  ${t.task_id} [${caseValue}, ${taskTokens(t)} tokens]: ${objective}`,
+                '    acceptance criteria:',
+                ...(criteria.length > 0
+                    ? criteria.map((c) => `      - ${c}`)
+                    : ['      (no acceptance criteria)']),
+                ...(clauses.length > 0
+                    ? ['    nonfunctional clauses:', ...clauses.map((c) => `      - ${c}`)]
+                    : []),
+            ].join('\n');
         })
             .join('\n')
         : '  (no tasks)';
@@ -299,7 +319,15 @@ async function emitPlanQuorumDecision(args, ctx, opts) {
  * operator must look before approving the plan.
  */
 export async function runPlanQuorum(input, ctx, opts = {}) {
-    const plan = loadPlan(input.epicId, input.version, input.planOpts);
+    const plan = input.plan ?? loadPlan(input.epicId, input.version, input.planOpts);
+    if (plan.epic_id !== input.epicId || plan.version !== input.version) {
+        throw new PlanError('plan.identity-mismatch', `The plan handed to the quorum is ${plan.epic_id} version ${plan.version}, but the command names --epic ${input.epicId} --plan-version ${input.version}. One quorum record describes one plan; say which.`, {
+            epic_id: plan.epic_id,
+            version: plan.version,
+            expected_epic_id: input.epicId,
+            expected_version: input.version,
+        });
+    }
     const policy = input.crosscheck?.policy ?? loadCrosscheckPolicy();
     const epicCapTokens = input.epicCapTokens ?? loadBudgetPolicy().epic.capTokens;
     const triggers = evaluatePlanQuorumTriggers(plan, policy.planQuorum, epicCapTokens, {

package/factory/orchestrator/dist/providers/api-transport.js

@@ -7,6 +7,12 @@ import { extractAndValidate } from './schema-validate.js';
 import { ProviderError } from './types.js';
 const NUDGE = '\n\nReturn only valid JSON per schema.';
 const RESPONSE_BODY_ERROR_SNIPPET_LIMIT = 500;
+// Raw answer kept on a rejected verdict: enough head to see what the model
+// started writing, enough tail to see where it stopped. A truncated JSON
+// answer and a prose answer look alike in a bare `no-json-found`.
+const CONTENT_SNIPPET_HEAD = 300;
+const CONTENT_SNIPPET_TAIL = 200;
+const CONTENT_SNIPPET_JOINER = ' … ';
 function resolveApiKey(config, provider) {
     const key = process.env[config.apiKeyEnv];
     if (!key) {
@@ -14,9 +20,31 @@ function resolveApiKey(config, provider) {
     }
     return key;
 }
+/**
+ * The raw answer as it may appear in an error: the API key scrubbed the same
+ * way a non-OK body is, and bounded to head + tail so a 64K truncation shows
+ * its last bytes instead of nothing.
+ */
+function contentSnippet(content, apiKey) {
+    const scrubbed = content.split(apiKey).join('[REDACTED]');
+    if (scrubbed.length <= CONTENT_SNIPPET_HEAD + CONTENT_SNIPPET_TAIL)
+        return scrubbed;
+    return `${scrubbed.slice(0, CONTENT_SNIPPET_HEAD)}${CONTENT_SNIPPET_JOINER}${scrubbed.slice(-CONTENT_SNIPPET_TAIL)}`;
+}
+/**
+ * Whether a second call with the nudge appended can change anything. It can
+ * when the model finished on its own (`stop`) — the prompt is the suspect. It
+ * cannot when the model was cut off at `max_tokens`: the same prompt runs to
+ * the same cap and bills the same tokens. An absent finish_reason is read as
+ * `stop` so a provider that omits the field keeps the retry it always had.
+ */
+function nudgeCanHelp(finishReason) {
+    return finishReason === undefined || finishReason === 'stop';
+}
 async function callOnce(provider, config, apiKey, prompt, budget, fetchImpl) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), budget.timeout_ms);
+    const maxTokens = budget.max_output_tokens ?? config.maxTokens;
     let response;
     try {
         response = await fetchImpl(`${config.baseUrl.replace(/\/$/, '')}/chat/completions`, {
@@ -27,6 +55,7 @@ async function callOnce(provider, config, apiKey, prompt, budget, fetchImpl) {
                 messages: [{ role: 'user', content: prompt }],
                 stream: false,
                 ...(config.responseFormatJsonObject ? { response_format: { type: 'json_object' } } : {}),
+                ...(maxTokens === undefined ? {} : { max_tokens: maxTokens }),
             }),
             signal: controller.signal,
         });
@@ -65,13 +94,39 @@ async function callOnce(provider, config, apiKey, prompt, budget, fetchImpl) {
     catch {
         throw new ProviderError('provider.malformed-response', `Provider "${provider}" API judge response was not valid JSON.`, { provider });
     }
-    const content = parsed.choices?.[0]?.message?.content ?? '';
+    const choice = parsed.choices?.[0];
+    const content = choice?.message?.content ?? '';
     return {
         content,
         usage: parsed.usage
             ? { input_tokens: parsed.usage.prompt_tokens, output_tokens: parsed.usage.completion_tokens }
             : undefined,
+        finishReason: typeof choice?.finish_reason === 'string' ? choice.finish_reason : undefined,
+    };
+}
+/**
+ * The error for an answer that never validated. Two codes, because the two
+ * situations are fixed in different places: `output-truncated` (the model
+ * stopped at the cap mid-answer) is fixed by a cap or a shorter prompt;
+ * `invalid-output` (the model finished and still did not answer the schema)
+ * is fixed at the prompt. Both carry the raw answer, scrubbed and bounded, so
+ * the operator can tell the two apart in the log instead of guessing from a
+ * reason string.
+ */
+function rejectedAnswerError(provider, apiKey, call, result, retried) {
+    const details = {
+        provider,
+        reason: result.reason,
+        errors: result.errors,
+        finish_reason: call.finishReason,
+        content_length: call.content.length,
+        content_snippet: contentSnippet(call.content, apiKey),
+        retried,
     };
+    if (call.finishReason === 'length') {
+        return new ProviderError('provider.output-truncated', `Provider "${provider}" API judge stopped at its output cap (finish_reason "length") after ${call.content.length} characters, before the answer closed; not retried. Raise max_tokens for the provider (crosscheck.yml) or --max-output-tokens, or shorten the prompt.`, details);
+    }
+    return new ProviderError('provider.invalid-output', `Provider "${provider}" API judge returned invalid output${retried ? ' after one retry' : ''}: ${result.reason}.`, details);
 }
 /**
  * Both attempts, added together — the provider billed both, and this is the
@@ -99,13 +154,15 @@ export async function runApiJudge(provider, config, request, fetchImpl = fetch)
     let call = await callOnce(provider, config, apiKey, request.prompt, request.budget, fetchImpl);
     let usage = call.usage;
     let result = extractAndValidate(call.content, request.schemaName);
-    if (!result.valid) {
+    let retried = false;
+    if (!result.valid && nudgeCanHelp(call.finishReason)) {
         call = await callOnce(provider, config, apiKey, `${request.prompt}${NUDGE}`, request.budget, fetchImpl);
         usage = addUsage(usage, call.usage);
         result = extractAndValidate(call.content, request.schemaName);
-        if (!result.valid) {
-            throw new ProviderError('provider.invalid-output', `Provider "${provider}" API judge returned invalid output after one retry: ${result.reason}.`, { provider, reason: result.reason, errors: 'errors' in result ? result.errors : undefined });
-        }
+        retried = true;
+    }
+    if (!result.valid) {
+        throw rejectedAnswerError(provider, apiKey, call, { reason: result.reason, errors: 'errors' in result ? result.errors : undefined }, retried);
     }
     return {
         provider,

package/factory/orchestrator/dist/providers/index.js

@@ -48,6 +48,7 @@ export async function runJudge(providerName, request, opts = {}) {
         model: config.model,
         apiKeyEnv: config.apiKeyEnv,
         responseFormatJsonObject: config.responseFormatJsonObject,
+        ...(config.maxTokens === undefined ? {} : { maxTokens: config.maxTokens }),
     }, request, opts.fetchImpl);
 }
 export { ProviderError } from './types.js';