mandrel 1.87.0 → 1.89.0

package/.agents/scripts/epic-plan-spec-validate.js

@@ -1,111 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * epic-plan-spec-validate.js — Phase 7.5 Tech Spec post-authoring gate CLI.
- *
- * `/plan` Phase 7 authors the Tech Spec; Phase 8.3 (Holistic
- * Consolidation) reconciles the draft ticket array against the Tech Spec's
- * `## Delivery Slicing` section, which the decompose-author skill uses as the
- * capability-boundary anchor. When that section is absent the consolidation
- * pass runs against a void and produces groupings that reflect technical
- * shape rather than capability boundaries.
- *
- * This CLI is the hard gate between Phase 7 and Phase 8: it reads the authored
- * `techspec.md`, runs {@link ./lib/orchestration/spec-section-validator.js#validateSpecSections},
- * and exits non-zero when the required section is missing so decomposition
- * cannot proceed against an un-anchored spec. It is the Phase 8-side
- * counterpart to the Phase 6 Epic Clarity Gate (`epic-plan-clarity.js`) —
- * same detect-then-prompt pattern, one phase later.
- *
- * Usage:
- *   epic-plan-spec-validate.js --techspec <path> [--json]
- *
- * Exit codes:
- *   0 — every required section present.
- *   1 — at least one required section missing, or a fatal error (bad path,
- *       unreadable file). The failure message names the missing section(s)
- *       and tells the operator how to recover.
- */
-
-import { readFile } from 'node:fs/promises';
-import { parseArgs } from 'node:util';
-import { runAsCli } from './lib/cli-utils.js';
-import { Logger } from './lib/Logger.js';
-import { validateSpecSections } from './lib/orchestration/spec-section-validator.js';
-
-/**
- * Build the operator-facing failure message for a missing-section result.
- * Names each missing section and tells the operator whether to re-author the
- * spec or add the section by hand before continuing to Phase 8.
- *
- * @param {{ techspecPath: string, missing: string[] }} args
- * @returns {string}
- */
-export function formatMissingSectionMessage({ techspecPath, missing }) {
-  const list = missing.map((name) => `## ${name}`).join(', ');
-  return [
-    `[epic-plan-spec-validate] Tech Spec is missing required section(s): ${list}`,
-    `  Spec file: ${techspecPath}`,
-    '',
-    `  Phase 8 (decomposition) reconciles the draft ticket array against the`,
-    `  Tech Spec's "## Delivery Slicing" section — without it, the Phase 8.3`,
-    `  consolidation pass has no capability-boundary anchor and groups by`,
-    `  technical shape instead.`,
-    '',
-    '  To continue, do ONE of the following before re-running Phase 8:',
-    `    1. Re-author the Tech Spec (re-run the Phase 7 spec-author step) so it`,
-    `       emits a "## Delivery Slicing" section, OR`,
-    `    2. Add a "## Delivery Slicing" section to the Tech Spec by hand,`,
-    `       describing the capability boundaries the work should be sliced along.`,
-  ].join('\n');
-}
-
-/**
- * Validate an authored Tech Spec file for the required post-authoring
- * sections. Pure-ish wrapper around `validateSpecSections` that owns the file
- * read so the CLI `main` stays a thin arg-parse shell.
- *
- * @param {{ techspecPath: string }} args
- * @returns {Promise<{ ok: boolean, missing: string[], present: string[] }>}
- */
-export async function validateSpecFile({ techspecPath }) {
-  const body = await readFile(techspecPath, 'utf8');
-  return validateSpecSections({ body });
-}
-
-/* node:coverage ignore next */
-async function main() {
-  const { values } = parseArgs({
-    options: {
-      techspec: { type: 'string' },
-      json: { type: 'boolean', default: false },
-    },
-  });
-
-  if (!values.techspec) {
-    throw new Error(
-      'Usage: epic-plan-spec-validate.js --techspec <path> [--json]',
-    );
-  }
-
-  const techspecPath = values.techspec;
-  const result = await validateSpecFile({ techspecPath });
-
-  if (values.json) {
-    process.stdout.write(`${JSON.stringify({ techspecPath, ...result })}\n`);
-  }
-
-  if (!result.ok) {
-    throw new Error(
-      formatMissingSectionMessage({ techspecPath, missing: result.missing }),
-    );
-  }
-
-  Logger.info(
-    `[epic-plan-spec-validate] Tech Spec section gate passed: ${result.present
-      .map((name) => `## ${name}`)
-      .join(', ')} present.`,
-  );
-}
-
-runAsCli(import.meta.url, main, { source: 'epic-plan-spec-validate' });

package/.agents/scripts/lib/feedback-loop/code-review-graduator.js

@@ -1,207 +0,0 @@
-/**
- * code-review-graduator.js — Auto-graduate non-blocking code-review
- * findings from the Epic's `code-review` structured comment into routed
- * GitHub follow-up issues.
- *
- * Story #2555 / Epic #2547. As of Story #3845 / Epic #3823 the spawn
- * helper, the path/idempotency probes, the `gh issue create` filer, the
- * toggle reader, and the route → probe → file walk all live in the
- * shared [`graduator-core.js`](./graduator-core.js). This module is the
- * thin code-review-specific shell: it owns the code-review finding parser
- * (the 🟢→low severity mapping, no lens), the code-review label / title /
- * body shape, and the code-review idempotency marker. Behaviour is
- * identical to the pre-consolidation graduator.
- *
- *   - Read the `code-review` structured comment off the Epic ticket via
- *     the injected provider (findStructuredComment surface).
- *   - For each non-blocking finding (severity high/medium/low — i.e.
- *     anything that is NOT a 🔴 Critical Blocker), check that the cited
- *     file still exists in the merged tree (`git cat-file -e <ref>:<path>`)
- *     via the injected spawn seam.
- *   - Route by source classification (framework vs consumer) using
- *     `classifyPathSource` (S1 helper). When the routed repo differs
- *     from the current repo, record under `skipped: 'cross-repo-deferred'`
- *     and log the would-be `gh issue create` invocation — do NOT actually
- *     shell out against a different repo.
- *   - File a follow-up issue with `gh issue create --repo <routed-repo>`
- *     carrying a `code-review::<severity>` label plus the matching
- *     `meta::<framework-gap|consumer-improvement>` label.
- *   - Embed an idempotency marker in each body:
- *       <!-- code-review-followup: epic-<id>-finding-<idx> -->
- *     Before filing, probe via `gh search issues "<marker>" --repo …`
- *     and skip findings whose marker is already present in any issue.
- *   - Short-circuit when `config.delivery.feedbackLoop.codeReviewAutoFile`
- *     is `false` — return `{ filed: [], skipped: [{reason:
- *     'toggle-disabled'}], errors: [] }`.
- *   - NEVER throw. Every failure path (missing comment, parse failure,
- *     gh/git spawn error, non-zero exit) is captured in `errors[]`.
- *
- * Tests inject `provider`, `classifier`, and `spawnImpl` to drive every
- * branch deterministically.
- */
-
-import {
-  graduate,
-  makeIsAutoFileEnabled,
-  probePathExists,
-} from './graduator-core.js';
-
-/**
- * Resolve the toggle from the resolved agentrc config. Defaults to `true`
- * — the feature is opt-out, not opt-in.
- *
- * @param {object|undefined|null} config
- * @returns {boolean}
- */
-export const isAutoFileEnabled = makeIsAutoFileEnabled('codeReviewAutoFile');
-
-// Re-export the shared path probe so existing importers keep working.
-export { probePathExists };
-
-/**
- * Severity → label mapping. Only non-blocking severities have a route;
- * 🔴 Critical Blocker is explicitly filtered out upstream.
- */
-const SEVERITY_LABEL = Object.freeze({
-  high: 'code-review::high',
-  medium: 'code-review::medium',
-  low: 'code-review::low',
-});
-
-/**
- * Map a classification source to its meta routing label.
- *
- * @param {string} source
- * @returns {string}
- */
-function metaSourceLabel(source) {
-  return source === 'framework'
-    ? 'meta::framework-gap'
-    : 'meta::consumer-improvement';
-}
-
-/**
- * Compile a marker for a given epicId / finding index. The marker is an
- * HTML comment so it survives GitHub markdown rendering without leaking
- * into the visible body — but it's still indexable via `gh search`.
- *
- * @param {number} epicId
- * @param {number} index — zero-based finding ordinal within the Epic.
- * @returns {string}
- */
-export function buildIdempotencyMarker(epicId, index) {
-  return `<!-- code-review-followup: epic-${epicId}-finding-${index} -->`;
-}
-
-/**
- * Parse the rendered code-review markdown into a list of findings. Each
- * finding has `{ severity, path, summary, index }`. Pure. Exported so
- * the parser can be unit-tested in isolation.
- *
- * The structured `code-review` comment emits findings as bullet lines under the
- * "🚨 Critical Findings" and "🟡 Warnings" sections. Each line begins
- * with a severity emoji and embeds the cited path inside backticks. We
- * filter 🔴 (Critical Blocker — blocking) out; 🟠/🟡/🟢 are non-blocking
- * and graduate to follow-up issues.
- *
- * @param {string} body
- * @returns {Array<{ severity: 'high'|'medium'|'low', path: string, summary: string, index: number }>}
- */
-export function parseFindings(body) {
-  if (typeof body !== 'string' || body.length === 0) return [];
-  const findings = [];
-  const lines = body.split(/\r?\n/);
-  let idx = 0;
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (trimmed.length === 0) continue;
-    let severity = null;
-    if (trimmed.startsWith('🟠')) severity = 'high';
-    else if (trimmed.startsWith('🟡')) severity = 'medium';
-    else if (trimmed.startsWith('🟢')) severity = 'low';
-    else continue;
-    // Path is the first backticked token on the line.
-    const pathMatch = trimmed.match(/`([^`]+)`/);
-    if (!pathMatch) continue;
-    const path = pathMatch[1];
-    // Summary is the line itself, stripped of the leading emoji bullet.
-    findings.push({
-      severity,
-      path,
-      summary: trimmed,
-      index: idx,
-    });
-    idx += 1;
-  }
-  return findings;
-}
-
-/**
- * Auto-graduate non-blocking code-review findings into routed follow-up
- * issues. Never throws. Thin wrapper around the shared `graduate()` walk
- * with the code-review-specific behaviour bundle.
- *
- * @param {object} opts
- * @param {number} opts.epicId
- * @param {object} opts.provider — ticketing provider exposing
- *   `getTicketComments(ticketId)`.
- * @param {object} [opts.config] — resolved agentrc.
- * @param {{owner: string, repo: string}} opts.currentRepo — the repo the
- *   listener is running inside; used for the cross-repo guard.
- * @param {{owner: string, repo: string}} [opts.frameworkRepo] — where
- *   framework-tagged findings get routed. Defaults to
- *   `currentRepo` when this is the framework repo, otherwise typically
- *   `{ owner: 'dsj1984', repo: 'mandrel' }`.
- * @param {string} [opts.gitRef='HEAD'] — ref against which to probe path
- *   existence.
- * @param {Function} [opts.classifier=classifyPathSource] — S1 helper.
- * @param {string} [opts.ghPath='gh']
- * @param {Function} [opts.spawnImpl]
- * @param {string} [opts.cwd]
- * @param {{info?: Function, warn?: Function, debug?: Function}} [opts.logger]
- * @returns {Promise<{
- *   filed: Array<{ index: number, severity: string, path: string, source: string, repo: string, url: string|null }>,
- *   skipped: Array<{ index?: number, reason: string, path?: string, severity?: string }>,
- *   errors: string[],
- * }>}
- */
-export async function graduateFindings(opts = {}) {
-  return graduate({
-    ...opts,
-    spec: {
-      fnName: 'graduateFindings',
-      isAutoFileEnabled,
-      commentMarker: '<!-- structured-comment: code-review -->',
-      noCommentReason: 'no-code-review-comment',
-      parseFindings,
-      buildIdempotencyMarker,
-      buildCrossRepoLog: ({ finding, routedRepo, source }) => {
-        const metaLabel = metaSourceLabel(source);
-        return `[code-review-graduator] cross-repo skip (would file in ${routedRepo.owner}/${routedRepo.repo}): gh issue create --repo ${routedRepo.owner}/${routedRepo.repo} --title "Code review follow-up: ${finding.path}" --label "${metaLabel},${SEVERITY_LABEL[finding.severity]}"`;
-      },
-      buildFollowUp: ({ finding, source, epicId, idMarker }) => {
-        const metaLabel = metaSourceLabel(source);
-        const title = `Code review follow-up: ${finding.path}`;
-        const body = [
-          idMarker,
-          '',
-          `Auto-filed from the Epic #${epicId} code-review pass.`,
-          '',
-          `**Severity**: ${finding.severity}`,
-          `**Source**: ${source}`,
-          `**Path**: \`${finding.path}\``,
-          '',
-          '### Finding',
-          '',
-          finding.summary,
-          '',
-          `_See Epic #${epicId} for the full code-review report._`,
-        ].join('\n');
-        const labels = [metaLabel, SEVERITY_LABEL[finding.severity]];
-        return { title, body, labels };
-      },
-    },
-  });
-}
-
-export default graduateFindings;

package/.agents/scripts/lib/orchestration/epic-plan-spec/phases/prompts.js

@@ -1,58 +0,0 @@
-/**
- * phases/prompts.js — Canonical Tech Spec / Acceptance Spec system prompts for
- * the spec phase of `/plan`.
- *
- * These ride along on the `--emit-context` envelope as a backstop. The
- * `epic-plan-spec-author` Skill
- * (`.agents/skills/core/epic-plan-spec-author/SKILL.md`) embeds the
- * authoritative copies of these strings — keep the two surfaces in sync when
- * either is edited.
- *
- * Story #4314: the PRD artifact class is retired. The Epic body (which now
- * carries its `## User Stories` section inline) is the sole authoring input;
- * both prompts consume the Epic body directly rather than a paraphrased PRD.
- *
- * Story #4324: the Tech Spec and Acceptance Spec are no longer separate
- * `context::*` tickets — the authored content lands as managed sections of
- * the same Epic body (`## Delivery Slicing`-led Tech Spec sections, and the
- * `## Acceptance Table` AC-ID table). Content semantics are unchanged; only
- * WHERE the output lives moved.
- */
-
-export const TECH_SPEC_SYSTEM_PROMPT = `You are an expert Engineering Architect.
-Your job is to convert an Epic into a Technical Specification for implementation.
-
-The Tech Spec should outline:
-1. Delivery Slicing — propose how the Epic's enumerated capabilities cluster into shippable Stories. This count is a CEILING, not a target: the Phase 8 consolidation pass may merge below your proposed count when slices form dependent single-consumer chains, but never splits above it. Do NOT coarsen the Epic enumeration to produce this; the grouping recommendation is the granularity lever.
-2. Architecture & Design
-3. Data Models (if any)
-4. API Changes (if any)
-5. Core Components
-6. Security & Privacy Considerations
-
-CRITICAL REQUIREMENTS:
-- Respond ONLY with valid Markdown.
-- Do not use top-level <h1> (# ) tags. Open the document with the \`## Delivery Slicing\` section — it is the primary input to Phase 8 consolidation, so author it first and hang the rest of the spec off it.
-- Do NOT restate the Epic's Context, Goal, or Scope — your output lands as sections of the same Epic body, which travels into every downstream story agent's prompt, so any restatement is pure duplication and a drift risk. If a brief technical orientation is genuinely useful, add an optional \`## Technical Overview\` of no more than 2–3 sentences that names the *technical approach* only (which subsystems are touched and reused); never re-narrate the problem statement, goals, or scope.
-- Format architectural decisions clearly with bullet points.
-- Author the \`## Delivery Slicing\` section as a markdown table with columns \`Slice | What ships | Independent?\`, using noun-phrase slice names (e.g. "Foundation", "Transport seam", "Send helper") that map onto Feature titles. "Independent?" answers: can this slice ship to production and provide value without the next slice landing? A slice you mark "Independent? No" MUST carry a one-line justification (parallelism, risk isolation, or delivery-envelope pressure); an unjustified dependent single-consumer slice folds into its consumer by default rather than shipping as its own Story.`;
-
-export const ACCEPTANCE_SPEC_SYSTEM_PROMPT = `You are an expert Acceptance Engineer.
-Your job is to convert an Epic and a Tech Spec into a structured Acceptance Specification that drives features-first BDD authoring.
-
-The Acceptance Spec should outline:
-1. Acceptance Table — one row per user-visible outcome, expressed as a Markdown table with columns: AC ID | Outcome | Feature File | Scenario | Disposition
-2. Stable AC IDs — assign AC-1, AC-2, ... in document order; reuse the same ID across re-plans when an Outcome is materially unchanged so scenario tags (@ac-N) stay aligned
-3. Disposition — tag each row with one of: new | updated | unchanged
-
-The Epic body's \`## Acceptance Criteria\` bullets are the single source of truth for what the spec verifies. Your table does not re-invent criteria — it anchors each one to a specific Epic AC bullet.
-
-CRITICAL REQUIREMENTS:
-- Respond ONLY with valid Markdown.
-- Do not use top-level <h1> (# ) tags. Start with ## Acceptance Table — the table lands as a section of the Epic body, so it must NOT reuse the Epic's own ## Acceptance Criteria heading.
-- Every AC row MUST have a stable AC ID of the form AC-<n> (AC-1, AC-2, ...) — do not reorder IDs across re-plans; new ACs get fresh sequential IDs.
-- Every AC row MUST carry a Disposition value from the enum: new | updated | unchanged. (At Epic close, the acceptance reconciler overwrites Disposition with the verification outcome — satisfied | pending | missing — inside this section only; on re-plan, reset each row to the authoring enum.)
-- Each Outcome MUST be a **terse restatement keyed to a specific Epic \`## Acceptance Criteria\` bullet** — lead the Outcome with the bullet's anchor (its quoted lead phrase or an explicit "Epic AC N" index) and keep the rest to a single user-visible behaviour. Do NOT re-elaborate the Epic bullet in independent words: a free-standing Outcome that paraphrases the criterion without naming the bullet it verifies is forbidden, because it drifts from the Epic silently. No DB assertions, no HTTP status codes, no internal implementation details.
-- Where one Epic AC bullet genuinely expands into several user-visible outcomes, emit one row per outcome and declare the split on each — e.g. lead with "splits Epic AC 3" — so the fan-out is explicit rather than hidden.
-- Anchor coverage MUST be complete and auditable: every Epic AC bullet MUST be covered by at least one row, and every row MUST anchor to an Epic AC bullet. Flag divergence in the authored spec instead of dropping it — if an Epic AC bullet has no corresponding row, or a row has no Epic anchor, call it out explicitly (a note beneath the table) rather than silently omitting the bullet or emitting an unanchored row.
-- Cite proposed feature file paths under tests/features/** so Phase 8 can scaffold matching scenarios.`;

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

@@ -1,292 +0,0 @@
-/**
- * Hotspot detector — pure module (Epic #1721 / Story #1769 / Task #1776).
- *
- * Walks every Story directory under `temp/epic-<eid>/`, aggregates edit
- * counts per `details.targetHash` for file-mutating tools across Stories,
- * and emits one `kind: 'hotspot'` SignalEvent per hash whose total edit
- * count exceeds `p95 * multiplier`. Pure: takes config-shaped args in,
- * returns events out. Caller persists via `appendEpicSignal` (the signal
- * is Epic-scope; there is no single owning Story).
- *
- * ## Counting rule
- *
- * Only file-mutating tools are counted:
- *   - `Edit`
- *   - `Write`
- *   - `MultiEdit`
- *   - `NotebookEdit`
- *
- * Every other tool (Read, Bash, Grep, Glob, …) is ignored. Trace records
- * without a `details.targetHash` are also skipped — without a stable key
- * we cannot group repeats.
- *
- * ## Cross-Story-only percentile pool
- *
- * Hashes that appear in **fewer than 2 Stories** are excluded from the
- * p95 calculation. This prevents a single large Story from manufacturing
- * its own hotspot when no other Story touches the same file. The pool
- * for the percentile is therefore the set of `totalEdits` values for
- * hashes seen in ≥ 2 Stories. Hashes outside that pool also do not
- * emit a signal — by construction they are not cross-Story.
- *
- * ## p95 algorithm
- *
- * Nearest-rank method (no interpolation): for a sorted array of length
- * `n`, the p95 index is `ceil(0.95 * n) - 1` (0-based). For
- * `[1,2,3,4,5,6,7,8,9,10]` the index is `ceil(9.5) - 1 = 9` → value `10`.
- * For a single-element array `[10]` the index is `ceil(0.95) - 1 = 0` →
- * value `10`. Nearest-rank keeps fixture-driven tests deterministic
- * across Node versions and avoids the floating-point ambiguity of
- * linear-interpolation variants.
- *
- * ## Privacy contract
- *
- * Trace records key off `details.targetHash` (a sha256 of the file path,
- * see `lib/observability/tool-trace-hook.js`). The detector groups by
- * the hash, never the raw path, so the privacy boundary established by
- * the hook is preserved end-to-end.
- *
- * ## Threshold semantics
- *
- * `totalEdits > p95 * multiplier` (strictly greater than). A hash with
- * exactly `p95 * multiplier` edits does NOT emit; only counts past the
- * threshold trip the detector. The multiplier comes from
- * `delivery.signals.hotspot.p95Multiplier` (default 1.25) — pass it in
- * via `args.multiplier`. The detector itself does not import the config
- * resolver.
- *
- * ## Robustness
- *
- *   - Missing `temp/epic-<eid>/` → returns `[]`. Never throws.
- *   - Story directories with no `traces.ndjson` → contribute zero edits.
- *   - Malformed JSON lines → silently skipped (consistent with
- *     `lib/signals/read.js` and `detectors/rework.js`).
- *   - Non-trace records → ignored (the file may legitimately interleave
- *     other kinds in future).
- *
- * @module lib/signals/detectors/hotspot
- */
-
-import { createReadStream } from 'node:fs';
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import { createInterface } from 'node:readline';
-import { epicTempDir } from '../../config/temp-paths.js';
-import { parseStoryBranch } from '../../git-utils.js';
-import { extractTool, validateDetectorArgs } from './common.js';
-
-/**
- * Tools that mutate files. Only these contribute to the per-target edit
- * count. Anything outside this set is ignored.
- *
- * @type {ReadonlySet<string>}
- */
-const FILE_MUTATING_TOOLS = Object.freeze(
-  new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']),
-);
-
-function isPositiveNumber(v) {
-  return typeof v === 'number' && Number.isFinite(v) && v > 0;
-}
-
-/**
- * Stream a single `traces.ndjson` line-by-line and emit per-targetHash
- * edit counts as a `Map<targetHash, count>`. Missing file → empty map.
- *
- * @param {string} tracesPath
- * @returns {Promise<Map<string, number>>}
- */
-async function tallyEditsByTarget(tracesPath) {
-  const counts = new Map();
-
-  // Existence check before opening the stream — `createReadStream`
-  // defers ENOENT until the first read, which leaves the iterator in a
-  // bad state on some Node versions.
-  try {
-    await fs.access(tracesPath);
-  } catch {
-    return counts;
-  }
-
-  const stream = createReadStream(tracesPath, { encoding: 'utf8' });
-  const rl = createInterface({ input: stream, crlfDelay: Infinity });
-
-  try {
-    for await (const rawLine of rl) {
-      if (rawLine.length === 0) continue;
-      let parsed;
-      try {
-        parsed = JSON.parse(rawLine);
-      } catch {
-        continue;
-      }
-      if (parsed == null || typeof parsed !== 'object') continue;
-      if (parsed.kind !== 'trace') continue;
-
-      const tool = extractTool(parsed);
-      if (tool == null || !FILE_MUTATING_TOOLS.has(tool)) continue;
-
-      const hash = parsed.details?.targetHash;
-      if (typeof hash !== 'string' || hash.length === 0) continue;
-
-      counts.set(hash, (counts.get(hash) ?? 0) + 1);
-    }
-  } finally {
-    rl.close();
-    if (!stream.destroyed) stream.destroy();
-  }
-
-  return counts;
-}
-
-/**
- * Enumerate `story-<id>` subdirectories of `epicDir`. Returns an empty
- * array when `epicDir` does not exist. The ordering is by Story ID
- * ascending so `storiesAffected` and any future audit output are stable.
- *
- * @param {string} epicDir
- * @returns {Promise<string[]>} absolute paths to each story directory
- */
-async function listStoryDirs(epicDir) {
-  let entries;
-  try {
-    entries = await fs.readdir(epicDir, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-  const stories = [];
-  for (const ent of entries) {
-    if (!ent.isDirectory()) continue;
-    const id = parseStoryBranch(ent.name);
-    if (id == null) continue;
-    stories.push({ id, dir: path.join(epicDir, ent.name) });
-  }
-  stories.sort((a, b) => a.id - b.id);
-  return stories.map((s) => s.dir);
-}
-
-/**
- * Nearest-rank p95 of a numeric array. Returns `0` for an empty input.
- *
- * The pool is sorted ascending in-place on a defensive copy and the
- * value at index `ceil(0.95 * n) - 1` (0-based) is returned. No
- * interpolation — keeps fixture tests deterministic.
- *
- * @param {readonly number[]} values
- * @returns {number}
- */
-export function nearestRankP95(values) {
-  if (!Array.isArray(values) || values.length === 0) return 0;
-  const sorted = [...values].sort((a, b) => a - b);
-  const idx = Math.ceil(0.95 * sorted.length) - 1;
-  return sorted[Math.max(0, Math.min(sorted.length - 1, idx))];
-}
-
-/**
- * Detect Epic-scope hotspots. Returns one `kind: 'hotspot'` SignalEvent
- * per `targetHash` whose cross-Story `totalEdits` strictly exceeds
- * `p95(pool) * multiplier`, where `pool` is the set of `totalEdits`
- * values for hashes appearing in ≥ 2 Stories.
- *
- * Pure — emission to disk is the caller's responsibility (use
- * `appendEpicSignal` since the signal is Epic-scope).
- *
- * @param {object} args
- * @param {number} args.epicId — positive integer Epic ID.
- * @param {number} args.multiplier — positive number; p95 multiplier.
- * @param {string} [args.tempRoot] — override `temp/` root (mostly for
- *   tests that point at a synthetic fixture tree).
- * @param {() => string} [args.nowFn] — optional clock seam returning the
- *   ISO-8601 `ts` stamped onto every emitted SignalEvent. Defaults to
- *   `() => new Date().toISOString()`. Inject a fixed-return function in
- *   tests to make the emitted `ts` deterministic. MUST, when provided, be
- *   a function.
- * @returns {Promise<object[]>} array of hotspot SignalEvents conforming
- *   to `.agents/schemas/signal-event.schema.json`'s envelope. Emitted
- *   `details` payload: `{ targetHash, totalEdits, storiesAffected,
- *   p95Threshold, multiplier }`.
- */
-export async function detectHotspot(args) {
-  // Hotspot shares only the args-shape, nowFn, and epicId guards with the
-  // Story-scoped detectors — it has no tracesPath/storyId/taskId/threshold.
-  // Gate those three off and validate multiplier/tempRoot (hotspot-specific)
-  // inline below.
-  const { epicId, nowFn } = validateDetectorArgs(args, {
-    fnName: 'detectHotspot',
-    requireTracesPath: false,
-    requireStoryId: false,
-    requireThreshold: false,
-  });
-  const { multiplier, tempRoot } = args;
-
-  if (!isPositiveNumber(multiplier)) {
-    throw new RangeError(
-      `detectHotspot: multiplier must be a positive number (got ${multiplier})`,
-    );
-  }
-  if (
-    tempRoot != null &&
-    (typeof tempRoot !== 'string' || tempRoot.length === 0)
-  ) {
-    throw new TypeError(
-      `detectHotspot: tempRoot, when provided, must be a non-empty string (got ${tempRoot})`,
-    );
-  }
-
-  // Resolve the Epic temp dir. When the caller supplies an explicit
-  // `tempRoot`, splice it into the `{ project: { paths: { tempRoot } } }`
-  // shape that `epicTempDir` understands without forcing a config load.
-  const epicDir = tempRoot
-    ? epicTempDir(epicId, { project: { paths: { tempRoot } } })
-    : epicTempDir(epicId);
-
-  const storyDirs = await listStoryDirs(epicDir);
-  if (storyDirs.length === 0) return [];
-
-  // Per-Story edit-count maps, then aggregate per-hash totals plus the
-  // count of distinct Stories each hash was seen in.
-  const totals = new Map(); // hash -> totalEdits across Stories
-  const storyHits = new Map(); // hash -> count of distinct Stories
-
-  for (const storyDir of storyDirs) {
-    const tracesPath = path.join(storyDir, 'traces.ndjson');
-    const perStory = await tallyEditsByTarget(tracesPath);
-    for (const [hash, count] of perStory) {
-      totals.set(hash, (totals.get(hash) ?? 0) + count);
-      storyHits.set(hash, (storyHits.get(hash) ?? 0) + 1);
-    }
-  }
-
-  // Cross-Story-only pool: keep hashes seen in ≥ 2 Stories. Single-Story
-  // hashes never qualify as hotspots regardless of their absolute count.
-  const crossStoryHashes = [];
-  for (const [hash, hits] of storyHits) {
-    if (hits >= 2) crossStoryHashes.push(hash);
-  }
-
-  if (crossStoryHashes.length === 0) return [];
-
-  const pool = crossStoryHashes.map((h) => totals.get(h));
-  const p95 = nearestRankP95(pool);
-  const threshold = p95 * multiplier;
-
-  // Sort offenders by hash ascending for stable emission order.
-  const offenders = crossStoryHashes
-    .filter((h) => totals.get(h) > threshold)
-    .sort();
-
-  const ts = nowFn();
-  return offenders.map((targetHash) => ({
-    ts,
-    kind: 'hotspot',
-    source: { tool: 'hotspot-detector' },
-    epicId,
-    details: {
-      targetHash,
-      totalEdits: totals.get(targetHash),
-      storiesAffected: storyHits.get(targetHash),
-      p95Threshold: threshold,
-      multiplier,
-    },
-  }));
-}