mandrel 1.88.0 → 1.90.0

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

@@ -42,6 +42,7 @@ import {
   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';
@@ -60,20 +61,23 @@ function tracesFile(eid, sid, config) {
  * Best-effort decoration of a signal record with a `source` field
  * (`"framework"` or `"consumer"`) produced by `classifyPathSource`.
  *
- * Rules (Epic #2547 / Story #2553 / Tech Spec #2550):
+ * 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 — the writer's existing
- *     serialisation guard will reject or pass it through as before.
- *   - If the caller pre-set `signal.source`, preserve it verbatim. Some
- *     detectors classify upstream (e.g. wave-lifecycle signals always
- *     belong to the framework) and we MUST NOT overwrite their
- *     intentional tag.
- *   - Otherwise, invoke `classifyPathSource` against the record's
- *     `failingPath` / `path` and `command` fields, and inject the result
- *     as a new `source` key. The classifier itself never throws, but we
- *     belt-and-braces a try/catch so an unexpected fault degrades to a
- *     `Logger.warn` and a passthrough of the original signal — never a
- *     dropped write.
+ *     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 `classifyPathSource` against
+ *     the record's `failingPath` / `path` and `command` /
+ *     `emitter.command` fields and inject/overwrite `source` with the
+ *     result.
  *
  * @param {unknown} signal
  * @returns {unknown}
@@ -82,16 +86,17 @@ function tagSignalSource(signal) {
   if (signal === null || typeof signal !== 'object' || Array.isArray(signal)) {
     return signal;
   }
-  // Caller-supplied source wins, even when undefined-typed but present as
-  // an own property — only inject when the key is absent entirely so we
-  // never overwrite an explicit decision.
-  if (Object.hasOwn(signal, 'source')) {
-    return signal;
+  const record = /** @type {Record<string, unknown>} */ (signal);
+  if (record.source === 'framework' || record.source === 'consumer') {
+    return record;
   }
   try {
-    const record = /** @type {Record<string, unknown>} */ (signal);
     const failingPath = record.failingPath ?? record.path;
-    const command = record.command;
+    const emitter =
+      record.emitter && typeof record.emitter === 'object'
+        ? /** @type {Record<string, unknown>} */ (record.emitter)
+        : null;
+    const command = record.command ?? emitter?.command;
     const source = classifyPathSource(failingPath, command);
     return { ...record, source };
   } catch (err) {
@@ -104,6 +109,27 @@ 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), a `Logger.warn` names the violating field, and the per-Epic
+ * reject tally is incremented under the Epic temp tree. Never throws —
+ * the writer's best-effort contract is preserved.
+ *
+ * @param {unknown} record
+ * @param {{ epicId?: number|null, config?: object, label: string }} ctx
+ * @returns {Promise<boolean>} true when the record is valid (safe to append).
+ */
+async function validateOrDrop(record, { epicId, config, label }) {
+  const { valid, violatingField, message } = validateSignal(record);
+  if (valid) return true;
+  Logger.warn(
+    `signals-writer: dropping schema-invalid ${label} record — violating field '${violatingField}' (${message}).`,
+  );
+  await recordSignalReject({ epicId, config, field: violatingField });
+  return false;
+}
+
 /**
  * Best-effort append of a single record as one newline-terminated JSON
  * line. Caller-supplied record must be JSON-serialisable; circular refs
@@ -163,14 +189,24 @@ export async function appendSignal(args) {
     );
     return false;
   }
-  return appendOne(target, tagSignalSource(signal));
+  const tagged = tagSignalSource(signal);
+  const ok = await validateOrDrop(tagged, {
+    epicId: Number.isInteger(epicId) ? epicId : null,
+    config,
+    label: 'signal',
+  });
+  if (!ok) return false;
+  return appendOne(target, tagged);
 }
 
 /**
  * Append one signal record to the per-Epic stream at
- * `temp/epic-<eid>/signals.ndjson` — used for wave-lifecycle signals
- * (`wave-start`, `wave-tick`, `wave-complete`, `epic-complete`) that are
- * not scoped to an individual Story.
+ * `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>}
@@ -188,7 +224,14 @@ export async function appendEpicSignal(args) {
     );
     return false;
   }
-  return appendOne(target, tagSignalSource(signal));
+  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);
 }
 
 /**
@@ -211,41 +254,32 @@ export async function appendTrace(args) {
     );
     return false;
   }
+  const ok = await validateOrDrop(trace, {
+    epicId: Number.isInteger(epicId) ? epicId : null,
+    config,
+    label: 'trace',
+  });
+  if (!ok) return false;
   return appendOne(target, trace);
 }
 
 /**
- * Stream `signals.ndjson` 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 — the analyzer treats absence as "no signals yet" and
- * keeps walking.
+ * 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.
  *
- * @param {number} epicId
- * @param {number} storyId
+ * Shared spine for `forEachLine` (per-Story stream) and `forEachEpicLine`
+ * (per-Epic stream) so the two readers cannot drift in their
+ * malformed-line / missing-file / cb-throw handling.
+ *
+ * @param {string} target
  * @param {(parsed: unknown, lineNumber: number) => unknown | Promise<unknown>} cb
- * @param {object} [config]
+ * @param {string} label   Reader name used in warn messages.
  * @returns {Promise<{ linesRead: number, linesParsed: number, missing: boolean }>}
  */
-export async function forEachLine(epicId, storyId, cb, config) {
-  if (typeof cb !== 'function') {
-    Logger.warn('signals-writer: forEachLine called without a callback');
-    return { linesRead: 0, linesParsed: 0, missing: false };
-  }
-
-  let target;
-  try {
-    target = signalsFile(epicId, storyId, config);
-  } catch (err) {
-    Logger.warn(
-      `signals-writer: invalid epicId/storyId for forEachLine: ${
-        err instanceof Error ? err.message : String(err)
-      }`,
-    );
-    return { linesRead: 0, linesParsed: 0, missing: false };
-  }
-
+async function forEachLineIn(target, cb, label) {
   try {
     await fs.access(target);
   } catch {
@@ -278,7 +312,7 @@ export async function forEachLine(epicId, storyId, cb, config) {
         await cb(parsed, linesRead);
       } catch (err) {
         Logger.warn(
-          `signals-writer: forEachLine cb threw at ${target}:${linesRead}: ${
+          `signals-writer: ${label} cb threw at ${target}:${linesRead}: ${
             err instanceof Error ? err.message : String(err)
           }`,
         );
@@ -286,7 +320,7 @@ export async function forEachLine(epicId, storyId, cb, config) {
     }
   } catch (err) {
     Logger.warn(
-      `signals-writer: forEachLine read failed for ${target}: ${
+      `signals-writer: ${label} read failed for ${target}: ${
         err instanceof Error ? err.message : String(err)
       }`,
     );
@@ -294,3 +328,72 @@ export async function forEachLine(epicId, storyId, cb, config) {
 
   return { linesRead, linesParsed, missing: false };
 }
+
+/**
+ * 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
+ * @param {object} [config]
+ * @returns {Promise<{ linesRead: number, linesParsed: number, missing: boolean }>}
+ */
+export async function forEachLine(epicId, storyId, cb, config) {
+  if (typeof cb !== 'function') {
+    Logger.warn('signals-writer: forEachLine called without a callback');
+    return { linesRead: 0, linesParsed: 0, missing: false };
+  }
+
+  let target;
+  try {
+    target = signalsFile(epicId, storyId, config);
+  } catch (err) {
+    Logger.warn(
+      `signals-writer: invalid epicId/storyId for forEachLine: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+    return { linesRead: 0, linesParsed: 0, missing: false };
+  }
+
+  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/tool-trace-hook.js

@@ -220,10 +220,10 @@ function hashBashInput(toolInput) {
  * (`tool_input.file_path`, `tool_input.path`, `tool_input.pattern`)
  * before recording. The raw value never appears on disk.
  *
- * @param {{ tool: string, toolInput?: object, durationMs?: number|null }} args
+ * @param {{ tool: string, toolInput?: object, durationMs?: number|null, exitCode?: number|null }} args
  * @returns {object}
  */
-function buildDetails({ tool, toolInput, durationMs }) {
+function buildDetails({ tool, toolInput, durationMs, exitCode }) {
   const details = {};
   if (typeof durationMs === 'number') {
     details.durationMs = durationMs;
@@ -231,6 +231,14 @@ function buildDetails({ tool, toolInput, durationMs }) {
     details.durationMs = null;
   }
 
+  // Bash exit code — the retry detector's failure predicate
+  // (`details.exitCode !== 0`) can only fire once this is recorded. Only
+  // Bash PostToolUse events carry a meaningful exit code; other tools omit
+  // the field entirely (Epic #4406 / Story #4413).
+  if (tool === 'Bash' && typeof exitCode === 'number') {
+    details.exitCode = exitCode;
+  }
+
   if (toolInput && typeof toolInput === 'object') {
     // Bash: hash `command` so a token-laden string never lands on disk.
     // Story #1768 also records `normalizedHash` (paraphrase-collapsed)
@@ -273,6 +281,35 @@ function buildDetails({ tool, toolInput, durationMs }) {
   return details;
 }
 
+/**
+ * Extract the Bash exit code from a PostToolUse event. The harness reports
+ * the tool result under `tool_response` (occasionally at the event root);
+ * the exit-code field name is not contractually fixed across harness
+ * versions, so we probe the known aliases and return the first numeric
+ * hit. Returns `null` when no numeric exit code is present — the caller
+ * omits `details.exitCode` entirely rather than recording a guess.
+ *
+ * Exported for testing.
+ *
+ * @param {object} event
+ * @returns {number|null}
+ */
+export function extractExitCode(event) {
+  const candidates = [
+    event?.tool_response?.exitCode,
+    event?.tool_response?.exit_code,
+    event?.tool_response?.returnCode,
+    event?.tool_response?.code,
+    event?.tool_response?.status,
+    event?.exit_code,
+    event?.exitCode,
+  ];
+  for (const c of candidates) {
+    if (typeof c === 'number' && Number.isFinite(c)) return c;
+  }
+  return null;
+}
+
 /**
  * PreToolUse handler. Stashes `{ startedAt, tool }` into the in-flight
  * Map keyed by the harness `tool_use_id`. Does not append to
@@ -306,6 +343,7 @@ export async function handlePost(event, active) {
   const id = event?.tool_use_id ?? event?.id ?? null;
   const tool = event?.tool_name ?? event?.tool ?? 'unknown';
   const toolInput = event?.tool_input;
+  const exitCode = extractExitCode(event);
 
   let durationMs = null;
   if (id && inflight.has(id)) {
@@ -317,13 +355,13 @@ export async function handlePost(event, active) {
   const trace = {
     ts: new Date().toISOString(),
     kind: 'trace',
-    source: { tool: clamp(tool) },
+    emitter: { tool: clamp(tool) },
     epicId: active.epicId,
     storyId: active.storyId,
     taskId: null,
     phase:
       typeof process.env.CC_PHASE === 'string' ? process.env.CC_PHASE : null,
-    details: buildDetails({ tool, toolInput, durationMs }),
+    details: buildDetails({ tool, toolInput, durationMs, exitCode }),
   };
 
   await appendTrace({

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

@@ -174,7 +174,7 @@ export function buildAcceptanceEvalSignal({
     epicId: epicId ?? null,
     storyId,
     phase,
-    source: { tool: 'acceptance-eval.js' },
+    emitter: { tool: 'acceptance-eval.js' },
     details: {
       decision: outcome.decision,
       round: outcome.round,

package/.agents/scripts/lib/orchestration/code-review.js

@@ -22,8 +22,11 @@
  * Behaviour:
  *   - Loads the configured review adapter via the factory; defaults to
  *     `native` when `delivery.codeReview.provider` is unset.
- *   - Always posts the structured `code-review` comment on the Epic
- *     issue (the adapter never posts; the orchestrator owns persistence).
+ *   - Always posts the unified `verification-results` structured comment on
+ *     the Epic issue (the adapter never posts; the orchestrator owns
+ *     persistence). Story #4411 (Epic #4405) unified the former
+ *     `code-review` and `audit-results` findings contracts into this one
+ *     `verification-results` marker.
  *   - Treats severity.critical > 0 as a halting blocker — the merged
  *     `/deliver` runner consults `halted` and refuses to advance
  *     to Phase E (retro) when set.
@@ -32,6 +35,8 @@
  * helper's "operator must remediate before /deliver" gate.
  */
 
+import { hasSurvivingCritical } from '../audit-suite/findings.js';
+import { resolveLensTier } from '../audit-suite/selector.js';
 import { resolveConfig } from '../config-resolver.js';
 import { selectAuditStrategy } from '../dynamic-workflow/capability.js';
 import { gitSpawn } from '../git-utils.js';
@@ -228,6 +233,71 @@ export function resolveAuditLenses(envelope = {}) {
   return LENS_ORDER.filter((lens) => matched.has(lens));
 }
 
+/**
+ * Compose the Epic-close (gate3) lens roster from the change-set selection
+ * plus every risk-routed lens.
+ *
+ * STOPGAP (post-#4405 review finding): Story #4412 excluded every
+ * `local`-tier change-set lens here on the premise that the Story-scope
+ * local-lens pass (Story #4409) verifies those concerns shift-left. That
+ * premise does not hold yet — `runLocalLensReview`
+ * (story-close/phases/code-review.js) materializes lens bodies with no
+ * `artifactPrefix` (so no content persists) and no consumer acts on its
+ * result, which left change-set lenses (security, privacy, performance,
+ * quality, …) executed by NO reviewer at ANY tier. Local-tier lenses are
+ * therefore KEPT at Epic close until the story-scope pass has a real
+ * consumer; re-enable the exclusion then (tracked as a follow-up issue).
+ * The write-time maker checklists (#4410) are advisory self-checks, not
+ * verification. The `resolveLensTierFn` seam is retained so the
+ * re-exclusion is a one-line revert.
+ *
+ * The two inputs mirror the `epic-audit-prepare.js` envelope:
+ *   - `changeSetAudits` — the raw change-set gate3 selection, kept in full
+ *     (see the stopgap note above).
+ *   - `riskRoutedAudits` — the verdict-routed high-risk lenses plus the
+ *     route-glob navigability lens. Kept in **full**, regardless of tier: a
+ *     high-risk axis (or a route-adding change set) that demands a local-tier
+ *     lens still runs it at Epic close, because that demand is the whole point
+ *     of risk routing.
+ *
+ * De-duplicated and order-preserving (kept change-set lenses first, then the
+ * risk-routed extras). Pure over the injected `resolveLensTierFn` seam; the
+ * default resolver reads `audit-rules.json` from disk.
+ *
+ * @param {{
+ *   changeSetAudits?: string[],
+ *   riskRoutedAudits?: string[],
+ *   resolveLensTierFn?: typeof resolveLensTier,
+ * }} [params]
+ * @returns {string[]} The Epic-close roster (all change-set tiers +
+ *   risk-routed; local-tier exclusion suspended per the stopgap above).
+ */
+export function selectEpicCloseLenses({
+  changeSetAudits = [],
+  riskRoutedAudits = [],
+  resolveLensTierFn = resolveLensTier,
+} = {}) {
+  const kept = [];
+  const seen = new Set();
+  const add = (lens) => {
+    if (typeof lens !== 'string' || lens.length === 0 || seen.has(lens)) return;
+    seen.add(lens);
+    kept.push(lens);
+  };
+  for (const lens of Array.isArray(changeSetAudits) ? changeSetAudits : []) {
+    if (typeof lens !== 'string' || lens.length === 0) continue;
+    // Stopgap: keep local-tier lenses (see docstring). The tier seam is
+    // deliberately untouched so restoring `=== 'local' → continue` is a
+    // one-line revert once the story-scope tier has a real consumer.
+    void resolveLensTierFn;
+    add(lens);
+  }
+  for (const lens of Array.isArray(riskRoutedAudits) ? riskRoutedAudits : []) {
+    add(lens);
+  }
+  return kept;
+}
+
 /**
  * Build the post-delivery audit-lens execution plan for a judged risk
  * envelope. Each routed lens (see {@link resolveAuditLenses}) is paired with a
@@ -551,7 +621,7 @@ async function postReviewComment({
     const postResult = await upsertCommentFn(
       provider,
       commentTargetId,
-      'code-review',
+      'verification-results',
       report,
     );
     const postedCommentId =
@@ -621,7 +691,7 @@ async function executeReviewPipeline({ opts, config, envelope }) {
   );
 
   const severity = countBySeverity(findings);
-  const halted = severity.critical > 0;
+  const halted = hasSurvivingCritical(severity);
   const report = renderFindingsFn({
     scope,
     ticketId,