mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/observability/signals-writer.js

@@ -1,35 +1,7 @@
 /**
- * Append-only signals writer (Epic #1030 Story #1041).
- *
- * Centralizes the per-(epic, story) NDJSON streams under
- * `temp/run-<id>/stories/story-<sid>/signals.ndjson`. Every live emitter
- * funnels through this writer so the on-disk shape stays under one schema
- * and one set of robustness guarantees. The sibling `traces.ndjson` stream
- * and its `appendTrace` entry point went in Story #5003 with the tool-trace
- * hook that was its only producer.
- *
- * Robustness contract (Tech Spec #1032 §observability):
- *   - **Best-effort.** Every entry point swallows fs / JSON failures
- *     after logging via `Logger.warn`. Observability MUST NOT take down
- *     the runner — a failed write is a missing signal, not a halted
- *     wave.
- *   - **No buffering.** Each `appendSignal` opens the target file, writes
- *     one newline-terminated JSON line, and closes.
- *     The Tech Spec explicitly forbids in-process buffering: emitters
- *     fire from inside per-Story sub-agents that may exit abruptly, and
- *     a buffered tail would silently disappear on `process.exit`.
- *   - **Lazy directory creation.** The first write to a fresh Story
- *     creates `temp/run-<id>/stories/story-<sid>/` via `fs.mkdir(..., { recursive: true })`.
- *     `epicId` / `storyId` are required positive integers — the
- *     `temp-paths.js` helpers assert this before we touch the disk.
- *
- * Reader contract:
- *   - `forEachLine(epicId, storyId, cb)` streams `signals.ndjson` line
- *     by line, parses each line as JSON, and invokes `cb(parsed, lineNumber)`.
- *     Malformed lines are skipped with a `Logger.warn`; a missing file
- *     returns `{ linesRead: 0, linesParsed: 0, missing: true }` rather
- *     than throwing. This matches how the analyzer wants to consume
- *     partial streams from in-flight Stories.
+ * Append-only writer and readers for per-Story `signals.ndjson`. Best-effort:
+ * failures are logged, never thrown. No buffering — emitters run in
+ * sub-agents that may exit abruptly.
  */
 
 import { createReadStream } from 'node:fs';
@@ -49,30 +21,8 @@ import { validateSignal } from './signal-validator.js';
 import { classifySignalSource } from './source-classifier.js';
 
 /**
- * Best-effort decoration of a signal record with a `source` field
- * (`"framework"` or `"consumer"`) produced by `classifyPathSource`.
- *
- * Post the Epic #4406 cutover `source` is reserved **exclusively** for
- * this framework/consumer classification — a record's originating tool
- * lives in `emitter`, never `source`. That freed the classifier to run
- * for every friction record (pre-cutover a provenance object under the
- * `source` key blocked it via `Object.hasOwn`).
- *
- * Rules:
- *   - If the record is not a plain object (string, number, null,
- *     undefined), return it unchanged.
- *   - If the caller pre-set `source` to exactly `"framework"` or
- *     `"consumer"`, preserve it verbatim — some detectors classify
- *     upstream and we MUST NOT overwrite their intentional tag.
- *   - Otherwise (absent, or any other value — defense in depth against a
- *     stray non-canonical `source`), invoke `classifySignalSource` against
- *     the whole record and inject/overwrite `source` with the result.
- *
- * Story #4824 moved the field extraction into the classifier. The writer
- * used to hand it only `failingPath` / `command`, which meant every
- * runtime-emitted record — which populates neither — took the `consumer`
- * default and the framework limb of the feedback loop was unreachable. The
- * classifier now sees the `category` and `details` it needs to resolve those.
+ * `source` means only framework/consumer (the tool lives in `emitter`); a
+ * caller-set canonical value is kept, anything else overwritten.
  *
  * @param {unknown} signal
  * @returns {unknown}
@@ -98,15 +48,6 @@ function tagSignalSource(signal) {
 }
 
 /**
- * Validate a record against the canonical `signal-event.schema.json`
- * before it is appended. On failure the record is **dropped** (never
- * appended) and a `Logger.warn` names the violating field. Never throws —
- * the writer's best-effort contract is preserved.
- *
- * Story #5003 removed the persisted per-Epic reject tally this used to
- * increment: v2 Stories are standalone (`epicId` is always null), so the
- * tally was never written and its only reader could never see one.
- *
  * @param {unknown} record
  * @param {string} label
  * @returns {boolean} true when the record is valid (safe to append).
@@ -121,10 +62,6 @@ function validateOrDrop(record, label) {
 }
 
 /**
- * Best-effort append of a single record as one newline-terminated JSON
- * line. Caller-supplied record must be JSON-serialisable; circular refs
- * or BigInt fields are reported via `Logger.warn` and dropped.
- *
  * @param {string} targetPath
  * @param {unknown} record
  * @returns {Promise<boolean>} true on success, false on any swallowed failure.
@@ -157,12 +94,6 @@ async function appendOne(targetPath, record) {
 }
 
 /**
- * Append one signal record to `temp/run-<id>/stories/story-<sid>/signals.ndjson`.
- *
- * The `signal` is written verbatim — callers (detectors) own its shape
- * (kind, severity, message, etc.). The writer adds nothing. Errors are
- * logged via `Logger.warn` and never thrown.
- *
  * @param {{ epicId: number, storyId: number, signal: unknown, config?: object }} args
  * @returns {Promise<boolean>}
  */
