mandrel 2.0.0 → 2.1.0

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

@@ -82,27 +82,13 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   'epic-run-progress',
   'epic-plan-state',
   'parked-follow-ons',
-  // Story #566 — per-phase wall-clock summary posted by single-story-close.js
-  // and consumed by analyze-execution / perf tooling to surface median /
-  // p95 phase timings across completed stories.
+  // Story #566 — per-phase wall-clock summary posted by single-story-close.js.
   'phase-timings',
   // Story #831 — story-init upserts a `story-init` comment that
   // surfaces `dependenciesInstalled` (and the underlying installStatus) so
   // downstream workflow steps don't have to infer install state from
   // node_modules presence.
   'story-init',
-  // Story #908 — /deliver upserts a `story-run-progress` snapshot
-  // on each Story per Task transition. The /deliver aggregator and
-  // `analyze-execution.js` both read this comment to derive
-  // Story-level state without re-fetching ticket labels.
-  'story-run-progress',
-  // Story #1123 — analyze-execution.js upserts perf summaries at close
-  // time. Story-mode posts `story-perf-summary` on each Story; Epic-mode
-  // posts `epic-perf-report` on the Epic. Both replace the legacy
-  // per-Task `friction` fan-out and the standalone `phase-timings`
-  // surface (Epic #1030).
-  'story-perf-summary',
-  'epic-perf-report',
   // Story #2128 — Phase 6 Epic Clarity Gate (CLI retired). Historical
   // `clarity-gate-update` comments may still exist on older tickets.
   'clarity-gate-update',
@@ -151,19 +137,13 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   // the documented remediation actually executable
   // (assertValidStructuredCommentType would otherwise throw).
   'wave-stall',
-  // Story #3873 (Epic #3865) — `plan-persist.js` upserts a `risk-verdict`
-  // comment on the Epic at persist time, recording the planner-authored,
-  // schema-validated risk verdict and the planningRisk envelope derived
-  // from it (`deriveRiskEnvelope`). One entry per Epic; re-plans upsert in
-  // place. Schema: `.agents/schemas/risk-verdict.schema.json`.
-  'risk-verdict',
-  // Story #4019 — `epic-plan-lease-guard.js` upserts a `plan-lease`
-  // comment on the Epic at lease-acquire time, recording the claiming
-  // operator and the claim timestamp. `/plan` emits no
-  // `story.heartbeat`, so this claim-time is the liveness signal that
-  // makes the documented `--steal` contract decidable: a foreign claim
-  // older than the lease TTL is reclaimed automatically; a fresh one
-  // refuses with the claim age. One entry per Epic; re-acquires upsert
+  // Story #4019 — the plan-tier lease guard upserts a `plan-lease`
+  // comment at lease-acquire time, recording the claiming operator and the
+  // claim timestamp. Nothing emits a per-run liveness beat, so this
+  // claim-time is the only age signal a reader has when reasoning about the
+  // documented `--steal` contract. The guard itself fails closed regardless
+  // (it anchors liveness to `now`), so a stranded claim is cleared with
+  // `--steal`, not by TTL expiry. One entry per ticket; re-acquires upsert
   // in place.
   'plan-lease',
   // Story #4415 (Epic #4406) — the feedback-loop graduators
@@ -183,6 +163,13 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   // v2 Stage 3 — flat Story persist checkpoint on every created Story
   // (replaces epic-plan-state for new plans). plan-summary stays primary-only.
   'story-plan-state',
+  // Story #4535 — `plan-persist.js` upserts a `superseded-by` comment on
+  // each `/plan --tickets` source issue at persist time, naming the single
+  // Story that claims it (plus any per-supersede note the plan authored),
+  // immediately before closing the issue as `not_planned`. Keying off this
+  // marker rather than a bare `postComment` is what makes a re-run
+  // non-double-commenting. One entry per source issue.
+  'superseded-by',
 ]);
 
 export const WAVE_TYPE_PATTERN = WAVE_MARKER_RE;
