mandrel 1.94.0 → 2.0.0

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

@@ -1,236 +0,0 @@
-/**
- * phases/plan-epic.js — Tech Spec / Acceptance Table persistence phase.
- *
- * Story #4324: the `context::tech-spec` / `context::acceptance-spec` ticket
- * classes are retired. The Epic body is the single planning document: this
- * phase upserts the authored Tech Spec (opening with `## Delivery Slicing`)
- * and the Acceptance Spec's AC-ID table (`## Acceptance Table`) as
- * marker-delimited managed sections of the Epic body — see
- * `lib/epic-body-sections.js`. Each write is **section-scoped**: only the
- * managed region is replaced; the rest of the body is byte-preserved.
- *
- * Idempotent against partial state: when the Epic body already carries all
- * requested sections, the phase short-circuits with `already-planned`.
- * Pass `force: true` to re-plan: the managed sections are overwritten in
- * place and a one-line regeneration audit comment lands on the Epic.
- *
- * The retired machine-managed `## Planning Artifacts` checklist (which
- * linked the old context tickets) is stripped on every persist so a
- * re-planned historical Epic stops advertising stale ticket links; the
- * legacy tickets themselves are ignored (forward-only cutover — no
- * backfill, no fetch).
- */
-
-import {
-  hasEpicSection,
-  stripEpicSection,
-  stripPlanningArtifactsSection,
-  upsertEpicSection,
-} from '../../../epic-body-sections.js';
-import { Logger } from '../../../Logger.js';
-import { ACCEPTANCE_NA } from '../../../label-constants.js';
-
-/**
- * Resolve whether Phase 7 should persist an acceptance-table section or
- * apply the `acceptance::n-a` waiver, from the planningRisk envelope derived
- * off the planner-authored risk verdict (`deriveRiskEnvelope`, Epic #3865).
- *
- * @param {import('../../planning-risk.js').PlanningRiskEnvelope|null} planningRisk
- *   Derived envelope; `null` (direct invocations without a verdict) never
- *   applies the waiver.
- * @param {string|null} acceptanceSpecContent
- * @returns {{ planningRisk: import('../../planning-risk.js').PlanningRiskEnvelope|null, wantsAcceptanceSpec: boolean, applyAcceptanceWaiver: boolean }}
- */
-export function resolveAcceptancePersistence(
-  planningRisk,
-  acceptanceSpecContent,
-) {
-  const hasAcceptanceContent =
-    typeof acceptanceSpecContent === 'string' &&
-    acceptanceSpecContent.trim() !== '';
-
-  if (planningRisk?.acceptanceDisposition === 'not-applicable') {
-    return {
-      planningRisk,
-      wantsAcceptanceSpec: false,
-      applyAcceptanceWaiver: true,
-    };
-  }
-
-  return {
-    planningRisk: planningRisk ?? null,
-    wantsAcceptanceSpec: hasAcceptanceContent,
-    applyAcceptanceWaiver: false,
-  };
-}
-
-export function validatePlanEpicInputs({
-  techSpecContent,
-  acceptanceSpecContent,
-}) {
-  if (typeof techSpecContent !== 'string' || techSpecContent.trim() === '') {
-    throw new Error(
-      '[Epic Planner] techSpecContent is required and must be non-empty.',
-    );
-  }
-  if (
-    acceptanceSpecContent !== null &&
-    (typeof acceptanceSpecContent !== 'string' ||
-      acceptanceSpecContent.trim() === '')
-  ) {
-    throw new Error(
-      '[Epic Planner] acceptanceSpecContent, when provided, must be a non-empty string.',
-    );
-  }
-}
-
-/**
- * Snapshot which managed planning sections the Epic body already carries.
- *
- * @param {{ body?: string }} epic
- * @returns {{ techSpec: boolean, acceptanceTable: boolean }}
- */
-export function getExistingSections(epic) {
-  const body = epic?.body ?? '';
-  return {
-    techSpec: hasEpicSection(body, 'techSpec'),
-    acceptanceTable: hasEpicSection(body, 'acceptanceTable'),
-  };
-}
-
-export function hasAllRequestedSections({ existing, wantsAcceptanceSpec }) {
-  return Boolean(
-    existing.techSpec &&
-      (wantsAcceptanceSpec ? existing.acceptanceTable : true),
-  );
-}
-
-/**
- * Persist the host-authored Tech Spec (and optional Acceptance Table) as
- * managed sections of the Epic body.
- *
- * @returns {Promise<{
- *   persisted: boolean,
- *   reason: 'already-planned'|'persisted'|'force-replan',
- *   techSpecPersisted: boolean,
- *   acceptanceTable: 'persisted'|'waived'|'none',
- * }>}
- */
-export async function planEpic(
-  epicId,
-  provider,
-  { techSpecContent, acceptanceSpecContent = null },
-  _settings = {},
-  { force = false, planningRisk = null } = {},
-) {
-  validatePlanEpicInputs({
-    techSpecContent,
-    acceptanceSpecContent,
-  });
-
-  Logger.info(`[Epic Planner] Fetching Epic #${epicId}...`);
-  const epic = await provider.getEpic(epicId);
-
-  if (!epic) {
-    throw new Error(`Epic #${epicId} not found.`);
-  }
-
-  const { wantsAcceptanceSpec, applyAcceptanceWaiver } =
-    resolveAcceptancePersistence(planningRisk, acceptanceSpecContent);
-
-  Logger.info(
-    `[Epic Planner] Acceptance disposition: ${planningRisk?.acceptanceDisposition ?? 'unspecified'}` +
-      (applyAcceptanceWaiver
-        ? ` — applying ${ACCEPTANCE_NA} waiver (no acceptance-table section).`
-        : wantsAcceptanceSpec
-          ? ' — persisting the ## Acceptance Table section.'
-          : ' — no acceptance-spec content supplied.'),
-  );
-
-  const existing = getExistingSections(epic);
-  if (!force && hasAllRequestedSections({ existing, wantsAcceptanceSpec })) {
-    Logger.warn(
-      `[Epic Planner] Epic #${epicId} body already carries all requested planning sections. Aborting to prevent an unintended overwrite. Use --force to re-plan.`,
-    );
-    return {
-      persisted: false,
-      reason: 'already-planned',
-      techSpecPersisted: existing.techSpec,
-      acceptanceTable: existing.acceptanceTable ? 'persisted' : 'none',
-    };
-  }
-
-  // Section-scoped writes: each upsert replaces only its own managed
-  // region; the ideation sections and any operator-authored prose are
-  // byte-preserved. The retired `## Planning Artifacts` checklist is
-  // stripped so re-planned historical Epics stop advertising the old
-  // context-ticket links (the legacy tickets themselves are ignored).
-  let newBody = stripPlanningArtifactsSection(epic.body ?? '');
-  newBody = upsertEpicSection(newBody, 'techSpec', techSpecContent);
-
-  let acceptanceTable = 'none';
-  if (wantsAcceptanceSpec) {
-    newBody = upsertEpicSection(
-      newBody,
-      'acceptanceTable',
-      acceptanceSpecContent,
-    );
-    acceptanceTable = 'persisted';
-  } else if (applyAcceptanceWaiver) {
-    // Acceptance transition: was present, now waived (acceptance::n-a).
-    // Strip the stale table so the close-time reconciler cannot read a
-    // section the planner no longer stands behind.
-    if (existing.acceptanceTable) {
-      Logger.info(
-        `[Epic Planner] Acceptance disposition now waived — removing the stale ## Acceptance Table section from Epic #${epicId}.`,
-      );
-      newBody = stripEpicSection(newBody, 'acceptanceTable');
-    }
-    acceptanceTable = 'waived';
-  }
-
-  /** @type {{ add?: string[], remove?: string[] }} */
-  const labelMutations = {};
-  if (applyAcceptanceWaiver) {
-    labelMutations.add = [ACCEPTANCE_NA];
-  } else if (
-    wantsAcceptanceSpec &&
-    (epic.labels ?? []).includes(ACCEPTANCE_NA)
-  ) {
-    labelMutations.remove = [ACCEPTANCE_NA];
-  }
-
-  Logger.info(
-    `[Epic Planner] Updating Epic #${epicId} body with the planning sections...`,
-  );
-  await provider.updateTicket(epicId, {
-    body: newBody,
-    ...(labelMutations.add || labelMutations.remove
-      ? { labels: labelMutations }
-      : {}),
-  });
-
-  if (force) {
-    // Preserve the regeneration audit trail the retired per-ticket
-    // overwrite used to leave. Best-effort — never fail the persist on a
-    // comment post error.
-    try {
-      await provider.postComment(epicId, {
-        type: 'notification',
-        body: '♻️ **Regeneration Audit**: the Tech Spec / Acceptance Table sections of this Epic body were regenerated in place by a `/plan --force` re-plan. Content outside the managed sections was preserved.',
-      });
-    } catch (_err) {
-      // Swallow: audit comment is advisory.
-    }
-  }
-
-  Logger.info(`[Epic Planner] Epic #${epicId} updated successfully.`);
-  Logger.info(`[Epic Planner] Planning pipeline complete!`);
-
-  return {
-    persisted: true,
-    reason: force ? 'force-replan' : 'persisted',
-    techSpecPersisted: true,
-    acceptanceTable,
-  };
-}

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

