mandrel 2.9.0 → 2.10.0

package/.agents/scripts/lib/orchestration/story-close/phases/review-core.js

@@ -9,7 +9,9 @@
  * file (Story #3653 established the shared-spine contract).
  */
 
+import { countChangedLines } from '../../../audit-suite/index.js';
 import { gitSpawn } from '../../../git-utils.js';
+import { appendFindingsYield } from '../../../observability/metrics-ledger.js';
 import { computeChangeSet } from '../../change-set.js';
 import { runCodeReview } from '../../code-review.js';
 import { runLocalLensReview } from './local-lens-review.js';
@@ -57,6 +59,8 @@ import { runLocalLensReview } from './local-lens-review.js';
  *   computeChangeSetFn?: typeof computeChangeSet,
  *   runCodeReviewFn?: typeof runCodeReview,
  *   runLocalLensReviewFn?: typeof runLocalLensReview,
+ *   countChangedLinesFn?: typeof countChangedLines,
+ *   appendFindingsYieldFn?: typeof appendFindingsYield,
  * }} args
  * @returns {Promise<object>} Raw result envelope from `runCodeReview`, augmented
  *   with a `localLensReview` field carrying the Story-scope local-lens pass
@@ -75,6 +79,8 @@ export async function runStoryReviewCore({
   computeChangeSetFn = computeChangeSet,
   runCodeReviewFn = runCodeReview,
   runLocalLensReviewFn = runLocalLensReview,
+  countChangedLinesFn = countChangedLines,
+  appendFindingsYieldFn = appendFindingsYield,
 }) {
   const storyIdNum = Number(storyId);
 
@@ -84,6 +90,16 @@ export async function runStoryReviewCore({
   // honour without retrying (Story #4603).
   const changeSet = computeChangeSetFn({ baseRef, headRef, gitSpawnFn });
 
+  // The one changed-LINE enumeration (Story #4699 — the lens diff-floor's
+  // size signal). Probed only when the file enumeration succeeded with a
+  // non-empty set: a null/empty set already yields an empty lens roster, so
+  // a second git spawn would buy nothing. `null` = count unknown → the
+  // floor fails open (no skip).
+  const changedLineCount =
+    Array.isArray(changeSet.files) && changeSet.files.length > 0
+      ? countChangedLinesFn({ baseRef, headRef, gitSpawnFn })
+      : null;
+
   const opts = {
     scope: 'story',
     ticketId: storyIdNum,
@@ -110,6 +126,7 @@ export async function runStoryReviewCore({
     baseRef,
     headRef,
     changedFiles: changeSet.files,
+    changedLineCount,
     storyId: storyIdNum,
     progress,
     progressTag,
@@ -117,5 +134,61 @@ export async function runStoryReviewCore({
   });
 
   const result = await runCodeReviewFn(opts);
+
+  // Findings-yield ledger (Story #4699) — record what this close's lens
+  // pass produced (or floor-skipped) so the roster can later be tuned on
+  // measurement. Best-effort: a ledger failure never fails the review.
+  try {
+    const yieldEntries = buildLensYieldEntries(localLensReview);
+    if (yieldEntries !== null) {
+      await appendFindingsYieldFn({
+        storyId: storyIdNum,
+        cli: 'story-close-review',
+        lenses: yieldEntries,
+        diffFloor: localLensReview?.floorSkip ?? null,
+      });
+    }
+  } catch (err) {
+    progress(
+      progressTag,
+      `⚠️ findings-yield ledger append failed (continuing): ${err?.message ?? err}`,
+    );
+  }
+
   return { ...result, localLensReview, changeSet };
 }
+
+/**
+ * Fold the lens-pass envelope into per-lens findings-yield entries
+ * (Story #4699). One entry per lens in the matched roster: the lens name,
+ * the count of materialization findings attributed to it, and whether the
+ * diff-floor skipped its materialization. Returns `null` when the roster is
+ * empty (nothing ran, nothing skipped — no record to write).
+ *
+ * Module-local: an implementation detail of {@link runStoryReviewCore},
+ * asserted through the appended record's shape rather than imported
+ * directly.
+ *
+ * @param {object|null|undefined} localLensReview
+ * @returns {Array<{ lens: string, findings: number, skippedByFloor: boolean }>|null}
+ */
+function buildLensYieldEntries(localLensReview) {
+  const lenses = Array.isArray(localLensReview?.lenses)
+    ? localLensReview.lenses.filter((l) => typeof l === 'string' && l.length)
+    : [];
+  if (lenses.length === 0) return null;
+  const skippedByFloor = localLensReview?.floorSkip?.skip === true;
+  const findingsByLens = new Map();
+  for (const finding of localLensReview?.materialized?.findings ?? []) {
+    if (typeof finding?.audit !== 'string') continue;
+    findingsByLens.set(
+      finding.audit,
+      (findingsByLens.get(finding.audit) ?? 0) + 1,
+    );
+  }
+  return lenses.map((lens) => ({
+    lens,
+    findings: skippedByFloor ? 0 : (findingsByLens.get(lens) ?? 0),
+    skippedByFloor,
+  }));
+}

package/.agents/scripts/lib/templates/decomposer-prompts.js

@@ -109,7 +109,7 @@ You MUST respond ONLY with a valid JSON array of objects. No prose, no markdown
 **Slug format**: \`^[a-z0-9][a-z0-9-]*$\` — hyphen-case only. Underscores are rejected by the validator.
 
 ### STORY BODY SCHEMA (REQUIRED FOR EVERY STORY):
-\`body\` MUST be a **string** — the serialized markdown produced by \`serialize()\` from \`lib/story-body/story-body.js\`. Do NOT emit \`body\` as a JSON object: an object body throws \`StoryBodyParseError\` in the reconciler (Story #3302) and is discarded by the GitHub provider, producing an empty issue body. Stories are consumed by non-interactive sub-agents that must self-verify from the Story ticket alone — so the ticket must carry everything an agent needs to execute and self-verify.
+\`body\` is either the serialized markdown **string** (the section format below) or a **structured object** carrying the same fields (\`goal\`, optional \`slicing\` / \`spec\`, \`changes\`, optional \`non_goals\` / \`wide\` / \`reason_to_exist\` / \`estimated_test_files\`) — persist parses either shape and serializes the canonical markdown itself, so you never need to read \`story-body.js\` or hand-assemble the markdown (the \`stories.template.json\` file emitted next to the plan-context envelope is a ready-to-fill structured-object skeleton). Stories are consumed by non-interactive sub-agents that must self-verify from the Story ticket alone — so the ticket must carry everything an agent needs to execute and self-verify.
 
 The \`acceptance[]\` and \`verify[]\` arrays live at the **top level** of the Story ticket object — that is the machine contract the validator reads. Author each list **once, at top level**, and **omit** the \`## Acceptance\` / \`## Verify\` sections from the authored \`body\` string: persist syncs the top-level arrays into those sections so the GitHub issue stays a complete executable document. The validator resolves both fields from the top level, so an omitted section is the expected shape, not a violation.
 
@@ -138,10 +138,6 @@ The serialized \`body\` string renders these markdown sections (in order):
     - <exact command or test path> (<tier>)
     - ...
 
-    ## References
-    - {"path": "<read-only dependency path>", "assumption": "exists"}
-    - ...
-
     ## Non-Goals
     - <a capability or change this Story explicitly does NOT deliver>
     - ...
@@ -149,7 +145,7 @@ The serialized \`body\` string renders these markdown sections (in order):
 #### STORY BODY RULES:
 
 - **goal** (in body string): One sentence stating WHY this Story exists.
-- **spec** (optional, in body string as \`## Spec\`): Lean technical approach only. If the Spec is large enough to feel like its own document, the Story is probably too big — split it. Persist keeps Specs inline and rejects over-budget Specs (never writes them under \`docs/\`).
+- **spec** (optional, in body string as \`## Spec\`): Lean technical approach only, at the altitude the SPEC PROSE CONTRACT below fixes — contract and invariants, never implementation narration. If the Spec is large enough to feel like its own document, the Story is probably too big — split it. Persist keeps Specs inline and rejects over-budget Specs (never writes them under \`docs/\`).
 - **slicing** (optional): Ordered intra-session checkpoints for one Story. Not a fan-out table and not a duplicate of Acceptance.
 - **changes** (in body string): Each entry is an object \`{ path, assumption }\` where \`assumption\` is one of \`creates | refactors-existing | deletes\`. Acceptable path shapes include explicit files (\`src/components/Foo.tsx\`), glob patterns (\`tests/e2e/*.spec.ts\`, \`**/*.astro\`), and module identifiers that resolve to files. Use \`refactors-existing\` for in-place edits to a file already on \`main\`; \`creates\` for net-new files; \`deletes\` for removals.
 - **acceptance** (top-level array on the ticket object): Items MUST be observable from outside the agent. Acceptable shapes: a specific command exits 0, a file exists at a given path, a snapshot test matches, a \`data-testid\` resolves under a given selector, a row count in a fixture matches. UNACCEPTABLE: "verify by reading the diff", "looks good", "matches the spec" — push these down into a \`verify\` command instead.
@@ -162,6 +158,17 @@ The serialized \`body\` string renders these markdown sections (in order):
 - **Bodies record decisions, never questions to the operator.** Never persist an open question ("Flag if…", "TBD", "confirm with the operator") into a Story body — the executing sub-agent is non-interactive and cannot answer it. Resolve the unknown before authoring, or restate it as a declarative Key Assumption the agent can act on.
 - **non_goals** (OPTIONAL, in body string as the \`## Non-Goals\` section): A short list of capabilities or changes this Story explicitly does NOT deliver — an advisory negative-scope bound that fences the executing agent away from adjacent work. It is **advisory and NON-GATING**: the validator does not require, count, or reject on it, and an absent or empty section renders nothing. Use the EXACT single-word hyphenated heading spelling \`## Non-Goals\` (a space-separated heading like \`## Out of Scope\` is NOT recognized by the parser and will be dropped). Reach for it when a Story's negative boundary is non-obvious from its \`acceptance[]\` alone; omit it otherwise.
 
+#### SPEC PROSE CONTRACT — state the contract, not the implementation:
+
+The Story is executed by a frontier-model deliverer that reads the codebase itself. Author \`## Spec\` (and Goal prose) at contract level:
+
+- **Spec states the contract and invariants**: interfaces, status codes, security invariants, and load-bearing constraints — each with its why. That is the whole job of the Spec.
+- **Implementation choices belong to the deliverer** unless a choice is load-bearing; a load-bearing choice is stated as a constraint (with why it binds), never as a walkthrough of how to code it.
+- **No per-file behavior paragraphs.** The \`## Changes\` list already names the footprint; do not narrate what each file will do.
+- **No current-state narration.** Do not describe how the codebase works today as scene-setting; the deliverer reads the code. The only current-state prose allowed is a claim a decision depends on, opening with \`Current state (verified <date>)\` per the observed-behavior rule above.
+- **Do not author a \`## References\` section.** Read-only context the deliverer needs is discoverable from the contract and the footprint.
+- **Acceptance criteria remain the binding contract** — the Spec constrains and explains; \`acceptance[]\` binds.
+
 #### DETERMINISTIC BODY-FORMAT LINTS — author lint-clean by construction:
 
 Persist enforces the deterministic body-format rules below and **rejects** an authored body that violates any of them. Author every Story to satisfy all of them on the FIRST draft — each rule is stated example-first so there is nothing to discover by trial-and-error. The two auto-fixable rules (\`changes-path-entry-shape\`, \`verify-tier-suffix\`) also emit the corrected form in the dry-run failure output, but authoring them right up front avoids the round-trip entirely.

package/.agents/scripts/lib/test-env.js

@@ -1,3 +1,62 @@
+import { mkdtempSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { TEST_TEMP_ROOT_ENV } from './config/temp-paths.js';
+
+/**
+ * Per-process memo for the created scratch dir, so repeated calls in one
+ * runner process (e.g. building env bags for several chunks) share a single
+ * scratch tree instead of minting one dir per call.
+ */
+let _createdScratchDir = null;
+
+/**
+ * Test-only: clear the per-process scratch memo so a suite can exercise the
+ * creation branch repeatedly in one process.
+ */
+export function _clearTestScratchTempRootCache() {
+  _createdScratchDir = null;
+}
+
+/**
+ * Ensure an absolute per-process scratch tempRoot is available for the test
+ * run and return it (Story #4696).
+ *
+ * If `baseEnv` already carries an absolute `MANDREL_TEST_TEMP_ROOT` (the
+ * common case for a child process that inherits the parent runner's env),
+ * that value is reused verbatim so every chunk / worker of a single suite
+ * run shares one scratch dir. Otherwise a fresh `os.tmpdir()` directory is
+ * created once per process (memoized). Every stream writer that resolves a
+ * relative tempRoot then lands under this dir instead of the repo's real
+ * `temp/` telemetry tree — the regression that let 99% of friction records
+ * be test-fixture pollution.
+ *
+ * Directly unit-tested via the injectable `mkdtemp` seam in
+ * `tests/lib/test-env.test.js` (Story #4711).
+ *
+ * @param {NodeJS.ProcessEnv} [baseEnv=process.env]
+ * @param {{ mkdtemp?: typeof mkdtempSync }} [deps] Injectable for tests.
+ * @returns {string} absolute scratch tempRoot
+ */
+export function ensureTestScratchTempRoot(
+  baseEnv = process.env,
+  { mkdtemp = mkdtempSync } = {},
+) {
+  const existing = baseEnv?.[TEST_TEMP_ROOT_ENV];
+  if (
+    typeof existing === 'string' &&
+    existing.length > 0 &&
+    path.isAbsolute(existing)
+  ) {
+    return existing;
+  }
+  if (_createdScratchDir === null) {
+    _createdScratchDir = mkdtemp(path.join(os.tmpdir(), 'mandrel-test-temp-'));
+  }
+  return _createdScratchDir;
+}
+
 /**
  * Build a webhook-safe child-process environment for test runners.
  *
@@ -27,6 +86,11 @@
  *     covered by `cleanGitEnv` in `git-utils.js`; this is the same scrub
  *     for test child processes, which may spawn git directly. Tests that
  *     need a `GIT_*` variable set it explicitly on their own spawn.
+ *   - `MANDREL_TEST_TEMP_ROOT` is set to an absolute per-process scratch
+ *     dir (Story #4696). Any test that reaches a stream writer without
+ *     injecting its own absolute tempRoot lands under scratch instead of
+ *     the repo's real `temp/` telemetry tree, so the suite can no longer
+ *     append fixture records to friction / lifecycle / trace streams.
  *
  * @param {NodeJS.ProcessEnv} baseEnv
  * @returns {NodeJS.ProcessEnv}
@@ -39,5 +103,6 @@ export function buildWebhookSafeTestEnv(baseEnv = process.env) {
   if (env.MANDREL_ALLOW_TEST_WEBHOOKS !== '1') {
     delete env.NOTIFICATION_WEBHOOK_URL;
   }
+  env[TEST_TEMP_ROOT_ENV] = ensureTestScratchTempRoot(baseEnv);
   return env;
 }

package/.agents/scripts/plan-context.js

@@ -18,18 +18,21 @@
  *                             Stories. Envelope carries `sourceTickets[]`.
  *
  * Flags:
- *   --out <path>     Also write the envelope to <path> (parent dirs created).
+ *   --out <path>     Write the envelope to <path> (parent dirs created).
  *                    `/plan` points this at `<plan-dir>/plan-context.json`,
  *                    which is where `plan-persist.js` auto-discovers the
  *                    `--tickets` source ids from (Story #4554). Without a
  *                    captured envelope persist cannot know a `--tickets` run
  *                    happened, and superseding degrades to the
- *                    `--source-tickets` flag.
- *   --pretty         Pretty-print the JSON envelope.
+ *                    `--source-tickets` flag. With --out, stdout carries a
+ *                    compact digest naming the artifact instead of the full
+ *                    envelope (Story #4708 script-output contract).
+ *   --pretty         Pretty-print the JSON envelope (no-op with --out).
  *
- * stdout is reserved for the JSON envelope (Story #2278 discipline):
- * `routeAllOutputToStderr()` runs before any pipeline code so a captured
- * file is unconditionally parseable by `JSON.parse`.
+ * stdout is reserved for a single JSON payload (Story #2278 discipline) —
+ * the envelope, or the digest when --out captures it:
+ * `routeAllOutputToStderr()` runs before any pipeline code so the stream
+ * is unconditionally parseable by `JSON.parse`.
  *
  * Exit codes:
  *   0 — envelope emitted.
@@ -49,7 +52,11 @@ import {
   validateOrchestrationConfig,
 } from './lib/config-resolver.js';
 import { Logger, routeAllOutputToStderr } from './lib/Logger.js';
-import { buildPlanContext } from './lib/orchestration/plan-context.js';
+import {
+  buildPlanContext,
+  renderStoriesTemplate,
+  STORIES_TEMPLATE_FILENAME,
+} from './lib/orchestration/plan-context.js';
 import { recordPlanInvocation } from './lib/orchestration/plan-metrics.js';
 import { createProvider } from './lib/provider-factory.js';
 
@@ -111,8 +118,31 @@ export async function emitPlanContext({
   const json = pretty
     ? JSON.stringify(envelope, null, 2)
     : JSON.stringify(envelope);
-  stdout.write(`${json}\n`);
-  if (outPath) await writeEnvelopeFile(outPath, json);
+  if (outPath) {
+    // Script-output contract (Story #4708, AC-5): the full envelope is a
+    // ~40KB artifact that would ride resident in the transcript for every
+    // later turn. When it is captured to disk anyway, stdout carries a
+    // compact digest naming the artifact instead of the payload itself.
+    await writeEnvelopeFile(outPath, json);
+    await writeStoriesTemplateFile(outPath);
+    const resolved = path.resolve(outPath);
+    const digest = {
+      digest: 'plan-context',
+      mode: envelope.mode,
+      out: resolved,
+      storiesTemplate: path.join(
+        path.dirname(resolved),
+        'stories.template.json',
+      ),
+      bytes: Buffer.byteLength(json, 'utf8'),
+      sourceTickets: (envelope.sourceTickets ?? []).map((t) => t.id),
+      duplicates: (envelope.duplicates ?? []).length,
+      complexityRoute: envelope.complexityRoute?.route ?? null,
+    };
+    stdout.write(`${JSON.stringify(digest)}\n`);
+  } else {
+    stdout.write(`${json}\n`);
+  }
   return envelope;
 }
 
@@ -140,6 +170,33 @@ async function writeEnvelopeFile(outPath, json) {
   Logger.info(`[plan-context] wrote envelope to ${resolved}`);
 }
 
+/**
+ * Emit the ready-to-fill Story authoring template next to the captured
+ * envelope (Story #4707 — one-shot authoring). The planner copies it to
+ * `stories.json` and fills the placeholders; no step of the authoring path
+ * requires reading `story-body.js` source. Written whenever `--out` is
+ * passed, and throwing on failure for the same reason the envelope write
+ * does: a silently missing template re-opens the format-discovery loop it
+ * exists to close.
+ *
+ * @param {string} outPath The envelope `--out` path; the template lands in
+ *   the same directory as {@link STORIES_TEMPLATE_FILENAME}.
+ */
+async function writeStoriesTemplateFile(outPath) {
+  const resolved = path.resolve(
+    path.dirname(path.resolve(outPath)),
+    STORIES_TEMPLATE_FILENAME,
+  );
+  try {
+    await writeFile(resolved, renderStoriesTemplate(), 'utf8');
+  } catch (err) {
+    throw new Error(
+      `[plan-context] cannot write stories template to ${resolved}: ${err.message}`,
+    );
+  }
+  Logger.info(`[plan-context] wrote ready-to-fill template to ${resolved}`);
+}
+
 async function main() {
   const { values } = parseArgs({
     options: {

package/.agents/scripts/plan-critics.js

@@ -9,6 +9,11 @@
  * act on it — dispatching a fresh-context critic sub-agent and folding its
  * findings into a re-author round **before** the plan is persisted.
  *
+ * The pre-mortem's external-dependency arm (Story #4700) needs the repo's own
+ * manifests to tell an external scoped package from a local one, so this CLI
+ * reads them (`collectRepoPackages`) and passes the specifier set down — the
+ * pure evaluation modules never touch the filesystem.
+ *
  * Why here and nowhere else. The evaluation used to run inside
  * `run-plan-persist.js`, after authoring was finished and immediately before
  * `createStoryIssues` — the one point in the flow where nothing can act on a
@@ -43,7 +48,7 @@
  * Exit codes: 0 success (any verdict); 1 usage/IO error.
  */
 
-import { readFile } from 'node:fs/promises';
+import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { parseArgs } from 'node:util';
 
@@ -63,6 +68,101 @@ const USAGE = 'Usage: plan-critics.js --stories <file> [--tech-spec <file>]';
 /** The `cli` discriminator every ledger record from this surface carries. */
 export const PLAN_CRITICS_CLI = 'plan-critics';
 
+/** Dependency maps a manifest can declare a package under. */
+const DEP_MAP_KEYS = [
+  'dependencies',
+  'devDependencies',
+  'optionalDependencies',
+  'peerDependencies',
+];
+
+/** Add a manifest's own name and every declared dependency to `names`. */
+function collectPackageIdentity(names, pkg) {
+  if (typeof pkg?.name === 'string') names.add(pkg.name);
+  for (const key of DEP_MAP_KEYS) {
+    const map = pkg?.[key];
+    if (map && typeof map === 'object') {
+      for (const dep of Object.keys(map)) names.add(dep);
+    }
+  }
+}
+
+/** Best-effort JSON read: a missing or malformed file yields `null`. */
+async function readJsonIfPresent(filePath) {
+  try {
+    return JSON.parse(await readFile(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Normalize the `workspaces` field (array or `{ packages: [] }`) to a list. */
+function workspacePatterns(pkg) {
+  const ws = pkg?.workspaces;
+  if (Array.isArray(ws)) return ws;
+  if (Array.isArray(ws?.packages)) return ws.packages;
+  return [];
+}
+
+/**
+ * Resolve `workspaces` patterns to child `package.json` paths. Handles the two
+ * common shapes — a `dir/*` glob (expanded one level) and a literal path — and
+ * never throws: an unreadable base directory is skipped.
+ *
+ * @param {string} rootDir
+ * @param {string[]} patterns
+ * @returns {Promise<string[]>}
+ */
+async function resolveWorkspaceManifestPaths(rootDir, patterns) {
+  const paths = [];
+  for (const pattern of patterns) {
+    if (typeof pattern !== 'string') continue;
+    if (!pattern.endsWith('/*')) {
+      paths.push(path.resolve(rootDir, pattern, 'package.json'));
+      continue;
+    }
+    const base = path.resolve(rootDir, pattern.slice(0, -2));
+    let entries;
+    try {
+      entries = await readdir(base, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        paths.push(path.join(base, entry.name, 'package.json'));
+      }
+    }
+  }
+  return paths;
+}
+
+/**
+ * Gather the package specifiers the repo's own manifests declare — the set the
+ * pre-mortem external-dependency probe (Story #4700) measures a scoped-package
+ * reference against. Includes the root manifest's own name and dependency maps
+ * plus every workspace manifest's. Best-effort: a repo with no `package.json`
+ * yields `[]`, which only widens what the probe treats as external.
+ *
+ * @param {{ rootDir?: string }} [opts]
+ * @returns {Promise<string[]>}
+ */
+export async function collectRepoPackages({ rootDir = process.cwd() } = {}) {
+  const root = await readJsonIfPresent(path.join(rootDir, 'package.json'));
+  if (!root) return [];
+  const names = new Set();
+  collectPackageIdentity(names, root);
+  const wsPaths = await resolveWorkspaceManifestPaths(
+    rootDir,
+    workspacePatterns(root),
+  );
+  for (const wsPath of wsPaths) {
+    const pkg = await readJsonIfPresent(wsPath);
+    if (pkg) collectPackageIdentity(names, pkg);
+  }
+  return [...names];
+}
+
 /**
  * Read the draft artifacts the critics evaluate.
  *
@@ -155,21 +255,32 @@ export async function recordCriticSkips(
  *   storiesPath: string,
  *   techSpecPath?: string|null,
  *   config?: object,
+ *   knownPackages?: string[],
  *   append?: typeof appendCriticSkip,
  * }} args
+ * @param {string[]} [args.knownPackages] - Package specifiers the repo's own
+ *   manifests declare, forwarded to the pre-mortem external-dependency probe
+ *   (Story #4700). `main()` resolves them via `collectRepoPackages`; tests may
+ *   pass an explicit set or omit it (defaults to `[]`).
  * @returns {Promise<{ consolidation: object, premortem: object, textHygiene: object }>}
  */
 export async function evaluateCriticArtifacts({
   storiesPath,
   techSpecPath = null,
   config = {},
+  knownPackages = [],
   append = appendCriticSkip,
 }) {
   const { tickets, techSpecContent } = await loadCriticArtifacts({
     storiesPath,
     techSpecPath,
   });
-  const verdict = evaluatePlanCritics({ techSpecContent, tickets, config });
+  const verdict = evaluatePlanCritics({
+    techSpecContent,
+    tickets,
+    config,
+    knownPackages,
+  });
   await recordCriticSkips(verdict, config, { append });
   return verdict;
 }
@@ -191,9 +302,10 @@ async function main() {
       ? path.resolve(values['tech-spec'])
       : null,
     config: resolveConfig(),
+    knownPackages: await collectRepoPackages(),
   });
 
-  process.stdout.write(`${JSON.stringify(verdict, null, 2)}\n`);
+  process.stdout.write(`${JSON.stringify(verdict)}\n`);
   return 0;
 }
 

package/.agents/scripts/plan-persist.js

@@ -34,6 +34,13 @@
  *                             ids, for hand-driven runs. Each id must be
  *                             claimed by exactly one Story's `supersedes[]`;
  *                             they are commented on and closed as superseded
+ *   --route-downgrade-reason <text>
+ *                             Audited planner downgrade (Story #4707): treat
+ *                             the envelope's `full` complexity verdict as
+ *                             `lite`, recording <text> on every Story's
+ *                             story-plan-state checkpoint. Absent this flag
+ *                             the deterministic verdict stands; the gate
+ *                             itself still fails toward `full`
  *   --no-close-superseded     Keep the source tickets open (no comment, no
  *                             close) — for a genuinely partial supersede
  *   --dry-run                 Assemble + validate without GitHub writes
@@ -100,6 +107,7 @@ const CLI_OPTIONS = {
   'plan-context': { type: 'string' },
   'plan-acceptance': { type: 'string' },
   'source-tickets': { type: 'string' },
+  'route-downgrade-reason': { type: 'string' },
   'close-superseded': { type: 'boolean', default: true },
   'no-close-superseded': { type: 'boolean', default: false },
   'dry-run': { type: 'boolean', default: false },
@@ -113,6 +121,7 @@ const USAGE =
   '[--tech-spec <file>] [--plan-dir <dir>] [--plan-context <file>] ' +
   '[--plan-acceptance <file>] ' +
   '[--source-tickets <ids>] [--no-close-superseded] ' +
+  '[--route-downgrade-reason <text>] ' +
   '[--dry-run] [--force-review] ' +
   '[--allow-over-budget] [--allow-large-fan-out]';
 
@@ -204,6 +213,7 @@ export function buildPersistOptions(values, paths, planContextEnvelope) {
     skipCleanup: values['dry-run'],
     sourceTicketIds: source.ids,
     sourceTicketOrigin: source.origin,
+    routeDowngradeReason: values['route-downgrade-reason'] ?? null,
     // Default-on: `--no-close-superseded` is the explicit escape and always
     // wins over the (default `true`) `--close-superseded`.
     closeSuperseded:
@@ -328,7 +338,7 @@ async function main() {
 
   await attachPlanMetrics(result, config, metricsSince);
 
-  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  process.stdout.write(`${JSON.stringify(result)}\n`);
 }
 
 runAsCli(import.meta.url, main, { source: 'plan-persist' });

package/.agents/scripts/plan-run-epilogue.js

@@ -67,7 +67,7 @@ export async function main(argv = process.argv.slice(2)) {
   });
   warnOnUnresolvedBase(result);
   warnOnEmptyRollup(result);
-  Logger.info(JSON.stringify(result, null, 2));
+  Logger.info(JSON.stringify(result));
   if (result.errors?.length) {
     process.exitCode = 1;
   }