@infinitedusky/indusk-mcp 1.44.0 → 1.44.2

package/hooks/gate-reminder.js

@@ -1,222 +1,127 @@
 #!/usr/bin/env node
 /**
- * PostToolUse hook: nudges the agent to call advance_plan when a phase is complete.
+ * PostToolUse hook on Edit|Write: the phase reminder.
  *
- * This hook is advisory — it cannot block. It outputs a reminder message
- * that appears in the conversation as additional context.
+ * When an edit to an `impl.md` closes a phase, tell the agent which trajectory
+ * rows the next phase opens with — the tests to author red before any code —
+ * and to call advance_plan. When a phase is mid-flight, name the rows that will
+ * block its close. Advisory: it never blocks.
+ *
+ * Delivery. A PostToolUse hook reaches the model in exactly one way at exit 0:
+ * a JSON envelope on stdout carrying `hookSpecificOutput.additionalContext`.
+ * stderr at exit 0 goes to the debug log and nowhere else. For its whole life
+ * this hook wrote to stderr and exited 0, so it was never once heard
+ * (workbench-trust-fixes, research F9). `console.info` writes to stdout and is
+ * on the linter's `noConsole` allowlist; a `console.log` here was swept once
+ * already and would be again.
+ *
+ * Phases. Two sequences ordered by document position (test-phase-structure):
+ * "the next phase" is the next heading in the document, whatever its kind, and
+ * trajectory cells are read through the shared `_trajectory-parser.js`, so
+ * `Build Phase 2`, `Test Phase 1` and `Phase 2` mean here exactly what they
+ * mean to check-gates. The nudge text has one definition — this file — pinned
+ * by `phase-start-nudge-single-definition.test.ts`.
  */
 
 import { readFileSync } from "node:fs";
-import { FORWARD_INTELLIGENCE_HEADING, gateHeading, PHASE_HEADING } from "./_impl-headings.js";
+import { phaseOrdinal, phaseSequence } from "./_impl-headings.js";
+import { parseImplPhases } from "./_impl-phases.js";
+import { parseTrajectoryFromBody, stripFrontmatter } from "./_trajectory-parser.js";
 
-// Read hook input from stdin
 let input = "";
 for await (const chunk of process.stdin) {
 	input += chunk;
 }
 
 const event = JSON.parse(input);
-const toolInput = event.tool_input ?? {};
-const filePath = toolInput.file_path ?? "";
+const filePath = event.tool_input?.file_path ?? "";
 
-// Fast path: not an impl.md file
+// Fast path: not an impl.md. Silence is the correct output here (A2).
 if (!filePath.endsWith("/impl.md") && !filePath.endsWith("\\impl.md")) {
 	process.exit(0);
 }
 
-// Read the impl file (post-edit state)
 let content;
 try {
-	content = readFileSync(filePath, "utf-8");
+	content = readFileSync(filePath, "utf-8"); // post-edit state
 } catch {
 	process.exit(0);
 }
 
