@infinitedusky/indusk-mcp 1.8.0 → 1.9.0

package/dist/bin/cli.js

@@ -14,11 +14,13 @@ program
     .command("init")
     .description("Initialize a project with InDusk dev system")
     .option("-f, --force", "Overwrite existing files (except CLAUDE.md and planning/)")
+    .option("--local", "Local mode — no committed file changes")
     .option("--no-index", "Skip code graph indexing")
     .action(async (opts) => {
     const { init } = await import("./commands/init.js");
     await init(process.cwd(), {
         force: opts.force ?? false,
+        local: opts.local ?? false,
         noIndex: opts.index === false,
     });
 });
@@ -129,6 +131,22 @@ infra
     const { infraStatus } = await import("./commands/infra.js");
     await infraStatus();
 });
+program
+    .command("pr-clean")
+    .description("Strip InDusk settings overlay before a PR")
+    .action(async () => {
+    const { stripOverlay } = await import("../lib/settings-overlay.js");
+    stripOverlay(process.cwd());
+    console.info("Stripped InDusk overlay from .claude/settings.json");
+});
+program
+    .command("pr-restore")
+    .description("Re-apply InDusk settings overlay after a PR")
+    .action(async () => {
+    const { applyOverlay } = await import("../lib/settings-overlay.js");
+    applyOverlay(process.cwd());
+    console.info("Re-applied InDusk overlay to .claude/settings.json");
+});
 program
     .command("serve")
     .description("Start the MCP server (used by Claude Code via .mcp.json)")

package/dist/bin/commands/check-gates.js

@@ -1,5 +1,6 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { getPlanningDir } from "../../lib/config.js";
 import { getAllPhaseCompletions, parseImpl } from "../../lib/impl-parser.js";
 export async function checkGates(projectRoot, options = {}) {
     let implPath;
@@ -7,10 +8,10 @@ export async function checkGates(projectRoot, options = {}) {
         implPath = options.file;
     }
     else {
-        // Find active impl (in-progress status) in planning/
-        const planningDir = join(projectRoot, "planning");
+        // Find active impl (in-progress status)
+        const planningDir = getPlanningDir(projectRoot);
         if (!existsSync(planningDir)) {
-            console.error("No planning/ directory found");
+            console.error("No planning directory found");
             process.exitCode = 1;
             return;
         }
@@ -29,7 +30,7 @@ export async function checkGates(projectRoot, options = {}) {
             }
         }
         if (!found) {
-            console.error("No in-progress impl found in planning/");
+            console.error("No in-progress impl found");
             process.exitCode = 1;
             return;
         }

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

@@ -1,5 +1,6 @@
 export interface InitOptions {
     force?: boolean;
+    local?: boolean;
     noIndex?: boolean;
 }
 export declare function init(projectRoot: string, options?: InitOptions): Promise<void>;

package/dist/bin/commands/init.js

@@ -56,10 +56,82 @@ function createCgcIgnore(projectRoot) {
     ].join("\n"));
     console.info("  create: .cgcignore");
 }
