@brainervirus/workit-core 0.4.0

package/src/core/changelog.ts

@@ -0,0 +1,312 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveWorkspaceRoot } from "./scripts";
+
+const CATEGORIES = [
+  "Added",
+  "Changed",
+  "Deprecated",
+  "Removed",
+  "Fixed",
+  "Security",
+];
+
+// Port of scripts/changelog/apply-unreleased.py — merge Keep a Changelog
+// entries into ## [Unreleased] without duplicating ### headings.
+const CAT_RE = /^###\s+(?:Added|Changed|Deprecated|Removed|Fixed|Security)\s*$/i;
+const UNRELEASED_RE = /^##\s+\[Unreleased\]\s*$/i;
+const VERSION_RE = /^##\s+\[/;
+const BULLET_RE = /^([-*]\s+)(.+?)\s*$/;
+const HEADING_RE = /^###\s+/;
+
+const SKELETON = `# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+`;
+
+function normalizeBullet(text: string): string {
+  text = text.trim();
+  const m = BULLET_RE.exec(text);
+  if (m) return m[2].trim();
+  if (text.startsWith("- ") || text.startsWith("* ")) return text.slice(2).trim();
+  return text;
+}
+
+function formatBullet(text: string): string {
+  return `- ${normalizeBullet(text)}`;
+}
+
+function splitUnreleased(text: string): [string, string, string] {
+  const lines = text.split(/(?<=\n)/);
+  let start: number | null = null;
+  for (let i = 0; i < lines.length; i++) {
+    if (UNRELEASED_RE.test(lines[i].replace(/\n$/, ""))) {
+      start = i;
+      break;
+    }
+  }
+  if (start === null) return [text, "", ""];
+
+  let end = lines.length;
+  for (let j = start + 1; j < lines.length; j++) {
+    const stripped = lines[j].replace(/\n$/, "");
+    // Next version heading ends Unreleased (ignore a stray second Unreleased)
+    if (VERSION_RE.test(stripped)) {
+      if (UNRELEASED_RE.test(stripped)) continue;
+      end = j;
+      break;
+    }
+  }
+
+  const before = lines.slice(0, start + 1).join("");
+  const body = lines.slice(start + 1, end).join("");
+  const after = lines.slice(end).join("");
+  return [before, body, after];
+}
+
+function canonicalCategory(heading: string): string | null {
+  const match = CAT_RE.exec(heading.replace(/\r?\n$/, ""));
+  if (!match) return null;
+  return CATEGORIES.find((c) => c.toLowerCase() === match[0].replace(/^###\s+/, "").trim().toLowerCase()) ?? null;
+}
+
+function splitSections(body: string): [string[], Array<{ heading: string; category: string | null; body: string[] }>] {
+  const preamble: string[] = [];
+  const sections: Array<{ heading: string; category: string | null; body: string[] }> = [];
+  let current: { heading: string; category: string | null; body: string[] } | null = null;
+  for (const line of body.split(/(?<=\n)/)) {
+    if (HEADING_RE.test(line)) {
+      current = { heading: line, category: canonicalCategory(line), body: [] };
+      sections.push(current);
+    } else if (current === null) {
+      preamble.push(line);
+    } else {
+      current.body.push(line);
+    }
+  }
+  return [preamble, sections];
+}
+
+function bulletBlocks(lines: string[]): Array<[string | null, string[]]> {
+  const blocks: Array<[string | null, string[]]> = [];
+  let current: string[] = [];
+  let key: string | null = null;
+  for (const line of lines) {
+    const match = BULLET_RE.exec(line.replace(/\r\n$/, "").replace(/\n$/, ""));
+    if (match) {
+      if (current.length) blocks.push([key, current]);
+      key = normalizeBullet(line).toLowerCase();
+      current = [line];
+    } else {
+      current.push(line);
+    }
+  }
+  if (current.length) blocks.push([key, current]);
+  return blocks;
+}
+
+function mergeSections(
+  body: string,
+  entries: Record<string, string[]>,
+  normalizeOnly: boolean,
+): [string, Record<string, number>, Record<string, number> | null, string | null] {
+  const [preamble, sections] = splitSections(body);
+  const first: Record<string, { heading: string; body: string[] }> = {};
+  const rendered: Array<{ heading: string; body: string[] }> = [];
+  for (const section of sections) {
+    if (section.category && section.category in first) {
+      first[section.category].body.push(...section.body);
+    } else {
+      const entry = { heading: section.heading, body: section.body };
+      rendered.push(entry);
+      if (section.category) first[section.category] = entry;
+    }
+  }
+
+  const added: Record<string, number> = {};
+  if (!normalizeOnly) {
+    for (const [rawCategory, bullets] of Object.entries(entries)) {
+      const category = CATEGORIES.find((c) => c.toLowerCase() === rawCategory.toLowerCase());
+      if (category === undefined) {
+        return ["", {}, {}, `invalid category: ${rawCategory}`];
+      }
+      let section = first[category];
+      if (section === undefined) {
+        section = { heading: `### ${category}\n`, body: ["\n"] };
+        rendered.push(section);
+        first[category] = section;
+      }
+
+      const seen = new Set<string>();
+      const kept: string[] = [];
+      for (const [key, block] of bulletBlocks(section.body)) {
+        if (key !== null && seen.has(key)) continue;
+        if (key !== null) seen.add(key);
+        kept.push(...block);
+      }
+
+      const fresh: string[] = [];
+      for (const bullet of bullets ?? []) {
+        const key = normalizeBullet(bullet).toLowerCase();
+        if (!key || seen.has(key)) continue;
+        seen.add(key);
+        fresh.push(formatBullet(bullet) + "\n");
+      }
+      if (fresh.length) {
+        let insertAt = 0;
+        while (insertAt < kept.length && !kept[insertAt].trim()) insertAt++;
+        section.body = [...kept.slice(0, insertAt), ...fresh, ...kept.slice(insertAt)];
+      } else {
+        section.body = kept;
+      }
+      added[category] = fresh.length;
+    }
+  }
+
+  let output = preamble.join("");
+  for (const section of rendered) {
+    output += section.heading + section.body.join("");
+  }
+  const counts: Record<string, number> = {};
+  for (const [category, section] of Object.entries(first)) {
+    counts[category] = bulletBlocks(section.body).filter(([key]) => key !== null).length;
+  }
+  return [output, counts, added, null];
+}
+
+function ensureFile(target: string): string {
+  if (fs.existsSync(target)) return fs.readFileSync(target, "utf8");
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, SKELETON, "utf8");
+  return SKELETON;
+}
+
+function hasUnreleasedHeading(text: string): boolean {
+  return text.split("\n").some((line) => UNRELEASED_RE.test(line.replace(/\n$/, "")));
+}
+
+function applyChangelog(
+  target: string,
+  entries: Record<string, string[]>,
+  normalizeOnly: boolean,
+): Record<string, any> {
+  let text = ensureFile(target);
+  if (!hasUnreleasedHeading(text)) {
+    const lines = text.split(/(?<=\n)/);
+    let insertAt = lines.length;
+    for (let i = 0; i < lines.length; i++) {
+      const stripped = lines[i].replace(/\n$/, "");
+      if (VERSION_RE.test(stripped) && !UNRELEASED_RE.test(stripped)) {
+        insertAt = i;
+        break;
+      }
+    }
+    text = lines.slice(0, insertAt).join("") + "## [Unreleased]\n\n" + lines.slice(insertAt).join("");
+  }
+
+  const [before, body, after] = splitUnreleased(text);
+  const [newBody, counts, addedCounts, error] = mergeSections(body, entries, normalizeOnly);
+  if (error) return { error };
+  // before already includes "## [Unreleased]\n"
+  const out = (before.endsWith("\n") ? before : before + "\n") + newBody + after;
+  fs.writeFileSync(target, out, "utf8");
+  return {
+    ok: true,
+    path: target,
+    normalize_only: normalizeOnly,
+    added: addedCounts,
+    categories: counts,
+  };
+}
+
+function normalizeEntries(entries: any): { data: Record<string, string[]> } | { error: string } {
+  if (!entries) return { data: {} };
+  if (Array.isArray(entries)) {
+    const grouped: Record<string, string[]> = {};
+    for (const item of entries) {
+      const cat = item.category ?? item.type;
+      const text = item.text ?? item.entry ?? "";
+      if (!cat || !text) {
+        return { error: "each entry needs category + text" };
+      }
+      const canon = CATEGORIES.find((c) => c.toLowerCase() === String(cat).toLowerCase());
+      if (!canon) return { error: `invalid category: ${cat}` };
+      (grouped[canon] ??= []).push(text);
+    }
+    return { data: grouped };
+  }
+  if (typeof entries === "object") {
+    const grouped: Record<string, string[]> = {};
+    for (const [cat, bullets] of Object.entries(entries)) {
+      const canon = CATEGORIES.find((c) => c.toLowerCase() === String(cat).toLowerCase());
+      if (!canon) return { error: `invalid category: ${cat}` };
+      const list = Array.isArray(bullets) ? bullets : [bullets];
+      grouped[canon] = list.filter(Boolean).map(String);
+    }
+    return { data: grouped };
+  }
+  return { error: "entries must be object or array" };
+}
+
+export function changelogApply({
+  entries,
+  path: changelogPath,
+  normalize_only,
+  workspace_root,
+}: {
+  entries?: any;
+  path?: string;
+  normalize_only?: boolean;
+  workspace_root: string;
+}): Record<string, any> {
+  const cwd = resolveWorkspaceRoot(workspace_root);
+  const normalized = normalize_only
+    ? { data: {} as Record<string, string[]> }
+    : normalizeEntries(entries);
+  if ("error" in normalized) return { error: normalized.error };
+  if (!normalize_only && Object.keys(normalized.data).length === 0) {
+    return { error: "entries required unless normalize_only" };
+  }
+
+  const rel = changelogPath || "CHANGELOG.md";
+  const target = path.resolve(cwd, rel);
+  const root = path.resolve(cwd);
+  if (target !== root && !target.startsWith(root + path.sep)) {
+    return { error: "changelog path must be inside workspace_root" };
+  }
+
+  try {
+    return applyChangelog(target, normalized.data, Boolean(normalize_only));
+  } catch (err) {
+    return { error: err instanceof Error ? err.message : "changelog apply failed" };
+  }
+}
+
+export function changelogUnreleasedStats(workspace_root: string, changelogPath = "CHANGELOG.md") {
+  const cwd = resolveWorkspaceRoot(workspace_root);
+  const abs = path.isAbsolute(changelogPath)
+    ? changelogPath
+    : path.join(cwd, changelogPath);
+  if (!fs.existsSync(abs)) return { exists: false };
+  const text = fs.readFileSync(abs, "utf8");
+  const m = text.match(/##\s+\[Unreleased\]([\s\S]*?)(?=\n##\s+\[|$)/i);
+  if (!m) return { exists: true, has_unreleased: false };
+  const body = m[1];
+  const headings = [...body.matchAll(/^###\s+(\w+)\s*$/gim)].map((x) => x[1]);
+  const dupes = headings.filter((h, i) =>
+    headings.slice(0, i).some((p) => p.toLowerCase() === h.toLowerCase()),
+  );
+  return {
+    exists: true,
+    has_unreleased: true,
+    category_headings: headings,
+    duplicate_category_headings: dupes,
+    needs_normalize: dupes.length > 0,
+  };
+}

package/src/core/config-guard.ts

@@ -0,0 +1,26 @@
+import { initStatus } from "./init";
+
+export const ALL_ITEM_IDS = ["youtrack_json", "youtrack_token", "vcs_json", "gitlab_token", "github_token"];
+export const CONFIG_GAP_MARKER = "workflow config missing";
+
+export function describeConfigGaps(scope?: string[]): { missing: string[]; ok: boolean } {
+  const all = scope ?? ALL_ITEM_IDS;
+  try {
+    const status: unknown = initStatus();
+    if (!status || typeof status !== "object" || (status as Record<string, unknown>).error) return { missing: all, ok: false };
+    const items = (status as Record<string, unknown>).items;
+    if (!Array.isArray(items) || items.length === 0) return { missing: all, ok: false };
+    const known = all;
+    const missing = items
+      .filter((item) => item && (item as Record<string, unknown>).ok === false)
+      .map((item) => String((item as Record<string, unknown>).id))
+      .filter((id) => known.includes(id));
+    return { missing, ok: missing.length === 0 };
+  } catch {
+    return { missing: all, ok: false };
+  }
+}
+
+export function configGuardError(missing: string[]): string {
+  return `${CONFIG_GAP_MARKER}: ${missing.join(", ")}. Run \`npx workit init\` or \`/wk-init\` to configure.`;
+}

package/src/core/config.ts

@@ -0,0 +1,73 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export type BranchPreset = "gitflow" | "github-flow" | "trunk-based" | "custom";
+
+export type ToolkitConfig = {
+  locale: string;
+  localeOptions: string[];
+  timezone: string;
+  branchPolicy: { preset: BranchPreset; allowed: string[]; protected: string[] };
+};
+
+export const PRESETS: Record<BranchPreset, { allowed: string[]; protected: string[] }> = {
+  gitflow: { allowed: ["feature/*", "bugfix/*", "hotfix/*", "release/*"], protected: ["main", "develop", "master", "prod", "production"] },
+  "github-flow": { allowed: ["*"], protected: ["main"] },
+  "trunk-based": { allowed: ["*"], protected: ["main"] },
+  custom: { allowed: [], protected: [] },
+};
+
+export const configDir = (): string =>
+  process.env.WORKFLOW_TOOLKIT_CONFIG
+  ?? process.env.WORKFLOW_TOOLKIT_CONFIG_DIR
+  ?? path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "workflow-toolkit");
+
+export const LOCALE_RE = /^[a-z]{2,3}(-[A-Z]{2})?$/;
+
+const DEFAULTS: ToolkitConfig = {
+  locale: "en",
+  localeOptions: ["en", "es-CL", "es-MX", "es-AR", "pt-BR"],
+  timezone: "America/Santiago",
+  branchPolicy: { preset: "gitflow", allowed: [...PRESETS.gitflow.allowed], protected: [...PRESETS.gitflow.protected] },
+};
+
+const readSafe = (p: string): string | null => {
+  try { return readFileSync(p, "utf8"); } catch { return null; }
+};
+
+export const readConfig = (): ToolkitConfig => {
+  const raw = readSafe(path.join(configDir(), "config.json"));
+  if (!raw) return DEFAULTS;
+  try {
+    const parsed = JSON.parse(raw) as Partial<ToolkitConfig>;
+    const locale = LOCALE_RE.test(String(parsed.locale ?? "")) ? parsed.locale as string : DEFAULTS.locale;
+    const preset = (parsed.branchPolicy?.preset ?? "gitflow") as BranchPreset;
+    const presetOk = Object.hasOwn(PRESETS, preset) ? preset : "gitflow";
+    const presetDefs = PRESETS[presetOk];
+    return {
+      locale,
+      localeOptions: Array.isArray(parsed.localeOptions) ? parsed.localeOptions : DEFAULTS.localeOptions,
+      timezone: parsed.timezone ?? DEFAULTS.timezone,
+      branchPolicy: {
+        preset: presetOk,
+        allowed: Array.isArray(parsed.branchPolicy?.allowed) ? parsed.branchPolicy.allowed : presetDefs.allowed,
+        protected: Array.isArray(parsed.branchPolicy?.protected) ? parsed.branchPolicy.protected : presetDefs.protected,
+      },
+    };
+  } catch {
+    return DEFAULTS;
+  }
+};
+
+export const writeConfig = (config: ToolkitConfig): void => {
+  const dir = configDir();
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(path.join(dir, "config.json"), JSON.stringify(config, null, 2) + "\n", "utf8");
+};
+
+export const resolveBranchPolicy = (config: ToolkitConfig): { allowed: RegExp[]; protected: Set<string> } => {
+  const allowed = config.branchPolicy.allowed.map((p) =>
+    new RegExp(`^${p.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*")}$`, "i"));
+  return { allowed, protected: new Set(config.branchPolicy.protected.map((p) => p.toLowerCase())) };
+};

package/src/core/detector.ts

@@ -0,0 +1,207 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { CONFIG_GAP_MARKER } from "./config-guard";
+import { parseTasksFromPlan } from "./docs-validate";
+
+export type Detection = { choices: string[]; pattern: "alpha" | "numeric" } | null;
+
+export const detectConfigGapError = (text: string): boolean =>
+  text.includes(CONFIG_GAP_MARKER);
+
+// Enforcement-rail detectors: case-insensitive word-boundary heuristics.
+// Conservative bias (D-03): require 1+ signal word AND 0 evidence words;
+// when any evidence wording appears, do NOT fire.
+
+const COMPLETION_CLAIMS = /\b(?:done|fixed|passing|green|complete|all set)\b/i;
+const VERIFICATION_EVIDENCE =
+  /\bbun run check\b|\bworkflow_verify\b|\bbun test\b|\bchecks?\s+pass(?:es|ing)?\b|\btests?\s+pass(?:es|ing)?\b/i;
+
+// Claims completion without verification-command evidence in the same text.
+export const detectVerificationClaim = (text: string): boolean =>
+  COMPLETION_CLAIMS.test(text) && !VERIFICATION_EVIDENCE.test(text);
+
+const IMPLEMENTATION_SIGNALS =
+  /\b(?:changed|implemented|implementing|added|refactored|commit(?:ted|s)?|edited)\b/i;
+const FAILING_TEST_WORDS =
+  /\b(?:failing test|test failed|watch it fail|red-green|tdd|test first)\b/i;
+
+// Implementation signal without a preceding failing-test mention.
+export const detectUntestedImplementation = (text: string): boolean =>
+  IMPLEMENTATION_SIGNALS.test(text) && !FAILING_TEST_WORDS.test(text);
+
+const IMPLEMENTATION_ACTION =
+  /\b(?:implement|add the feature|write the code|create the component|build (?:the )?(?:feature|component|module|command|screen|service))\b/i;
+const DESIGN_WORDS =
+  /\b(?:design|spec|brainstorm|approved|plan|requested|instruction|as you asked|as you said)\b/i;
+
+// Implementation action without a presented/approved design.
+export const detectImplementationWithoutDesign = (text: string): boolean =>
+  IMPLEMENTATION_ACTION.test(text) && !DESIGN_WORDS.test(text);
+
+const FIX_SIGNALS = /\b(?:fixed|fix|patch|solved)\b/i;
+const ROOT_CAUSE_WORDS =
+  /\b(?:root cause|caused by|reproduced|stack trace|investigation|because)\b/i;
+
+// Fix proposal without root-cause evidence.
+export const detectFixWithoutRootCause = (text: string): boolean =>
+  FIX_SIGNALS.test(text) && !ROOT_CAUSE_WORDS.test(text);
+
+const ACCEPTANCE_SIGNALS = /\b(?:agreed|makes sense|good point|will implement)\b/i;
+const REVIEW_VERIFICATION_WORDS =
+  /\b(?:verif(?:y|ied)|check(?:ed|ing)?|reproduced|tested|confirmed)\b/i;
+
+// Review acceptance without verification wording.
+export const detectBlindReviewAcceptance = (text: string): boolean =>
+  ACCEPTANCE_SIGNALS.test(text) && !REVIEW_VERIFICATION_WORDS.test(text);
+
+// Instruction-option detector: a clickable `question` option whose label is an
+// instruction to type free text. Clicking such an option returns the label
+// literal, not the typed value. Conservative: instruction verb + free-text noun.
+export const INSTRUCTION_OPTION_RE =
+  /^(type|provide|paste|enter|write|give me)\b.*\b(url|id|issue|text|notes|number)\b/i;
+
+// Accepts the question tool-call input: an array of questions OR { questions: [...] }.
+export const detectInstructionOption = (questions: unknown): boolean => {
+  const list = Array.isArray(questions)
+    ? questions
+    : (questions as { questions?: unknown } | null)?.questions;
+  if (!Array.isArray(list)) return false;
+  for (const q of list) {
+    if (!q || typeof q !== "object") continue;
+    const options = (q as { options?: unknown }).options;
+    if (!Array.isArray(options)) continue;
+    for (const opt of options) {
+      if (!opt || typeof opt !== "object") continue;
+      const label = (opt as { label?: unknown }).label;
+      if (typeof label !== "string" || !label) continue;
+      if (INSTRUCTION_OPTION_RE.test(label)) return true;
+    }
+  }
+  return false;
+};
+
+// Raw delivery: an UNLABELED fenced block carrying doc markers — the agent pasted
+// the doc instead of rendering it. Rendered docs keep labeled fences (```mermaid)
+// and never match; reminders use angle-bracket blocks, so no false positives.
+// Labeled blocks are stripped first so their plain closing fence (```) can't match.
+export const detectRawDocDelivery = (text: string): boolean =>
+  /^```\s*$/m.test(text.replace(/```\S[^\n]*\r?\n[\s\S]*?```/g, "")) &&
+  (text.includes("# Spec") || text.includes("# Plan") ||
+    text.includes("**Spec:**") || text.includes("**Branch:**"));
+
+// Interrogative gate: a literal question mark OR explicit interrogative phrases.
+// Plain "I want to confirm..." or "the script which runs" must NOT match.
+const INTERROGATIVE = /[?¿]|which\s+one|choose\s+(?:one|between|among)|do\s+you\s+(?:want|prefer)|want\s+me\s+to/i;
+
+export const detectProseChoices = (text: string): Detection => {
+  if (!INTERROGATIVE.test(text)) return null;
+
+  const lines = text.split("\n").map((l) => l.trim()).filter(Boolean);
+
+  const alphaAll = [...text.matchAll(/([a-dA-D])[.)]\s+([^\n]*?)(?=\s+[a-dA-D][.)]\s|$)/g)]
+    .map((m) => ({ letter: m[1].toLowerCase(), choice: m[2].trim() }));
+  const alphaLines = lines
+    .map((l) => /^([a-dA-D])[.)]\s+(.+)$/.exec(l))
+    .filter((m): m is RegExpExecArray => Boolean(m))
+    .map((m) => ({ letter: m[1].toLowerCase(), choice: m[2] }));
+  const alpha = alphaAll.length >= alphaLines.length ? alphaAll : alphaLines;
+
+  if (alpha.length >= 2) {
+    const letters = alpha.map((a) => a.letter);
+    const expected = ["a", "b", "c", "d"].slice(0, alpha.length);
+    if (letters.every((l, i) => l === expected[i])) {
+      return { choices: alpha.map((a) => a.choice), pattern: "alpha" };
+    }
+  }
+
+  const numericAll = [...text.matchAll(/(\d+)[.)]\s+([^\n]*?)(?=\s+\d+[.)]\s|$)/g)]
+    .map((m) => ({ num: Number(m[1]), choice: m[2].trim() }));
+  const numericLines = lines
+    .map((l) => /^(\d+)[.)]\s+(.+)$/.exec(l))
+    .filter((m): m is RegExpExecArray => Boolean(m))
+    .map((m) => ({ num: Number(m[1]), choice: m[2] }));
+  const numeric = numericAll.length >= numericLines.length ? numericAll : numericLines;
+
+  if (numeric.length >= 2) {
+    const nums = numeric.map((n) => n.num);
+    if (nums.every((n, i) => n === i + 1)) {
+      return { choices: numeric.map((n) => n.choice), pattern: "numeric" };
+    }
+  }
+
+  return null;
+};
+
+const stripFences = (text: string): string => {
+  const lines = text.split("\n");
+  const out: string[] = [];
+  let inFence = false;
+  for (const line of lines) {
+    if (line.startsWith("```")) { inFence = !inFence; continue; }
+    if (!inFence) out.push(line);
+  }
+  return out.join("\n");
+};
+
+export const detectBacktickDocRefs = (text: string): string[] | null => {
+  const body = stripFences(text);
+  const refs = [...body.matchAll(/`docs\/[^`\s]+\.md`/g)].map((m) => m[0]);
+  if (!refs.length) return null;
+  if (/\[[^\]]+\]\(docs\//.test(body)) return null;
+  return refs;
+};
+
+// The rail has no terminal FlowStatus — a fully completed SDD ledger is done,
+// but only if its complete set covers every task id in the plan (the last
+// task's append may have been skipped, leaving an all-complete partial ledger).
+const isPlanComplete = (slugDir: string): boolean => {
+  const ledger = path.join(slugDir, "sdd", "progress.md");
+  if (!existsSync(ledger)) return false; // no ledger yet — not provably complete
+  let taskLines: string[];
+  try {
+    taskLines = readFileSync(ledger, "utf8")
+      .split("\n")
+      .map((l) => l.trim())
+      .filter((l) => /^Task \s*\d+:/i.test(l));
+  } catch {
+    return true; // unreadable ledger → exclude the slug
+  }
+  if (taskLines.length === 0 || !taskLines.every((l) => /^Task \s*\d+:\s*complete\b/i.test(l))) {
+    return false;
+  }
+  try {
+    const planTasks = parseTasksFromPlan(readFileSync(path.join(slugDir, "plan.md"), "utf8"));
+    if (planTasks.length === 0) return true;
+    const completeIds = new Set(
+      taskLines.map((l) => Number(/^Task\s*(\d+):/i.exec(l)?.[1])).filter(Number.isFinite),
+    );
+    return planTasks.every((t) => completeIds.has(t.id));
+  } catch {
+    return false; // unreadable/missing plan.md — not provably complete, rail stays on
+  }
+};
+
+export const findActiveSubagentDrivenPlans = (root: string): string[] => {
+  const docsDir = path.join(root, "docs");
+  if (!existsSync(docsDir)) return [];
+  const slugs: string[] = [];
+  for (const slug of readdirSync(docsDir)) {
+    const file = path.join(docsDir, slug, "sdd", "flow.json");
+    try {
+      const flow = JSON.parse(readFileSync(file, "utf8")) as {
+        menu?: { chosen?: string };
+        plan?: { status?: string };
+      };
+      if (
+        flow.menu?.chosen === "subagent-driven" &&
+        flow.plan?.status === "approved" &&
+        !isPlanComplete(path.join(docsDir, slug))
+      ) {
+        slugs.push(slug);
+      }
+    } catch {
+      // skip unreadable or malformed flow.json
+    }
+  }
+  return slugs;
+};

package/src/core/doc-render.ts

@@ -0,0 +1,14 @@
+export const MAX_LINES = 150;
+export const MAX_BYTES = 8192;
+export const MAX_MERMAID = 3;
+
+const MERMAID_FENCE = /^```mermaid\s*$/gm;
+
+export const shouldRenderDoc = (text: string): boolean => {
+  const lines = text.split(/\r?\n/);
+  if (lines[lines.length - 1] === "") lines.pop();
+  if (lines.length > MAX_LINES) return false;
+  if (Buffer.byteLength(text, "utf8") > MAX_BYTES) return false;
+  const mermaidCount = text.match(MERMAID_FENCE)?.length ?? 0;
+  return mermaidCount <= MAX_MERMAID;
+};