mandrel 1.88.0 → 1.90.0

package/.agents/scripts/lib/orchestration/story-close/shared-checkout-guard.js

@@ -0,0 +1,163 @@
+/**
+ * shared-checkout-guard.js — cross-epic contention guard for the merge
+ * phase's `git checkout <epicBranch>` in the shared main checkout
+ * (Story #4460).
+ *
+ * `story-close.js`'s merge phase (`runFinalizeMerge` in `merge-runner.js`)
+ * runs `git checkout <epicBranch>` directly in the shared main repo
+ * checkout — `close-inputs.js` resolves `cwd` to `PROJECT_ROOT`, not an
+ * isolated worktree. The only exclusivity guard around that shared
+ * checkout is the per-Epic `epic-merge-lock.js` mutex, which only
+ * serializes concurrent runs for the SAME epic. Nothing stops a
+ * DIFFERENT epic's concurrently-running `story-close.js` from treating
+ * the same shared checkout as scratch space at the same time.
+ *
+ * This was observed live: while delivering Epic #4425 Stories #4427/#4428,
+ * the shared checkout repeatedly carried uncommitted stray changes
+ * belonging to a concurrently-running Epic #4405 delivery (parked on
+ * `epic/4405` with dirty edits), which blocked the `git checkout epic/4425`
+ * merge step with a raw `error: Your local changes ... would be
+ * overwritten by checkout`.
+ *
+ * `assertSharedCheckoutAvailable` runs immediately before that checkout
+ * and fails fast with an actionable, story-close-specific diagnostic
+ * instead of letting the raw git error surface. It COMPOSES with (does
+ * not replace) the per-Epic lock: by the time this guard runs, the
+ * caller's own epic lock is already held (acquired around the whole
+ * close flow in `story-close.js`), so this guard only inspects OTHER
+ * epics' lock files plus the tree's overall dirty state — it never
+ * contends with same-epic concurrent runs, which continue to serialize
+ * solely via `withEpicMergeLock` before this guard ever executes.
+ *
+ * Breadth trade-off (deliberate): the foreign-lock probe keys on the
+ * OTHER epic's per-epic merge lock, which that run holds for its WHOLE
+ * close flow — so any overlapping story-close of another epic trips this
+ * guard even when that run never actually touches the shared checkout
+ * during the overlap. The refusal is deterministic and loud (throws with
+ * a diagnostic naming the holder pid), never a deadlock (no waiting),
+ * and stale/dead-pid foreign locks are ignored via the pid-liveness
+ * probe. Narrowing the window (a dedicated checkout-phase lock) was
+ * considered and rejected: the coarse refusal is rare, cheap to retry,
+ * and far simpler than a second lock tier.
+ */
+
+import { findForeignActiveEpicLock as defaultFindForeignActiveEpicLock } from '../../epic-merge-lock.js';
+import { gitSpawn as defaultGitSpawn } from '../../git-utils.js';
+
+const MAX_LISTED_DIRTY_FILES = 20;
+
+function describeForeignLock(foreign) {
+  const acquired = Number.isFinite(foreign.acquiredAt)
+    ? new Date(foreign.acquiredAt).toISOString()
+    : 'an unknown time';
+  return (
+    `[story-close] shared-checkout guard: refusing to touch the shared main checkout — ` +
+    `it is currently held by epic #${foreign.epicId}'s story-close merge phase ` +
+    `(lock ${foreign.filePath}, pid ${foreign.pid}, acquired ${acquired}). ` +
+    `Wait for that epic's story-close run to finish before retrying this merge. ` +
+    `If you have independently confirmed that process is no longer running, remove ` +
+    `the lock file by hand — never force a checkout past a live foreign lock. ` +
+    `See .agents/rules/git-conventions.md § Shared-checkout contention (Story #4460).`
+  );
+}
+
+function listDirtyFiles(porcelainOutput) {
+  // `git status --porcelain` lines are `XY <path>` — a fixed 2-char status
+  // column, a space, then the path. Strip only a trailing `\r` (Windows)
+  // before slicing off that 3-char prefix; trimming the whole line first
+  // would shift the slice offset whenever the status column starts with a
+  // space (the common "unstaged modification" case), truncating the path.
+  const lines = porcelainOutput
+    .split('\n')
+    .map((line) => line.replace(/\r$/, ''))
+    .filter((line) => line.length > 0);
+  const shown = lines
+    .slice(0, MAX_LISTED_DIRTY_FILES)
+    .map((line) => line.slice(3).trim() || line);
+  const overflow = lines.length - shown.length;
+  return overflow > 0
+    ? `${shown.join(', ')}, … (+${overflow} more)`
+    : shown.join(', ');
+}
+
+function describeDirtyCheckout({ cwd, epicId, currentBranch, dirtyFiles }) {
+  return (
+    `[story-close] shared-checkout guard: refusing to check out the epic branch for ` +
+    `epic #${epicId} — the shared main checkout at ${cwd} is dirty (currently on ` +
+    `\`${currentBranch}\`). Dirty files: ${dirtyFiles}. This usually means another ` +
+    `epic's story-close run left uncommitted work in the shared checkout, or a prior ` +
+    `run crashed mid-merge. Resolve manually (stash/commit/reset in ${cwd}) before ` +
+    `retrying. See .agents/rules/git-conventions.md § Shared-checkout contention ` +
+    `(Story #4460).`
+  );
+}
+
+/**
+ * Fail fast when the shared main checkout is not safely available for this
+ * epic's merge-phase `git checkout <epicBranch>` — either because another
+ * epic's story-close merge phase currently holds it (a live foreign lock),
+ * or because it is simply dirty (regardless of whose branch is checked
+ * out). Silent no-op when the checkout is clean and uncontended.
+ *
+ * @param {{
+ *   cwd: string,
+ *   epicId: number|string,
+ *   gitSpawn?: typeof defaultGitSpawn,
+ *   findForeignActiveEpicLock?: typeof defaultFindForeignActiveEpicLock,
+ * }} opts
+ * @throws {Error} with an actionable, story-close-specific diagnostic.
+ */
+/**
+ * Foreign-lock-only variant for the RESUME merge path (Story #4460
+ * follow-up): a resume legitimately re-enters a shared checkout that is
+ * dirty with THIS story's own in-progress merge, so the dirty-tree half
+ * of `assertSharedCheckoutAvailable` would false-positive there. The
+ * cross-epic hazard — another epic's live merge phase holding the
+ * checkout — still applies and is the only probe this variant runs.
+ */
+export function assertNoForeignEpicLock({
+  cwd,
+  epicId,
+  findForeignActiveEpicLock = defaultFindForeignActiveEpicLock,
+}) {
+  const foreign = findForeignActiveEpicLock(epicId, { repoRoot: cwd });
+  if (foreign) {
+    throw new Error(describeForeignLock(foreign));
+  }
+}
+
+export function assertSharedCheckoutAvailable({
+  cwd,
+  epicId,
+  gitSpawn = defaultGitSpawn,
+  findForeignActiveEpicLock = defaultFindForeignActiveEpicLock,
+}) {
+  const foreign = findForeignActiveEpicLock(epicId, { repoRoot: cwd });
+  if (foreign) {
+    throw new Error(describeForeignLock(foreign));
+  }
+
+  const statusRes = gitSpawn(cwd, 'status', '--porcelain');
+  if (statusRes.status !== 0) {
+    // Can't determine dirtiness from here — let the downstream checkout
+    // surface whatever git itself reports rather than guessing.
+    return;
+  }
+  const porcelain = statusRes.stdout || '';
+  if (porcelain.trim().length === 0) return;
+
+  const branchRes = gitSpawn(cwd, 'rev-parse', '--abbrev-ref', 'HEAD');
+  const currentBranch =
+    branchRes.status === 0
+      ? (branchRes.stdout || '').trim() || 'unknown'
+      : 'unknown';
+
+  throw new Error(
+    describeDirtyCheckout({
+      cwd,
+      epicId,
+      currentBranch,
+      dirtyFiles: listDirtyFiles(porcelain),
+    }),
+  );
+}

