@infinitedusky/indusk-mcp 1.1.2 → 1.2.0

package/dist/bin/cli.js

@@ -75,6 +75,13 @@ ext
     const { extensionsRemove } = await import("./commands/extensions.js");
     await extensionsRemove(process.cwd(), names);
 });
+ext
+    .command("update [names...]")
+    .description("Update third-party extensions from their original source")
+    .action(async (names) => {
+    const { extensionsUpdate } = await import("./commands/extensions.js");
+    await extensionsUpdate(process.cwd(), names);
+});
 ext
     .command("suggest")
     .description("Recommend extensions based on project contents")

package/dist/bin/commands/extensions.d.ts

@@ -4,4 +4,5 @@ export declare function extensionsEnable(projectRoot: string, names: string[]):
 export declare function extensionsDisable(projectRoot: string, names: string[]): Promise<void>;
 export declare function extensionsAdd(projectRoot: string, name: string, from: string): Promise<void>;
 export declare function extensionsRemove(projectRoot: string, names: string[]): Promise<void>;
+export declare function extensionsUpdate(projectRoot: string, names?: string[]): Promise<void>;
 export declare function extensionsSuggest(projectRoot: string): Promise<void>;

package/dist/bin/commands/extensions.js

@@ -68,7 +68,8 @@ export async function extensionsStatus(projectRoot) {
                     .map((r) => r.name)
                     .join(", ")}`;
         }
-        console.info(`  ${ext.manifest.name} — ${healthStatus}`);
+        const source = ext.manifest._source ? ` (from ${ext.manifest._source})` : " (built-in)";
+        console.info(`  ${ext.manifest.name}${source} — ${healthStatus}`);
     }
 }
 export async function extensionsEnable(projectRoot, names) {
@@ -194,9 +195,40 @@ export async function extensionsAdd(projectRoot, name, from) {
         console.info(`  ${name}: invalid JSON in manifest`);
         return;
     }
+    // Store the source in the manifest so `extensions update` can re-fetch
+    try {
+        const parsed = JSON.parse(manifestContent);
+        parsed._source = from;
+        manifestContent = JSON.stringify(parsed, null, "\t");
+    }
+    catch {
+        // leave as-is if parsing fails
+    }
     const targetPath = join(extensionsDir(projectRoot), `${name}.json`);
     writeFileSync(targetPath, manifestContent);
     console.info(`  ${name}: added from ${from}`);
+    // Run post-update hook if defined
+    try {
+        const manifest = JSON.parse(manifestContent);
+        if (manifest.hooks?.on_post_update) {
+            console.info(`  ${name}: running post-update hook...`);
+            try {
+                execSync(manifest.hooks.on_post_update, {
+                    cwd: projectRoot,
+                    timeout: 30000,
+                    stdio: ["ignore", "pipe", "pipe"],
+                });
+                console.info(`  ${name}: post-update hook completed`);
+            }
+            catch (e) {
+                const err = e;
+                console.info(`  ${name}: post-update hook failed: ${err.stderr?.trim() ?? "unknown error"}`);
+            }
+        }
+    }
+    catch {
+        // ignore parse errors
+    }
 }
 export async function extensionsRemove(projectRoot, names) {
     for (const name of names) {
@@ -221,6 +253,42 @@ export async function extensionsRemove(projectRoot, names) {
         }
     }
 }
+export async function extensionsUpdate(projectRoot, names) {
+    const extDir = extensionsDir(projectRoot);
+    if (!existsSync(extDir)) {
+        console.info("No extensions installed.");
+        return;
+    }
+    // Find all third-party extensions (ones with _source)
+    const files = readdirSync(extDir).filter((f) => f.endsWith(".json"));
+    let updated = 0;
+    for (const file of files) {
+        const name = file.replace(".json", "");
+        if (names?.length && !names.includes(name))
+            continue;
+        try {
+            const manifest = JSON.parse(readFileSync(join(extDir, file), "utf-8"));
+            if (!manifest._source) {
+                if (names && names.includes(name)) {
+                    console.info(`  ${name}: built-in extension — updated via package update, not extensions update`);
+                }
+                continue;
+            }
+            console.info(`  ${name}: updating from ${manifest._source}...`);
+            await extensionsAdd(projectRoot, name, manifest._source);
+            updated++;
+        }
+        catch {
+            console.info(`  ${name}: failed to read manifest`);
+        }
+    }
+    if (updated === 0) {
+        console.info("No third-party extensions to update.");
+    }
+    else {
+        console.info(`\n${updated} extension(s) updated.`);
+    }
+}
 export async function extensionsSuggest(projectRoot) {
     const builtins = getBuiltinExtensions();
     const suggestions = [];

package/dist/bin/commands/init.js

@@ -176,7 +176,12 @@ export async function init(projectRoot, options = {}) {
     console.info("\n[Hooks]");
     const hooksSource = join(packageRoot, "hooks");
     const hooksTarget = join(projectRoot, ".claude/hooks");
-    const hookFiles = ["check-gates.js", "gate-reminder.js", "validate-impl-structure.js", "check-catchup.js"];
+    const hookFiles = [
+        "check-gates.js",
+        "gate-reminder.js",
+        "validate-impl-structure.js",
+        "check-catchup.js",
+    ];
     if (existsSync(hooksSource)) {
         mkdirSync(hooksTarget, { recursive: true });
         for (const file of hookFiles) {

package/dist/lib/extension-loader.d.ts

@@ -17,6 +17,7 @@ export interface ExtensionManifest {
     name: string;
     description: string;
     version?: string;
+    _source?: string;
     provides: {
         skill?: boolean;
         networking?: {
@@ -38,6 +39,7 @@ export interface ExtensionManifest {
     hooks?: {
         on_init?: string;
         on_update?: string;
+        on_post_update?: string;
         on_health_check?: string;
         on_onboard?: string;
     };

package/dist/tools/graph-tools.js

@@ -6,22 +6,58 @@ function cgcPath() {
     const paths = [join(process.env.HOME ?? "", ".local/bin/cgc"), "/usr/local/bin/cgc"];
     return paths.find((p) => existsSync(p)) ?? null;
 }
-function runCgc(args, projectRoot) {
+function getFalkorHost() {
+    if (process.env.FALKORDB_HOST)
+        return process.env.FALKORDB_HOST;
+    // Try OrbStack hostname first, fall back to localhost
+    try {
+        execSync("ping -c 1 -W 1 falkordb.orb.local", {
+            stdio: ["ignore", "ignore", "ignore"],
+            timeout: 2000,
+        });
+        return "falkordb.orb.local";
+    }
+    catch {
+        return "localhost";
+    }
+}
+function checkFalkorConnection(host) {
+    try {
+        // Fast TCP check — try to connect to Redis port
+        execSync(`node -e "const s=require('net').connect(6379,'${host}');s.setTimeout(2000);s.on('connect',()=>{s.end();process.exit(0)});s.on('error',()=>process.exit(1));s.on('timeout',()=>process.exit(1))"`, { timeout: 3000, stdio: ["ignore", "ignore", "ignore"] });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function runCgc(args, projectRoot, options) {
     const cgc = cgcPath();
     if (!cgc) {
         return JSON.stringify({ error: "CGC not installed — run: pipx install codegraphcontext" });
     }
+    const host = getFalkorHost();
+    const timeout = options?.timeout ?? 15000;
+    // Fast pre-check: is FalkorDB reachable?
+    if (!options?.skipConnectionCheck && !checkFalkorConnection(host)) {
+        return JSON.stringify({
+            error: `FalkorDB not reachable at ${host}:6379. Is the container running? Try: docker start falkordb`,
+            host,
+            suggestion: host === "localhost"
+                ? "OrbStack not detected. If using OrbStack, ensure it's running."
+                : "Try: docker start falkordb — or check if OrbStack is running.",
+        });
+    }
     try {
         return execSync(`${cgc} ${args}`, {
             encoding: "utf-8",
-            timeout: 60000,
+            timeout,
             stdio: ["ignore", "pipe", "pipe"],
             cwd: projectRoot,
             env: {
                 ...process.env,
                 DATABASE_TYPE: "falkordb-remote",
-                FALKORDB_HOST: process.env.FALKORDB_HOST ?? "falkordb.orb.local",
-                FALKORDB_PORT: process.env.FALKORDB_PORT ?? "6379",
+                FALKORDB_HOST: host,
                 FALKORDB_GRAPH_NAME: process.env.FALKORDB_GRAPH_NAME ?? basename(projectRoot),
             },
         }).trim();
@@ -38,10 +74,16 @@ export function indexProject(projectRoot) {
     if (!cgc) {
         return { success: false, output: "CGC not installed — run: pipx install codegraphcontext" };
     }
+    const host = getFalkorHost();
+    if (!checkFalkorConnection(host)) {
+        return {
+            success: false,
+            output: `FalkorDB not reachable at ${host}:6379. Is the container running? Try: docker start falkordb`,
+        };
+    }
     const graphName = process.env.FALKORDB_GRAPH_NAME ?? basename(projectRoot);
+    const hasIgnore = existsSync(join(projectRoot, ".cgcignore"));
     try {
-        // Check if .cgcignore exists
-        const hasIgnore = existsSync(join(projectRoot, ".cgcignore"));
         const output = execSync(`${cgc} index ${projectRoot}`, {
             encoding: "utf-8",
             timeout: 120000,
@@ -49,8 +91,7 @@ export function indexProject(projectRoot) {
             env: {
                 ...process.env,
                 DATABASE_TYPE: "falkordb-remote",
-                FALKORDB_HOST: process.env.FALKORDB_HOST ?? "falkordb.orb.local",
-                FALKORDB_PORT: process.env.FALKORDB_PORT ?? "6379",
+                FALKORDB_HOST: host,
                 FALKORDB_GRAPH_NAME: graphName,
             },
         }).trim();
@@ -268,4 +309,141 @@ export function registerGraphTools(server, projectRoot) {
             content: [{ type: "text", text: output }],
         };
     });
+    server.registerTool("graph_ensure", {
+        description: "Validate and fix the entire code graph stack: FalkorDB container, CGC connection, repo indexing. Call this during catchup or when graph tools fail. Attempts auto-repair for common issues.",
+    }, async () => {
+        const steps = [];
+        // 1. Check CGC installed
+        const cgc = cgcPath();
+        if (!cgc) {
+            steps.push({
+                step: "cgc-installed",
+                status: "error",
+                detail: "CGC not installed — run: pipx install codegraphcontext",
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ steps }, null, 2) }],
+                isError: true,
+            };
+        }
+        steps.push({ step: "cgc-installed", status: "ok", detail: cgc });
+        // 2. Check FalkorDB container exists and is running
+        try {
+            const status = execSync("docker ps --filter name=falkordb --format '{{.Status}}'", {
+                encoding: "utf-8",
+                timeout: 5000,
+                stdio: ["ignore", "pipe", "pipe"],
+            }).trim();
+            if (status) {
+                steps.push({ step: "falkordb-container", status: "ok", detail: status });
+            }
+            else {
+                // Container exists but not running — try to start
+                try {
+                    execSync("docker start falkordb", {
+                        timeout: 10000,
+                        stdio: ["ignore", "pipe", "pipe"],
+                    });
+                    steps.push({
+                        step: "falkordb-container",
+                        status: "fixed",
+                        detail: "Started existing container",
+                    });
+                }
+                catch {
+                    // Container doesn't exist — create it
+                    try {
+                        execSync("docker run -d --name falkordb --restart unless-stopped -v falkordb-global:/var/lib/falkordb/data falkordb/falkordb:latest", { timeout: 30000, stdio: ["ignore", "pipe", "pipe"] });
+                        steps.push({
+                            step: "falkordb-container",
+                            status: "fixed",
+                            detail: "Created new container",
+                        });
+                    }
+                    catch (e) {
+                        const err = e;
+                        steps.push({
+                            step: "falkordb-container",
+                            status: "error",
+                            detail: err.message ?? "Failed to create container",
+                        });
+                    }
+                }
+            }
+        }
+        catch {
+            steps.push({
+                step: "falkordb-container",
+                status: "error",
+                detail: "Docker not available — is OrbStack running?",
+            });
+        }
+        // 3. Check connectivity
+        const host = getFalkorHost();
+        if (checkFalkorConnection(host)) {
+            steps.push({
+                step: "falkordb-connection",
+                status: "ok",
+                detail: `Connected to ${host}:6379`,
+            });
+        }
+        else {
+            // Wait a moment if we just started the container
+            const justStarted = steps.some((s) => s.step === "falkordb-container" && s.status === "fixed");
+            if (justStarted) {
+                await new Promise((r) => setTimeout(r, 3000));
+                if (checkFalkorConnection(host)) {
+                    steps.push({
+                        step: "falkordb-connection",
+                        status: "ok",
+                        detail: `Connected to ${host}:6379 (after wait)`,
+                    });
+                }
+                else {
+                    steps.push({
+                        step: "falkordb-connection",
+                        status: "error",
+                        detail: `Cannot connect to ${host}:6379`,
+                    });
+                }
+            }
+            else {
+                steps.push({
+                    step: "falkordb-connection",
+                    status: "error",
+                    detail: `Cannot connect to ${host}:6379`,
+                });
+            }
+        }
+        // 4. Check if repo is indexed
+        if (steps.every((s) => s.status !== "error")) {
+            const listOutput = runCgc("list", projectRoot, { skipConnectionCheck: true });
+            if (listOutput.includes(projectRoot) || listOutput.includes(basename(projectRoot))) {
+                steps.push({ step: "repo-indexed", status: "ok", detail: "Repository is indexed" });
+            }
+            else {
+                steps.push({
+                    step: "repo-indexed",
+                    status: "error",
+                    detail: "Repository not indexed — call index_project to index",
+                });
+            }
+        }
+        const hasErrors = steps.some((s) => s.status === "error");
+        const hasFixed = steps.some((s) => s.status === "fixed");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        healthy: !hasErrors,
+                        autoRepaired: hasFixed,
+                        host,
+                        steps,
+                    }, null, 2),
+                },
+            ],
+            isError: hasErrors,
+        };
+    });
 }

package/extensions/falkordb/manifest.json

@@ -6,6 +6,10 @@
 			{
 				"name": "falkordb-container",
 				"command": "docker ps --filter name=falkordb --format '{{.Status}}'"
+			},
+			{
+				"name": "falkordb-connection",
+				"command": "node -e \"const s=require('net').connect(6379,process.env.FALKORDB_HOST||'falkordb.orb.local');s.setTimeout(3000);s.on('connect',()=>{console.log('connected');s.end();process.exit(0)});s.on('error',e=>{console.error(e.message);process.exit(1)});s.on('timeout',()=>{console.error('timeout');process.exit(1)})\""
 			}
 		],
 		"env_vars": {

package/hooks/check-gates.js

@@ -216,11 +216,25 @@ for (const item of newlyChecked) {
 	for (const phase of oldPhases) {
 		if (phase.number >= item.phase) break;
 
-		const isOverridden = (text) =>
-			gatePolicy !== "strict" &&
-			(text.includes("(none needed)") ||
+		const isOverridden = (text) => {
+			if (gatePolicy === "strict") return false;
+
+			const hasBareOptOut =
+				text.includes("(none needed)") ||
 				text.includes("(not applicable)") ||
-				text.includes("skip-reason:"));
+				text.includes("skip-reason:");
+
+			if (gatePolicy === "auto") return hasBareOptOut;
+
+			// ask mode: requires conversation proof
+			// Format: (none needed — asked: "{question}" — user: "{answer}")
+			const hasConversationProof =
+				/\(none needed\s*—\s*asked:\s*"[^"]+"\s*—\s*user:\s*"[^"]+"\)/.test(text) ||
+				/\(not applicable\s*—\s*asked:\s*"[^"]+"\s*—\s*user:\s*"[^"]+"\)/.test(text) ||
+				/skip-reason:.*—\s*asked:\s*"[^"]+"\s*—\s*user:\s*"[^"]+"/.test(text);
+
+			return hasConversationProof;
+		};
 
 		const uncheckedGates = phase.items.filter(
 			(i) => !i.checked && !isOverridden(i.text) && requiredGates.includes(i.gate),
@@ -231,7 +245,9 @@ for (const item of newlyChecked) {
 			const skipHint =
 				gatePolicy === "strict"
 					? "Gate policy is 'strict' — no overrides allowed.\n"
-					: "To skip a gate item, ask the user first, then mark with (none needed) or skip-reason: {why}\n";
+					: gatePolicy === "ask"
+						? 'Gate policy is \'ask\' — to skip, you must ask the user and include proof.\nFormat: (none needed — asked: "your question" — user: "their answer")\n'
+						: "To skip a gate item, mark with (none needed) or skip-reason: {why}\n";
 			process.stderr.write(
 				`Phase ${item.phase} blocked (policy: ${gatePolicy}): complete Phase ${phase.number} gates first:\n${missing}\n${skipHint}`,
 			);

package/hooks/validate-impl-structure.js

@@ -194,7 +194,9 @@ for (const phase of phases) {
 	}
 
 	// In strict mode, opt-outs are not allowed — sections must have real items
-	if (gatePolicy === "strict") {
+	// In ask mode, opt-outs are not allowed at write time — every gate must have a real item
+	// Opt-outs only happen during /work (execution time), not during /plan (write time)
+	if (gatePolicy === "strict" || gatePolicy === "ask") {
 		const optOuts = [];
 		if (requirements.verification && phase.hasVerification && phase.verificationIsOptOut)
 			optOuts.push("Verification");
@@ -202,8 +204,12 @@ for (const phase of phases) {
 		if (requirements.document && phase.hasDocument && phase.documentIsOptOut)
 			optOuts.push("Document");
 		if (optOuts.length > 0) {
+			const modeHint =
+				gatePolicy === "strict"
+					? "strict mode — no opt-outs allowed"
+					: "ask mode — every gate must have a real item when the impl is written. Opt-outs happen during /work after asking the user";
 			errors.push(
-				`Phase ${phase.number} (${phase.name}): ${optOuts.join(", ")} cannot use opt-outs in strict mode — add real items`,
+				`Phase ${phase.number} (${phase.name}): ${optOuts.join(", ")} cannot use opt-outs at write time (${modeHint})`,
 			);
 		}
 	}
@@ -217,7 +223,9 @@ if (errors.length > 0) {
 	const skipHint =
 		gatePolicy === "strict"
 			? "Gate policy is 'strict' — all sections must have real items, no overrides.\n"
-			: "If a section isn't needed, add it with (none needed) or skip-reason: {why}\nExample: #### Phase 1 Document\\n(none needed)\n";
+			: gatePolicy === "ask"
+				? "Gate policy is 'ask' — every gate must have a real item when writing the impl. Opt-outs happen during /work after asking the user.\n"
+				: "If a section isn't needed, add it with (none needed) or skip-reason: {why}\nExample: #### Phase 1 Document\\n(none needed)\n";
 	process.stderr.write(
 		`Impl structure incomplete (workflow: ${workflow}, policy: ${gatePolicy}):\n${msg}\n\nThis workflow requires: ${reqNames.join(", ")} sections per phase.\n${skipHint}To change requirements, add 'workflow: bugfix' to the impl frontmatter.\n`,
 	);

package/package.json

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

package/skills/catchup.md

@@ -64,7 +64,7 @@ Understand what each skill does and when to use it. You should be able to answer
 **After reviewing, edit the handoff to check off:** `- [x] skills` and `- [x] extensions`
 
 ### 7. Check Code Graph
-Call `graph_stats` to understand the codebase size and structure. This gives you a sense of what's indexed and queryable. If it fails, call `graph_doctor` to diagnose. If FalkorDB is down or the repo isn't indexed, flag it.
+Call `graph_ensure` to validate the entire code graph stack: FalkorDB container, CGC connection, repo indexing. This tool auto-repairs common issues (starts stopped containers, detects the right host). If it reports errors it couldn't fix, tell the user what's wrong and how to fix it. If the repo isn't indexed, call `index_project`.
 
 **After checking, edit the handoff to check off:** `- [x] graph`
 

package/skills/plan.md

@@ -78,7 +78,11 @@ Workflow templates are in `templates/workflows/` in the package. They describe w
 
 6. **If ADR is accepted** (or brief is accepted for bugfix/refactor), write the impl. Break into phased checklists with concrete tasks. For refactor workflows, include a `## Boundary Map` section. For multi-phase impls of any type, consider adding a boundary map.
 
