mandrel 2.9.0 → 2.11.0

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

@@ -13,10 +13,17 @@
  */
 
 import {
+  evaluateLensDiffFloor,
+  resolveLensDiffFloor,
   runAuditSuite,
   selectLocalLenses,
 } from '../../../audit-suite/index.js';
+import { resolveConfig } from '../../../config-resolver.js';
 import { gitSpawn } from '../../../git-utils.js';
+import {
+  emitRuntimeFriction,
+  RUNTIME_FRICTION_CATEGORIES,
+} from '../../../observability/runtime-friction.js';
 import { computeChangeSet } from '../../change-set.js';
 
 /**
@@ -180,10 +187,21 @@ function resolveLensChangeSet({
  * this the default review provider dropped the materialized envelope, so the
  * pass was a progress log line with no reader.
  *
+ * Story #4699 — the **lens diff-floor**. When the caller supplies a known
+ * `changedLineCount` and the diff sits strictly below the configured floor
+ * (`delivery.review.lensDiffFloor`, default 40) with zero sensitive-path
+ * hits, the pass records the matched roster but skips materialization
+ * entirely (`skipped: true` with the lenses retained and a `floorSkip`
+ * verdict) — the maker-blind code-review pillar and every hard gate are
+ * untouched. An unknown line count, a disabled floor, or a sensitive-path
+ * hit all fail open to the full materialization.
+ *
  * @param {{
  *   baseRef: string,
  *   headRef: string,
  *   changedFiles?: string[]|null,
+ *   changedLineCount?: number|null,
+ *   lensDiffFloor?: number,
  *   storyId?: number|string|null,
  *   artifactPrefix?: string,
  *   progress: (tag: string, msg: string) => void,
@@ -191,11 +209,15 @@ function resolveLensChangeSet({
  *   gitSpawnFn?: import('../../change-set.js').GitSpawnFn,
  *   selectLocalLensesFn?: typeof selectLocalLenses,
  *   runAuditSuiteFn?: typeof runAuditSuite,
+ *   resolveConfigFn?: typeof resolveConfig,
+ *   evaluateLensDiffFloorFn?: typeof evaluateLensDiffFloor,
+ *   emitToolDegradationFn?: typeof emitRuntimeFriction,
  * }} args
  * @returns {Promise<{
  *   depth: 'light',
  *   lenses: string[],
  *   skipped: boolean,
+ *   floorSkip: object|null,
  *   materialized: object|null,
  *   artifactPaths: string[],
  * }>}
@@ -204,6 +226,8 @@ export async function runLocalLensReview({
   baseRef,
   headRef,
   changedFiles: injectedChangedFiles,
+  changedLineCount = null,
+  lensDiffFloor,
   storyId,
   artifactPrefix,
   progress,
@@ -211,11 +235,15 @@ export async function runLocalLensReview({
   gitSpawnFn = gitSpawn,
   selectLocalLensesFn = selectLocalLenses,
   runAuditSuiteFn = runAuditSuite,
+  resolveConfigFn = resolveConfig,
+  evaluateLensDiffFloorFn = evaluateLensDiffFloor,
+  emitToolDegradationFn = emitRuntimeFriction,
 }) {
   const empty = {
     depth: STORY_SCOPE_LENS_DEPTH,
     lenses: [],
     skipped: true,
+    floorSkip: null,
     materialized: null,
     artifactPaths: [],
   };
@@ -234,6 +262,34 @@ export async function runLocalLensReview({
       );
       return empty;
     }
+
+    // Lens diff-floor (Story #4699). Deliberately evaluated AFTER lens
+    // selection so a floor-skip still records WHICH lenses it skipped —
+    // the findings-yield ledger needs the roster either way.
+    const floorVerdict = evaluateLensDiffFloorFn({
+      changedFiles,
+      changedLineCount,
+      floor:
+        typeof lensDiffFloor === 'number'
+          ? lensDiffFloor
+          : resolveLensDiffFloor(safeResolveConfig(resolveConfigFn)),
+    });
+    if (floorVerdict.skip) {
+      progress(
+        progressTag,
+        `Lens diff-floor: ${floorVerdict.changedLineCount} changed line(s) < ` +
+          `floor ${floorVerdict.floor} with zero sensitive-path hits — ` +
+          `skipping materialization of ${lenses.join(', ')}.`,
+      );
+      return {
+        depth: STORY_SCOPE_LENS_DEPTH,
+        lenses,
+        skipped: true,
+        floorSkip: floorVerdict,
+        materialized: null,
+        artifactPaths: [],
+      };
+    }
     // Scope the artifact filenames to this Story so concurrent closes on a
     // shared audit output dir cannot clobber each other's prompts.
     const effectivePrefix =
@@ -256,16 +312,48 @@ export async function runLocalLensReview({
       depth: STORY_SCOPE_LENS_DEPTH,
       lenses,
       skipped: false,
+      floorSkip: floorVerdict,
       materialized,
       artifactPaths,
     };
   } catch (err) {
     // The lens pass is advisory: a git or materialization failure must not
-    // fail the close. Log and degrade to a skipped envelope.
+    // fail the close. Log, route the tool-execution degradation to friction
+    // telemetry (Story #4699 — degradations are operational signals, not
+    // findings), and degrade to a skipped envelope.
     progress(
       progressTag,
       `⚠️ local lens pass failed (continuing without it): ${err?.message ?? err}`,
     );
+    try {
+      await emitToolDegradationFn({
+        storyId,
+        category: RUNTIME_FRICTION_CATEGORIES.TOOL_DEGRADED,
+        tool: 'local-lens-review',
+        details: {
+          surface: 'lens-materialization',
+          reason: String(err?.message ?? err).slice(0, 500),
+        },
+      });
+    } catch {
+      // Observability must never fail the close (best-effort contract).
+    }
     return empty;
   }
 }
+
+/**
+ * Resolve config for the floor read without letting a resolver failure
+ * fail the (advisory) lens pass. Module-local: a degraded config simply
+ * yields the framework-default floor.
+ *
+ * @param {typeof resolveConfig} resolveConfigFn
+ * @returns {object|undefined}
+ */
+function safeResolveConfig(resolveConfigFn) {
+  try {
+    return resolveConfigFn();
+  } catch {
+    return undefined;
+  }
+}

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/orchestration/ticket-validator-conflicts.js

