heyspex 0.1.0

package/vendor/heyspex-mcp/next-review.mjs

@@ -0,0 +1,548 @@
+/**
+ * `heyspex_next_review` resolver — returns the next review-ready spec
+ * (parent body + HS-REV doc + prompt markdown) for the reviewer agent.
+ *
+ * [[HS-TASK-RVDC-heyspex-review-on-deck-mcp-and-hs-review]] · [[HS-RES-CLR4-close-out-review-screen-jtbd-architecture]] §J17
+ *
+ * Mirrors `resolveNextOnDeckPayload` in cli.mjs, but filters to `status: in_review`
+ * specs that have an `HS-REV-<suffix>-*.md` companion. Cli.mjs supplies the
+ * shared helpers (`findSpecFile`, `loadSpec`, `loadRoadmap`, `loadTask`) via
+ * dependency injection so tests can stub them.
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+import { readMvpModeState } from './mvp-mode.mjs';
+import { loadReviewFocus } from './review-focus.mjs';
+import { extractSpecSuffix, findReviewDocForSpec } from './spec-id-lib.mjs';
+
+const STATUS_IN_REVIEW = 'in_review';
+
+/**
+ * Active review grain ([[HS-EPIC-7CWZ]]) — the spec kind that crosses the
+ * build→review boundary, so the only kind eligible for the Review queue. MVP off
+ * (or no `review_grain`) ⇒ `task` (today's behavior); MVP on ⇒ the configured
+ * grain (`milestone` / `epic` / `task`). Mirror of the console `resolveNextReview`
+ * grain filter so the agent (`heyspex_next_review`) and the console agree.
+ */
+function activeReviewGrain(vaultRoot) {
+  const state = readMvpModeState(vaultRoot);
+  const g = state?.review_grain;
+  return g === 'task' || g === 'epic' || g === 'milestone' ? g : 'task';
+}
+
+/** Spec kind from a loaded spec/task, lowercased. */
+function specKind(spec) {
+  return String(spec?.frontmatter?.type ?? spec?.type ?? '').toLowerCase();
+}
+
+/**
+ * Resolve the next review-ready spec.
+ *
+ * Algorithm (spec §1):
+ *   1. If `args.spec_id` provided → fetch that spec's review context directly.
+ *   2. Else if `.heyspex/review-focus.yaml` exists and `ignore_focus !== true`
+ *      → honor that pin.
+ *   3. Else walk the roadmap manifest phases and collect specs with
+ *      `status: in_review` + HS-REV companion.
+ *   4. If the manifest yields no candidates, scan `specs/tasks/` and
+ *      `specs/epics/` directly so off-manifest in_review specs still surface.
+ *   5. Sort candidates by `updated:` ascending (oldest first, mirrors
+ *      HS-RES-CLR4 §J2 aging signal) and return the first match.
+ *
+ * @param {string} vaultRoot
+ * @param {{ defaultRoadmapId?: string }} config
+ * @param {{ spec_id?: string, roadmap_id?: string, ignore_focus?: boolean }} args
+ * @param {{ findSpecFile: Function, loadSpec: Function, loadRoadmap: Function, loadTask: Function }} deps
+ * @returns {{ result?: object, error?: object }}
+ */
+export function resolveNextReviewPayload(vaultRoot, config, args = {}, deps) {
+  if (!deps || !deps.findSpecFile || !deps.loadSpec || !deps.loadTask) {
+    return {
+      error: {
+        error: 'MISSING_DEPS',
+        message:
+          'resolveNextReviewPayload requires deps { findSpecFile, loadSpec, loadRoadmap, loadTask }',
+      },
+    };
+  }
+
+  const roadmapId = args.roadmap_id || config?.defaultRoadmapId || 'HS-ROADMAP-PRODUCT';
+  const ignoreFocus = args.ignore_focus === true || args.ignore_focus === 'true';
+
+  // 1) Direct lookup
+  if (args.spec_id) {
+    return buildPayloadForSpec(
+      vaultRoot,
+      args.spec_id,
+      roadmapId,
+      'direct_lookup',
+      { phase_id: 'direct', phase_name: 'Direct lookup' },
+      deps,
+    );
+  }
+
+  // 2) review-focus.yaml pin
+  if (!ignoreFocus) {
+    const focus = loadReviewFocus(vaultRoot);
+    if (focus && focus.spec_id) {
+      const result = buildPayloadForSpec(
+        vaultRoot,
+        focus.spec_id,
+        roadmapId,
+        'review_focus',
+        { phase_id: 'review_focus', phase_name: 'Pinned review' },
+        deps,
+      );
+      if (result.result) {
+        if (focus.reason) result.result.focus_reason = focus.reason;
+        if (focus.pinned_at) result.result.pinned_at = focus.pinned_at;
+      }
+      return result;
+    }
+  }
+
+  // Active review grain — only units of this kind are eligible for the queue
+  // ([[HS-EPIC-7CWZ]] AC#7).
+  const grain = activeReviewGrain(vaultRoot);
+
+  // 3) Manifest traversal
+  let candidates = collectInReviewCandidates(vaultRoot, roadmapId, deps);
+
+  // 4) Folder-scan fallback
+  if (candidates.length === 0) {
+    const scanned = scanInReviewFromFolders(vaultRoot, deps, grain);
+    for (const item of scanned) candidates.push(item);
+  }
+
+  // Grain-filter: keep only units whose kind IS the active review grain.
+  candidates = candidates.filter((c) => specKind(c.spec) === grain);
+
+  if (candidates.length === 0) {
+    return {
+      error: {
+        error: 'NO_REVIEW_READY',
+        message: `No status: in_review specs at the active review grain (${grain}) with the required companion found.`,
+      },
+    };
+  }
+
+  // 5) Sort by updated: ascending (oldest first)
+  candidates.sort((a, b) => {
+    const ua = String(a.spec.frontmatter?.updated || '');
+    const ub = String(b.spec.frontmatter?.updated || '');
+    return ua.localeCompare(ub);
+  });
+
+  const pick = candidates[0];
+  return buildPayloadForSpec(
+    vaultRoot,
+    pick.spec.frontmatter.id || pick.spec.id,
+    roadmapId,
+    'review_queue',
+    { phase_id: pick.phaseId, phase_name: pick.phaseName },
+    deps,
+    { reviewDocPath: pick.reviewDocPath, specPath: pick.specPath },
+  );
+}
+
+function collectInReviewCandidates(vaultRoot, roadmapId, deps) {
+  const { loadRoadmap, loadTask } = deps;
+  if (!loadRoadmap) return [];
+  const roadmap = loadRoadmap(vaultRoot, roadmapId);
+  if (!roadmap) return [];
+  const manifest = roadmap.frontmatter?.roadmap_manifest;
+  if (!manifest || !Array.isArray(manifest.phases)) return [];
+
+  const candidates = [];
+  const seen = new Set();
+  for (const phase of manifest.phases) {
+    for (const taskId of phase.tasks || []) {
+      if (seen.has(taskId)) continue;
+      seen.add(taskId);
+      const task = loadTask?.(vaultRoot, taskId);
+      if (!task || task.status !== STATUS_IN_REVIEW) continue;
+      const specId = task.frontmatter?.id || taskId;
+      const reviewDocPath = findReviewDocForSpec(vaultRoot, specId);
+      if (!reviewDocPath) continue;
+      candidates.push({
+        spec: task,
+        phaseId: phase.id,
+        phaseName: phase.name,
+        reviewDocPath,
+        specPath: task.specPath,
+      });
+    }
+  }
+  return candidates;
+}
+
+function scanInReviewFromFolders(vaultRoot, deps, grain = 'task') {
+  const { loadSpec } = deps;
+  // Scan the folder for the active grain. A milestone is the MVP review unit and
+  // qualifies on its own (its "review doc" is its own acceptance gate) — `HS-MIL-*`
+  // ids aren't covered by extractSpecSuffix either, so don't require an HS-REV
+  // companion for it (mirrors the console `resolveNextReview` isMilestone branch).
+  const FOLDER_BY_GRAIN = {
+    task: ['specs/tasks'],
+    epic: ['specs/epics'],
+    milestone: ['specs/milestones'],
+  };
+  const folders = FOLDER_BY_GRAIN[grain] ?? ['specs/tasks'];
+  const requireReviewDoc = grain !== 'milestone';
+  const candidates = [];
+  for (const rel of folders) {
+    const full = join(vaultRoot, rel);
+    if (!existsSync(full)) continue;
+    let entries;
+    try {
+      entries = readdirSync(full);
+    } catch {
+      continue;
+    }
+    for (const file of entries) {
+      if (!file.endsWith('.md')) continue;
+      const specPath = `${rel}/${file}`;
+      const spec = loadSpec(vaultRoot, specPath);
+      if (!spec || spec.frontmatter?.status !== STATUS_IN_REVIEW) continue;
+      const specId = spec.frontmatter?.id || file.replace(/\.md$/i, '');
+      const reviewDocPath = findReviewDocForSpec(vaultRoot, specId);
+      if (!reviewDocPath && requireReviewDoc) continue;
+      candidates.push({
+        spec: { ...spec, id: specId, specPath },
+        phaseId: 'unscheduled',
+        phaseName: 'Unscheduled (off-manifest in_review)',
+        reviewDocPath: reviewDocPath ?? null,
+        specPath,
+      });
+    }
+  }
+  return candidates;
+}
+
+function buildPayloadForSpec(
+  vaultRoot,
+  specId,
+  roadmapId,
+  sourceKind,
+  phaseInfo,
+  deps,
+  prefetched = {},
+) {
+  const { findSpecFile, loadSpec } = deps;
+  const specPath = prefetched.specPath || findSpecFile?.(vaultRoot, specId);
+  if (!specPath) {
+    return {
+      error: {
+        error: 'SPEC_NOT_FOUND',
+        message: `Spec ${specId} not found in vault`,
+      },
+    };
+  }
+  const spec = loadSpec(vaultRoot, specPath);
+  if (!spec) {
+    return {
+      error: {
+        error: 'SPEC_LOAD_FAILED',
+        message: `Could not load spec at ${specPath}`,
+      },
+    };
+  }
+  if (spec.frontmatter?.status && spec.frontmatter.status !== STATUS_IN_REVIEW) {
+    return {
+      error: {
+        error: 'SPEC_NOT_IN_REVIEW',
+        message: `Spec ${specId} has status: ${spec.frontmatter.status}, not in_review.`,
+        status: spec.frontmatter.status,
+        spec_path: specPath,
+      },
+    };
+  }
+  // A milestone is reviewed via its own acceptance gate, not an HS-REV companion
+  // ([[HS-EPIC-7CWZ]] milestone grain) — don't require one.
+  const isMilestone = specKind(spec) === 'milestone';
+  const reviewDocPath =
+    prefetched.reviewDocPath || findReviewDocForSpec(vaultRoot, specId) || null;
+  if (!reviewDocPath && !isMilestone) {
+    return {
+      error: {
+        error: 'NO_REVIEW_DOC',
+        message: `Spec ${specId} has no HS-${extractSpecSuffix(specId)}-REV-*.md companion in specs/reviews/.`,
+        spec_path: specPath,
+      },
+    };
+  }
+  let reviewDocBody = '';
+  if (reviewDocPath) {
+    try {
+      reviewDocBody = readFileSync(join(vaultRoot, reviewDocPath), 'utf-8');
+    } catch {
+      /* leave empty — prompt will note the missing body */
+    }
+  }
+
+  const inReviewChangelogRow = extractInReviewChangelogRow(spec.body);
+  const filesChanged = listFilesChangedSinceFlip(vaultRoot, specPath);
+  const ageDays = computeAgeDays(spec.frontmatter?.updated);
+  const parentBasename = specPath
+    .split(/[\\/]/)
+    .pop()
+    .replace(/\.md$/i, '');
+
+  const promptMarkdown = buildHsReviewPromptMarkdown({
+    specId,
+    title: spec.frontmatter?.name || specId,
+    status: spec.frontmatter?.status || STATUS_IN_REVIEW,
+    sourceKind,
+    parentBasename,
+    parentSpecBody: spec.body,
+    reviewDocPath,
+    reviewDocBody: stripFrontmatter(reviewDocBody),
+    inReviewChangelogRow,
+    filesChanged,
+    phaseId: phaseInfo.phase_id,
+    phaseName: phaseInfo.phase_name,
+    ageDays,
+    parentSpecPath: specPath,
+  });
+
+  const result = {
+    spec_id: specId,
+    title: spec.frontmatter?.name || specId,
+    status: STATUS_IN_REVIEW,
+    source_kind: sourceKind,
+    phase_id: phaseInfo.phase_id,
+    roadmap_id: roadmapId,
+    parent_spec_path: specPath,
+    review_doc_path: reviewDocPath,
+    in_review_changelog_row: inReviewChangelogRow,
+    files_changed: filesChanged,
+    // user_prompt_markdown is the canonical user-facing field after [[HS-TASK-HSNX]]
+    // unified the wire shape across agent-dispatch tools. next_review has no
+    // agent-dispatch object today (the reviewer is human; no routing needed),
+    // so prompt_markdown still mirrors it for back-compat consumers.
+    user_prompt_markdown: promptMarkdown,
+    prompt_markdown: promptMarkdown,
+    resolved_at: new Date().toISOString(),
+  };
+  if (phaseInfo.phase_name) result.phase_name = phaseInfo.phase_name;
+  if (typeof ageDays === 'number') result.age_in_review_days = ageDays;
+
+  return { result };
+}
+
+/**
+ * Parse the parent spec's `## Change log` table and return the row that
+ * most likely represents the in_review flip.
+ *
+ * Heuristic (in order):
+ *   1. If any row's change-text mentions `in_review` / `in review` /
+ *      "review", return the most recent such row.
+ *   2. Else return the last row of the table — by convention the most
+ *      recent change-log entry is appended at the bottom, and flipping to
+ *      `in_review` happens at session close so it is typically the last
+ *      author-stamped change.
+ *
+ * Returns the row verbatim (table pipe-syntax preserved) or null if there
+ * is no `## Change log` table or no data rows.
+ */
+export function extractInReviewChangelogRow(body) {
+  if (!body) return null;
+  const m = body.match(/##\s+Change log\s*\n([\s\S]*)$/i);
+  if (!m) return null;
+  const lines = m[1].split(/\r?\n/);
+  const matchPattern = /\bin[_ -]?review\b|status:\s*review/i;
+  let explicitMatch = null;
+  let lastDataRow = null;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|')) continue;
+    if (trimmed.includes('---')) continue;
+    if (/^\|\s*Date\s*\|/i.test(trimmed)) continue;
+    lastDataRow = trimmed;
+    if (matchPattern.test(trimmed)) {
+      explicitMatch = trimmed;
+    }
+  }
+  return explicitMatch || lastDataRow;
+}
+
+/**
+ * List files the reviewer is likely to need to inspect.
+ *
+ * Per CLAUDE.md the agent does NOT commit at session close — they flip the
+ * spec to `in_review` and leave the working tree dirty for the reviewer.
+ * So the most useful file list is:
+ *
+ *   1. **Working-tree changes** (`git status --porcelain` — staged + unstaged
+ *      + untracked) when the tree is dirty — this is the agent's just-finished
+ *      work, exactly what the reviewer needs to walk.
+ *   2. **Last commit's files** (`git show --name-only HEAD`) when the tree is
+ *      clean — likely the close-out / review commit for an older in_review
+ *      spec that was already committed.
+ *
+ * Either source is filtered to `interestingPrefixes` (so node_modules / log
+ * noise drops out) and capped at `maxFiles` to avoid blasting the prompt.
+ * Returns [] gracefully if git isn't available.
+ */
+export function listFilesChangedSinceFlip(vaultRoot, specPath, options = {}) {
+  const interestingPrefixes = options.interestingPrefixes || [
+    'spex-console/',
+    'vendor/',
+    'scripts/',
+    'specs/',
+    'companion/',
+    'pm-control-center/',
+    '.claude/',
+    '.cursor/',
+  ];
+  const maxFiles = options.maxFiles || 50;
+  const filterAndCap = (list) =>
+    list
+      .filter((p) => interestingPrefixes.some((prefix) => p.startsWith(prefix)))
+      .slice(0, maxFiles);
+
+  try {
+    const porcelain = execSync('git status --porcelain', {
+      cwd: vaultRoot,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const dirty = porcelain
+      .split(/\r?\n/)
+      .map((line) => {
+        const m = line.match(/^[ MADRCU?!]{1,2}\s+(.+?)(?:\s+->\s+(.+))?$/);
+        if (!m) return null;
+        return (m[2] || m[1]).replace(/^"|"$/g, '');
+      })
+      .filter(Boolean);
+
+    if (dirty.length > 0) {
+      return filterAndCap(dirty);
+    }
+
+    // Working tree is clean — fall back to the last commit.
+    const showOutput = execSync('git show --name-only --pretty=format: HEAD', {
+      cwd: vaultRoot,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const committed = showOutput
+      .split(/\r?\n/)
+      .map((s) => s.trim())
+      .filter(Boolean);
+    return filterAndCap(committed);
+  } catch {
+    return [];
+  }
+}
+
+function computeAgeDays(updatedIso) {
+  if (!updatedIso) return null;
+  const t = Date.parse(String(updatedIso));
+  if (Number.isNaN(t)) return null;
+  return Math.max(0, Math.floor((Date.now() - t) / (1000 * 60 * 60 * 24)));
+}
+
+function stripFrontmatter(content) {
+  if (!content) return '';
+  const m = content.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?([\s\S]*)$/);
+  return (m ? m[1] : content).trim();
+}
+
+/**
+ * Group a flat file list by top-level folder, producing a bulleted markdown
+ * block. Returns `(none detected — review the parent spec body directly)`
+ * when the list is empty.
+ */
+export function renderFilesChangedBlock(files) {
+  if (!Array.isArray(files) || files.length === 0) {
+    return '(none detected — review the parent spec body directly)';
+  }
+  const groups = new Map();
+  for (const f of files) {
+    const top = f.split('/')[0] || '(root)';
+    if (!groups.has(top)) groups.set(top, []);
+    groups.get(top).push(f);
+  }
+  const lines = [];
+  for (const [top, paths] of [...groups].sort((a, b) => a[0].localeCompare(b[0]))) {
+    lines.push(`- **${top}/** (${paths.length})`);
+    for (const p of paths.sort()) {
+      lines.push(`  - \`${p}\``);
+    }
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Build the verbatim prompt markdown for `/hs-review`. See the template in
+ * [[HS-TASK-RVDC-heyspex-review-on-deck-mcp-and-hs-review]] §1 `prompt_markdown`.
+ */
+export function buildHsReviewPromptMarkdown(input) {
+  const {
+    specId,
+    title,
+    status,
+    sourceKind,
+    parentBasename,
+    parentSpecBody,
+    reviewDocPath,
+    reviewDocBody,
+    inReviewChangelogRow,
+    filesChanged,
+    phaseId,
+    phaseName,
+    ageDays,
+    parentSpecPath,
+  } = input;
+
+  const suffix = extractSpecSuffix(specId) || 'UNKNOWN';
+  const headerKind = sourceKind === 'review_focus' ? 'review_focus' : 'review_queue';
+  const ageStr = typeof ageDays === 'number' ? `${ageDays} day${ageDays === 1 ? '' : 's'}` : 'unknown';
+  const phaseStr = phaseName ? `${phaseName} (${phaseId})` : phaseId || 'unknown';
+  const flippedLine = inReviewChangelogRow
+    ? inReviewChangelogRow
+    : '_(no `in_review` row found in the parent spec\'s `## Change log` table)_';
+
+  return `## ${headerKind} — HS-${suffix}-REV
+
+**Parent spec:** [[${parentBasename}]] (status: ${status}, age in review: ${ageStr})
+**Title:** ${title}
+**Phase:** ${phaseStr}
+**Review doc:** \`${reviewDocPath}\`
+**Flipped to in_review:** ${flippedLine}
+
+---
+
+# Parent spec body
+
+${parentSpecBody.trim()}
+
+---
+
+# Review doc — fill-in workspace
+
+${(reviewDocBody || '').trim() || '_(review doc body could not be read — open the file directly)_'}
+
+---
+
+# Files changed since in_review flip
+
+${renderFilesChangedBlock(filesChanged)}
+
+---
+
+## What to do
+
+Walk the four sections of the review doc in order:
+
+1. **\`## Acceptance verification\`** — tick boxes as you verify each criterion. Add inline deviation notes for anything that doesn't behave as the parent spec describes.
+2. **\`## Reviewer notes\`** — read the agent's session observations. These are the raw material for memory extraction.
+3. **\`## Memory candidates\`** — score each candidate row against the **four-axis rubric**: non-derivability / reusability / surprise-cost / concreteness, 0–3 each. **Threshold ≥ 7/12** to accept.
+   - **Conflict check first.** Each candidate row must include a \`Conflict check\` cell — \`New\`, \`Refines [[existing-memory]]\`, or \`Conflict [[existing-memory]]\`. Resolve any \`Conflict\` row by either updating the existing memory or rejecting the new candidate; **never silently materialize a contradictory memory**. Use \`heyspex_recall_memories\` with relevant tags to enumerate existing memories before scoring.
+4. **\`## Decision: close or reopen\`** — record pass/fail with reasoning. On Pass, the reviewer (human) commits + pushes; the commit IS the close action.
+
+_Spec path: \`${parentSpecPath}\`_`;
+}