@brainervirus/workit-core 0.4.0

package/src/core/docs-repo.ts

@@ -0,0 +1,196 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import os from "node:os";
+import path from "node:path";
+
+const configPath = () =>
+  process.env.WORKFLOW_DOCS_REPO_CONFIG
+  ?? path.join(os.homedir(), ".config", "workflow-toolkit", "docs-repo.json");
+
+export const readDocsRepoConfig = (): { path: string } | null => {
+  try {
+    const parsed = JSON.parse(readFileSync(configPath(), "utf8")) as { path?: string };
+    return parsed.path ? { path: parsed.path } : null;
+  } catch {
+    return null;
+  }
+};
+
+export const writeDocsRepoConfig = (docsPath: string): void => {
+  const file = configPath();
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify({ path: docsPath }, null, 2) + "\n", "utf8");
+};
+
+export const docsRepoPath = (): string | null => readDocsRepoConfig()?.path ?? null;
+
+export const validateDocsRepo = (docsPath: string): { ok: true } | { ok: false; error: string } => {
+  if (!existsSync(docsPath)) return { ok: false, error: `docs repo path does not exist: ${docsPath}` };
+  try {
+    execFileSync("git", ["-C", docsPath, "rev-parse", "--is-inside-work-tree"], { stdio: "pipe" });
+  } catch {
+    return { ok: false, error: `docs repo is not a git repository: ${docsPath}` };
+  }
+  const featuresDir = path.join(docsPath, "features");
+  if (!existsSync(featuresDir)) mkdirSync(featuresDir, { recursive: true });
+  return { ok: true };
+};
+
+export const linkDocsRepo = (
+  docsPath: string,
+  confirmed: boolean,
+): { ok: true; path: string } | { ok: false; error: string } => {
+  if (!confirmed) return { ok: false, error: "confirmed: true required" };
+  const valid = validateDocsRepo(docsPath);
+  if (!valid.ok) return valid;
+  writeDocsRepoConfig(docsPath);
+  return { ok: true, path: docsPath };
+};
+
+export const listSpecs = (
+  workspaceRoot: string,
+): { docs_repo: string | null; specs: { slug: string; spec: string; promoted: boolean; target: string | null }[] } => {
+  const repoPath = docsRepoPath();
+  const specs: { slug: string; spec: string; promoted: boolean; target: string | null }[] = [];
+  const docsDir = path.join(workspaceRoot, "docs");
+  if (existsSync(docsDir)) {
+    for (const slug of readdirSync(docsDir)) {
+      if (slug.startsWith(".")) continue;
+      const spec = path.posix.join("docs", slug, "spec.md");
+      if (!existsSync(path.join(workspaceRoot, spec))) continue;
+      let promoted = false;
+      let target: string | null = null;
+      if (repoPath) {
+        const featuresDir = path.join(repoPath, "features");
+        if (existsSync(featuresDir)) {
+          const match = readdirSync(featuresDir).find((d) => new RegExp(`^20\\d{2}-\\d{2}-${slug}$`).test(d));
+          if (match) {
+            promoted = true;
+            target = path.join(repoPath, "features", match);
+          }
+        }
+      }
+      specs.push({ slug, spec, promoted, target });
+    }
+  }
+  return { docs_repo: repoPath, specs };
+};
+
+import { docsValidate, qualitySpec } from "./docs-validate";
+
+const monthPrefix = () => {
+  const now = new Date();
+  return `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}`;
+};
+
+const readSafe = (p: string): string | null => {
+  try { return readFileSync(p, "utf8"); } catch { return null; }
+};
+
+const specSummary = (specText: string): string => {
+  const contextMatch = specText.match(/## Context\n\n([\s\S]*?)(?=\n## |\Z)/);
+  if (!contextMatch) return "";
+  const first = contextMatch[1].trim().split("\n").find((l) => l.trim() && !l.startsWith("<!--"));
+  return (first ?? "").trim();
+};
+
+const specRepos = (specText: string): string => {
+  const match = specText.match(/^\*\*Repos:\*\*\s*(.+)$/m);
+  return match?.[1]?.trim() ?? "—";
+};
+
+const SLUG_RE = /^[a-z0-9][a-z0-9._-]*$/i;
+
+export const promoteSpec = (
+  workspaceRoot: string,
+  slug: string,
+  opts: { confirmed: boolean; force?: boolean },
+): { ok: true; target_dir: string; files: string[]; index_updated: boolean }
+  | { ok: false; error: string; findings?: unknown[] } => {
+  if (!opts.confirmed) return { ok: false, error: "confirmed: true required" };
+  if (!SLUG_RE.test(slug)) return { ok: false, error: `invalid slug: ${JSON.stringify(slug)}` };
+  const repoPath = docsRepoPath();
+  if (!repoPath) return { ok: false, error: "docs repo not linked — run workflow_docs_repo_link" };
+  const repoValid = validateDocsRepo(repoPath);
+  if (!repoValid.ok) return { ok: false, error: repoValid.error };
+
+  const specRel = path.posix.join("docs", slug, "spec.md");
+  const planRel = path.posix.join("docs", slug, "plan.md");
+  const specText = readSafe(path.join(workspaceRoot, specRel));
+  if (specText === null) return { ok: false, error: `docs/${slug}/spec.md not found` };
+
+  const planText = readSafe(path.join(workspaceRoot, planRel));
+  if (planText !== null) {
+    const validated = docsValidate({ spec_path: specRel, plan_path: planRel, workspace_root: workspaceRoot });
+    if (validated.ok === false) return { ok: false, error: validated.error };
+  }
+
+  const findings = qualitySpec(specText);
+  const hardFindings = findings.filter((f) => f.severity === "hard");
+  if (hardFindings.length > 0 && !opts.force) {
+    return { ok: false, error: "spec has hard quality findings; pass force: true to override", findings };
+  }
+
+  // SDD working state must be gitignored before promotion
+  if (!opts.force) {
+    const sddDir = path.join(workspaceRoot, "docs", slug, "sdd");
+    if (existsSync(sddDir)) {
+      try {
+        execFileSync("git", ["-C", workspaceRoot, "check-ignore", path.posix.join("docs", slug, "sdd", "progress.md")], { stdio: "pipe" });
+      } catch {
+        return { ok: false, error: `docs/${slug}/sdd/ is not gitignored — add 'docs/*/sdd/' to .gitignore or pass force: true` };
+      }
+    }
+  }
+
+  const prefix = monthPrefix();
+  const featuresDir = path.join(repoPath, "features");
+  const existing = existsSync(featuresDir)
+    ? readdirSync(featuresDir).find((d) => new RegExp(`^20\\d{2}-\\d{2}-${slug}$`).test(d))
+    : undefined;
+  const targetDir = path.join(featuresDir, existing ?? `${prefix}-${slug}`);
+  mkdirSync(targetDir, { recursive: true });
+
+  const files: string[] = ["spec.md"];
+  writeFileSync(path.join(targetDir, "spec.md"), specText, "utf8");
+  if (planText !== null) {
+    writeFileSync(path.join(targetDir, "plan.md"), planText, "utf8");
+    files.push("plan.md");
+  }
+
+  const title = specText.match(/^#\s+(.+)$/m)?.[1]?.trim() ?? slug;
+  const readme = `# Feature: ${title}
+
+**Fecha:** ${prefix}
+**Estado:** Spec en revisión
+**Repos afectados:** ${specRepos(specText)}
+
+## Resumen
+
+${specSummary(specText)}
+
+## Documentación
+
+| Documento | Contenido |
+| --- | --- |
+| [spec.md](./spec.md) | Especificación completa |
+${planText !== null ? "| [plan.md](./plan.md) | Plan de implementación |\n" : ""}`;
+  writeFileSync(path.join(targetDir, "README.md"), readme, "utf8");
+  files.push("README.md");
+
+  const indexPath = path.join(repoPath, "features", "README.md");
+  const indexText = readSafe(indexPath) ?? `# Features\n\nEspecificaciones y planes por feature.\n\n## Features documentadas\n\n| Feature | Repos afectados | Estado |\n| --- | --- | --- |\n`;
+  const row = `| [${slug}](./${prefix}-${slug}/) | ${specRepos(specText)} | Spec en revisión |`;
+  const rowRe = new RegExp(`^\\| \\[${slug}\\]\\([^)]*\\) \\|.*$`, "m");
+  let newIndex: string;
+  if (rowRe.test(indexText)) {
+    newIndex = indexText.replace(rowRe, row);
+  } else if (/^(\| --- \| --- \| --- \|\n)/m.test(indexText)) {
+    newIndex = indexText.replace(/^(\| --- \| --- \| --- \|\n)/m, `$1${row}\n`);
+  } else {
+    newIndex = indexText + `\n${row}\n`;
+  }
+  writeFileSync(indexPath, newIndex, "utf8");
+
+  return { ok: true, target_dir: targetDir, files, index_updated: true };
+};

package/src/core/docs-validate.ts

@@ -0,0 +1,255 @@
+import { existsSync, readFileSync } from "node:fs";
+import { hygieneFiles } from "./hygiene";
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+
+export type DocError = { code: string; message: string; path?: string };
+
+const BRANCH_RE = /^\s*\*+Branch:\*+\s*`?([^`\s|]+)`?\s*$/im;
+const SPEC_LINK_RE = /^\s*\*+Spec:\*+\s*(?:`([^`]+)`|(\S+))\s*$/im;
+const TASK_RE = /^###\s+Task\s+(\d+):\s*(.*)$/i;
+
+const err = (code: string, message: string, path?: string): DocError => {
+  const item: DocError = { code, message };
+  if (path) item.path = path;
+  return item;
+};
+
+const failValidate = (
+  errors: DocError[],
+): { ok: false; errors: DocError[]; error: string } => ({
+  ok: false,
+  errors,
+  error: errors.map((e) => e.message).filter(Boolean).join("; ") || "docs validation failed",
+});
+
+const readBranch = (text: string, label: string): [string | null, DocError | null] => {
+  const match = text.match(BRANCH_RE);
+  if (!match) return [null, err("missing_branch", `**Branch:** feature/* or bugfix/* required in ${label}`)];
+  return [match[1].trim().replace(/`/g, ""), null];
+};
+
+const scanTaskHeadings = (planText: string): [number[], string[], DocError | null] => {
+  const ids: number[] = [];
+  const titles: string[] = [];
+  let inFence = false;
+  for (const line of planText.split("\n")) {
+    if (line.startsWith("```")) { inFence = !inFence; continue; }
+    if (inFence) continue;
+    const match = line.match(TASK_RE);
+    if (match) { ids.push(Number(match[1])); titles.push(match[2].trim()); }
+  }
+  if (ids.length === 0) return [ids, titles, err("task_order", "no ### Task N sections found outside fences")];
+  const expected = ids.map((_, i) => i + 1);
+  const sorted = [...ids].sort((a, b) => a - b);
+  if (JSON.stringify(sorted) !== JSON.stringify(expected) || new Set(ids).size !== ids.length) {
+    return [ids, titles, err("task_order", `task headings must be contiguous from 1..${ids.length}; found ${ids}`)];
+  }
+  return [ids, titles, null];
+};
+
+// Port of scripts/lib/parse-plan-tasks.sh (JSON mode)
+export const parseTasksFromPlan = (planText: string): { id: number; title: string; section_text: string }[] => {
+  const tasks: { id: number; title: string; section_text: string }[] = [];
+  let current: { id: number; title: string; body: string[] } | null = null;
+  let inFence = false;
+  for (const line of planText.split("\n")) {
+    if (line.startsWith("```")) { inFence = !inFence; continue; }
+    if (inFence) continue;
+    const match = line.match(TASK_RE);
+    if (match) {
+      if (current) tasks.push({ id: current.id, title: current.title, section_text: current.body.join("\n") });
+      current = { id: Number(match[1]), title: match[2].trim(), body: [] };
+    } else if (current) {
+      current.body.push(line);
+    }
+  }
+  if (current) tasks.push({ id: current.id, title: current.title, section_text: current.body.join("\n") });
+  return tasks;
+};
+
+export const docsValidate = ({
+  spec_path,
+  plan_path,
+  workspace_root,
+}: {
+  spec_path: string;
+  plan_path: string;
+  workspace_root: string;
+}):
+  | { ok: true; spec: string; plan: string; branch: string; task_count: number; quality: QualityFinding[] }
+  | { ok: false; errors: DocError[]; error: string } => {
+  const cwd = path.resolve(workspace_root);
+  const specAbs = path.isAbsolute(spec_path) ? spec_path : path.join(cwd, spec_path);
+  const planAbs = path.isAbsolute(plan_path) ? plan_path : path.join(cwd, plan_path);
+  const errors: DocError[] = [];
+
+  const read = (p: string): string | null => {
+    try { return readFileSync(p, "utf8"); } catch { return null; }
+  };
+
+  const specText = read(specAbs);
+  const planText = read(planAbs);
+  if (specText === null) errors.push(err("missing_file", `spec not found: ${spec_path}`, spec_path));
+  if (planText === null) errors.push(err("missing_file", `plan not found: ${plan_path}`, plan_path));
+  if (errors.length) return failValidate(errors);
+
+  const [specBranch, specErr] = readBranch(specText!, "spec");
+  if (specErr) errors.push(specErr);
+  const [planBranch, planErr] = readBranch(planText!, "plan");
+  if (planErr) errors.push(planErr);
+
+  const linkMatch = planText!.match(SPEC_LINK_RE);
+  if (!linkMatch) {
+    errors.push(err("missing_spec_link", "**Spec:** link required in plan", plan_path));
+  } else {
+    const linked = (linkMatch[1] ?? linkMatch[2] ?? "").trim();
+    const linkedAbs = path.isAbsolute(linked) ? linked : path.join(cwd, linked);
+    if (path.resolve(linkedAbs) !== path.resolve(specAbs)) {
+      errors.push(err("spec_mismatch", `plan **Spec:** ${linked} does not match spec_path ${spec_path}`, plan_path));
+    }
+  }
+
+  if (specBranch && planBranch && specBranch !== planBranch) {
+    errors.push(err("branch_mismatch", `spec branch ${JSON.stringify(specBranch)} != plan branch ${JSON.stringify(planBranch)}`, plan_path));
+  }
+
+  const [, , taskErr] = scanTaskHeadings(planText!);
+  if (taskErr) errors.push(taskErr);
+
+  if (errors.length) return failValidate(errors);
+
+  const tasks = parseTasksFromPlan(planText!);
+  const [headingIds, headingTitles, headingErr] = scanTaskHeadings(planText!);
+  if (headingErr) return failValidate([headingErr]);
+  if (tasks.length !== headingIds.length) {
+    return failValidate([err("task_order", `parse count ${tasks.length} != heading count ${headingIds.length}`, plan_path)]);
+  }
+  for (let i = 0; i < tasks.length; i++) {
+    if (String(tasks[i].id) !== String(headingIds[i]) || tasks[i].title.trim() !== headingTitles[i]) {
+      return failValidate([err("task_order", `task mismatch at position ${i + 1}`, plan_path)]);
+    }
+  }
+
+  const relSpec = path.isAbsolute(spec_path) ? path.relative(cwd, specAbs) : spec_path;
+  const relPlan = path.isAbsolute(plan_path) ? path.relative(cwd, planAbs) : plan_path;
+  const quality = qualitySpec(specText!);
+  const slug = path.basename(path.dirname(spec_path));
+  if (!sddIgnored(cwd, slug)) {
+    quality.push({
+      code: "sdd_not_ignored",
+      message: `docs/${slug}/sdd/ exists but is not gitignored — add 'docs/*/sdd/' to .gitignore (or run wk-init)`,
+      severity: "hard",
+    });
+  }
+  const hygiene = hygieneFiles(cwd);
+  const hyState = hygiene.state;
+  if (hyState["CHANGELOG.md"] === "missing") quality.push({ code: "changelog_missing", message: "CHANGELOG.md missing — create it with Keep a Changelog format (run wk-init hygiene)", severity: "warning" });
+  if (hyState["CHANGELOG.md"] === "invalid") quality.push({ code: "changelog_invalid_format", message: "CHANGELOG.md lacks ## [Unreleased] — Keep a Changelog format required", severity: "warning" });
+  if (hyState["README.md"] === "missing") quality.push({ code: "readme_missing", message: "README.md missing", severity: "warning" });
+  if (hyState[".editorconfig"] === "missing") quality.push({ code: "editorconfig_missing", message: ".editorconfig missing", severity: "warning" });
+  if (hyState[".gitattributes"] === "missing") quality.push({ code: "gitattributes_missing", message: ".gitattributes missing", severity: "warning" });
+  if (hygiene.openSource && hyState.LICENSE === "missing") quality.push({ code: "license_missing", message: "LICENSE missing (open-source repo)", severity: "warning" });
+  if (hygiene.openSource && hyState["CONTRIBUTING.md"] === "missing") quality.push({ code: "contributing_missing", message: "CONTRIBUTING.md missing (open-source repo)", severity: "warning" });
+  return {
+    ok: true,
+    spec: relSpec,
+    plan: relPlan,
+    branch: specBranch!,
+    task_count: tasks.length,
+    quality,
+  };
+};
+
+export type QualityFinding = {
+  code: string;
+  message: string;
+  severity: "warning" | "hard";
+};
+
+const REQUIRED_SECTIONS = [
+  "## Context",
+  "## Goals",
+  "## Non-goals",
+  "## Architecture",
+  "## Acceptance criteria",
+];
+
+const UI_KEYWORDS = [/\bui\b/, /\binterface\b/, /\bscreen\b/, /\bmodal\b/, /\bform\b/, /\bcomponent\b/];
+const FLOW_KEYWORDS = [/\bflow\b/, /\bpipeline\b/, /\bsequence\b/, /\bdiagram\b/];
+const GLOSSARY_KEYWORDS = [/\bglossary\b/, /\bcontracts?\b/, /\bscope\b/];
+
+const finding = (code: string, message: string, severity: "warning" | "hard"): QualityFinding =>
+  ({ code, message, severity });
+
+// Replace fenced code blocks with a single marker line so their content cannot
+// satisfy the checks, but the fence itself (and its language) stays detectable.
+export const stripFences = (text: string): string => {
+  const lines = text.split("\n");
+  const out: string[] = [];
+  let inFence = false;
+  for (const line of lines) {
+    if (line.startsWith("```")) {
+      if (!inFence) out.push(line); // opening fence: keep the ```lang marker
+      inFence = !inFence;
+      continue;
+    }
+    if (!inFence) out.push(line);
+  }
+  return out.join("\n");
+};
+
+export const qualitySpec = (text: string): QualityFinding[] => {
+  const findings: QualityFinding[] = [];
+  const body = stripFences(text);
+  const lower = body.toLowerCase();
+
+  for (const section of REQUIRED_SECTIONS) {
+    if (!body.includes(section)) {
+      findings.push(finding("missing_section", `required section ${section} missing`, "hard"));
+    }
+  }
+
+  const hasCa = /^\s*(?:- CA-\d+|CA-\d+[.:])/m.test(body); // M1: ^ with /m covers line starts
+  if (!hasCa) {
+    findings.push(finding("missing_acceptance_criteria", "no enumerable CA-XX acceptance criteria found", "hard"));
+  }
+
+  const hasAsciiFence = /```(?:text|ascii)/.test(body);
+  const mentionsUi = UI_KEYWORDS.some((k) => k.test(lower));
+  if (mentionsUi && !hasAsciiFence) {
+    findings.push(finding("missing_ascii_for_ui", "spec mentions UI but has no ASCII wireframe fence", "warning"));
+  }
+
+  const hasMermaid = /```mermaid/.test(body);
+  const explicitlyNoFlow = /\bno (?:flow|pipeline|sequence|diagram)\b/.test(lower);
+  const mentionsFlow = FLOW_KEYWORDS.some((k) => k.test(lower));
+  if (mentionsFlow && !hasMermaid && !explicitlyNoFlow) {
+    findings.push(finding("missing_mermaid_for_flow", "spec describes a flow/pipeline/sequence but has no mermaid fence", "warning"));
+  }
+
+  const hasTable = /^\s*\|.+\|.+\|/m.test(body);
+  const mentionsGlossary = GLOSSARY_KEYWORDS.some((k) => k.test(lower));
+  const onlyOutOfScope = /\bout of scope\b/.test(lower) && !/\bglossary\b/.test(lower) && !/\bcontracts?\b/.test(lower);
+  if (mentionsGlossary && !hasTable && !onlyOutOfScope) {
+    findings.push(finding("missing_table", "spec has glossary/contract/scope content but no markdown table", "warning"));
+  }
+
+  return findings;
+};
+
+const sddIgnored = (cwd: string, slug: string): boolean => {
+  const sddDir = path.join(cwd, "docs", slug, "sdd");
+  if (!existsSync(sddDir)) return true;
+  try {
+    execFileSync("git", ["-C", cwd, "rev-parse", "--is-inside-work-tree"], { stdio: "pipe" });
+  } catch {
+    return true; // not a git repo — nothing to be unignored in; validation presupposes a repo
+  }
+  try {
+    execFileSync("git", ["-C", cwd, "check-ignore", path.posix.join("docs", slug, "sdd", "progress.md")], { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+};

package/src/core/flow-state.ts

@@ -0,0 +1,225 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync, existsSync } from "node:fs";
+import path from "node:path";
+import { parseTasksFromPlan, qualitySpec, stripFences } from "./docs-validate";
+
+export type FlowStatus = "draft" | "self_reviewed" | "approved";
+export type FlowDocState = { path: string; status: FlowStatus };
+export type FlowState = {
+  slug: string;
+  spec: FlowDocState;
+  plan: FlowDocState;
+  menu: { presented: boolean; chosen: string };
+  updated_at: number;
+};
+
+type Result = { ok: true } | { ok: false; error: string };
+
+const SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+const flowPath = (root: string, slug: string) => {
+  if (!SLUG_RE.test(slug)) throw new Error(`invalid slug: ${JSON.stringify(slug)}`);
+  return path.join(root, "docs", slug, "sdd", "flow.json");
+};
+
+export const readFlowState = (root: string, slug: string): FlowState => {
+  const file = flowPath(root, slug);
+  if (!existsSync(file)) {
+    return {
+      slug,
+      spec: { path: "", status: "draft" },
+      plan: { path: "", status: "draft" },
+      menu: { presented: false, chosen: "" },
+      updated_at: Date.now(),
+    };
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(file, "utf8")) as Partial<FlowState>;
+    return {
+      slug: parsed.slug ?? slug,
+      spec: { path: parsed.spec?.path ?? "", status: parsed.spec?.status ?? "draft" },
+      plan: { path: parsed.plan?.path ?? "", status: parsed.plan?.status ?? "draft" },
+      menu: { presented: Boolean(parsed.menu?.presented), chosen: parsed.menu?.chosen ?? "" },
+      updated_at: parsed.updated_at ?? Date.now(),
+    };
+  } catch {
+    return {
+      slug,
+      spec: { path: "", status: "draft" },
+      plan: { path: "", status: "draft" },
+      menu: { presented: false, chosen: "" },
+      updated_at: Date.now(),
+    };
+  }
+};
+
+export const writeFlowState = (root: string, state: FlowState) => {
+  const file = flowPath(root, state.slug);
+  mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp`;
+  writeFileSync(tmp, JSON.stringify(state, null, 2) + "\n", "utf8");
+  renameSync(tmp, file);
+};
+
+const nextStatus = (
+  current: FlowStatus,
+  confirmed: boolean,
+): { ok: false; error: string } | { ok: true; next: FlowStatus } => {
+  if (!confirmed) return { ok: false, error: "confirmed: true required" };
+  if (current === "draft") return { ok: true, next: "self_reviewed" };
+  if (current === "self_reviewed") return { ok: true, next: "approved" };
+  return { ok: false, error: "already approved; no further transitions" };
+};
+
+export const transitionSpec = (
+  root: string,
+  slug: string,
+  specPath: string,
+  confirmed: boolean,
+): Result => {
+  let state: FlowState;
+  try {
+    state = readFlowState(root, slug);
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : "invalid flow state" };
+  }
+  if (!existsSync(path.isAbsolute(specPath) ? specPath : path.join(root, specPath))) {
+    return { ok: false, error: `spec not found: ${specPath}` };
+  }
+  if (state.spec.status === "draft" && confirmed) {
+    const specFile = path.isAbsolute(specPath) ? specPath : path.join(root, specPath);
+    let text: string;
+    try {
+      text = readFileSync(specFile, "utf8");
+    } catch (error) {
+      return {
+        ok: false,
+        error: `spec self-review failed: unreadable spec: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+    const hard = qualitySpec(text).filter((f) => f.severity === "hard");
+    const missing: string[] = [];
+    if (!/^\s*\*+Branch:\*+/im.test(stripFences(text))) missing.push("**Branch:** header missing");
+    if (hard.length > 0 || missing.length > 0) {
+      return {
+        ok: false,
+        error:
+          "spec self-review failed: " +
+          hard.map((f) => `${f.code} — ${f.message}`).concat(missing).join("; ") +
+          " — see templates/spec-template.md for the required structure",
+      };
+    }
+  }
+  const step = nextStatus(state.spec.status, confirmed);
+  if (!step.ok) return { ok: false, error: step.error };
+  writeFlowState(root, {
+    ...state,
+    spec: { path: specPath, status: step.next },
+    updated_at: Date.now(),
+  });
+  return { ok: true };
+};
+
+export const transitionPlan = (
+  root: string,
+  slug: string,
+  planPath: string,
+  confirmed: boolean,
+): Result => {
+  let state: FlowState;
+  try {
+    state = readFlowState(root, slug);
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : "invalid flow state" };
+  }
+  if (!existsSync(path.isAbsolute(planPath) ? planPath : path.join(root, planPath))) {
+    return { ok: false, error: `plan not found: ${planPath}` };
+  }
+  if (state.spec.status !== "approved") {
+    return { ok: false, error: "spec must be approved before the plan can be approved" };
+  }
+  if (state.plan.status === "draft" && confirmed) {
+    const planFile = path.isAbsolute(planPath) ? planPath : path.join(root, planPath);
+    let text: string;
+    try {
+      text = readFileSync(planFile, "utf8");
+    } catch (error) {
+      return {
+        ok: false,
+        error: `plan self-review failed: unreadable plan: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+    const missing: string[] = [];
+    const stripped = stripFences(text);
+    if (parseTasksFromPlan(text).length === 0) missing.push("no ### Task N: sections outside fences");
+    if (!/^\s*\*+Spec:\*+/im.test(stripped)) missing.push("**Spec:** header missing");
+    if (!/^\s*\*+Branch:\*+/im.test(stripped)) missing.push("**Branch:** header missing");
+    if (missing.length > 0) {
+      return { ok: false, error: "plan self-review failed: " + missing.join("; ") };
+    }
+  }
+  const step = nextStatus(state.plan.status, confirmed);
+  if (!step.ok) return { ok: false, error: step.error };
+  writeFlowState(root, {
+    ...state,
+    plan: { path: planPath, status: step.next },
+    updated_at: Date.now(),
+  });
+  return { ok: true };
+};
+
+export const recordMenuChoice = (
+  root: string,
+  slug: string,
+  planPath: string,
+  choice: string,
+  confirmed: boolean,
+): Result => {
+  if (!confirmed) return { ok: false, error: "confirmed: true required" };
+  let state: FlowState;
+  try {
+    state = readFlowState(root, slug);
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : "invalid flow state" };
+  }
+  writeFlowState(root, {
+    ...state,
+    plan: state.plan.path ? state.plan : { path: planPath, status: state.plan.status },
+    menu: { presented: true, chosen: choice },
+    updated_at: Date.now(),
+  });
+  return { ok: true };
+};
+
+export const slugFromPath = (p: string) => {
+  const dirName = path.basename(path.dirname(p));
+  return dirName === "." || dirName === "/" || dirName === "" ? "" : dirName;
+};
+
+export const assertFlowGates = (
+  root: string,
+  planPath: string,
+  opts: { requireMenu?: boolean } = {},
+): Result => {
+  const slug = slugFromPath(planPath);
+  const state = readFlowState(root, slug);
+  if (state.spec.status !== "approved") {
+    return {
+      ok: false,
+      error: `spec not approved (status: ${state.spec.status}). Run workflow_spec_approve after the user's approval.`,
+    };
+  }
+  if (state.plan.status !== "approved") {
+    return {
+      ok: false,
+      error: `plan not approved (status: ${state.plan.status}). Run workflow_plan_approve after the user's approval.`,
+    };
+  }
+  if (opts.requireMenu && !state.menu.presented) {
+    return {
+      ok: false,
+      error:
+        "post-plan menu not presented. Ask the native question menu (Subagent-driven/Inline/Handoff/Review spec/Review plan) and record the answer with workflow_plan_menu.",
+    };
+  }
+  return { ok: true };
+};