@infinitedusky/indusk-mcp 1.36.2 → 1.37.0

package/dist/bin/commands/worktree.js

@@ -1,7 +1,9 @@
 import { spawnSync } from "node:child_process";
-import { existsSync, lstatSync, readdirSync, readFileSync, readlinkSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync, readlinkSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { listWorkbenchSubdirs, worktreeOwner } from "../../lib/worktree/layout.js";
+import { isWorkbench, NOT_A_WORKBENCH, readWorkbenchRepos, repoDir, } from "../../lib/worktree/repos.js";
 import { validateWorktreeConfig } from "../../lib/worktree/validate-config.js";
 import { provisionWorktreeEnv } from "./doppler.js";
 /**
@@ -88,14 +90,46 @@ function runWorktreeScript(scriptName, args) {
     });
     process.exit(r.status ?? 1);
 }
-export function worktreeCreate(slug, baseBranch) {
+/**
+ * `indusk worktree create [repo] <slug> [base-branch]`.
+ *
+ * The repo argument returns from the pre-v1 multi-repo design. Disambiguated
+ * against the DECLARED SET rather than by arity: a leading token is a repo
+ * only if the workbench actually declares it, so `create my-feature` in a
+ * one-repo workbench still means what it always meant, and `create alpha
+ * my-feature` means alpha. Guessing by position would silently reinterpret
+ * every existing single-repo invocation whose slug happened to arrive first.
+ *
+ * When the repo cannot be determined here the args pass through untouched and
+ * `_resolve_workbench_repo` in the shell refuses, naming the candidates —
+ * one refusal, in one place, rather than two that can disagree.
+ */
+export function worktreeCreate(args, projectRoot) {
+    const declared = new Set(readWorkbenchRepos(projectRoot ?? process.cwd()).map((r) => r.name));
+    const named = args.length >= 2 && declared.has(args[0]);
+    const repo = named ? args[0] : undefined;
+    const [slug, baseBranch] = named ? args.slice(1) : args;
+    return worktreeCreateResolved(slug, baseBranch, repo);
+}
+function worktreeCreateResolved(slug, baseBranch, repo) {
     const pkgRoot = indusKMcpPackageRoot();
     const script = resolve(pkgRoot, "extensions/worktree/scripts/setup-worktree.sh");
     if (!existsSync(script)) {
         console.error(`Error: setup-worktree.sh not found at ${script}`);
         process.exit(1);
     }
-    const r = spawnSync("bash", [script, ...(baseBranch ? [slug, baseBranch] : [slug])], {
+    // The shell script places the worktree; tell it where when a location is
+    // declared. Absent, it keeps putting worktrees at the workbench root.
+    const declared = repo
+        ? readWorkbenchRepos(process.cwd()).find((r) => r.name === repo)
+        : undefined;
+    const scriptArgs = [
+        ...(declared?.worktrees ? ["--worktrees-dir", declared.worktrees] : []),
+        ...(repo ? ["--repo", repo] : []),
+        slug,
+        ...(baseBranch ? [baseBranch] : []),
+    ];
+    const r = spawnSync("bash", [script, ...scriptArgs], {
         cwd: process.cwd(),
         stdio: "inherit",
     });
@@ -130,7 +164,7 @@ export function worktreeCreate(slug, baseBranch) {
 }
 /** Read `post_create` commands from the workbench's worktree config — run in each new worktree after create. */
 function readPostCreate(workbenchRoot) {
-    const repo = readWorkbenchConfig(workbenchRoot)?.worktree?.wrapped_repo;
+    const repo = readWorkbenchRepos(workbenchRoot)[0]?.name;
     if (!repo)
         return [];
     const p = join(workbenchRoot, ".indusk", "worktree-configs", `${repo}.json`);
@@ -150,7 +184,7 @@ function readPostCreate(workbenchRoot) {
 function resolveWorkbenchRoot(start) {
     let dir = resolve(start);
     for (let i = 0; i < 40; i++) {
-        if (readWorkbenchConfig(dir)?.worktree?.shape === "workbench")
+        if (isWorkbench(dir))
             return dir;
         const parent = dirname(dir);
         if (parent === dir)
@@ -165,129 +199,138 @@ export function worktreeRefresh(slug) {
 export function worktreePreflight(slug, baseBranch) {
     runWorktreeScript("preflight", baseBranch ? [slug, baseBranch] : [slug]);
 }
-function readWorkbenchConfig(workbenchRoot) {
-    const cfg = join(workbenchRoot, ".indusk", "config.json");
-    if (!existsSync(cfg))
-        return null;
+// ---- list (TS-implemented; uses the Phase 2 validator) ----------------------
+/**
+ * `indusk worktree list` — print the workbench's current state:
+ *   - wrapped repo + trunk symlink path + resolves status
+ *   - worktrees as siblings of the trunk
+ *   - worktree config status badge: (config valid) / (config missing) /
+ *     (config invalid: <reason>) / (no worktrees)
+ */
+/** Trunk symlink status for one declared repo. */
+function trunkStatusFor(trunkPath) {
+    if (!existsSync(trunkPath)) {
+        return "missing — run `indusk workbench restore` to materialize it";
+    }
     try {
-        return JSON.parse(readFileSync(cfg, "utf-8"));
+        const st = lstatSync(trunkPath);
+        if (!st.isSymbolicLink())
+            return "directory (not a symlink — unusual for a workbench trunk)";
+        const target = readlinkSync(trunkPath);
+        return existsSync(trunkPath)
+            ? `→ ${target} (resolves)`
+            : `symlink broken (target ${target} not found)`;
     }
-    catch {
-        return null;
+    catch (err) {
+        return `error: ${err.message}`;
     }
 }
-function listSubdirs(workbenchRoot) {
-    const reserved = new Set([
-        ".indusk",
-        ".claude",
-        ".vscode",
-        ".cursor",
-        "node_modules",
-        "dist",
-        "build",
-        ".git",
-        ".next",
-        "scripts",
-        "env",
-    ]);
-    const entries = [];
-    for (const name of readdirSync(workbenchRoot)) {
-        if (reserved.has(name))
-            continue;
-        const full = join(workbenchRoot, name);
-        try {
-            const st = lstatSync(full);
-            if (st.isDirectory() || st.isSymbolicLink())
-                entries.push(name);
-        }
-        catch {
-            // fall through
-        }
+/** Per-repo worktree config badge. */
+function configStatusFor(projectRoot, repo) {
+    const configPath = join(projectRoot, ".indusk", "worktree-configs", `${repo}.json`);
+    if (!existsSync(configPath))
+        return { path: configPath, status: "(config missing)" };
+    try {
+        const result = validateWorktreeConfig(JSON.parse(readFileSync(configPath, "utf-8")));
+        if (result.valid)
+            return { path: configPath, status: "(config valid)" };
+        const first = result.errors[0];
+        return {
+            path: configPath,
+            status: first ? `(config invalid: ${first.field} — ${first.message})` : "(config invalid)",
+        };
+    }
+    catch (err) {
+        return {
+            path: configPath,
+            status: `(config invalid: parse error — ${err.message})`,
+        };
     }
-    return entries.sort();
 }
 /**
- * `indusk worktree list` — print the workbench's current state:
- *   - wrapped repo + trunk symlink path + resolves status
- *   - worktrees as siblings of the trunk
- *   - worktree config status badge: (config valid) / (config missing) /
- *     (config invalid: <reason>) / (no worktrees)
+ * `indusk worktree list` — the workbench's current state, one block per
+ * declared repo.
+ *
+ * N repos rather than one wrapped repo: each declared repo gets its own trunk
+ * line, its own config badge, and its own worktrees. Attribution matters more
+ * than layout here — a reader has to be able to tell "beta has no worktrees"
+ * from "beta's worktrees are listed under alpha".
  */
 export function worktreeList(projectRoot) {
-    const config = readWorkbenchConfig(projectRoot);
-    const wrappedRepo = config?.worktree?.wrapped_repo;
-    const shape = config?.worktree?.shape;
-    if (shape !== "workbench" || !wrappedRepo) {
-        console.error('Error: this project is not a workbench (set worktree.shape="workbench" and worktree.wrapped_repo in .indusk/config.json, or run `indusk init --workbench`).');
+    const repos = readWorkbenchRepos(projectRoot);
+    if (!isWorkbench(projectRoot) || repos.length === 0) {
+        console.error(`Error: ${NOT_A_WORKBENCH}`);
         process.exit(1);
     }
-    // Trunk: symlink at workbench/<wrapped_repo>
-    const trunkPath = join(projectRoot, wrappedRepo);
-    let trunkStatus = "";
-    let trunkTarget = "";
-    if (!existsSync(trunkPath)) {
-        trunkStatus = "missing — run `indusk init --workbench` to create it";
-    }
-    else {
-        try {
-            const st = lstatSync(trunkPath);
-            if (st.isSymbolicLink()) {
-                trunkTarget = readlinkSync(trunkPath);
-                // Resolve to verify the target exists.
-                if (!existsSync(trunkPath)) {
-                    trunkStatus = `symlink broken (target ${trunkTarget} not found)`;
-                }
-                else {
-                    trunkStatus = `→ ${trunkTarget} (resolves)`;
-                }
-            }
-            else {
-                trunkStatus = "directory (not a symlink — unusual for a workbench trunk)";
-            }
-        }
-        catch (err) {
-            trunkStatus = `error: ${err.message}`;
-        }
+    // Trunks are found at their DECLARED path; `name` is an identifier, not a
+    // location. A repo whose directory was renamed still resolves, because
+    // nothing here derives a path from a name.
+    const repoPaths = new Map(repos.map((r) => [r.name, join(projectRoot, repoDir(r))]));
+    const occupied = new Set([
+        ...repos.map((r) => repoDir(r)),
+        ...repos.map((r) => r.worktrees).filter((w) => typeof w === "string"),
+    ]);
+    const slugs = listWorkbenchSubdirs(projectRoot).filter((name) => !occupied.has(name));
+    const byRepo = new Map(repos.map((r) => [r.name, []]));
+    const unattributed = [];
+    // STRUCTURAL first: a repo that declares a worktrees directory owns what is
+    // inside it, by construction. No git call, no inference — the containing
+    // directory IS the answer, which is the whole point of declaring it.
+    for (const repo of repos) {
+        if (!repo.worktrees)
+            continue;
+        const dir = join(projectRoot, repo.worktrees);
+        if (!existsSync(dir))
+            continue;
+        byRepo.get(repo.name)?.push(...listWorkbenchSubdirs(dir));
     }
-    // Per-repo config: .indusk/worktree-configs/<wrapped_repo>.json
-    const configPath = join(projectRoot, ".indusk", "worktree-configs", `${wrappedRepo}.json`);
-    let configStatus = "";
-    if (!existsSync(configPath)) {
-        configStatus = "(config missing)";
+    // Then whatever is loose at the root — the flat layout, and anything a
+    // declaration does not place. Attribution falls back to asking git.
+    //
+    // Discovery stays on DISK. Declarations add structure and can never
+    // subtract: a directory renamed without updating config must still appear,
+    // as unattributed, rather than vanish from the listing. A declaration that
+    // silently removes work is worse than one that admits it cannot place it.
+    for (const slug of slugs) {
+        const owner = worktreeOwner(join(projectRoot, slug), repoPaths);
+        if (owner)
+            byRepo.get(owner)?.push(slug);
+        else
+            unattributed.push(slug);
     }
-    else {
-        try {
-            const raw = JSON.parse(readFileSync(configPath, "utf-8"));
-            const result = validateWorktreeConfig(raw);
-            if (result.valid) {
-                configStatus = "(config valid)";
-            }
-            else {
-                const firstErr = result.errors[0];
-                configStatus = firstErr
-                    ? `(config invalid: ${firstErr.field} — ${firstErr.message})`
-                    : "(config invalid)";
-            }
+    console.info(`Workbench:    ${projectRoot}`);
+    console.info(`Repos (${repos.length}): ${repos.map((r) => r.name).join(", ")}`);
+    for (const repo of repos) {
+        const cfg = configStatusFor(projectRoot, repo.name);
+        const mine = byRepo.get(repo.name) ?? [];
+        console.info("");
+        console.info(`${repo.name}`);
+        console.info(`  Trunk:      ${repoDir(repo)} ${trunkStatusFor(join(projectRoot, repoDir(repo)))}`);
+        console.info(`  Remote:     ${repo.remote ?? "(none declared — `workbench restore` cannot clone it)"}`);
+        console.info(`  Config:     ${cfg.path} ${cfg.status}`);
+        if (mine.length === 0) {
+            console.info(`  Worktrees:  (none) — \`indusk worktree create ${repo.name} <slug>\` to add one`);
         }
-        catch (err) {
-            configStatus = `(config invalid: parse error — ${err.message})`;
+        else {
+            console.info(`  Worktrees (${mine.length}):`);
+            for (const slug of mine)
+                console.info(`    ${slug}`);
         }
     }
-    // Worktrees: subdirs at workbench root excluding the trunk + reserved.
-    const allSubdirs = listSubdirs(projectRoot);
-    const worktreeSlugs = allSubdirs.filter((name) => name !== wrappedRepo);
-    console.info(`Workbench:    ${projectRoot}`);
-    console.info(`Wrapped repo: ${wrappedRepo}`);
-    console.info(`Trunk:        ${wrappedRepo} ${trunkStatus}`);
-    console.info(`Config:       ${configPath} ${configStatus}`);
-    console.info("");
-    if (worktreeSlugs.length === 0) {
-        console.info("Worktrees:    (no worktrees) — `indusk worktree create <slug>` to add one");
-    }
-    else {
-        console.info(`Worktrees (${worktreeSlugs.length}):`);
-        for (const slug of worktreeSlugs) {
+    if (unattributed.length > 0) {
+        console.info("");
+        console.info(`Unattributed (${unattributed.length}) — present on disk, but not inside any declared worktrees location and not resolvable to a declared repo:`);
+        for (const slug of unattributed) {
             console.info(`  ${slug}`);
+            // Name what is INSIDE it, one level down. A renamed worktrees
+            // directory is the common way to land here, and reporting only the
+            // container is its own kind of subtraction: the reader sees a folder
+            // and cannot tell it holds work. Naming them is the difference
+            // between "not dropped" and "actually visible".
+            for (const inner of listWorkbenchSubdirs(join(projectRoot, slug))) {
+                const owner = worktreeOwner(join(projectRoot, slug, inner), repoPaths);
+                console.info(`    ${inner}${owner ? `  (a worktree of ${owner})` : ""}`);
+            }
         }
     }
 }

package/dist/lib/config.d.ts

@@ -138,6 +138,65 @@ export interface InduskConfig {
     planning?: {
         dead_draft_days?: number;
     };
+    /**
+     * Workbench topology (versioned-workbench). A workbench wraps N >= 1 repos.
+     *
+     * `repos[]` is the single source of truth for which repos a workbench is
+     * made of; the older singular `wrapped_repo` reduces to a one-element list,
+     * so no existing workbench needs a config edit. Both are read through
+     * `readWorkbenchRepos` in `lib/worktree/repos.ts` — never destructured
+     * directly, because the reduction lives in that one function and a caller
+     * that reads the raw field skips it.
+     *
+     * Typed here rather than in the resolver so the shape has one home:
+     * `worktree.ts`, `stray-state-audit.ts` and `hooks/_hook-paths.js` each
+     * hand-rolled a private copy of it before this existed.
+     */
+    worktree?: WorktreeConfig;
+}
+/** One repo a workbench wraps. */
+export interface WorkbenchRepo {
+    name: string;
+    /**
+     * Where to clone from, for `indusk workbench restore`. Optional: a repo
+     * declared without one is declared-but-unrestorable, which restore reports
+     * by name rather than skipping silently. Absent is a real state, not a
+     * malformed one — the singular `wrapped_repo` shape never carried a remote.
+     */
+    remote?: string;
+    /**
+     * The directory holding this repo's checkout, relative to the workbench.
+     * Absent ⇒ `name`.
+     *
+     * Declaring it is what lets a directory be renamed without breaking
+     * anything: `name` becomes an identifier rather than a location. Nothing
+     * derives a path from a name — the same rule the listing already follows
+     * when it asks git who owns a worktree rather than guessing from a prefix.
+     */
+    path?: string;
+    /**
+     * The directory this repo's worktrees live in, relative to the workbench.
+     * Absent ⇒ the workbench root, which is today's flat layout.
+     *
+     * **Absence meaning flat is the whole migration story.** An existing
+     * workbench declares nothing and behaves exactly as it does now; the nested
+     * layout is opt-in per repo. Same reduction shape that made `wrapped_repo`
+     * → `repos[]` cost nothing.
+     *
+     * Declaring it also makes the ignore rule precise: worktree names are
+     * invented at runtime and cannot be listed in advance, but the directory
+     * containing them can be named exactly.
+     */
+    worktrees?: string;
+}
+export interface WorktreeConfig {
+    shape?: "workbench";
+    /** The repos this workbench wraps. Supersedes `wrapped_repo`. */
+    repos?: WorkbenchRepo[];
+    /** Legacy singular form. Reduces to `repos: [{ name }]`. */
+    wrapped_repo?: string;
+    /** Parent directory the sibling clones live in. */
+    sibling_parent?: string;
 }
 /** Default sweep TTL: 7 days. Distinct from the 60-minute display TTL. */
 export declare const DEFAULT_SWEEP_TTL_MINUTES: number;

package/dist/lib/hook-migration.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Migration surface for retired hooks — the twin of `mcp-migration.ts`.
+ *
+ * Deleting a hook from the package source does nothing to consumers. The file
+ * stays on disk in every `.claude/hooks/` that ever installed it, *and* stays
+ * registered in `.claude/settings.json`, so it keeps being invoked forever —
+ * or, once the file is finally removed by hand, the registration keeps
+ * invoking something that no longer exists. `check-plan-order.js` was the live
+ * instance: deleted from the package in the context-beam cleanup, still on disk
+ * and still registered months later.
+ *
+ * Hooks discovery is `globSync` on both install sides, which means new hooks
+ * arrive automatically and removed hooks never leave. This closes the other
+ * half: `init` and `update` both call it, and future retirements extend
+ * `LEGACY_HOOKS` rather than hand-rolling a removal loop in a command file.
+ */
+/** Hooks retired from the package. Extend on future retirements. */
+export declare const LEGACY_HOOKS: readonly string[];
+export interface RemoveLegacyHooksResult {
+    /** Hook files deleted from `.claude/hooks/`. */
+    filesRemoved: string[];
+    /** Hooks whose `.claude/settings.json` registration was removed. */
+    registrationsRemoved: string[];
+}
+export interface RemoveLegacyHooksOptions {
+    /** Override the legacy list (tests). */
+    hooks?: readonly string[];
+}
+/**
+ * Remove every retired hook's file and its settings registration.
+ *
+ * Both halves matter and they fail differently: an orphaned *file* is dead
+ * weight that still runs, an orphaned *registration* makes Claude Code invoke a
+ * missing script on every matching tool call. Absent state is not an error —
+ * a missing hooks dir, missing settings file, or unparseable settings means
+ * nothing to do, never a throw, because this runs inside `init`/`update` where
+ * a migration must not be able to fail the command.
+ *
+ * A matcher entry whose `hooks` array empties out is dropped entirely rather
+ * than left as an empty shell that matches tool calls and runs nothing.
+ */
+export declare function removeLegacyHooks(projectRoot: string, opts?: RemoveLegacyHooksOptions): RemoveLegacyHooksResult;

package/dist/lib/hook-migration.js

@@ -0,0 +1,94 @@
+/**
+ * Migration surface for retired hooks — the twin of `mcp-migration.ts`.
+ *
+ * Deleting a hook from the package source does nothing to consumers. The file
+ * stays on disk in every `.claude/hooks/` that ever installed it, *and* stays
+ * registered in `.claude/settings.json`, so it keeps being invoked forever —
+ * or, once the file is finally removed by hand, the registration keeps
+ * invoking something that no longer exists. `check-plan-order.js` was the live
+ * instance: deleted from the package in the context-beam cleanup, still on disk
+ * and still registered months later.
+ *
+ * Hooks discovery is `globSync` on both install sides, which means new hooks
+ * arrive automatically and removed hooks never leave. This closes the other
+ * half: `init` and `update` both call it, and future retirements extend
+ * `LEGACY_HOOKS` rather than hand-rolling a removal loop in a command file.
+ */
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/** Hooks retired from the package. Extend on future retirements. */
+export const LEGACY_HOOKS = ["check-plan-order.js"];
+/**
+ * Remove every retired hook's file and its settings registration.
+ *
+ * Both halves matter and they fail differently: an orphaned *file* is dead
+ * weight that still runs, an orphaned *registration* makes Claude Code invoke a
+ * missing script on every matching tool call. Absent state is not an error —
+ * a missing hooks dir, missing settings file, or unparseable settings means
+ * nothing to do, never a throw, because this runs inside `init`/`update` where
+ * a migration must not be able to fail the command.
+ *
+ * A matcher entry whose `hooks` array empties out is dropped entirely rather
+ * than left as an empty shell that matches tool calls and runs nothing.
+ */
+export function removeLegacyHooks(projectRoot, opts = {}) {
+    const legacy = opts.hooks ?? LEGACY_HOOKS;
+    const result = { filesRemoved: [], registrationsRemoved: [] };
+    for (const name of legacy) {
+        const hookPath = join(projectRoot, ".claude/hooks", name);
+        if (existsSync(hookPath)) {
+            try {
+                rmSync(hookPath, { force: true });
+                result.filesRemoved.push(name);
+            }
+            catch {
+                // Leave it rather than fail the migration; the registration removal
+                // below still stops it being invoked.
+            }
+        }
+    }
+    const settingsPath = join(projectRoot, ".claude/settings.json");
+    if (!existsSync(settingsPath))
+        return result;
+    let settings;
+    try {
+        settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+    }
+    catch {
+        return result;
+    }
+    if (!settings.hooks)
+        return result;
+    let changed = false;
+    for (const [event, entries] of Object.entries(settings.hooks)) {
+        if (!Array.isArray(entries))
+            continue;
+        const keptEntries = [];
+        for (const entry of entries) {
+            const commands = Array.isArray(entry.hooks) ? entry.hooks : [];
+            const kept = commands.filter((c) => {
+                const cmd = String(c.command ?? "");
+                const hit = legacy.find((name) => cmd.includes(name));
+                if (hit) {
+                    if (!result.registrationsRemoved.includes(hit))
+                        result.registrationsRemoved.push(hit);
+                    changed = true;
+                    return false;
+                }
+                return true;
+            });
+            // An entry that had commands and now has none would match tool calls and
+            // run nothing — drop it instead.
+            if (commands.length > 0 && kept.length === 0)
+                continue;
+            keptEntries.push(kept.length === commands.length ? entry : { ...entry, hooks: kept });
+        }
+        if (keptEntries.length === 0)
+            delete settings.hooks[event];
+        else
+            settings.hooks[event] = keptEntries;
+    }
+    if (changed)
+        writeFileSync(settingsPath, `${JSON.stringify(settings, null, "\t")}\n`);
+    return result;
+}

package/dist/lib/path-segment.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The one definition of "this name is safe to join into a path".
+ *
+ * Lived inside `plan-parser.ts` while plan declarations were the only
+ * caller. Workbench repo names are the second caller, and the standing rule
+ * here is that a primitive kept in a domain folder gets COPIED by the next
+ * domain rather than imported — which is how `git()` and the phase-block scan
+ * each ended up with two definitions. Moving it out on the second caller
+ * rather than the third is the cheap moment.
+ *
+ * Both callers read a name out of a file a human edits and then join it into
+ * a filesystem path. Same question, same answer — unlike `isMachineState` vs
+ * `isNotCode`, which look alike and are deliberately not shared because their
+ * answers genuinely differ.
+ */
+/**
+ * A name must be a single clean path segment to be joined into a path or
+ * rendered verbatim. Anything else is dropped at the boundary: degrade to
+ * structure-loss, never a path traversal or a raw render.
+ */
+export declare function isCleanSegment(name: string): boolean;
+/** A clean segment that does not collide with machine-owned state. */
+export declare function isUsableSegment(name: string): boolean;

package/dist/lib/path-segment.js

@@ -0,0 +1,41 @@
+/**
+ * The one definition of "this name is safe to join into a path".
+ *
+ * Lived inside `plan-parser.ts` while plan declarations were the only
+ * caller. Workbench repo names are the second caller, and the standing rule
+ * here is that a primitive kept in a domain folder gets COPIED by the next
+ * domain rather than imported — which is how `git()` and the phase-block scan
+ * each ended up with two definitions. Moving it out on the second caller
+ * rather than the third is the cheap moment.
+ *
+ * Both callers read a name out of a file a human edits and then join it into
+ * a filesystem path. Same question, same answer — unlike `isMachineState` vs
+ * `isNotCode`, which look alike and are deliberately not shared because their
+ * answers genuinely differ.
+ */
+/**
+ * A name must be a single clean path segment to be joined into a path or
+ * rendered verbatim. Anything else is dropped at the boundary: degrade to
+ * structure-loss, never a path traversal or a raw render.
+ */
+export function isCleanSegment(name) {
+    return (name.trim() !== "" &&
+        name !== "." &&
+        name !== ".." &&
+        !name.includes("/") &&
+        !name.includes("\\"));
+}
+/**
+ * Directories a declared path must never resolve onto.
+ *
+ * `isCleanSegment` answers "could this traverse?" — it cannot answer "does
+ * this collide?". `.git`, `.indusk` and `.claude` are all single clean
+ * segments, so a config declaring `worktrees: ".git"` would place worktrees
+ * inside the workbench's own git directory. Collision is a different question
+ * from traversal and needs its own answer.
+ */
+const RESERVED_SEGMENTS = new Set([".git", ".indusk", ".claude"]);
+/** A clean segment that does not collide with machine-owned state. */
+export function isUsableSegment(name) {
+    return isCleanSegment(name) && !RESERVED_SEGMENTS.has(name);
+}

package/dist/lib/plan-parser.js

@@ -2,6 +2,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import matter from "gray-matter";
 import { getPlanningDir } from "./config.js";
+import { isCleanSegment } from "./path-segment.js";
 const STAGE_ORDER = [
     "research",
     "brief",
@@ -101,19 +102,10 @@ export function parsePlan(planDir) {
         ...(parseError && { parseError }),
     };
 }
-/**
- * A declaration name must be a single clean path segment — it gets joined
- * into filesystem paths (`join(planningDir, name, "master.md")`) and rendered
- * verbatim in the sidebar. Anything else is dropped at this boundary: degrade
- * to structure-loss, never a path traversal or a raw render.
- */
-function isCleanSegment(name) {
-    return (name.trim() !== "" &&
-        name !== "." &&
-        name !== ".." &&
-        !name.includes("/") &&
-        !name.includes("\\"));
-}
+// A declaration name must be a single clean path segment — it gets joined into
+// filesystem paths (`join(planningDir, name, "master.md")`) and rendered
+// verbatim in the sidebar. The guard now lives in `lib/path-segment.ts`,
+// shared with workbench repo names, which are the same question.
 /**
  * Read a frontmatter key as a string array; anything else yields [].
  * Non-string entries, non-segment names, and duplicates are dropped —

package/dist/lib/stray-state-audit.d.ts

@@ -10,7 +10,8 @@
  * operator can manually `rm -rf` after confirming nothing important is in them.
  *
  * Workbench mode is detected by reading `.indusk/config.json` at the
- * `workbenchRoot` and checking for a `worktree.wrapped_repo` field. Single-
+ * `workbenchRoot` and resolving its declared repo set via `readWorkbenchRepos`
+ * (which reduces the legacy `wrapped_repo` into a one-element list). Single-
  * repo mode skips the audit entirely (no false positives).
  *
  * Worktrees that live at the workbench-root level (sibling to the wrapped
@@ -31,7 +32,7 @@ export interface StrayStateFinding {
  * Find stray `.indusk/` directories in a workbench-shaped project.
  *
  * Returns an empty array if:
- * - `workbenchRoot` is not a workbench-mode project (no `worktree.wrapped_repo`
+ * - `workbenchRoot` is not a workbench-mode project (no declared repos
  *   in config) — single-repo projects are not audited
  * - the wrapped repo doesn't exist (nothing to audit)
  * - no stray state is found (clean workbench)