@@ -268,8 +255,8 @@ export function structuredCommentMarker(type, attrs = null) {
  * recent `findStructuredComment` / `upsertStructuredComment` call.
  * Story #1795 — every Epic run owns its process for the duration of
  * the run, so a single seed-then-reuse window saves one
- * `getTicketComments` per repeat upsert on the hot path (wave-level
- * `story-run-progress`, `wave-N-end`, etc).
+ * `getTicketComments` per repeat upsert on the hot path (`story-init`,
+ * `verification-results`, etc).
  *
  * Lifecycle:
  *   - First call to `findStructuredComment(provider, t, type, attrs)`
@@ -355,8 +342,8 @@ export function structuredCommentCacheKey(ticketId, type, attrs) {
  * array returned by the most recent `provider.getTicketComments(ticketId)`
  * call. Story #2465 — `findStructuredComment` is invoked back-to-back for
  * different `type` discriminators against the same ticket (e.g.
- * `story-run-progress` + `epic-run-progress` + a `friction` probe during
- * an Epic-close wave). Without this cache each lookup pays a full
+ * `story-init` + `verification-results` + a `friction` probe during a
+ * single close). Without this cache each lookup pays a full
  * pagination round-trip even when the prior call already fetched the
  * same comments. The structured-comment-id cache short-circuits *repeat*
  * lookups for the same `(type, attrs)` tuple but does not help across

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

@@ -37,6 +37,10 @@ import {
   eventSeverity,
   renderTransitionMessage,
 } from '../../notifications/notifier.js';
+import {
+  emitRuntimeFriction,
+  RUNTIME_FRICTION_CATEGORIES,
+} from '../../observability/runtime-friction.js';
 import { ColumnSync } from '../column-sync.js';
 import {
   ALL_STATES,
@@ -279,6 +283,46 @@ function dispatchTransitionNotification(args) {
   });
 }
 