-// Parse phases
-function parsePhases(text) {
-	const fmMatch = text.match(/^---\n[\s\S]*?\n---\n/);
-	const body = fmMatch ? text.slice(fmMatch[0].length) : text;
-
-	const lines = body.split("\n");
-	const phases = [];
-	let currentPhase = null;
-	let currentGateType = "implementation";
-
-	for (const line of lines) {
-		const phaseMatch = line.match(PHASE_HEADING);
-		if (phaseMatch) {
-			if (currentPhase) phases.push(currentPhase);
-			currentPhase = {
-				number: parseInt(phaseMatch[1], 10),
-				name: phaseMatch[2].trim(),
-				items: [],
-			};
-			currentGateType = "implementation";
-			continue;
-		}
-
-		// [1] is the phase number, [2] the gate kind — see gateHeading().
-		const gateMatch = line.match(gateHeading("(Verification|Context|Document)"));
-		if (gateMatch) {
-			currentGateType = gateMatch[2].toLowerCase();
-			continue;
-		}
-
-		if (line.match(FORWARD_INTELLIGENCE_HEADING)) {
-			currentGateType = "_fi";
-			continue;
-		}
-
-		if (currentPhase && currentGateType !== "_fi") {
-			const itemMatch = line.match(/^-\s+\[([ x])\]\s+(.*)/);
-			if (itemMatch) {
-				currentPhase.items.push({
-					checked: itemMatch[1] === "x",
-					gate: currentGateType,
-				});
-			}
-		}
-	}
-	if (currentPhase) phases.push(currentPhase);
-	return phases;
+const AUTHORABLE = new Set(["planned", "writable", ""]);
+const CLOSES_PHASE = new Set(["passing", "skipped", "blocked"]);
+
+const body = stripFrontmatter(content);
+const sequence = phaseSequence(body);
+const phases = parseImplPhases(content);
+const { rows } = parseTrajectoryFromBody(body);
+const hasTestPhases = sequence.some((p) => p.kind === "test");
+
+const ordinalOf = (ref) => phaseOrdinal(ref, sequence);
+const label = (p) =>
+	p.kind === "test"
+		? `Test Phase ${p.number}`
+		: hasTestPhases
+			? `Build Phase ${p.number}`
+			: `Phase ${p.number}`;
+
+/** Rows the next phase must open by authoring, red. */
+function writableAtNudge(next) {
+	const target = ordinalOf(next);
+	const due = rows.filter(
+		(r) =>
+			ordinalOf({ kind: r.writableAtKind, number: r.writableAt }) === target &&
+			AUTHORABLE.has(r.state),
+	);
+	if (due.length === 0) return null;
+	const lines = due.map((r) => `  [${r.id}] ${r.asserts}`);
+	return `${label(next)} opens with these tests to author (commit as failing before implementation work):\n${lines.join("\n")}`;
 }
 
-const phases = parsePhases(content);
-
-// Find the first phase that just became fully complete
-// (all items checked, including gates)
-for (const phase of phases) {
-	const allChecked = phase.items.every((i) => i.checked);
-	if (!allChecked) continue;
-
-	// Check if the next phase has any unchecked items (meaning work hasn't started there yet)
-	const nextPhase = phases.find((p) => p.number === phase.number + 1);
-	if (nextPhase) {
-		const nextHasUnchecked = nextPhase.items.some((i) => !i.checked);
-		if (nextHasUnchecked) {
-			// This phase is complete and next phase hasn't started
-			const _result = {
-				hookSpecificOutput: {
-					hookEventName: "PostToolUse",
-				},
-			};
-			console.error(
-				`Phase ${phase.number} (${phase.name}) is fully complete. Call advance_plan to validate gates before starting Phase ${nextPhase.number}.`,
-			);
-			// Add trajectory nudges if applicable
-			const trajectory = parseTrajectoryRows(content);
-			if (trajectory.rows.length > 0) {
-				const startNudge = writableAtNudge(trajectory, nextPhase.number);
-				if (startNudge) console.error(`\n${startNudge}`);
-			}
-			process.exit(0);
-		}
-	}
+const parts = [];
+
+// A phase that just became fully complete, with the next one not yet started.
+// "Not started" means NOTHING in it is checked — once the next phase has
+// begun, repeating the send-off on every edit is noise, and the phase in
+// progress needs its own blockers instead (falsification A19).
+for (let i = 0; i + 1 < phases.length; i++) {
+	const phase = phases[i];
+	const next = phases[i + 1];
+	if (phase.items.length === 0 || !phase.items.every((x) => x.checked)) continue;
+	if (next.items.some((x) => x.checked)) continue;
+	parts.push(
+		`${label(phase)} (${phase.name}) is fully complete. Call advance_plan to validate gates before starting ${label(next)}.`,
+	);
+	const nudge = writableAtNudge(next);
+	if (nudge) parts.push(nudge);
+	break;
 }
 
-// Additional nudge: if any phase is mid-execution (some items checked, some not)
-// and has trajectory rows blocking close, warn about them.
-const trajectory = parseTrajectoryRows(content);
-if (trajectory.rows.length > 0) {
+// Otherwise: a phase mid-flight whose trajectory rows will block its close.
+if (parts.length === 0) {
 	for (const phase of phases) {
-		const anyChecked = phase.items.some((i) => i.checked);
-		const allChecked = phase.items.every((i) => i.checked);
-		if (!anyChecked || allChecked) continue;
-		const blockers = trajectory.rows.filter(
-			(row) =>
-				row.passesAt === phase.number &&
-				row.state !== "passing" &&
-				row.state !== "skipped" &&
-				row.state !== "blocked",
+		const checked = phase.items.filter((x) => x.checked).length;
+		if (checked === 0 || checked === phase.items.length) continue;
+		const target = ordinalOf(phase);
+		const blockers = rows.filter(
+			(r) =>
+				ordinalOf({ kind: r.passesAtKind, number: r.passesAt }) === target &&
+				!CLOSES_PHASE.has(r.state),
 		);
-		if (blockers.length > 0) {
-			const lines = blockers.map((r) => `  [${r.id}] ${r.asserts} — state: ${r.state}`);
-			console.error(
-				`Phase ${phase.number} trajectory rows still not passing (will block phase close):\n${lines.join("\n")}`,
-			);
-			break; // one nudge per hook invocation
-		}
-	}
-}
-
-process.exit(0);
-
-// ------------------------------------------------------------------
-// Trajectory parsing (minimal — just id, passesAt, state)
-// ------------------------------------------------------------------
-
-function parseTrajectoryRows(implContent) {
-	const fmMatch = implContent.match(/^---\n[\s\S]*?\n---\n/);
-	const body = fmMatch ? implContent.slice(fmMatch[0].length) : implContent;
-	const lines = body.split("\n");
-
-	let inTrajectory = false;
-	const tableLines = [];
-	for (const line of lines) {
-		if (/^##\s+Test Trajectory\b/.test(line)) {
-			inTrajectory = true;
-			continue;
-		}
-		if (!inTrajectory) continue;
-		if (/^###\s+Deferred Verification\b/.test(line)) break;
-		if (/^#{1,3}\s+/.test(line)) {
-			const depth = (line.match(/^(#{1,6})/) || ["", ""])[1].length;
-			if (depth <= 3) break;
-		}
-		tableLines.push(line);
-	}
-
-	const pipeLines = tableLines.filter((l) => l.trim().startsWith("|"));
-	if (pipeLines.length < 2) return { rows: [] };
-	const header = parseRow(pipeLines[0]);
-	const sep = parseRow(pipeLines[1]);
-	if (!sep.every((c) => /^:?-+:?$/.test(c))) return { rows: [] };
-
-	const keys = header.map((h) => {
-		const n = h.toLowerCase().trim();
-		if (n === "id") return "id";
-		if (n === "writable at") return "writableAt";
-		if (n === "passes at") return "passesAt";
-		if (n === "state") return "state";
-		if (n === "asserts") return "asserts";
-		return n;
-	});
-
-	const rows = [];
-	for (let i = 2; i < pipeLines.length; i++) {
-		const cells = parseRow(pipeLines[i]);
-		if (cells.length !== keys.length) continue;
-		const rec = {};
-		for (let j = 0; j < keys.length; j++) rec[keys[j]] = cells[j];
-		if (!rec.id) continue;
-		const w = (rec.writableAt || "").match(/^\s*Phase\s+(\d+)\s*$/i);
-		const p = (rec.passesAt || "").match(/^\s*Phase\s+(\d+)\s*$/i);
-		rows.push({
-			id: rec.id.trim(),
-			asserts: (rec.asserts || "").trim(),
-			writableAt: w ? Number.parseInt(w[1], 10) : Number.NaN,
-			passesAt: p ? Number.parseInt(p[1], 10) : Number.NaN,
-			state: (rec.state || "").toLowerCase().trim(),
-		});
+		if (blockers.length === 0) continue;
+		const lines = blockers.map((r) => `  [${r.id}] ${r.asserts} — state: ${r.state}`);
+		parts.push(
+			`${label(phase)} trajectory rows still not passing (will block phase close):\n${lines.join("\n")}`,
+		);
+		break; // one nudge per invocation
 	}
-	return { rows };
 }
 
-function parseRow(line) {
-	const t = line.trim();
-	if (!t.startsWith("|") || !t.endsWith("|")) return [];
-	return t
-		.slice(1, -1)
-		.split("|")
-		.map((c) => c.trim());
-}
-
-function writableAtNudge(trajectory, phase) {
-	const rows = trajectory.rows.filter(
-		(r) =>
-			r.writableAt === phase && (r.state === "planned" || r.state === "writable" || r.state === ""),
+if (parts.length > 0) {
+	console.info(
+		JSON.stringify({
+			hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: parts.join("\n\n") },
+		}),
 	);
-	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")}`;
 }
+process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@infinitedusky/indusk-mcp",
-  "version": "1.44.0",
+  "version": "1.44.2",
   "description": "InDusk development system — skills, MCP tools, and CLI for structured AI-assisted development",
   "type": "module",
   "files": [
@@ -109,6 +109,6 @@
     "build": "tsc",
     "start": "node dist/server/index.js",
     "test": "vitest run",
-    "release": "npm whoami && pnpm publish --no-git-checks"
+    "release": "bash scripts/release-guard.sh && npm whoami && pnpm publish --no-git-checks"
   }
 }

package/skills/cleanup.md

@@ -39,7 +39,7 @@ Two consequences worth being explicit about:
 
 This is best-practice-guided decomposition, not blanket extraction. **Extraction is not universally good** — forcing it produces 8-line "components", prop-drilling, and the wrong abstraction (which costs more than the duplication it removes). Recommend only what best practices actually warrant.
 
-1. **Find the changed files that deserve scrutiny.** The threshold is a focus tool, not a cap. Use `listOversizedChangedFiles(planRoot, baseRef)` — import it from `@infinitedusky/indusk-mcp/cleanup/oversized` in a consumer project (or `apps/indusk-mcp/src/lib/cleanup/oversized.ts` in the dusk monorepo), invoked via `tsx` or a short Node script — it diffs the plan's branch against its merge base and returns the changed files over their resolved cleanup cap, with `{ path, loc, cap, scope, isNew }`. The caps come from the `cleanup` config block in `.indusk/config.json` (`max_file_loc` + per-scope overrides). A file being flagged means "look here", not "this fails". **Workbench caveat:** run it against the git repo/worktree where the code lives — the workbench root (where `.indusk/` lives) is not a git repo, and the lib throws there rather than silently reporting nothing.
+1. **Find the changed files that deserve scrutiny.** The threshold is a focus tool, not a cap. Use `listOversizedChangedFiles(planRoot, baseRef)` — import it from `@infinitedusky/indusk-mcp/cleanup/oversized` in a consumer project (or `apps/indusk-mcp/src/lib/cleanup/oversized.ts` in the dusk monorepo), invoked via `tsx` or a short Node script — it diffs the plan's branch against its merge base and returns the changed files over their resolved cleanup cap, with `{ path, loc, cap, scope, isNew }`. The caps come from the `cleanup` config block in `.indusk/config.json` (`max_file_loc` + per-scope overrides). A file being flagged means "look here", not "this fails". **Workbench caveat:** run it against the git repo/worktree where the code lives. The workbench root (where `.indusk/` lives) holds the plan and none of the code, and the lib refuses there by declaration — it throws naming the declared repo dirs rather than reporting "nothing to clean" for code it never saw.
 2. **Apply the enabled domain extensions' best practices.** What counts as a cohesive unit is domain-specific — it comes from the enabled extensions, not from this skill. Read the skills of the project's enabled domain extensions (via `extensions_status` / `get_skill_summaries`):
    - **`nextjs`** — "minimize `"use client"` boundaries, push them as deep as possible"; "server components can't use hooks/event handlers". The concrete move on a Next.js project is often *pull the interactive `"use client"` island out of a big server component into its own file*, splitting server and client concerns.
    - **`react`** — "one component per file for non-trivial components".

package/skills/retrospective.md

@@ -206,6 +206,7 @@ Re-read CLAUDE.md in full. After the entire impl is done, verify:
 - **Key Decisions** — was the ADR decision added (post-ADR trigger)?
 - **Known Gotchas** — were all surprises and corrections captured?
 - **Current State** — does it reflect what's actually in progress?
+- **Sequence** — does every active plan folder have exactly one fate: a step declared in the root `master.md` sequence, archived with a `closed_reason`, or standalone with a reason written in the master? A folder with none is how a close-out goes unwritten for weeks (indusk-makeover sat `completed` for 53 days in a queue labelled "any time"). Fix it here — declare it, archive it, or write the reason — and write any follow-on this plan surfaced into the brief of the step that owns it, not into this retrospective alone.
 
 Fix any inaccuracies. The impl may have changed things that weren't anticipated in the per-phase context updates.