mandrel 2.20.0 → 2.22.0

package/.agents/scripts/lib/feedback-loop/retro-proposals-graduator.js

@@ -49,32 +49,76 @@ import {
 export const isAutoFileEnabled = makeIsAutoFileEnabled('retroProposals');
 
 /**
- * Build the content-hash idempotency marker embedded in freshly filed
- * follow-up bodies. Derived from the proposal's CATEGORY (retro proposals
- * are path-less and the rendered title embeds a mutable recurrence count)
- * so the marker is stable across sibling insert/remove/reorder churn AND
- * across re-runs that change the count. An HTML comment so it survives
- * markdown rendering without leaking into the visible body; the idempotency
- * probe strips the comment delimiters before querying `gh search` (the raw
- * `<!-- … -->` form never matches the index — Story #4657).
+ * The content fingerprint identifying one retro proposal.
  *
- * @param {number} epicId
- * @param {{ category?: string, title?: string }} finding
- * @returns {string}
+ * Fingerprinted on the CATEGORY only — never the rendered title. The title
+ * embeds the mutable recurrence count ("… recurred <N> times in …"), so
+ * hashing it made a retro re-run after the count changed mint a fresh
+ * fingerprint and re-file a duplicate issue for the same category.
+ *
+ * @param {{ category?: string }} finding
+ * @returns {string} 16-char lowercase hex digest.
  */
-export function buildContentMarker(epicId, finding) {
-  // Fingerprint on the CATEGORY only — never the rendered title. The
-  // title embeds the mutable recurrence count ("… recurred <N> times in
-  // Epic #X"), so hashing it made a retro re-run after the count changed
-  // mint a fresh fingerprint and re-file a duplicate issue for the same
-  // category. The idempotency identity of a retro proposal is
-  // (epic, category); the epic id is already carried in the marker text.
-  const fp = contentFingerprint({
-    category: finding.category,
+function proposalFingerprint(finding) {
+  return contentFingerprint({
+    category: finding?.category,
     path: '',
     title: '',
   });
-  return `<!-- retro-proposal-followup: epic-${epicId}-${fp} -->`;
+}
+
+/**
+ * Build the content-hash idempotency marker embedded in filed follow-up
+ * bodies. An HTML comment so it survives markdown rendering without leaking
+ * into the visible body; the idempotency probe strips the comment delimiters
+ * before querying `gh search` (the raw `<!-- … -->` form never matches the
+ * index — Story #4657).
+ *
+ * **Anchor-free by construction (Story #4837).** The marker used to read
+ * `epic-<anchorId>-<fp>`. The fingerprint half was stable, but the anchor
+ * half was the run's FIRST STORY for a run-scoped roll-up
+ * (`run-epilogue.js` passes `anchorId: Number(stories[0])`), so it changed
+ * every run and the key could never match a prior filing. Measured: closed
+ * issues #4833 and #4834 are one `story-blocked` finding under two anchors —
+ * `epic-101-e59976671e0b848b` and `epic-777-e59976671e0b848b` — identical
+ * fingerprint, different anchor. Dedup did not malfunction; its key was too
+ * narrow. The identity of a recurring friction category is the category,
+ * full stop: the anchor is evidence about one occurrence and belongs in the
+ * body, never in the key.
+ *
+ * The `epicId` parameter is retained because `graduate()` owns the calling
+ * convention for every graduator's `buildContentMarker`; this one
+ * deliberately does not consult it.
+ *
+ * @param {number} _epicId — unused; see above.
+ * @param {{ category?: string }} finding
+ * @returns {string}
+ */
+export function buildContentMarker(_epicId, finding) {
+  return `<!-- retro-proposal-followup: ${proposalFingerprint(finding)} -->`;
+}
+
+/**
+ * Body substrings that identify a follow-up already filed for this finding,
+ * handed to the graduator's strongly-consistent read (Story #4837).
+ *
+ * Two shapes, because the marker format changed under a live backlog:
+ *
+ *   1. The current anchor-free marker.
+ *   2. `-<fp> -->` — the tail every pre-cutover anchored marker ends with
+ *      (`<!-- retro-proposal-followup: epic-4828-d185e7279a48d03d -->`),
+ *      whatever anchor it carried. Without it the cutover would re-file the
+ *      whole already-filed backlog exactly once, which is the failure this
+ *      Story exists to stop rather than to perform one last time.
+ *
+ * Module-local: it reaches `graduate()` on the spec bundle, so the walk is
+ * the seam and a second exported symbol would only be one nothing imports.
+ *
+ * @param {{ finding: { category?: string }, contentMarker: string }} args
+ * @returns {string[]}
+ */
+function buildMatchTokens({ finding, contentMarker }) {
+  return [contentMarker, `-${proposalFingerprint(finding)} -->`];
 }
 
 /**
@@ -108,6 +152,7 @@ function makeSpec(source) {
     noCommentReason: 'no-retro-comment',
     parseFindings: () => [],
     buildContentMarker,
+    buildMatchTokens,
     crossRepoCommentAttrs: { graduator: 'retro-proposals' },
     decorateRecord: (record, finding) => {
       record.category = finding.category;
@@ -232,6 +277,11 @@ export async function graduateRetroProposals({
   // circuit the repeat with no spawn.
   const filedMarkers = new Set();
 
+  // One live-label-set read per routed repo across both buckets (Story #4828):
+  // the two buckets file into at most two repos, and every finding in a bucket
+  // wants the same `meta::*` name.
+  const labelCache = new Map();
+
   let remaining = maxFilingsPerRun;
   for (const { source, items } of buckets) {
     if (items.length === 0) continue;
@@ -252,6 +302,7 @@ export async function graduateRetroProposals({
       maxFilingsPerRun: Math.max(0, remaining),
       findings,
       filedMarkers,
+      labelCache,
       logger,
       spec: makeSpec(source),
     });

package/.agents/scripts/lib/label-constants.js

@@ -135,11 +135,22 @@ export const PLANNING_LABELS = {
  */
 export const PLANNING_HEALTHCHECK_WAIVED = 'planning::healthcheck-waived';
 
-/** Palette for the taxonomy; consumed by label-taxonomy.js. */
+/**
+ * Palette for the taxonomy; consumed by label-taxonomy.js and by the
+ * feedback loop's just-in-time label mint (`graduator-core.ensureIssueLabels`).
+ *
+ * `META` and `FRICTION` are not in `LABEL_TAXONOMY`: the bootstrap runs once
+ * at repo setup, but `friction::<category>` names are minted from live
+ * telemetry and cannot be enumerated ahead of time. The graduator mints both
+ * axes on demand instead — Story #4828, where their absence made every
+ * `gh issue create` fail and the whole feedback loop file zero.
+ */
 export const LABEL_COLORS = {
   TYPE: '#7057FF',
   AGENT: '#0E8A16',
   STATUS_BLOCKED: '#D93F0B',
   ACCEPTANCE: '#FBCA04',
   PLANNING: '#FEF2C0',
+  META: '#1D76DB',
+  FRICTION: '#D4C5F9',
 };

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

@@ -348,9 +348,16 @@ export async function emitCloseRecoveredFriction({ storyId, config } = {}) {
  * foreign rows attributes each one correctly; the fallback covers records
  * written before the field existed.
  *
+ * `tool` (from `emitter.tool`) joined the shape in Story #4824. `category`
+ * remains the routing and de-duplication unit — it is what titles and
+ * de-duplicates a filed issue — but a roll-up that discards a candidate has
+ * to be able to *name* it, and a bare category cannot distinguish a
+ * `tool-degraded` from the scoped-lint runner from one out of lens
+ * materialization. It is descriptive, never a routing key.
+ *
  * @param {unknown} parsed          One parsed NDJSON row.
  * @param {number}  fallbackStoryId Stream owner, used when the row has none.
- * @returns {{ category: string, source: 'framework'|'consumer', storyId: number, details: object }|null}
+ * @returns {{ category: string, source: 'framework'|'consumer', storyId: number, tool: string, details: object }|null}
  */
 export function normalizeGatheredSignal(parsed, fallbackStoryId) {
   if (!parsed || typeof parsed !== 'object') return null;
@@ -358,10 +365,15 @@ export function normalizeGatheredSignal(parsed, fallbackStoryId) {
     typeof parsed.category === 'string' ? parsed.category.trim() : '';
   if (!category) return null;
   const recordStoryId = Number(parsed.storyId);
+  const emitterTool =
+    parsed.emitter && typeof parsed.emitter === 'object'
+      ? parsed.emitter.tool
+      : undefined;
   return {
     category,
     source: parsed.source === 'framework' ? 'framework' : 'consumer',
     storyId: Number.isInteger(recordStoryId) ? recordStoryId : fallbackStoryId,
+    tool: typeof emitterTool === 'string' ? emitterTool.trim() : '',
     details:
       parsed.details && typeof parsed.details === 'object'
         ? parsed.details

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

@@ -36,10 +36,17 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { createInterface } from 'node:readline';
 
-import { signalsFile, storyTempDir } from '../config/temp-paths.js';
+import {
+  resolvedTempRoot,
+  SIGNALS_BASENAME,
+  STANDALONE_DIRNAME,
+  STORIES_DIRNAME,
+  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';
+import { classifySignalSource } from './source-classifier.js';
 
 const TRACES_BASENAME = 'traces.ndjson';
 
@@ -69,10 +76,14 @@ function tracesFile(eid, sid, config) {
  *     `"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.
+ *     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.
  *
  * @param {unknown} signal
  * @returns {unknown}
@@ -86,14 +97,7 @@ function tagSignalSource(signal) {
     return record;
   }
   try {
-    const failingPath = record.failingPath ?? record.path;
-    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 };
+    return { ...record, source: classifySignalSource(record) };
   } catch (err) {
     Logger.warn(
       `signals-writer: source classifier failed (${
@@ -321,3 +325,118 @@ 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[]>}
+ */
+async function readDirEntries(dir) {
+  try {
+    return await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * 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.
+ *
+ * @param {object} [config]
+ * @returns {Promise<Array<{ storyId: number, file: string }>>}
+ */
+async function listStorySignalStreams(config) {
+  let root;
+  try {
+    root = resolvedTempRoot(config);
+  } catch (err) {
+    Logger.warn(
+      `signals-writer: cannot resolve tempRoot for stream discovery: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+    return [];
+  }
+
+  const storiesDirs = [];
+  for (const entry of await readDirEntries(root)) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name !== STANDALONE_DIRNAME && !RUN_DIR_RE.test(entry.name)) {
+      continue;
+    }
+    storiesDirs.push(path.join(root, entry.name, STORIES_DIRNAME));
+  }
+
+  const streams = [];
+  for (const storiesDir of storiesDirs) {
+    for (const entry of await readDirEntries(storiesDir)) {
+      if (!entry.isDirectory()) continue;
+      const match = STORY_DIR_RE.exec(entry.name);
+      if (match === null) continue;
+      streams.push({
+        storyId: Number(match[1]),
+        file: path.join(storiesDir, entry.name, SIGNALS_BASENAME),
+      });
+    }
+  }
+  return streams.sort((a, b) => a.file.localeCompare(b.file));
+}
+
+/**
+ * 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.
+ *
+ * @param {(parsed: unknown, context: { storyId: number, file: string, lineNumber: number }) => unknown | Promise<unknown>} cb
+ * @param {object} [config]
+ * @returns {Promise<{ streams: number, linesParsed: number }>}
+ */
+export async function forEachSignalStreamLine(cb, config) {
+  if (typeof cb !== 'function') {
+    Logger.warn(
+      'signals-writer: forEachSignalStreamLine called without a callback',
+    );
+    return { streams: 0, linesParsed: 0 };
+  }
+  const streams = await listStorySignalStreams(config);
+  let linesParsed = 0;
+  for (const { storyId, file } of streams) {
+    const result = await forEachLineIn(
+      file,
+      (parsed, lineNumber) => cb(parsed, { storyId, file, lineNumber }),
+      'forEachSignalStreamLine',
+    );
+    linesParsed += result.linesParsed;
+  }
+  return { streams: streams.length, linesParsed };
+}

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

@@ -22,6 +22,12 @@
  *     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
@@ -100,4 +106,128 @@ export function classifyPathSource(failingPath, command) {
   return 'consumer';
 }
 
-export const __testing = Object.freeze({ FRAMEWORK_PREFIXES });
+/**
+ * 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.
+ *
+ * @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[]}
+ */
+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}
+ */
+function isSupplied(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+/**
+ * Concatenate the scannable free text out of a record's `details` payload.
+ *
+ * @param {unknown} details
+ * @returns {string}
+ */
+function detailsScanText(details) {
+  if (details === null || typeof details !== 'object') return '';
+  const record = /** @type {Record<string, unknown>} */ (details);
+  const parts = [];
+  for (const key of DETAIL_SCAN_KEYS) {
+    const value = record[key];
+    if (typeof value === 'string') parts.push(value);
+  }
+  return parts.join('\n');
+}
+
+/**
+ * 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.
+ *
+ * @param {unknown} record One signal record (the `appendSignal` payload).
+ * @returns {"framework"|"consumer"}
+ */
+export function classifySignalSource(record) {
+  if (record === null || typeof record !== 'object' || Array.isArray(record)) {
+    return 'consumer';
+  }
+  const signal = /** @type {Record<string, unknown>} */ (record);
+  const emitter =
+    signal.emitter !== null && typeof signal.emitter === 'object'
+      ? /** @type {Record<string, unknown>} */ (signal.emitter)
+      : null;
+  const failingPath = signal.failingPath ?? signal.path;
+  const command = signal.command ?? emitter?.command;
+
+  if (isSupplied(failingPath) || isSupplied(command)) {
+    return classifyPathSource(failingPath, command);
+  }
+  if (containsFrameworkPrefix(detailsScanText(signal.details))) {
+    return 'framework';
+  }
+  if (
+    typeof signal.category === 'string' &&
+    signal.category.trim() === TOOL_DEGRADED_CATEGORY
+  ) {
+    return 'framework';
+  }
+  return 'consumer';
+}
+
+export const __testing = Object.freeze({
+  FRAMEWORK_PREFIXES,
+  TOOL_DEGRADED_CATEGORY,
+});

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

@@ -43,6 +43,10 @@ import { hasSurvivingCritical } from '../audit-suite/findings.js';
 import { resolveConfig } from '../config-resolver.js';
 import { computeChangeSet } from './change-set.js';
 import { deriveChangeLevel, resolveDepth } from './review-depth.js';
+import {
+  collectProviderDegradations,
+  degradationEnvelope,
+} from './review-providers/degraded-gates.js';
 import {
   countBySeverity,
   renderFindings,
@@ -176,6 +180,7 @@ function resolveScopeEnvelope(opts, config) {
  *   postedCommentId: number|null,
  *   commentTargetId: number,
  *   halted: boolean,
+ *   degraded: boolean, degradations: Array<object>,
  *   blockerReason: string|null,
  * }>}
  */
@@ -357,6 +362,11 @@ async function executeReviewPipeline({ opts, config, envelope }) {
     logger,
   );
 
+  // Story #4839 — degraded gates ride beside the findings, never inside them.
+  const degradations = await collectProviderDegradations(
+    reviewProvider,
+    logger,
+  );
   const severity = countBySeverity(findings);
   const halted = hasSurvivingCritical(severity);
   const report = renderFindingsFn({
@@ -367,6 +377,7 @@ async function executeReviewPipeline({ opts, config, envelope }) {
     findings,
     provider: providerName,
     promptMessages,
+    degradations,
   });
 
   const { posted, postedCommentId } = await postReviewComment({
@@ -385,6 +396,7 @@ async function executeReviewPipeline({ opts, config, envelope }) {
     postedCommentId,
     commentTargetId,
     halted,
+    ...degradationEnvelope(degradations),
     blockerReason: halted
       ? `code-review reported ${severity.critical} critical blocker(s)`
       : null,