heyspex 0.1.0 → 0.2.1

package/scripts/hs-auto-resolve.mjs

@@ -0,0 +1,240 @@
+/**
+ * Resolve `/hs-auto [filename]` to a dev-factory dispatch target.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { basename, isAbsolute, join, normalize, relative } from 'node:path';
+import { findSpecFile } from '../dev-factory/lib/spec-io.mjs';
+// Epic/parent-shaped detection is the shared source of truth in dev-factory/lib —
+// scripts/ already imports findSpecFile from there, so this import direction is
+// established (2026-07-11 consolidation of the previously-triplicated predicate).
+import { specFacts, isEpicSpec } from '../dev-factory/lib/epic-detect.mjs';
+import {
+  fmWikilinkList,
+  isPhase1Artifact,
+  isSourcePlanningSpec,
+  readSpecMetaFull,
+  resolvePhase1Spec,
+  resolveSourcePlanningSpec,
+} from './hs-auto-source.mjs';
+
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+const HS_ID = /^HS-[A-Z0-9]+-(?:TASK|EPIC|MIL|CAP|RES|REV|DIAG)(?:-|$)/i;
+
+/**
+ * @param {string} repoRoot
+ * @param {string} raw
+ */
+function toRepoRelative(repoRoot, raw) {
+  const abs = isAbsolute(raw) ? normalize(raw) : normalize(join(repoRoot, raw));
+  const rel = relative(repoRoot, abs).replace(/\\/g, '/');
+  if (rel.startsWith('..')) return raw.replace(/\\/g, '/');
+  return rel;
+}
+
+/**
+ * @param {string} fm
+ * @param {string} key
+ */
+function fmScalar(fm, key) {
+  const m = fm.match(new RegExp(`^${key}:\\s*(.+)$`, 'm'));
+  if (!m) return null;
+  return m[1].trim().replace(/^['"]|['"]$/g, '');
+}
+
+/**
+ * @param {string} filePath
+ */
+function readSpecMeta(filePath) {
+  const meta = readSpecMetaFull(filePath);
+  return {
+    id: meta.id,
+    type: meta.type,
+    status: meta.status,
+    target: meta.target,
+    spec_path: filePath,
+  };
+}
+
+/**
+ * @param {string} specsDir
+ * @param {string} targetNeedle repo-relative, forward slashes
+ */
+function findTaskByTargetSync(specsDir, targetNeedle) {
+  const tasksDir = join(specsDir, 'tasks');
+  if (!existsSync(tasksDir)) return null;
+  /** @type {string[]} */
+  const files = [];
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry);
+      if (statSync(full).isDirectory()) walk(full);
+      else if (entry.endsWith('.md')) files.push(full);
+    }
+  };
+  walk(tasksDir);
+
+  const norm = targetNeedle.replace(/\\/g, '/');
+  for (const file of files) {
+    const meta = readSpecMeta(file);
+    if (!meta.target) continue;
+    const t = meta.target.replace(/\\/g, '/');
+    if (t === norm || norm.endsWith(t) || t.endsWith(norm)) {
+      return meta;
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {{ id: string|null, type: string|null, target: string|null }} meta
+ * @param {string} rel
+ * @param {string} repoRoot
+ */
+function resolveExecutableSpec(meta, rel, repoRoot) {
+  if (isSourcePlanningSpec(meta.type, meta.id)) {
+    const full = readSpecMetaFull(join(repoRoot, rel));
+    return resolveSourcePlanningSpec(repoRoot, full, rel);
+  }
+  // HS-5Q41: a capture (raw or mid-stage) resolves to the Phase-1 runner with a start-at-step hint,
+  // instead of dead-ending at MISSING_TARGET. Placed before the epic/target branches — a capture is
+  // neither an epic nor a dispatchable task.
+  if (isPhase1Artifact(meta.type, meta.id)) {
+    const full = readSpecMetaFull(join(repoRoot, rel));
+    return resolvePhase1Spec(full, rel);
+  }
+  // Epic/parent backstop (2026-07-11 idle-fleet incident): an epic is detected by
+  // type:, by id — including ids ENDING in "-EPIC", which the old /-EPIC-/ regex
+  // missed — by living under specs/epics/, or by carrying a children: frontmatter
+  // key at all (parent-shaped). Any of these is STRUCTURALLY blocked from
+  // `mode: dispatch`: an epic with children: [] (or with children) can only ever
+  // classify as breakdown, even when it carries a target: of its own. The dispatch
+  // branch below is unreachable for it by construction, and controller.mjs's
+  // dispatch gate (lib/dispatch-gate.mjs) backstops any caller that bypasses this.
+  // Detection is the shared source of truth (dev-factory/lib/epic-detect.mjs); this
+  // classifier additionally routes ANY parent-shaped spec (a children: key present,
+  // even with children) to breakdown.
+  let facts = { id: meta.id ?? '', type: (meta.type ?? '').toLowerCase(), path: rel, hasChildrenKey: false, childCount: 0, target: meta.target };
+  let childCount = 0;
+  try {
+    const raw = readFileSync(join(repoRoot, rel), 'utf8');
+    facts = specFacts({ raw, specPath: rel, specId: meta.id });
+    const fm = raw.match(FRONTMATTER)?.[1] ?? '';
+    if (facts.hasChildrenKey) childCount = fmWikilinkList(fm, 'children').length;
+  } catch { /* unreadable file → fall through to the target checks below */ }
+  const isEpic = isEpicSpec(facts) || facts.hasChildrenKey;
+  if (isEpic) {
+    return {
+      mode: 'breakdown',
+      spec_id: meta.id,
+      spec_path: rel,
+      children_count: childCount,
+      dispatch_blocked:
+        'An epic (or a parent-shaped spec with a children: key) is never dispatchable as a single target — breakdown first, then dispatch the FILED child tasks across the fleet.',
+      breakdown_command: `node dev-factory/controller.mjs --breakdown-epic ${meta.id}`,
+      epic_pipeline_command: `node dev-factory/dispatch-epic.mjs --epic ${meta.id}`,
+      filing_helper: 'node dev-factory/lib/breakdown-to-filing.mjs --draft <draft.json> --task-id HS-....-TASK [--target path]',
+      coo_contract:
+        'COO orchestration only — run preflight, then breakdown_command (or epic_pipeline_command, which chains breakdown → owner approval → filed-children fan-out via backlog-runner --concurrent). Review draft JSON, run filing_helper per task row, file via heyspex_file_spec with ## Builder brief, re-resolve, dispatch. NEVER controller.mjs --spec <epic> --target — the dispatch gate refuses it. Do NOT implement in Cursor.',
+    };
+  }
+  if (!meta.target) {
+    return {
+      error: 'MISSING_TARGET',
+      message: `${meta.id ?? rel} has no target: frontmatter — add target before dispatch.`,
+      spec_id: meta.id ?? undefined,
+      spec_path: rel,
+    };
+  }
+  return {
+    mode: 'dispatch',
+    spec_id: meta.id,
+    spec_path: rel,
+    target: meta.target.replace(/\\/g, '/'),
+    dispatch_command: buildDispatchCommand(rel, meta.target),
+    coo_contract:
+      'COO orchestration only — run preflight, then dispatch_command. Do NOT implement in Cursor unless the gate fails after fleet retries.',
+  };
+}
+
+/**
+ * @param {string} repoRoot
+ * @param {string | undefined | null} filename
+ */
+export function resolveHsAutoEntry(repoRoot, filename) {
+  const specsDir = join(repoRoot, 'specs');
+  const trimmed = (filename ?? '').trim().replace(/^["']|['"]$/g, '');
+  if (!trimmed) {
+    return {
+      mode: 'discover',
+      message: 'No filename — run backlog discovery after pre-flight.',
+      coo_contract:
+        'COO orchestration only — run preflight, discover_command, pick a ready task with target:, re-resolve. Do NOT implement in Cursor.',
+    };
+  }
+
+  const idToken = trimmed.match(HS_ID)?.[0] ?? (
+    basename(trimmed).match(HS_ID)?.[0] ?? null
+  );
+
+  if (idToken) {
+    const specPath = findSpecFile(specsDir, idToken);
+    if (!specPath) {
+      return { error: 'SPEC_NOT_FOUND', message: `No vault spec found for ${idToken}` };
+    }
+    const meta = readSpecMeta(specPath);
+    const rel = relative(repoRoot, specPath).replace(/\\/g, '/');
+    return resolveExecutableSpec(meta, rel, repoRoot);
+  }
+
+  const relPath = toRepoRelative(repoRoot, trimmed);
+  const absPath = join(repoRoot, relPath);
+  if (relPath.endsWith('.md') && existsSync(absPath)) {
+    const meta = readSpecMeta(absPath);
+    return resolveExecutableSpec(meta, relPath, repoRoot);
+  }
+
+  if (existsSync(absPath)) {
+    const byTarget = findTaskByTargetSync(specsDir, relPath);
+    if (byTarget?.id && byTarget.target) {
+      const specRel = relative(repoRoot, byTarget.spec_path).replace(/\\/g, '/');
+      return {
+        mode: 'dispatch',
+        spec_id: byTarget.id,
+        spec_path: specRel,
+        target: byTarget.target.replace(/\\/g, '/'),
+        matched_via: 'target_frontmatter',
+        dispatch_command: buildDispatchCommand(specRel, byTarget.target),
+        coo_contract:
+          'COO orchestration only — run preflight, then dispatch_command. Do NOT implement in Cursor unless the gate fails after fleet retries.',
+      };
+    }
+    return {
+      error: 'NO_TASK_FOR_FILE',
+      message: `No vault task lists target: ${relPath}. File a task with target: or pass a spec path/id.`,
+      file: relPath,
+    };
+  }
+
+  return {
+    error: 'FILE_NOT_FOUND',
+    message: `Path not found: ${trimmed}`,
+  };
+}
+
+/**
+ * @param {string} specPath repo-relative
+ * @param {string} target
+ */
+export function buildDispatchCommand(specPath, target) {
+  const specId = basename(specPath, '.md');
+  const checkpoint = `dev-factory/state/checkpoint-${specId}.json`;
+  return [
+    'node dev-factory/controller.mjs',
+    `--spec ${specPath}`,
+    `--target ${target.replace(/\\/g, '/')}`,
+    '--use-scheduler',
+    '--quality-pipeline',
+    '--n 3',
+    `--checkpoint ${checkpoint}`,
+  ].join(' ');
+}

package/scripts/hs-auto-source.mjs

@@ -0,0 +1,398 @@
+/**
+ * Source-spec pipeline helpers for `/hs-auto` — diagnose + research are planning
+ * inputs (like capture/research in Phase 1). They are NOT dispatchable until a
+ * remediation epic + tasks with `target:` exist.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, basename } from 'node:path';
+
+import { findSpecFile } from '../dev-factory/lib/spec-io.mjs';
+
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+
+/** @typedef {{ id: string|null, type: string|null, status: string|null, target: string|null, parent: string|null, spec_path: string, body: string }} SpecMeta */
+
+/**
+ * @param {string} fm
+ * @param {string} key
+ */
+export function fmScalar(fm, key) {
+  const m = fm.match(new RegExp(`^${key}:\\s*(.+)$`, 'm'));
+  if (!m) return null;
+  return m[1].trim().replace(/^['"]|['"]$/g, '');
+}
+
+/**
+ * @param {string} filePath
+ * @returns {SpecMeta}
+ */
+export function readSpecMetaFull(filePath) {
+  const raw = readFileSync(filePath, 'utf8');
+  const m = raw.match(FRONTMATTER);
+  const fm = m?.[1] ?? '';
+  const body = m ? raw.slice(m[0].length) : raw;
+  return {
+    id: fmScalar(fm, 'id'),
+    type: fmScalar(fm, 'type'),
+    status: fmScalar(fm, 'status'),
+    target: fmScalar(fm, 'target'),
+    parent: fmScalar(fm, 'parent'),
+    spec_path: filePath,
+    body,
+  };
+}
+
+/**
+ * @param {string} fm
+ * @param {string} key
+ * @returns {string[]}
+ */
+export function fmWikilinkList(fm, key) {
+  const block = fm.match(new RegExp(`^${key}:\\s*\\n((?:\\s*-\\s+.+\\n?)*)`, 'm'));
+  if (!block) {
+    const scalar = fmScalar(fm, key);
+    if (!scalar) return [];
+    const ids = scalar.match(/HS-[A-Z0-9]+-(?:TASK|EPIC|MIL|DIAG|RES|CAP|REV)(?:-[A-Z0-9]+)?/gi);
+    return ids ?? [];
+  }
+  return block[1]
+    .split(/\r?\n/)
+    .map((line) => line.match(/^\s*-\s+(.+?)\s*$/)?.[1])
+    .filter(Boolean)
+    .flatMap((entry) => {
+      const ids = entry.match(/HS-[A-Z0-9]+-(?:TASK|EPIC|MIL|DIAG|RES|CAP|REV)(?:-[A-Z0-9]+)?/gi);
+      return ids ?? [];
+    });
+}
+
+/**
+ * @param {string | null | undefined} type
+ * @param {string | null | undefined} id
+ */
+export function isSourcePlanningSpec(type, id) {
+  const t = (type ?? '').toLowerCase();
+  if (t === 'diagnose' || t === 'research') return true;
+  const token = id ?? '';
+  return /-DIAG(?:-|$)/i.test(token) || /-RES(?:-|$)/i.test(token);
+}
+
+// ── Phase-1 resolver (HS-5Q41): detect a capture's Phase-1 stage so runPhase1 can enter at the
+// matching step instead of restarting from scratch. A capture (-CAP / type: capture) is a Phase-1
+// pipeline artifact; DIAG/RES keep their own remediation flow (isSourcePlanningSpec) untouched. ──
+
+/** The Phase-1 pipeline stages, ordered raw → plan-draft. */
+export const PHASE1_STAGES = Object.freeze([
+  'raw',
+  'expanded',
+  'research-stub',
+  'research-doc',
+  'plan-draft',
+]);
+
+/**
+ * Stage → runPhase1 entry step (name + index; mirrors dev-factory/pipeline/phase1.mjs STEP).
+ * A later stage skips the earlier steps; at run time the recorded checkpoint still wins over the
+ * hint so a re-pinned artifact never rewinds or restarts.
+ */
+export const PHASE1_STAGE_TO_STEP = Object.freeze({
+  raw: { step: 'expand', index: 0 },
+  expanded: { step: 'classify', index: 2 },
+  'research-stub': { step: 'research_l1', index: 3 },
+  // research-doc has its research done but no plan authored yet → enter at the plan-author step
+  // (index 6) so the plan is actually authored before filing (HS-KMBT-EPIC). plan-draft already
+  // carries a plan → enter at file (now index 7, after PLAN_AUTHOR was inserted at 6).
+  'research-doc': { step: 'plan_author', index: 6 },
+  'plan-draft': { step: 'file', index: 7 },
+});
+
+/**
+ * A spec is a Phase-1 artifact when it is a capture (type: capture or an -CAP id). DIAG/RES route
+ * through isSourcePlanningSpec instead, so this stays orthogonal to the remediation flow.
+ * @param {string | null | undefined} type
+ * @param {string | null | undefined} id
+ */
+export function isPhase1Artifact(type, id) {
+  if ((type ?? '').toLowerCase() === 'capture') return true;
+  return /-CAP(?:-|$)/i.test(id ?? '');
+}
+
+/**
+ * Deterministic Phase-1 stage detection for a capture (frontmatter + section presence, never
+ * semantic). Precedence: (1) explicit `phase1-stage`/`phase1_stage` frontmatter; (2) `capture_status`
+ * (promoted → plan-draft, expanded → at-least-expanded); (3) body section presence. Returns one of
+ * PHASE1_STAGES; unknown/empty inputs resolve to 'raw' (the safe full-pipeline entry).
+ * @param {SpecMeta} meta
+ * @returns {string}
+ */
+export function detectPhase1Stage(meta) {
+  const raw = readFileSync(meta.spec_path, 'utf8');
+  const fmMatch = raw.match(FRONTMATTER);
+  const fm = fmMatch?.[1] ?? '';
+  const body = meta.body ?? (fmMatch ? raw.slice(fmMatch[0].length) : raw);
+
+  // 1) An explicit stage field is authoritative — the caller/pipeline stamped it deliberately.
+  const explicit = (fmScalar(fm, 'phase1-stage') ?? fmScalar(fm, 'phase1_stage'))?.toLowerCase();
+  if (explicit && PHASE1_STAGES.includes(explicit)) return explicit;
+
+  // 2) Genuine research artifacts override the lifecycle field UPWARD. These headings are never in
+  // the raw capture template (which seeds only Core Idea / Notes / Source Material / Summary — a bare
+  // `# Core Idea` heading is NOT proof of expansion), so their presence means real added content:
+  //   - a completed research doc carries BOTH `## Sources` and `## Executive Summary` → research-doc
+  //   - a research stub carries `## Sources` or a `## Research` / `## Findings` heading → research-stub
+  const hasSources = /^##\s+Sources\b/im.test(body);
+  const hasExecSummary = /^##\s+Executive Summary\b/im.test(body);
+  const hasResearchHeading = /^##\s+(Research|Findings)\b/im.test(body);
+  if (hasSources && hasExecSummary) return 'research-doc';
+  if (hasSources || hasResearchHeading) return 'research-stub';
+
+  // 3) `capture_status` is the maintained lifecycle field — authoritative for raw/expanded/promoted.
+  // (Heading presence is deliberately NOT used to infer expanded: the capture template seeds a
+  // `# Core Idea` heading even for raw captures, so inferring expansion from it misreads raw as
+  // expanded — a real defect found driving live captures through the resolver, 2026-07-09.)
+  const capStatus = (fmScalar(fm, 'capture_status') ?? '').toLowerCase();
+  if (capStatus === 'promoted') return 'plan-draft';
+  if (capStatus === 'expanded') return 'expanded';
+
+  // 4) Default: raw (the safe full-pipeline entry) — including when capture_status is absent/unknown.
+  return 'raw';
+}
+
+/**
+ * Resolve a capture to a `mode: phase1` dispatch plan with the detected stage + start-at-step hint,
+ * so `/hs-auto` on a capture (or a mid-stage capture) no longer dead-ends at MISSING_TARGET.
+ * @param {SpecMeta} meta full meta (spec_path + body populated)
+ * @param {string} relPath repo-relative capture path
+ */
+export function resolvePhase1Spec(meta, relPath) {
+  const stage = detectPhase1Stage(meta);
+  const entry = PHASE1_STAGE_TO_STEP[stage] ?? PHASE1_STAGE_TO_STEP.raw;
+  return {
+    mode: 'phase1',
+    spec_id: meta.id,
+    spec_path: relPath,
+    stage,
+    entry_step: entry.step,
+    entry_step_index: entry.index,
+    phase1_command: `node dev-factory/pipeline/phase1.mjs --capture ${relPath} --stage ${stage}`,
+    coo_contract: [
+      'COO orchestration only — Phase-1 resolver (start from any state).',
+      `Run runPhase1 entering at the "${entry.step}" step (stage: ${stage}).`,
+      'Invariant: re-pinning a mid-stage artifact resumes from its recorded checkpoint — never restarts.',
+      'Per-front reach: Handheld advances one checkpoint; Assisted carries to end-of-Phase-1 (milestone + epics filed) then a review gate; Autonomous carries into Phase 2.',
+      'Do NOT implement in Cursor.',
+    ].join('\n'),
+  };
+}
+
+/**
+ * @param {SpecMeta} meta
+ * @param {string} sourceId
+ */
+export function referencesSourceId(meta, sourceId) {
+  const raw = readFileSync(meta.spec_path, 'utf8');
+  const m = raw.match(FRONTMATTER);
+  const fm = m?.[1] ?? '';
+  const haystack = [
+    fmScalar(fm, 'source'),
+    fmScalar(fm, 'remediation_of'),
+    fmScalar(fm, 'diagnose'),
+    fmScalar(fm, 'research'),
+    fmScalar(fm, 'parent'),
+    meta.body,
+  ]
+    .filter(Boolean)
+    .join('\n');
+  return haystack.includes(sourceId);
+}
+
+/**
+ * @param {string} specsDir
+ */
+function walkMarkdown(specsDir) {
+  /** @type {string[]} */
+  const files = [];
+  const walk = (dir) => {
+    if (!existsSync(dir)) return;
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry);
+      if (statSync(full).isDirectory()) walk(full);
+      else if (entry.endsWith('.md')) files.push(full);
+    }
+  };
+  walk(specsDir);
+  return files;
+}
+
+/**
+ * @param {string} repoRoot
+ * @param {string} sourceId
+ * @returns {SpecMeta | null}
+ */
+export function findRemediationEpic(repoRoot, sourceId) {
+  const epicsDir = join(repoRoot, 'specs', 'epics');
+  for (const file of walkMarkdown(epicsDir)) {
+    const meta = readSpecMetaFull(file);
+    if (referencesSourceId(meta, sourceId)) return meta;
+  }
+  return null;
+}
+
+/**
+ * @param {string} repoRoot
+ * @param {string} sourceId
+ * @param {string | null} epicId
+ * @returns {SpecMeta[]}
+ */
+export function findLinkedTasks(repoRoot, sourceId, epicId) {
+  const tasksDir = join(repoRoot, 'specs', 'tasks');
+  /** @type {SpecMeta[]} */
+  const out = [];
+  for (const file of walkMarkdown(tasksDir)) {
+    const meta = readSpecMetaFull(file);
+    const linked =
+      referencesSourceId(meta, sourceId)
+      || (epicId && (meta.parent?.includes(epicId) ?? false));
+    if (linked) out.push(meta);
+  }
+  return out;
+}
+
+const DISPATCHABLE_STATUSES = new Set(['open', 'in_progress']);
+
+/**
+ * @param {SpecMeta[]} tasks
+ * @returns {SpecMeta | null}
+ */
+export function pickDispatchableTask(tasks) {
+  const ready = tasks.filter(
+    (t) => t.target && t.status && DISPATCHABLE_STATUSES.has(t.status),
+  );
+  ready.sort((a, b) => a.spec_path.localeCompare(b.spec_path));
+  return ready[0] ?? null;
+}
+
+/**
+ * @param {string} repoRoot
+ * @param {string} epicId
+ * @returns {number}
+ */
+export function countEpicChildren(repoRoot, epicId) {
+  const epicPath = findSpecFile(join(repoRoot, 'specs'), epicId);
+  if (!epicPath) return 0;
+  const raw = readFileSync(epicPath, 'utf8');
+  const fm = raw.match(FRONTMATTER)?.[1] ?? '';
+  return fmWikilinkList(fm, 'children').length;
+}
+
+/**
+ * @param {string} specPath repo-relative
+ * @param {string} target
+ */
+function buildDispatchCommand(specPath, target) {
+  const specId = basename(specPath, '.md');
+  const checkpoint = `dev-factory/state/checkpoint-${specId}.json`;
+  return [
+    'node dev-factory/controller.mjs',
+    `--spec ${specPath}`,
+    `--target ${target.replace(/\\/g, '/')}`,
+    '--use-scheduler',
+    '--n 3',
+    `--checkpoint ${checkpoint}`,
+  ].join(' ');
+}
+
+/**
+ * @param {string} repoRoot
+ * @param {{ id: string|null, type: string|null, spec_path: string }} sourceMeta
+ * @param {string} relPath repo-relative source path
+ */
+export function resolveSourcePlanningSpec(repoRoot, sourceMeta, relPath) {
+  const sourceId = sourceMeta.id;
+  if (!sourceId) {
+    return {
+      error: 'SOURCE_ID_MISSING',
+      message: `${relPath} has no id: frontmatter.`,
+      spec_path: relPath,
+    };
+  }
+
+  const sourceKind = (sourceMeta.type ?? '').toLowerCase() === 'research' ? 'research' : 'diagnose';
+  const epic = findRemediationEpic(repoRoot, sourceId);
+  const tasks = findLinkedTasks(repoRoot, sourceId, epic?.id ?? null);
+  const dispatchTask = pickDispatchableTask(tasks);
+
+  if (dispatchTask?.id && dispatchTask.target) {
+    const taskRel = relative(repoRoot, dispatchTask.spec_path).replace(/\\/g, '/');
+    return {
+      mode: 'dispatch',
+      spec_id: dispatchTask.id,
+      spec_path: taskRel,
+      target: dispatchTask.target.replace(/\\/g, '/'),
+      source_spec_id: sourceId,
+      source_spec_path: relPath,
+      source_kind: sourceKind,
+      matched_via: 'source_remediation_task',
+      dispatch_command: buildDispatchCommand(taskRel, dispatchTask.target),
+      coo_contract:
+        'COO orchestration only — run preflight, then dispatch_command. Do NOT implement in Cursor unless the gate fails after fleet retries.',
+    };
+  }
+
+  if (epic?.id) {
+    const childCount = countEpicChildren(repoRoot, epic.id);
+    const epicRel = relative(repoRoot, epic.spec_path).replace(/\\/g, '/');
+    if (childCount === 0) {
+      return {
+        mode: 'breakdown',
+        spec_id: epic.id,
+        spec_path: epicRel,
+        source_spec_id: sourceId,
+        source_spec_path: relPath,
+        source_kind: sourceKind,
+        remediation_epic_id: epic.id,
+        breakdown_kind: 'decompose',
+        breakdown_command: `node dev-factory/engine/breakdown.mjs --decompose --epic ${epic.id}`,
+        coo_contract:
+          'COO orchestration only — run preflight, then breakdown_command. Review the JSON draft, file tasks via heyspex_file_spec (each with target:), register linkage, re-run hs auto on the source spec, then dispatch. Do NOT implement in Cursor.',
+      };
+    }
+    return {
+      mode: 'breakdown',
+      spec_id: epic.id,
+      spec_path: epicRel,
+      source_spec_id: sourceId,
+      source_spec_path: relPath,
+      source_kind: sourceKind,
+      remediation_epic_id: epic.id,
+      breakdown_kind: 'incremental',
+      breakdown_command: `node dev-factory/controller.mjs --breakdown-epic ${epic.id}`,
+      linked_tasks_without_target: tasks.filter((t) => !t.target).map((t) => t.id),
+      coo_contract:
+        'COO orchestration only — run preflight, then breakdown_command. Review draft, file any missing tasks with target:, re-run hs auto on the source spec, then dispatch. Do NOT implement in Cursor.',
+    };
+  }
+
+  return {
+    mode: 'source_plan',
+    source_kind: sourceKind,
+    spec_id: sourceId,
+    spec_path: relPath,
+    linked_tasks: tasks.map((t) => ({ id: t.id, status: t.status, target: t.target })),
+    file_epic_intent: 'file_epic',
+    file_task_intent: 'file_task',
+    decompose_command: 'node dev-factory/engine/breakdown.mjs --decompose --epic <REMEDIATION_EPIC_ID>',
+    re_resolve_command: `node bin/hs.mjs auto ${sourceId} --json`,
+    coo_contract: [
+      'COO orchestration only — do NOT implement in Cursor.',
+      '1) Run preflight from JSON.',
+      '2) heyspex_preflight({ intent: "file_epic" }) → heyspex_file_spec a remediation epic (no milestone required). Body: synthesize Decision, Fix slices, Deferred, and Acceptance from the source spec. Frontmatter source: wikilink to this diagnose/research.',
+      '3) heyspex_register_spec(epic_id, parent_id) — parent_id null/omit when no milestone.',
+      '4) node dev-factory/engine/breakdown.mjs --decompose --epic <EPIC_ID> — fleet breakdown seat drafts tasks.',
+      '5) COO reviews draft → heyspex_file_spec each task with target: + acceptance criteria → heyspex_register_spec per task.',
+      '6) Re-run node bin/hs.mjs auto on the source spec → expect mode dispatch.',
+      '7) Run dispatch_command; review gate verdict only.',
+    ].join('\n'),
+    message:
+      `No remediation epic linked to ${sourceId}. File epic + tasks from the source spec, then re-resolve for fleet dispatch.`,
+  };
+}