package/.agents/scripts/lib/orchestration/ticketing/reads.js

@@ -59,7 +59,17 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   'friction',
   'notification',
   // Extended set (Story #449 — retro follow-ons)
-  'code-review',
+  // Story #4411 (Epic #4405) — the former `code-review` structured comment
+  // is unified with the former `audit-results` comment into the single
+  // `verification-results` findings contract. `runCodeReview` (the sole code
+  // producer) upserts `verification-results`; the feedback-loop graduators and
+  // the auto-merge integration gate read it. Both the `code-review` and (as of
+  // Story #4412's slim-Epic-close cutover) the `audit-results` markers are
+  // retired here — the Phase 4 standalone lens walk folded into the Phase 5
+  // code-review pass, whose single `verification-results` comment now carries
+  // the Epic-close lens findings. Hard cutover, no dual-shape reader per
+  // `git-conventions.md`.
+  'verification-results',
   'retro',
   'retro-partial',
   'epic-run-state',
@@ -98,14 +108,6 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   // operator can correct drift before Phase 8 decomposes from a stale
   // spec. Advisory: the run continues regardless of the report contents.
   'spec-freshness',
-  // Story #2681 — `/deliver` Phase 4 epic-audit helper upserts an
-  // `audit-results` comment on the Epic listing the per-lens findings
-  // returned by the change-set audit pass. The marker was prescribed by
-  // `helpers/epic-audit.md` Step 4 long before it was added to this
-  // registry; without the entry the helper's `post-structured-comment.js`
-  // invocation always failed with "Invalid structured-comment type". One
-  // entry per Epic; re-runs replace prior content.
-  'audit-results',
   // Story #2813 — the per-Task progress writer (since retired under
   // #3157) upserted a `model-attribution` comment on a Task ticket at
   // the moment it transitioned to `agent::executing`, recording which