@@ -829,6 +829,12 @@ export function renderHardConflictError(finding) {
   if (finding.kind === 'missing-bdd-scaffold') {
     return `Missing BDD scaffold: Story "${finding.consumer.storySlug}" verifies against "${finding.path}" (created by Story "${finding.producer.storySlug}") via body.${finding.consumer.sourceField}, but "${finding.consumer.storySlug}" has no depends_on path to "${finding.producer.storySlug}" — the .feature file is scaffolded in the same wave (or later), so verification runs before the file exists. Add depends_on: ["${finding.producer.storySlug}"] to the consumer Story so the scaffold lands in an earlier wave.`;
   }
+  // Findings from other passes (sizing, spec-word-budget) carry their own
+  // message — render it rather than a shape-blind generic line, so the soft
+  // surface (`surfaceSoftConflictFindings`) stays legible for every kind.
+  if (typeof finding.message === 'string' && finding.message.length > 0) {
+    return finding.message;
+  }
   return `Conflict finding ${finding.kind} on path "${finding.path ?? '<unknown>'}".`;
 }
 

package/.agents/scripts/lib/orchestration/ticket-validator.js

@@ -3,11 +3,12 @@ import { detectCycle } from '../Graph.js';
 import { gitSpawn } from '../git-utils.js';
 
 import { Logger } from '../Logger.js';
-import {
-  parse as parseStoryBody,
-  StoryBodyParseError,
-} from '../story-body/story-body.js';
 import { validateStoryFileAssumptions } from './file-assumptions.js';
+import { computeSpecBudgetFindings } from './spec-budget.js';
+import {
+  assertStoryBodiesParse,
+  parseStoryBodyOrThrow,
+} from './story-body-gate.js';
 import {
   computeConflictFindings,
   renderHardConflictError,
@@ -46,63 +47,6 @@ function collectPathsFromText(text, paths) {
   }
 }
 