+/**
+ * Emit a runtime-derived `friction` signal when a ticket parks at
+ * `agent::blocked` (Story #4578). No-op for every other target state.
+ *
+ * Why here: `agent::blocked` is the single runtime HITL pause point
+ * (`.agents/instructions.md` § 1.J), and this is its canonical mutator — so
+ * one hook catches every block regardless of which path drove it (the
+ * `merge.unlanded` and `merge.flip-failed` paths in
+ * `single-story-close/phases/confirm-merge.js`, the review-block path, an
+ * operator's `update-ticket-state.js`, a Story worker giving up). Before
+ * this, a block was only ever a *label* — it left no trace in the friction
+ * stream the retro reads, so a run could park a worker and still produce a
+ * zero-signal roll-up.
+ *
+ * This is also why the terminal-envelope hook deliberately skips `blocked`
+ * (see `frictionForTerminal`): the two would otherwise count one incident
+ * twice.
+ *
+ * Best-effort and awaited: `emitRuntimeFriction` swallows its own failures
+ * and resolves `false`, so this can neither throw nor block the transition.
+ * It is awaited rather than fire-and-forget because CLI entry points exit
+ * via `process.exit` as soon as `main` resolves (`cli-utils.runAsCli` with
+ * `propagateExitCode`), which would discard a still-pending append.
+ *
+ * @param {number} ticketId
+ * @param {string} newState
+ * @param {{ config?: object }} opts
+ * @returns {Promise<void>}
+ */
+async function emitBlockedFriction(ticketId, newState, opts) {
+  if (newState !== STATE_LABELS.BLOCKED) return;
+  await emitRuntimeFriction({
+    storyId: ticketId,
+    category: RUNTIME_FRICTION_CATEGORIES.STORY_BLOCKED,
+    tool: 'transitionTicketState',
+    details: { toState: newState },
+    config: opts?.config,
+  });
+}
+
 /**
  * Transitions a ticket's label to the new state.
  * Removes other agent:: state labels.
@@ -361,6 +405,10 @@ export async function transitionTicketState(
     _ticketSnapshot: ticketSnapshot,
   });
 
+  // Story #4578 — derive a friction signal from the block, at the point the
+  // runtime already knows. Best-effort; never blocks the transition.
+  await emitBlockedFriction(ticketId, newState, opts);
+
   // Story #2548 — mirror the new state onto the Projects v2 Status
   // column. Best-effort; never blocks the transition.
   // Story #3645 — thread the DIP seam so callers can inject a stub.
@@ -460,14 +508,25 @@ export async function toggleTasklistCheckbox(
 /**
  * Post a structured comment to a ticket.
  *
+ * Returns whatever the provider's `postComment` resolved to (Story #4543).
+ * Previously the result was swallowed, which made it impossible for a caller
+ * to reference the comment it had just written — the terminal envelope's
+ * `blocked.frictionCommentId` pointer needs exactly that, so an operator can
+ * be sent straight to the remediation instead of told to go find it. Callers
+ * that don't need the id simply ignore the return, so this is additive.
+ *
+ * The shape is provider-defined and may be `undefined` for providers that do
+ * not surface one; callers must treat the id as best-effort.
+ *
  * @param {import('../../ITicketingProvider.js').ITicketingProvider} provider
  * @param {number} ticketId
  * @param {'progress'|'friction'|'notification'} type
  * @param {string} payload
+ * @returns {Promise<unknown>} The provider's `postComment` result.
  */
 export async function postStructuredComment(provider, ticketId, type, payload) {
   assertValidStructuredCommentType(type);
-  await provider.postComment(ticketId, {
+  const posted = await provider.postComment(ticketId, {
     type,
     body: payload,
   });
@@ -475,4 +534,5 @@ export async function postStructuredComment(provider, ticketId, type, payload) {
   // `findStructuredComment` against this ticket re-fetches and sees the
   // freshly-posted comment.
   invalidateRawCommentsCache(provider, ticketId);
+  return posted;
 }

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

@@ -26,7 +26,6 @@
 export {
   __resetParentCascadeLocks,
   __setCascadeRetryDelays,
-  cascadeCompletion,
   logCascadePartialFailures,
 } from './ticketing/bulk.js';
 // Re-export the read surface.

package/.agents/scripts/lib/plan-phase-cleanup.js

@@ -1,9 +1,9 @@
 /**
  * plan-phase-cleanup.js — Post-phase temp-file cleanup for `/plan`.
  *
- * The spec and decompose phases write several Epic-scoped temp files under
- * the per-Epic tree (`temp/epic-<id>/planner-context.json`,
- * `temp/epic-<id>/techspec.md`, etc. — see `lib/config/temp-paths.js`). The
+ * The spec and decompose phases write several run-scoped temp files under
+ * the per-run tree (`temp/run-<id>/planner-context.json`,
+ * `temp/run-<id>/techspec.md`, etc. — see `lib/config/temp-paths.js`). The
  * workflow .md previously told the operator to `Remove-Item` those files by
  * name at the end of each phase, which rots: adding a new temp file in the
  * script required a synchronized markdown edit, and missed edits left
@@ -19,20 +19,20 @@
  * never sinks a successful phase.
  *
  * Migration note (Epic #1030 Story #1040): the legacy flat layout
- * (`temp/planner-context-epic-<id>.json` etc.) has been retired. The
- * resolver now delegates to `epicArtifactPath` from
- * `lib/config/temp-paths.js`, which yields `temp/epic-<id>/<basename>`
+ * (`temp/planner-context-for-<id>.json` etc.) has been retired. The
+ * resolver now delegates to `runArtifactPath` from
+ * `lib/config/temp-paths.js`, which yields `temp/run-<id>/<basename>`
  * under the configured `tempRoot`.
  */
 
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { epicArtifactPath } from './config/temp-paths.js';
+import { runArtifactPath } from './config/temp-paths.js';
 import { PROJECT_ROOT, resolveConfig } from './config-resolver.js';
 
 /**
- * Map of phase → artifact basenames (no path components). The per-Epic
- * directory prefix is supplied by `epicArtifactPath` at resolution time.
+ * Map of phase → artifact basenames (no path components). The per-run
+ * directory prefix is supplied by `runArtifactPath` at resolution time.
  */
 export const PHASE_TEMP_BASENAMES = Object.freeze({
   spec: Object.freeze([
@@ -45,15 +45,13 @@ export const PHASE_TEMP_BASENAMES = Object.freeze({
   // plan-phase artifact and deletes them ONLY at terminal success (after
   // the `agent::ready` flip), fixing the mid-pipeline deletion defect where
   // per-phase cleanup removed artifacts a `--force`/`--resume` re-persist
-  // was still entitled to reuse. `risk-verdict.json` joins the set here:
-  // the split-phase cleanup never owned it, which orphaned it in temp/.
+  // was still entitled to reuse.
   // `plan-metrics.json` stays deliberately excluded (PR1) — the ledger
   // must survive cleanup so the whole plan run is visible in one stream.
   persist: Object.freeze([
     'planner-context.json',
     'techspec.md',
     'acceptance-spec.md',
-    'risk-verdict.json',
     'decomposer-context.json',
     'tickets.json',
   ]),
@@ -84,8 +82,8 @@ export function resolvePhaseTempPaths(phase, epicId, repoRoot = PROJECT_ROOT) {
     config = undefined;
   }
   return basenames.map((basename) => {
-    const rel = epicArtifactPath(epicId, basename, config);
-    // `epicArtifactPath` yields a path under `tempRoot` (relative when
+    const rel = runArtifactPath(epicId, basename, config);
+    // `runArtifactPath` yields a path under `tempRoot` (relative when
     // tempRoot is itself relative — the framework default). Rebase
     // relative paths against `repoRoot` so callers always receive an
     // absolute path — matches the pre-migration contract that

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

@@ -2,310 +2,36 @@
  * planning-corpus.js — corpus-aware context for the standalone-Story
  * planning path (Story #4432).
  *
- * `/plan --seed` 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:
+ * `/plan --seed` drafts a standalone Story from the seed, the body
+ * template, and a title-only duplicate scan. This module assembles the
+ * 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 historical Epic list surface (`provider.getEpics`) returns a
- * list-scale payload with no `body`. 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.
+ *   2. `relevantSections` — always `[]`. This field previously carried
+ *      ranked Tech Spec excerpts mined from open Epics. v2.0.0 removed
+ *      the Epic tier, and the provider's Epic-list surface was reduced
+ *      to a `return []` stub, which made the entire ranking pipeline a
+ *      permanent no-op. The pipeline has been removed; the field is
+ *      retained so the envelope shape stays stable for its consumers.
  */
 
-import { overlapScore, tokenize } from './duplicate-search.js';
-import { Logger } from './Logger.js';
 import { buildDocsDigest } from './orchestration/docs-digest.js';
-import {
-  extractTicketSection,
-  hasTicketSection,
-} from './ticket-body-sections.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 — 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 (hasTicketSection(body, 'techSpec')) {
-    return {
-      kind: 'techSpec',
-      content: extractTicketSection(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,
-}) {
+export async function buildCorpusContext({ docsContextFiles, docsRoot }) {
   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 };
+  return { docsDigest, relevantSections: [] };
 }

package/.agents/scripts/lib/preflight-runner.js

@@ -52,8 +52,8 @@ const DEFAULT_LOGGER = {
  * flag, finding/fix routing, and pretty-print of the blocker table.
  *
  * @param {object} opts
- * @param {string} opts.scope          Consumer surface — `'epic-close'`,
- *   `'story-close'`, `'npm-test'`, etc.
+ * @param {string} opts.scope          Consumer surface — `'story-close'`,
+ *   `'npm-test'`, `'diagnose'`, etc.
  * @param {boolean} [opts.autoFix=true] Forwarded to `runChecks`. Defaults
  *   to `true` because every wiring call site at this Story's level wants
  *   auto-correction (the `retro` consumer that needs `autoFix:false` does

package/.agents/scripts/lib/qa/qa-context-hydrator.js

@@ -142,7 +142,7 @@ export async function verifySurfaceMap(surfaceMap, gitPort, baseRef) {
  * with no network when the ports are fakes.
  *
  * @param {{
- *   epicNumber: number,
+ *   ticketNumber: number,
  *   githubPort: GithubPort,
  *   gitPort: GitPort,
  *   surfaceMap?: SurfaceMapEntry[],
@@ -162,7 +162,7 @@ export async function verifySurfaceMap(surfaceMap, gitPort, baseRef) {
  */
 export async function hydrateQaContext(opts) {
   const {
-    epicNumber,
+    ticketNumber,
     githubPort,
     gitPort,
     surfaceMap = [],
@@ -172,9 +172,9 @@ export async function hydrateQaContext(opts) {
     fsImpl,
   } = opts ?? {};
 
-  if (!Number.isInteger(epicNumber)) {
+  if (!Number.isInteger(ticketNumber)) {
     throw new Error(
-      'hydrateQaContext: `epicNumber` is required and must be an integer',
+      'hydrateQaContext: `ticketNumber` is required and must be an integer',
     );
   }
   if (!githubPort || typeof githubPort.fetchIssue !== 'function') {
@@ -192,7 +192,7 @@ export async function hydrateQaContext(opts) {
     );
   }
 
-  const epicIssue = await githubPort.fetchIssue(epicNumber);
+  const epicIssue = await githubPort.fetchIssue(ticketNumber);
   const epic = {
     number: epicIssue.number,
     body: epicIssue.body ?? '',