mandrel 1.81.0 → 1.83.0

package/.agents/schemas/qa-finding.schema.json

@@ -1,133 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "QaFinding",
-  "description": "Structured `F#` finding emitted by the agent-driven QA harness (`.agents/workflows/qa-run.md`, Epic #3214). One object per genuine problem surfaced while sweeping a consumer's Gherkin scenarios through chrome-devtools MCP: a non-allowlisted console error, a failed/error-status network request, or a gross design-token violation. Findings are validated against this schema before they are bundled by likely root cause into operator-approved follow-up ticket drafts (the harness never files tickets autonomously). The shape mirrors the F# convergence in Tech Spec #3285 and is produced in its console-derived subset by `.agents/scripts/lib/qa/console-allowlist.js`.",
-  "type": "object",
-  "additionalProperties": false,
-  "required": [
-    "id",
-    "classification",
-    "surface",
-    "symptom",
-    "likelyRootCause",
-    "disposition",
-    "acceptance",
-    "evidence"
-  ],
-  "properties": {
-    "id": {
-      "type": "string",
-      "description": "Stable finding identifier, assigned `F1`, `F2`, … in capture order across a surface.",
-      "pattern": "^F[0-9]+$"
-    },
-    "classification": {
-      "type": "string",
-      "description": "What kind of problem this finding represents. `console-error` and `network-error` are emitted by the instrumentation layer; `design-token` by the visual-inspection layer; `behavior` for a semantic Then-assertion failure.",
-      "enum": ["console-error", "network-error", "design-token", "behavior"]
-    },
-    "surface": {
-      "type": "string",
-      "description": "The surface (route/screen label) the finding was observed on. Falls back to `unknown` when the harness cannot resolve a surface label.",
-      "minLength": 1
-    },
-    "symptom": {
-      "type": "string",
-      "description": "A one-line, user-visible description of the problem. Captured evidence (console/network) MUST already be scrubbed of tokens, session cookies, and PII per `.agents/rules/security-baseline.md` before this is rendered."
-    },
-    "likelyRootCause": {
-      "type": ["string", "null"],
-      "description": "The agent's best assessment of the underlying cause, or `null` when not yet inferred. Used to bundle findings into follow-up tickets in the assisted drafting step."
-    },
-    "disposition": {
-      "type": "string",
-      "description": "Whether the finding blocks the scenario (`blocker`) or is a deferred follow-up (`follow-up`).",
-      "enum": ["blocker", "follow-up"]
-    },
-    "acceptance": {
-      "type": ["string", "null"],
-      "description": "The acceptance condition that would close the follow-up this finding seeds, or `null` when the finding has not yet been promoted to a draft."
-    },
-    "foldsInto": {
-      "type": "string",
-      "description": "Optional. The id of another finding this one is a duplicate of, or folds into during root-cause bundling. Omit for a standalone finding.",
-      "pattern": "^F[0-9]+$"
-    },
-    "security": {
-      "type": "boolean",
-      "description": "Optional. `true` when the finding has a security dimension (e.g. a leaked token, an auth boundary failure, an injection-prone request) and MUST be routed with security baseline scrutiny. Omit or `false` for a non-security finding."
-    },
-    "routedTo": {
-      "type": "object",
-      "description": "Optional finding-to-issue link recording where the finding was routed once it is promoted to a follow-up ticket draft. Omit until the finding has been filed. The same link shape is mirrored on `qa-ledger.schema.json`.",
-      "additionalProperties": false,
-      "required": ["issue", "url", "kind"],
-      "properties": {
-        "issue": {
-          "type": "integer",
-          "description": "The GitHub issue number the finding was routed to.",
-          "minimum": 1
-        },
-        "url": {
-          "type": "string",
-          "description": "The canonical URL of the routed issue.",
-          "minLength": 1
-        },
-        "kind": {
-          "type": "string",
-          "description": "The kind of ticket the finding was routed to: a `story`, an `epic`, or a bare `issue`.",
-          "enum": ["story", "epic", "issue"]
-        }
-      }
-    },
-    "evidence": {
-      "type": "object",
-      "description": "Raw signal supporting the finding. Both arrays are always present (possibly empty) so a console-only or network-only finding still carries a well-formed evidence envelope.",
-      "additionalProperties": false,
-      "required": ["console", "network"],
-      "properties": {
-        "console": {
-          "type": "array",
-          "description": "Captured console messages supporting the finding.",
-          "items": {
-            "type": "object",
-            "additionalProperties": false,
-            "required": ["level", "text"],
-            "properties": {
-              "level": {
-                "type": "string",
-                "description": "Console message level (e.g. `error`, `severe`, `warning`)."
-              },
-              "text": {
-                "type": "string",
-                "description": "Console message text, scrubbed of secrets and PII."
-              }
-            }
-          }
-        },
-        "network": {
-          "type": "array",
-          "description": "Captured network requests supporting the finding.",
-          "items": {
-            "type": "object",
-            "additionalProperties": false,
-            "required": ["url", "status"],
-            "properties": {
-              "url": {
-                "type": "string",
-                "description": "Request URL, scrubbed of secrets and PII (e.g. query-string tokens)."
-              },
-              "status": {
-                "type": "integer",
-                "description": "HTTP status code of the response (0 when the request never completed)."
-              },
-              "method": {
-                "type": "string",
-                "description": "Optional HTTP method (e.g. `GET`, `POST`)."
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-}

package/.agents/scripts/lib/issue-link-parser.js

@@ -1,74 +0,0 @@
-/**
- * Parse PRD / Tech-Spec / Acceptance-Spec references from a GitHub epic body.
- * Extracted from providers/github.js so link-parsing is not mixed with HTTP
- * transport.
- *
- * Expected markdown conventions in an epic body (case-insensitive, tolerant
- * of the `- [ ]` / `- [x]` checkbox prefix that `epic-plan-spec.js` emits in
- * the `## Planning Artifacts` section):
- *   - "PRD: #42"  or  "prd #42"
- *   - "Tech Spec: #43"  /  "Technical Spec: #43"  /  "tech-spec: #43"
- *   - "Acceptance Spec: #44"  /  "acceptance-spec: #44"  /  "accept spec: #44"
- *
- * Story #2091 added the `acceptanceSpec` slot so the
- * `closePlanningArtifacts()` cascade in `epic-deliver-finalize.js` can close
- * the `context::acceptance-spec` ticket Epic #2001 introduces alongside the
- * existing PRD / Tech-Spec pair.
- *
- * Story #3848: regexes are now scoped to the `## Planning Artifacts` section
- * only. Prose elsewhere in the body (e.g. bundled-follow-up notes that
- * mention a foreign Epic's spec ticket by number) can no longer collide with
- * the machine-managed list items.
- */
-
-const PRD_RE = /(?:PRD|prd)[:\s]+#(\d+)/;
-const TECH_SPEC_RE = /(?:Tech Spec|tech.?spec|technical.?spec)[:\s]+#(\d+)/i;
-const ACCEPTANCE_SPEC_RE =
-  /(?:Acceptance Spec|acceptance.?spec|accept.?spec)[:\s]+#(\d+)/i;
-
-/**
- * Extract the `## Planning Artifacts` section text from an Epic body.
- * Returns the slice from just after the heading line to the next `##`-level
- * heading (exclusive), or to end-of-string when no following heading is
- * present. Returns an empty string when the section is absent.
- *
- * @param {string} body
- * @returns {string}
- */
-function extractPlanningArtifactsSection(body) {
-  // Step 1: locate the heading.
-  const startMatch = body.match(/^##\s+Planning Artifacts[^\n]*/m);
-  if (!startMatch) return '';
-  // Step 2: slice from just after the heading to the next ## heading (or EOB).
-  const afterHeading = body.slice(startMatch.index + startMatch[0].length);
-  const nextHeadingMatch = afterHeading.match(/\n##\s/);
-  return nextHeadingMatch
-    ? afterHeading.slice(0, nextHeadingMatch.index)
-    : afterHeading;
-}
-
-/**
- * @param {string|null|undefined} body
- * @returns {{ prd: number|null, techSpec: number|null, acceptanceSpec: number|null }}
- */
-export function parseLinkedIssues(body) {
-  const result = { prd: null, techSpec: null, acceptanceSpec: null };
-  if (typeof body !== 'string' || body.length === 0) return result;
-
-  // Scope all regex matching to the canonical Planning Artifacts section so
-  // prose references elsewhere in the body do not shadow the machine-managed
-  // list items. When the section is absent every slot stays null — the caller
-  // (plan-epic.js) treats null as "not yet linked" and creates fresh tickets.
-  const section = extractPlanningArtifactsSection(body);
-  if (section.length === 0) return result;
-
-  const prdMatch = section.match(PRD_RE);
-  if (prdMatch) result.prd = Number.parseInt(prdMatch[1], 10);
-  const specMatch = section.match(TECH_SPEC_RE);
-  if (specMatch) result.techSpec = Number.parseInt(specMatch[1], 10);
-  const acceptanceMatch = section.match(ACCEPTANCE_SPEC_RE);
-  if (acceptanceMatch) {
-    result.acceptanceSpec = Number.parseInt(acceptanceMatch[1], 10);
-  }
-  return result;
-}

package/.agents/scripts/lib/orchestration/finalize/close-planning-tickets.js

@@ -1,116 +0,0 @@
-// .agents/scripts/lib/orchestration/finalize/close-planning-tickets.js
-/**
- * close-planning-tickets.js — finalize helper that closes the three
- * planning context tickets (PRD / Tech Spec / Acceptance Spec) linked
- * from the Epic body's `## Planning Artifacts` section.
- *
- * Extracted from `/deliver` Phase 7.1 prose (the `gh issue close`
- * sequence) so the lifecycle Finalizer listener has a single async
- * helper to call. Reuses `parseLinkedIssues` so the three planning ids
- * are read from the same canonical body shape that `epic-plan` writes
- * via `ensurePlanningArtifacts` and that `closePlanningArtifacts` (the
- * existing post-merge close-tail helper) consumes.
- *
- * Story #2894 / Task #2904 (Epic #2880).
- *
- * Contract:
- *   - Input:  { epicId, provider, transitionFn?, logger? }
- *   - Output: { closed, alreadyClosed, failed, details[] }
- *
- * Idempotency: a planning ticket that is already closed (provider
- * `state === 'closed'`) is counted under `alreadyClosed` and not
- * re-transitioned. A failed close on one ticket records a `failed`
- * entry and the helper continues with the remaining tickets — finalize
- * surfaces the count and the listener decides whether to escalate via
- * `agent::blocked`.
- */
-
-import { parseLinkedIssues } from '../../issue-link-parser.js';
-import { Logger } from '../../Logger.js';
-import { STATE_LABELS, transitionTicketState } from '../ticketing.js';
-
-/**
- * @param {object} args
- * @param {number} args.epicId — numeric Epic ticket id.
- * @param {object} args.provider — ITicketingProvider. Must implement
- *   `getTicket(id)` returning at least `{ body, state, linkedIssues? }`.
- * @param {Function} [args.transitionFn] — override of
- *   `transitionTicketState` for tests.
- * @param {object} [args.logger] — { info, warn, debug } surface.
- * @returns {Promise<{
- *   closed: number,
- *   alreadyClosed: number,
- *   failed: number,
- *   details: Array<{ kind: 'prd'|'techSpec'|'acceptanceSpec', id: number|null, status: 'closed'|'already-closed'|'failed'|'skipped', detail?: string }>,
- * }>}
- */
-export async function closePlanningTickets({
-  epicId,
-  provider,
-  transitionFn = transitionTicketState,
-  logger = Logger,
-} = {}) {
-  if (!Number.isInteger(epicId) || epicId < 1) {
-    throw new TypeError(
-      'closePlanningTickets: epicId must be a positive integer',
-    );
-  }
-  if (!provider || typeof provider.getTicket !== 'function') {
-    throw new TypeError(
-      'closePlanningTickets: provider must implement getTicket()',
-    );
-  }
-
-  const epic = await provider.getTicket(epicId);
-  const linked = epic?.linkedIssues ?? parseLinkedIssues(epic?.body ?? '');
-
-  const kinds = /** @type {const} */ ([
-    ['prd', linked?.prd ?? null],
-    ['techSpec', linked?.techSpec ?? null],
-    ['acceptanceSpec', linked?.acceptanceSpec ?? null],
-  ]);
-
-  const settled = await Promise.all(
-    kinds.map(async ([kind, id]) => {
-      if (!Number.isInteger(id) || id <= 0) {
-        return { kind, id: null, status: 'skipped', detail: 'no-link' };
-      }
-      let snapshot;
-      try {
-        snapshot = await provider.getTicket(id);
-      } catch (err) {
-        const detail = err?.message ?? String(err);
-        logger.warn?.(
-          `[finalize/close-planning-tickets] read of ${kind} #${id} failed: ${detail}`,
-        );
-        return { kind, id, status: 'failed', detail };
-      }
-      if (snapshot?.state === 'closed') {
-        return { kind, id, status: 'already-closed' };
-      }
-      try {
-        await transitionFn(provider, id, STATE_LABELS.DONE, { cascade: false });
-        logger.info?.(
-          `[finalize/close-planning-tickets] closed ${kind} #${id} for Epic #${epicId}`,
-        );
-        return { kind, id, status: 'closed' };
-      } catch (err) {
-        const detail = err?.message ?? String(err);
-        logger.warn?.(
-          `[finalize/close-planning-tickets] close of ${kind} #${id} failed: ${detail}`,
-        );
-        return { kind, id, status: 'failed', detail };
-      }
-    }),
-  );
-
-  let closed = 0;
-  let alreadyClosed = 0;
-  let failed = 0;
-  for (const row of settled) {
-    if (row.status === 'closed') closed += 1;
-    else if (row.status === 'already-closed') alreadyClosed += 1;
-    else if (row.status === 'failed') failed += 1;
-  }
-  return { closed, alreadyClosed, failed, details: settled };
-}

package/.agents/scripts/lib/orchestration/planning-state-manager.js

@@ -1,318 +0,0 @@
-/**
- * @file planning-state-manager.js
- * Extracted state-healing and artifact idempotency logic for epic planning.
- *
- * Invariant: After planning completes, exactly ONE open PRD and ONE open
- * Tech Spec must exist as sub-issues of the Epic.  All others are closed
- * (state_reason: 'not_planned') and detached.
- */
-
-import { Logger } from '../Logger.js';
-import {
-  ACCEPTANCE_NA,
-  AGENT_LABELS,
-  CONTEXT_LABELS,
-} from '../label-constants.js';
-import { concurrentMap } from '../util/concurrent-map.js';
-
-/**
- * Snapshot of the Epic's planning-artifact state as seen / mutated by
- * {@link PlanningStateManager}. Mirrors the `epic-plan-state` structured
- * comment schema owned by `epic-plan-state-store.js`, narrowed to the fields
- * this manager reads and rewrites.
- *
- * @typedef {object} PlanCheckpointState
- * @property {number} epicId                             Epic ticket id.
- * @property {{ prd: (number | null), techSpec: (number | null), acceptanceSpec: (number | null) }} linkedIssues  Canonical planning-artifact references persisted on the Epic.
- * @property {string} body                               Current Epic body (may include a `## Planning Artifacts` section).
- */
-
-/**
- * Heals and de-duplicates the Epic's PRD / Tech Spec planning artifacts so
- * the post-state invariant holds: exactly ONE open PRD and ONE open Tech
- * Spec, both linked from the Epic body. All redundant artifacts are closed
- * (`state_reason: 'not_planned'`) and detached.
- */
-export class PlanningStateManager {
-  /**
-   * @param {import('../ITicketingProvider.js').ITicketingProvider} provider  Ticketing provider used for ticket + sub-issue mutations.
-   */
-  constructor(provider) {
-    this.provider = provider;
-  }
-
-  /**
-   * Resolve existing planning artifacts and heal / clean up the graph.
-   *
-   * With `force=false` (normal run):
-   *   - Pick the canonical PRD / Tech Spec (first open one, else first overall).
-   *   - Heal dangling `epic.linkedIssues` references.
-   *   - Close + detach any redundant artifacts (posting an audit-trace
-   *     notification first).
-   *   - Persist the healed references back to the Epic body if they were not
-   *     already written.
-   *
-   * With `force=true` (re-plan requested): **overwrite the canonical
-   * context tickets in place.** Keep the canonical PRD / Tech Spec /
-   * Acceptance Spec **open** and keep `epic.linkedIssues` pointing at them
-   * (so the caller can refresh their bodies via `provider.updateTicket`),
-   * close + detach only the redundant duplicate artifacts (exactly as the
-   * non-force path does), and strip the `## Planning Artifacts` section
-   * from the Epic body so the caller re-appends it pointing at the same
-   * preserved IDs. Context tickets are no longer closed-and-recreated on a
-   * forced re-plan; only Feature/Story child tickets keep that behaviour
-   * (handled outside this manager by `forceCloseExistingChildren`).
-   *
-   * Mutates `epic.linkedIssues` and `epic.body` in place.
-   *
-   * @param {PlanCheckpointState & { linkedIssues: object, body: string, id: number }} epic  Epic ticket with mutable planning state.
-   * @param {boolean} [force=false]  When true, preserve canonical context tickets (overwrite-in-place) and strip the Planning Artifacts body section for a forced re-plan.
-   * @returns {Promise<void>}
-   * @throws {Error}  Propagates non-404/410 errors from `provider.updateTicket`. All other provider errors are intentionally swallowed.
-   */
-  async healAndCleanupArtifacts(epic, force = false) {
-    const epicId = epic.id;
-    const relatedTickets = await this.provider.getTickets(epicId);
-    this.provider.primeTicketCache(relatedTickets);
-
-    // One descriptor per planning-artifact type. Each entry parameterizes
-    // the label filter, the canonical reference key on `epic.linkedIssues`,
-    // and a human-readable name for the heal log line, so the per-type
-    // filter / canonical / heal / successor logic runs from a single loop
-    // instead of three inlined copies.
-    const ARTIFACT_TYPES = [
-      { label: CONTEXT_LABELS.PRD, key: 'prd', name: 'PRD' },
-      { label: CONTEXT_LABELS.TECH_SPEC, key: 'techSpec', name: 'Tech Spec' },
-      {
-        label: CONTEXT_LABELS.ACCEPTANCE_SPEC,
-        key: 'acceptanceSpec',
-        name: 'Acceptance Spec',
-      },
-    ];
-
-    // Resolve each artifact type: collect ALL matching tickets (open AND
-    // closed) so stale sub-issue links get cleaned up regardless of state;
-    // pick the canonical one (first open, else first overall); heal a
-    // dangling `epic.linkedIssues` reference; and record the resolved
-    // canonical id for successor resolution below.
-    const resolved = ARTIFACT_TYPES.map((descriptor) => {
-      const all = relatedTickets.filter((t) =>
-        t.labels.includes(descriptor.label),
-      );
-      const canonical = all.find((t) => t.state === 'open') ?? all[0] ?? null;
-
-      if (!epic.linkedIssues[descriptor.key] && canonical?.state === 'open') {
-        epic.linkedIssues[descriptor.key] = canonical.id;
-        Logger.info(
-          `[Epic Planner] Healed dangling ${descriptor.name} reference: #${epic.linkedIssues[descriptor.key]}`,
-        );
-      }
-
-      const canonicalId = epic.linkedIssues[descriptor.key] ?? canonical?.id;
-      return { ...descriptor, all, canonicalId };
-    });
-
-    // Identify redundant artifacts: everything that is NOT the canonical one.
-    const redundant = resolved.flatMap((r) =>
-      r.all.filter((t) => t.id !== r.canonicalId),
-    );
-
-    // Map artifact label → resolved canonical id, for successor resolution.
-    const successorByLabel = new Map(
-      resolved.map((r) => [r.label, r.canonicalId]),
-    );
-
-    // Bound the close+detach mutation burst at 3 so wide redundancy
-    // cleanup does not race the GitHub secondary rate limit.
-    await concurrentMap(
-      redundant,
-      async (t) => {
-        const descriptor = ARTIFACT_TYPES.find((d) =>
-          t.labels.includes(d.label),
-        );
-        const successorId = descriptor
-          ? successorByLabel.get(descriptor.label)
-          : undefined;
-        Logger.info(
-          `[Epic Planner] Cleaning up redundant artifact #${t.id} (superseded by #${successorId})...`,
-        );
-
-        // Close the issue if it's still open
-        if (t.state === 'open') {
-          try {
-            await this.provider.postComment(t.id, {
-              type: 'notification',
-              body: `⚠️ **Audit Trace**: This planning artifact was created during an interrupted or failed orchestration run and is now **superseded by #${successorId}**. \n\nClosing this issue to maintain a single source of truth for Epic #${epicId}.`,
-            });
-          } catch (err) {
-            Logger.warn(
-              `[Epic Planner]   Could not post audit-trace comment on #${t.id}: ${err.message}`,
-            );
-          }
-          await this.provider.updateTicket(t.id, {
-            state: 'closed',
-            state_reason: 'not_planned',
-          });
-        }
-
-        // Detach the sub-issue from the Epic to prevent orphaned links
-        try {
-          await this.provider.removeSubIssue(epicId, t.id);
-          Logger.info(
-            `[Epic Planner]   Detached #${t.id} from Epic #${epicId}.`,
-          );
-        } catch (_err) {
-          // Already detached or API doesn't support — safe to ignore
-          Logger.info(
-            `[Epic Planner]   Could not detach #${t.id} (may already be detached).`,
-          );
-        }
-      },
-      { concurrency: 3 },
-    );
-
-    // Persist healed references to the body if needed.
-    if (
-      !force &&
-      epic.linkedIssues.prd &&
-      epic.linkedIssues.techSpec &&
-      !epic.body.includes('## Planning Artifacts')
-    ) {
-      Logger.info(
-        `[Epic Planner] Persisting healed references to Epic body...`,
-      );
-      const appendBody = `\n\n## Planning Artifacts\n- [ ] PRD: #${epic.linkedIssues.prd}\n- [ ] Tech Spec: #${epic.linkedIssues.techSpec}\n`;
-      await this.provider.updateTicket(epicId, {
-        body: epic.body + appendBody,
-      });
-      epic.body += appendBody;
-    }
-
-    // Force re-plan: overwrite the canonical context tickets in place.
-    // The redundant duplicates have already been closed + detached by the
-    // cleanup pass above. Here we only strip the `## Planning Artifacts`
-    // body section so `planEpic` re-appends it pointing at the same
-    // preserved canonical IDs. We deliberately DO NOT close the canonical
-    // PRD / Tech Spec / Acceptance Spec, and we keep `epic.linkedIssues`
-    // pointing at them so the caller can refresh their bodies.
-    if (force) {
-      const stripped = epic.body.replace(
-        /\n*## Planning Artifacts[\s\S]*$/,
-        '',
-      );
-      if (stripped !== epic.body) {
-        await this.provider.updateTicket(epicId, { body: stripped });
-        epic.body = stripped;
-        Logger.info(
-          '[Epic Planner]   Stripped old Planning Artifacts section from Epic body (canonical context tickets preserved for in-place overwrite).',
-        );
-      }
-    }
-  }
-
-  /**
-   * Compute whether an Epic is ready to transition from `agent::review-spec`
-   * to `agent::ready` by inspecting the state of its context tickets.
-   *
-   * An Epic is ready when **all three** context tickets — PRD, Tech Spec, and
-   * Acceptance Spec — exist and are closed. The acceptance-spec requirement
-   * can be waived by attaching the `acceptance::n-a` label to the Epic, in
-   * which case acceptance-spec presence and state are ignored. Missing PRD
-   * or Tech Spec is never waivable through this method.
-   *
-   * This predicate is **pure** with respect to the world: it reads tickets
-   * via the provider and computes a verdict. Callers (e.g. the planning
-   * runner) are responsible for actually flipping the label when
-   * `ready === true`.
-   *
-   * @param {number} epicId  Epic ticket id.
-   * @returns {Promise<{ ready: boolean, reason: string, contexts: { prd: ('open' | 'closed' | 'missing'), techSpec: ('open' | 'closed' | 'missing'), acceptanceSpec: ('open' | 'closed' | 'missing' | 'waived') } }>}
-   *   `ready` is `true` when the Epic satisfies the readiness gate.
-   *   `reason` is a machine-readable code suitable for logging / metrics
-   *   (`all-context-closed`, `acceptance-waived`, `prd-missing`,
-   *   `prd-open`, `tech-spec-missing`, `tech-spec-open`,
-   *   `acceptance-spec-missing`, `acceptance-spec-open`).
-   *   `contexts` is per-axis status for callers that want to render the
-   *   verdict alongside ticket links.
-   */
-  async computeReviewReadiness(epicId) {
-    const epic = await this.provider.getTicket(epicId);
-    const relatedTickets = await this.provider.getTickets(epicId);
-    this.provider.primeTicketCache(relatedTickets);
-
-    const epicLabels = epic?.labels ?? [];
-    const acceptanceWaived = epicLabels.includes(ACCEPTANCE_NA);
-
-    const findByLabel = (label) =>
-      relatedTickets.find((t) => (t.labels ?? []).includes(label)) ?? null;
-
-    const prd = findByLabel(CONTEXT_LABELS.PRD);
-    const techSpec = findByLabel(CONTEXT_LABELS.TECH_SPEC);
-    const acceptanceSpec = findByLabel(CONTEXT_LABELS.ACCEPTANCE_SPEC);
-
-    const axisStatus = (ticket) => {
-      if (!ticket) return 'missing';
-      return ticket.state === 'closed' ? 'closed' : 'open';
-    };
-
-    const contexts = {
-      prd: axisStatus(prd),
-      techSpec: axisStatus(techSpec),
-      acceptanceSpec: acceptanceWaived ? 'waived' : axisStatus(acceptanceSpec),
-    };
-
-    if (contexts.prd === 'missing') {
-      return { ready: false, reason: 'prd-missing', contexts };
-    }
-    if (contexts.prd === 'open') {
-      return { ready: false, reason: 'prd-open', contexts };
-    }
-    if (contexts.techSpec === 'missing') {
-      return { ready: false, reason: 'tech-spec-missing', contexts };
-    }
-    if (contexts.techSpec === 'open') {
-      return { ready: false, reason: 'tech-spec-open', contexts };
-    }
-    if (!acceptanceWaived) {
-      if (contexts.acceptanceSpec === 'missing') {
-        return { ready: false, reason: 'acceptance-spec-missing', contexts };
-      }
-      if (contexts.acceptanceSpec === 'open') {
-        return { ready: false, reason: 'acceptance-spec-open', contexts };
-      }
-    }
-
-    return {
-      ready: true,
-      reason: acceptanceWaived ? 'acceptance-waived' : 'all-context-closed',
-      contexts,
-    };
-  }
-
-  /**
-   * If the Epic satisfies {@link computeReviewReadiness}, flip it from
-   * `agent::review-spec` to `agent::ready`. Returns the verdict plus the
-   * label transition that was applied (if any). No-ops when readiness is
-   * not yet satisfied — callers are expected to retry on the next planning
-   * tick rather than block.
-   *
-   * @param {number} epicId
-   * @returns {Promise<{ ready: boolean, reason: string, contexts: object, transitioned: boolean }>}
-   */
-  async flipEpicToReadyIfContextClosed(epicId) {
-    const verdict = await this.computeReviewReadiness(epicId);
-    if (!verdict.ready) {
-      return { ...verdict, transitioned: false };
-    }
-    await this.provider.updateTicket(epicId, {
-      labels: {
-        add: [AGENT_LABELS.READY],
-        remove: [AGENT_LABELS.REVIEW_SPEC],
-      },
-    });
-    Logger.info(
-      `[Epic Planner] Epic #${epicId} → ${AGENT_LABELS.READY} (${verdict.reason}).`,
-    );
-    return { ...verdict, transitioned: true };
-  }
-}