mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/dead-exports-knip.js

@@ -0,0 +1,105 @@
+/**
+ * dead-exports-knip.js — the knip driver behind the dead-export ratchet.
+ *
+ * Owns everything about talking to knip and normalising what comes back:
+ * spawning it, reading a pre-captured report, and flattening its report into
+ * `{ file, symbol }` rows. `check-dead-exports.js` stays a thin CLI over this.
+ *
+ * @module lib/dead-exports-knip
+ */
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import process from 'node:process';
+
+/**
+ * Spawn `npx knip --reporter json --no-progress` and return the parsed
+ * envelope. Never throws — the caller logs the error and treats current rows as
+ * empty, which surfaces every baseline row as "removed": loud, but safe.
+ *
+ * `production` adds knip's `--production` flag, which restricts analysis to
+ * entry/project patterns carrying the `!` suffix in `knip.json`. The test globs
+ * deliberately lack that suffix, so production mode drops them as entry points
+ * and an export reachable only from a test reads as dead. Without those
+ * suffixes production mode has no entry patterns at all and reports nothing —
+ * `knip.json` and this flag are a matched pair.
+ *
+ * Exported as a hook so tests can stub the spawn without a working knip
+ * workspace.
+ *
+ * @param {{ cwd?: string, spawn?: typeof spawnSync, production?: boolean }} [opts]
+ * @returns {{ ok: true, envelope: unknown } | { ok: false, error: string }}
+ */
+export function runKnip({
+  cwd = process.cwd(),
+  spawn = spawnSync,
+  production = false,
+} = {}) {
+  const args = ['knip', '--reporter', 'json', '--no-progress'];
+  if (production) args.push('--production');
+  const result = spawn(process.platform === 'win32' ? 'npx.cmd' : 'npx', args, {
+    cwd,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf-8',
+    shell: process.platform === 'win32',
+  });
+  if (result.error) {
+    return { ok: false, error: `spawn failed: ${result.error.message}` };
+  }
+  const stdout = typeof result.stdout === 'string' ? result.stdout : '';
+  if (stdout.trim().length === 0) {
+    return { ok: false, error: 'knip produced empty stdout' };
+  }
+  try {
+    return { ok: true, envelope: JSON.parse(stdout) };
+  } catch (err) {
+    return {
+      ok: false,
+      error: `knip JSON parse failed: ${err?.message ?? err}`,
+    };
+  }
+}
+
+/**
+ * Read a pre-captured knip JSON envelope from disk (the `--knip-output` test
+ * seam). Returns the parsed envelope or `null` on failure.
+ *
+ * @param {string} filePath
+ * @returns {unknown}
+ */
+export function readKnipOutput(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Flatten knip's `--reporter json` output into `{ file, symbol }` rows. Knip
+ * emits `{ issues: [{ file, exports: [{ name, ... }], ... }, ...] }`. Only
+ * `exports` rows are mapped — the ratchet ignores file-, dependency- and
+ * duplicate-level issues, which knip surfaces under separate `rules` keys.
+ *
+ * @param {unknown} knipEnvelope The parsed knip JSON report.
+ * @returns {Array<{ file: string, symbol: string }>}
+ */
+export function extractRowsFromKnip(knipEnvelope) {
+  const rows = [];
+  if (!knipEnvelope || typeof knipEnvelope !== 'object') return rows;
+  const issues = Array.isArray(knipEnvelope.issues) ? knipEnvelope.issues : [];
+  for (const issue of issues) {
+    const file = issue?.file;
+    if (typeof file !== 'string' || file.length === 0) continue;
+    const exports_ = Array.isArray(issue.exports) ? issue.exports : [];
+    for (const e of exports_) {
+      const symbol =
+        (e && typeof e.name === 'string' && e.name) ||
+        (e && typeof e.symbol === 'string' && e.symbol) ||
+        null;
+      if (!symbol) continue;
+      rows.push({ file, symbol });
+    }
+  }
+  return rows;
+}

package/.agents/scripts/lib/dead-exports-mode.js

@@ -0,0 +1,51 @@
+/**
+ * dead-exports-mode.js — the two passes of the dead-export ratchet.
+ *
+ * The gate runs twice with different reachability assumptions, and each pass
+ * needs a matched triple: which knip invocation to make, which baseline to
+ * ratchet against, and how to label its output. Resolving that triple in one
+ * place keeps the three from drifting apart — a pass that ran production knip
+ * against the default baseline would report every test-only export as newly
+ * dead and fail the build for no reason.
+ *
+ * - **default** — `tests/**` are knip entry points, so an export imported only
+ *   by a test reads as used. This is the historical gate.
+ * - **production** — knip's `--production` drops the test entries, so an export
+ *   no production code reaches reads as dead. Depends on the `!` pattern
+ *   suffixes in `knip.json`; without them production mode has no entry points
+ *   and silently reports nothing.
+ *
+ * The two ratchet against separate baselines on purpose. This repo sanctions
+ * exporting purely for a test (`.agents/rules/test-seams.md`), so the
+ * production row set is large and mostly intentional; merging it into the
+ * default baseline would destroy that baseline's meaning.
+ *
+ * @module lib/dead-exports-mode
+ */
+
+import path from 'node:path';
+
+/** Baseline for the default pass (test entry points included). */
+const DEFAULT_BASELINE = path.join('baselines', 'dead-exports.json');
+
+/** Baseline for the `--production` pass (test-only-importer discount). */
+const PRODUCTION_BASELINE = path.join(
+  'baselines',
+  'dead-exports-production.json',
+);
+
+/**
+ * Resolve the baseline / label / mode-tag triple for a pass.
+ *
+ * @param {boolean} production
+ * @returns {{ mode: 'production'|'default', label: string, baseline: string }}
+ */
+export function resolveDeadExportsMode(production) {
+  return production
+    ? {
+        mode: 'production',
+        label: 'dead-exports:production',
+        baseline: PRODUCTION_BASELINE,
+      }
+    : { mode: 'default', label: 'dead-exports', baseline: DEFAULT_BASELINE };
+}

package/.agents/scripts/lib/dependency-parser.js

@@ -2,8 +2,9 @@
  * dependency-parser.js — Shared Dependency & Metadata Parsing Utilities
  *
  * Canonical implementation of dependency-related regex parsing and
- * ticket metadata extraction. Eliminates duplicated implementations
- * across dispatcher.js, verify-prereqs.js, and providers/github.js.
+ * ticket metadata extraction, shared by the ticketing provider and the
+ * orchestration layer (e.g. providers/github/tickets.js,
+ * lib/story-adjacency.js, lib/branch-name-guard.js).
  */
 
 /**

package/.agents/scripts/lib/doc-tiers.js

@@ -7,8 +7,8 @@
  *
  *   - `alwaysLoaded`  — `CLAUDE.md` plus the transitive closure of its
  *                       `@`-import references (`@AGENTS.md`,
- *                       `@.agents/instructions.md`, the persona, the always-on
- *                       rules, …). This is the context every session re-pays
+ *                       `@.agents/instructions.md`, the always-on rules, …).
+ *                       This is the context every session re-pays
  *                       on every subagent spawn (instructions.md § 4), so it is
  *                       the primary budget the context-budget ratchet gates.
  *   - `mandatoryRead` — the resolved `project.docsContextFiles` set (prefixed

package/.agents/scripts/lib/duplicate-search.js

@@ -1,23 +1,36 @@
 /**
- * duplicate-search.js — Cross-Epic Duplicate Detection
+ * duplicate-search.js — Cross-Story Duplicate Detection
  *
- * Used by `/plan` Phase 2 (s-plan-ideation) to surface open Epics
- * whose scope overlaps with a sharpened one-pager before a new Epic is
- * created. Returns ranked candidates with an overlap score and URL so
- * the host LLM can pause for HITL confirmation.
+ * Used by `/plan` to surface open Stories whose scope overlaps with a
+ * seed / seed-file / tickets corpus before new Stories are created.
+ * Returns ranked candidates with an overlap score and URL so the host
+ * LLM can pause for HITL confirmation.
  *
  * Design notes:
- *  - The provider abstraction (`ITicketingProvider#getEpics`) is the
- *    only I/O surface; the scoring routine is pure and trivially
- *    testable in isolation.
- *  - Scoring is intentionally simple (token Jaccard over title +
- *    structured one-pager sections). It is a triage signal, not a
- *    semantic-search replacement.
- *  - Provider errors propagate verbatim — the caller is responsible
- *    for translating them into a friction comment or operator-visible
- *    failure.
+ *  - Prefer `provider.searchIssues` to narrow open Stories server-side
+ *    (`label:"type::story" state:open` + top seed tokens), capped at
+ *    ~100 hits, then rank that set. Fall back to `listIssuesByLabel`
+ *    when search errors, is unavailable, or returns **nothing** (same
+ *    try/catch pattern as `TicketGateway.getTickets`).
+ *  - The narrowing query is deliberately weak (Story #4541). GitHub ANDs
+ *    free-text terms, so the former 8-token query demanded that a candidate
+ *    contain all eight of a multi-sentence seed's longest words — which no
+ *    real Story does. Gate #1 duplicate triage therefore reported "no
+ *    candidates" on every realistic seed while looking perfectly healthy.
+ *    Search is now a cheap best-case narrowing over a handful of tokens; an
+ *    empty result is treated as "search did not help", not "no duplicates",
+ *    and falls through to the label listing whose Jaccard ranker has real
+ *    recall.
+ *  - Scoring is intentionally simple (token Jaccard over title + body).
+ *    It is a triage signal, not a semantic-search replacement.
+ *  - Provider errors on the list fallback propagate verbatim — the
+ *    caller is responsible for translating them into a friction comment
+ *    or operator-visible failure.
  */
 
+import { Logger } from './Logger.js';
+import { TYPE_LABELS } from './label-constants.js';
+
 const STOPWORDS = new Set([
   'a',
   'an',
@@ -75,6 +88,19 @@ const STOPWORDS = new Set([
 
 const DEFAULT_MIN_SCORE = 0.15;
 const DEFAULT_MAX_RESULTS = 5;
+/**
+ * How many seed tokens to pass as free-text search terms.
+ *
+ * GitHub ANDs these, so the cap is a precision/recall dial pointing the
+ * wrong way: every extra token shrinks the candidate set. Three is a
+ * best-case narrowing that can plausibly hit on a focused seed; anything
+ * beyond that reliably matched nothing on a multi-sentence one (Story
+ * #4541). Recall does not rest on this number — an empty result falls back
+ * to label-listing plus client-side ranking.
+ */
+const DEFAULT_SEARCH_TOKEN_CAP = 3;
+/** Hard cap on search hits ranked client-side (~one Search API page). */
+const SEARCH_RESULT_CAP = 100;
 
 /**
  * Tokenize freeform text into a deduplicated set of meaningful words.
@@ -92,6 +118,33 @@ export function tokenize(text) {
   return new Set(tokens);
 }
 
+/**
+ * Pick the highest-signal seed tokens for a Search API free-text query.
+ * Longer tokens first (specificity proxy), then alphabetical for stability.
+ *
+ * @param {string} seed
+ * @param {number} [maxTokens]
+ * @returns {string[]}
+ */
+export function pickSearchTokens(seed, maxTokens = DEFAULT_SEARCH_TOKEN_CAP) {
+  const tokens = tokenize(seed);
+  return [...tokens]
+    .sort((a, b) => b.length - a.length || a.localeCompare(b))
+    .slice(0, maxTokens);
+}
+
+/**
+ * Build the `/search/issues` query for open Stories overlapping a seed.
+ * Repo scoping is left to `provider.searchIssues`.
+ *
+ * @param {string} seed
+ * @returns {string}
+ */
+export function buildOpenStorySearchQuery(seed) {
+  const tokens = pickSearchTokens(seed);
+  return [`label:"${TYPE_LABELS.STORY}"`, 'state:open', ...tokens].join(' ');
+}
+
 /**
  * Compute the Jaccard overlap between two token sets.
  *
@@ -108,14 +161,14 @@ export function overlapScore(a, b) {
 }
 
 /**
- * Build the Epic URL for an issue id. The candidate exposes the URL so
- * the HITL pause can render clickable links without a second round-trip.
+ * Build the issue URL for an id. The candidate exposes the URL so the
+ * HITL pause can render clickable links without a second round-trip.
  *
  * @param {number|string} id
  * @param {{ owner?: string, repo?: string }} [opts]
  * @returns {string}
  */
-function buildEpicUrl(id, opts = {}) {
+function buildIssueUrl(id, opts = {}) {
   const owner = opts.owner || process.env.GITHUB_OWNER;
   const repo = opts.repo || process.env.GITHUB_REPO;
   if (owner && repo) {
@@ -125,54 +178,72 @@ function buildEpicUrl(id, opts = {}) {
 }
 
 /**
- * Find open Epics whose title + body overlap with the supplied
- * one-pager above a configurable threshold.
+ * Normalize a provider issue (list or search hit) into the ranking shape.
+ *
+ * @param {object} issue
+ * @returns {{ id: number, title: string, body: string, url?: string }}
+ */
+function normalizeIssue(issue) {
+  return {
+    id: Number(issue.number ?? issue.id),
+    title: issue.title ?? '',
+    body: issue.body ?? '',
+    url: issue.html_url ?? issue.url ?? undefined,
+  };
+}
+
+/**
+ * Rank a pre-fetched open-Story list against a seed corpus.
+ * Pure helper shared by the provider-backed search and tests.
  *
  * @param {{
- *   onePager: string,
- *   provider: import('./ITicketingProvider.js').ITicketingProvider,
+ *   seed: string,
+ *   openStories: Array<{ id:number, title?:string, body?:string, url?:string }>,
  *   minScore?: number,
  *   maxResults?: number,
  *   owner?: string,
  *   repo?: string,
+ *   excludeIds?: Iterable<number|string>,
  * }} args
- * @returns {Promise<Array<{ id: number, title: string, score: number, url: string }>>}
+ * @returns {Array<{ id: number, title: string, score: number, url: string }>}
  */
-export async function findSimilarOpenEpics({
-  onePager,
-  provider,
+export function rankOpenStoryDuplicates({
+  seed,
+  openStories,
   minScore = DEFAULT_MIN_SCORE,
   maxResults = DEFAULT_MAX_RESULTS,
   owner,
   repo,
+  excludeIds = [],
 }) {
-  if (!onePager || typeof onePager !== 'string') {
-    throw new Error(
-      'findSimilarOpenEpics: onePager must be a non-empty string',
-    );
+  if (!seed || typeof seed !== 'string') {
+    throw new Error('rankOpenStoryDuplicates: seed must be a non-empty string');
   }
-  if (!provider || typeof provider.getEpics !== 'function') {
-    throw new Error('findSimilarOpenEpics: provider must implement getEpics()');
+  if (!Array.isArray(openStories)) {
+    throw new Error('rankOpenStoryDuplicates: openStories must be an array');
   }
 
-  const seedTokens = tokenize(onePager);
+  const seedTokens = tokenize(seed);
   if (seedTokens.size === 0) return [];
 
-  // Provider errors propagate verbatim — caller decides how to surface.
-  const epics = await provider.getEpics({ state: 'open' });
-  if (!Array.isArray(epics) || epics.length === 0) return [];
+  const excluded = new Set(
+    [...excludeIds].map((id) => Number(id)).filter((n) => Number.isFinite(n)),
+  );
 
   const ranked = [];
-  for (const epic of epics) {
-    const corpus = `${epic.title || ''}\n${epic.body || ''}`;
+  for (const story of openStories) {
+    const id = Number(story?.id ?? story?.number);
+    if (!Number.isFinite(id) || excluded.has(id)) continue;
+    const title = story.title || '';
+    const corpus = `${title}\n${story.body || ''}`;
     const candidateTokens = tokenize(corpus);
     const score = overlapScore(seedTokens, candidateTokens);
     if (score >= minScore) {
       ranked.push({
-        id: epic.id,
-        title: epic.title,
+        id,
+        title,
         score: Number(score.toFixed(4)),
-        url: buildEpicUrl(epic.id, { owner, repo }),
+        url: story.url || buildIssueUrl(id, { owner, repo }),
       });
     }
   }
@@ -181,9 +252,139 @@ export async function findSimilarOpenEpics({
   return ranked.slice(0, maxResults);
 }
 
+/**
+ * Server-narrowed open-Story fetch via `/search/issues`.
+ *
+ * @param {object} provider
+ * @param {string} seed
+ * @returns {Promise<Array<{ id:number, title:string, body:string, url?:string }>>}
+ */
+async function fetchOpenStoriesViaSearch(provider, seed) {
+  const query = buildOpenStorySearchQuery(seed);
+  const hits = await provider.searchIssues({ query });
+  if (!Array.isArray(hits)) return [];
+  return hits.slice(0, SEARCH_RESULT_CAP).map(normalizeIssue);
+}
+
+/**
+ * Full open-Story backlog via label listing (fallback path).
+ *
+ * @param {object} provider
+ * @returns {Promise<Array<{ id:number, title:string, body:string, url?:string }>>}
+ */
+async function fetchOpenStoriesViaList(provider) {
+  if (typeof provider.listIssuesByLabel !== 'function') {
+    throw new Error(
+      'findSimilarOpenStories: provider must implement listIssuesByLabel()',
+    );
+  }
+  const issues = await provider.listIssuesByLabel({
+    state: 'open',
+    labels: TYPE_LABELS.STORY,
+  });
+  if (!Array.isArray(issues)) return [];
+  return issues.map(normalizeIssue);
+}
+
+/**
+ * Fetch open-Story candidates: try Search API narrowing first, fall back to
+ * `listIssuesByLabel` when search errors, is unavailable, or **returns no
+ * hits**.
+ *
+ * The empty-result fallback is the load-bearing one (Story #4541). The
+ * narrowing query ANDs seed tokens, so on any real multi-sentence seed it
+ * matches nothing — and treating that as an authoritative "no duplicates
+ * exist" is what made Gate #1 triage report a clean bill of health while
+ * never actually looking. An empty search is evidence about the *query*, not
+ * about the backlog.
+ *
+ * @param {object} provider
+ * @param {string} seed
+ * @returns {Promise<Array<{ id:number, title:string, body:string, url?:string }>>}
+ */
+async function fetchOpenStoryCandidates(provider, seed) {
+  if (!provider || typeof provider !== 'object') {
+    throw new Error('findSimilarOpenStories: provider is required');
+  }
+
+  const hasSearch = typeof provider.searchIssues === 'function';
+  const hasList = typeof provider.listIssuesByLabel === 'function';
+  if (!hasSearch && !hasList) {
+    throw new Error(
+      'findSimilarOpenStories: provider must implement searchIssues() or listIssuesByLabel()',
+    );
+  }
+
+  if (hasSearch) {
+    try {
+      const hits = await fetchOpenStoriesViaSearch(provider, seed);
+      if (hits.length > 0 || !hasList) return hits;
+      Logger.info(
+        '[duplicate-search] narrowed search matched no open Stories; ' +
+          'falling back to listIssuesByLabel + client-side ranking',
+      );
+    } catch (err) {
+      if (!hasList) throw err;
+      const msg = typeof err?.message === 'string' ? err.message : String(err);
+      Logger.warn(
+        `[duplicate-search] search-based candidate fetch failed (${msg}); ` +
+          'falling back to listIssuesByLabel',
+      );
+    }
+  }
+
+  return fetchOpenStoriesViaList(provider);
+}
+
+/**
+ * Find open Stories whose title + body overlap with the supplied seed
+ * above a configurable threshold.
+ *
+ * @param {{
+ *   seed: string,
+ *   provider: import('./ITicketingProvider.js').ITicketingProvider,
+ *   minScore?: number,
+ *   maxResults?: number,
+ *   owner?: string,
+ *   repo?: string,
+ *   excludeIds?: Iterable<number|string>,
+ * }} args
+ * @returns {Promise<Array<{ id: number, title: string, score: number, url: string }>>}
+ */
+export async function findSimilarOpenStories({
+  seed,
+  provider,
+  minScore = DEFAULT_MIN_SCORE,
+  maxResults = DEFAULT_MAX_RESULTS,
+  owner,
+  repo,
+  excludeIds = [],
+}) {
+  if (!seed || typeof seed !== 'string') {
+    throw new Error('findSimilarOpenStories: seed must be a non-empty string');
+  }
+
+  // Avoid a network round-trip when the seed cannot produce a score.
+  if (tokenize(seed).size === 0) return [];
+
+  const openStories = await fetchOpenStoryCandidates(provider, seed);
+  return rankOpenStoryDuplicates({
+    seed,
+    openStories,
+    minScore,
+    maxResults,
+    owner,
+    repo,
+    excludeIds,
+  });
+}
+
 export const __test = {
   STOPWORDS,
   DEFAULT_MIN_SCORE,
   DEFAULT_MAX_RESULTS,
-  buildEpicUrl,
+  DEFAULT_SEARCH_TOKEN_CAP,
+  SEARCH_RESULT_CAP,
+  buildIssueUrl,
+  buildEpicUrl: buildIssueUrl,
 };

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

@@ -30,8 +30,8 @@
  * failure path is captured in `errors[]`.
  */
 
+import { DEFAULT_FRAMEWORK_REPO } from '../github/framework-repo.js';
 import { META_LABELS } from '../label-constants.js';
-import { DEFAULT_FRAMEWORK_REPO } from '../orchestration/retro/phases/gather-signals.js';
 import {
   contentFingerprint,
   DEFAULT_MAX_FILINGS_PER_RUN,

package/.agents/scripts/lib/findings/promote-finding.js

@@ -6,7 +6,7 @@
  * session's ledger items (see `.agents/schemas/qa-ledger.schema.json` and
  * `lib/qa/qa-session.js`), the still-untriaged backlog is clustered and each
  * cluster is promoted to a follow-up ticket — a single Story (via `/plan`)
- * for a tight, one-deliverable cluster, or an Epic (via `/plan --idea`) for
+ * for a tight, one-deliverable cluster, or a multi-Story plan-seed (via `/plan --seed`) for
  * a broad cluster that spans multiple coverage surfaces. Each contributing
  * ledger item then has the resulting `routedTo` issue link written back onto it
  * so a resume run sees the item as filed rather than re-promoting it.
@@ -32,15 +32,24 @@ import { highestSeverity as highestSeverityOf } from './severity.js';
 /** Triaged dispositions, mirrored from the `disposition` enum in the schema. */
 const TRIAGED_DISPOSITIONS = Object.freeze(['file', 'defer', 'dismiss']);
 
-/** The two promotion targets a cluster routes to. */
+/**
+ * The two promotion targets a cluster routes to.
+ *
+ * `PLAN_SEED` promotes a broad cluster by seeding a multi-Story `/plan`
+ * run (`/plan --seed`). Its persisted wire token is the legacy string
+ * `'epic'`: archived qa-ledger records (and the distributed
+ * `qa-ledger.schema.json` `routedTo.kind` enum) still carry `'epic'`, so
+ * the value is kept read-compatible while the write-side constant name is
+ * modernised.
+ */
 export const PROMOTION_TARGETS = Object.freeze({
   STORY: 'story',
-  EPIC: 'epic',
+  PLAN_SEED: 'epic',
 });
 
 /**
  * A cluster of more than this many distinct coverage surfaces is broad enough
- * to warrant an Epic (`/plan --idea`) rather than a single Story
+ * to warrant a plan-seed (`/plan --seed`) rather than a single Story
  * (`/plan`). One or two surfaces is a tight, single-deliverable cluster.
  */
 const EPIC_COVERAGE_THRESHOLD = 2;
@@ -70,7 +79,7 @@ export function isPromotable(item) {
  * Stable cluster key for a ledger item: its `class`. Items sharing a class
  * describe the same kind of signal (a product bug, a tooling-DX gap, …) and
  * merge into one follow-up ticket. A class whose items span many distinct
- * coverage surfaces is broad enough to promote to an Epic (see
+ * coverage surfaces is broad enough to promote to a plan-seed (see
  * {@link targetForCluster}); a class confined to one or two surfaces is a
  * single-deliverable Story. Coverage is therefore a *secondary* signal that
  * sizes the cluster rather than splitting it.
@@ -159,7 +168,7 @@ export function clusterLedgerItems(items) {
 /**
  * Decide a cluster's promotion target. A cluster that spans more than
  * {@link EPIC_COVERAGE_THRESHOLD} distinct coverage surfaces is broad enough to
- * warrant an Epic (`/plan --idea`); otherwise it is a single-deliverable
+ * warrant a plan-seed (`/plan --seed`); otherwise it is a single-deliverable
  * Story (`/plan`).
  *
  * @param {{ coverages: string[] }} cluster
@@ -170,7 +179,7 @@ export function targetForCluster(cluster) {
     ? cluster.coverages.length
     : 0;
   return surfaces > EPIC_COVERAGE_THRESHOLD
-    ? PROMOTION_TARGETS.EPIC
+    ? PROMOTION_TARGETS.PLAN_SEED
     : PROMOTION_TARGETS.STORY;
 }
 
@@ -224,7 +233,7 @@ function routedToLink(issue, kind) {
 }
 
 /**
- * Promote the clustered untriaged ledger items into Stories / Epics via the
+ * Promote the clustered untriaged ledger items into Stories / plan-seeds via the
  * shared findings/route logic, then write the resulting `routedTo` issue link
  * back onto each contributing ledger item.
  *
@@ -233,7 +242,7 @@ function routedToLink(issue, kind) {
  *      shared `routeFinding` against existing Issues (via the injected search
  *      port). This dedups against work already filed.
  *   2. On a `new` decision, open the follow-up ticket through the injected
- *      `createStory` (`/plan`) or `createEpic` (`/plan --idea`) port,
+ *      `createStory` (`/plan`) or `createPlanSeed` (`/plan --seed`) port,
  *      chosen by {@link targetForCluster}. On any other decision, link back to
  *      the matched Issue rather than creating a duplicate.
  *   3. Stamp the resolved `routedTo` link onto every contributing ledger item
@@ -251,8 +260,8 @@ function routedToLink(issue, kind) {
  *   Optional semantic candidate search, forwarded to `routeFinding`.
  * @param {(cluster: object) => Promise<{ number: number, url?: string }>} ports.createStory
  *   Opens a single Story (`/plan`) for a tight cluster.
- * @param {(cluster: object) => Promise<{ number: number, url?: string }>} ports.createEpic
- *   Opens an Epic (`/plan --idea`) for a broad cluster.
+ * @param {(cluster: object) => Promise<{ number: number, url?: string }>} ports.createPlanSeed
+ *   Opens a plan-seed (`/plan --seed`) run for a broad cluster.
  * @returns {Promise<{
  *   promotions: Array<{
  *     clusterKey: string,
@@ -268,7 +277,7 @@ function routedToLink(issue, kind) {
  * @throws {Error} when a required create port is missing for a routed cluster.
  */
 export async function promoteFindings(ledgerItems, ports = {}) {
-  const { searchIssues, searchCandidates, createStory, createEpic } = ports;
+  const { searchIssues, searchCandidates, createStory, createPlanSeed } = ports;
   if (
     typeof searchCandidates !== 'function' &&
     typeof searchIssues !== 'function'
@@ -294,10 +303,10 @@ export async function promoteFindings(ledgerItems, ports = {}) {
 
     if (route.decision === 'new') {
       const createPort =
-        target === PROMOTION_TARGETS.EPIC ? createEpic : createStory;
+        target === PROMOTION_TARGETS.PLAN_SEED ? createPlanSeed : createStory;
       if (typeof createPort !== 'function') {
         throw new Error(
-          `promoteFindings: a ${target === PROMOTION_TARGETS.EPIC ? 'createEpic' : 'createStory'} port is required to promote cluster ${cluster.key}`,
+          `promoteFindings: a ${target === PROMOTION_TARGETS.PLAN_SEED ? 'createPlanSeed' : 'createStory'} port is required to promote cluster ${cluster.key}`,
         );
       }
       issue = await createPort(cluster);