-/**
- * Parse a Story's serialized markdown body, translating a
- * `StoryBodyParseError` into a `ValidationError` that names the offending
- * **section** and **entry** (Story #4541).
- *
- * `StoryBodyParseError` already carries `field` (the section the parser was
- * reading) and `raw` (the entry text that failed); this lifts both into an
- * operator-legible message and a structured `violation` payload so an
- * authoring loop can point at the exact bullet instead of re-deriving it
- * from a downstream freshness miss.
- *
- * @param {object} story Story whose `body` is a non-empty markdown string.
- * @returns {object} The structured body.
- * @throws {ValidationError} `code: 'story-body-unparseable'`.
- */
-function parseStoryBodyOrThrow(story) {
-  try {
-    return parseStoryBody(story.body).body;
-  } catch (err) {
-    if (!(err instanceof StoryBodyParseError)) throw err;
-    const slug = story.slug ?? '<unknown>';
-    const section = err.field ?? 'body';
-    const entry = err.raw ?? null;
-    const entryLine = entry === null ? '' : `\n      entry: ${entry}`;
-    const violation = { slug, section, entry, reason: err.message };
-    const error = new ValidationError(
-      `Cross-Validation Failed: Story "${slug}" has an unparseable body — ` +
-        `the ## ${section} section could not be read: ${err.message}` +
-        `${entryLine}\n\nFix the offending entry; this is a malformed body, ` +
-        'not a stale path reference.',
-      { violations: [violation] },
-    );
-    error.code = 'story-body-unparseable';
-    error.violations = [violation];
-    throw error;
-  }
-}
-
-/**
- * Refuse the plan when any Story's serialized body cannot be parsed, before
- * either git-probe gate runs (Story #4541). Ordering matters: the freshness
- * gate consults `body.changes` for its net-new whitelist, so an unparseable
- * body used to reach the operator as a freshness miss naming declared paths.
- *
- * @param {{ tickets: object[] }} opts
- * @throws {ValidationError} `code: 'story-body-unparseable'` on the first
- *   offending Story.
- */
-function assertStoryBodiesParse({ tickets }) {
-  for (const story of (tickets ?? []).filter((t) => t.type === 'story')) {
-    if (typeof story.body !== 'string' || story.body.trim().length === 0) {
-      continue;
-    }
-    parseStoryBodyOrThrow(story);
-  }
-}
-
 /**
  * Resolve every acceptance line a Story declares, across both authoring
  * shapes (Story #4541).
@@ -721,7 +665,19 @@ export function validateAndNormalizeTickets(tickets, opts = {}) {
     stories,
     policy: opts.conflictPolicy,
   });
-  const findings = [...sizingFindings, ...conflictFindings];
+  // Advisory `## Spec` word-budget pass (Story #4723) — soft findings only,
+  // surfaced as warnings here and via the persist soft-finding channel;
+  // never promoted to `errors[]`, so an over-budget Spec cannot fail the
+  // persist. Runs after `assertStoryBodiesParse`, so string bodies parse.
+  const specBudgetFindings = computeSpecBudgetFindings({ stories });
+  for (const finding of specBudgetFindings) {
+    Logger.warn(`[ticket-validator] spec-word-budget: ${finding.message}`);
+  }
+  const findings = [
+    ...sizingFindings,
+    ...conflictFindings,
+    ...specBudgetFindings,
+  ];
   const CONFLICT_KINDS = new Set([
     'shared-editor',
     'implicit-cross-story-dep',

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,40 @@ 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, envelope);
+    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,
+      // Advisory only (Story #4722): signals, no route — the planner owns
+      // the trivial-vs-standard verdict and persist validates it by shape.
+      complexitySignals: envelope.complexitySignals
+        ? {
+            artifactCount: envelope.complexitySignals.artifactCount,
+            riskHeuristicHits: envelope.complexitySignals.riskHeuristicHits,
+            sensitivePathClasses:
+              envelope.complexitySignals.sensitivePathClasses,
+          }
+        : null,
+    };
+    stdout.write(`${JSON.stringify(digest)}\n`);
+  } else {
+    stdout.write(`${json}\n`);
+  }
   return envelope;
 }
 
@@ -140,6 +179,42 @@ 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. The envelope's advisory `complexitySignals` are threaded
+ * through so the skeleton's `changes[]` arrive pre-resolved to
+ * creates-vs-refactors against the repo snapshot (Story #4723).
+ *
+ * @param {string} outPath The envelope `--out` path; the template lands in
+ *   the same directory as {@link STORIES_TEMPLATE_FILENAME}.
+ * @param {object} [envelope] The emitted plan-context envelope.
+ */
+async function writeStoriesTemplateFile(outPath, envelope = {}) {
+  const resolved = path.resolve(
+    path.dirname(path.resolve(outPath)),
+    STORIES_TEMPLATE_FILENAME,
+  );
+  try {
+    await writeFile(
+      resolved,
+      renderStoriesTemplate({
+        complexitySignals: envelope?.complexitySignals ?? null,
+      }),
+      '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: {