heyspex 0.1.0

package/vendor/heyspex-mcp/regen-tasks.mjs

@@ -0,0 +1,326 @@
+/**
+ * heyspex_regen_task + heyspex_regen_tasks_for_epic — user-invoked regen
+ * tools (T6 of [[HS-EPIC-VQZ8]], implementation under [[HS-EPIC-HSN1]]).
+ *
+ * The tools operate in two modes:
+ *
+ *   1. **Brief mode** (no `commit` param). Returns a deterministic context
+ *      brief — parent epic, acceptance criteria, current task body, linked
+ *      plans, sibling tasks. The calling agent reads this and produces a
+ *      new task body in its own thinking.
+ *
+ *   2. **Commit mode** (`commit: true`, `new_body` supplied). Soft-deletes
+ *      the existing task file to `.trash/<epic-slug>/<timestamp>-<basename>.md`,
+ *      then writes the new body in place. Reversible via the `.trash/`
+ *      directory — recovery is `git mv` or copy back from `.trash/`.
+ *
+ * Per [[destructive-action-checklist]] both modes are soft-delete only; no
+ * `fs.unlink`. The brief shape mirrors `buildDecompositionPromptMarkdown` so
+ * agents see a consistent surface across all the breakdown-related tools.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+const TERMINAL_STATUSES = new Set([
+  'closed',
+  'shipped',
+  'in_review',
+  'archived',
+  'cancelled',
+  'duplicate',
+  'hibernated',
+  'superseded',
+]);
+
+function timestamp() {
+  return new Date().toISOString().replace(/[:.]/g, '-');
+}
+
+/**
+ * Soft-delete a spec file to `<vault>/specs/.trash/<bucket>/<ts>-<basename>`.
+ * `bucket` lets the caller group related retirements (e.g. one epic's
+ * batch lands in `.trash/<epic-slug>/`). Returns the absolute path of the
+ * file in `.trash/` so the recovery procedure can find it.
+ */
+export function softDeleteToTrash(vaultRoot, relPath, bucket = 'misc') {
+  const abs = join(vaultRoot, relPath);
+  if (!existsSync(abs)) return { ok: false, error: 'not_found', source: relPath };
+  const basename = relPath.split(/[\\/]/).pop() || `${timestamp()}-spec.md`;
+  const trashDir = join(vaultRoot, 'specs', '.trash', bucket);
+  mkdirSync(trashDir, { recursive: true });
+  const dest = join(trashDir, `${timestamp()}-${basename}`);
+  renameSync(abs, dest);
+  const trashRel = dest.slice(vaultRoot.length).replace(/\\/g, '/').replace(/^\/+/, '');
+  return { ok: true, trash_path: trashRel, original_rel_path: relPath };
+}
+
+function gitLastCommitTime(vaultRoot, relPath) {
+  try {
+    const out = execFileSync('git', ['log', '-1', '--format=%ct', '--', relPath], {
+      cwd: vaultRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const secs = Number(out.trim());
+    return Number.isFinite(secs) ? new Date(secs * 1000).toISOString() : null;
+  } catch {
+    return null;
+  }
+}
+
+function loadSpecRecord(loadTask, ref) {
+  if (!ref || typeof loadTask !== 'function') return null;
+  const t = loadTask(ref);
+  return t || null;
+}
+
+function summarizeSpec(spec) {
+  if (!spec) return null;
+  const fm = spec.frontmatter || {};
+  return {
+    id: spec.id || fm.id,
+    name: spec.name || fm.name,
+    type: spec.type || fm.type,
+    status: spec.status || fm.status || 'unknown',
+    rel_path: spec.relPath || spec.rel_path || spec.specPath || null,
+    body: spec.body || '',
+  };
+}
+
+function wikilinkTarget(raw) {
+  if (typeof raw !== 'string') return null;
+  const m = raw.match(/\[\[([^\]]+)\]\]/);
+  return (m ? m[1].trim() : raw.trim()) || null;
+}
+
+function parentEpicOf(task, loadTask) {
+  const parentRef = wikilinkTarget(task?.frontmatter?.parent);
+  if (!parentRef) return null;
+  return loadSpecRecord(loadTask, parentRef);
+}
+
+function siblingTasksOf(epic, loadTask, excludeId) {
+  const refs = Array.isArray(epic?.frontmatter?.children)
+    ? epic.frontmatter.children.map(wikilinkTarget).filter(Boolean)
+    : [];
+  const out = [];
+  for (const ref of refs) {
+    const t = loadSpecRecord(loadTask, ref);
+    if (!t) continue;
+    if ((t.id || t.frontmatter?.id) === excludeId) continue;
+    out.push(summarizeSpec(t));
+  }
+  return out;
+}
+
+function relatedPlans(spec) {
+  const fm = spec?.frontmatter || {};
+  return (Array.isArray(fm.related) ? fm.related : []).map(wikilinkTarget).filter(Boolean);
+}
+
+function epicSlugFromRel(relPath) {
+  // specs/epics/HS-EPIC-XXXX-slug.md → HS-EPIC-XXXX-slug
+  if (!relPath) return 'misc';
+  const basename = relPath.split(/[\\/]/).pop() || '';
+  return basename.replace(/\.md$/i, '') || 'misc';
+}
+
+/**
+ * `heyspex_regen_task` — single-task regen.
+ *
+ *   - Brief mode: returns context for the agent to author a new task body.
+ *   - Commit mode (`commit: true` + `new_body`): soft-delete old to `.trash/`,
+ *     write `new_body` in its place.
+ *
+ * Both modes return `{ ok, mode, task, epic, brief?, commit_result? }`.
+ */
+export function executeRegenTask(vaultRoot, { task_id, commit = false, new_body, retire_reason, loadTask }) {
+  if (!task_id) {
+    return { ok: false, error: 'MISSING_TASK_ID', message: 'task_id is required' };
+  }
+  const task = loadSpecRecord(loadTask, task_id);
+  if (!task) {
+    return { ok: false, error: 'TASK_NOT_FOUND', task_id };
+  }
+  const taskSummary = summarizeSpec(task);
+  if (!taskSummary) {
+    return { ok: false, error: 'TASK_INVALID', task_id };
+  }
+  const epic = parentEpicOf(task, loadTask);
+  const epicSummary = epic ? summarizeSpec(epic) : null;
+
+  if (commit) {
+    if (typeof new_body !== 'string' || !new_body.trim()) {
+      return {
+        ok: false,
+        error: 'MISSING_NEW_BODY',
+        message: 'commit: true requires non-empty new_body',
+      };
+    }
+    if (!taskSummary.rel_path) {
+      return { ok: false, error: 'NO_REL_PATH', task_id };
+    }
+    const bucket = epicSummary ? epicSlugFromRel(epicSummary.rel_path) : 'misc';
+    const deletion = softDeleteToTrash(vaultRoot, taskSummary.rel_path, bucket);
+    if (!deletion.ok) {
+      return { ok: false, error: 'TRASH_FAILED', detail: deletion };
+    }
+    // Write the new body at the original rel_path. The agent's new_body is
+    // expected to include frontmatter; if it doesn't, we don't reconstruct
+    // it — that's an agent error and surfaces as a malformed spec at the
+    // next /hs-next.
+    const destAbs = join(vaultRoot, taskSummary.rel_path);
+    mkdirSync(dirname(destAbs), { recursive: true });
+    writeFileSync(destAbs, new_body, 'utf8');
+    return {
+      ok: true,
+      mode: 'commit',
+      task: { id: taskSummary.id, rel_path: taskSummary.rel_path },
+      retired_to: deletion.trash_path,
+      retire_reason: retire_reason || null,
+      epic: epicSummary ? { id: epicSummary.id } : null,
+      message:
+        `Soft-deleted previous body to ${deletion.trash_path}; wrote new body at ${taskSummary.rel_path}. ` +
+        `Recovery: git restore or copy from ${deletion.trash_path}.`,
+    };
+  }
+
+  // Brief mode — return the context the agent needs to author the new body.
+  return {
+    ok: true,
+    mode: 'brief',
+    task: {
+      ...taskSummary,
+      last_git_commit_at: gitLastCommitTime(vaultRoot, taskSummary.rel_path),
+    },
+    epic: epicSummary
+      ? {
+          ...epicSummary,
+          last_git_commit_at: gitLastCommitTime(vaultRoot, epicSummary.rel_path),
+        }
+      : null,
+    sibling_tasks: epic ? siblingTasksOf(epic, loadTask, taskSummary.id) : [],
+    related_plans: relatedPlans(task),
+    next_action:
+      'Author a new task body (markdown + frontmatter) grounded in the epic acceptance criteria + ' +
+      'related_plans + any context from sibling_tasks. Then re-call this tool with ' +
+      "`{ task_id, commit: true, new_body, retire_reason }` to soft-delete the old body and write the new one.",
+  };
+}
+
+/**
+ * `heyspex_regen_tasks_for_epic` — epic-scope Stage-1-2-3 regen.
+ *
+ *   - Brief mode: returns the context the agent needs (epic acceptance,
+ *     all current tasks, linked plans) plus an ordered Stage-1-2-3 plan.
+ *   - Commit mode (`commit: true` + `task_specs[]`): each entry is either
+ *     `{ id, new_body, retire_reason }` (replace existing) or `{ new_id, body, rel_path }`
+ *     (file new). Each retirement soft-deletes to `.trash/<epic-slug>/`.
+ *
+ * The tool is deliberately deterministic — the LLM thinking happens between
+ * brief mode and commit mode in the calling agent.
+ */
+export function executeRegenTasksForEpic(vaultRoot, { epic_id, commit = false, task_specs, loadTask }) {
+  if (!epic_id) {
+    return { ok: false, error: 'MISSING_EPIC_ID', message: 'epic_id is required' };
+  }
+  const epic = loadSpecRecord(loadTask, epic_id);
+  if (!epic) {
+    return { ok: false, error: 'EPIC_NOT_FOUND', epic_id };
+  }
+  const epicSummary = summarizeSpec(epic);
+  if (!epicSummary || (epicSummary.type || '').toLowerCase() !== 'epic') {
+    return { ok: false, error: 'NOT_AN_EPIC', epic_id };
+  }
+  const childRefs = Array.isArray(epic.frontmatter?.children)
+    ? epic.frontmatter.children.map(wikilinkTarget).filter(Boolean)
+    : [];
+  const currentTasks = [];
+  for (const ref of childRefs) {
+    const t = loadSpecRecord(loadTask, ref);
+    if (!t) continue;
+    currentTasks.push({
+      ...summarizeSpec(t),
+      last_git_commit_at: gitLastCommitTime(vaultRoot, t.relPath || t.rel_path || t.specPath),
+    });
+  }
+
+  if (commit) {
+    if (!Array.isArray(task_specs)) {
+      return {
+        ok: false,
+        error: 'MISSING_TASK_SPECS',
+        message: 'commit: true requires task_specs: [{ id, new_body, retire_reason } | { new_id, body, rel_path }]',
+      };
+    }
+    const bucket = epicSlugFromRel(epicSummary.rel_path);
+    const retired = [];
+    const wrote = [];
+    const errors = [];
+    for (const entry of task_specs) {
+      if (entry && typeof entry === 'object' && entry.id && typeof entry.new_body === 'string') {
+        const target = loadSpecRecord(loadTask, entry.id);
+        const rel = target?.relPath || target?.rel_path || target?.specPath;
+        if (!rel) {
+          errors.push({ id: entry.id, error: 'NO_REL_PATH' });
+          continue;
+        }
+        const del = softDeleteToTrash(vaultRoot, rel, bucket);
+        if (!del.ok) {
+          errors.push({ id: entry.id, error: 'TRASH_FAILED', detail: del });
+          continue;
+        }
+        const abs = join(vaultRoot, rel);
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, entry.new_body, 'utf8');
+        retired.push({ id: entry.id, trash_path: del.trash_path, retire_reason: entry.retire_reason || null });
+        wrote.push({ id: entry.id, rel_path: rel });
+      } else if (entry && typeof entry === 'object' && entry.new_id && typeof entry.body === 'string' && entry.rel_path) {
+        const abs = join(vaultRoot, entry.rel_path);
+        if (existsSync(abs)) {
+          errors.push({ new_id: entry.new_id, error: 'CONFLICT', rel_path: entry.rel_path });
+          continue;
+        }
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, entry.body, 'utf8');
+        wrote.push({ id: entry.new_id, rel_path: entry.rel_path });
+      } else {
+        errors.push({ entry, error: 'INVALID_SHAPE' });
+      }
+    }
+    return {
+      ok: errors.length === 0,
+      mode: 'commit',
+      epic: { id: epicSummary.id },
+      retired,
+      wrote,
+      errors,
+      bucket,
+      message:
+        `Stage-1-2-3 commit for ${epicSummary.id}: retired ${retired.length}, wrote ${wrote.length}, errors ${errors.length}.` +
+        ` Recovery from .trash/specs/.trash/${bucket}/.`,
+    };
+  }
+
+  // Brief mode — Stage 1-2-3 instructions + context.
+  return {
+    ok: true,
+    mode: 'brief',
+    epic: {
+      ...epicSummary,
+      last_git_commit_at: gitLastCommitTime(vaultRoot, epicSummary.rel_path),
+    },
+    current_tasks: currentTasks,
+    open_task_count: currentTasks.filter((t) => !TERMINAL_STATUSES.has(String(t.status).toLowerCase())).length,
+    related_plans: relatedPlans(epic),
+    stage_1_generate:
+      'Read the epic Acceptance criteria + related_plans. Ignore current_tasks at this step. Produce a fresh task set, one per acceptance section.',
+    stage_2_reconcile:
+      'Compare your fresh set against current_tasks. Fold residual value (e.g. a child task that captured a constraint not in the acceptance criteria) into the new set. Mark which current_tasks are superseded.',
+    stage_3_retire:
+      "Re-call this tool with `{ epic_id, commit: true, task_specs: [{ id, new_body, retire_reason }, ...] }` to soft-delete superseded tasks to .trash/ and write the new bodies. New tasks not replacing an existing one use the `{ new_id, body, rel_path }` shape.",
+    recovery: 'All retired bodies land in .trash/specs/.trash/<epic-slug>/; recoverable via git or copy.',
+  };
+}