@@ -185,19 +116,11 @@ export async function appendSignal(args) {
 }
 
 /**
- * Stream any NDJSON `target` file line by line, invoking
- * `cb(parsed, lineNumber)` for each successfully parsed JSON line.
- * `lineNumber` is 1-based to match operator log expectations. Malformed
- * lines are skipped with a `Logger.warn`. A missing file resolves with
- * `missing: true` rather than throwing.
- *
- * Shared spine for `forEachLine`
- * (per-Epic stream) so the two readers cannot drift in their
- * malformed-line / missing-file / cb-throw handling.
+ * Shared reader spine; malformed lines and callback throws are skipped.
  *
  * @param {string} target
  * @param {(parsed: unknown, lineNumber: number) => unknown | Promise<unknown>} cb
- * @param {string} label   Reader name used in warn messages.
+ * @param {string} label
  * @returns {Promise<{ linesRead: number, linesParsed: number, missing: boolean }>}
  */
 async function forEachLineIn(target, cb, label) {
@@ -215,7 +138,6 @@ async function forEachLineIn(target, cb, label) {
   try {
     for await (const rawLine of rl) {
       linesRead += 1;
-      // Skip empty lines (trailing newline at EOF, accidental blanks).
       if (rawLine.length === 0) continue;
       let parsed;
       try {
@@ -251,11 +173,6 @@ async function forEachLineIn(target, cb, label) {
 }
 
 /**
- * Stream a per-Story `signals.ndjson` line by line, invoking
- * `cb(parsed, lineNumber)` for each successfully parsed JSON line. A
- * missing file resolves with `missing: true` rather than throwing — the
- * analyzer treats absence as "no signals yet" and keeps walking.
- *
  * @param {number} epicId
  * @param {number} storyId
  * @param {(parsed: unknown, lineNumber: number) => unknown | Promise<unknown>} cb
@@ -283,18 +200,11 @@ export async function forEachLine(epicId, storyId, cb, config) {
   return forEachLineIn(target, cb, 'forEachLine');
 }
 
-/** Matches an Epic run directory (`run-<eid>`) directly under `tempRoot`. */
 const RUN_DIR_RE = /^run-\d+$/;
 
-/** Matches a per-Story directory (`story-<sid>`) under a `stories/` parent. */
 const STORY_DIR_RE = /^story-(\d+)$/;
 
 /**
- * List directory entries, or `[]` when the directory is absent/unreadable.
- * Absence is the common case (a fresh checkout has no temp tree at all) and
- * must not throw — the discovery walk feeds a roll-up that may not fail the
- * land.
- *
  * @param {string} dir
  * @returns {Promise<import('node:fs').Dirent[]>}
  */
@@ -307,18 +217,8 @@ async function readDirEntries(dir) {
 }
 
 /**
- * Discover every per-Story `signals.ndjson` surviving under the configured
- * temp root (Story #4824).
- *
- * Both canonical layouts are walked — `<tempRoot>/standalone/stories/story-<sid>/`
- * (v2 standalone Stories, where every close writes) and
- * `<tempRoot>/run-<eid>/stories/story-<sid>/` (Epic-attached streams). The
- * walk is the **recurrence window** the follow-up composer reduces over: a
- * defect that fires exactly once per Story is invisible inside a single
- * Story's stream and only becomes a recurrence across the surviving ones.
- *
- * Sorted by absolute path so a given tree always yields the same order and
- * the composed proposals stay byte-identical.
+ * Every surviving stream (both layouts) — the recurrence window. Sorted so
+ * composed proposals are deterministic.
  *
  * @param {object} [config]
  * @returns {Promise<Array<{ storyId: number, file: string }>>}
@@ -361,18 +261,8 @@ async function listStorySignalStreams(config) {
 }
 
 /**
- * Stream **every** surviving per-Story `signals.ndjson` under the configured
- * temp root, invoking `cb(parsed, context)` per parsed row (Story #4824).
- *
- * `context` carries `{ storyId, file, lineNumber }` — `storyId` is the
- * **stream owner** (from the directory name), used only as the fallback when
- * a row carries no `storyId` of its own; `file` + `lineNumber` identify the
- * physical row, which is what lets a caller de-duplicate a legacy row that
- * predates `eventId`.
- *
- * Same robustness contract as `forEachLine`: a missing tree, an unreadable
- * directory, a malformed line, or a throwing callback each degrade to a
- * warning rather than a rejection.
+ * `context.storyId` is the stream owner (a fallback only); `file` +
+ * `lineNumber` de-duplicate legacy rows without `eventId`.
  *
  * @param {(parsed: unknown, context: { storyId: number, file: string, lineNumber: number }) => unknown | Promise<unknown>} cb
  * @param {object} [config]

package/.agents/scripts/lib/observability/source-classifier.js

@@ -1,48 +1,9 @@
 /**
- * source-classifier.js — pure classifier that tags a friction signal
- * record as either `"framework"` (the Mandrel framework itself) or
- * `"consumer"` (the host project that consumes the framework via the
- * materialized `.agents/` directory).
- *
- * Used by `signals-writer.js#appendSignal` so every
- * record in `temp/run-<id>/stories/story-<sid>/signals.ndjson` carries an
- * authoritative `source` field, allowing downstream retro consumers to
- * route framework signals back to mandrel and keep consumer signals in
- * the host project (Epic #2547 / Story #2553).
- *
- * Heuristic (Tech Spec #2550):
- *   - A signal is `"framework"` when its `failingPath` or `command`
- *     mentions any path under the framework's own surface area:
- *       - `.agents/`
- *       - `.agentrc.json`
- *       - `.claude/`
- *       - `node .agents/scripts/`
- *     …or (Story #4916) names one of the CLI entry points shipped at the
- *     top level of `.agents/scripts/` by **bare basename**, so recognition
- *     does not depend on how the caller spelled the reference.
- *   - Anything else (or empty input) defaults to `"consumer"`. The default
- *     is intentional — most friction comes from consumer code touching
- *     framework tooling, and we'd rather under-tag than mis-route a
- *     consumer signal into the framework retro stream.
- *
- * Story #4824 adds {@link classifySignalSource} alongside it — the
- * record-level entry point the writer now calls, which resolves a
- * runtime-emitted record (no `failingPath`, no `command`) instead of letting
- * the `consumer` default win unconditionally. `classifyPathSource` keeps its
- * two-argument signature and behaviour verbatim.
- *
- * The classifier is pure: no I/O, no logging, no throws on weird input.
- * Callers (the writer) are responsible for swallowing classifier-level
- * faults — but the only way this function can throw is via a programmer
- * error in this file, which would surface during unit testing.
+ * source-classifier.js — tag a friction signal `"framework"` or `"consumer"`.
+ * Defaults to consumer: under-tagging beats mis-routing. Pure.
  */
 
-/**
- * Framework prefixes, in declaration order. Order is significant only
- * for documentation purposes — any one match returns `"framework"`.
- *
- * @type {readonly string[]}
- */
+/** @type {readonly string[]} */
 const FRAMEWORK_PREFIXES = Object.freeze([
   '.agents/',
   '.agentrc.json',
@@ -51,28 +12,9 @@ const FRAMEWORK_PREFIXES = Object.freeze([
 ]);
 
 /**
- * Basenames of the CLI entry points shipped at the top level of
- * `.agents/scripts/` (Story #4916).
- *
- * The prefix scan above recognises a framework script only when the caller
- * spelled a path — `node .agents/scripts/acceptance-eval.js` classifies
- * `framework`, while the same script named bare (`acceptance-eval.js --story
- * 4901`) matched no prefix and fell through to `consumer`, so a real framework
- * defect was routed as consumer-actionable and discarded. Recognition must not
- * depend on how the caller spelled the reference.
- *
- * Kept as **static data**, not a directory read: `classifySignalSource` is
- * called once per signal and MUST stay pure — no filesystem I/O at classify
- * time. The sync test in
- * `tests/lib/observability/source-classifier.test.js` reads the real directory
- * and fails when a script is added, renamed, or removed without this list
- * being updated, so the set cannot go stale and silently restore the blind
- * spot.
- *
- * Scoped to the top level deliberately: those are the entry points a command
- * line names. Library modules under `.agents/scripts/lib/` carry generic
- * basenames (`index.js`, `config.js`) that a consumer command could plausibly
- * name, and widening to them would trade one mis-route for another.
+ * Top-level `.agents/scripts/` CLIs, so a bare basename classifies like its
+ * path. Static (classification is I/O-free); a sync test pins it to the
+ * directory. `lib/` basenames are too generic to include.
  *
  * @type {readonly string[]}
  */
@@ -85,33 +27,21 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'audit-to-stories.js',
   'boot-sweep.js',
   'bootstrap.js',
-  'check-action-pinning.js',
   'check-arch-cycles.js',
-  'check-audit-attribution.js',
-  'check-baseline-drift.js',
-  'check-baseline-scope.js',
   'check-baselines.js',
   'check-context-budget.js',
   'check-cyclomatic.js',
   'check-dead-exports.js',
   'check-doc-links.js',
-  'check-generated-validator.js',
   'check-gherkin-corpus.js',
-  'check-knip-entries.js',
-  'check-lifecycle-lint.js',
-  'check-pinned-override-notes.js',
-  'check-schema-references.js',
-  'check-test-portability.js',
   'check-test-temp-hygiene.js',
   'check-windows-git-perf.js',
-  'check-workflow-citations.js',
-  'check-workflow-cli-lint.js',
-  'check-workflow-timeouts.js',
   'ceremony-derive.js',
   'cleanup-repo-test-temp.js',
   'coverage-capture.js',
   'deliver-light.js',
   'deliver-recover.js',
+  'deliver-run.js',
   'diagnose-friction.js',
   'diagnose.js',
   'drain-pending-cleanup.js',
@@ -122,9 +52,7 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'generate-skills-index.js',
   'generate-workflows-doc.js',
   'git-cleanup.js',
-  'install-matrix-assert.js',
   'lint-issue-body.js',
-  'lint-label-vocabulary.js',
   'mandrel-update-preflight.js',
   'merge-baseline.js',
   'nav-registry-diff.js',
@@ -133,21 +61,14 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'plan-critics.js',
   'plan-persist.js',
   'plan-run-epilogue.js',
-  'post-structured-comment.js',
   'pr-watch-with-update.js',
-  'provision-git-hooks.js',
-  'prune-baseline-orphans.js',
   'prune-plan-run-labels.js',
   'quality-preview.js',
   'quality-watch.js',
   'resolve-doc-tiers.js',
   'resolve-stories.js',
   'resync-status-column.js',
-  'run-coverage.js',
-  'run-lint.js',
-  'run-test-profile.js',
   'run-tests.js',
-  'run-verify.js',
   'single-story-close.js',
   'single-story-confirm-merge.js',
   'single-story-init.js',
@@ -155,38 +76,22 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'sync-agentrc.js',
   'sync-claude-agents.js',
   'sync-claude-commands.js',
-  'test-isolate.js',
   'test-wrapper.js',
   'update-coverage-baseline.js',
   'update-crap-baseline.js',
-  'update-dead-exports-baseline.js',
   'update-duplication-baseline.js',
   'update-maintainability-baseline.js',
   'update-ticket-state.js',
   'validate-skills.js',
 ]);
 
-/**
- * Membership index over {@link FRAMEWORK_SCRIPT_BASENAMES}, built once at
- * module load so the per-signal scan is a hash lookup.
- *
- * @type {ReadonlySet<string>}
- */
+/** @type {ReadonlySet<string>} */
 const FRAMEWORK_SCRIPT_BASENAME_SET = new Set(FRAMEWORK_SCRIPT_BASENAMES);
 
-/**
- * Characters a shell-ish command line can wrap a token in. Stripped from both
- * ends before the membership test so `"acceptance-eval.js",` still resolves.
- *
- * @type {RegExp}
- */
+/** @type {RegExp} */
 const TOKEN_TRIM = /^[\s'"`(,;:]+|[\s'"`),;:]+$/g;
 
 /**
- * Normalise a value to a string for prefix scanning. Anything that is not
- * a string (undefined, null, numbers, objects) becomes the empty string,
- * which scans clean against every framework prefix.
- *
  * @param {unknown} value
  * @returns {string}
  */
@@ -196,11 +101,7 @@ function toScanString(value) {
 }
 
 /**
- * Return true when `haystack` contains any framework prefix as a
- * substring. We use `includes` (not `startsWith`) because a command line
- * like `node .agents/scripts/single-story-init.js` carries the prefix in the
- * middle, and a failing-path like `repo/.agents/foo.js` may carry an
- * absolute prefix.
+ * Substring match: prefixes appear mid-command and under absolute paths.
  *
  * @param {string} haystack
  * @returns {boolean}
@@ -214,14 +115,7 @@ function containsFrameworkPrefix(haystack) {
 }
 
 /**
- * Return true when `haystack` names a top-level framework script by **bare
- * basename** — no path segment at all (Story #4916).
- *
- * Whitespace-tokenised and matched whole: only a token that *equals* a known
- * basename counts. A token carrying any path segment is deliberately left to
- * {@link containsFrameworkPrefix} — `./tools/notify.js` is the consumer's own
- * script and must stay `consumer`, while `.agents/scripts/notify.js` already
- * matches a prefix. Likewise `my-notify.js` is not `notify.js`.
+ * Exact token match only: `./tools/notify.js` is the consumer's own script.
  *
  * @param {string} haystack
  * @returns {boolean}
@@ -236,13 +130,6 @@ function containsFrameworkScriptBasename(haystack) {
 }
 
 /**
- * True when `haystack` names the framework's own surface, by either
- * recognition route: a path prefix, or a bare framework-script basename.
- *
- * Purely additive over {@link containsFrameworkPrefix} — every string that
- * matched a prefix still matches here, so widening can only ever move a
- * classification from `consumer` to `framework`, never the reverse.
- *
  * @param {string} haystack
  * @returns {boolean}
  */
@@ -252,27 +139,10 @@ function namesFrameworkSurface(haystack) {
 }
 
 /**
- * Classify a friction signal as `"framework"` or `"consumer"`.
- *
- * Both arguments are best-effort: pass whatever the detector already has
- * (the failing file path, the failing command line, or both). When both
- * are empty / non-string, returns `"consumer"` — the safe default for
- * routing.
- *
- * Framework-wins: if either input matches a framework prefix, the result
- * is `"framework"` even when the other input looks consumer-shaped. This
- * matters for mixed cases like a consumer test invoking
- * `node .agents/scripts/single-story-init.js` — that's framework friction even
- * though the failing test path lives under the consumer.
- *
- * Either input matches on a framework path prefix **or** on a bare framework
- * script basename (Story #4916), so `single-story-close.js --story 4906` is
- * recognised exactly like its fully-pathed spelling.
+ * Framework wins if either input names it.
  *
- * @param {unknown} failingPath  The path of the file or directory the
- *                               signal blames (e.g. `"tests/foo.test.js"`).
- * @param {unknown} command       The command line the signal blames
- *                                (e.g. `"node .agents/scripts/single-story-init.js"`).
+ * @param {unknown} failingPath
+ * @param {unknown} command
  * @returns {"framework"|"consumer"}
  */
 export function classifyPathSource(failingPath, command) {
@@ -284,33 +154,17 @@ export function classifyPathSource(failingPath, command) {
 }
 
 /**
- * The one friction category that is definitionally a framework-surface
- * failure (Story #4824).
- *
- * Kept as a local literal rather than imported from
- * `RUNTIME_FRICTION_CATEGORIES.TOOL_DEGRADED` because `runtime-friction.js`
- * imports `signals-writer.js`, which imports this module — the import would
- * close a cycle for a single string. The unit test asserts the two spellings
- * agree, so the duplication cannot drift silently.
+ * Literal copy of `RUNTIME_FRICTION_CATEGORIES.TOOL_DEGRADED` (importing it
+ * would close a cycle); a test pins them together.
  *
  * @type {string}
  */
 const TOOL_DEGRADED_CATEGORY = 'tool-degraded';
 
-/**
- * Detail keys whose free text names the surface a runtime record blames.
- * Scanned (step 2 below) because a runtime emitter puts the framework path
- * it was executing here, not in `failingPath` / `command`.
- *
- * @type {readonly string[]}
- */
+/** @type {readonly string[]} */
 const DETAIL_SCAN_KEYS = Object.freeze(['reason', 'surface', 'phase']);
 
 /**
- * True when `value` is a non-empty string — the test for "the operator (or a
- * detector) actually supplied this field", as opposed to a runtime emitter
- * that leaves it absent.
- *
  * @param {unknown} value
  * @returns {boolean}
  */
@@ -319,8 +173,6 @@ function isSupplied(value) {
 }
 
 /**
- * Concatenate the scannable free text out of a record's `details` payload.
- *
  * @param {unknown} details
  * @returns {string}
  */
@@ -336,45 +188,12 @@ function detailsScanText(details) {
 }
 
 /**
- * Classify a whole signal record as `"framework"` or `"consumer"`
- * (Story #4824).
- *
- * `classifyPathSource` above requires **positive evidence** of a framework
- * prefix in an operator-supplied `failingPath` / `command`. Every
- * runtime-emitted friction record (`runtime-friction.js`) populates neither
- * field, so the `consumer` default always won and the framework limb of the
- * feedback loop was unreachable — 78% of real records mis-tagged.
- *
- * The naive repair — "runtime-emitted means framework" — is measurably
- * **wrong**. `close-failed` records from `single-story-close` carry
- * consumer-owned failures (a base-sync conflict in the consumer's own source
- * tree, a consumer `npm run test:coverage` exiting non-zero); tagging those
- * `framework` would flood the framework repo with consumer test failures,
- * which is worse than the current silence.
- *
- * So the discriminator is resolved in four steps, first match wins:
- *
- * 1. An operator-supplied `failingPath` / `path` / `command` /
- *    `emitter.command` → the existing {@link classifyPathSource} prefix scan,
- *    **unchanged**. A consumer command invoked through `diagnose-friction.js`
- *    stays `consumer`.
- * 2. Else the `details` payload's free text (`reason`, `surface`, `phase`)
- *    naming a framework prefix → `framework`. A runtime emitter blames its
- *    surface here, not in a `command` field.
- * 3. Else `category === "tool-degraded"` → `framework`.
- *    `RUNTIME_FRICTION_CATEGORIES.TOOL_DEGRADED` is defined as a tool that
- *    failed to *execute* — an operational degradation, not a code finding.
- *    The framework's own tooling could not run, which says nothing about
- *    consumer code.
- * 4. Else `consumer` — the existing safe default, unchanged.
- *
- * Steps 1, 2 and 4 leave every currently-exercised input byte-identical;
- * step 3 is the limb that was unreachable. There is deliberately no emitter
- * allowlist: nothing to maintain, nothing to rot.
- *
- * Pure, and never throws — the writer's `tagSignalSource` still guards it.
+ * First match wins: a supplied path/command → {@link classifyPathSource};
+ * `details` text naming a framework prefix; `tool-degraded`; else consumer.
+ * "Runtime-emitted means framework" is wrong — `close-failed` often blames
+ * consumer code.
  *
- * @param {unknown} record One signal record (the `appendSignal` payload).
+ * @param {unknown} record
  * @returns {"framework"|"consumer"}
  */
 export function classifySignalSource(record) {

package/.agents/scripts/lib/observability/terse-result.js

@@ -5,34 +5,14 @@ import { orchestrationLogDir } from '../config/temp-paths.js';
 import { Logger } from '../Logger.js';
 
 /**
- * Terse hot-path result emission (Story #4685).
- *
- * The orchestration CLIs an agent invokes on every delivery turn
- * (`single-story-init`, `single-story-close`, `single-story-confirm-merge`)
- * historically dumped their whole result object to stdout as pretty-printed
- * JSON:
- *
- *   --- STORY CLOSE RESULT ---
- *   { ... every field, 2-space indented ... }
- *   --- END RESULT ---
- *
- * That blob stays resident for the rest of the session and is re-read as
- * cache every subsequent turn, yet the agent acts on only a handful of its
- * fields (the machine contract is the separate terminal envelope). This helper
- * routes the full detail to a temp log the agent can read on demand and emits
- * a single structured summary line in its place.
- *
- * The escape hatch `MANDREL_RESULT_DETAIL=inline` restores the old inline
- * pretty dump for interactive debugging.
+ * Hot-path CLIs log their full result and print one summary line, keeping a
+ * pretty JSON blob out of the agent's resident context.
+ * `MANDREL_RESULT_DETAIL=inline` restores the inline dump.
  */
 
-/** Env var that restores the legacy inline pretty dump when set to `inline`. */
 const RESULT_DETAIL_ENV = 'MANDREL_RESULT_DETAIL';
 
 /**
- * Turn a human label (`STORY CLOSE RESULT`) into a filesystem-safe log
- * basename fragment (`story-close-result`).
- *
  * @param {string} label
  * @returns {string}
  */
@@ -46,10 +26,6 @@ function slugify(label) {
 }
 
 /**
- * The full detail block, byte-compatible with the legacy dump the hot-path
- * scripts used to write to stdout — same markers, same pretty JSON — so a log
- * a human opens reads exactly as the old inline dump did.
- *
  * @param {string} label
  * @param {unknown} result
  * @returns {string}
@@ -59,24 +35,17 @@ function detailBlock(label, result) {
 }
 
 /**
- * Route a verbose result object off the agent's turn-resident stdout: write the
- * full pretty detail to a temp log and emit a single-line structured summary in
- * its place.
- *
  * @param {object} args
- * @param {string} args.label Human label for the result (e.g. `STORY CLOSE RESULT`).
- * @param {unknown} args.result The full result object; pretty-printed to the log.
- * @param {Record<string, unknown>} [args.summary] The few fields the agent acts
- *   on; serialized compactly onto the single summary line.
- * @param {string|number} [args.scope] Disambiguating suffix for the log name
- *   (typically the Story id) so concurrent deliveries don't clobber one file.
- * @param {string} [args.logDir] Directory for the detail log. Defaults to the
- *   configured `<tempRoot>/orchestration` (Story #4794 — was a hardcoded
- *   `<cwd>/temp/orchestration`, which ignored `project.paths.tempRoot`).
- * @param {object} [args.config] Resolved config bag, for the default `logDir`.
- * @param {typeof nodeFs} [args.fs] Filesystem seam (tests).
- * @param {{ info: (m: string) => void }} [args.log] Logger seam (tests).
- * @param {NodeJS.ProcessEnv} [args.env] Environment seam (tests).
+ * @param {string} args.label
+ * @param {unknown} args.result
+ * @param {Record<string, unknown>} [args.summary]
+ * @param {string|number} [args.scope] Log-name suffix so concurrent
+ *   deliveries don't clobber one file.
+ * @param {string} [args.logDir]
+ * @param {object} [args.config]
+ * @param {typeof nodeFs} [args.fs]
+ * @param {{ info: (m: string) => void }} [args.log]
+ * @param {NodeJS.ProcessEnv} [args.env]
  * @returns {{ logPath: string|null, inline: boolean, error?: string }}
  */
 export function emitTerseResult({
@@ -92,7 +61,6 @@ export function emitTerseResult({
 } = {}) {
   const body = detailBlock(label, result);
 
-  // Escape hatch: restore the full inline pretty dump for interactive debugging.
   if (String(env[RESULT_DETAIL_ENV] ?? '').toLowerCase() === 'inline') {
     log.info?.(`\n${body}\n`);
     return { logPath: null, inline: true };
@@ -110,8 +78,7 @@ export function emitTerseResult({
     );
     return { logPath, inline: false };
   } catch (err) {
-    // Never lose detail: if the log write fails, fall back to the inline dump
-    // so the result is still recoverable from the transcript.
+    // Never lose detail: fall back to the inline dump.
     log.info?.(`\n${body}\n`);
     return { logPath: null, inline: true, error: err?.message ?? String(err) };
   }