@infinitedusky/indusk-mcp 0.7.2 → 0.8.0

package/hooks/check-gates.js

@@ -80,6 +80,22 @@ if (event.tool_name === "Edit" && oldContent) {
 	process.exit(0);
 }
 
+// Detect workflow type from content frontmatter
+function detectWorkflow(content) {
+	const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n/);
+	const fm = fmMatch ? fmMatch[1] : "";
+	const m = fm.match(/workflow:\s*(bugfix|refactor|feature|spike)/);
+	return m ? m[1] : "feature";
+}
+
+// Which gate types are required per workflow
+const WORKFLOW_GATES = {
+	feature: ["verification", "context", "document"],
+	refactor: ["verification", "context", "document"],
+	bugfix: ["verification", "document"],
+	spike: [],
+};
+
 // Parse phases from the NEW content (after edit) and OLD content (before edit)
 function parsePhases(content) {
 	// Strip frontmatter
@@ -131,6 +147,8 @@ function parsePhases(content) {
 	return phases;
 }
 
+const workflow = detectWorkflow(fullContent);
+const requiredGates = WORKFLOW_GATES[workflow] || WORKFLOW_GATES.feature;
 const oldPhases = parsePhases(fullContent);
 const newPhases = parsePhases(newFullContent);
 
@@ -171,15 +189,19 @@ for (const item of newlyChecked) {
 	for (const phase of oldPhases) {
 		if (phase.number >= item.phase) break;
 
+		const isOverridden = (text) =>
+			text.includes("(none needed)") ||
+			text.includes("(not applicable)") ||
+			text.includes("skip-reason:");
+
 		const uncheckedGates = phase.items.filter(
-			(i) =>
-				!i.checked && (i.gate === "verification" || i.gate === "context" || i.gate === "document"),
+			(i) => !i.checked && !isOverridden(i.text) && requiredGates.includes(i.gate),
 		);
 
 		if (uncheckedGates.length > 0) {
 			const missing = uncheckedGates.map((i) => `  [${i.gate}] ${i.text}`).join("\n");
 			process.stderr.write(
-				`Phase ${item.phase} blocked: complete Phase ${phase.number} gates first:\n${missing}\n`,
+				`Phase ${item.phase} blocked: complete Phase ${phase.number} gates first:\n${missing}\nTo skip a gate item, mark it with (none needed) or skip-reason: {why}\n`,
 			);
 			process.exit(2);
 		}

package/hooks/validate-impl-structure.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse hook: validates that impl phases have all four gate sections.
+ *
+ * Every phase must have: implementation items, Verification, Context, Document.
+ * Sections can opt out with (none needed), (not applicable), or skip-reason: {why}.
+ *
+ * Exit 0 = allow the edit
+ * Exit 2 = block the edit (stderr sent to agent as feedback)
+ */
+
+import { readFileSync } from "node:fs";
+
+// 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 ?? "";
+
+// Fast path: not an impl.md file
+if (!filePath.endsWith("/impl.md") && !filePath.endsWith("\\impl.md")) {
+	process.exit(0);
+}
+
+// Check for skip-gates escape hatch
+const newContent = toolInput.new_string ?? toolInput.content ?? "";
+if (newContent.includes("<!-- skip-gates -->")) {
+	process.exit(0);
+}
+
+// Determine the full new content after edit
+let newFullContent;
+if (event.tool_name === "Edit" && toolInput.old_string) {
+	try {
+		const diskContent = readFileSync(filePath, "utf-8");
+		newFullContent = diskContent.replace(toolInput.old_string, newContent);
+	} catch {
+		// File doesn't exist yet — will be created by Write
+		newFullContent = newContent;
+	}
+} else if (event.tool_name === "Write") {
+	newFullContent = toolInput.content ?? "";
+} else {
+	process.exit(0);
+}
+
+// Only validate if this edit is adding/modifying phase structure
+// Check if the edit contains phase headers
+const editContent = toolInput.new_string ?? toolInput.content ?? "";
+const hasPhaseHeader = /###\s+Phase\s+\d+/.test(editContent);
+const hasChecklistItem = /- \[ \]/.test(editContent);
+
+// If the edit doesn't touch phase structure, allow it
+if (!hasPhaseHeader && !hasChecklistItem) {
+	process.exit(0);
+}
+
+// Parse frontmatter to detect workflow type
+const fmMatch = newFullContent.match(/^---\n([\s\S]*?)\n---\n/);
+const frontmatter = fmMatch ? fmMatch[1] : "";
+const body = fmMatch ? newFullContent.slice(fmMatch[0].length) : newFullContent;
+
+// Detect workflow type from frontmatter (workflow: bugfix|refactor|feature)
+// or infer from plan structure
+const workflowMatch = frontmatter.match(/workflow:\s*(bugfix|refactor|feature|spike)/);
+const workflow = workflowMatch ? workflowMatch[1] : "feature";
+
+// Different workflows have different requirements
+const requirements = {
+	feature: { verification: true, context: true, document: true },
+	refactor: { verification: true, context: true, document: true },
+	bugfix: { verification: true, context: false, document: true },
+	spike: { verification: false, context: false, document: false },
+}[workflow];
+const lines = body.split("\n");
+
+const phases = [];
+let currentPhase = null;
+let currentSection = "implementation";
+
+for (const line of lines) {
+	const phaseMatch = line.match(/^###\s+Phase\s+(\d+)[:\s]+(.*)/);
+	if (phaseMatch) {
+		if (currentPhase) phases.push(currentPhase);
+		currentPhase = {
+			number: parseInt(phaseMatch[1], 10),
+			name: phaseMatch[2].trim(),
+			hasImplementation: false,
+			hasVerification: false,
+			hasContext: false,
+			hasDocument: false,
+		};
+		currentSection = "implementation";
+		continue;
+	}
+
+	if (!currentPhase) continue;
+
+	// Detect gate section headers
+	const verMatch = line.match(/^####\s+Phase\s+\d+\s+Verification\b/);
+	if (verMatch) {
+		currentPhase.hasVerification = true;
+		currentSection = "verification";
+		continue;
+	}
+
+	const ctxMatch = line.match(/^####\s+Phase\s+\d+\s+Context\b/);
+	if (ctxMatch) {
+		currentPhase.hasContext = true;
+		currentSection = "context";
+		continue;
+	}
+
+	const docMatch = line.match(/^####\s+Phase\s+\d+\s+Document\b/);
+	if (docMatch) {
+		currentPhase.hasDocument = true;
+		currentSection = "document";
+		continue;
+	}
+
+	// Check for implementation items
+	if (currentSection === "implementation" && /^-\s+\[[ x]\]/.test(line)) {
+		currentPhase.hasImplementation = true;
+	}
+
+	// Forward intelligence doesn't count as a gate
+	if (line.match(/^####\s+Phase\s+\d+\s+Forward Intelligence\b/)) {
+		currentSection = "fi";
+	}
+}
+if (currentPhase) phases.push(currentPhase);
+
+// Check for opt-out content in gate sections
+// Re-scan to check if sections that exist have (none needed) or skip-reason:
+const isOptedOut = (text) =>
+	text.includes("(none needed)") ||
+	text.includes("(not applicable)") ||
+	text.includes("skip-reason:");
+
+// Validate each phase
+const errors = [];
+for (const phase of phases) {
+	if (!phase.hasImplementation) continue; // Skip phases with no impl items (might be a header-only outline)
+
+	const missing = [];
+	if (requirements.verification && !phase.hasVerification) missing.push("Verification");
+	if (requirements.context && !phase.hasContext) missing.push("Context");
+	if (requirements.document && !phase.hasDocument) missing.push("Document");
+
+	if (missing.length > 0) {
+		errors.push(`Phase ${phase.number} (${phase.name}) is missing: ${missing.join(", ")}`);
+	}
+}
+
+if (errors.length > 0) {
+	const msg = errors.join("\n");
+	const reqNames = Object.entries(requirements)
+		.filter(([, v]) => v)
+		.map(([k]) => k.charAt(0).toUpperCase() + k.slice(1));
+	process.stderr.write(
+		`Impl structure incomplete (workflow: ${workflow}):\n${msg}\n\nThis workflow requires: ${reqNames.join(", ")} sections per phase.\nIf a section isn't needed, add it with (none needed) or skip-reason: {why}\nExample: #### Phase 1 Document\\n(none needed)\nTo change requirements, add 'workflow: bugfix' to the impl frontmatter.\n`,
+	);
+	process.exit(2);
+}
+
+process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@infinitedusky/indusk-mcp",
-	"version": "0.7.2",
+	"version": "0.8.0",
 	"description": "InDusk development system — skills, MCP tools, and CLI for structured AI-assisted development",
 	"type": "module",
 	"files": [

package/skills/document.md

@@ -97,6 +97,35 @@ flowchart TD
 
 **Never** use bare ` ```mermaid ` blocks without the wrapper. The diagrams are often too small to read inline, and the FullscreenDiagram gives users zoom and pan controls.
 
+## Documentation by Workflow Type
+
+The document gate's expectations vary by workflow type. The hook enforces that the section exists, but what goes in it depends on what you're building.
+
+### Feature (full documentation)
+
+A feature is new functionality. It needs complete documentation:
+- Write new reference pages for tools, APIs, or configuration added
+- Write new guide pages for workflows introduced
+- Create Mermaid diagrams for architecture, flows, and relationships
+- Update existing pages that reference the area you changed
+- Create FullscreenDiagram-wrapped diagrams for anything structural
+
+### Refactor (update existing docs)
+
+A refactor restructures existing code. Documentation should reflect the new structure:
+- Update existing pages that reference moved/renamed code
+- Update diagrams that show the old structure
+- Don't create new pages unless the refactor introduces new concepts
+- If nothing user-facing changed, mark with `(none needed)`
+
+### Bugfix (document the fix)
+
+A bugfix solves a specific problem. Documentation is about the fix, not new content:
+- Update any docs that described the broken behavior
+- If the bug revealed a gotcha, add it to the relevant reference page
+- If the fix changes a public API or configuration, update that reference page
+- For internal-only fixes, mark with `(none needed)`
+
 ## Shaping Impl Documents
 
 When writing an impl (via the plan skill), every phase should consider documentation:
@@ -106,7 +135,7 @@ When writing an impl (via the plan skill), every phase should consider documenta
 - [ ] {Specific docs page to write or update}
 ```
 
-The agent writing the impl must answer: **"What does a user or developer need to know about what this phase built?"** If the answer is "nothing user-facing" — no document items needed. Not every phase produces docs. But the question must be asked.
+The agent writing the impl must answer: **"What does a user or developer need to know about what this phase built?"** If the answer is "nothing user-facing" — `(none needed)` or `skip-reason:` to opt out. Not every phase produces docs. But the question must be asked, and the section must exist (enforced by hook).
 
 ### Document Items Are Blocking
 

package/skills/plan.md

@@ -49,7 +49,14 @@ Workflow templates are in `templates/workflows/` in the package. They describe w
 
 2. **Figure out where things stand.** If a plan folder already exists, read what's there. Check frontmatter statuses. The next document to write is the first one that's missing or incomplete.
 
-3. **If starting fresh**, create the plan folder and start with the first document for the workflow type:
+3. **If starting fresh**, do a quick scan of the project (read CLAUDE.md, check the code graph) to understand the context. Then **ask the user discovery questions before doing any research or writing any documents.** The goal is to understand what they're trying to achieve, not just what they named the plan. Good discovery questions:
+   - "What problem are you trying to solve?" or "What should this feature do for your users?"
+   - "Is there anything specific you've already thought through or have strong opinions about?"
+   - "Are there any constraints I should know about — timeline, technology preferences, things to avoid?"
+
+   For non-developers especially, this conversation is critical. They may not know the right technical terms, but they know what they want. Draw that out before proceeding.
+
+   Once you understand the intent, create the plan folder and start with the first document for the workflow type:
    - **feature**: start with research
    - **bugfix**: start with brief (streamlined template)
    - **refactor**: start with brief (includes boundary map)
@@ -62,7 +69,7 @@ Workflow templates are in `templates/workflows/` in the package. They describe w
    - Include the graph findings in research.md — concrete numbers like "X has 12 dependents across 3 apps"
    Document what you find. The research doc records findings and analysis, but saves the recommendation for the brief.
 
-4. **If research is done**, write the brief. This is where a direction emerges from the research. The brief proposes what we're building and why, informed by what the research uncovered. Present for review.
+4. **If research is done**, write the brief. This is where a direction emerges from the research. The brief proposes what we're building and why, informed by what the research uncovered. **Present the brief and have a conversation about it.** Don't just ask "does this look good?" — walk the user through it: "Here's what I'm proposing we build. Does this match what you had in mind? Is there anything missing, or anything here you don't want?" Iterate until the user is genuinely happy with the direction, then mark it as `accepted`.
 
 5. **If brief is accepted** and the workflow includes an ADR (feature only), write the ADR. The ADR formalizes the decisions that were discussed during research and led to the brief. It records what was chosen, what was rejected, and why. **After the ADR is accepted**, add a one-liner to CLAUDE.md's Key Decisions section per the context skill: `- {decision summary} — see planning/{plan}/adr.md`