@@ -1,307 +0,0 @@
-/**
- * phases/run-spec-phase.js — orchestrator for Phase 7 (spec).
- *
- * Wires the planEpic persist phase, the Tech Spec freshness advisory, the
- * `agent::review-spec` label flip, the planning-state checkpoint upsert, and
- * the temp-file cleanup into a single sequential flow.
- */
-
-import path from 'node:path';
-import { verifyBddRunnerPendingTag } from '../../../bdd-runner-detect.js';
-import { Logger } from '../../../Logger.js';
-import { AGENT_LABELS, TYPE_LABELS } from '../../../label-constants.js';
-import { cleanupPhaseTempFiles } from '../../../plan-phase-cleanup.js';
-import { PROJECT_ROOT } from '../../../project-root.js';
-import { acquireEpicPlanLease } from '../../epic-plan-lease-guard.js';
-import {
-  initialize as initializePlanState,
-  read as readPlanState,
-  write as writePlanState,
-} from '../../epic-plan-state-store.js';
-import { resolveReviewRouting } from '../../plan-review-routing.js';
-import { deriveRiskEnvelope } from '../../planning-risk.js';
-import {
-  formatMissingSectionMessage,
-  validateSpecSections,
-} from '../../spec-section-validator.js';
-import { upsertStructuredComment } from '../../ticketing.js';
-import { planEpic } from './plan-epic.js';
-import { runSpecFreshnessCheck } from './spec-freshness.js';
-
-/**
- * Render the `risk-verdict` structured-comment body: a reviewer-readable
- * axis table plus the canonical fenced-JSON record (verdict + derived
- * envelope) downstream tooling parses.
- *
- * @param {{ epicId: number, riskVerdict: import('../../planning-risk.js').RiskVerdict, planningRisk: import('../../planning-risk.js').PlanningRiskEnvelope }} input
- * @returns {string}
- */
-function buildRiskVerdictCommentBody({ epicId, riskVerdict, planningRisk }) {
-  const axisRows = planningRisk.axes.map(
-    (entry) => `| ${entry.axis} | ${entry.level} | ${entry.rationale} |`,
-  );
-  const axisTable =
-    axisRows.length > 0
-      ? ['| Axis | Level | Rationale |', '| --- | --- | --- |', ...axisRows]
-      : ['_No risk axes apply (planner-asserted)._'];
-  const record = {
-    kind: 'risk-verdict',
-    epicId,
-    verdict: riskVerdict,
-    planningRisk,
-  };
-  // Story #4145 — when the disposition was forced to not-applicable because
-  // no BDD runner exists, make the waiver operator-visible in the rendered
-  // comment (not just the fenced JSON record) so a reviewer sees why an
-  // otherwise-required AC table was waived.
-  const waiverNote = planningRisk.acceptanceWaivedReason
-    ? ['', `> ⚠️ **Acceptance waived** — ${planningRisk.acceptanceWaivedReason}`]
-    : [];
-  return [
-    `### 🧭 Planning Risk Verdict — ${planningRisk.overallLevel} · ${planningRisk.gateDecision}`,
-    '',
-    riskVerdict.summary,
-    '',
-    ...axisTable,
-    ...waiverNote,
-    '',
-    '```json',
-    JSON.stringify(record, null, 2),
-    '```',
-  ].join('\n');
-}
-
-async function setEpicLabel(provider, epicId, targetLabel) {
-  const planningLabels = [AGENT_LABELS.REVIEW_SPEC, AGENT_LABELS.READY];
-  await provider.updateTicket(epicId, {
-    labels: {
-      add: [targetLabel],
-      remove: planningLabels.filter((l) => l !== targetLabel),
-    },
-  });
-}
-
-/**
- * Execute the spec phase end to end.
- *
- * @param {number} epicId
- * @param {import('../../../ITicketingProvider.js').ITicketingProvider} provider
- * @param {{ techSpecContent: string, acceptanceSpecContent?: string|null }} artifacts
- * @param {object} settings
- * @param {{ force?: boolean, forceReview?: boolean, steal?: boolean, config?: object, riskVerdict?: import('../../planning-risk.js').RiskVerdict }} [opts]
- * @returns {Promise<{ epicId: number, techSpecPersisted: boolean, acceptanceTable: 'persisted'|'waived'|'none', checkpoint: object, planningRisk: import('../../planning-risk.js').PlanningRiskEnvelope, reviewRouting: import('../../plan-review-routing.js').ReviewRoutingEnvelope }>}
- */
-export async function runSpecPhase(
-  epicId,
-  provider,
-  { techSpecContent, acceptanceSpecContent = null },
-  settings = {},
-  {
-    force = false,
-    forceReview = false,
-    steal = false,
-    config,
-    riskVerdict,
-  } = {},
-) {
-  // Hard cutover (Epic #3865): the planner-authored risk verdict is the
-  // sole risk source. Derive the envelope up front so a missing verdict
-  // fails closed before any GitHub mutation.
-  if (!riskVerdict || !Array.isArray(riskVerdict.axes)) {
-    throw new Error(
-      '[epic-plan-spec] risk verdict is required — author risk-verdict.json via the epic-plan-spec-author Skill and pass it with --risk-verdict.',
-    );
-  }
-
-  // Story #4403 (Finding 3): the "## Delivery Slicing" presence gate — the
-  // Phase 8-side anchor the Holistic Consolidation pass reconciles against —
-  // is validated here, against the in-memory authored content, before any
-  // GitHub mutation (lease acquisition, Epic body write, structured
-  // comments). This replaces the retired standalone `epic-plan-spec-validate.js`
-  // CLI / Phase 7.5 workflow step, whose documented ordering ran the check
-  // AFTER the persist path had already written to GitHub and deleted the
-  // temp file it read — so the "blocking gate" could never actually block.
-  const sectionCheck = validateSpecSections({ body: techSpecContent });
-  if (!sectionCheck.ok) {
-    throw new Error(
-      formatMissingSectionMessage({
-        techspecPath: `Epic #${epicId} authored Tech Spec`,
-        missing: sectionCheck.missing,
-      }),
-    );
-  }
-
-  // Story #4145 — probe the project's BDD runner. When none is detected
-  // (`fallback === true`, e.g. a node:test repo with no tests/features/**),
-  // the acceptance disposition is forced to not-applicable inside
-  // deriveRiskEnvelope: an authored AC table could never be reconciled by
-  // `@epic-<id>-ac-*` feature tags, so /deliver finalize would otherwise
-  // abort and require a manual `acceptance::n-a`. The probe is static and
-  // best-effort — a detection failure degrades to "runner present" (no
-  // forced waiver), preserving the BDD-repo path, and never blocks Phase 7.
-  let bddRunner = null;
-  try {
-    bddRunner = await verifyBddRunnerPendingTag({ cwd: PROJECT_ROOT });
-  } catch (err) {
-    Logger.warn(
-      `[epic-plan-spec] BDD runner probe skipped (${err.message}); acceptance disposition derived from risk axes only.`,
-    );
-  }
-  const planningRisk = deriveRiskEnvelope(riskVerdict, { bddRunner });
-  if (planningRisk.acceptanceWaivedReason) {
-    Logger.info(
-      `[epic-plan-spec] Acceptance disposition forced to not-applicable for Epic #${epicId}: ${planningRisk.acceptanceWaivedReason}`,
-    );
-  }
-
-  const epic = await provider.getEpic(epicId);
-  if (!epic) {
-    throw new Error(`[epic-plan-spec] Epic #${epicId} not found.`);
-  }
-  if (!epic.labels?.includes(TYPE_LABELS.EPIC)) {
-    throw new Error(
-      `[epic-plan-spec] Ticket #${epicId} is not a ${TYPE_LABELS.EPIC}.`,
-    );
-  }
-
-  // Workflow-guards (Story #3481): acquire the Epic-lease before any Phase 7
-  // mutation so two concurrent /plan runs cannot both drive this Epic. The
-  // guard fails closed (audit #3513) — any foreign assignee refuses here and
-  // the CLI exits non-zero naming the owner, unless `--steal` transfers it.
-  await acquireEpicPlanLease({ provider, epicId, config, steal });
-
-  await initializePlanState({ provider, epicId });
-
-  const planResult = await planEpic(
-    epicId,
-    provider,
-    { techSpecContent, acceptanceSpecContent },
-    settings,
-    {
-      force,
-      planningRisk,
-    },
-  );
-  const specChanged = planResult?.persisted !== false;
-
-  const afterPlan = await provider.getEpic(epicId);
-
-  // Story #2635 — cross-validate the authored Tech Spec body against the
-  // base branch and surface any stale path-shaped references. Story #4324:
-  // with the Tech Spec folded into the Epic body, the advisory comment
-  // lands on the Epic itself. Non-blocking: a missing base ref, an
-  // unreadable temp directory, or a provider failure downgrades to a
-  // warning so Phase 7 never fails on the advisory check.
-  const baseBranchRef = settings?.baseBranch ?? 'main';
-  const tempRoot = path.resolve(
-    PROJECT_ROOT,
-    settings?.paths?.tempRoot ?? 'temp',
-  );
-  const freshness = await runSpecFreshnessCheck({
-    epicId,
-    techSpecContent,
-    baseBranchRef,
-    tempRoot,
-    provider,
-  });
-
-  // Story #1585 (Epic #1471): the baseline-snapshot fork was previously
-  // performed here at plan-time. It now runs at first-story-init time
-  // inside `lib/story-init/branch-initializer.js#bootstrapWorktree` so
-  // `/plan` remains git-state-free. `forkAndCommitEpicSnapshot` and
-  // `forkMainToEpic` remain exported for that caller.
-
-  const reviewRouting = resolveReviewRouting({ planningRisk, forceReview });
-
-  // Record the planner-authored verdict as a structured artifact — the
-  // audit trail the retired regex classifier never produced (Epic #3865).
-  await upsertStructuredComment(
-    provider,
-    epicId,
-    'risk-verdict',
-    buildRiskVerdictCommentBody({ epicId, riskVerdict, planningRisk }),
-  );
-
-  const currentState =
-    (await readPlanState({ provider, epicId })) ??
-    (await initializePlanState({ provider, epicId }));
-  const checkpoint = await writePlanState({
-    provider,
-    epicId,
-    state: {
-      ...currentState,
-      planningRisk,
-      riskVerdict,
-      reviewRouting: {
-        decision: reviewRouting.decision,
-        requiresStop: reviewRouting.requiresStop,
-        forceReviewApplied: reviewRouting.forceReviewApplied,
-      },
-      spec: {
-        ...currentState.spec,
-        techSpecPersisted: planResult?.techSpecPersisted === true,
-        acceptanceTable: planResult?.acceptanceTable ?? 'none',
-        completedAt: new Date().toISOString(),
-      },
-    },
-  });
-
-  Logger.info(`[epic-plan-spec] Review routing: ${reviewRouting.decision}.`);
-  Logger.info(`[epic-plan-spec] ${reviewRouting.operatorMessage}`);
-
-  // Story #4019 (refining #3905): a spec-phase rerun that changed nothing
-  // (planEpic short-circuited on `already-planned`) MUST NOT demote a
-  // fully-decomposed `agent::ready` Epic back to `agent::review-spec` —
-  // there is no new spec content to review. The demotion fires only when
-  // the spec actually persisted/changed, or when the Epic is not at
-  // `agent::ready` (where the flip is the normal forward transition).
-  const epicLabels = afterPlan.labels ?? [];
-  const skipDemotion = !specChanged && epicLabels.includes(AGENT_LABELS.READY);
-  let labelTransition;
-  if (skipDemotion) {
-    labelTransition = 'kept-ready';
-    Logger.info(
-      `[epic-plan-spec] Spec unchanged (${planResult?.reason ?? 'already-planned'}) and Epic #${epicId} is ${AGENT_LABELS.READY} — keeping ${AGENT_LABELS.READY} (no demotion to ${AGENT_LABELS.REVIEW_SPEC}).`,
-    );
-  } else {
-    labelTransition = 'review-spec';
-    Logger.info(
-      `[epic-plan-spec] Flipping Epic #${epicId} to ${AGENT_LABELS.REVIEW_SPEC}...`,
-    );
-    await setEpicLabel(provider, epicId, AGENT_LABELS.REVIEW_SPEC);
-  }
-
-  const cleanup = await cleanupPhaseTempFiles({ phase: 'spec', epicId });
-
-  const acceptanceSummary =
-    planResult?.acceptanceTable === 'persisted'
-      ? ' + ## Acceptance Table section'
-      : planResult?.acceptanceTable === 'waived'
-        ? ' (acceptance waived)'
-        : '';
-  const freshnessSummary =
-    freshness.stale > 0 || freshness.ambiguous > 0
-      ? ` ⚠️ Spec freshness: ${freshness.stale} stale / ${freshness.ambiguous} ambiguous reference(s) — see ${freshness.reportPath ?? 'report'}.`
-      : '';
-  Logger.info(
-    `[epic-plan-spec] ✅ Spec phase complete for Epic #${epicId}. Tech Spec sections folded into the Epic body${acceptanceSummary}.${freshnessSummary}`,
-  );
-  if (cleanup.deleted.length > 0) {
-    Logger.info(
-      `[epic-plan-spec] 🧹 Cleaned up ${cleanup.deleted.length} temp file(s).`,
-    );
-  }
-
-  return {
-    epicId,
-    techSpecPersisted: planResult?.techSpecPersisted === true,
-    acceptanceTable: planResult?.acceptanceTable ?? 'none',
-    checkpoint,
-    cleanup,
-    freshness,
-    planningRisk,
-    reviewRouting,
-    specChanged,
-    labelTransition,
-  };
-}

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

