mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/observability/runtime-friction.js

@@ -0,0 +1,243 @@
+/**
+ * runtime-friction.js — derive friction signals from observables the
+ * runtime already has (Story #4578).
+ *
+ * ## Why this exists
+ *
+ * Friction telemetry was **opt-in**: a `friction` record existed only when
+ * an agent volunteered a `diagnose-friction.js --story <id> --cmd <...>`
+ * call. `plan-run-epilogue.js`'s `follow-up-rollup` then read an empty
+ * `signals.ndjson` and truthfully reported "No friction signals — nothing
+ * to follow up". A 7-Story run containing a mid-run git outage, a parked
+ * worker needing an operator resume, and a four-round acceptance critic
+ * produced a **zero-signal retro** — because the stream is least likely to
+ * fill exactly when a run is going badly and the agent is busy.
+ *
+ * This module closes that gap from the other side: the runtime emits
+ * friction from what it *already knows*, at the point it already knows it.
+ * No agent cooperation required.
+ *
+ * ## Not a second channel
+ *
+ * These records go through the **existing** `appendSignal` path, carry the
+ * **existing** `kind: 'friction'` shape, and land in the **same**
+ * `signals.ndjson` stream `diagnose-friction.js` writes and the roll-up
+ * reads. The only thing that is new is *who* decides to write.
+ *
+ * Deliberately distinct from {@link ../gates/friction.js}'s
+ * `emitFrictionSignal`, which early-returns unless **both** `storyId` and
+ * `epicId` are truthy. Every v2 Story is standalone (`epicId: null` — see
+ * `temp-paths.storyTempDir`'s standalone branch), and the roll-up reads the
+ * standalone stream via `forEachLine(null, sid, ...)`. Routing runtime
+ * friction through the gate helper would drop **every** record on the floor,
+ * silently, which is the bug this Story exists to fix.
+ *
+ * ## Robustness contract
+ *
+ * Observability MUST NOT halt the runner (`signals-writer.js`; the
+ * `docs/patterns.md` friction pattern). Every export here is best-effort:
+ * it swallows its own failures after a `Logger.warn` and resolves `false`.
+ * A missing signal is strictly preferable to a broken close.
+ *
+ * @module lib/observability/runtime-friction
+ */
+
+import crypto from 'node:crypto';
+
+import { Logger } from '../Logger.js';
+import { appendSignal } from './signals-writer.js';
+
+/**
+ * The friction categories this module emits.
+ *
+ * Values are plain strings by design: `signal-event.schema.json` types
+ * `category` as a free-form `{ type: 'string', minLength: 1 }`, so no schema
+ * change is required to add one. They are frozen here so the emitters and
+ * their tests name the same literal instead of spreading it.
+ *
+ * Category choice is load-bearing for the retro: `retro-proposals.js`
+ * aggregates **by exact category string**, so these are deliberately coarse
+ * — one bucket per failure mode — rather than per-incident. Two Stories that
+ * hit the same wall in one run aggregate to `occurrences: 2` and route as a
+ * real proposal instead of being discarded as two unrelated singletons.
+ */
+export const RUNTIME_FRICTION_CATEGORIES = Object.freeze({
+  /** A Story was parked at `agent::blocked` — the HITL pause (§ 1.J). */
+  STORY_BLOCKED: 'story-blocked',
+  /** A close run ended on a `failed` terminal (non-zero exit). */
+  CLOSE_FAILED: 'close-failed',
+  /** A bounded merge wait expired with the PR still in flight. */
+  MERGE_WAIT_EXHAUSTED: 'merge-wait-exhausted',
+});
+
+/** Cap on free-form reason text copied into a signal's `details`. */
+const REASON_PREVIEW_LIMIT = 500;
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function preview(value) {
+  return String(value ?? '').slice(0, REASON_PREVIEW_LIMIT);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {number|null}
+ */
+function positiveIntOrNull(value) {
+  const n = Number(value);
+  return Number.isInteger(n) && n > 0 ? n : null;
+}
+
+/**
+ * Append one runtime-derived `friction` record to the Story's signals
+ * stream. Best-effort: never throws, never rejects.
+ *
+ * `epicId` defaults to `null` (the standalone-Story stream) because that is
+ * where v2 Stories live and where the roll-up reads.
+ *
+ * @param {object} args
+ * @param {number} args.storyId
+ * @param {number|null} [args.epicId]
+ * @param {string} args.category  One of {@link RUNTIME_FRICTION_CATEGORIES}.
+ * @param {string} args.tool      Emitting surface, for `emitter.tool`.
+ * @param {object} [args.details] Kind-specific payload (always an object).
+ * @param {object} [args.config]  Resolved config (for `tempRoot`).
+ * @returns {Promise<boolean>} true when a record was appended.
+ */
+export async function emitRuntimeFriction({
+  storyId,
+  epicId = null,
+  category,
+  tool,
+  details = {},
+  config,
+} = {}) {
+  const sid = positiveIntOrNull(storyId);
+  if (sid === null) {
+    // No Story context → no stream to write to. Not an error: some close
+    // paths (a usage error before the id is parsed) genuinely have none.
+    return false;
+  }
+  if (typeof category !== 'string' || category.trim() === '') {
+    Logger.warn('[runtime-friction] refusing to emit a category-less signal');
+    return false;
+  }
+
+  const signal = {
+    kind: 'friction',
+    eventId: crypto.randomUUID(),
+    ts: new Date().toISOString(),
+    epicId: positiveIntOrNull(epicId),
+    storyId: sid,
+    // 2-tier hierarchy (Epic #3163): no Task tier. Retained for schema
+    // compatibility and always null — mirrors diagnose-friction.js.
+    taskId: null,
+    category: category.trim(),
+    emitter: { tool: tool || 'runtime-friction' },
+    details: details && typeof details === 'object' ? details : {},
+  };
+
+  try {
+    return await appendSignal({
+      epicId: signal.epicId,
+      storyId: sid,
+      signal,
+      config,
+    });
+  } catch (err) {
+    // `appendSignal` already swallows its own I/O failures; this catch is
+    // defense in depth so a surprise (a poisoned config, a throwing
+    // validator) still cannot take down the path being observed.
+    Logger.warn(
+      `[runtime-friction] append failed for Story #${sid} (${category}): ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+    return false;
+  }
+}
+
+/**
+ * Decide whether a `story-deliver-terminal` envelope is worth a friction
+ * record, and describe it. **Pure** — no I/O — so the (interesting) policy
+ * is unit-testable without touching disk.
+ *
+ * The partition is deliberate; each observable is emitted from exactly ONE
+ * place, so one incident never double-counts into `occurrences: 2` and
+ * fabricates a filed proposal out of a single event:
+ *
+ *   - `blocked`  → **null here.** Every blocked terminal flips the Story to
+ *     `agent::blocked` (`confirm-merge.js`, both the `merge.unlanded` and
+ *     `merge.flip-failed` paths), and that transition is instrumented at the
+ *     canonical mutator (`ticketing/transition.js`). Emitting here as well
+ *     would count the same block twice.
+ *   - `landed`   → null. Nothing happened worth a retro.
+ *   - `failed`   → friction. A close that ended non-zero.
+ *   - `pending`  → friction **only when a `waitBudget` was exhausted**. That
+ *     is the parked worker from the report: a bounded wait expired with the
+ *     PR in flight and a human must resume it. A `pending` with **no**
+ *     `waitBudget` is the `--no-wait-merge` / operator-merge path, where the
+ *     human deliberately owns the land and nothing is broken — flagging it
+ *     would train operators to ignore the channel.
+ *
+ * Deliberately **not exported**: it is this module's internal policy, and
+ * `emitTerminalFriction` is the contract callers (and tests) exercise. An
+ * export solely for testability would be production-dead code — the
+ * `--production` dead-exports ratchet exists to catch exactly that.
+ *
+ * @param {object} envelope A `story-deliver-terminal` envelope.
+ * @returns {{ category: string, details: object }|null}
+ */
+function frictionForTerminal(envelope) {
+  if (!envelope || typeof envelope !== 'object') return null;
+  const { status, phase, waitBudget, failure, pr } = envelope;
+
+  if (status === 'failed') {
+    return {
+      category: RUNTIME_FRICTION_CATEGORIES.CLOSE_FAILED,
+      details: {
+        phase: phase ?? null,
+        reason: preview(failure?.reason),
+      },
+    };
+  }
+
+  if (status === 'pending' && waitBudget) {
+    return {
+      category: RUNTIME_FRICTION_CATEGORIES.MERGE_WAIT_EXHAUSTED,
+      details: {
+        phase: phase ?? null,
+        prNumber: pr?.number ?? null,
+        checksStatus: pr?.checksStatus ?? null,
+        waitedSeconds: waitBudget.waitedSeconds ?? null,
+        cumulativeSeconds: waitBudget.cumulativeSeconds ?? null,
+        maxBudgetSeconds: waitBudget.maxBudgetSeconds ?? null,
+      },
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Emit the friction record (if any) implied by a terminal envelope.
+ * Best-effort; never throws.
+ *
+ * @param {object} args
+ * @param {object} args.envelope
+ * @param {object} [args.config]
+ * @returns {Promise<boolean>} true when a record was appended.
+ */
+export async function emitTerminalFriction({ envelope, config } = {}) {
+  const verdict = frictionForTerminal(envelope);
+  if (!verdict) return false;
+  return emitRuntimeFriction({
+    storyId: envelope?.storyId,
+    category: verdict.category,
+    tool: 'single-story-close',
+    details: verdict.details,
+    config,
+  });
+}

package/.agents/scripts/lib/observability/signal-validator.js

@@ -18,7 +18,7 @@
  * other draft-07 validators (see `tests/schemas/signal-schemas.test.js`).
  *
  * A per-Epic reject tally is persisted under the Epic temp tree
- * (`temp/epic-<eid>/signal-rejects.json`) so a cross-process reader (the
+ * (`temp/run-<eid>/signal-rejects.json`) so a cross-process reader (the
  * loop-health check, a follow-on Story) can surface how many records were
  * dropped. The tally is read-modify-written best-effort; a lost increment
  * under a write race is acceptable for a diagnostic counter.
@@ -32,7 +32,7 @@ import { fileURLToPath } from 'node:url';
 import Ajv from 'ajv';
 import addFormats from 'ajv-formats';
 
-import { epicArtifactPath } from '../config/temp-paths.js';
+import { runArtifactPath } from '../config/temp-paths.js';
 import { Logger } from '../Logger.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -141,7 +141,7 @@ export async function recordSignalReject({ epicId, config, field }) {
   if (!Number.isInteger(epicId) || epicId <= 0) return null;
   let target;
   try {
-    target = epicArtifactPath(epicId, REJECT_TALLY_BASENAME, config);
+    target = runArtifactPath(epicId, REJECT_TALLY_BASENAME, config);
   } catch {
     return null;
   }
@@ -190,7 +190,7 @@ export async function readSignalRejectCount({ epicId, config }) {
   if (!Number.isInteger(epicId) || epicId <= 0) return 0;
   let target;
   try {
-    target = epicArtifactPath(epicId, REJECT_TALLY_BASENAME, config);
+    target = runArtifactPath(epicId, REJECT_TALLY_BASENAME, config);
   } catch {
     return 0;
   }

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

@@ -2,7 +2,7 @@
  * Append-only signals/trace writer (Epic #1030 Story #1041).
  *
  * Centralizes the per-(epic, story) NDJSON streams under
- * `temp/epic-<eid>/stories/story-<sid>/signals.ndjson` (and a sibling
+ * `temp/run-<id>/stories/story-<sid>/signals.ndjson` (and a sibling
  * `traces.ndjson` for trace-shaped records). Detector modules and the
  * runtime trace hook all funnel through this writer so the on-disk
  * shape stays under one schema and one set of robustness guarantees.
@@ -18,7 +18,7 @@
  *     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/epic-<eid>/stories/story-<sid>/` via `fs.mkdir(..., { recursive: true })`.
+ *     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.
  *
@@ -36,17 +36,12 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { createInterface } from 'node:readline';
 
-import {
-  epicArtifactPath,
-  signalsFile,
-  storyTempDir,
-} from '../config/temp-paths.js';
+import { signalsFile, storyTempDir } from '../config/temp-paths.js';
 import { Logger } from '../Logger.js';
 import { recordSignalReject, validateSignal } from './signal-validator.js';
 import { classifyPathSource } from './source-classifier.js';
 
 const TRACES_BASENAME = 'traces.ndjson';
-const EPIC_SIGNALS_BASENAME = 'signals.ndjson';
 
 /**
  * Async traces-file path (kept private — consumers thread through
@@ -167,7 +162,7 @@ async function appendOne(targetPath, record) {
 }
 
 /**
- * Append one signal record to `temp/epic-<eid>/stories/story-<sid>/signals.ndjson`.
+ * 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
@@ -200,42 +195,7 @@ export async function appendSignal(args) {
 }
 
 /**
- * Append one signal record to the per-Epic stream at
- * `temp/epic-<eid>/signals.ndjson` — used for Epic-scoped signals not tied
- * to an individual Story: the wave-window forensics kinds (`wave-start`,
- * `wave-complete`), notification-derived anchors (`state-transition`,
- * `notification.emitted`), and Epic-level `friction` (e.g.
- * `lifecycle-emit.js`). The retired write-only kinds `wave-tick` /
- * `epic-complete` are gone (Story #3909) and are NOT valid here.
- *
- * @param {{ epicId: number, signal: unknown, config?: object }} args
- * @returns {Promise<boolean>}
- */
-export async function appendEpicSignal(args) {
-  const { epicId, signal, config } = args ?? {};
-  let target;
-  try {
-    target = epicArtifactPath(epicId, EPIC_SIGNALS_BASENAME, config);
-  } catch (err) {
-    Logger.warn(
-      `signals-writer: invalid epicId for appendEpicSignal: ${
-        err instanceof Error ? err.message : String(err)
-      }`,
-    );
-    return false;
-  }
-  const tagged = tagSignalSource(signal);
-  const ok = await validateOrDrop(tagged, {
-    epicId: Number.isInteger(epicId) ? epicId : null,
-    config,
-    label: 'epic signal',
-  });
-  if (!ok) return false;
-  return appendOne(target, tagged);
-}
-
-/**
- * Append one trace record to `temp/epic-<eid>/stories/story-<sid>/traces.ndjson`.
+ * Append one trace record to `temp/run-<id>/stories/story-<sid>/traces.ndjson`.
  * Same robustness contract as `appendSignal` — never throws.
  *
  * @param {{ epicId: number, storyId: number, trace: unknown, config?: object }} args
@@ -270,7 +230,7 @@ export async function appendTrace(args) {
  * lines are skipped with a `Logger.warn`. A missing file resolves with
  * `missing: true` rather than throwing.
  *
- * Shared spine for `forEachLine` (per-Story stream) and `forEachEpicLine`
+ * Shared spine for `forEachLine`
  * (per-Epic stream) so the two readers cannot drift in their
  * malformed-line / missing-file / cb-throw handling.
  *
@@ -361,39 +321,3 @@ export async function forEachLine(epicId, storyId, cb, config) {
 
   return forEachLineIn(target, cb, 'forEachLine');
 }
-
-/**
- * Stream the per-Epic `signals.ndjson` line by line, invoking
- * `cb(parsed, lineNumber)` for each successfully parsed JSON line. This is
- * the read side of `appendEpicSignal` — the wave-lifecycle stream at
- * `temp/epic-<eid>/signals.ndjson` written by `appendEpicSignal` callers
- * (e.g. `lifecycle-emit`). A missing file resolves with `missing: true`
- * rather than throwing, mirroring the per-Story `forEachLine` contract so
- * the retro's unified counts scan can fold the Epic stream in alongside the
- * Story streams without a special-cased absence branch.
- *
- * @param {number} epicId
- * @param {(parsed: unknown, lineNumber: number) => unknown | Promise<unknown>} cb
- * @param {object} [config]
- * @returns {Promise<{ linesRead: number, linesParsed: number, missing: boolean }>}
- */
-export async function forEachEpicLine(epicId, cb, config) {
-  if (typeof cb !== 'function') {
-    Logger.warn('signals-writer: forEachEpicLine called without a callback');
-    return { linesRead: 0, linesParsed: 0, missing: false };
-  }
-
-  let target;
-  try {
-    target = epicArtifactPath(epicId, EPIC_SIGNALS_BASENAME, config);
-  } catch (err) {
-    Logger.warn(
-      `signals-writer: invalid epicId for forEachEpicLine: ${
-        err instanceof Error ? err.message : String(err)
-      }`,
-    );
-    return { linesRead: 0, linesParsed: 0, missing: false };
-  }
-
-  return forEachLineIn(target, cb, 'forEachEpicLine');
-}

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

@@ -4,8 +4,8 @@
  * `"consumer"` (the host project that consumes the framework via the
  * materialized `.agents/` directory).
  *
- * Used by `signals-writer.js#appendSignal` / `appendEpicSignal` so every
- * record in `temp/epic-<eid>/stories/story-<sid>/signals.ndjson` carries an
+ * 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).
@@ -57,7 +57,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/story-init.js` carries the prefix in the
+ * 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.
  *
@@ -83,13 +83,13 @@ function containsFrameworkPrefix(haystack) {
  * 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/story-init.js` — that's framework friction even
+ * `node .agents/scripts/single-story-init.js` — that's framework friction even
  * though the failing test path lives under the consumer.
  *
  * @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/story-init.js"`).
+ *                                (e.g. `"node .agents/scripts/single-story-init.js"`).
  * @returns {"framework"|"consumer"}
  */
 export function classifyPathSource(failingPath, command) {

package/.agents/scripts/lib/observability/tool-trace-hook.js

@@ -5,7 +5,7 @@
  * PostToolUse hook entries. Resolves the active Epic + Story from
  * environment variables (`CC_EPIC_ID` / `CC_STORY_ID`), pairs Pre/Post
  * tool-call events, and appends one `kind:"trace"` NDJSON line per tool
- * call to `temp/epic-<eid>/stories/story-<sid>/traces.ndjson` via the
+ * call to `temp/run-<id>/stories/story-<sid>/traces.ndjson` via the
  * `signals-writer.appendTrace` helper.
  *
  * Robustness contract (Tech Spec #1032 §observability + §security):
@@ -48,7 +48,6 @@
 
 import { createHash } from 'node:crypto';
 
-import { emitHeartbeatFromHook } from './hook-heartbeat.js';
 import { appendTrace } from './signals-writer.js';
 
 /**
@@ -388,19 +387,10 @@ export async function main(event) {
     const phase = event.hook_event_name;
     if (phase === 'PreToolUse') {
       // Pre-pairing only matters for the trace-line duration, which only
-      // the Story-scoped trace path records; slice-only context (single
-      // delivery) needs no Pre.
+      // the Story-scoped trace path records.
       if (active) handlePre(event);
     } else if (phase === 'PostToolUse') {
       if (active) await handlePost(event, active);
-      // Heartbeat OFF the token stream (Epic #4476 M5). A throttled
-      // story.heartbeat / slice.heartbeat, keyed off the same active-Story /
-      // active-slice env vars, so the §2e Idle Watchdog's forward-progress
-      // signal is a free byproduct of ANY tool call — no dedicated
-      // bookkeeping LLM turn. Best-effort and self-guarded; resolves its own
-      // target (fires for slice context even when `active` is null because
-      // there is no CC_STORY_ID under single delivery).
-      emitHeartbeatFromHook();
     }
     // Any other phase is silently ignored — the hook is registered for
     // Pre/Post only; receiving anything else is a configuration error

package/.agents/scripts/lib/onboard/init-tail.js

@@ -37,9 +37,7 @@ import { STUB_MARKER, scaffoldDocs } from './scaffold-docs.js';
  */
 export const PLAN_HANDOFF_TEXT =
   '\n✅  Mandrel is ready. Start your first project:\n\n' +
-  '    /plan --idea "<one-line description of what you want to build>"\n\n' +
-  'Or, if you already have a `type::epic` Issue open:\n\n' +
-  '    /plan <epicId>\n';
+  '    /plan --seed "<one-line description of what you want to build>"\n';
 
 // ---------------------------------------------------------------------------
 // Internal helpers

package/.agents/scripts/lib/orchestration/acceptance-clusters.js

@@ -15,7 +15,7 @@
  * hard-clamped to `[1, 8]`), and the executor spawns ONE maker-blind
  * fresh-context `Agent` critic per cluster. The cluster count is therefore
  * `ceil(totalACs / clusterCeiling)` — a deterministic fan-out width the
- * `deliver-epic-single.md` executor and its isolation test both key off.
+ * consuming executor and its isolation test both key off.
  *
  * Pure and total — inputs in, clusters out. No I/O, no throws on malformed
  * input (a non-array / empty AC set yields zero clusters — the executor then

package/.agents/scripts/lib/orchestration/acceptance-eval-decision.js

@@ -41,7 +41,7 @@
 
 import { readFileSync } from 'node:fs';
 
-import { epicArtifactPath, signalsFile } from '../config/temp-paths.js';
+import { runArtifactPath, signalsFile } from '../config/temp-paths.js';
 
 /** Epic-level signals stream basename (mirrors signals-writer). */
 const EPIC_SIGNALS_BASENAME = 'signals.ndjson';
@@ -231,7 +231,7 @@ export function deriveAcceptanceEvalRound({
   readFile = (p) => readFileSync(p, 'utf8'),
   signalsPathResolver = signalsFile,
   epicSignalsPathResolver = (eid, cfg) =>
-    epicArtifactPath(eid, EPIC_SIGNALS_BASENAME, cfg),
+    runArtifactPath(eid, EPIC_SIGNALS_BASENAME, cfg),
 }) {
   // Epic #4475 (M4-B): single-delivery critics score AC clusters, not
   // Stories. When `clusterId` is supplied the round is counted per cluster