-   **Gate policy applies when writing impls.** Set `gate_policy` in the impl frontmatter (`strict`, `ask`, or `auto`). See the work skill "Gate Override Policy" for what each mode means. The `validate-impl-structure` hook enforces this at write time.
+   **Gate policy applies when writing impls.** Set `gate_policy` in the impl frontmatter (`strict`, `ask`, or `auto`). The `validate-impl-structure` hook enforces this at write time:
+   - **`strict` / `ask`**: Every gate section (Verification, Context, Document) must have a real item — `(none needed)` and `skip-reason:` are blocked at write time. Opt-outs only happen during `/work` execution.
+   - **`auto`**: Gate sections can be pre-filled with `(none needed)` or `skip-reason:` at write time.
+
+   Default is `ask`. See the work skill "Gate Override Policy" for full details on what each mode enforces at execution time.
 
 7. **If impl is completed** (all items checked off by `/work`), invoke the retrospective skill (`/retrospective {plan-name}`). This handles the structured audit (docs, tests, quality, context), knowledge handoff to the docs site, and archival. Do not write a freeform retrospective — use the skill. (Bugfix and refactor workflows may skip retrospective for small changes — user's call.)
 
@@ -193,6 +197,22 @@ because **{rationale}**.
 ### Risks
 - {Risk and mitigation}
 
+## Documentation Plan
+{Decide upfront what documentation this feature produces. This shapes the Document gates in the impl.}
+
+### Pages
+- {New page or existing page to update — e.g., "New: reference/tools/settlement-api.md", "Update: guide/getting-started.md"}
+
+### Diagrams
+- {What diagrams are needed — e.g., "Architecture diagram showing settlement flow", "Sequence diagram for agent registration"}
+- {Where they go — e.g., "Mermaid in reference/tools/settlement-api.md", "Standalone in guide/architecture.md"}
+
+### Changelog
+- {What changelog entry — e.g., "Added settlement API with EIP-712 receipts"}
+
+### ADR in Docs
+- {Should this ADR be published to the docs site? If yes, which section — e.g., "decisions/settlement-architecture.md"}
+
 ## References
 - {Links to research, brief, related plans, external resources}
 ```

package/skills/toolbelt.md

@@ -10,7 +10,7 @@ You have MCP tools from two servers: **indusk** (dev system) and **codegraphcont
 /work → executes impl checklist, phase by phase
          each phase has four gates:
            implement → verify → context → document → next phase
-         hooks enforce gates — can't skip
+         hooks enforce gates — can't skip (see Gate Policy below)
                 ↓
 /retrospective → audit, quality ratchet, knowledge handoff, archive
 ```
@@ -52,6 +52,18 @@ While executing impl items:
 - After completing context items, call `get_context` to verify CLAUDE.md was updated correctly.
 - After completing document items, call `list_docs` to verify the doc page exists.
 
+## Gate Policy
+
+Gates prevent skipping important work. Three enforcement levels, set via `gate_policy` in impl frontmatter or `.claude/settings.json`:
+
+| Mode | Writing the impl (`/plan`) | Executing the impl (`/work`) |
+|------|---------------------------|------------------------------|
+| **`strict`** | Every gate must have a real item. No `(none needed)`. | Every item must be completed. No skipping. |
+| **`ask`** (default) | Every gate must have a real item. No `(none needed)`. | Skip only with conversation proof: `(none needed — asked: "..." — user: "...")` |
+| **`auto`** | `(none needed)` / `skip-reason:` allowed at write time. | Skip without asking using `(none needed)` or `skip-reason:`. |
+
+Hooks enforce both stages. See the work skill "Gate Override Policy" for full details.
+
 ## Advancing Phases
 
 When you think a phase is complete:

package/skills/work.md

@@ -69,9 +69,9 @@ Three modes, configured via `gate_policy` in the impl frontmatter or `.claude/se
 
 | Mode | Behavior |
 |------|----------|
-| **`strict`** | No overrides. Every gate item must be completed. `(none needed)` and `skip-reason:` are not accepted. Use for critical work where nothing should be skipped. |
-| **`ask`** (default) | Agent must ask the user before skipping any gate item. The agent explains why it wants to skip and waits for approval. Only after the user says yes can it mark with `skip-reason:`. |
-| **`auto`** | Agent can skip with `skip-reason:` without asking. Use when running autonomously or when you trust the agent's judgment. |
+| **`strict`** | No overrides at any stage. Every gate must have a real item when the impl is written (`/plan`), and every item must be completed during `/work`. No `(none needed)`, no `skip-reason:`, no conversation proof. |
+| **`ask`** (default) | Every gate must have a real item when the impl is written. During `/work`, the agent must ask the user before skipping, and include proof of the conversation in the skip format. Hooks enforce both stages. |
+| **`auto`** | Gates can be pre-filled with `(none needed)` or `skip-reason:` at write time. During `/work`, the agent can skip without asking. Use when running autonomously. |
 
 ### How to set the mode
 
@@ -100,14 +100,30 @@ Priority: per-invocation > per-plan > per-project > default (`ask`).
 
 When the agent encounters a gate item it thinks should be skipped:
 
-> "Phase 2 has a Document gate: 'Write reference page for the new API.' I don't think this phase needs a new docs page because we only changed internal implementation — the public API didn't change. Can I mark this as `skip-reason: internal change, no public API change`?"
+> "Phase 2 has a Document gate: 'Write reference page for the new API.' I don't think this phase needs a new docs page because we only changed internal implementation — the public API didn't change. Can I skip the document gate?"
 
 The user can say:
-- **"yes"** — agent marks it with skip-reason and continues
+- **"yes, skip it"** — agent marks it with conversation proof and continues
 - **"no, do it"** — agent completes the gate item
-- **"no, but mark it (none needed)"** — if the gate truly doesn't apply
 
-**The agent must NEVER skip a gate without asking in `ask` mode.** This is the core enforcement. The hooks block unauthorized skips, and the skill enforces the conversation.
+### Conversation proof format (enforced by hooks)
+
+In `ask` mode, skipped gates MUST include proof that the conversation happened:
+
+```markdown
+#### Phase 2 Document
+- [x] (none needed — asked: "Phase 2 is internal refactoring with no public API changes. Can I skip the document gate?" — user: "yes, skip it")
+```
+
+The hook validates that both `asked:` and `user:` are present with non-empty quoted content. Bare `(none needed)` or `skip-reason:` without conversation proof will be **blocked by the hook**.
+
+| Mode | At write time (`/plan`) | At execution time (`/work`) |
+|------|------------------------|---------------------------|
+| `strict` | No opt-outs — real items required | No skipping — everything completed |
+| `ask` | No opt-outs — real items required | Skip only with conversation proof |
+| `auto` | `(none needed)` / `skip-reason:` allowed | Skip without asking |
+
+**The agent must NEVER skip a gate without asking in `ask` mode.** This is enforced by hooks at both stages — not just instructional.
 
 11. **Verification items.** The Verification section requires proof, not assumption. See the verify skill for full guidance.
    - Run checks in order: type check → lint → affected tests → build. Skip checks that don't apply (see verify skill's skip logic table).