@@ -160,6 +162,15 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   // refuses with the claim age. One entry per Epic; re-acquires upsert
   // in place.
   'plan-lease',
+  // Story #4415 (Epic #4406) — the feedback-loop graduators
+  // (`audit-results-graduator.js` / `retro-proposals-graduator.js`) upsert a
+  // `cross-repo-deferred` comment on the Epic listing findings that route
+  // to a different repository and were therefore not filed here. Replaces
+  // the prior log-line-only trace so the deferral survives the finalize
+  // run as a durable, operator-visible record. Discriminated by a
+  // `graduator="audit-results|code-review"` attr so the two graduators
+  // upsert independent comments; re-runs upsert in place.
+  'cross-repo-deferred',
 ]);
 
 export const WAVE_TYPE_PATTERN = WAVE_MARKER_RE;

package/.agents/scripts/lib/planning-corpus.js

@@ -0,0 +1,306 @@
+/**
+ * planning-corpus.js — corpus-aware context for the standalone-Story
+ * planning path (Story #4432).
+ *
+ * `/plan --idea` previously drafted a standalone Story from a blank
+ * slate: the seed, the body template, and a title-only duplicate scan.
+ * For a change request that is really a small delta against an
+ * already-delivered surface, that blank slate throws away context the
+ * project already has — the docs digest and the relevant Tech Spec
+ * sections of existing Epics that cover the touched area.
+ *
+ * This module assembles that inherited context (`corpusContext`) for
+ * `story-plan.js`'s `--emit-context` envelope:
+ *
+ *   1. `docsDigest` — the same per-project docs digest
+ *      `orchestration/docs-digest.js` builds for `/deliver` Story
+ *      children, reused here so the standalone path gets the same
+ *      compact outline instead of re-reading the whole docs set.
+ *      `null` when `project.docsContextFiles` is not configured.
+ *   2. `relevantSections` — a ranked list of existing Epic Tech Spec
+ *      (or lede, when no Tech Spec region exists) excerpts that overlap
+ *      with the seed, so the draft can build on prior art instead of
+ *      re-deriving it.
+ *
+ * The Epic list surface (`provider.getEpics`) maps every issue through
+ * `issueToEpicListItem`, which deliberately omits `body` (a list-scale
+ * payload trim). Body content therefore requires an **explicit**,
+ * bounded per-candidate fetch via `provider.getEpic(id)` — never a
+ * silent assumption that the list response carries prose to score
+ * against.
+ *
+ * Relevance scoring reuses the same `tokenize` / `overlapScore` Jaccard
+ * primitives `duplicate-search.js` exports for Epic-dedupe and
+ * `story-plan.js` reuses for Story-dedupe — one matcher, three
+ * consumers, no forked scoring logic.
+ */
+
+import { overlapScore, tokenize } from './duplicate-search.js';
+import { extractEpicSection, hasEpicSection } from './epic-body-sections.js';
+import { Logger } from './Logger.js';
+import { buildDocsDigest } from './orchestration/docs-digest.js';
+
+/** Top-K Epics kept after the cheap title-only ranking pass. */
+const DEFAULT_CORPUS_MAX_CANDIDATES = 5;
+
+/**
+ * Bound on the explicit per-candidate body fetch. Keeps corpus-context
+ * assembly at a fixed, small number of GitHub reads regardless of how
+ * many open Epics the repo carries.
+ */
+export const DEFAULT_CORPUS_BODY_FETCH_TOP_K = 3;
+
+/** Minimum Jaccard overlap for a section excerpt to be worth surfacing. */
+const DEFAULT_CORPUS_MIN_SCORE = 0.1;
+
+/** Max relevant-section excerpts returned in the envelope. */
+const DEFAULT_CORPUS_MAX_SECTIONS = 5;
+
+/** Excerpt length cap (chars) so one oversized Tech Spec doesn't blow the envelope. */
+const EXCERPT_MAX_CHARS = 600;
+
+/**
+ * Page-scan cap passed to `provider.getEpics({ state: 'open', pageCap })`.
+ * The corpus lookup only ever ranks the list down to a top-5 shortlist
+ * (`DEFAULT_CORPUS_MAX_CANDIDATES`), so there is no need to inherit
+ * `paginateRest`'s full default ceiling (50 pages / 5000 items) to build
+ * it — a bounded scan keeps this call a fixed, small number of GitHub
+ * reads regardless of how many open Epics the repo carries.
+ */
+const CORPUS_EPICS_PAGE_CAP = 5;
+
+/**
+ * Rank open Epics by title-overlap with the seed. This is the cheap
+ * first pass over the list surface (title only — `issueToEpicListItem`
+ * has no `body`), used solely to pick the bounded top-K candidates
+ * worth an explicit body fetch. It is not the final relevance signal;
+ * `extractRelevantSections` re-scores against actual section content.
+ *
+ * @param {{ seed: string, epics: Array<{ id:number, title:string }>, maxResults?: number }} opts
+ * @returns {Array<{ id:number, title:string, score:number }>}
+ */
+export function rankCandidateEpics({
+  seed,
+  epics,
+  maxResults = DEFAULT_CORPUS_MAX_CANDIDATES,
+}) {
+  if (!seed || typeof seed !== 'string') {
+    throw new Error('rankCandidateEpics: seed must be a non-empty string');
+  }
+  if (!Array.isArray(epics)) {
+    throw new Error('rankCandidateEpics: epics must be an array');
+  }
+  const seedTokens = tokenize(seed);
+  if (seedTokens.size === 0) return [];
+
+  const ranked = [];
+  for (const epic of epics) {
+    if (!epic || typeof epic.title !== 'string') continue;
+    const score = overlapScore(seedTokens, tokenize(epic.title));
+    ranked.push({
+      id: epic.id,
+      title: epic.title,
+      score: Number(score.toFixed(4)),
+    });
+  }
+  ranked.sort((a, b) => b.score - a.score);
+  return ranked.slice(0, maxResults);
+}
+
+/**
+ * Fetch full bodies for the top-K ranked candidates via the single-issue
+ * read (`provider.getEpic`), which — unlike the `getEpics` list mapper —
+ * does carry `body`. This is the explicit, bounded fetch the corpus
+ * lookup performs instead of assuming the list surface already has
+ * prose to score: a candidate never contributes a relevant section
+ * without this round-trip resolving its body.
+ *
+ * A single candidate's fetch failing (deleted issue, transient error) is
+ * non-fatal — it is dropped from the result rather than aborting corpus
+ * assembly for every other candidate. Failures are logged via
+ * `Logger.debug` (stderr) so they are visible under
+ * `AGENT_LOG_LEVEL=verbose` triage without violating the friction-
+ * telemetry posture in `.agents/instructions.md` §1.H of never silently
+ * swallowing an error.
+ *
+ * The bounded candidate slice is fetched concurrently
+ * (`Promise.allSettled`) rather than sequentially — `topK` is a fixed
+ * small ceiling (default 3), so this is a bounded fan-out, not an
+ * unbounded one, and it removes the serial network-latency stacking a
+ * plain `for`-await loop would otherwise incur.
+ *
+ * @param {{ provider: object, candidates: Array<{ id:number, title:string }>, topK?: number }} opts
+ * @returns {Promise<Array<{ id:number, title:string, body:string }>>}
+ */
+export async function fetchCandidateBodies({
+  provider,
+  candidates,
+  topK = DEFAULT_CORPUS_BODY_FETCH_TOP_K,
+}) {
+  if (!provider || typeof provider.getEpic !== 'function') return [];
+  if (!Array.isArray(candidates) || candidates.length === 0) return [];
+
+  const bounded = candidates.slice(0, topK);
+  const settled = await Promise.allSettled(
+    bounded.map(async (candidate) => {
+      const epic = await provider.getEpic(candidate.id);
+      return {
+        id: candidate.id,
+        title: candidate.title ?? epic?.title ?? '',
+        body: epic?.body ?? '',
+      };
+    }),
+  );
+
+  const results = [];
+  for (let i = 0; i < settled.length; i += 1) {
+    const outcome = settled[i];
+    if (outcome.status === 'fulfilled') {
+      results.push(outcome.value);
+      continue;
+    }
+    // Best-effort: one candidate failing to resolve must not abort
+    // corpus-context assembly for the rest — but the failure is still
+    // surfaced for triage rather than silently swallowed.
+    Logger.debug(
+      `[planning-corpus] fetchCandidateBodies: candidate #${bounded[i].id} failed to resolve: ${outcome.reason?.message ?? outcome.reason}`,
+    );
+  }
+  return results;
+}
+
+/**
+ * Extract a scoreable excerpt from an Epic body: the managed Tech Spec
+ * region when present (the folded `## Delivery Slicing` section, #4324),
+ * otherwise the ideation lede — the prose before the first `##` heading
+ * — so a plain-body Epic still contributes something to score.
+ *
+ * @param {string} body
+ * @returns {{ kind:'techSpec'|'lede', content:string }}
+ */
+function extractScoreableExcerpt(body) {
+  if (hasEpicSection(body, 'techSpec')) {
+    return { kind: 'techSpec', content: extractEpicSection(body, 'techSpec') };
+  }
+  const lede = (body ?? '').split(/^##\s+/m)[0].trim();
+  return { kind: 'lede', content: lede };
+}
+
+/**
+ * Rank existing-Epic body excerpts (Tech Spec section, or lede) by
+ * overlap with the seed. Reuses the same `tokenize` / `overlapScore`
+ * primitives as the title-ranking pass above and as
+ * `duplicate-search.js` — one matcher shared across every corpus /
+ * dedupe surface.
+ *
+ * @param {{ seed:string, epicBodies: Array<{ id:number, title:string, body:string }>, maxResults?: number, minScore?: number }} opts
+ * @returns {Array<{ epicId:number, epicTitle:string, section:'techSpec'|'lede', score:number, excerpt:string }>}
+ */
+export function extractRelevantSections({
+  seed,
+  epicBodies,
+  maxResults = DEFAULT_CORPUS_MAX_SECTIONS,
+  minScore = DEFAULT_CORPUS_MIN_SCORE,
+}) {
+  if (!seed || typeof seed !== 'string') {
+    throw new Error('extractRelevantSections: seed must be a non-empty string');
+  }
+  if (!Array.isArray(epicBodies)) {
+    throw new Error('extractRelevantSections: epicBodies must be an array');
+  }
+  const seedTokens = tokenize(seed);
+  if (seedTokens.size === 0) return [];
+
+  const ranked = [];
+  for (const epic of epicBodies) {
+    if (!epic) continue;
+    const { kind, content } = extractScoreableExcerpt(epic.body ?? '');
+    if (!content) continue;
+    const score = overlapScore(seedTokens, tokenize(content));
+    if (score < minScore) continue;
+    ranked.push({
+      epicId: epic.id,
+      epicTitle: epic.title ?? null,
+      section: kind,
+      score: Number(score.toFixed(4)),
+      excerpt: content.slice(0, EXCERPT_MAX_CHARS),
+    });
+  }
+  ranked.sort((a, b) => b.score - a.score);
+  return ranked.slice(0, maxResults);
+}
+
+/**
+ * Assemble the `corpusContext` field of the story-plan context envelope.
+ * Pure orchestration over the three helpers above plus `buildDocsDigest`
+ * — no I/O beyond what `provider` and the docs-digest reader perform.
+ *
+ * `relevantSections` is `[]` (not an error) when the provider has no
+ * `getEpics` surface, the seed tokenizes to nothing, or no candidate
+ * clears `minScore` — the standalone-Story draft path degrades to
+ * exactly today's blank-slate behavior in that case.
+ *
+ * @param {{
+ *   seed: string,
+ *   provider?: { getEpics?: Function, getEpic?: Function },
+ *   docsContextFiles?: string[],
+ *   docsRoot?: string,
+ *   maxCandidates?: number,
+ *   bodyFetchTopK?: number,
+ *   maxSections?: number,
+ *   minScore?: number,
+ * }} opts
+ * @returns {Promise<{ docsDigest: string|null, relevantSections: Array<object> }>}
+ */
+export async function buildCorpusContext({
+  seed,
+  provider,
+  docsContextFiles,
+  docsRoot,
+  maxCandidates = DEFAULT_CORPUS_MAX_CANDIDATES,
+  bodyFetchTopK = DEFAULT_CORPUS_BODY_FETCH_TOP_K,
+  maxSections = DEFAULT_CORPUS_MAX_SECTIONS,
+  minScore = DEFAULT_CORPUS_MIN_SCORE,
+}) {
+  const docsDigest = await buildDocsDigest({ docsContextFiles, docsRoot });
+
+  let relevantSections = [];
+  if (provider && typeof provider.getEpics === 'function') {
+    // A single candidate-listing call failing (rate limit, transient
+    // network error, provider outage) must not abort the whole
+    // `--emit-context` envelope build — degrade to an empty candidate
+    // list instead of letting the rejection propagate out of the
+    // caller's `Promise.all` and take down the rest of the envelope
+    // (body template, tech-stack summary, docs digest) with it.
+    let epics = [];
+    try {
+      epics = await provider.getEpics({
+        state: 'open',
+        pageCap: CORPUS_EPICS_PAGE_CAP,
+      });
+    } catch (err) {
+      Logger.debug(
+        `[planning-corpus] buildCorpusContext: provider.getEpics failed, degrading to an empty candidate list: ${err?.message ?? err}`,
+      );
+      epics = [];
+    }
+    const ranked = rankCandidateEpics({
+      seed,
+      epics: Array.isArray(epics) ? epics : [],
+      maxResults: maxCandidates,
+    });
+    const bodies = await fetchCandidateBodies({
+      provider,
+      candidates: ranked,
+      topK: bodyFetchTopK,
+    });
+    relevantSections = extractRelevantSections({
+      seed,
+      epicBodies: bodies,
+      maxResults: maxSections,
+      minScore,
+    });
+  }
+
+  return { docsDigest, relevantSections };
+}

package/.agents/scripts/lib/signals/detectors/common.js

@@ -1,7 +1,7 @@
 /**
  * detectors/common.js — shared helpers for the signals layer.
  *
- * Hoisted out of three detector modules (hotspot, retry, rework) plus
+ * Hoisted out of the detector modules (retry, rework) plus
  * `signals/read.js` and `signals/schema.js`, all of which shipped
  * byte-equivalent copies of these predicates. See Story #2464.
  */
@@ -19,15 +19,15 @@ export function isPositiveInt(v) {
 
 /**
  * Pull the tool name from a trace record. The hook writes the tool name
- * into `source.tool` and (defensively) into `details.tool` — we accept
- * either so older traces still classify correctly.
+ * into `emitter.tool` (canonical provenance) and, defensively, into
+ * `details.tool` — we accept either.
  *
  * @param {object} rec
  * @returns {string|null}
  */
 export function extractTool(rec) {
-  if (typeof rec?.source?.tool === 'string' && rec.source.tool.length > 0) {
-    return rec.source.tool;
+  if (typeof rec?.emitter?.tool === 'string' && rec.emitter.tool.length > 0) {
+    return rec.emitter.tool;
   }
   if (typeof rec?.details?.tool === 'string' && rec.details.tool.length > 0) {
     return rec.details.tool;
@@ -38,12 +38,12 @@ export function extractTool(rec) {
 /**
  * Validate and normalize the shared detector argument preamble.
  *
- * `detectRework`, `detectRetry`, and `detectHotspot` previously shipped a
- * near-identical guard block: the `args` object-shape `TypeError`, the
- * `nowFn` function-type `TypeError`, the positive-integer `RangeError`s for
- * the id fields, the non-empty-string `tracesPath` check, and the
+ * `detectRework` and `detectRetry` previously shipped a near-identical
+ * guard block: the `args` object-shape `TypeError`, the `nowFn`
+ * function-type `TypeError`, the positive-integer `RangeError`s for the id
+ * fields, the non-empty-string `tracesPath` check, and the
  * non-negative-integer `threshold` check. Story #4077 hoists that preamble
- * here so the three detectors share one error-message contract.
+ * here so the detectors share one error-message contract.
  *
  * Error wording stays per-detector-accurate by prefixing every message with
  * `fnName` (e.g. `detectRework: …`). Error *types* are preserved exactly:

package/.agents/scripts/lib/signals/detectors/index.js

@@ -2,13 +2,13 @@
  * Detectors barrel (Epic #1721 / Story #1771 / Task #1774).
  *
  * Single import surface for every signal detector. Detector Stories
- * (rework in #1771, retry in #1768, hotspot in #1769) re-export from
- * here so callers (`lib/observability/perf-aggregator.js`, future
- * emission orchestrators) only ever import from one place.
+ * (rework in #1771, retry in #1768) re-export from here so callers
+ * (`lib/orchestration/detectors-phase.js`) only ever import from one
+ * place. The Epic #1769 hotspot detector was retired in the Epic #4406
+ * signal-contract cutover (no live emitter, no consumer).
  *
  * @module lib/signals/detectors
  */
 
-export { detectHotspot, nearestRankP95 } from './hotspot.js';
 export { detectRetry } from './retry.js';
 export { detectRework } from './rework.js';

package/.agents/scripts/lib/signals/detectors/retry.js

@@ -27,11 +27,12 @@
  * ## Failure rule
  *
  * A trace record is treated as **failed** when its `details.exitCode`
- * is a number and not `0`. The hook does not itself capture the exit
- * code today (the field is set by callers / future hook extensions);
- * records without an `exitCode` field are ignored, which matches the
- * decision in the parent Epic body that retry only counts non-zero-exit
- * commands.
+ * is a number and not `0`. As of Epic #4406 / Story #4413 the tool-trace
+ * hook captures `details.exitCode` for Bash `PostToolUse` events, so this
+ * detector fires on real deliveries; records without an `exitCode` field
+ * (non-Bash tools, or tools that report no exit code) are ignored, which
+ * matches the decision in the parent Epic body that retry only counts
+ * non-zero-exit commands.
  *
  * Successful runs after failures **do not** cancel the count — failure-
  * count is monotonic per identity. This matches the Epic's intent: once
@@ -41,12 +42,11 @@
  *
  * ## Tool filter
  *
- * Only trace records whose `source.tool === 'Bash'` participate. Edit /
+ * Only trace records whose `emitter.tool === 'Bash'` participate. Edit /
  * Write / Read / Grep / Glob events are not retries — those belong to
- * other detectors (rework for file-edit churn, hotspot at Epic scope).
- * The tool name is read from `source.tool` first and falls back to
- * `details.tool` to mirror the rework detector's tolerance for legacy
- * trace shapes.
+ * other detectors (rework for file-edit churn). The tool name is read
+ * from `emitter.tool` first and falls back to `details.tool` (see
+ * `common.extractTool`).
  *
  * ## Privacy contract
  *
@@ -124,13 +124,14 @@ function resolveIdentity(rec) {
 }
 
 /**
- * Decide whether a trace record represents a failed invocation. The
- * hook (today) does not capture exit codes; the field is populated by
- * future hook extensions and by tests that need to assert behaviour.
- * A record counts as failed when `details.exitCode` is a number and
- * not zero. Anything else (missing field, null, non-number, zero) is
- * NOT a failure and is ignored entirely — the detector only counts
- * non-zero-exit commands per the parent Epic.
+ * Decide whether a trace record represents a failed invocation. As of
+ * Epic #4406 / Story #4413 the tool-trace hook records `details.exitCode`
+ * for Bash `PostToolUse` events, so the field is present on real Bash
+ * traces (and still set directly by tests). A record counts as failed
+ * when `details.exitCode` is a number and not zero. Anything else
+ * (missing field, null, non-number, zero) is NOT a failure and is ignored
+ * entirely — the detector only counts non-zero-exit commands per the
+ * parent Epic.
  *
  * @param {object} rec
  * @returns {boolean}
@@ -238,7 +239,7 @@ export async function detectRetry(args) {
   return offenders.map(([commandHash, failureCount]) => ({
     ts,
     kind: 'retry',
-    source: { tool: 'retry-detector' },
+    emitter: { tool: 'retry-detector' },
     epicId,
     storyId,
     taskId,

package/.agents/scripts/lib/signals/detectors/rework.js

@@ -158,7 +158,7 @@ export async function detectRework(args) {
   return offenders.map(([targetHash, editCount]) => ({
     ts,
     kind: 'rework',
-    source: { tool: 'rework-detector' },
+    emitter: { tool: 'rework-detector' },
     epicId,
     storyId,
     taskId,