@infinitedusky/indusk-mcp 1.14.10 → 1.15.1

package/dist/bin/commands/update.js

@@ -183,21 +183,32 @@ export async function update(projectRoot) {
     console.info("\n[Hooks]\n");
     const hooksSource = join(packageRoot, "hooks");
     const hooksTarget = join(projectRoot, ".claude/hooks");
+    console.info(`  source: ${hooksSource}`);
     let hooksUpdated = 0;
     let hooksCurrent = 0;
-    if (existsSync(hooksSource) && existsSync(hooksTarget)) {
-        const hookFiles = [
-            "check-gates.js",
-            "gate-reminder.js",
-            "validate-impl-structure.js",
-            "check-catchup.js",
-            "eval-trigger.js",
-        ];
+    if (!existsSync(hooksSource)) {
+        console.info(`  source missing — the package install is broken`);
+    }
+    else if (!existsSync(hooksTarget)) {
+        // Never initialized — create the dir and copy all bundled hooks
+        mkdirSync(hooksTarget, { recursive: true });
+        console.info(`  created: ${hooksTarget}`);
+        const bundled = globSync("*.js", { cwd: hooksSource });
+        for (const file of bundled) {
+            cpSync(join(hooksSource, file), join(hooksTarget, file));
+            console.info(`  added: ${file}`);
+            hooksUpdated++;
+        }
+        console.info(`\n  ${hooksUpdated} added.`);
+    }
+    else {
+        // Both dirs exist — sync by hash compare. Discover bundled hooks from
+        // the source dir rather than hardcoding names, so new hooks added to
+        // the package get synced on update without code changes here.
+        const hookFiles = globSync("*.js", { cwd: hooksSource });
         for (const file of hookFiles) {
             const sourceFile = join(hooksSource, file);
             const targetFile = join(hooksTarget, file);
-            if (!existsSync(sourceFile))
-                continue;
             if (!existsSync(targetFile)) {
                 cpSync(sourceFile, targetFile);
                 console.info(`  added: ${file}`);
@@ -244,9 +255,6 @@ export async function update(projectRoot) {
             }
         }
     }
-    else {
-        console.info("  not installed (run init to install)");
-    }
     // 5b. Migrate stale MCP configs
     const mcpJsonPath = join(projectRoot, ".mcp.json");
     if (existsSync(mcpJsonPath)) {

package/dist/lib/trajectory/audit.d.ts

@@ -0,0 +1,51 @@
+import type { DeferredRow, Trajectory, TrajectoryRow } from "./parser.js";
+export type MitigationKind = "telemetry-alert" | "scheduled-review" | "downstream-plan" | "canary-or-staging" | "feedback-signal" | "unclassified";
+export interface MitigationClassification {
+    row: DeferredRow;
+    kind: MitigationKind;
+    /** Hints extracted from the text: plan names, file paths, metric names. */
+    hints: string[];
+    /** Non-null when the mitigation is too vague — needs a more concrete commitment. */
+    warning: string | null;
+}
+/**
+ * Retrospective audit: classify every Deferred Verification row, flag any
+ * whose mitigation text is too vague or unclassifiable. Returns findings
+ * suitable for inclusion in a retrospective's "What We Learned" section
+ * or a Graphiti audit episode.
+ */
+export declare function auditDeferredMitigations(trajectory: Trajectory): MitigationClassification[];
+export interface BlockedRowFinding {
+    row: TrajectoryRow;
+    message: string;
+}
+/**
+ * Retrospective audit: surface trajectory rows that ended the plan in
+ * `blocked` state. Blocked means "was writable/written but regressed or
+ * changed" — if the plan closes with blocked rows, they should be
+ * explicitly resolved (fix, move passesAt, or move to Deferred Verification).
+ */
+export declare function findBlockedRows(trajectory: Trajectory): BlockedRowFinding[];
+export interface TestIdResolution {
+    id: string;
+    asserts: string;
+    /** Best-effort test file name glob (e.g. "**\/*reconciler*.test.ts") or null. */
+    fileGlob: string | null;
+    /** Vitest command with a filter, if one can be derived from the asserts text. */
+    suggestedCommand: string;
+}
+/**
+ * Derive a concrete test file glob + runnable command from a trajectory
+ * row's asserts text. Heuristic: extract identifiers (camelCase, kebab-case,
+ * backtick-quoted code) and use the longest as a filename hint. Returns a
+ * fallback `pnpm test` with a `-t` name filter if no filename hint found.
+ *
+ * The verify skill uses this to resolve phase-Verification items that say
+ * "T3 passes (...)" into a real invocation. Best-effort — human can override.
+ */
+export declare function resolveTestIdCommand(trajectory: Trajectory, id: string): TestIdResolution | null;
+/** Convenience — parse + audit + resolve in one call for the retrospective skill. */
+export declare function auditPlanAtClose(body: string): {
+    deferred: MitigationClassification[];
+    blocked: BlockedRowFinding[];
+};

package/dist/lib/trajectory/audit.js

@@ -0,0 +1,96 @@
+import { parseTrajectory } from "./parser.js";
+const TELEMETRY_KEYWORDS = ["alert", "metric", "otel", "dash0", "grafana", "threshold"];
+const REVIEW_KEYWORDS = [
+    "weekly",
+    "monthly",
+    "quarterly",
+    "daily",
+    "review",
+    "spot-check",
+    "audit",
+];
+const PLAN_REF = /\b[a-z][a-z0-9-]*-[a-z][a-z0-9-]*\b/g; // kebab-case identifiers that look like plan slugs
+const CANARY_KEYWORDS = ["staging", "canary", "smoke", "preflight", "pre-release"];
+const FEEDBACK_KEYWORDS = ["feedback", "ticket", "support", "channel", "signal"];
+function classifyMitigation(row) {
+    const text = row.mitigation.toLowerCase();
+    const hints = [];
+    const hasAny = (words) => words.some((w) => text.includes(w));
+    let kind = "unclassified";
+    if (hasAny(TELEMETRY_KEYWORDS))
+        kind = "telemetry-alert";
+    else if (hasAny(CANARY_KEYWORDS))
+        kind = "canary-or-staging";
+    else if (hasAny(FEEDBACK_KEYWORDS))
+        kind = "feedback-signal";
+    else if (hasAny(REVIEW_KEYWORDS))
+        kind = "scheduled-review";
+    const planRefs = [...row.mitigation.matchAll(PLAN_REF)].map((m) => m[0]);
+    if (planRefs.length > 0) {
+        hints.push(...planRefs);
+        if (kind === "unclassified")
+            kind = "downstream-plan";
+    }
+    let warning = null;
+    if (kind === "unclassified" || row.mitigation.trim().length < 20) {
+        warning = `Mitigation for "${row.name}" is vague — expected a specific alert, review cadence, plan reference, or procedure. Got: "${row.mitigation}"`;
+    }
+    return { row, kind, hints, warning };
+}
+/**
+ * Retrospective audit: classify every Deferred Verification row, flag any
+ * whose mitigation text is too vague or unclassifiable. Returns findings
+ * suitable for inclusion in a retrospective's "What We Learned" section
+ * or a Graphiti audit episode.
+ */
+export function auditDeferredMitigations(trajectory) {
+    return trajectory.deferred.map(classifyMitigation);
+}
+/**
+ * Retrospective audit: surface trajectory rows that ended the plan in
+ * `blocked` state. Blocked means "was writable/written but regressed or
+ * changed" — if the plan closes with blocked rows, they should be
+ * explicitly resolved (fix, move passesAt, or move to Deferred Verification).
+ */
+export function findBlockedRows(trajectory) {
+    return trajectory.rows
+        .filter((row) => row.state === "blocked")
+        .map((row) => ({
+        row,
+        message: `Row ${row.id} ended plan in 'blocked' state — needs resolution (fix, reschedule, or move to Deferred Verification)`,
+    }));
+}
+/**
+ * Derive a concrete test file glob + runnable command from a trajectory
+ * row's asserts text. Heuristic: extract identifiers (camelCase, kebab-case,
+ * backtick-quoted code) and use the longest as a filename hint. Returns a
+ * fallback `pnpm test` with a `-t` name filter if no filename hint found.
+ *
+ * The verify skill uses this to resolve phase-Verification items that say
+ * "T3 passes (...)" into a real invocation. Best-effort — human can override.
+ */
+export function resolveTestIdCommand(trajectory, id) {
+    const row = trajectory.rows.find((r) => r.id === id);
+    if (!row)
+        return null;
+    const backtickMatches = [...row.asserts.matchAll(/`([^`]+)`/g)].map((m) => m[1]);
+    const identifiers = [...row.asserts.matchAll(/\b[a-zA-Z][a-zA-Z0-9_]{3,}\b/g)].map((m) => m[0]);
+    const keyword = backtickMatches
+        .filter((s) => /[a-zA-Z]/.test(s))
+        .sort((a, b) => b.length - a.length)[0] ??
+        identifiers.sort((a, b) => b.length - a.length)[0] ??
+        null;
+    const fileGlob = keyword ? `**/*${keyword.toLowerCase().replace(/[^a-z0-9]/g, "")}*.test.ts` : null;
+    const suggestedCommand = keyword
+        ? `pnpm test -t "${keyword}"`
+        : `pnpm test -t "${row.asserts.slice(0, 40)}"`;
+    return { id, asserts: row.asserts, fileGlob, suggestedCommand };
+}
+/** Convenience — parse + audit + resolve in one call for the retrospective skill. */
+export function auditPlanAtClose(body) {
+    const trajectory = parseTrajectory(body);
+    return {
+        deferred: auditDeferredMitigations(trajectory),
+        blocked: findBlockedRows(trajectory),
+    };
+}

package/dist/lib/trajectory/parser.d.ts

@@ -0,0 +1,30 @@
+export type TrajectoryState = "planned" | "writable" | "written" | "passing" | "blocked" | "skipped" | "unknown";
+export type TrajectoryKind = "example" | "property" | "contract" | "approval" | "formal";
+export type TrajectoryScope = "unit" | "integration" | "e2e";
+export interface TrajectoryRow {
+    id: string;
+    asserts: string;
+    writableAt: number;
+    passesAt: number;
+    state: TrajectoryState;
+    kind?: TrajectoryKind;
+    scope?: TrajectoryScope;
+}
+export interface DeferredRow {
+    name: string;
+    reason: string;
+    wouldRequire: string;
+    mitigation: string;
+}
+export interface Trajectory {
+    rows: TrajectoryRow[];
+    deferred: DeferredRow[];
+    present: boolean;
+}
+/**
+ * Parse a Test Trajectory from an impl.md body (the content after the
+ * frontmatter). Returns an empty trajectory with `present: false` when the
+ * `## Test Trajectory` section is absent. Never throws — errors are surfaced
+ * by the validator, not the parser.
+ */
+export declare function parseTrajectory(body: string): Trajectory;

package/dist/lib/trajectory/parser.js

@@ -0,0 +1,251 @@
+const TRAJECTORY_HEADING = /^##\s+Test Trajectory\b/;
+const DEFERRED_HEADING = /^###\s+Deferred Verification\b/;
+const NEXT_SECTION_HEADING = /^#{1,3}\s+/;
+const PHASE_REFERENCE = /^\s*Phase\s+(\d+)\s*$/i;
+const VALID_STATES = new Set([
+    "planned",
+    "writable",
+    "written",
+    "passing",
+    "blocked",
+    "skipped",
+    "unknown",
+]);
+const VALID_KINDS = new Set([
+    "example",
+    "property",
+    "contract",
+    "approval",
+    "formal",
+]);
+const VALID_SCOPES = new Set(["unit", "integration", "e2e"]);
+/**
+ * Parse a markdown table row into cells. Strips the leading/trailing pipe and
+ * splits on unescaped pipes. Does NOT handle escaped pipes inside cell content
+ * — the trajectory asserts column does not contain pipes in practice.
+ */
+function parseTableRow(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("|") || !trimmed.endsWith("|"))
+        return [];
+    return trimmed
+        .slice(1, -1)
+        .split("|")
+        .map((cell) => cell.trim());
+}
+/**
+ * Normalize a header cell to a canonical key. Case-insensitive, trims
+ * whitespace, maps variant spellings to canonical names.
+ */
+function normalizeHeader(header) {
+    const normalized = header.toLowerCase().replace(/\s+/g, " ").trim();
+    const aliases = {
+        id: "id",
+        asserts: "asserts",
+        "writable at": "writableAt",
+        "passes at": "passesAt",
+        state: "state",
+        kind: "kind",
+        scope: "scope",
+    };
+    return aliases[normalized] ?? normalized;
+}
+/**
+ * Parse a "Phase N" cell into a number. Returns NaN if the cell is not a
+ * valid phase reference. The validator catches NaN and emits a specific error.
+ */
+function parsePhaseReference(cell) {
+    const match = cell.match(PHASE_REFERENCE);
+    if (!match)
+        return Number.NaN;
+    return Number.parseInt(match[1], 10);
+}
+function parseState(cell) {
+    const normalized = cell.toLowerCase().trim();
+    if (VALID_STATES.has(normalized)) {
+        return normalized;
+    }
+    return "unknown";
+}
+function parseOptionalKind(cell) {
+    const normalized = cell.toLowerCase().trim();
+    if (!normalized)
+        return undefined;
+    if (VALID_KINDS.has(normalized)) {
+        return normalized;
+    }
+    return undefined;
+}
+function parseOptionalScope(cell) {
+    const normalized = cell.toLowerCase().trim();
+    if (!normalized)
+        return undefined;
+    if (VALID_SCOPES.has(normalized)) {
+        return normalized;
+    }
+    return undefined;
+}
+/**
+ * Extract the block of lines under `## Test Trajectory` up to the next
+ * heading of equal or lesser depth. The trajectory block includes the
+ * main table; the `### Deferred Verification` subsection is extracted
+ * separately.
+ */
+function extractTrajectoryBlock(lines) {
+    let inTrajectory = false;
+    let inDeferred = false;
+    const tableLines = [];
+    const deferredLines = [];
+    for (const line of lines) {
+        if (TRAJECTORY_HEADING.test(line)) {
+            inTrajectory = true;
+            inDeferred = false;
+            continue;
+        }
+        if (!inTrajectory)
+            continue;
+        if (DEFERRED_HEADING.test(line)) {
+            inDeferred = true;
+            continue;
+        }
+        // A new top-level or second-level heading ends the trajectory block.
+        // A third-level heading other than Deferred Verification also ends it.
+        if (NEXT_SECTION_HEADING.test(line) && !DEFERRED_HEADING.test(line)) {
+            const depth = line.match(/^(#{1,6})/)?.[1].length ?? 0;
+            if (depth <= 2)
+                break;
+            // A ### heading that isn't Deferred Verification ends the trajectory
+            if (depth === 3)
+                break;
+        }
+        if (inDeferred) {
+            deferredLines.push(line);
+        }
+        else {
+            tableLines.push(line);
+        }
+    }
+    return { tableLines, deferredLines };
+}
+/**
+ * Parse a Deferred Verification block. Each deferred item is a top-level
+ * bullet with three sub-bullets:
+ *
+ * - **{name}**
+ *   - reason: {text}
+ *   - would require: {text}
+ *   - mitigation: {text}
+ */
+function parseDeferredBlock(lines) {
+    const rows = [];
+    let current = null;
+    const flush = () => {
+        if (current && current.name !== undefined) {
+            rows.push({
+                name: current.name,
+                reason: current.reason ?? "",
+                wouldRequire: current.wouldRequire ?? "",
+                mitigation: current.mitigation ?? "",
+            });
+        }
+        current = null;
+    };
+    for (const rawLine of lines) {
+        const line = rawLine.replace(/\s+$/, "");
+        // Top-level bullet with bolded name: - **{name}**
+        const nameMatch = line.match(/^-\s+\*\*(.+?)\*\*\s*(?:—\s*(.*))?$/);
+        if (nameMatch) {
+            flush();
+            current = { name: nameMatch[1].trim() };
+            // Handle inline one-line form: - **Name** — reason: X — would require: Y — mitigation: Z
+            const rest = nameMatch[2];
+            if (rest) {
+                const reasonMatch = rest.match(/reason:\s*([^—]+?)(?:\s*—|$)/i);
+                const wrMatch = rest.match(/would require:\s*([^—]+?)(?:\s*—|$)/i);
+                const mitMatch = rest.match(/mitigation:\s*(.+)$/i);
+                if (reasonMatch)
+                    current.reason = reasonMatch[1].trim();
+                if (wrMatch)
+                    current.wouldRequire = wrMatch[1].trim();
+                if (mitMatch)
+                    current.mitigation = mitMatch[1].trim();
+            }
+            continue;
+        }
+        if (!current)
+            continue;
+        // Sub-bullet: - reason: / - would require: / - mitigation:
+        const subMatch = line.match(/^\s+-\s+(reason|would require|mitigation):\s*(.*)$/i);
+        if (subMatch) {
+            const key = subMatch[1].toLowerCase();
+            const value = subMatch[2].trim();
+            if (key === "reason")
+                current.reason = value;
+            else if (key === "would require")
+                current.wouldRequire = value;
+            else if (key === "mitigation")
+                current.mitigation = value;
+        }
+    }
+    flush();
+    return rows;
+}
+/**
+ * Parse the trajectory table. Returns rows parsed from the GFM table under
+ * `## Test Trajectory`. Unknown column headers are ignored. Rows with
+ * missing required columns are skipped — the validator catches structural
+ * problems and surfaces them.
+ */
+function parseTrajectoryTable(lines) {
+    const tableLines = lines.filter((line) => line.trim().startsWith("|"));
+    if (tableLines.length < 2)
+        return [];
+    const headerCells = parseTableRow(tableLines[0]);
+    const separator = parseTableRow(tableLines[1]);
+    // Separator row looks like |----|----|... — every cell is dashes/colons
+    const isSeparator = separator.every((cell) => /^:?-+:?$/.test(cell));
+    if (!isSeparator)
+        return [];
+    const columnKeys = headerCells.map(normalizeHeader);
+    const rows = [];
+    for (let i = 2; i < tableLines.length; i++) {
+        const cells = parseTableRow(tableLines[i]);
+        if (cells.length !== columnKeys.length)
+            continue;
+        const record = {};
+        for (let j = 0; j < columnKeys.length; j++) {
+            record[columnKeys[j]] = cells[j];
+        }
+        const id = record.id?.trim();
+        const asserts = record.asserts?.trim();
+        if (!id || !asserts)
+            continue;
+        rows.push({
+            id,
+            asserts,
+            writableAt: parsePhaseReference(record.writableAt ?? ""),
+            passesAt: parsePhaseReference(record.passesAt ?? ""),
+            state: parseState(record.state ?? ""),
+            kind: parseOptionalKind(record.kind ?? ""),
+            scope: parseOptionalScope(record.scope ?? ""),
+        });
+    }
+    return rows;
+}
+/**
+ * Parse a Test Trajectory from an impl.md body (the content after the
+ * frontmatter). Returns an empty trajectory with `present: false` when the
+ * `## Test Trajectory` section is absent. Never throws — errors are surfaced
+ * by the validator, not the parser.
+ */
+export function parseTrajectory(body) {
+    const lines = body.split("\n");
+    const hasTrajectory = lines.some((line) => TRAJECTORY_HEADING.test(line));
+    if (!hasTrajectory) {
+        return { rows: [], deferred: [], present: false };
+    }
+    const { tableLines, deferredLines } = extractTrajectoryBlock(lines);
+    const rows = parseTrajectoryTable(tableLines);
+    const deferred = parseDeferredBlock(deferredLines);
+    return { rows, deferred, present: true };
+}

package/dist/lib/trajectory/state-ops.d.ts

@@ -0,0 +1,49 @@
+import type { Trajectory, TrajectoryRow, TrajectoryState } from "./parser.js";
+/**
+ * Rows whose `Writable at` equals the given phase and whose state is not
+ * yet `written` or beyond. These are tests the author should commit as
+ * failing at phase start (before implementation work).
+ */
+export declare function getRowsWritableAt(trajectory: Trajectory, phase: number): TrajectoryRow[];
+/**
+ * Rows whose `Passes at` equals the given phase, regardless of current state.
+ * These are the tests that must be in `passing` (or `skipped` with reason)
+ * before the phase can close.
+ */
+export declare function getRowsPassingAt(trajectory: Trajectory, phase: number): TrajectoryRow[];
+/**
+ * Rows that block phase-close for the given phase. A row blocks if its
+ * `Passes at` equals the phase AND its state is not one of the terminal
+ * states (`passing`, `skipped`, `blocked` — blocked implies a tracked
+ * investigation, not a silent fail).
+ */
+export declare function getRowsBlockingPhaseClose(trajectory: Trajectory, phase: number): TrajectoryRow[];
+/**
+ * Update the `State` column for a specific row ID in an impl.md body.
+ * Returns the new body. The input must be the full impl body (after
+ * frontmatter); the output is body markdown with exactly one cell changed.
+ *
+ * If the row ID is not found, returns the body unchanged.
+ */
+export declare function updateRowState(body: string, id: string, newState: TrajectoryState): string;
+/**
+ * Convenience: parse the body, compute blocking rows, and return error
+ * messages suitable for a hook's stderr. Returns empty array if phase can
+ * close cleanly.
+ */
+export declare function computePhaseCloseBlockers(body: string, phase: number): {
+    row: TrajectoryRow;
+    message: string;
+}[];
+/**
+ * Convenience: nudge text for phase start. Returns a string listing rows
+ * whose `Writable at` equals the phase and are not yet written, or null
+ * if nothing needs authoring.
+ */
+export declare function getPhaseStartNudge(body: string, phase: number): string | null;
+/**
+ * Convenience: nudge text for near-phase-close. Returns a string listing
+ * rows whose `Passes at` equals the phase but state is not yet `passing`
+ * or `skipped`, or null if the trajectory for this phase is green.
+ */
+export declare function getPhaseCloseNudge(body: string, phase: number): string | null;

package/dist/lib/trajectory/state-ops.js

@@ -0,0 +1,132 @@
+import { parseTrajectory } from "./parser.js";
+/**
+ * Rows whose `Writable at` equals the given phase and whose state is not
+ * yet `written` or beyond. These are tests the author should commit as
+ * failing at phase start (before implementation work).
+ */
+export function getRowsWritableAt(trajectory, phase) {
+    return trajectory.rows.filter((row) => row.writableAt === phase &&
+        (row.state === "planned" || row.state === "writable" || row.state === "unknown"));
+}
+/**
+ * Rows whose `Passes at` equals the given phase, regardless of current state.
+ * These are the tests that must be in `passing` (or `skipped` with reason)
+ * before the phase can close.
+ */
+export function getRowsPassingAt(trajectory, phase) {
+    return trajectory.rows.filter((row) => row.passesAt === phase);
+}
+/**
+ * Rows that block phase-close for the given phase. A row blocks if its
+ * `Passes at` equals the phase AND its state is not one of the terminal
+ * states (`passing`, `skipped`, `blocked` — blocked implies a tracked
+ * investigation, not a silent fail).
+ */
+export function getRowsBlockingPhaseClose(trajectory, phase) {
+    return trajectory.rows.filter((row) => row.passesAt === phase &&
+        row.state !== "passing" &&
+        row.state !== "skipped" &&
+        row.state !== "blocked");
+}
+/**
+ * Update the `State` column for a specific row ID in an impl.md body.
+ * Returns the new body. The input must be the full impl body (after
+ * frontmatter); the output is body markdown with exactly one cell changed.
+ *
+ * If the row ID is not found, returns the body unchanged.
+ */
+export function updateRowState(body, id, newState) {
+    const lines = body.split("\n");
+    let inTrajectoryTable = false;
+    let headerCells = null;
+    let stateIndex = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (/^##\s+Test Trajectory\b/.test(line)) {
+            inTrajectoryTable = true;
+            headerCells = null;
+            stateIndex = -1;
+            continue;
+        }
+        if (!inTrajectoryTable)
+            continue;
+        // A new heading ends the trajectory block
+        if (/^#{1,3}\s+/.test(line) && !/^##\s+Test Trajectory\b/.test(line)) {
+            inTrajectoryTable = false;
+            continue;
+        }
+        const trimmed = line.trim();
+        if (!trimmed.startsWith("|") || !trimmed.endsWith("|"))
+            continue;
+        const cells = trimmed
+            .slice(1, -1)
+            .split("|")
+            .map((c) => c.trim());
+        // Header row: find the State column index
+        if (!headerCells) {
+            headerCells = cells;
+            stateIndex = cells.findIndex((c) => c.toLowerCase() === "state");
+            continue;
+        }
+        // Separator row: skip
+        if (cells.every((c) => /^:?-+:?$/.test(c)))
+            continue;
+        // Data row: check ID and update State
+        if (cells[0] !== id || stateIndex === -1)
+            continue;
+        if (cells[stateIndex] === newState)
+            return body;
+        const newCells = [...cells];
+        newCells[stateIndex] = newState;
+        // Preserve the leading/trailing pipe and surrounding whitespace
+        const leadingWs = line.match(/^\s*/)?.[0] ?? "";
+        lines[i] = `${leadingWs}| ${newCells.join(" | ")} |`;
+        return lines.join("\n");
+    }
+    return body;
+}
+/**
+ * Convenience: parse the body, compute blocking rows, and return error
+ * messages suitable for a hook's stderr. Returns empty array if phase can
+ * close cleanly.
+ */
+export function computePhaseCloseBlockers(body, phase) {
+    const trajectory = parseTrajectory(body);
+    if (!trajectory.present)
+        return [];
+    const blocking = getRowsBlockingPhaseClose(trajectory, phase);
+    return blocking.map((row) => ({
+        row,
+        message: `  [${row.id}] ${row.asserts} — state: ${row.state} (must be 'passing' or 'skipped' to close Phase ${phase})`,
+    }));
+}
+/**
+ * Convenience: nudge text for phase start. Returns a string listing rows
+ * whose `Writable at` equals the phase and are not yet written, or null
+ * if nothing needs authoring.
+ */
+export function getPhaseStartNudge(body, phase) {
+    const trajectory = parseTrajectory(body);
+    if (!trajectory.present)
+        return null;
+    const rows = getRowsWritableAt(trajectory, phase);
+    if (rows.length === 0)
+        return null;
+    const lines = rows.map((r) => `  [${r.id}] ${r.asserts}`);
+    return `Phase ${phase} opens with these tests to author (commit as failing before implementation work):\n${lines.join("\n")}`;
+}
+/**
+ * Convenience: nudge text for near-phase-close. Returns a string listing
+ * rows whose `Passes at` equals the phase but state is not yet `passing`
+ * or `skipped`, or null if the trajectory for this phase is green.
+ */
+export function getPhaseCloseNudge(body, phase) {
+    const trajectory = parseTrajectory(body);
+    if (!trajectory.present)
+        return null;
+    const blocking = getRowsBlockingPhaseClose(trajectory, phase);
+    if (blocking.length === 0)
+        return null;
+    const lines = blocking.map((r) => `  [${r.id}] ${r.asserts} — state: ${r.state}`);
+    return `Phase ${phase} cannot close until these trajectory rows are 'passing' or 'skipped':\n${lines.join("\n")}`;
+}