@@ -1,117 +0,0 @@
-/**
- * phases/spec-freshness.js — Tech Spec freshness check phase.
- *
- * Cross-validates the authored Tech Spec body against the base branch and
- * surfaces any stale path-shaped references on the Epic (Story #4324: the
- * Tech Spec is folded into the Epic body, so the Epic is the comment
- * target). Two side effects, both best-effort and non-blocking:
- *
- *   1. Write the full `{ stale, fresh, ambiguous }` report to
- *      `<tempRoot>/epic-<id>-spec-freshness.json` so downstream tooling
- *      (the `--code-freshness` health check on the roadmap, or an
- *      operator inspecting the run) can read it without re-probing git.
- *   2. When `stale.length > 0`, upsert a `spec-freshness` structured
- *      comment on the Epic listing each suspect citation.
- *      The comment is upserted, so re-running spec re-renders the same
- *      comment in place rather than spamming the issue.
- *
- * Caller signals are aggressive in containment — any error in this path
- * is downgraded to a warning. Phase 7 must not fail because a doc-author
- * cited a path the validator can't probe (e.g. shallow clone, base ref
- * not fetched). The non-blocking contract is the load-bearing AC.
- */
-
-import { mkdir, writeFile } from 'node:fs/promises';
-import path from 'node:path';
-import { Logger } from '../../../Logger.js';
-import {
-  renderSpecFreshnessComment,
-  validateSpecFreshness,
-} from '../../spec-freshness.js';
-import { upsertStructuredComment } from '../../ticketing.js';
-
-/**
- * @param {object} opts
- * @param {number} opts.epicId
- * @param {string} opts.techSpecContent
- * @param {string} opts.baseBranchRef
- * @param {string} opts.tempRoot
- * @param {import('../../../ITicketingProvider.js').ITicketingProvider} opts.provider
- * @param {Function} [opts.validator] - Testing seam (defaults to validateSpecFreshness).
- * @param {Function} [opts.commentUpserter] - Testing seam (defaults to upsertStructuredComment).
- * @param {Function} [opts.fileWriter] - Testing seam (defaults to fs writeFile/mkdir wrapper).
- * @returns {Promise<{ stale: number, ambiguous: number, fresh: number, reportPath: string|null, commentPosted: boolean }>}
- */
-export async function runSpecFreshnessCheck({
-  epicId,
-  techSpecContent,
-  baseBranchRef,
-  tempRoot,
-  provider,
-  validator = validateSpecFreshness,
-  commentUpserter = upsertStructuredComment,
-  fileWriter = async (filePath, body) => {
-    await mkdir(path.dirname(filePath), { recursive: true });
-    await writeFile(filePath, body, 'utf8');
-  },
-}) {
-  try {
-    const report = validator(techSpecContent, { baseBranchRef });
-    const reportPath = path.join(
-      tempRoot,
-      `epic-${epicId}-spec-freshness.json`,
-    );
-    const payload = {
-      epicId,
-      baseBranchRef,
-      generatedAt: new Date().toISOString(),
-      summary: {
-        stale: report.stale.length,
-        ambiguous: report.ambiguous.length,
-        fresh: report.fresh.length,
-      },
-      ...report,
-    };
-    await fileWriter(reportPath, `${JSON.stringify(payload, null, 2)}\n`);
-
-    let commentPosted = false;
-    if (report.stale.length > 0 && Number.isFinite(epicId)) {
-      const body = renderSpecFreshnessComment(report, {
-        baseBranchRef,
-        epicId,
-      });
-      await commentUpserter(provider, epicId, 'spec-freshness', body);
-      commentPosted = true;
-    }
-
-    if (report.stale.length > 0 || report.ambiguous.length > 0) {
-      Logger.warn(
-        `[epic-plan-spec] Tech Spec freshness: ${report.stale.length} stale, ${report.ambiguous.length} ambiguous, ${report.fresh.length} fresh against ${baseBranchRef}. Report: ${reportPath}.`,
-      );
-    } else {
-      Logger.info(
-        `[epic-plan-spec] Tech Spec freshness: ${report.fresh.length} fresh references against ${baseBranchRef}. No drift detected.`,
-      );
-    }
-
-    return {
-      stale: report.stale.length,
-      ambiguous: report.ambiguous.length,
-      fresh: report.fresh.length,
-      reportPath,
-      commentPosted,
-    };
-  } catch (err) {
-    Logger.warn(
-      `[epic-plan-spec] Tech Spec freshness check skipped: ${err.message}`,
-    );
-    return {
-      stale: 0,
-      ambiguous: 0,
-      fresh: 0,
-      reportPath: null,
-      commentPosted: false,
-      error: err.message,
-    };
-  }
-}