+function detectTooling(projectRoot) {
+    const detected = {};
+    // Detect linter
+    if (existsSync(join(projectRoot, "biome.json")) || existsSync(join(projectRoot, "biome.jsonc"))) {
+        detected.linter = "biome";
+    }
+    else if (existsSync(join(projectRoot, ".eslintrc.js")) ||
+        existsSync(join(projectRoot, ".eslintrc.json")) ||
+        existsSync(join(projectRoot, ".eslintrc.cjs")) ||
+        existsSync(join(projectRoot, "eslint.config.js")) ||
+        existsSync(join(projectRoot, "eslint.config.mjs")) ||
+        existsSync(join(projectRoot, "eslint.config.ts"))) {
+        detected.linter = "eslint";
+    }
+    // Detect test runner
+    if (existsSync(join(projectRoot, "vitest.config.ts")) ||
+        existsSync(join(projectRoot, "vitest.config.js"))) {
+        detected.testRunner = "vitest";
+    }
+    else if (existsSync(join(projectRoot, "jest.config.js")) ||
+        existsSync(join(projectRoot, "jest.config.ts"))) {
+        detected.testRunner = "jest";
+    }
+    // Detect OTel
+    if (existsSync(join(projectRoot, "instrumentation.ts")) ||
+        existsSync(join(projectRoot, "src/instrumentation.ts")) ||
+        existsSync(join(projectRoot, "instrumentation.py"))) {
+        detected.otel = true;
+    }
+    // Detect TypeScript
+    if (existsSync(join(projectRoot, "tsconfig.json"))) {
+        detected.typeCheck = true;
+    }
+    return detected;
+}
+function writeGitInfoExclude(projectRoot) {
+    const excludePath = join(projectRoot, ".git/info/exclude");
+    const marker = "# InDusk local mode";
+    // Ensure .git/info/ exists
+    mkdirSync(join(projectRoot, ".git/info"), { recursive: true });
+    let content = "";
+    if (existsSync(excludePath)) {
+        content = readFileSync(excludePath, "utf-8");
+        if (content.includes(marker))
+            return; // Already configured
+    }
+    const entries = [
+        "",
+        marker,
+        ".indusk/",
+        ".claude/skills/",
+        ".claude/hooks/",
+        ".claude/lessons/",
+        ".claude/settings.json",
+        ".claude/handoff.md",
+        ".cgcignore",
+        ".mcp.json",
+        "",
+    ].join("\n");
+    writeFileSync(excludePath, content.trimEnd() + entries);
+    console.info("  updated: .git/info/exclude (InDusk local mode entries)");
+}
 export async function init(projectRoot, options = {}) {
-    const { force = false, noIndex = false } = options;
+    const { force = false, local = false, noIndex = false } = options;
     const projectName = basename(projectRoot);
-    console.info(`Initializing InDusk dev system...${force ? " (--force)" : ""}\n`);
+    const modeLabel = local ? " (--local)" : "";
+    console.info(`Initializing InDusk dev system...${force ? " (--force)" : ""}${modeLabel}\n`);
+    // Detect existing tooling
+    const detected = detectTooling(projectRoot);
+    if (local) {
+        console.info("[Detection]");
+        console.info(`  linter: ${detected.linter ?? "none"}`);
+        console.info(`  test runner: ${detected.testRunner ?? "none"}`);
+        console.info(`  otel: ${detected.otel ? "yes" : "no"}`);
+        console.info(`  typescript: ${detected.typeCheck ? "yes" : "no"}`);
+    }
     // 1. Copy skills
     console.info("[Skills]");
     const skillsSource = join(packageRoot, "skills");
@@ -95,25 +167,31 @@ export async function init(projectRoot, options = {}) {
         }
     }
     // 3. Create CLAUDE.md (never overwrite — write CLAUDE-NEW.md if exists)
