truecourse 0.7.0-next.0 → 0.7.0-next.2

package/cli.mjs

@@ -105218,7 +105218,7 @@ function parseBlockedOnCapabilities(reason) {
     return [];
   return m[1].split(",").map((s) => s.trim()).filter(Boolean);
 }
-var GuardWrittenScenarioSchema, GuardCoverageGapKindSchema, GuardCoverageGapSchema, GuardBirthFindingSchema, GuardGenerateErrorSchema, GuardExtractionFailureSchema, GuardOrphanedSectionSchema, GuardRecipeReportSchema, GuardGenerateUsageSchema, GuardGenerateReportSchema;
+var GuardWrittenScenarioSchema, GuardCoverageGapKindSchema, GuardCoverageGapSchema, GuardBirthFindingSchema, GuardGenerateErrorSchema, GuardEntryPreflightSchema, GuardExtractionFailureSchema, GuardOrphanedSectionSchema, GuardRecipeReportSchema, GuardGenerateUsageSchema, GuardGenerateReportSchema;
 var init_report = __esm({
   "packages/shared/dist/guard/report.js"() {
     "use strict";
@@ -105271,6 +105271,14 @@ var init_report = __esm({
       anchor: external_exports.string(),
       message: external_exports.string()
     }).strict();
+    GuardEntryPreflightSchema = external_exports.object({
+      /** Display form of the entry argv, e.g. `node tools/cli/dist/index.js`. */
+      entry: external_exports.string(),
+      /** The recipe build command, for the rebuild hint. */
+      buildCommand: external_exports.string(),
+      /** The full, UNTRUNCATED startup output the dead entry produced. */
+      stderr: external_exports.string()
+    }).strict();
     GuardExtractionFailureSchema = external_exports.object({
       doc: external_exports.string(),
       reason: external_exports.string()
@@ -105316,7 +105324,13 @@ var init_report = __esm({
        */
       birthPassed: external_exports.number().int().nonnegative().optional(),
       manifestPath: external_exports.string().optional(),
-      usage: GuardGenerateUsageSchema.optional()
+      usage: GuardGenerateUsageSchema.optional(),
+      /**
+       * Present ONLY when the built entry failed to start — the whole birth phase was
+       * short-circuited, so every changed section stayed unsettled. Optional so older
+       * reports (written before this field existed) keep parsing.
+       */
+      entryPreflight: GuardEntryPreflightSchema.optional()
     }).strict();
   }
 });
@@ -170270,7 +170284,7 @@ function readToolVersion() {
   if (cachedVersion)
     return cachedVersion;
   if (true) {
-    cachedVersion = "0.7.0-next.0";
+    cachedVersion = "0.7.0-next.2";
     return cachedVersion;
   }
   try {
@@ -196272,8 +196286,14 @@ var CorpusDocSchema = external_exports.object({
 var OverlapSectionSchema = external_exports.object({
   /** The doc this section lives in, by ref (one of the overlap's two docs). */
   doc: DocRefSchema,
-  /** The heading text of the conflicting section (verbatim from the doc). */
-  heading: external_exports.string()
+  /**
+   * The heading text of the conflicting section (verbatim from the doc), or
+   * `null` when the conflicting passage sits in the doc's PREAMBLE — the block
+   * before its first heading (README badges/tagline, intro line). A plain string
+   * from older corpora still parses; `null` is the preamble marker the viewer
+   * bands as the pre-first-heading block.
+   */
+  heading: external_exports.string().nullable()
 });
 var OverlapSchema = external_exports.object({
   /** The two docs that overlap, by ref. */
@@ -197210,7 +197230,9 @@ NOT a disagreement (do NOT flag):
 
 Bias: when there is a PLAUSIBLE contradiction a human should check, flag it. When the docs are clearly complementary or agree, do not.
 
-When you flag an overlap, also identify the SECTIONS that conflict: the nearest markdown heading (the \`#\`/\`##\`/\`###\` title, verbatim, WITHOUT the leading #s) above the conflicting text in EACH doc. List one entry per side; omit a side only if it genuinely has no heading.
+When you flag an overlap, also identify the SECTIONS that conflict: the nearest markdown heading (the \`#\`/\`##\`/\`###\` title, verbatim, WITHOUT the leading #s) above the conflicting text in EACH doc. List one entry per side; omit a side only when it genuinely has no conflicting passage.
+
+PREAMBLE: when a doc's conflicting passage sits ABOVE its first \`#\` heading \u2014 the preamble block (a README's badges, tagline, or the intro line before any heading) \u2014 there is no heading to name. Set that side's \`heading\` to the JSON literal \`null\` (not the string "null", not ""). Use \`null\` ONLY for that pre-first-heading block; whenever the passage is under a heading, name the heading verbatim.
 
 In the NOTE, refer to each doc by its FILENAME (the basename shown in the header, e.g. \`users.md\`) \u2014 NEVER "doc A" / "doc B", which mean nothing to the reader.
 
@@ -197220,6 +197242,12 @@ Output ONLY a JSON object, no prose, no code fences:
   "note": "users.md uses auth0_id; identity.md uses auth0_sub for the same user column",
   "sections": [ { "side": "A", "heading": "User model" }, { "side": "B", "heading": "Identity" } ] }
 
+Preamble example \u2014 doc A's claim is a README badge/tagline above any heading, so its side uses null:
+
+{ "overlap": true,
+  "note": "README.md lists C# as a supported language in the preamble; plan.md's Tech Stack omits it",
+  "sections": [ { "side": "A", "heading": null }, { "side": "B", "heading": "Tech Stack" } ] }
+
 Use { "overlap": false, "note": "", "sections": [] } when they are complementary or agree. The note is shown to the user \u2014 name the specific thing that differs.`;
 var OVERLAP_PREVIEW_LINES = 120;
 function docBody2(doc) {
@@ -197271,12 +197299,12 @@ function buildOverlapUserPrompt(areaId, a, b) {
 var LlmOverlapSchema = external_exports.object({
   overlap: external_exports.boolean(),
   note: external_exports.string().default(""),
-  sections: external_exports.array(external_exports.object({ side: external_exports.enum(["A", "B"]), heading: external_exports.string() })).default([])
+  sections: external_exports.array(external_exports.object({ side: external_exports.enum(["A", "B"]), heading: external_exports.string().nullable() })).default([])
 });
 var OverlapVerdictSchema = external_exports.object({
   overlap: external_exports.boolean(),
   note: external_exports.string().default(""),
-  sections: external_exports.array(external_exports.object({ doc: external_exports.string(), heading: external_exports.string() })).default([])
+  sections: external_exports.array(external_exports.object({ doc: external_exports.string(), heading: external_exports.string().nullable() })).default([])
 });
 function spawnOverlapRunner(opts = {}) {
   const transport = opts.transport ?? cliTransport({ bin: opts.bin });
@@ -197466,35 +197494,49 @@ function prefilterDocs(docs, manualIncludes = []) {
     skipped: [...reasons].map(([path79, reason]) => ({ path: path79, reason }))
   };
 }
+async function planRelevanceWork(repoRoot5, docs, manualIncludes = []) {
+  const manualSet = new Set(manualIncludes);
+  const { toClassify, skipped } = prefilterDocs(docs, manualIncludes);
+  const needsCall = [];
+  const known = /* @__PURE__ */ new Map();
+  await Promise.all(toClassify.map(async (doc) => {
+    if (manualSet.has(doc.path)) {
+      known.set(doc.path, { path: doc.path, include: true, reason: "manual include" });
+      return;
+    }
+    const cached = await readCache4(repoRoot5, computeCacheKey5(doc));
+    if (cached)
+      known.set(doc.path, cached);
+    else
+      needsCall.push(doc);
+  }));
+  return { toClassify, prefilterSkipped: skipped, needsCall, known };
+}
 async function filterByRelevance(repoRoot5, docs, opts = {}) {
   if (opts.enabled === false || docs.length === 0) {
     return { included: docs, skipped: [] };
   }
-  const manualSet = new Set(opts.manualIncludes ?? []);
   const runner = opts.runner ?? spawnRelevanceRunner({ transport: opts.transport, model: opts.model, fallbackModel: opts.fallbackModel });
   const concurrency = opts.concurrency ?? defaultConcurrency();
-  const { toClassify, skipped: prefilterSkipped } = prefilterDocs(docs, opts.manualIncludes ?? []);
-  const prefilterReason = new Map(prefilterSkipped.map((s) => [s.path, s.reason]));
+  const plan = await planRelevanceWork(repoRoot5, docs, opts.manualIncludes ?? []);
+  const prefilterReason = new Map(plan.prefilterSkipped.map((s) => [s.path, s.reason]));
   const total = docs.length;
   let done = 0;
   const markDone = () => opts.onProgress?.(++done, total);
   opts.onProgress?.(0, total);
-  for (let i = 0; i < prefilterReason.size; i++)
+  const resolvedUpfront = prefilterReason.size + plan.known.size;
+  for (let i = 0; i < resolvedUpfront; i++)
     markDone();
-  const verdicts = /* @__PURE__ */ new Map();
+  const verdicts = new Map(plan.known);
+  const pending = plan.needsCall;
   let cursor = 0;
   let active11 = 0;
   await new Promise((resolve12) => {
+    if (pending.length === 0)
+      return resolve12();
     const launch = () => {
-      while (active11 < concurrency && cursor < toClassify.length) {
-        const doc = toClassify[cursor++];
-        if (manualSet.has(doc.path)) {
-          verdicts.set(doc.path, { path: doc.path, include: true, reason: "manual include" });
-          markDone();
-          if (cursor >= toClassify.length && active11 === 0)
-            resolve12();
-          continue;
-        }
+      while (active11 < concurrency && cursor < pending.length) {
+        const doc = pending[cursor++];
         active11++;
         classifyOne(repoRoot5, doc, runner).then((verdict) => {
           verdicts.set(doc.path, verdict);
@@ -197507,14 +197549,12 @@ async function filterByRelevance(repoRoot5, docs, opts = {}) {
         }).finally(() => {
           markDone();
           active11--;
-          if (cursor >= toClassify.length && active11 === 0)
+          if (cursor >= pending.length && active11 === 0)
             resolve12();
           else
             launch();
         });
       }
-      if (cursor >= toClassify.length && active11 === 0)
-        resolve12();
     };
     launch();
   });
@@ -197628,7 +197668,7 @@ async function classifyOne(repoRoot5, doc, runner) {
   await writeCache4(repoRoot5, cacheKey, verdict);
   return verdict;
 }
-var RELEVANCE_SYSTEM_PROMPT = `You are a documentation relevance classifier. Classify by CONTENT, not by folder or filename: does this doc state durable, intended behavior or decisions about THE SYSTEM IN THIS REPOSITORY (its endpoints, data, auth, events, invariants, business rules, architecture)?
+var RELEVANCE_SYSTEM_PROMPT = `You are a documentation relevance classifier. Judge mainly by CONTENT \u2014 does this doc state durable, intended behavior or decisions about THE SYSTEM IN THIS REPOSITORY (its endpoints, data, auth, events, invariants, business rules, architecture)? The doc's PATH (given below) is evidence too, never an automatic verdict: weigh path and content together.
 
 ${OUTPUT_ONLY_GUARDRAIL}
 
@@ -197641,22 +197681,23 @@ INCLUDE (spec-source material):
 SKIP (not spec-source material):
   - Pure status / TODO checklists, kanban boards, release notes / changelog drafts
   - Docs about a THIRD-PARTY / external system (vendor API research, integration notes) \u2014 that is someone else's contract, not ours, and cannot be verified against this codebase
+  - TEST-DATA specs: a doc under a test / fixture / sample / example tree (PATH segments like tests/, fixtures/, __fixtures__/, examples/, sample-*) that describes a FICTIONAL or sample product used as test data for THIS repo's own tooling \u2014 that product is not this repository's system, so its "spec" is not ours. (The path is evidence, not proof: if the doc plainly describes THIS repository's real product or engineering, keep it.)
   - SUPERSEDED docs \u2014 an older version of a newer doc covering the same subject
   - Process / meta docs not about product behavior: contribution / onboarding guides, code-style guides, deployment runbooks (keep a deployment doc ONLY if it states our runtime contracts)
   - Exploratory scratch with no committed decisions (brain dumps, open-questions-only notes)
   - AI-agent instructions / prompt templates; personal engineering journals
 
-Distinguish "states a decision about our system" (INCLUDE) from "tracks status / describes an external system / is superseded / is process" (SKIP). The SKIP categories above are explicit \u2014 they are not "doubt." WHEN GENUINELY AMBIGUOUS: include (dropping a real spec doc costs more than keeping noise).
+Distinguish "states a decision about our system" (INCLUDE) from "tracks status / describes an external or test-data product / is superseded / is process" (SKIP). The SKIP categories above are explicit \u2014 they are not "doubt." WHEN GENUINELY AMBIGUOUS: include (dropping a real spec doc costs more than keeping noise).
 
 Output ONLY a JSON object:
 
   { "include": true|false, "reason": "short explanation" }
 
-The reason is shown to the user in the dashboard \u2014 be specific ("vendor API research (ServiceTitan)", "superseded by capacity-ml-plan-v3", "deployment runbook, no product contracts") so they can verify the call.`;
+The reason is shown to the user in the dashboard \u2014 be specific ("vendor API research (ServiceTitan)", "superseded by capacity-ml-plan-v3", "deployment runbook, no product contracts", "test-data spec for a sample product (tests/fixtures/\u2026)") so they can verify the call.`;
 function buildRelevanceUserPrompt(doc) {
   const preview = doc.preview.split("\n").slice(0, 60).join("\n");
   return [
-    `Path: ${doc.path}`,
+    `PATH (repo-relative): ${doc.path}`,
     `Detected kind: ${doc.kind}`,
     `Size: ${doc.size} bytes`,
     "",
@@ -197710,9 +197751,6 @@ async function readCache4(scope, cacheKey) {
 async function writeCache4(scope, cacheKey, verdict) {
   await setCacheEntry(scope, CACHE_NAME5, cacheKey, verdict);
 }
-async function readRelevanceCache(repoRoot5, doc) {
-  return readCache4(repoRoot5, computeCacheKey5(doc));
-}
 
 // packages/spec-consolidator/dist/curate.js
 async function curate(repoRoot5, opts = {}) {
@@ -201820,6 +201858,9 @@ var STAGE_DEFAULTS = {
   // Authoring an executable scenario faithful to a spec claim is the hard,
   // load-bearing call (a weak scenario is false confidence) — opus.
   "guard.generate": "opus",
+  // The one evidence-retry per birth-failed claim — the same authoring task, so
+  // the same tier; a distinct stage so retry spend is attributed to the birth line.
+  "guard.retry": "opus",
   // Proposing a build/entry recipe is a modest structured task — sonnet.
   "guard.recipe": "sonnet",
   "rules.violationGen": "opus"
@@ -205110,6 +205151,129 @@ function listSandboxFiles(dir) {
   return out.sort();
 }
 
+// packages/guard-runner/dist/executor.js
+import { spawn as spawn9 } from "node:child_process";
+var DEFAULT_STEP_TIMEOUT_MS = 3e4;
+function executeStep(opts) {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_STEP_TIMEOUT_MS;
+  const [command, ...args] = opts.argv;
+  const start = Date.now();
+  return new Promise((resolve12) => {
+    const child = spawn9(command, args, {
+      cwd: opts.cwd,
+      env: opts.env,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let settled = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGKILL");
+    }, timeoutMs);
+    const finish = (capture) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      resolve12(capture);
+    };
+    child.stdout.on("data", (chunk3) => {
+      stdout += chunk3.toString("utf-8");
+    });
+    child.stderr.on("data", (chunk3) => {
+      stderr += chunk3.toString("utf-8");
+    });
+    child.on("error", (err) => {
+      finish({
+        exitCode: null,
+        signal: null,
+        stdout,
+        stderr,
+        timedOut,
+        spawnError: err.message,
+        durationMs: Date.now() - start
+      });
+    });
+    child.on("close", (code, signal) => {
+      finish({
+        exitCode: code,
+        signal,
+        stdout,
+        stderr,
+        timedOut,
+        durationMs: Date.now() - start
+      });
+    });
+    if (opts.stdin !== void 0)
+      child.stdin.write(opts.stdin);
+    child.stdin.end();
+  });
+}
+
+// packages/guard-runner/dist/preflight.js
+var ENTRY_PROBE_ARGVS = [[], ["--help"]];
+var ENTRY_PREFLIGHT_TIMEOUT_MS = 2e4;
+var defaultEntryProbeExecutor = async (fullArgv, recipeEnv, timeoutMs) => {
+  const sandbox = createSandbox({ recipeEnv });
+  try {
+    return await executeStep({ argv: fullArgv, cwd: sandbox.cwd, env: sandbox.env, timeoutMs });
+  } finally {
+    sandbox.cleanup();
+  }
+};
+async function preflightEntry(opts) {
+  const exec3 = opts.exec ?? defaultEntryProbeExecutor;
+  const timeoutMs = opts.timeoutMs ?? ENTRY_PREFLIGHT_TIMEOUT_MS;
+  const entry = opts.displayEntry.join(" ");
+  const probes = await Promise.all(ENTRY_PROBE_ARGVS.map(async (argv) => ({
+    argv: [...argv],
+    capture: await exec3([...opts.resolvedEntry, ...argv], opts.recipeEnv, timeoutMs)
+  })));
+  const ok = entryStarts(probes);
+  return { ok, entry, stderr: ok ? "" : startupOutput(probes[0].capture, timeoutMs), probes };
+}
+function entryStarts(probes) {
+  if (probes.some((p2) => startedCleanly(p2.capture)))
+    return true;
+  const shapes = probes.map((p2) => failureShape(p2.capture));
+  return shapes.some((s) => s !== shapes[0]);
+}
+function startedCleanly(c2) {
+  return !c2.spawnError && !c2.timedOut && c2.signal === null && c2.exitCode === 0;
+}
+function failureShape(c2) {
+  return JSON.stringify({
+    spawnError: c2.spawnError ?? null,
+    signal: c2.signal ?? null,
+    timedOut: c2.timedOut,
+    exitCode: c2.exitCode,
+    stdout: c2.stdout,
+    stderr: c2.stderr
+  });
+}
+function startupOutput(c2, timeoutMs) {
+  const parts = [];
+  const primary = c2.stderr || c2.stdout;
+  if (primary)
+    parts.push(primary.trimEnd());
+  if (c2.spawnError)
+    parts.push(`failed to spawn: ${c2.spawnError}`);
+  if (c2.timedOut)
+    parts.push(`(the entry produced no output within ${timeoutMs}ms and was killed)`);
+  if (parts.length === 0) {
+    parts.push(c2.exitCode !== null ? `(the entry exited ${c2.exitCode} with no output)` : `(the entry was killed by ${c2.signal})`);
+  }
+  return parts.join("\n");
+}
+function entryPreflightHeadline(entry, buildCommand) {
+  return `The recipe entry \`${entry}\` failed to start \u2014 it crashes before it runs, so every scenario would fail identically. Rebuild it with \`${buildCommand}\` (its build output is likely stale or incomplete), then retry.`;
+}
+function formatEntryPreflightError(opts) {
+  return [entryPreflightHeadline(opts.entry, opts.buildCommand), "", "Startup output:", opts.stderr].join("\n");
+}
+
 // packages/guard-runner/dist/capabilities/git.js
 import { spawnSync as spawnSync2 } from "node:child_process";
 import fs51 from "node:fs";
@@ -205190,67 +205354,6 @@ function applyCapabilities(setup, ctx) {
   }
 }
 
-// packages/guard-runner/dist/executor.js
-import { spawn as spawn9 } from "node:child_process";
-var DEFAULT_STEP_TIMEOUT_MS = 3e4;
-function executeStep(opts) {
-  const timeoutMs = opts.timeoutMs ?? DEFAULT_STEP_TIMEOUT_MS;
-  const [command, ...args] = opts.argv;
-  const start = Date.now();
-  return new Promise((resolve12) => {
-    const child = spawn9(command, args, {
-      cwd: opts.cwd,
-      env: opts.env,
-      stdio: ["pipe", "pipe", "pipe"]
-    });
-    let stdout = "";
-    let stderr = "";
-    let timedOut = false;
-    let settled = false;
-    const timer = setTimeout(() => {
-      timedOut = true;
-      child.kill("SIGKILL");
-    }, timeoutMs);
-    const finish = (capture) => {
-      if (settled)
-        return;
-      settled = true;
-      clearTimeout(timer);
-      resolve12(capture);
-    };
-    child.stdout.on("data", (chunk3) => {
-      stdout += chunk3.toString("utf-8");
-    });
-    child.stderr.on("data", (chunk3) => {
-      stderr += chunk3.toString("utf-8");
-    });
-    child.on("error", (err) => {
-      finish({
-        exitCode: null,
-        signal: null,
-        stdout,
-        stderr,
-        timedOut,
-        spawnError: err.message,
-        durationMs: Date.now() - start
-      });
-    });
-    child.on("close", (code, signal) => {
-      finish({
-        exitCode: code,
-        signal,
-        stdout,
-        stderr,
-        timedOut,
-        durationMs: Date.now() - start
-      });
-    });
-    if (opts.stdin !== void 0)
-      child.stdin.write(opts.stdin);
-    child.stdin.end();
-  });
-}
-
 // packages/guard-runner/dist/normalizers.js
 var CANONICAL_ORDER = [
   "abs-paths",
@@ -205881,16 +205984,27 @@ async function runGuard(opts) {
   }));
   const executable = planned.filter((p2) => p2.resolution.kind === "match" || p2.resolution.kind === "remap");
   const nonExecutable = planned.filter((p2) => p2.resolution.kind === "stale" || p2.resolution.kind === "orphaned");
-  if (!opts.skipBuild && executable.length > 0) {
+  const buildsOwnEntry = !opts.skipBuild && executable.length > 0;
+  if (buildsOwnEntry) {
     opts.onPhase?.("build");
     const build8 = await runBuild(repoRoot5, loaded.recipe.build, loaded.recipe.env);
     if (!build8.ok)
       return { status: "build-failed", build: build8, loadErrors };
   }
+  const resolvedEntry = resolveEntry(repoRoot5, loaded.recipe.entry);
+  if (buildsOwnEntry) {
+    const preflight = await preflightEntry({
+      resolvedEntry,
+      displayEntry: loaded.recipe.entry,
+      recipeEnv: loaded.recipe.env
+    });
+    if (!preflight.ok) {
+      return { status: "entry-preflight-failed", preflight, buildCommand: loaded.recipe.build, loadErrors };
+    }
+  }
   opts.onPhase?.("run", selected.length);
   const runId = buildRunId();
   const ranAt = (/* @__PURE__ */ new Date()).toISOString();
-  const resolvedEntry = resolveEntry(repoRoot5, loaded.recipe.entry);
   const stepTimeoutMs = opts.stepTimeoutMs ?? DEFAULT_STEP_TIMEOUT_MS;
   const concurrency = opts.concurrency ?? defaultRunConcurrency();
   const results = [];
@@ -206435,11 +206549,11 @@ function spawnGenerateRunner2(opts = {}) {
   return async (ctx) => {
     const refs = ctx.claims.map((c2) => c2.ref).join(",");
     const isRetry = ctx.claims.some((c2) => c2.retry);
-    const suffix = `${isRetry ? ":retry" : ""}${ctx.correction ? ":correction" : ""}`;
+    const stage = isRetry ? "guard.retry" : "guard.generate";
     const raw = await transport({
-      id: `guard.generate:${ctx.doc}:${refs}${suffix}`,
-      stage: "guard.generate",
-      model: opts.model,
+      id: `${stage}:${ctx.doc}:${refs}${ctx.correction ? ":correction" : ""}`,
+      stage,
+      model: isRetry ? opts.retryModel ?? opts.model : opts.model,
       fallbackModel: opts.fallbackModel,
       system: GENERATE_SYSTEM_PROMPT,
       user: buildAuthorUserPrompt(ctx),
@@ -206751,12 +206865,15 @@ async function captureProbes(opts) {
     const cached = await getCacheEntry(opts.repoRoot, GROUND_CACHE_NAME, key4);
     if (cached) {
       const parsed = ProbeTranscriptSchema.safeParse(cached);
-      if (parsed.success)
+      if (parsed.success) {
+        opts.onProbeCaptured?.();
         return parsed.data;
+      }
     }
     const capture = await exec3([...opts.resolvedEntry, ...argv], opts.recipeEnv);
     const transcript = toTranscript(argv, [...opts.displayEntry, ...argv], capture);
     await setCacheEntry(opts.repoRoot, GROUND_CACHE_NAME, key4, transcript);
+    opts.onProbeCaptured?.();
     return transcript;
   }));
 }
@@ -207021,6 +207138,7 @@ function deleteScenarioFiles(repoRoot5, ids) {
 
 // packages/guard-generator/dist/generate.js
 var GENERATE_CACHE_NAME = "guard/generate";
+var ENTRY_PREFLIGHT_ANCHOR = "(entry preflight)";
 function defaultConcurrency3() {
   const env = process.env.TRUECOURSE_MAX_CONCURRENCY;
   if (env) {
@@ -207090,7 +207208,12 @@ async function generateGuards(options) {
   const limit = pLimit(Math.max(1, options.concurrency ?? defaultConcurrency3()));
   const batchSize = Math.max(1, options.batchSize ?? defaultGenerateBatch2());
   const extractRunner = options.extractRunner ?? spawnExtractRunner({ transport: options.transport, model: options.models?.extract, fallbackModel: options.models?.fallback });
-  const generateRunner = options.generateRunner ?? spawnGenerateRunner2({ transport: options.transport, model: options.models?.generate, fallbackModel: options.models?.fallback });
+  const generateRunner = options.generateRunner ?? spawnGenerateRunner2({
+    transport: options.transport,
+    model: options.models?.generate,
+    retryModel: options.models?.retry,
+    fallbackModel: options.models?.fallback
+  });
   const coverageGaps = [];
   const errors = [];
   const extractionFailures = [];
@@ -207161,11 +207284,15 @@ async function generateGuards(options) {
     return buildPromise;
   };
   let resolvedEntryMemo = null;
+  let groundPlanned = 0;
+  let groundCaptured = 0;
   const groundClaims = async (claimTexts) => {
     const probes = deriveProbes(claimTexts, recipe.entry);
     const build8 = await buildPromise;
-    if (!build8.ok)
+    if (!build8.ok || probes.length === 0)
       return [];
+    groundPlanned += probes.length;
+    options.onGroundProgress?.(groundCaptured, groundPlanned);
     resolvedEntryMemo ??= resolveEntry(repoRoot5, recipe.entry);
     return captureProbes({
       repoRoot: repoRoot5,
@@ -207173,9 +207300,21 @@ async function generateGuards(options) {
       resolvedEntry: resolvedEntryMemo,
       displayEntry: recipe.entry,
       recipeFingerprint,
-      recipeEnv: recipe.env
+      recipeEnv: recipe.env,
+      onProbeCaptured: () => options.onGroundProgress?.(++groundCaptured, groundPlanned)
     });
   };
+  let entryPreflightMemo = null;
+  const preflightEntryOnce = () => {
+    entryPreflightMemo ??= (async () => {
+      const build8 = await buildPromise;
+      if (!build8.ok)
+        return null;
+      resolvedEntryMemo ??= resolveEntry(repoRoot5, recipe.entry);
+      return preflightEntry({ resolvedEntry: resolvedEntryMemo, displayEntry: recipe.entry, recipeEnv: recipe.env });
+    })();
+    return entryPreflightMemo;
+  };
   const priorSections = readPriorManifest(repoRoot5);
   const manifestByKey = new Map(priorSections.map((e) => [`${e.doc}\0${e.anchor}`, e]));
   const usedIds = existingScenarioIds(repoRoot5);
@@ -207199,9 +207338,11 @@ async function generateGuards(options) {
     });
     settledKeys.add(k);
     writeWorkingManifest();
+    options.onSectionSettled?.(settledKeys.size, plan.work.length);
   };
   const written = [];
   const birthFindings = [];
+  let entryPreflightFailure = null;
   let birthTotal = 0;
   let birthSettled = 0;
   let birthPassed = 0;
@@ -207248,6 +207389,20 @@ async function generateGuards(options) {
       return;
     settleChain = settleChain.then(() => settleCliSection(sectionByKey.get(k), refsBySection.get(k)));
   };
+  const deadEntry = async () => {
+    const preflight = await preflightEntryOnce();
+    if (!preflight || preflight.ok)
+      return false;
+    if (!entryPreflightFailure) {
+      entryPreflightFailure = { entry: preflight.entry, buildCommand: recipe.build, stderr: preflight.stderr };
+      errors.push({
+        doc: preflight.entry,
+        anchor: ENTRY_PREFLIGHT_ANCHOR,
+        message: formatEntryPreflightError(entryPreflightFailure)
+      });
+    }
+    return true;
+  };
   async function settleCliSection(section, refs) {
     const k = key2(section);
     for (const id of priorIdsOf(k))
@@ -207282,6 +207437,8 @@ async function generateGuards(options) {
         const message = `build failed (\`${build8.command}\`)${build8.timedOut ? " \u2014 timed out" : ""}`;
         for (const c2 of round1)
           localErrors.push(errorFrom({ candidate: c2, result: { failure: { actual: message } } }));
+      } else if (await deadEntry()) {
+        return;
       } else {
         birthTotal += round1.length;
         const r1 = await birthValidate(repoRoot5, round1, { skipBuild: true, onPhase: options.onBirthPhase, onScenarioSettled: bumpBirth });
@@ -207358,6 +207515,8 @@ async function generateGuards(options) {
   const authorTotal = authTasks.length;
   let authorDone = 0;
   const bumpAuthor = (n) => options.onAuthorProgress?.(authorDone += n, authorTotal);
+  if (authorTotal > 0)
+    options.onAuthorProgress?.(authorDone, authorTotal);
   const missTasks = [];
   for (const t2 of authTasks) {
     const cached = await readAuthorCache(repoRoot5, t2.claim, t2.section, recipeFingerprint);
@@ -207429,7 +207588,8 @@ async function generateGuards(options) {
     extractionFailures,
     orphaned,
     birthPassed,
-    manifestPath: manifestPath2(repoRoot5)
+    manifestPath: manifestPath2(repoRoot5),
+    ...entryPreflightFailure ? { entryPreflight: entryPreflightFailure } : {}
   };
 }
 var key2 = (s) => `${s.doc}\0${s.anchor}`;
@@ -207818,12 +207978,14 @@ function previewChars() {
   return 60 * 50;
 }
 async function estimateScanTokens(repoRoot5, prices) {
+  const decisions = readCorpusDecisions(repoRoot5);
+  const manualIncludes = decisions.manualIncludes ?? [];
+  const manualExcludes = new Set(decisions.manualExcludes ?? []);
   const docs = discoverDocs(repoRoot5);
-  const { toClassify } = prefilterDocs(docs);
-  const nClassify = toClassify.length;
-  const relevance = await Promise.all(toClassify.map((d3) => readRelevanceCache(repoRoot5, d3)));
-  const relevanceMissDocs = toClassify.filter((_2, i) => relevance[i] === null);
-  const cachedKeptDocs = toClassify.filter((_2, i) => relevance[i]?.include === true);
+  const plan = await planRelevanceWork(repoRoot5, docs, manualIncludes);
+  const nClassify = plan.toClassify.length;
+  const relevanceMissDocs = plan.needsCall;
+  const cachedKeptDocs = plan.toClassify.filter((d3) => plan.known.get(d3.path)?.include === true && !manualExcludes.has(d3.path));
   const cachedKeptTagged = await Promise.all(cachedKeptDocs.map((d3) => isAreaTagCached(repoRoot5, d3)));
   const cachedKeptTagMisses = cachedKeptTagged.filter((cached) => !cached).length;
   const estChangedKept = Math.round(relevanceMissDocs.length * KEEP_RATE);
@@ -210089,12 +210251,18 @@ async function runSpecDocsSkipped(opts = {}) {
     "Force-include a skipped doc with `spec docs include <path>`; force-exclude a kept doc with `spec docs exclude <path>`."
   );
 }
-async function runSpecDocsInclude(docPath, opts = {}) {
+async function runSpecDocsInclude(docPaths, opts = {}) {
   const root2 = repoRoot3(opts);
-  if (!docPath) return fail3("Missing doc path");
-  await addManualInclude(root2, docPath);
+  const paths = docPaths.filter(Boolean);
+  if (paths.length === 0) return fail3("Missing doc path");
+  for (const docPath of paths) {
+    await addManualInclude(root2, docPath);
+    O2.step(`Force-included ${docPath}`);
+  }
   await reScan2(root2);
-  gt(`Force-include ${docPath} \u2014 re-scanned. Review \`truecourse spec conflicts list\`.`);
+  gt(
+    paths.length === 1 ? `Force-include ${paths[0]} \u2014 re-scanned. Review \`truecourse spec conflicts list\`.` : `Force-included ${paths.length} docs \u2014 re-scanned once. Review \`truecourse spec conflicts list\`.`
+  );
 }
 async function runSpecDocsUninclude(docPath, opts = {}) {
   const root2 = repoRoot3(opts);
@@ -210103,12 +210271,18 @@ async function runSpecDocsUninclude(docPath, opts = {}) {
   await reScan2(root2);
   gt(`Removed force-include for ${docPath} \u2014 re-scanned.`);
 }
-async function runSpecDocsExclude(docPath, opts = {}) {
+async function runSpecDocsExclude(docPaths, opts = {}) {
   const root2 = repoRoot3(opts);
-  if (!docPath) return fail3("Missing doc path");
-  await addManualExclude(root2, docPath);
+  const paths = docPaths.filter(Boolean);
+  if (paths.length === 0) return fail3("Missing doc path");
+  for (const docPath of paths) {
+    await addManualExclude(root2, docPath);
+    O2.step(`Force-excluded ${docPath}`);
+  }
   await reScan2(root2);
-  gt(`Force-exclude ${docPath} \u2014 re-scanned. Review \`truecourse spec conflicts list\`.`);
+  gt(
+    paths.length === 1 ? `Force-exclude ${paths[0]} \u2014 re-scanned. Review \`truecourse spec conflicts list\`.` : `Force-excluded ${paths.length} docs \u2014 re-scanned once. Review \`truecourse spec conflicts list\`.`
+  );
 }
 async function runSpecDocsUnexclude(docPath, opts = {}) {
   const root2 = repoRoot3(opts);
@@ -210213,12 +210387,14 @@ var GUARD_GENERATE_STEPS = [
 var GUARD_STEP_STAGES = {
   index: ["guard.recipe"],
   extract: ["guard.extract"],
-  author: ["guard.generate"]
+  author: ["guard.generate"],
+  validate: ["guard.retry"]
 };
 function resolveGuardModels(repoRoot5) {
   return {
     extract: resolveModel("guard.extract", void 0, repoRoot5),
     generate: resolveModel("guard.generate", void 0, repoRoot5),
+    retry: resolveModel("guard.retry", void 0, repoRoot5),
     recipe: resolveModel("guard.recipe", void 0, repoRoot5),
     fallback: resolveFallbackModel(repoRoot5) ?? void 0
   };
@@ -210260,10 +210436,20 @@ async function guardGenerateInProcess(repoRoot5, options = {}) {
     cur = ni;
   };
   const withUsage = (key4, base2) => `${base2}${stageUsageTag(GUARD_STEP_STAGES[key4] ?? [], repoRoot5)}`;
+  let authorDone = 0;
+  let authorTotal = 0;
+  let authorFinished = false;
+  let groundCaptured = 0;
+  let groundPlanned = 0;
+  const authorDetail = () => {
+    const claims = `${authorDone}/${authorTotal} claim${authorTotal === 1 ? "" : "s"}`;
+    const base2 = groundPlanned > 0 ? `grounding probes ${groundCaptured}/${groundPlanned} \xB7 authoring ${claims}` : claims;
+    return withUsage("author", base2);
+  };
   let building = false;
-  let birthSeen = false;
   let birthDone = 0;
-  let birthTotal = 0;
+  let sectionsDone = 0;
+  let sectionsTotal = 0;
   let retrySeen = false;
   let retryDone = 0;
   let retryTotal = 0;
@@ -210274,10 +210460,10 @@ async function guardGenerateInProcess(repoRoot5, options = {}) {
       tracker?.start("validate");
       validateStarted = true;
     }
-    const parts = [building ? "building\u2026" : `birth ${birthDone}/${birthTotal}`];
+    const parts = [`sections ${sectionsDone}/${sectionsTotal}`, building ? "building\u2026" : `birth ${birthDone}`];
     if (retrySeen)
-      parts.push(`retrying failed claims ${retryDone}/${retryTotal}`);
-    tracker?.detail("validate", parts.join(" \xB7 "));
+      parts.push(`retrying ${retryDone}/${retryTotal}`);
+    tracker?.detail("validate", withUsage("validate", parts.join(" \xB7 ")));
   };
   tracker?.start("index");
   try {
@@ -210289,6 +210475,7 @@ async function guardGenerateInProcess(repoRoot5, options = {}) {
       generateRunner: options.generateRunner,
       recipeRunner: options.recipeRunner,
       onPlan: (total, work) => {
+        sectionsTotal = work;
         tracker?.done("index", withUsage("index", `${work} of ${total} section${total === 1 ? "" : "s"} changed`));
         cur = STEPS.indexOf("extract");
         tracker?.start("extract", `0 views`);
@@ -210305,27 +210492,30 @@ async function guardGenerateInProcess(repoRoot5, options = {}) {
       },
       onAuthorProgress: (done, total) => {
         advanceTo("author");
-        const detail = withUsage("author", `${done}/${total} claim${total === 1 ? "" : "s"}`);
-        if (done >= total)
-          tracker?.done("author", detail);
-        else
-          tracker?.detail("author", detail);
-      },
-      onBirthPhase: (phase, total) => {
-        if (phase === "build") {
-          building = true;
+        authorDone = done;
+        authorTotal = total;
+        if (done >= total) {
+          authorFinished = true;
+          tracker?.done("author", withUsage("author", `${done}/${total} claim${total === 1 ? "" : "s"}`));
         } else {
-          building = false;
-          if (!birthSeen && total !== void 0)
-            birthTotal = total;
+          tracker?.detail("author", authorDetail());
         }
+      },
+      onGroundProgress: (captured, planned) => {
+        groundCaptured = captured;
+        groundPlanned = planned;
+        if (authorFinished)
+          return;
+        advanceTo("author");
+        tracker?.detail("author", authorDetail());
+      },
+      onBirthPhase: (phase) => {
+        building = phase === "build";
         renderValidate();
       },
-      onBirthProgress: (done, total) => {
+      onBirthProgress: (done) => {
         building = false;
-        birthSeen = true;
         birthDone = done;
-        birthTotal = total;
         renderValidate();
       },
       onRetryProgress: (done, total) => {
@@ -210333,6 +210523,12 @@ async function guardGenerateInProcess(repoRoot5, options = {}) {
         retryDone = done;
         retryTotal = total;
         renderValidate();
+      },
+      onSectionSettled: (settled, total) => {
+        sectionsDone = settled;
+        sectionsTotal = total;
+        if (validateStarted)
+          renderValidate();
       }
     });
     for (let i = cur; i < STEPS.length; i++)
@@ -210356,7 +210552,7 @@ async function guardGenerateInProcess(repoRoot5, options = {}) {
     }
   }
 }
-var GUARD_USAGE_STAGES = ["guard.recipe", "guard.extract", "guard.generate"];
+var GUARD_USAGE_STAGES = ["guard.recipe", "guard.extract", "guard.generate", "guard.retry"];
 function sumGuardUsage() {
   const usage = getStageUsage();
   let calls = 0;
@@ -210404,6 +210600,8 @@ async function guardRunInProcess(repoRoot5, options = {}) {
     tracker?.done("run", `${n} scenario${n === 1 ? "" : "s"}`);
   } else if (result.status === "build-failed") {
     tracker?.error("build", `Build failed (\`${result.build.command}\`)${result.build.timedOut ? " \u2014 timed out" : ""}`);
+  } else if (result.status === "entry-preflight-failed") {
+    tracker?.error("build", `Entry failed to start: \`${result.preflight.entry}\` (rebuild via \`${result.buildCommand}\`)`);
   }
   return result;
 }
@@ -210467,6 +210665,15 @@ async function runGuardRun(opts = {}) {
       process.exit(1);
       return;
     }
+    case "entry-preflight-failed": {
+      O2.error(`The recipe entry \`${result.preflight.entry}\` failed to start \u2014 every scenario would fail identically.`);
+      for (const line of result.preflight.stderr.trimEnd().split("\n")) console.log(`  ${line}`);
+      O2.step(`Rebuild it with \`${result.buildCommand}\` (its build output is likely stale or incomplete), then re-run \`truecourse guard run\`.`);
+      printLoadErrors(result.loadErrors);
+      gt("Aborted \u2014 the entry could not start; no scenarios ran.");
+      process.exit(1);
+      return;
+    }
     case "ok":
       break;
   }
@@ -210549,6 +210756,13 @@ async function runGuardGenerate(opts = {}) {
     gt("Add or fix `.truecourse/scenarios/recipe.json` and retry.");
     process.exit(1);
   }
+  if (guard.entryPreflight) {
+    O2.error(`The recipe entry \`${guard.entryPreflight.entry}\` failed to start \u2014 every scenario would fail identically, so nothing was validated.`);
+    for (const line of guard.entryPreflight.stderr.trimEnd().split("\n")) console.log(`  ${line}`);
+    O2.step(`Rebuild it with \`${guard.entryPreflight.buildCommand}\` (its build output is likely stale or incomplete), then re-run \`truecourse guard generate\`.`);
+    gt("Aborted \u2014 the entry could not start; no scenarios were validated.");
+    process.exit(1);
+  }
   if (guard.recipe?.status === "discovered") {
     O2.step(`recipe      wrote ${guard.recipe.wrotePath} \u2014 review and commit it`);
   }
@@ -210772,6 +210986,7 @@ var STAGE_LABEL = {
   "contract.gapJudge": "Contract \xB7 gap judge",
   "guard.extract": "Guard  \xB7 claim extract",
   "guard.generate": "Guard  \xB7 scenario gen",
+  "guard.retry": "Guard  \xB7 scenario retry",
   "guard.recipe": "Guard  \xB7 recipe discover",
   "rules.violationGen": "Rules  \xB7 violation gen"
 };
@@ -211080,7 +211295,7 @@ async function runHooksRun() {
 
 // tools/cli/src/index.ts
 var program2 = new Command();
-program2.name("truecourse").version("0.7.0-next.0").description("TrueCourse CLI \u2014 analyze your repository and open the dashboard");
+program2.name("truecourse").version("0.7.0-next.2").description("TrueCourse CLI \u2014 analyze your repository and open the dashboard");
 var dashboardCmd = program2.command("dashboard").description("Start the TrueCourse dashboard and open it in your browser").option("--reconfigure", "Re-prompt for console vs background service mode").option("--service", "Run as a background service (skips mode prompt)").option("--console", "Run in this terminal (skips mode prompt)").action(async (options) => {
   if (options.service && options.console) {
     console.error("error: --service and --console are mutually exclusive");
@@ -211193,14 +211408,14 @@ docsCmd.command("list").description("List the kept (corpus) docs with their area
 docsCmd.command("skipped").description("List docs the relevance filter excluded from extraction").action(async () => {
   await runSpecDocsSkipped();
 });
-docsCmd.command("include <path>").description("Force-include a skipped doc and re-scan").action(async (docPath) => {
-  await runSpecDocsInclude(docPath);
+docsCmd.command("include <path...>").description("Force-include one or more skipped docs and re-scan once").action(async (docPaths) => {
+  await runSpecDocsInclude(docPaths);
 });
 docsCmd.command("uninclude <path>").description("Remove a force-include override").action(async (docPath) => {
   await runSpecDocsUninclude(docPath);
 });
-docsCmd.command("exclude <path>").description("Force-exclude a kept doc from the corpus and re-scan").action(async (docPath) => {
-  await runSpecDocsExclude(docPath);
+docsCmd.command("exclude <path...>").description("Force-exclude one or more kept docs from the corpus and re-scan once").action(async (docPaths) => {
+  await runSpecDocsExclude(docPaths);
 });
 docsCmd.command("unexclude <path>").description("Remove a force-exclude override").action(async (docPath) => {
   await runSpecDocsUnexclude(docPath);