-    console.info("\n[Project files]");
-    const claudeMdPath = join(projectRoot, "CLAUDE.md");
-    if (existsSync(claudeMdPath)) {
-        const newPath = join(projectRoot, "CLAUDE-NEW.md");
-        cpSync(join(packageRoot, "templates/CLAUDE.md"), newPath);
-        console.info("  create: CLAUDE-NEW.md (merge manually with existing CLAUDE.md)");
-    }
-    else {
-        cpSync(join(packageRoot, "templates/CLAUDE.md"), claudeMdPath);
-        console.info("  create: CLAUDE.md");
+    if (!local) {
+        console.info("\n[Project files]");
+        const claudeMdPath = join(projectRoot, "CLAUDE.md");
+        if (existsSync(claudeMdPath)) {
+            const newPath = join(projectRoot, "CLAUDE-NEW.md");
+            cpSync(join(packageRoot, "templates/CLAUDE.md"), newPath);
+            console.info("  create: CLAUDE-NEW.md (merge manually with existing CLAUDE.md)");
+        }
+        else {
+            cpSync(join(packageRoot, "templates/CLAUDE.md"), claudeMdPath);
+            console.info("  create: CLAUDE.md");
+        }
     }
     // 3. Create planning directory
-    const planningDir = join(projectRoot, "planning");
+    const planningDir = join(projectRoot, ".indusk/planning");
+    const legacyPlanningDir = join(projectRoot, "planning");
     if (existsSync(planningDir)) {
-        console.info("  skip: planning/ (already exists)");
+        console.info("  skip: .indusk/planning/ (already exists)");
+    }
+    else if (existsSync(legacyPlanningDir)) {
+        console.info("  migrate: planning/ → .indusk/planning/ (move manually or run: mv planning .indusk/planning)");
     }
     else {
         mkdirSync(planningDir, { recursive: true });
-        console.info("  create: planning/");
+        console.info("  create: .indusk/planning/");
     }
     // 4. Set up MCP servers via claude mcp add
     console.info("\n[MCP config]");
@@ -255,29 +333,95 @@ export async function init(projectRoot, options = {}) {
         console.info("  create: .indusk/extensions/graphiti/ (manifest + skill)");
     }
     // 5. Generate .vscode/settings.json
-    console.info("\n[Editor]");
-    const vscodePath = join(projectRoot, ".vscode/settings.json");
-    if (existsSync(vscodePath) && !force) {
-        console.info("  skip: .vscode/settings.json (already exists)");
-    }
-    else {
-        mkdirSync(join(projectRoot, ".vscode"), { recursive: true });
-        cpSync(join(packageRoot, "templates/vscode-settings.json"), vscodePath);
-        console.info(`  ${existsSync(vscodePath) ? "overwrite" : "create"}: .vscode/settings.json`);
+    if (!local) {
+        console.info("\n[Editor]");
+        const vscodePath = join(projectRoot, ".vscode/settings.json");
+        if (existsSync(vscodePath) && !force) {
+            console.info("  skip: .vscode/settings.json (already exists)");
+        }
+        else {
+            mkdirSync(join(projectRoot, ".vscode"), { recursive: true });
+            cpSync(join(packageRoot, "templates/vscode-settings.json"), vscodePath);
+            console.info(`  ${existsSync(vscodePath) ? "overwrite" : "create"}: .vscode/settings.json`);
+        }
     }
-    // 6. Create base biome.json
-    const biomePath = join(projectRoot, "biome.json");
-    if (existsSync(biomePath) && !force) {
-        console.info("  skip: biome.json (already exists)");
+    // 6. Create biome.json (root in full mode, .indusk/ in local mode)
+    if (!local) {
+        const biomePath = join(projectRoot, "biome.json");
+        if (existsSync(biomePath) && !force) {
+            console.info("  skip: biome.json (already exists)");
+        }
+        else {
+            cpSync(join(packageRoot, "templates/biome.template.json"), biomePath);
+            console.info(`  ${existsSync(biomePath) ? "overwrite" : "create"}: biome.json`);
+        }
     }
     else {
-        cpSync(join(packageRoot, "templates/biome.template.json"), biomePath);
-        console.info(`  ${existsSync(biomePath) ? "overwrite" : "create"}: biome.json`);
+        console.info("\n[Local Quality Tools]");
+        // Biome in .indusk/
+        const localBiomePath = join(projectRoot, ".indusk/biome.json");
+        if (existsSync(localBiomePath) && !force) {
+            console.info("  skip: .indusk/biome.json (already exists)");
+        }
+        else {
+            cpSync(join(packageRoot, "templates/biome.template.json"), localBiomePath);
+            console.info("  create: .indusk/biome.json");
+        }
+        // Test runner config in .indusk/
+        if (detected.testRunner === "jest") {
+            const jestConfig = join(projectRoot, ".indusk/jest.config.js");
+            if (!existsSync(jestConfig) || force) {
+                writeFileSync(jestConfig, [
+                    "/** @type {import('jest').Config} */",
+                    "module.exports = {",
+                    "  roots: ['<rootDir>/../', '<rootDir>/tests/'],",
+                    "  testMatch: ['<rootDir>/tests/**/*.test.{js,ts}'],",
+                    "};",
+                    "",
+                ].join("\n"));
+                console.info("  create: .indusk/jest.config.js (extends team roots)");
+            }
+        }
+        else {
+            // Default to vitest
+            const vitestConfig = join(projectRoot, ".indusk/vitest.config.ts");
+            if (!existsSync(vitestConfig) || force) {
+                writeFileSync(vitestConfig, [
+                    'import { defineConfig } from "vitest/config";',
+                    "",
+                    "export default defineConfig({",
+                    "  test: {",
+                    '    include: [".indusk/tests/**/*.test.{ts,js}"],',
+                    "    passWithNoTests: true,",
+                    "  },",
+                    "});",
+                    "",
+                ].join("\n"));
+                console.info("  create: .indusk/vitest.config.ts");
+            }
+        }
+        // Tests directory
+        const testsDir = join(projectRoot, ".indusk/tests");
+        if (!existsSync(testsDir)) {
+            mkdirSync(testsDir, { recursive: true });
+            writeFileSync(join(testsDir, ".gitkeep"), "");
+            console.info("  create: .indusk/tests/");
+        }
+        // Docs directory
+        const docsDir = join(projectRoot, ".indusk/docs");
+        if (!existsSync(docsDir)) {
+            mkdirSync(docsDir, { recursive: true });
+            writeFileSync(join(docsDir, "index.md"), `# ${projectName}\n\nLocal documentation. Portable to VitePress later.\n`);
+            console.info("  create: .indusk/docs/ (with index.md)");
+        }
     }
-    // 7. Scaffold OpenTelemetry instrumentation
-    // Skip if this is the indusk-mcp package itself (has templates/ directory with instrumentation.ts)
+    // 7. Scaffold OpenTelemetry instrumentation (skip in local mode)
     const isInduskMcp = existsSync(join(projectRoot, "templates/instrumentation.ts"));
-    if (isInduskMcp) {
+    if (local) {
+        console.info("\n[OpenTelemetry]");
+        console.info("  skip: local mode (team owns OTel setup)");
+    }
+    else if (isInduskMcp) {
         console.info("\n[OpenTelemetry]");
         console.info("  skip: this is the indusk-mcp package (templates are source, not scaffolded)");
     }
@@ -421,6 +565,7 @@ export async function init(projectRoot, options = {}) {
         }
     }
     // Merge hook config + permissions into .claude/settings.json
+    const { writeOverlay, applyOverlay } = await import("../../lib/settings-overlay.js");
     const claudeSettingsPath = join(projectRoot, ".claude/settings.json");
     const catchupPermissions = [
         "mcp__indusk__list_lessons",
@@ -507,9 +652,25 @@ export async function init(projectRoot, options = {}) {
         writeFileSync(claudeSettingsPath, `${JSON.stringify(settings, null, "\t")}\n`);
         console.info("  create: .claude/settings.json (with hook config + catchup permissions)");
     }
-    // 8. Create .cgcignore (always overwrite — package-owned)
+    // In local mode, save overlay so we can strip our additions before PRs
+    if (local) {
+        const overlayData = {
+            permissions: { allow: catchupPermissions },
+            hooks: hookConfig,
+        };
+        writeOverlay(projectRoot, overlayData);
+        applyOverlay(projectRoot);
+        console.info("  saved: .indusk/settings-overlay.json");
+    }
+    // 8. Create .cgcignore and manage git excludes
     createCgcIgnore(projectRoot);
-    ensureGitignoreMcpJson(projectRoot);
+    if (local) {
+        console.info("\n[Git Excludes]");
+        writeGitInfoExclude(projectRoot);
+    }
+    else {
+        ensureGitignoreMcpJson(projectRoot);
+    }
     // 9. Run on_init hooks from enabled extensions
     console.info("\n[Extension Hooks]");
     const { getEnabledExtensions } = await import("../../lib/extension-loader.js");
@@ -568,6 +729,30 @@ export async function init(projectRoot, options = {}) {
     console.info("\n[Extensions]");
     const { autoEnableExtensions } = await import("./extensions.js");
     await autoEnableExtensions(projectRoot);
+    // 12. Write .indusk/config.json
+    const { writeConfig } = await import("../../lib/config.js");
+    const linterTool = local ? "biome" : (detected.linter ?? "biome");
+    const linterConfig = local ? ".indusk/biome.json" : "biome.json";
+    const testTool = detected.testRunner ?? "vitest";
+    const testConfig = local
+        ? `.indusk/${testTool === "jest" ? "jest.config.js" : "vitest.config.ts"}`
+        : `${testTool}.config.${testTool === "jest" ? "js" : "ts"}`;
+    const config = {
+        mode: local ? "local" : "full",
+        verify: {
+            linter: { tool: linterTool, config: linterConfig },
+            testRunner: { tool: testTool, config: testConfig },
+            ...(detected.typeCheck ? { typeCheck: "tsc" } : {}),
+        },
+        detected: {
+            ...(detected.linter ? { linter: detected.linter } : {}),
+            ...(detected.testRunner ? { testRunner: detected.testRunner } : {}),
+            ...(detected.otel ? { otel: true } : {}),
+        },
+    };
+    writeConfig(projectRoot, config);
+    console.info(`\n[Config]`);
+    console.info(`  create: .indusk/config.json (mode: ${config.mode})`);
     // Summary
     console.info("\nDone!");
     console.info("\n⚠  Restart Claude Code to load the updated MCP server and skills.");

package/dist/bin/commands/update.js

@@ -1,6 +1,6 @@
-import { createHash } from "node:crypto";
 import { execSync } from "node:child_process";
-import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { globSync } from "glob";
@@ -186,7 +186,12 @@ export async function update(projectRoot) {
     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"];
+        const hookFiles = [
+            "check-gates.js",
+            "gate-reminder.js",
+            "validate-impl-structure.js",
+            "check-catchup.js",
+        ];
         for (const file of hookFiles) {
             const sourceFile = join(hooksSource, file);
             const targetFile = join(hooksTarget, file);
@@ -252,20 +257,21 @@ export async function update(projectRoot) {
                 cpSync(builtinSkill, targetSkill);
                 console.info(`  added: ${name} skill`);
             }
-            // Run on_update hook if present
+            // Run update hooks if present
             const manifest = loadExtension(enabledManifest);
-            if (manifest?.hooks?.on_update) {
-                console.info(`  ${name}: running on_update hook...`);
+            const updateHook = manifest?.hooks?.on_update ?? manifest?.hooks?.on_post_update;
+            if (updateHook) {
+                console.info(`  ${name}: running update hook...`);
                 try {
-                    execSync(manifest.hooks.on_update, {
+                    execSync(updateHook, {
                         cwd: projectRoot,
                         timeout: 30000,
                         stdio: ["ignore", "pipe", "pipe"],
                     });
-                    console.info(`  ${name}: on_update hook completed`);
+                    console.info(`  ${name}: update hook completed`);
                 }
                 catch {
-                    console.info(`  ${name}: on_update hook failed`);
+                    console.info(`  ${name}: update hook failed`);
                 }
             }
             if (manifest?.mcp_server?.setup_instructions) {
@@ -286,6 +292,15 @@ export async function update(projectRoot) {
     catch {
         console.info("  could not check third-party extensions");
     }
+    // 8. Respect local mode: re-apply overlay, refresh excludes
+    const { readConfig } = await import("../../lib/config.js");
+    const config = readConfig(projectRoot);
+    if (config?.mode === "local") {
+        console.info("\n[Local Mode]\n");
+        const { applyOverlay } = await import("../../lib/settings-overlay.js");
+        applyOverlay(projectRoot);
+        console.info("  re-applied settings overlay");
+    }
     console.info("\nDone.");
     if (didUpgrade) {
         console.info("Restart Claude Code to pick up the new MCP server.");

package/dist/lib/config.d.ts

@@ -0,0 +1,21 @@
+export interface VerifyToolConfig {
+    tool: string;
+    config: string;
+}
+export interface InduskConfig {
+    mode: "full" | "local";
+    verify: {
+        linter?: VerifyToolConfig;
+        testRunner?: VerifyToolConfig;
+        typeCheck?: string;
+    };
+    detected: {
+        otel?: boolean;
+        testRunner?: string;
+        linter?: string;
+    };
+}
+export declare function getConfigPath(projectRoot: string): string;
+export declare function readConfig(projectRoot: string): InduskConfig | null;
+export declare function writeConfig(projectRoot: string, config: InduskConfig): void;
+export declare function getPlanningDir(projectRoot: string): string;

package/dist/lib/config.js

@@ -0,0 +1,28 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+const CONFIG_PATH = ".indusk/config.json";
+export function getConfigPath(projectRoot) {
+    return join(projectRoot, CONFIG_PATH);
+}
+export function readConfig(projectRoot) {
+    const configPath = getConfigPath(projectRoot);
+    if (!existsSync(configPath))
+        return null;
+    return JSON.parse(readFileSync(configPath, "utf-8"));
+}
+export function writeConfig(projectRoot, config) {
+    const configPath = getConfigPath(projectRoot);
+    mkdirSync(dirname(configPath), { recursive: true });
+    writeFileSync(configPath, `${JSON.stringify(config, null, "\t")}\n`);
+}
+export function getPlanningDir(projectRoot) {
+    const newPath = join(projectRoot, ".indusk/planning");
+    const legacyPath = join(projectRoot, "planning");
+    // Prefer .indusk/planning, fall back to legacy planning/ for migration
+    if (existsSync(newPath))
+        return newPath;
+    if (existsSync(legacyPath))
+        return legacyPath;
+    // Default to new path (will be created by init)
+    return newPath;
+}

package/dist/lib/plan-parser.js

@@ -1,6 +1,7 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import matter from "gray-matter";
+import { getPlanningDir } from "./config.js";
 const STAGE_ORDER = ["research", "brief", "adr", "impl", "retrospective"];
 function parseFrontmatter(filePath) {
     if (!existsSync(filePath))
@@ -22,7 +23,7 @@ function parseDependsOn(filePath) {
         return [];
     const deps = [];
     for (const line of depsMatch[1].split("\n")) {
-        const match = line.match(/^-\s+`?planning\/([^/`]+)\/?`?/);
+        const match = line.match(/^-\s+`?(?:\.indusk\/)?planning\/([^/`]+)\/?`?/);
         if (match) {
             deps.push(match[1]);
         }
@@ -72,7 +73,7 @@ export function parsePlan(planDir) {
     };
 }
 export function parseAllPlans(projectRoot) {
-    const planningDir = join(projectRoot, "planning");
+    const planningDir = getPlanningDir(projectRoot);
     if (!existsSync(planningDir))
         return [];
     return readdirSync(planningDir, { withFileTypes: true })

package/dist/lib/settings-overlay.d.ts

@@ -0,0 +1,13 @@
+export declare function getOverlayPath(projectRoot: string): string;
+export declare function writeOverlay(projectRoot: string, additions: Record<string, unknown>): void;
+export declare function readOverlay(projectRoot: string): Record<string, unknown> | null;
+/**
+ * Merge overlay additions into .claude/settings.json.
+ * Deep-merges objects, concatenates arrays (deduplicating strings).
+ */
+export declare function applyOverlay(projectRoot: string): void;
+/**
+ * Remove overlay additions from .claude/settings.json.
+ * Strips keys/values that came from the overlay.
+ */
+export declare function stripOverlay(projectRoot: string): void;

package/dist/lib/settings-overlay.js

@@ -0,0 +1,101 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+const OVERLAY_PATH = ".indusk/settings-overlay.json";
+const SETTINGS_PATH = ".claude/settings.json";
+export function getOverlayPath(projectRoot) {
+    return join(projectRoot, OVERLAY_PATH);
+}
+export function writeOverlay(projectRoot, additions) {
+    const overlayPath = getOverlayPath(projectRoot);
+    mkdirSync(dirname(overlayPath), { recursive: true });
+    writeFileSync(overlayPath, `${JSON.stringify(additions, null, "\t")}\n`);
+}
+export function readOverlay(projectRoot) {
+    const overlayPath = getOverlayPath(projectRoot);
+    if (!existsSync(overlayPath))
+        return null;
+    return JSON.parse(readFileSync(overlayPath, "utf-8"));
+}
+/**
+ * Merge overlay additions into .claude/settings.json.
+ * Deep-merges objects, concatenates arrays (deduplicating strings).
+ */
+export function applyOverlay(projectRoot) {
+    const overlay = readOverlay(projectRoot);
+    if (!overlay)
+        return;
+    const settingsPath = join(projectRoot, SETTINGS_PATH);
+    const existing = existsSync(settingsPath) ? JSON.parse(readFileSync(settingsPath, "utf-8")) : {};
+    const merged = deepMerge(existing, overlay);
+    mkdirSync(dirname(settingsPath), { recursive: true });
+    writeFileSync(settingsPath, `${JSON.stringify(merged, null, "\t")}\n`);
+}
+/**
+ * Remove overlay additions from .claude/settings.json.
+ * Strips keys/values that came from the overlay.
+ */
+export function stripOverlay(projectRoot) {
+    const overlay = readOverlay(projectRoot);
+    if (!overlay)
+        return;
+    const settingsPath = join(projectRoot, SETTINGS_PATH);
+    if (!existsSync(settingsPath))
+        return;
+    const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+    const cleaned = deepStrip(settings, overlay);
+    writeFileSync(settingsPath, `${JSON.stringify(cleaned, null, "\t")}\n`);
+}
+function deepMerge(target, source) {
+    const result = { ...target };
+    for (const [key, sourceVal] of Object.entries(source)) {
+        const targetVal = result[key];
+        if (Array.isArray(sourceVal) && Array.isArray(targetVal)) {
+            // Concatenate arrays, dedup strings
+            const combined = [...targetVal];
+            for (const item of sourceVal) {
+                if (typeof item === "string") {
+                    if (!combined.includes(item))
+                        combined.push(item);
+                }
+                else {
+                    combined.push(item);
+                }
+            }
+            result[key] = combined;
+        }
+        else if (isObject(sourceVal) && isObject(targetVal)) {
+            result[key] = deepMerge(targetVal, sourceVal);
+        }
+        else {
+            result[key] = sourceVal;
+        }
+    }
+    return result;
+}
+function deepStrip(target, overlay) {
+    const result = { ...target };
+    for (const [key, overlayVal] of Object.entries(overlay)) {
+        const targetVal = result[key];
+        if (Array.isArray(overlayVal) && Array.isArray(targetVal)) {
+            // Remove overlay items from array
+            result[key] = targetVal.filter((item) => {
+                if (typeof item === "string") {
+                    return !overlayVal.includes(item);
+                }
+                // For objects (hook entries), compare by JSON serialization
+                const itemStr = JSON.stringify(item);
+                return !overlayVal.some((ov) => JSON.stringify(ov) === itemStr);
+            });
+        }
+        else if (isObject(overlayVal) && isObject(targetVal)) {
+            result[key] = deepStrip(targetVal, overlayVal);
+        }
+        else {
+            delete result[key];
+        }
+    }
+    return result;
+}
+function isObject(val) {
+    return typeof val === "object" && val !== null && !Array.isArray(val);
+}

package/dist/tools/plan-tools.js

@@ -1,5 +1,6 @@
 import { join } from "node:path";
 import { z } from "zod";
+import { getPlanningDir } from "../lib/config.js";
 import { getAllPhaseCompletions, parseImpl } from "../lib/impl-parser.js";
 import { parseAllPlans, parsePlan } from "../lib/plan-parser.js";
 export function registerPlanTools(server, projectRoot) {
@@ -15,7 +16,7 @@ export function registerPlanTools(server, projectRoot) {
         description: "Get detailed status of a specific plan including phase progress and blocked items",
         inputSchema: { name: z.string().describe("Plan directory name (e.g. 'mcp-dev-system')") },
     }, async ({ name }) => {
-        const planDir = join(projectRoot, "planning", name);
+        const planDir = join(getPlanningDir(projectRoot), name);
         const plan = parsePlan(planDir);
         const implPath = join(planDir, "impl.md");
         const impl = parseImpl(implPath);
@@ -33,7 +34,7 @@ export function registerPlanTools(server, projectRoot) {
         description: "Validate whether a plan can advance to the next stage. Returns what is missing if blocked.",
         inputSchema: { name: z.string().describe("Plan directory name") },
     }, async ({ name }) => {
-        const planDir = join(projectRoot, "planning", name);
+        const planDir = join(getPlanningDir(projectRoot), name);
         const plan = parsePlan(planDir);
         const implPath = join(planDir, "impl.md");
         const impl = parseImpl(implPath);

package/package.json

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

package/skills/context.md

@@ -30,7 +30,7 @@ CLAUDE.md has exactly six sections. This structure is fixed — never add, remov
 {Patterns to follow, anti-patterns to avoid. Accumulated from corrections, retrospectives, and explicit decisions. Each entry is a concise one-liner.}
 
 ## Key Decisions
-{One-liner per decision with a link to the source document. Format: "- {decision summary} — see planning/{plan}/adr.md"}
+{One-liner per decision with a link to the source document. Format: "- {decision summary} — see .indusk/planning/{plan}/adr.md"}
 
 ## Known Gotchas
 {Things that went wrong before. Mistakes the agent made and was corrected on. Each entry is a concise one-liner explaining what NOT to do and why.}
@@ -87,7 +87,7 @@ Do this immediately after writing the retrospective, before moving on.
 When an ADR's status changes to `accepted`, add a one-liner to **Key Decisions**:
 
 ```markdown
-- {Concise decision summary} — see `planning/{plan-name}/adr.md`
+- {Concise decision summary} — see `.indusk/planning/{plan-name}/adr.md`
 ```
 
 Do not duplicate the ADR's rationale. The link is the documentation.

package/skills/plan.md

@@ -8,7 +8,7 @@ You know how to plan work in this project.
 
 ## How Plans Work Here
 
-Every plan lives in `planning/{kebab-case-name}/` and follows the same document lifecycle:
+Every plan lives in `.indusk/planning/{kebab-case-name}/` and follows the same document lifecycle:
 
 ```
 research.md → brief.md → adr.md → impl.md → retrospective.md
@@ -63,7 +63,7 @@ Workflow templates are in `templates/workflows/` in the package. They describe w
    - **spike**: start with research (and stop there)
 
    **Check for existing research first.** Before writing new research, scan `research/` at the repo root for relevant standalone research docs. If one exists (e.g., `research/auth-options.md`), ask the user: "I found existing research at `research/auth-options.md`. Want to use this as the starting point?" If yes:
-   - Copy it to `planning/{plan-name}/research.md`
+   - Copy it to `.indusk/planning/{plan-name}/research.md`
    - Set the frontmatter status to `complete`
    - Move straight to the brief
 
@@ -74,7 +74,7 @@ Workflow templates are in `templates/workflows/` in the package. They describe w
 
 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. **Consider creating a visual sketch** of the proposed architecture with Excalidraw (if the extension is enabled) — a hand-drawn diagram makes the proposal concrete and easier to discuss. **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`
+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 .indusk/planning/{plan}/adr.md`
 
 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.
 
@@ -91,7 +91,7 @@ Workflow templates are in `templates/workflows/` in the package. They describe w
 ## Cross-Referencing Between Plans
 
 Plans frequently depend on or relate to each other. When work overlaps:
-- Reference related plans by path: "See `planning/security-hardening/` Phase 8"
+- Reference related plans by path: "See `.indusk/planning/security-hardening/` Phase 8"
 - Use the `## Depends On` / `## Blocks` sections in the brief to make ordering explicit
 - If a change in one plan affects another, update both — don't let them drift
 
@@ -154,10 +154,10 @@ status: draft | accepted
 - {How we know this worked}
 
 ## Depends On
-- {Plans that must be completed before this one — e.g., `planning/per-game-escrow/`}
+- {Plans that must be completed before this one — e.g., `.indusk/planning/per-game-escrow/`}
 
 ## Blocks
-- {Plans that are waiting on this one — e.g., `planning/electric-ledger-sync/`}
+- {Plans that are waiting on this one — e.g., `.indusk/planning/electric-ledger-sync/`}
 ```
 
 ### adr.md
@@ -323,7 +323,7 @@ date: {YYYY-MM-DD}
 ## Folder Conventions
 
 ```
-planning/
+.indusk/planning/
 ├── {plan-name}/
 │   ├── research.md
 │   ├── brief.md
@@ -337,8 +337,8 @@ research/                    # Standalone insights useful across plans
 ```
 
 - Kebab-case folder names
-- Archive completed/abandoned plans to `planning/archive/`
-- When revising, archive the old version first (`planning/archive/{name}_v1/`)
+- Archive completed/abandoned plans to `.indusk/planning/archive/`
+- When revising, archive the old version first (`.indusk/planning/archive/{name}_v1/`)
 
 ## Important
 

package/skills/retrospective.md

@@ -30,7 +30,7 @@ Work through these steps in order. Each step is blocking — do not skip ahead.
 
 ### Step 1: Write the Retrospective Document
 
-Create `planning/{plan-name}/retrospective.md` using the template from the plan skill. This is the reflective writing — what we set out to do, what actually happened, what we learned.
+Create `.indusk/planning/{plan-name}/retrospective.md` using the template from the plan skill. This is the reflective writing — what we set out to do, what actually happened, what we learned.
 
 Key sections to fill in honestly:
 - **What We Set Out to Do** — recap from the brief
@@ -110,7 +110,7 @@ Distill planning artifacts into the docs site so the knowledge survives archival
 **ADR → Decisions page:**
 Create `apps/indusk-docs/src/decisions/{plan-name}.md` with:
 - A concise summary of what was decided and why
-- Link to the full ADR in the archive: `planning/archive/{plan-name}/adr.md`
+- Link to the full ADR in the archive: `.indusk/planning/archive/{plan-name}/adr.md`
 - Key tradeoffs accepted
 
 **Retrospective insights → Lessons page:**
@@ -127,8 +127,8 @@ Not every plan produces a lessons page — only create one if the insights are g
 Move the planning artifacts to the archive:
 
 ```bash
-mkdir -p planning/archive
-mv planning/{plan-name} planning/archive/{plan-name}
+mkdir -p .indusk/planning/archive
+mv .indusk/planning/{plan-name} .indusk/planning/archive/{plan-name}
 ```
 
 The docs site now holds the published knowledge. The archive holds the process history. Both are preserved, but the docs are the primary reference going forward.

package/skills/work.md

@@ -8,11 +8,11 @@ You know how to execute plans in this project.
 
 ## How Work Works Here
 
-Implementation plans live in `planning/{plan-name}/impl.md` as checklists. Your job is to work through them methodically — one item at a time, in order, checking each off immediately after completing it.
+Implementation plans live in `.indusk/planning/{plan-name}/impl.md` as checklists. Your job is to work through them methodically — one item at a time, in order, checking each off immediately after completing it.
 
 ## What to Do When Asked to Work
 
-1. **Find the right plan.** Look in `planning/` for the plan matching what the user asked for. If they didn't specify, list all plans that have an impl with status `approved` or `in-progress` and ask which one.
+1. **Find the right plan.** Look in `.indusk/planning/` for the plan matching what the user asked for. If they didn't specify, list all plans that have an impl with status `approved` or `in-progress` and ask which one.
 
 2. **Check prerequisites.** Before starting work:
    - If the plan has an ADR, verify its status is `accepted`. If it's still `proposed`, warn the user: "The ADR hasn't been accepted yet — want to review it first, or proceed anyway?"