@haus-tech/haus-workflow 1.4.1 → 1.5.0

package/dist/cli.js

@@ -59,12 +59,12 @@ var init_exec = __esm({
 });
 
 // src/cli.ts
-import { readFileSync as readFileSync4 } from "node:fs";
-import path53 from "node:path";
+import { readFileSync as readFileSync5 } from "node:fs";
+import path70 from "node:path";
 import { Command } from "commander";
 
 // src/commands/apply.ts
-import path22 from "node:path";
+import path23 from "node:path";
 import checkbox from "@inquirer/checkbox";
 
 // src/catalog/load-catalog.ts
@@ -141,13 +141,44 @@ async function atomicWriteText(file, value) {
   await fs.writeFile(tempPath, value, "utf8");
   await fs.move(tempPath, file, { overwrite: true });
 }
+async function findNestedRepoDirs(root) {
+  const matches = await fg("**/.git", {
+    cwd: root,
+    dot: true,
+    onlyFiles: false,
+    followSymbolicLinks: false,
+    suppressErrors: true,
+    ignore: ["**/node_modules/**", "**/dist/**"]
+  });
+  const owners = /* @__PURE__ */ new Set();
+  for (const match of matches) {
+    const owner = path.posix.dirname(match);
+    if (owner === "." || owner === "") continue;
+    owners.add(owner);
+  }
+  const shallowestFirst = [...owners].sort((a, b) => a.split("/").length - b.split("/").length);
+  const nested = [];
+  for (const dir of shallowestFirst) {
+    if (nested.some((kept) => dir === kept || dir.startsWith(`${kept}/`))) continue;
+    nested.push(dir);
+  }
+  return nested;
+}
 async function listFiles(root, patterns) {
+  const nestedRepoDirs = await findNestedRepoDirs(root);
+  const ignore = [
+    "**/node_modules/**",
+    "**/.git/**",
+    "**/dist/**",
+    "**/tests/fixtures/**",
+    ...nestedRepoDirs.map((d) => `${d}/**`)
+  ];
   const files = await fg(patterns, {
     cwd: root,
     dot: true,
     onlyFiles: true,
     suppressErrors: true,
-    ignore: ["**/node_modules/**", "**/.git/**", "**/dist/**", "**/tests/fixtures/**"]
+    ignore
   });
   return files.sort((a, b) => a.localeCompare(b));
 }
@@ -478,12 +509,12 @@ async function resolveCatalogRef(opts) {
   const fetchLatest = opts?.fetchLatestTag ?? fetchLatestCatalogTag;
   const tag = await fetchLatest();
   if (tag !== null) return tag;
-  const fallback = opts?.fallbackRef;
-  if (fallback) {
+  const fallback2 = opts?.fallbackRef;
+  if (fallback2) {
     warn(
-      `Tag resolution failed \u2014 using cached ref ${fallback}. To use latest, retry or set HAUS_CATALOG_REF explicitly.`
+      `Tag resolution failed \u2014 using cached ref ${fallback2}. To use latest, retry or set HAUS_CATALOG_REF explicitly.`
     );
-    return fallback;
+    return fallback2;
   }
   const bundled = getBundledCatalogRef();
   if (bundled) {
@@ -1489,6 +1520,37 @@ function catalogItemContentPath(contentRoot, item) {
   return path9.join(contentRoot, item.path);
 }
 
+// src/claude/gitignore-owned-check.ts
+init_exec();
+var HAUS_OWNED_TRACKED_PATHS = [
+  ".claude",
+  ".claude/skills",
+  ".claude/agents",
+  ".claude/commands",
+  ".haus-workflow"
+];
+async function findGitignoredHausPaths(root) {
+  try {
+    const result = await runGit(["check-ignore", "--", ...HAUS_OWNED_TRACKED_PATHS], {
+      cwd: root,
+      timeout: 5e3
+    });
+    if (result.exitCode !== 0 && result.exitCode !== 1) return [];
+    return [
+      ...new Set(
+        result.stdout.split("\n").map((line2) => line2.trim()).filter(Boolean)
+      )
+    ];
+  } catch {
+    return [];
+  }
+}
+function summarizeGitignoredHausDirs(paths) {
+  const dirs = /* @__PURE__ */ new Set();
+  for (const p of paths) dirs.add(p === ".haus-workflow" ? ".haus-workflow/" : ".claude/");
+  return [...dirs];
+}
+
 // src/claude/write-claude-files.ts
 import path19 from "node:path";
 import fs18 from "fs-extra";
@@ -1596,7 +1658,8 @@ function digestFileContent(buf) {
   }
   return hashText(buf);
 }
-async function hashInstalledPaths(root, relPaths) {
+async function hashInstalledPaths(root, relPaths, opts = {}) {
+  const followSymlinks = opts.followSymlinks ?? true;
   if (relPaths.length === 0) {
     return hashText(EMPTY_LOCK_PATHS_TOKEN);
   }
@@ -1605,17 +1668,24 @@ async function hashInstalledPaths(root, relPaths) {
   for (const rel of normalized) {
     const abs = path10.join(root, rel);
     if (!await fs7.pathExists(abs)) continue;
-    const stat = await fs7.stat(abs);
+    const stat = followSymlinks ? await fs7.stat(abs) : await fs7.lstat(abs);
+    if (!followSymlinks && stat.isSymbolicLink()) continue;
     if (stat.isFile()) {
       const body = await fs7.readFile(abs);
       fileDigests.push({ rel, digest: digestFileContent(body) });
       continue;
     }
     if (!stat.isDirectory()) continue;
-    const inner = await fg2("**/*", { cwd: abs, onlyFiles: true, dot: true });
+    const inner = await fg2("**/*", {
+      cwd: abs,
+      onlyFiles: true,
+      dot: true,
+      followSymbolicLinks: followSymlinks
+    });
     for (const sub of inner.sort()) {
-      const relFile = path10.join(rel, sub).replace(/\\/g, "/");
       const absFile = path10.join(abs, sub);
+      if (!followSymlinks && (await fs7.lstat(absFile)).isSymbolicLink()) continue;
+      const relFile = path10.join(rel, sub).replace(/\\/g, "/");
       const body = await fs7.readFile(absFile);
       fileDigests.push({ rel: relFile, digest: digestFileContent(body) });
     }
@@ -2033,8 +2103,8 @@ function buildDenyRules() {
   for (const command of DENY_COMMANDS) {
     rules.push(`Bash(${command}:*)`);
   }
-  for (const path54 of DENY_PATHS) {
-    const pattern = DENY_DIRS.has(path54) ? `${path54}/**` : path54;
+  for (const path71 of DENY_PATHS) {
+    const pattern = DENY_DIRS.has(path71) ? `${path71}/**` : path71;
     for (const tool of FILE_TOOLS) {
       rules.push(`${tool}(${pattern})`);
     }
@@ -2078,6 +2148,13 @@ var PROJECT_HOOK_FRAGMENTS = [
     event: "SessionStart",
     matcher: "*",
     command: "haus update --from-hook"
+  },
+  {
+    id: "hook.workspace.worktree-check",
+    gate: "keep",
+    event: "SessionStart",
+    matcher: "*",
+    command: "haus workspace worktree doctor --from-hook"
   }
 ];
 async function readProjectSettings(root) {
@@ -2186,6 +2263,10 @@ var CANONICAL_HOOKS = {
       {
         matcher: "*",
         hooks: [{ type: "command", command: "haus update --from-hook" }]
+      },
+      {
+        matcher: "*",
+        hooks: [{ type: "command", command: "haus workspace worktree doctor --from-hook" }]
       }
     ]
   }
@@ -2555,7 +2636,6 @@ function refillContent(existing, v) {
 }
 var FALLBACK_CONTEXT = {
   generatedAt: "",
-  root: "",
   repoName: "",
   packageManager: "unknown",
   repoRoles: [],
@@ -3247,27 +3327,192 @@ async function pruneOrphanedCatalogItems(root, prevLock, notOrphanedIds, dryRun,
   }
 }
 
+// src/claude/write-gitignore.ts
+init_exec();
+import path20 from "node:path";
+import fs19 from "fs-extra";
+var GITIGNORE_BEGIN = "# HAUS:BEGIN haus-managed v=1";
+var GITIGNORE_END = "# HAUS:END haus-managed";
+var GITIGNORED_ARTIFACT_PATHS = [
+  ".haus-workflow/context-map.json",
+  ".haus-workflow/recommendation.json",
+  ".haus-workflow/sources-report.json",
+  ".haus-workflow/deep-context.json"
+];
+function findLineMarker3(content2, marker, from = 0) {
+  let idx = content2.indexOf(marker, from);
+  while (idx !== -1) {
+    const lineStart = idx === 0 || content2[idx - 1] === "\n";
+    const after = idx + marker.length;
+    const lineEnd = after === content2.length || content2[after] === "\n" || content2[after] === "\r";
+    if (lineStart && lineEnd) return { start: idx, end: after };
+    idx = content2.indexOf(marker, idx + marker.length);
+  }
+  return null;
+}
+function findBlockRangeFor(content2, beginMarker, endMarker) {
+  const begin = findLineMarker3(content2, beginMarker);
+  if (!begin) return null;
+  const end = findLineMarker3(content2, endMarker, begin.end);
+  if (!end) return null;
+  return { start: begin.start, end: end.end };
+}
+function gitignoreCovers(lines, entry) {
+  const bare = entry.replace(/^\/+/, "");
+  const exactEquivalents = /* @__PURE__ */ new Set([bare, `/${bare}`]);
+  for (const raw of lines) {
+    const line2 = raw.trim();
+    if (!line2 || line2.startsWith("#")) continue;
+    if (exactEquivalents.has(line2)) return true;
+    const dirCandidate = line2.replace(/^\/+/, "").replace(/\/\*\*$/, "").replace(/\/$/, "");
+    if (dirCandidate && !/[*?[\]!]/.test(dirCandidate)) {
+      if (bare === dirCandidate || bare.startsWith(`${dirCandidate}/`)) return true;
+    }
+  }
+  return false;
+}
+function linesOutsideBlockFor(content2, beginMarker, endMarker) {
+  const range = findBlockRangeFor(content2, beginMarker, endMarker);
+  const outside = range ? content2.slice(0, range.start) + content2.slice(range.end) : content2;
+  return outside.split("\n");
+}
+function buildBlockFor(existing, beginMarker, endMarker, comment, patterns) {
+  const outside = linesOutsideBlockFor(existing, beginMarker, endMarker);
+  const needed = patterns.filter((p) => !gitignoreCovers(outside, p));
+  if (needed.length === 0) return null;
+  return [beginMarker, comment, ...needed, endMarker].join("\n");
+}
+var ARTIFACT_BLOCK_COMMENT = "# haus scan artifacts \u2014 machine-local, must never be committed (see ADR-0025)";
+function injectBlockFor(existing, beginMarker, endMarker, comment, patterns) {
+  const block = buildBlockFor(existing, beginMarker, endMarker, comment, patterns);
+  const range = findBlockRangeFor(existing, beginMarker, endMarker);
+  if (block === null) {
+    if (!range) return existing;
+    const before = existing.slice(0, range.start);
+    const after = existing.slice(range.end);
+    const merged = `${before}${after}`.replace(/\n{3,}/g, "\n\n").trimEnd();
+    return merged.length > 0 ? `${merged}
+` : "";
+  }
+  if (range) {
+    const before = existing.slice(0, range.start);
+    const after = existing.slice(range.end);
+    return `${before}${block}${after}`.replace(/\n*$/, "\n");
+  }
+  const loneBegin = findLineMarker3(existing, beginMarker);
+  if (loneBegin) {
+    const before = existing.slice(0, loneBegin.start).trimEnd();
+    if (before.length === 0) return `${block}
+`;
+    return `${before}
+
+${block}
+`;
+  }
+  const trimmed = existing.trimEnd();
+  if (trimmed.length === 0) return `${block}
+`;
+  return `${trimmed}
+
+${block}
+`;
+}
+function injectGitignoreBlock(existing) {
+  return injectBlockFor(
+    existing,
+    GITIGNORE_BEGIN,
+    GITIGNORE_END,
+    ARTIFACT_BLOCK_COMMENT,
+    GITIGNORED_ARTIFACT_PATHS
+  );
+}
+var LINK_CONTEXT_GITIGNORE_BEGIN = "# HAUS:BEGIN haus-managed-link-context v=1";
+var LINK_CONTEXT_GITIGNORE_END = "# HAUS:END haus-managed-link-context";
+var LINKED_CONTEXT_GITIGNORE_PATTERNS = [
+  ".claude/skills/*--*/",
+  ".claude/agents/*--*.md",
+  ".claude/commands/*--*.md"
+];
+var LINK_CONTEXT_BLOCK_COMMENT = "# haus workspace link-context copies \u2014 derived cross-repo skill/agent/command copies, never committed";
+function injectLinkContextGitignoreBlock(existing) {
+  return injectBlockFor(
+    existing,
+    LINK_CONTEXT_GITIGNORE_BEGIN,
+    LINK_CONTEXT_GITIGNORE_END,
+    LINK_CONTEXT_BLOCK_COMMENT,
+    LINKED_CONTEXT_GITIGNORE_PATTERNS
+  );
+}
+async function writeGitignore(root, dryRun) {
+  const filePath = path20.join(root, ".gitignore");
+  const prev = await fs19.pathExists(filePath) ? await fs19.readFile(filePath, "utf8") : "";
+  const next = injectGitignoreBlock(prev);
+  await writeManagedText(root, filePath, next, dryRun);
+  return filePath;
+}
+async function writeLinkContextGitignore(root, dryRun) {
+  const filePath = path20.join(root, ".gitignore");
+  const prev = await fs19.pathExists(filePath) ? await fs19.readFile(filePath, "utf8") : "";
+  const next = injectLinkContextGitignoreBlock(prev);
+  await writeManagedText(root, filePath, next, dryRun);
+  return filePath;
+}
+async function listTrackedArtifactPaths(root) {
+  try {
+    const result = await runGit(["ls-files", "--", ...GITIGNORED_ARTIFACT_PATHS], {
+      cwd: root,
+      timeout: 5e3
+    });
+    if (result.exitCode !== 0) return [];
+    return result.stdout.split("\n").map((line2) => line2.trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+async function untrackMachineLocalArtifacts(root, dryRun, notify) {
+  const tracked = await listTrackedArtifactPaths(root);
+  const untracked = [];
+  for (const rel of tracked) {
+    if (dryRun) {
+      notify(
+        `Would untrack ${rel} from git \u2014 it contains machine-local scan output and should never have been committed.`
+      );
+      continue;
+    }
+    const result = await runGit(["rm", "--cached", "--quiet", "--", rel], { cwd: root });
+    if (result.exitCode === 0) {
+      untracked.push(rel);
+      notify(
+        `Untracked ${rel} from git \u2014 it contains machine-local scan output and should never have been committed. Run \`git status\` to review before committing this change.`
+      );
+    } else {
+      notify(`Could not untrack ${rel} from git: ${result.stderr.trim() || result.stdout.trim()}`);
+    }
+  }
+  return untracked;
+}
+
 // src/refs/fetch-refs.ts
-import path21 from "node:path";
-import fs20 from "fs-extra";
+import path22 from "node:path";
+import fs21 from "fs-extra";
 
 // src/refs/cache-meta.ts
-import path20 from "node:path";
-import fs19 from "fs-extra";
+import path21 from "node:path";
+import fs20 from "fs-extra";
 var META_FILENAME = "cache-meta.json";
 async function readCacheMeta(cacheDir) {
-  const metaPath = path20.join(cacheDir, META_FILENAME);
+  const metaPath = path21.join(cacheDir, META_FILENAME);
   try {
-    const raw = await fs19.readFile(metaPath, "utf8");
+    const raw = await fs20.readFile(metaPath, "utf8");
     return JSON.parse(raw);
   } catch {
     return {};
   }
 }
 async function writeCacheMeta(cacheDir, meta) {
-  await fs19.ensureDir(cacheDir);
-  const metaPath = path20.join(cacheDir, META_FILENAME);
-  await fs19.writeFile(metaPath, JSON.stringify(meta, null, 2) + "\n", "utf8");
+  await fs20.ensureDir(cacheDir);
+  const metaPath = path21.join(cacheDir, META_FILENAME);
+  await fs20.writeFile(metaPath, JSON.stringify(meta, null, 2) + "\n", "utf8");
 }
 
 // src/refs/fetch-refs.ts
@@ -3287,8 +3532,8 @@ function isLlmsTxtUrl(ref) {
 async function fetchSingleRef(url, cacheDir, meta) {
   const existing = meta[url];
   const headers = {};
-  const safeFile = existing?.file && existing.file === path21.basename(existing.file);
-  const cachedFileExists = safeFile && await fs20.pathExists(path21.join(cacheDir, existing.file));
+  const safeFile = existing?.file && existing.file === path22.basename(existing.file);
+  const cachedFileExists = safeFile && await fs21.pathExists(path22.join(cacheDir, existing.file));
   if (cachedFileExists) {
     if (existing?.etag) headers["If-None-Match"] = existing.etag;
     if (existing?.lastModified) headers["If-Modified-Since"] = existing.lastModified;
@@ -3299,8 +3544,8 @@ async function fetchSingleRef(url, cacheDir, meta) {
     if (!res.ok) return { result: "failed" };
     const text = await res.text();
     const file = `${urlToSlug(url)}.md`;
-    await fs20.ensureDir(cacheDir);
-    await fs20.writeFile(path21.join(cacheDir, file), text, "utf8");
+    await fs21.ensureDir(cacheDir);
+    await fs21.writeFile(path22.join(cacheDir, file), text, "utf8");
     meta[url] = {
       url,
       etag: res.headers.get("etag") ?? void 0,
@@ -3323,8 +3568,8 @@ async function pruneOrphanedRefs(cacheDir, keepUrls) {
     if (keepUrls.has(url)) continue;
     delete meta[url];
     removed++;
-    const safeFile = typeof entry.file === "string" && entry.file === path21.basename(entry.file);
-    if (safeFile) await fs20.remove(path21.join(cacheDir, entry.file)).catch(() => {
+    const safeFile = typeof entry.file === "string" && entry.file === path22.basename(entry.file);
+    if (safeFile) await fs21.remove(path22.join(cacheDir, entry.file)).catch(() => {
     });
   }
   if (removed > 0) await writeCacheMeta(cacheDir, meta);
@@ -3346,10 +3591,10 @@ async function fetchRefsForItems(items, cacheDir) {
       const outcome = await fetchSingleRef(url, cacheDir, meta);
       if (outcome.result === "fetched") {
         summary.fetched++;
-        summary.cachedFiles[url] = path21.join(cacheDir, outcome.file);
+        summary.cachedFiles[url] = path22.join(cacheDir, outcome.file);
       } else if (outcome.result === "unchanged") {
         summary.unchanged++;
-        if (meta[url]?.file) summary.cachedFiles[url] = path21.join(cacheDir, meta[url].file);
+        if (meta[url]?.file) summary.cachedFiles[url] = path22.join(cacheDir, meta[url].file);
       } else {
         summary.failed++;
         summary.failedUrls.push(url);
@@ -3372,7 +3617,7 @@ function parseIdList(value) {
 // src/commands/apply.ts
 var STALE_CACHE_THRESHOLD_DAYS = 7;
 async function cacheHasItems() {
-  const data = await readJson(path22.join(getCacheDir(), "manifest.json"));
+  const data = await readJson(path23.join(getCacheDir(), "manifest.json"));
   return Array.isArray(data?.items) && data.items.length > 0;
 }
 function installableRecommendedItems(recommended) {
@@ -3478,6 +3723,8 @@ async function runApply(options) {
     force: options.force,
     prune: options.prune
   });
+  await writeGitignore(root, isDryRun);
+  await untrackMachineLocalArtifacts(root, isDryRun, warn);
   if (!isDryRun) {
     try {
       const cacheDir = hausPath(root, "llms-cache");
@@ -3503,6 +3750,15 @@ async function runApply(options) {
       );
     }
   }
+  const gitignoredHausPaths = await findGitignoredHausPaths(root);
+  if (gitignoredHausPaths.length > 0) {
+    const dirs = summarizeGitignoredHausDirs(gitignoredHausPaths);
+    const dirList = dirs.join(" and ");
+    const verb = dirs.length === 1 ? "is" : "are";
+    warn(
+      `${dirList} ${verb} gitignored \u2014 installed skills/agents/commands will not be visible to anything relying on git-tracked state. Remove the covering .gitignore rule (only settings.json, settings.local.json, and worktrees/ under .claude/ should ever be ignored).`
+    );
+  }
   if (isDryRun) {
     log(`Dry-run complete \u2014 ${files.length} file(s) planned, none written. Run --write to apply.`);
   } else {
@@ -3512,8 +3768,8 @@ async function runApply(options) {
 }
 
 // src/commands/backups.ts
-import path23 from "node:path";
-import fs21 from "fs-extra";
+import path24 from "node:path";
+import fs22 from "fs-extra";
 
 // src/utils/prompts.ts
 import { stdin as input, stdout as output } from "node:process";
@@ -3543,14 +3799,14 @@ function classify(name) {
 }
 async function listBackups(root) {
   const dir = hausPath(root, "backups");
-  if (!await fs21.pathExists(dir)) return [];
-  const names = await fs21.readdir(dir);
+  if (!await fs22.pathExists(dir)) return [];
+  const names = await fs22.readdir(dir);
   const entries = [];
   for (const name of names) {
     const kind = classify(name);
     if (!kind) continue;
-    const absPath = path23.join(dir, name);
-    const stat = await fs21.lstat(absPath);
+    const absPath = path24.join(dir, name);
+    const stat = await fs22.lstat(absPath);
     if (stat.isSymbolicLink()) continue;
     const expectDirectory = kind !== "lock";
     if (stat.isDirectory() !== expectDirectory) continue;
@@ -3579,13 +3835,13 @@ async function runList(root) {
   }
 }
 async function isUnsafeWriteTarget(root, target) {
-  const segments = path23.relative(root, target).split(path23.sep).filter(Boolean);
+  const segments = path24.relative(root, target).split(path24.sep).filter(Boolean);
   let current = root;
   for (let i = 0; i < segments.length; i++) {
-    current = path23.join(current, segments[i]);
+    current = path24.join(current, segments[i]);
     const isLastSegment = i === segments.length - 1;
     try {
-      const stat = await fs21.lstat(current);
+      const stat = await fs22.lstat(current);
       if (isLastSegment) {
         if (!stat.isFile()) return true;
       } else if (!stat.isDirectory()) {
@@ -3600,7 +3856,7 @@ async function isUnsafeWriteTarget(root, target) {
 }
 async function lstatIfRegularFile(abs) {
   try {
-    const stat = await fs21.lstat(abs);
+    const stat = await fs22.lstat(abs);
     return stat.isFile() ? stat : null;
   } catch (err) {
     if (err.code === "ENOENT") return null;
@@ -3615,8 +3871,8 @@ async function restoreLockBackup(root, entry, yes) {
     );
     return false;
   }
-  if (await fs21.pathExists(target)) {
-    const targetStat = await fs21.stat(target);
+  if (await fs22.pathExists(target)) {
+    const targetStat = await fs22.stat(target);
     if (targetStat.mtimeMs > entry.mtimeMs) {
       warn(
         `Current haus.lock.json (${new Date(targetStat.mtimeMs).toISOString()}) is newer than backup ${entry.id} (${new Date(entry.mtimeMs).toISOString()}) \u2014 it will be overwritten.`
@@ -3636,7 +3892,7 @@ async function restoreLockBackup(root, entry, yes) {
     error(`Refusing to restore: ${entry.id} or ${target} changed since being checked.`);
     return false;
   }
-  await fs21.copy(entry.absPath, target, { overwrite: true });
+  await fs22.copy(entry.absPath, target, { overwrite: true });
   log(`Restored .haus-workflow/haus.lock.json from ${entry.id}.`);
   return true;
 }
@@ -3644,10 +3900,10 @@ async function collectFilesRecursive(dir) {
   const files = [];
   const skippedLinks = [];
   const skippedOther = [];
-  const names = await fs21.readdir(dir);
+  const names = await fs22.readdir(dir);
   for (const name of names) {
-    const abs = path23.join(dir, name);
-    const stat = await fs21.lstat(abs);
+    const abs = path24.join(dir, name);
+    const stat = await fs22.lstat(abs);
     if (stat.isSymbolicLink()) {
       skippedLinks.push(abs);
       continue;
@@ -3669,12 +3925,12 @@ async function restoreDirBackup(root, entry, yes) {
   const { files, skippedLinks, skippedOther } = await collectFilesRecursive(entry.absPath);
   if (skippedLinks.length > 0) {
     warn(
-      `Skipped ${skippedLinks.length} symlink(s) inside backup ${entry.id} \u2014 never followed: ${skippedLinks.map((abs) => path23.relative(entry.absPath, abs)).join(", ")}`
+      `Skipped ${skippedLinks.length} symlink(s) inside backup ${entry.id} \u2014 never followed: ${skippedLinks.map((abs) => path24.relative(entry.absPath, abs)).join(", ")}`
     );
   }
   if (skippedOther.length > 0) {
     warn(
-      `Skipped ${skippedOther.length} non-regular file(s) inside backup ${entry.id} (not restorable): ${skippedOther.map((abs) => path23.relative(entry.absPath, abs)).join(", ")}`
+      `Skipped ${skippedOther.length} non-regular file(s) inside backup ${entry.id} (not restorable): ${skippedOther.map((abs) => path24.relative(entry.absPath, abs)).join(", ")}`
     );
   }
   if (files.length === 0) {
@@ -3684,8 +3940,8 @@ async function restoreDirBackup(root, entry, yes) {
   const safeFiles = [];
   const unsafeTargets = [];
   for (const abs of files) {
-    const rel = path23.relative(entry.absPath, abs);
-    const target = path23.join(root, rel);
+    const rel = path24.relative(entry.absPath, abs);
+    const target = path24.join(root, rel);
     if (await isUnsafeWriteTarget(root, target)) unsafeTargets.push(rel);
     else safeFiles.push(abs);
   }
@@ -3702,16 +3958,16 @@ async function restoreDirBackup(root, entry, yes) {
   const vanished = [];
   const toRestore = [];
   for (const abs of safeFiles) {
-    const rel = path23.relative(entry.absPath, abs);
+    const rel = path24.relative(entry.absPath, abs);
     const backupFileStat = await lstatIfRegularFile(abs);
     if (!backupFileStat) {
       vanished.push(rel);
       continue;
     }
     toRestore.push(abs);
-    const target = path23.join(root, rel);
-    if (await fs21.pathExists(target)) {
-      const targetStat = await fs21.stat(target);
+    const target = path24.join(root, rel);
+    if (await fs22.pathExists(target)) {
+      const targetStat = await fs22.stat(target);
       if (targetStat.mtimeMs > backupFileStat.mtimeMs) {
         stale.push({
           rel,
@@ -3750,14 +4006,14 @@ async function restoreDirBackup(root, entry, yes) {
   let restoredCount = 0;
   const skippedAtWrite = [];
   for (const abs of toRestore) {
-    const rel = path23.relative(entry.absPath, abs);
-    const target = path23.join(root, rel);
+    const rel = path24.relative(entry.absPath, abs);
+    const target = path24.join(root, rel);
     if (!await lstatIfRegularFile(abs) || await isUnsafeWriteTarget(root, target)) {
       skippedAtWrite.push(rel);
       continue;
     }
-    await fs21.ensureDir(path23.dirname(target));
-    await fs21.copy(abs, target, { overwrite: true });
+    await fs22.ensureDir(path24.dirname(target));
+    await fs22.copy(abs, target, { overwrite: true });
     restoredCount++;
   }
   if (skippedAtWrite.length > 0) {
@@ -3814,7 +4070,7 @@ Keeping ${keepCount}.`
   const failed = [];
   for (const entry of removeList) {
     try {
-      await fs21.remove(entry.absPath);
+      await fs22.remove(entry.absPath);
       removed.push(entry.id);
     } catch (err) {
       failed.push({ id: entry.id, message: err instanceof Error ? err.message : String(err) });
@@ -3895,16 +4151,16 @@ async function runCatalogAudit() {
 }
 
 // src/commands/doctor.ts
-import path33 from "node:path";
-import fs28 from "fs-extra";
+import path37 from "node:path";
+import fs29 from "fs-extra";
 
 // src/decisions/doctor.ts
-import path27 from "node:path";
-import fs25 from "fs-extra";
+import path28 from "node:path";
+import fs26 from "fs-extra";
 
 // src/decisions/check.ts
-import path26 from "node:path";
-import fs24 from "fs-extra";
+import path27 from "node:path";
+import fs25 from "fs-extra";
 
 // src/decisions/diff.ts
 init_exec();
@@ -3959,22 +4215,22 @@ function matchesAnyRegex(filePath, patterns) {
 }
 
 // src/decisions/paths.ts
-import path24 from "node:path";
-import fs22 from "fs-extra";
+import path25 from "node:path";
+import fs23 from "fs-extra";
 async function resolveDecisionsDir(root) {
-  const primary = path24.join(root, DECISIONS_TRIGGERS.decisionsDir);
-  if (await fs22.pathExists(primary)) return primary;
-  const legacy = path24.join(root, DECISIONS_TRIGGERS.legacyDecisionsDir ?? "docs/adr");
-  if (await fs22.pathExists(legacy)) return legacy;
+  const primary = path25.join(root, DECISIONS_TRIGGERS.decisionsDir);
+  if (await fs23.pathExists(primary)) return primary;
+  const legacy = path25.join(root, DECISIONS_TRIGGERS.legacyDecisionsDir ?? "docs/adr");
+  if (await fs23.pathExists(legacy)) return legacy;
   return primary;
 }
 function relativeDecisionPath(decisionsDir, root) {
-  return path24.relative(root, decisionsDir).replace(/\\/g, "/");
+  return path25.relative(root, decisionsDir).replace(/\\/g, "/");
 }
 
 // src/decisions/validate.ts
-import path25 from "node:path";
-import fs23 from "fs-extra";
+import path26 from "node:path";
+import fs24 from "fs-extra";
 function validateDecisionContent(content2) {
   const errors = [];
   for (const section of DECISIONS_TRIGGERS.requiredSections) {
@@ -4003,14 +4259,14 @@ function decisionNumberFromFile(name) {
   return match?.[1] ?? null;
 }
 async function validateIndexSync(decisionsDir, decisionFiles) {
-  const readmePath = path25.join(decisionsDir, "README.md");
-  if (!await fs23.pathExists(readmePath)) {
+  const readmePath = path26.join(decisionsDir, "README.md");
+  if (!await fs24.pathExists(readmePath)) {
     return ["docs/decisions/README.md is missing"];
   }
   const readme = await readText(readmePath) ?? "";
   const errors = [];
   for (const file of decisionFiles) {
-    const num = decisionNumberFromFile(path25.basename(file));
+    const num = decisionNumberFromFile(path26.basename(file));
     if (num && !indexReferencesNumber(readme, num)) {
       errors.push(`README.md missing index row for ADR-${num}`);
     }
@@ -4064,22 +4320,22 @@ async function checkSatisfaction(input2) {
   const errors = [];
   const decisionsPrefix = `${input2.decisionsRel}/`;
   const newDecisionFiles = input2.changedFiles.filter(
-    (f) => f.startsWith(decisionsPrefix) && isDecisionFileName(path26.basename(f))
+    (f) => f.startsWith(decisionsPrefix) && isDecisionFileName(path27.basename(f))
   );
   if (newDecisionFiles.length === 0) {
     errors.push(`no new or updated decision under ${input2.decisionsRel}/`);
     return errors;
   }
-  const decisionsDir = path26.join(input2.root, input2.decisionsRel);
+  const decisionsDir = path27.join(input2.root, input2.decisionsRel);
   for (const rel of newDecisionFiles) {
-    const abs = path26.join(input2.root, rel);
+    const abs = path27.join(input2.root, rel);
     const content2 = await readText(abs) ?? "";
     const valid = validateDecisionContent(content2);
     if (!valid.ok) errors.push(...valid.errors.map((e) => `${rel}: ${e}`));
   }
   const indexErrors = await validateIndexSync(
     decisionsDir,
-    newDecisionFiles.map((f) => path26.basename(f))
+    newDecisionFiles.map((f) => path27.basename(f))
   );
   errors.push(...indexErrors);
   return errors;
@@ -4123,8 +4379,8 @@ ${opts.commitMessages ?? ""}`;
     changedFiles: stats.files
   });
   if (satisfactionErrors.length > 0 && decisionsRel !== legacyRel) {
-    const legacyExists = await fs24.pathExists(path26.join(root, legacyRel));
-    if (legacyExists && !await fs24.pathExists(decisionsDir)) {
+    const legacyExists = await fs25.pathExists(path27.join(root, legacyRel));
+    if (legacyExists && !await fs25.pathExists(decisionsDir)) {
       satisfactionErrors = await checkSatisfaction({
         root,
         decisionsRel: legacyRel,
@@ -4144,18 +4400,18 @@ ${opts.commitMessages ?? ""}`;
   return { triggered: true, satisfied: false, reasons, securityTriggered };
 }
 async function listDecisionNumbers(decisionsDir) {
-  if (!await fs24.pathExists(decisionsDir)) return [];
-  const entries = await fs24.readdir(decisionsDir);
+  if (!await fs25.pathExists(decisionsDir)) return [];
+  const entries = await fs25.readdir(decisionsDir);
   return entries.map((name) => decisionNumberFromFile(name)).filter((n) => n != null).map((n) => Number(n));
 }
 
 // src/decisions/doctor.ts
 async function auditDecisionsLayout(root) {
   const findings = [];
-  const primary = path27.join(root, DECISIONS_TRIGGERS.decisionsDir);
-  const legacy = path27.join(root, DECISIONS_TRIGGERS.legacyDecisionsDir ?? "docs/adr");
-  const hasPrimary = await fs25.pathExists(primary);
-  const hasLegacy = await fs25.pathExists(legacy);
+  const primary = path28.join(root, DECISIONS_TRIGGERS.decisionsDir);
+  const legacy = path28.join(root, DECISIONS_TRIGGERS.legacyDecisionsDir ?? "docs/adr");
+  const hasPrimary = await fs26.pathExists(primary);
+  const hasLegacy = await fs26.pathExists(legacy);
   if (!hasPrimary && hasLegacy) {
     findings.push({
       level: "advisory",
@@ -4168,8 +4424,8 @@ async function auditDecisionsLayout(root) {
   if (!hasPrimary) return findings;
   const decisionsDir = await resolveDecisionsDir(root);
   const rel = relativeDecisionPath(decisionsDir, root);
-  const readmePath = path27.join(decisionsDir, "README.md");
-  if (!await fs25.pathExists(readmePath)) {
+  const readmePath = path28.join(decisionsDir, "README.md");
+  if (!await fs26.pathExists(readmePath)) {
     findings.push({
       level: "advisory",
       line: `- DECISIONS: missing ${rel}/README.md index`,
@@ -4179,7 +4435,7 @@ async function auditDecisionsLayout(root) {
     return findings;
   }
   const readme = await readText(readmePath);
-  const entries = (await fs25.readdir(decisionsDir)).filter(
+  const entries = (await fs26.readdir(decisionsDir)).filter(
     (f) => f.endsWith(".md") && f !== "README.md"
   );
   for (const file of entries) {
@@ -4193,7 +4449,7 @@ async function auditDecisionsLayout(root) {
       });
     }
   }
-  const claude = await readText(path27.join(root, "CLAUDE.md"));
+  const claude = await readText(path28.join(root, "CLAUDE.md"));
   if (claude && !claude.includes(`@${rel}/README.md`)) {
     findings.push({
       level: "advisory",
@@ -4224,17 +4480,187 @@ async function auditDecisionsLayout(root) {
 }
 
 // src/scanner/read-context.ts
-import path32 from "node:path";
-import fs27 from "fs-extra";
+import path36 from "node:path";
+import fs28 from "fs-extra";
+
+// src/commands/workspace/config.ts
+import path29 from "node:path";
+import YAML from "yaml";
+var WORKSPACE_FILE = "haus.workspace.yaml";
+function parseWorkspaceConfig(text) {
+  if (!text) return void 0;
+  let parsed;
+  try {
+    parsed = YAML.parse(text);
+  } catch {
+    return void 0;
+  }
+  if (!parsed || typeof parsed !== "object") return void 0;
+  const obj = parsed;
+  const repos = Array.isArray(obj.repos) ? obj.repos.filter(
+    (r) => typeof r === "object" && r !== null && typeof r.name === "string" && typeof r.path === "string"
+  ) : [];
+  return {
+    client: typeof obj.client === "string" ? obj.client : "unknown",
+    repos,
+    relationships: Array.isArray(obj.relationships) ? obj.relationships : []
+  };
+}
+async function readWorkspaceConfig(workspaceRoot) {
+  return parseWorkspaceConfig(await readText(path29.join(workspaceRoot, WORKSPACE_FILE)));
+}
+
+// src/workspace/members.ts
+import path30 from "node:path";
+var REPOS_MANIFEST_FILE = "repos.manifest.json";
+var REPOS_LOCAL_FILE = "repos.local.json";
+var MemberConfigError = class extends Error {
+  constructor(filePath, reason) {
+    super(`Cannot read workspace member config at ${filePath}: ${reason}`);
+    this.filePath = filePath;
+  }
+  filePath;
+  name = "MemberConfigError";
+};
+function resolveAbsPath(workspaceRoot, folder, overrides) {
+  const override = overrides[folder];
+  if (override) return path30.resolve(workspaceRoot, override);
+  return path30.resolve(workspaceRoot, folder);
+}
+async function readPathOverrides(workspaceRoot) {
+  const filePath = path30.join(workspaceRoot, REPOS_LOCAL_FILE);
+  const result = await readJsonDetailed(filePath);
+  if (result.status === "missing") return {};
+  if (result.status === "invalid") throw new MemberConfigError(filePath, "invalid JSON");
+  const parsed = result.value;
+  const rawOverrides = parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed.pathOverrides : void 0;
+  if (rawOverrides === null || typeof rawOverrides !== "object" || Array.isArray(rawOverrides)) {
+    return {};
+  }
+  const overrides = {};
+  for (const [folder, value] of Object.entries(rawOverrides)) {
+    if (typeof value === "string") overrides[folder] = value;
+  }
+  return overrides;
+}
+async function readFromWorkspaceYaml(workspaceRoot, overrides) {
+  const filePath = path30.join(workspaceRoot, WORKSPACE_FILE);
+  const text = await readText(filePath);
+  if (text === void 0) return void 0;
+  const config = parseWorkspaceConfig(text);
+  if (!config) throw new MemberConfigError(filePath, "malformed YAML or invalid shape");
+  return config.repos.map((repo) => ({
+    id: repo.name,
+    folder: repo.path,
+    absPath: resolveAbsPath(workspaceRoot, repo.path, overrides),
+    source: "haus.workspace.yaml"
+  }));
+}
+async function readFromManifest(workspaceRoot, overrides) {
+  const filePath = path30.join(workspaceRoot, REPOS_MANIFEST_FILE);
+  const result = await readJsonDetailed(filePath);
+  if (result.status === "missing") return void 0;
+  if (result.status === "invalid") throw new MemberConfigError(filePath, "invalid JSON");
+  const parsed = result.value;
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new MemberConfigError(filePath, 'expected a top-level object with a "repos" array');
+  }
+  const raw = parsed.repos;
+  if (!Array.isArray(raw)) {
+    throw new MemberConfigError(filePath, '"repos" must be an array');
+  }
+  const members = [];
+  raw.forEach((entry, index) => {
+    if (typeof entry !== "object" || entry === null || typeof entry.id !== "string" || typeof entry.folder !== "string") {
+      throw new MemberConfigError(
+        filePath,
+        `repos[${index}] must be an object with string "id" and "folder" fields`
+      );
+    }
+    const e = entry;
+    members.push({
+      id: e.id,
+      folder: e.folder,
+      url: typeof e.repo === "string" ? e.repo : void 0,
+      absPath: resolveAbsPath(workspaceRoot, e.folder, overrides),
+      source: "repos.manifest.json"
+    });
+  });
+  return members;
+}
+async function readMembers(rootInfo) {
+  const workspaceRoot = rootInfo.mainRoot;
+  const overrides = await readPathOverrides(workspaceRoot);
+  const fromYaml = await readFromWorkspaceYaml(workspaceRoot, overrides);
+  if (fromYaml) return fromYaml;
+  const fromManifest = await readFromManifest(workspaceRoot, overrides);
+  if (fromManifest) return fromManifest;
+  return [];
+}
 
 // src/scanner/scan-project.ts
-import path31 from "node:path";
+import path35 from "node:path";
 
 // src/utils/audit-checks.ts
 function isRecord(v) {
   return typeof v === "object" && v !== null;
 }
 
+// src/utils/git-root.ts
+init_exec();
+import path31 from "node:path";
+function fallback(start) {
+  return {
+    cwd: start,
+    repoRoot: start,
+    gitDir: "",
+    gitCommonDir: "",
+    isLinkedWorktree: false,
+    mainRoot: start,
+    worktreeName: null,
+    isGitRepo: false
+  };
+}
+async function resolveAbsoluteGitPath(flag, cwd, repoRoot) {
+  const withFormat = await runGit(["rev-parse", "--path-format=absolute", flag], { cwd });
+  const raw = withFormat.exitCode === 0 ? withFormat.stdout.trim() : "";
+  if (raw && path31.isAbsolute(raw)) return path31.resolve(raw);
+  const plain = await runGit(["rev-parse", flag], { cwd });
+  const plainRaw = plain.exitCode === 0 ? plain.stdout.trim() : "";
+  if (!plainRaw) return "";
+  return path31.isAbsolute(plainRaw) ? path31.resolve(plainRaw) : path31.resolve(repoRoot, plainRaw);
+}
+async function resolveRoots(start) {
+  const cwd = start ?? process.cwd();
+  try {
+    const toplevel = await runGit(["rev-parse", "--show-toplevel"], { cwd });
+    if (toplevel.exitCode !== 0) return fallback(cwd);
+    const toplevelRaw = toplevel.stdout.trim();
+    if (!toplevelRaw) return fallback(cwd);
+    const repoRoot = path31.resolve(toplevelRaw);
+    const [gitDir, gitCommonDir] = await Promise.all([
+      resolveAbsoluteGitPath("--git-dir", cwd, repoRoot),
+      resolveAbsoluteGitPath("--git-common-dir", cwd, repoRoot)
+    ]);
+    if (!gitDir || !gitCommonDir) return fallback(cwd);
+    const isLinkedWorktree = gitDir !== gitCommonDir;
+    const mainRoot = isLinkedWorktree && path31.basename(gitCommonDir) === ".git" ? path31.dirname(gitCommonDir) : repoRoot;
+    const worktreeName = isLinkedWorktree ? path31.basename(gitDir) : null;
+    return {
+      cwd,
+      repoRoot,
+      gitDir,
+      gitCommonDir,
+      isLinkedWorktree,
+      mainRoot,
+      worktreeName,
+      isGitRepo: true
+    };
+  } catch {
+    return fallback(cwd);
+  }
+}
+
 // src/utils/versions.ts
 import semver from "semver";
 function normalizeVersion(version) {
@@ -4255,8 +4681,8 @@ function compareVersions(a, b) {
 }
 
 // src/scanner/detect-package-manager.ts
-import path28 from "node:path";
-import fs26 from "fs-extra";
+import path32 from "node:path";
+import fs27 from "fs-extra";
 function detectPackageManager(root, packageManagerField) {
   const field = String(packageManagerField ?? "").trim();
   if (field.startsWith("yarn@")) {
@@ -4274,9 +4700,9 @@ function detectPackageManager(root, packageManagerField) {
     if (satisfiesVersion(version, ">=9")) return "npm";
     return "unknown";
   }
-  if (fs26.existsSync(path28.join(root, "yarn.lock"))) return "yarn";
-  if (fs26.existsSync(path28.join(root, "pnpm-lock.yaml"))) return "pnpm";
-  if (fs26.existsSync(path28.join(root, "package-lock.json"))) return "npm";
+  if (fs27.existsSync(path32.join(root, "yarn.lock"))) return "yarn";
+  if (fs27.existsSync(path32.join(root, "pnpm-lock.yaml"))) return "pnpm";
+  if (fs27.existsSync(path32.join(root, "package-lock.json"))) return "npm";
   return "unknown";
 }
 
@@ -4346,6 +4772,14 @@ function matchRule(rule, ctx) {
   return false;
 }
 var ROLE_RULES = [
+  // Workspace/meta-repo root — same bridge signal `readMembers()`/
+  // `resolveWorkspaceForWorktree()` already use (src/workspace/members.ts,
+  // src/workspace/worktree/root.ts): presence of either config file marks this
+  // root as a workspace aggregating sibling repos, not a runnable app of its own.
+  // `fileEquals` only matches the file at the scan root (not nested under a
+  // sub-repo, which the nested-`.git` boundary excludes from `files` anyway) —
+  // see Task 3.5, docs/plans/workspace-detection-and-permissions-fixes.md.
+  { role: "workspace", any: [fileEquals(WORKSPACE_FILE), fileEquals(REPOS_MANIFEST_FILE)] },
   { role: "next-app", any: [dep("next"), fileIncludes("next.config.")] },
   { role: "react-app", any: [dep("react")] },
   { role: "vite-app", any: [dep("vite"), fileIncludes("vite.config.")] },
@@ -4478,7 +4912,7 @@ function runDetection(ctx, rules = STACK_RULES) {
 }
 
 // src/scanner/detection.ts
-import path29 from "node:path";
+import path33 from "node:path";
 var UNSUPPORTED_MARKERS = {
   "requirements.txt": "python",
   "pyproject.toml": "python",
@@ -4498,6 +4932,12 @@ function computeDetectionStatus(roles, stacks, unsupportedSignals) {
   if (!hasRealSignal) return "unknown";
   return unsupportedSignals.length > 0 ? "partial" : "supported";
 }
+function describeUnknownDetection(unsupportedSignals, isLinkedWorktree) {
+  const markers = unsupportedSignals.join(", ");
+  const base = markers ? `Stack not recognised \u2014 detected ${markers}, which haus does not support.` : "Stack not recognised \u2014 no supported framework detected.";
+  const worktreeNote = isLinkedWorktree ? "You're running from inside a git worktree \u2014 sibling repos may not be on disk here, so this could be a false zero-signal reading rather than truly no stack." : "";
+  return [base, worktreeNote, "Only stack-agnostic workflow and security guidance is applied."].filter(Boolean).join(" ");
+}
 function blocked(rel) {
   return SENSITIVE_PATH_REGEXES.some((x) => x.test(rel));
 }
@@ -4532,14 +4972,14 @@ function finalizeRoles(registryRoles, deps, files) {
 function collectUnsupportedSignals(files) {
   return [
     ...new Set(
-      files.map((f) => UNSUPPORTED_MARKERS[path29.basename(f)]).filter((s) => Boolean(s))
+      files.map((f) => UNSUPPORTED_MARKERS[path33.basename(f)]).filter((s) => Boolean(s))
     )
   ].sort();
 }
 
 // src/scanner/render.ts
 import { readFile } from "node:fs/promises";
-import path30 from "node:path";
+import path34 from "node:path";
 async function buildContentBlob(root, files) {
   const candidates = files.filter(
     (f) => f.endsWith(".ts") || f.endsWith(".js") || f.endsWith(".php") || f.endsWith(".json") || f.endsWith(".yml") || f.endsWith(".yaml")
@@ -4547,7 +4987,7 @@ async function buildContentBlob(root, files) {
   const slice = candidates.slice(0, 300);
   const parts = await mapWithConcurrency(slice, async (rel) => {
     try {
-      return await readFile(path30.join(root, rel), "utf8");
+      return await readFile(path34.join(root, rel), "utf8");
     } catch {
       return "";
     }
@@ -4594,6 +5034,11 @@ var SAFE_FILES = [
   "pnpm-lock.yaml",
   "composer.json",
   "composer.lock",
+  // Workspace/meta-repo root markers — presence only, drives the 'workspace' role
+  // (src/scanner/detection-registry.ts). Same files resolveWorkspaceForWorktree()
+  // and readMembers() already treat as the workspace-root signal.
+  WORKSPACE_FILE,
+  REPOS_MANIFEST_FILE,
   "nx.json",
   "turbo.json",
   "tsconfig.json",
@@ -4634,8 +5079,8 @@ var SAFE_FILES = [
   "Gemfile"
 ];
 async function scanProject(root) {
-  const pkg = await readJson(path31.join(root, "package.json"));
-  const composer = await readJson(path31.join(root, "composer.json"));
+  const pkg = await readJson(path35.join(root, "package.json"));
+  const composer = await readJson(path35.join(root, "composer.json"));
   const files = await listFiles(root, SAFE_FILES);
   const safeFiles = files.filter((f) => !blocked(f));
   const deps = dependencySet(pkg, composer);
@@ -4659,10 +5104,10 @@ async function scanProject(root) {
     crossRepoHints.push("Monorepo orchestration detected");
   const unsupportedSignals = collectUnsupportedSignals(safeFiles);
   const detectionStatus = computeDetectionStatus(roles, stacks, unsupportedSignals);
+  const repoNameFallback = pkg?.name ? String(pkg.name) : path35.basename((await resolveRoots(root)).mainRoot);
   const context = {
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    root,
-    repoName: String(pkg?.name ?? path31.basename(root)),
+    repoName: repoNameFallback,
     packageManager,
     repoRoles: roles,
     detectedStacks: stacks,
@@ -4680,10 +5125,18 @@ async function scanProject(root) {
 
 // src/scanner/read-context.ts
 async function isCacheFresh(root, cachePath) {
-  const pkgJsonPath = path32.join(root, "package.json");
-  if (!await fs27.pathExists(pkgJsonPath)) return true;
-  const [cacheStat, pkgStat] = await Promise.all([fs27.stat(cachePath), fs27.stat(pkgJsonPath)]);
-  return cacheStat.mtimeMs >= pkgStat.mtimeMs;
+  const markerPaths = [
+    path36.join(root, "package.json"),
+    path36.join(root, WORKSPACE_FILE),
+    path36.join(root, REPOS_MANIFEST_FILE)
+  ];
+  const cacheStat = await fs28.stat(cachePath);
+  for (const markerPath of markerPaths) {
+    if (!await fs28.pathExists(markerPath)) continue;
+    const markerStat = await fs28.stat(markerPath);
+    if (markerStat.mtimeMs > cacheStat.mtimeMs) return false;
+  }
+  return true;
 }
 async function readContextOrScan(root) {
   const cachePath = hausPath(root, "context-map.json");
@@ -4781,7 +5234,7 @@ async function runDoctor(options) {
   } else {
     ok(`- HOOKS OK: ${hooks.message}`);
   }
-  const rootClaudeMdPath = path33.join(root, "CLAUDE.md");
+  const rootClaudeMdPath = path37.join(root, "CLAUDE.md");
   const rootClaudeMdContent = await readText(rootClaudeMdPath);
   if (!rootClaudeMdContent) {
     flag(
@@ -4809,7 +5262,7 @@ async function runDoctor(options) {
       const block = rootClaudeMdContent.slice(beginIdx, endIdx + BLOCK_END.length);
       const importTargets = [...block.matchAll(/@\.haus-workflow\/(\S+)/g)].map((m) => m[1]);
       for (const target of importTargets) {
-        if (!await fs28.pathExists(hausPath(root, target))) {
+        if (!await fs29.pathExists(hausPath(root, target))) {
           flag(
             `- CLAUDE.md import: @.haus-workflow/${target} does not resolve (run \`haus apply --write\`)`,
             `A file CLAUDE.md links to (${target}) is missing, so part of the guidance won't load`,
@@ -4820,7 +5273,7 @@ async function runDoctor(options) {
     }
   }
   const workflowPath = hausPath(root, "WORKFLOW.md");
-  const workflowExists = await fs28.pathExists(workflowPath);
+  const workflowExists = await fs29.pathExists(workflowPath);
   if (!workflowExists) {
     flag(
       "- .haus-workflow/WORKFLOW.md: missing (run `haus apply --write`)",
@@ -4835,15 +5288,15 @@ async function runDoctor(options) {
     } else {
       const storedHashMatch = firstLine.match(/hash=(sha256-[a-f0-9]+)/);
       const bodyContent = workflowContent.slice(firstLine.length + 1);
-      const cachePath = path33.join(getCacheDir(), "templates/agentic-workflow-standard.md");
-      const bundledPath = path33.join(
+      const cachePath = path37.join(getCacheDir(), "templates/agentic-workflow-standard.md");
+      const bundledPath = path37.join(
         packageRoot(),
         "library",
         "global",
         "templates",
         "agentic-workflow-standard.md"
       );
-      const templatePath = await fs28.pathExists(cachePath) ? cachePath : bundledPath;
+      const templatePath = await fs29.pathExists(cachePath) ? cachePath : bundledPath;
       const templateContent = await readText(templatePath);
       const verdict = checkManagedTamper(bodyContent, storedHashMatch?.[1], templateContent ?? null);
       if (verdict.status === "tampered" || verdict.status === "legacy-diverged") {
@@ -4864,7 +5317,7 @@ async function runDoctor(options) {
     }
   }
   const workflowConfigPath = hausPath(root, "workflow-config.md");
-  const workflowConfigExists = await fs28.pathExists(workflowConfigPath);
+  const workflowConfigExists = await fs29.pathExists(workflowConfigPath);
   if (!workflowConfigExists) {
     flag(
       "- .haus-workflow/workflow-config.md: missing (run `haus apply --write`)",
@@ -4872,7 +5325,7 @@ async function runDoctor(options) {
       "haus apply --write"
     );
   } else {
-    const cfg = await fs28.readFile(workflowConfigPath, "utf8");
+    const cfg = await fs29.readFile(workflowConfigPath, "utf8");
     const unfilled = cfg.split("\n").filter((l) => l.includes("<!-- fill in")).length;
     if (unfilled > 0) {
       suggest(
@@ -4885,7 +5338,7 @@ async function runDoctor(options) {
     }
   }
   if (workflowExists) {
-    const prettierIgnore = await readText(path33.join(root, ".prettierignore")) ?? "";
+    const prettierIgnore = await readText(path37.join(root, ".prettierignore")) ?? "";
     const lines = prettierIgnore.split("\n");
     const missing = IGNORED_PATHS.filter((p) => !prettierIgnoreProtects(lines, p));
     if (missing.length > 0) {
@@ -4898,6 +5351,29 @@ async function runDoctor(options) {
       ok(`- .prettierignore: protects ${IGNORED_PATHS.join(" and ")}`);
     }
   }
+  const trackedArtifacts = await listTrackedArtifactPaths(root);
+  if (trackedArtifacts.length > 0) {
+    flag(
+      `- GITIGNORE: ${trackedArtifacts.length} machine-local scan artifact(s) still tracked in git (${trackedArtifacts.join(", ")})`,
+      `${trackedArtifacts.length} machine-local scan artifact(s) are still tracked in git`,
+      `git rm --cached ${trackedArtifacts.join(" ")} (or run \`haus apply --write\` to do this and update .gitignore for you)`
+    );
+  } else {
+    ok("- GITIGNORE: OK (no machine-local scan artifacts tracked in git)");
+  }
+  const gitignoredHausPaths = await findGitignoredHausPaths(root);
+  if (gitignoredHausPaths.length > 0) {
+    const dirs = summarizeGitignoredHausDirs(gitignoredHausPaths);
+    const dirList = dirs.join(" and ");
+    const verb = dirs.length === 1 ? "is" : "are";
+    flag(
+      `- GITIGNORE (haus content): ${dirList} ${verb} gitignored \u2014 installed skills/agents/commands will not be visible to anything relying on git-tracked state`,
+      `${dirList} ${verb} gitignored, so haus-installed content isn't visible to git-tracked state`,
+      "remove the covering .gitignore rule (only settings.json, settings.local.json, and worktrees/ under .claude/ should ever be ignored)"
+    );
+  } else {
+    ok("- GITIGNORE (haus content): OK (.claude/ and .haus-workflow/ are tracked)");
+  }
   for (const finding of await auditDecisionsLayout(root)) {
     if (finding.level === "ok") ok(finding.line);
     else suggest(finding.line, finding.sentence, finding.fix);
@@ -4935,7 +5411,7 @@ async function runDoctor(options) {
       );
     }
   }
-  const pkgJson = await readJson(path33.join(packageRoot(), "package.json"));
+  const pkgJson = await readJson(path37.join(packageRoot(), "package.json"));
   const currentVersion = pkgJson?.version ?? "0.0.0";
   const npmStatus = await fetchNpmVersionStatus(currentVersion);
   if (npmStatus.updateAvailable && npmStatus.latest !== null) {
@@ -4968,12 +5444,12 @@ async function runDoctor(options) {
 }
 
 // src/commands/update.ts
-import path36 from "node:path";
+import path40 from "node:path";
 
 // src/claude/refresh-project.ts
-import fs29 from "fs-extra";
+import fs30 from "fs-extra";
 async function isHausProject(root) {
-  if (await fs29.pathExists(hausPath(root, "recommendation.json"))) return true;
+  if (await fs30.pathExists(hausPath(root, "recommendation.json"))) return true;
   const result = await readJsonDetailed(claudePath(root, "settings.json"));
   if (result.status === "ok") return result.value._haus != null;
   return false;
@@ -4985,8 +5461,8 @@ async function refreshProjectApply(root) {
 
 // src/install/apply.ts
 import crypto2 from "node:crypto";
-import path34 from "node:path";
-import fs30 from "fs-extra";
+import path38 from "node:path";
+import fs31 from "fs-extra";
 
 // src/install/header.ts
 var MD_PREFIX = "<!-- HAUS-MANAGED";
@@ -5072,57 +5548,57 @@ function hashContent(content2) {
 }
 function sourceVersion() {
   try {
-    const pkgPath = path34.join(packageRoot(), "package.json");
-    const pkg = JSON.parse(fs30.readFileSync(pkgPath, "utf8"));
+    const pkgPath = path38.join(packageRoot(), "package.json");
+    const pkg = JSON.parse(fs31.readFileSync(pkgPath, "utf8"));
     return `${pkg.name ?? "haus"}@${pkg.version ?? "0.0.0"}`;
   } catch {
     return "haus@0.0.0";
   }
 }
 function globalSrcDir() {
-  return path34.join(packageRoot(), "library", "global");
+  return path38.join(packageRoot(), "library", "global");
 }
 function collectSkillAuxFiles(skillsDir, claudeDir, skillName) {
-  const skillDir = path34.join(skillsDir, skillName);
+  const skillDir = path38.join(skillsDir, skillName);
   const entries = [];
-  for (const rel of fs30.readdirSync(skillDir, { recursive: true })) {
+  for (const rel of fs31.readdirSync(skillDir, { recursive: true })) {
     if (rel === "SKILL.md") continue;
-    const abs = path34.join(skillDir, rel);
-    if (!fs30.statSync(abs).isFile()) continue;
-    const posixRel = rel.split(path34.sep).join("/");
+    const abs = path38.join(skillDir, rel);
+    if (!fs31.statSync(abs).isFile()) continue;
+    const posixRel = rel.split(path38.sep).join("/");
     entries.push({
       stableId: `skill.${skillName}.${posixRel.replace(/\//g, ".")}`,
-      srcRelPath: path34.join("library", "global", "skills", skillName, rel),
-      destPath: path34.join(claudeDir, "skills", skillName, rel)
+      srcRelPath: path38.join("library", "global", "skills", skillName, rel),
+      destPath: path38.join(claudeDir, "skills", skillName, rel)
     });
   }
   return entries;
 }
 function collectSourceFiles(srcDir, claudeDir) {
   const entries = [];
-  const skillsDir = path34.join(srcDir, "skills");
-  if (fs30.pathExistsSync(skillsDir)) {
-    for (const skillName of fs30.readdirSync(skillsDir)) {
-      const skillFile = path34.join(skillsDir, skillName, "SKILL.md");
-      if (fs30.pathExistsSync(skillFile)) {
+  const skillsDir = path38.join(srcDir, "skills");
+  if (fs31.pathExistsSync(skillsDir)) {
+    for (const skillName of fs31.readdirSync(skillsDir)) {
+      const skillFile = path38.join(skillsDir, skillName, "SKILL.md");
+      if (fs31.pathExistsSync(skillFile)) {
         entries.push({
           stableId: `skill.${skillName}`,
-          srcRelPath: path34.join("library", "global", "skills", skillName, "SKILL.md"),
-          destPath: path34.join(claudeDir, "skills", skillName, "SKILL.md")
+          srcRelPath: path38.join("library", "global", "skills", skillName, "SKILL.md"),
+          destPath: path38.join(claudeDir, "skills", skillName, "SKILL.md")
         });
         entries.push(...collectSkillAuxFiles(skillsDir, claudeDir, skillName));
       }
     }
   }
-  const commandsDir = path34.join(srcDir, "commands");
-  if (fs30.pathExistsSync(commandsDir)) {
-    for (const fileName of fs30.readdirSync(commandsDir)) {
+  const commandsDir = path38.join(srcDir, "commands");
+  if (fs31.pathExistsSync(commandsDir)) {
+    for (const fileName of fs31.readdirSync(commandsDir)) {
       if (!fileName.endsWith(".md")) continue;
       const commandName = fileName.slice(0, -".md".length);
       entries.push({
         stableId: `command.${commandName}`,
-        srcRelPath: path34.join("library", "global", "commands", fileName),
-        destPath: path34.join(claudeDir, "commands", fileName)
+        srcRelPath: path38.join("library", "global", "commands", fileName),
+        destPath: path38.join(claudeDir, "commands", fileName)
       });
     }
   }
@@ -5148,7 +5624,7 @@ async function applyInstall(options = {}) {
   };
   const manifestFiles = [];
   for (const entry of sourceFiles) {
-    const srcPath = path34.join(packageRoot(), entry.srcRelPath);
+    const srcPath = path38.join(packageRoot(), entry.srcRelPath);
     const rawContent = await readText(srcPath);
     if (rawContent === void 0) {
       warn(`Source file not found: ${entry.srcRelPath}`);
@@ -5168,7 +5644,7 @@ async function applyInstall(options = {}) {
       }
       continue;
     }
-    const destExists = fs30.pathExistsSync(entry.destPath);
+    const destExists = fs31.pathExistsSync(entry.destPath);
     if (destExists) {
       const currentContent = await readText(entry.destPath);
       if (currentContent !== void 0) {
@@ -5208,7 +5684,7 @@ async function applyInstall(options = {}) {
   }
   let mergedSettings;
   if (!check) {
-    const fragmentPath = path34.join(srcDir, "settings-fragments", "hooks.json");
+    const fragmentPath = path38.join(srcDir, "settings-fragments", "hooks.json");
     const fragments = await loadHooksFragment(fragmentPath);
     const settings = await readSettings();
     const { settings: hookSettings, addedIds } = mergeHooks(settings, fragments);
@@ -5222,13 +5698,13 @@ async function applyInstall(options = {}) {
     const currentDestPaths = new Set(sourceFiles.map((f) => f.destPath));
     for (const entry of existingManifest.files) {
       if (currentDestPaths.has(entry.destPath)) continue;
-      if (!fs30.pathExistsSync(entry.destPath)) continue;
+      if (!fs31.pathExistsSync(entry.destPath)) continue;
       const content2 = await readText(entry.destPath);
       if (!content2) continue;
       const hasHeader = parseMarkdownHeader(content2) !== void 0;
       const currentHash = hashContent(content2);
       if (hasHeader && currentHash === entry.hash) {
-        if (!dryRun) await fs30.remove(entry.destPath);
+        if (!dryRun) await fs31.remove(entry.destPath);
         result.deleted.push(entry.destPath);
       } else {
         warn(`Orphaned file ${entry.destPath} was user-modified \u2014 leaving in place`);
@@ -5297,7 +5773,7 @@ function summarizeLockDiff(before, after) {
 
 // src/update/lockfile.ts
 import { mkdir, readFile as readFile2, copyFile } from "node:fs/promises";
-import path35 from "node:path";
+import path39 from "node:path";
 async function readLockSummary(root) {
   const lock = await readJson(hausPath(root, "haus.lock.json")) ?? [];
   const catalogRef = lock.find((item) => item.catalogRef)?.catalogRef ?? null;
@@ -5333,7 +5809,7 @@ async function applyLock(root) {
   try {
     const backupDir = hausPath(root, "backups");
     await mkdir(backupDir, { recursive: true });
-    await copyFile(lockPath, path35.join(backupDir, `haus.lock.${Date.now()}.json`));
+    await copyFile(lockPath, path39.join(backupDir, `haus.lock.${Date.now()}.json`));
   } catch {
   }
   const enriched = await Promise.all(
@@ -5355,7 +5831,7 @@ function diffLock(before, after) {
 }
 async function hasLocalOverrides(root) {
   try {
-    await readFile2(path35.join(root, ".claude", "settings.json"), "utf8");
+    await readFile2(path39.join(root, ".claude", "settings.json"), "utf8");
     return true;
   } catch {
     return false;
@@ -5371,7 +5847,7 @@ async function runUpdate(options) {
     return;
   }
   if (options.check) {
-    const pkgJson2 = await readJson(path36.join(packageRoot(), "package.json"));
+    const pkgJson2 = await readJson(path40.join(packageRoot(), "package.json"));
     const currentVersion2 = pkgJson2?.version ?? "0.0.0";
     const [status, npmVersion, latestCatalogTag, globalInstallDrift, catalogItems, lockItems] = await Promise.all([
       options.fast ? fastLockStatus(root) : checkLock(root),
@@ -5406,7 +5882,7 @@ async function runUpdate(options) {
     if (hasHashDrift || formerIdMigrations.length > 0) process.exitCode = 1;
     return;
   }
-  const pkgJson = await readJson(path36.join(packageRoot(), "package.json"));
+  const pkgJson = await readJson(path40.join(packageRoot(), "package.json"));
   const currentVersion = pkgJson?.version ?? "0.0.0";
   const npmStatus = await fetchNpmVersionStatus(currentVersion);
   if (npmStatus.updateAvailable && npmStatus.latest !== null) {
@@ -5448,7 +5924,7 @@ async function runFromHookCheck(root) {
   try {
     const summary = await readLockSummary(root);
     if (summary.count === 0) return;
-    const pkgJson = await readJson(path36.join(packageRoot(), "package.json"));
+    const pkgJson = await readJson(path40.join(packageRoot(), "package.json"));
     const currentVersion = pkgJson?.version ?? "0.0.0";
     const [npmVersion, latestCatalogTag] = await Promise.all([
       fetchNpmVersionStatus(currentVersion),
@@ -5598,7 +6074,7 @@ async function runCiGate(options = {}) {
 // src/commands/clone.ts
 init_exec();
 import { existsSync as existsSync2 } from "node:fs";
-import path37 from "node:path";
+import path41 from "node:path";
 var GIT_LOCATION_VARS = [
   "GIT_DIR",
   "GIT_WORK_TREE",
@@ -5648,11 +6124,11 @@ async function runClone(url, opts = {}) {
     process.exitCode = 1;
     return;
   }
-  const target = path37.resolve(opts.dir?.trim() || repoNameFromUrl(url));
+  const target = path41.resolve(opts.dir?.trim() || repoNameFromUrl(url));
   if (existsSync2(target)) {
     const check = await checkExistingTarget(target, url);
     if (check.kind === "matches") {
-      log(`\u2022 ${path37.basename(target)} already cloned here, matches ${url} \u2014 skipped`);
+      log(`\u2022 ${path41.basename(target)} already cloned here, matches ${url} \u2014 skipped`);
       return;
     }
     const message = check.kind === "not-a-repo" ? `${target} already exists and is not a git repository \u2014 refusing to clone ${url} there. Remove or rename it, or pass a different [dir].` : `${target} already exists as a different repository (origin: ${check.origin ?? "(no origin remote)"}) \u2014 refusing to clone ${url} there. Remove or rename it, or pass a different [dir].`;
@@ -5762,7 +6238,7 @@ async function runDecisionsGuard(options = {}) {
 }
 
 // src/commands/decisions.ts
-import path38 from "node:path";
+import path42 from "node:path";
 
 // src/decisions/next-number.ts
 async function nextDecisionNumber(root) {
@@ -5873,7 +6349,7 @@ async function runDecisions(sub, arg, options = {}) {
     return;
   }
   if (sub === "validate") {
-    const target = arg ? path38.resolve(root, arg) : void 0;
+    const target = arg ? path42.resolve(root, arg) : void 0;
     if (!target) {
       error("usage: haus decisions validate <path-to-decision.md>");
       process.exitCode = 1;
@@ -6142,8 +6618,8 @@ async function runGuard(kind, _options) {
 }
 
 // src/commands/init.ts
-import path39 from "node:path";
-import fs31 from "fs-extra";
+import path44 from "node:path";
+import fs32 from "fs-extra";
 
 // src/recommender/git-signal.ts
 init_exec();
@@ -6206,11 +6682,9 @@ function describeRequiresAny(clauses) {
     return "unknown";
   }).join(" | ");
 }
-function mergeRecommendationWarnings(context) {
+function mergeRecommendationWarnings(context, isLinkedWorktree = false) {
   const markers = context.unsupportedSignals?.join(", ");
-  const statusLines = context.detectionStatus === "unknown" ? [
-    markers ? `Stack not recognised \u2014 detected ${markers}, which haus does not support. Only stack-agnostic workflow and security guidance is applied.` : "Stack not recognised \u2014 no supported framework detected. Only stack-agnostic workflow and security guidance is applied."
-  ] : context.detectionStatus === "partial" && markers ? [
+  const statusLines = context.detectionStatus === "unknown" ? [describeUnknownDetection(context.unsupportedSignals ?? [], isLinkedWorktree)] : context.detectionStatus === "partial" && markers ? [
     `Partially supported \u2014 found unsupported ${markers} alongside recognised stacks; guidance covers the supported parts only.`
   ] : [];
   const riskLines = (context.securityRisks?.length ?? 0) > 0 ? [`Scan reported security signals: ${context.securityRisks.join("; ")}`] : [];
@@ -6429,11 +6903,12 @@ async function recommend(root, context, opts = {}) {
   const skippedRules = skipped.length;
   const estimatedContextTokens = estimateContextTokens(selectedRules);
   const estimatedTokenReductionPct = tokenReductionPct(selectedRules, skippedRules);
+  const { isLinkedWorktree } = await resolveRoots(root);
   return {
     recommended,
     skipped,
     optInEligible,
-    warnings: [...mergeRecommendationWarnings(context), ...includeWarnings],
+    warnings: [...mergeRecommendationWarnings(context, isLinkedWorktree), ...includeWarnings],
     estimatedContextTokens,
     selectedRules,
     skippedRules,
@@ -6610,9 +7085,162 @@ function buildOptInEligible(items, skipped) {
   return eligible;
 }
 
+// src/commands/workspace/discover.ts
+import path43 from "node:path";
+import fg4 from "fast-glob";
+import YAML2 from "yaml";
+var DEFAULT_MAX_DEPTH = 3;
+var GIT_MARKER = ["**/.git"];
+var MANIFEST_MARKERS = [
+  "**/package.json",
+  "**/composer.json",
+  "**/*.csproj",
+  "**/*.sln",
+  "**/*.fsproj",
+  // .NET
+  "**/pom.xml",
+  "**/build.gradle*",
+  // Java
+  "**/Gemfile"
+  // Ruby
+];
+var IGNORE = ["**/node_modules/**", "**/vendor/**", "**/dist/**", "**/.haus-workflow/**"];
+function isDescendant(child, ancestor) {
+  if (ancestor === ".") return child !== ".";
+  return child === ancestor ? false : child.startsWith(`${ancestor}/`);
+}
+async function findRepoRoots(workspaceRoot, maxDepth = DEFAULT_MAX_DEPTH) {
+  const commonOpts = {
+    cwd: workspaceRoot,
+    dot: true,
+    onlyFiles: false,
+    deep: maxDepth,
+    followSymbolicLinks: false,
+    // Discovery walks arbitrary directories under the workspace root; an
+    // unreadable subtree (EPERM/EACCES) must be skipped, not abort the whole scan.
+    suppressErrors: true
+  };
+  const [gitMatches, manifestMatches] = await Promise.all([
+    fg4(GIT_MARKER, { ...commonOpts, ignore: IGNORE }),
+    fg4(MANIFEST_MARKERS, { ...commonOpts, ignore: [...IGNORE, "**/.git/**"] })
+  ]);
+  const gitDirs = /* @__PURE__ */ new Set();
+  const manifestDirs = /* @__PURE__ */ new Set();
+  for (const match of gitMatches) {
+    gitDirs.add(path43.posix.dirname(match));
+  }
+  for (const match of manifestMatches) {
+    manifestDirs.add(path43.posix.dirname(match));
+  }
+  const repoRoots = [...gitDirs];
+  const manifestSorted = [...manifestDirs].sort(
+    (a, b) => a.split("/").length - b.split("/").length || a.localeCompare(b)
+  );
+  for (const dir of manifestSorted) {
+    if (gitDirs.has(dir)) continue;
+    if (repoRoots.some((root) => isDescendant(dir, root))) continue;
+    repoRoots.push(dir);
+  }
+  repoRoots.sort((a, b) => a.localeCompare(b));
+  return repoRoots;
+}
+async function discoverRepos(workspaceRoot, maxDepth = DEFAULT_MAX_DEPTH) {
+  const repoRoots = await findRepoRoots(workspaceRoot, maxDepth);
+  return mapWithConcurrency(repoRoots, async (relDir) => {
+    const absDir = path43.resolve(workspaceRoot, relDir);
+    const pkg = await readJson(path43.join(absDir, "package.json"));
+    const name = typeof pkg?.name === "string" && pkg.name.length > 0 ? pkg.name : path43.basename(relDir === "." ? workspaceRoot : absDir);
+    let role = "auto";
+    try {
+      const scan = await scanProject(absDir);
+      if (scan.repoRoles.length > 0) role = scan.repoRoles.join("+");
+    } catch {
+    }
+    return { name, path: relDir === "." ? "." : relDir, role };
+  });
+}
+function mergeWorkspaceConfig(existing, discovered, opts = {}) {
+  const existingRepos = existing?.repos ?? [];
+  const byPath = new Map(existingRepos.map((r) => [r.path, r]));
+  for (const repo of discovered) {
+    if (!byPath.has(repo.path)) {
+      byPath.set(repo.path, { name: repo.name, path: repo.path, role: repo.role });
+    }
+  }
+  const ordered = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const repo of existingRepos) {
+    ordered.push(byPath.get(repo.path));
+    seen.add(repo.path);
+  }
+  for (const repo of discovered) {
+    if (seen.has(repo.path)) continue;
+    ordered.push(byPath.get(repo.path));
+    seen.add(repo.path);
+  }
+  return {
+    client: opts.client ?? existing?.client ?? "unknown",
+    repos: ordered,
+    relationships: existing?.relationships ?? []
+  };
+}
+function renderWorkspaceYaml(config) {
+  return YAML2.stringify({
+    client: config.client,
+    repos: config.repos.map((r) => ({ name: r.name, path: r.path, role: r.role ?? "auto" })),
+    relationships: config.relationships
+  });
+}
+async function runDiscover(workspaceRoot, opts = {}) {
+  const yamlPath = path43.join(workspaceRoot, "haus.workspace.yaml");
+  const existingText = await readText(yamlPath);
+  const existing = parseWorkspaceConfig(existingText);
+  if (existingText && !existing) {
+    error(
+      "Existing haus.workspace.yaml is malformed \u2014 fix or remove it before running discover (refusing to overwrite)."
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const discovered = await discoverRepos(workspaceRoot, opts.maxDepth ?? DEFAULT_MAX_DEPTH);
+  if (discovered.length === 0) {
+    error("No repos discovered under the workspace root.");
+    process.exitCode = 1;
+    return;
+  }
+  const merged = mergeWorkspaceConfig(existing, discovered, { client: opts.client });
+  const yamlText = renderWorkspaceYaml(merged);
+  if (opts.write) {
+    await writeText(yamlPath, yamlText);
+    if (opts.json) {
+      log(JSON.stringify({ discovered, config: merged, wrote: yamlPath }, null, 2));
+    } else {
+      log(`Wrote ${merged.repos.length} repo(s) to haus.workspace.yaml`);
+    }
+    return;
+  }
+  if (opts.json) {
+    log(JSON.stringify({ discovered, config: merged }, null, 2));
+    return;
+  }
+  log("Proposed haus.workspace.yaml (run with --write to persist):\n");
+  log(yamlText);
+}
+
+// src/scanner/sibling-repos.ts
+var SIBLING_REPO_WARNING = 'Multiple sibling repos detected under this root \u2014 consider "haus workspace discover" instead of running setup-project/scan per repo.';
+async function hasMultipleSiblingRepos(root) {
+  try {
+    const repoRoots = await findRepoRoots(root);
+    return repoRoots.filter((relDir) => relDir !== ".").length >= 2;
+  } catch {
+    return false;
+  }
+}
+
 // src/claude/setup-core.ts
 async function runSetupCore(root, opts) {
-  const { json, apply, dryRun, quiet, confirm: confirm2 } = opts;
+  const { json, apply, dryRun, quiet, confirm: confirm2, force } = opts;
   const say = quiet ? () => {
   } : log;
   const scanResult = await scanProject(root);
@@ -6623,8 +7251,35 @@ async function runSetupCore(root, opts) {
     say(`Roles: ${scanResult.repoRoles.join(", ") || "unknown"}`);
     say(`Package manager: ${scanResult.packageManager}`);
   }
+  const siblingWarning = await hasMultipleSiblingRepos(root) ? [SIBLING_REPO_WARNING] : [];
   const context = await readContextOrScan(root);
   const recommendation = await recommend(root, context);
+  if (recommendation.recommended.length === 0 && !force) {
+    const warningLines2 = [
+      .../* @__PURE__ */ new Set([...context.warnings, ...recommendation.warnings ?? [], ...siblingWarning])
+    ];
+    if (json) {
+      say(JSON.stringify(recommendation, null, 2));
+    } else {
+      say("Haus recommendation ready");
+      say("Recommended: 0");
+      say(`Skipped: ${recommendation.skipped.length}`);
+      say(`Repo: ${context.repoName}`);
+      for (const warning of warningLines2) say(`- WARN: ${warning}`);
+    }
+    const message = "No catalog items matched this project at all (zero signal) \u2014 refusing to write recommendation.json/haus.lock.json. Re-run with `haus setup-project --force` to write anyway.";
+    warn(message);
+    process.exitCode = 1;
+    return {
+      root,
+      repoName: context.repoName,
+      roles: scanResult.repoRoles,
+      recommendedCount: 0,
+      warnings: [...warningLines2, message],
+      hooksOk: false,
+      written: []
+    };
+  }
   await writeJson(hausPath(root, "recommendation.json"), recommendation);
   if (json) {
     say(JSON.stringify(recommendation, null, 2));
@@ -6634,7 +7289,9 @@ async function runSetupCore(root, opts) {
     say(`Skipped: ${recommendation.skipped.length}`);
   }
   const hooks = await verifyProjectSettingsHooksContract(root);
-  const warningLines = [.../* @__PURE__ */ new Set([...context.warnings, ...recommendation.warnings ?? []])];
+  const warningLines = [
+    .../* @__PURE__ */ new Set([...context.warnings, ...recommendation.warnings ?? [], ...siblingWarning])
+  ];
   say(`Repo: ${context.repoName}`);
   for (const warning of warningLines) say(`- WARN: ${warning}`);
   const hooksOk = hooks.ok;
@@ -6699,6 +7356,7 @@ async function runSetupProject(options) {
     json: options.json,
     apply: !options.json,
     dryRun: false,
+    force: options.force,
     confirm: () => confirm("Approve and write Claude files now?")
   });
 }
@@ -6706,8 +7364,8 @@ async function runSetupProject(options) {
 // src/commands/init.ts
 async function runInit(options) {
   const root = process.cwd();
-  const hausDir = path39.join(root, ".haus-workflow");
-  const alreadyInit = await fs31.pathExists(hausDir);
+  const hausDir = path44.join(root, ".haus-workflow");
+  const alreadyInit = await fs32.pathExists(hausDir);
   if (alreadyInit) {
     log("Haus AI already initialized in this project.");
     log("Run `haus setup-project` to reconfigure.");
@@ -6842,8 +7500,8 @@ async function runRefresh() {
 }
 
 // src/install/scaffold.ts
-import path40 from "node:path";
-import fs32 from "fs-extra";
+import path45 from "node:path";
+import fs33 from "fs-extra";
 async function scaffoldConfigItems(projectRoot, catalogRoot, items, opts = {}) {
   const scaffolded = [];
   const skipped = [];
@@ -6856,27 +7514,27 @@ async function scaffoldConfigItems(projectRoot, catalogRoot, items, opts = {}) {
     skipped.push(name);
     if (outcome === "skipped-exists") skippedExisting.push(name);
   };
-  const realRoot = await fs32.realpath(catalogRoot).catch(() => null);
+  const realRoot = await fs33.realpath(catalogRoot).catch(() => null);
   for (const item of items) {
     if (item.type !== "config") continue;
-    const sourcePath = path40.resolve(catalogRoot, item.path);
-    const rel = path40.relative(catalogRoot, sourcePath);
-    const escapes = rel === "" || path40.isAbsolute(rel) || rel.split(/[/\\]/).some((seg) => seg === "..");
+    const sourcePath = path45.resolve(catalogRoot, item.path);
+    const rel = path45.relative(catalogRoot, sourcePath);
+    const escapes = rel === "" || path45.isAbsolute(rel) || rel.split(/[/\\]/).some((seg) => seg === "..");
     if (escapes) {
       warn(`Skipping ${item.id}: path '${item.path}' escapes the catalog root`);
       continue;
     }
-    const realSource = await fs32.realpath(sourcePath).catch(() => null);
+    const realSource = await fs33.realpath(sourcePath).catch(() => null);
     if (!realRoot || !realSource) {
       warn(`Skipping ${item.id}: source not found at ${sourcePath}`);
       continue;
     }
-    const realRel = path40.relative(realRoot, realSource);
-    if (realRel !== "" && (path40.isAbsolute(realRel) || realRel.split(/[/\\]/)[0] === "..")) {
+    const realRel = path45.relative(realRoot, realSource);
+    if (realRel !== "" && (path45.isAbsolute(realRel) || realRel.split(/[/\\]/)[0] === "..")) {
       warn(`Skipping ${item.id}: path '${item.path}' resolves outside the catalog root`);
       continue;
     }
-    const stat = await fs32.lstat(sourcePath).catch(() => null);
+    const stat = await fs33.lstat(sourcePath).catch(() => null);
     if (!stat) {
       warn(`Skipping ${item.id}: source not found at ${sourcePath}`);
       continue;
@@ -6886,14 +7544,14 @@ async function scaffoldConfigItems(projectRoot, catalogRoot, items, opts = {}) {
       continue;
     }
     if (stat.isFile()) {
-      const filename = path40.basename(sourcePath);
-      const dest = path40.join(projectRoot, filename);
+      const filename = path45.basename(sourcePath);
+      const dest = path45.join(projectRoot, filename);
       record(filename, await scaffoldFile(sourcePath, dest, item.id, projectRoot, opts));
     } else if (stat.isDirectory()) {
-      const entries = await fs32.readdir(sourcePath);
+      const entries = await fs33.readdir(sourcePath);
       for (const entry of entries) {
-        const src = path40.join(sourcePath, entry);
-        const dest = path40.join(projectRoot, entry);
+        const src = path45.join(sourcePath, entry);
+        const dest = path45.join(projectRoot, entry);
         record(entry, await scaffoldFile(src, dest, item.id, projectRoot, opts));
       }
     }
@@ -6901,42 +7559,42 @@ async function scaffoldConfigItems(projectRoot, catalogRoot, items, opts = {}) {
   return { scaffolded, skipped, skippedExisting };
 }
 async function scaffoldFile(src, dest, itemId, projectRoot, opts) {
-  const destDisplay = path40.relative(projectRoot, dest) || path40.basename(dest);
-  const srcStat = await fs32.lstat(src).catch(() => null);
+  const destDisplay = path45.relative(projectRoot, dest) || path45.basename(dest);
+  const srcStat = await fs33.lstat(src).catch(() => null);
   if (!srcStat) {
-    warn(`Skipping ${path40.basename(src)}: source not found`);
+    warn(`Skipping ${path45.basename(src)}: source not found`);
     return "skipped-refused";
   }
   if (srcStat.isSymbolicLink()) {
-    warn(`Skipping ${path40.basename(src)}: source is a symlink`);
+    warn(`Skipping ${path45.basename(src)}: source is a symlink`);
     return "skipped-refused";
   }
-  const exists = await fs32.pathExists(dest);
+  const exists = await fs33.pathExists(dest);
   if (exists && !opts.force) {
     warn(`Skipping ${destDisplay}: already exists \u2014 re-run with --force to overwrite it`);
     return "skipped-exists";
   }
   if (opts.dryRun) {
-    log(`[dry-run] would ${exists ? "overwrite" : "create"} ${path40.basename(dest)} (${itemId})`);
+    log(`[dry-run] would ${exists ? "overwrite" : "create"} ${path45.basename(dest)} (${itemId})`);
     return "scaffolded";
   }
   if (exists && opts.force) {
-    await fs32.remove(dest);
+    await fs33.remove(dest);
   }
-  await fs32.ensureDir(path40.dirname(dest));
-  await fs32.copy(src, dest, {
+  await fs33.ensureDir(path45.dirname(dest));
+  await fs33.copy(src, dest, {
     overwrite: true,
     dereference: false,
     // A vanished/unreadable entry mid-walk must skip that path, not crash the copy.
     filter: (s) => {
       try {
-        return !fs32.lstatSync(s).isSymbolicLink();
+        return !fs33.lstatSync(s).isSymbolicLink();
       } catch {
         return false;
       }
     }
   });
-  log(`${exists ? "Overwrote" : "Created"} ${path40.basename(dest)} (${itemId})`);
+  log(`${exists ? "Overwrote" : "Created"} ${path45.basename(dest)} (${itemId})`);
   return "scaffolded";
 }
 
@@ -6981,7 +7639,8 @@ async function runScaffold(ids, options) {
 
 // src/commands/scan.ts
 async function runScan(options) {
-  const result = await scanProject(process.cwd());
+  const root = process.cwd();
+  const result = await scanProject(root);
   if (options.json) {
     log(JSON.stringify(result, null, 2));
     return;
@@ -6989,12 +7648,19 @@ async function runScan(options) {
   log("Haus scan complete");
   log(`Roles: ${result.repoRoles.join(", ") || "unknown"}`);
   log(`Package manager: ${result.packageManager}`);
+  if (result.detectionStatus === "unknown") {
+    const { isLinkedWorktree } = await resolveRoots(root);
+    log(`- WARN: ${describeUnknownDetection(result.unsupportedSignals, isLinkedWorktree)}`);
+  }
   for (const w of result.warnings) log(`- WARN: ${w}`);
+  if (await hasMultipleSiblingRepos(root)) {
+    log(`- WARN: ${SIBLING_REPO_WARNING}`);
+  }
 }
 
 // src/commands/undo.ts
-import path41 from "node:path";
-import fs33 from "fs-extra";
+import path46 from "node:path";
+import fs34 from "fs-extra";
 
 // src/claude/managed-paths.ts
 var PROJECT_MANAGED_CLAUDE_REL = ["rules/haus.md"];
@@ -7009,7 +7675,7 @@ function coreManagedAbsolutePaths(root) {
 async function collectCoreManagedPaths(root) {
   const existing = [];
   for (const abs of coreManagedAbsolutePaths(root)) {
-    if (await fs33.pathExists(abs)) existing.push(abs);
+    if (await fs34.pathExists(abs)) existing.push(abs);
   }
   return existing;
 }
@@ -7021,18 +7687,18 @@ async function collectLockTrackedPaths(root) {
     const relPaths = row.paths ?? [];
     const existingRel = [];
     for (const rel of relPaths) {
-      if (await fs33.pathExists(path41.resolve(root, rel))) existingRel.push(rel);
+      if (await fs34.pathExists(path46.resolve(root, rel))) existingRel.push(rel);
     }
     if (existingRel.length === 0) continue;
     if (row.hash === void 0) {
-      removable.push(...existingRel.map((rel) => path41.resolve(root, rel)));
+      removable.push(...existingRel.map((rel) => path46.resolve(root, rel)));
       continue;
     }
     const currentHash = await hashInstalledPaths(root, existingRel);
     if (currentHash === row.hash) {
-      removable.push(...existingRel.map((rel) => path41.resolve(root, rel)));
+      removable.push(...existingRel.map((rel) => path46.resolve(root, rel)));
     } else {
-      preserved.push(...existingRel.map((rel) => path41.resolve(root, rel)));
+      preserved.push(...existingRel.map((rel) => path46.resolve(root, rel)));
       log(`Preserving locally-modified ${row.id ?? "(unknown item)"}: ${existingRel.join(", ")}`);
     }
   }
@@ -7040,51 +7706,51 @@ async function collectLockTrackedPaths(root) {
 }
 async function settingsHasHausContent(root) {
   const settingsPath = claudePath(root, "settings.json");
-  if (!await fs33.pathExists(settingsPath)) return false;
+  if (!await fs34.pathExists(settingsPath)) return false;
   const settings = await readProjectSettings(root);
   return settings._haus != null;
 }
 async function claudeMdHasHausBlock(root) {
-  const filePath = path41.join(root, "CLAUDE.md");
-  if (!await fs33.pathExists(filePath)) return false;
-  const text = await fs33.readFile(filePath, "utf8");
+  const filePath = path46.join(root, "CLAUDE.md");
+  if (!await fs34.pathExists(filePath)) return false;
+  const text = await fs34.readFile(filePath, "utf8");
   return text.includes(BLOCK_BEGIN);
 }
 async function stripProjectSettings(root) {
   const settingsPath = claudePath(root, "settings.json");
-  if (!await fs33.pathExists(settingsPath)) return false;
+  if (!await fs34.pathExists(settingsPath)) return false;
   let settings = await readProjectSettings(root);
   settings = stripHausHooks(stripHausAsk(stripHausAllow(stripHausDeny(settings))));
   const hasContent = Object.keys(settings).length > 0;
   if (hasContent) {
     await writeProjectSettings(root, settings);
-    log(`Stripped haus rules from ${path41.relative(root, settingsPath)} (user settings preserved).`);
+    log(`Stripped haus rules from ${path46.relative(root, settingsPath)} (user settings preserved).`);
     return true;
   }
-  await fs33.remove(settingsPath);
-  log(`Removed ${path41.relative(root, settingsPath)} (no user-owned settings remained).`);
+  await fs34.remove(settingsPath);
+  log(`Removed ${path46.relative(root, settingsPath)} (no user-owned settings remained).`);
   return true;
 }
 async function stripRootClaudeMd(root) {
-  const filePath = path41.join(root, "CLAUDE.md");
-  if (!await fs33.pathExists(filePath)) return false;
-  const prev = await fs33.readFile(filePath, "utf8");
+  const filePath = path46.join(root, "CLAUDE.md");
+  if (!await fs34.pathExists(filePath)) return false;
+  const prev = await fs34.readFile(filePath, "utf8");
   if (!prev.includes(BLOCK_BEGIN)) return false;
   const next = stripHausBlock(prev);
   if (next.length === 0) {
-    await fs33.remove(filePath);
+    await fs34.remove(filePath);
     log("Removed CLAUDE.md (only contained haus import block).");
   } else {
-    await fs33.writeFile(filePath, next, "utf8");
+    await fs34.writeFile(filePath, next, "utf8");
     log("Removed haus import block from CLAUDE.md (user content preserved).");
   }
   return true;
 }
 async function pruneDirIfEmpty(dir) {
-  if (!await fs33.pathExists(dir)) return;
+  if (!await fs34.pathExists(dir)) return;
   try {
-    const entries = await fs33.readdir(dir);
-    if (entries.length === 0) await fs33.remove(dir);
+    const entries = await fs34.readdir(dir);
+    if (entries.length === 0) await fs34.remove(dir);
   } catch {
   }
 }
@@ -7093,13 +7759,13 @@ async function backupManagedFilesBeforeUndo(root, managedAbsPaths) {
   const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
   const backupRoot = hausPath(root, "backups", `undo-${stamp}`);
   for (const abs of managedAbsPaths) {
-    if (!await fs33.pathExists(abs)) continue;
-    const rel = path41.relative(root, abs);
-    const backupPath = path41.join(backupRoot, rel);
-    await fs33.ensureDir(path41.dirname(backupPath));
-    await fs33.copy(abs, backupPath);
+    if (!await fs34.pathExists(abs)) continue;
+    const rel = path46.relative(root, abs);
+    const backupPath = path46.join(backupRoot, rel);
+    await fs34.ensureDir(path46.dirname(backupPath));
+    await fs34.copy(abs, backupPath);
   }
-  log(`Backed up ${managedAbsPaths.length} managed file(s) to ${path41.relative(root, backupRoot)}.`);
+  log(`Backed up ${managedAbsPaths.length} managed file(s) to ${path46.relative(root, backupRoot)}.`);
 }
 async function runUndo(options) {
   const root = options.root ?? process.cwd();
@@ -7112,7 +7778,7 @@ async function runUndo(options) {
     log("Nothing to remove: no haus-managed files found in this directory.");
     return;
   }
-  const relTargets = managed.map((p) => path41.relative(root, p));
+  const relTargets = managed.map((p) => path46.relative(root, p));
   const summaryParts = [...relTargets];
   if (stripSettings) summaryParts.push(".claude/settings.json (haus rules only)");
   if (stripClaudeMd) summaryParts.push("CLAUDE.md (haus import block only)");
@@ -7134,9 +7800,9 @@ User-owned .claude/ files will be preserved.`
   }
   await backupManagedFilesBeforeUndo(root, managed);
   for (const abs of managed) {
-    if (!await fs33.pathExists(abs)) continue;
-    await fs33.remove(abs);
-    log(`Removed ${path41.relative(root, abs)}`);
+    if (!await fs34.pathExists(abs)) continue;
+    await fs34.remove(abs);
+    log(`Removed ${path46.relative(root, abs)}`);
   }
   if (stripSettings) await stripProjectSettings(root);
   if (stripClaudeMd) await stripRootClaudeMd(root);
@@ -7147,8 +7813,8 @@ User-owned .claude/ files will be preserved.`
 
 // src/install/uninstall.ts
 import crypto3 from "node:crypto";
-import path42 from "node:path";
-import fs34 from "fs-extra";
+import path47 from "node:path";
+import fs35 from "fs-extra";
 async function runUninstall(options = {}) {
   const { force = false } = options;
   const manifest = await readManifest();
@@ -7158,7 +7824,7 @@ async function runUninstall(options = {}) {
     return result;
   }
   for (const entry of manifest.files) {
-    const exists = fs34.pathExistsSync(entry.destPath);
+    const exists = fs35.pathExistsSync(entry.destPath);
     if (!exists) continue;
     const content2 = await readText(entry.destPath);
     if (content2 === void 0) continue;
@@ -7176,23 +7842,23 @@ async function runUninstall(options = {}) {
       result.skipped.push(entry.destPath);
       continue;
     }
-    await fs34.remove(entry.destPath);
-    await pruneEmptyDir(path42.dirname(entry.destPath));
+    await fs35.remove(entry.destPath);
+    await pruneEmptyDir(path47.dirname(entry.destPath));
     result.deleted.push(entry.destPath);
   }
   const settings = await readSettings();
   const stripped = stripHausHooks(stripHausAsk(stripHausAllow(stripHausDeny(settings))));
   await writeSettings(stripped);
   result.hooksStripped = true;
-  const hausDir = path42.join(globalClaudeDir(), "haus");
+  const hausDir = path47.join(globalClaudeDir(), "haus");
   const manifestPath2 = hausManifestPath();
-  if (fs34.pathExistsSync(manifestPath2)) {
-    await fs34.remove(manifestPath2);
+  if (fs35.pathExistsSync(manifestPath2)) {
+    await fs35.remove(manifestPath2);
   }
-  if (fs34.pathExistsSync(hausDir)) {
+  if (fs35.pathExistsSync(hausDir)) {
     try {
-      const remaining = await fs34.readdir(hausDir);
-      if (remaining.length === 0) await fs34.remove(hausDir);
+      const remaining = await fs35.readdir(hausDir);
+      if (remaining.length === 0) await fs35.remove(hausDir);
     } catch {
     }
   }
@@ -7225,11 +7891,11 @@ async function runUninstallCommand(options) {
 }
 
 // src/commands/validate-catalog.ts
-import path44 from "node:path";
+import path49 from "node:path";
 
 // src/catalog/validate-core.ts
-import fs35 from "node:fs";
-import path43 from "node:path";
+import fs36 from "node:fs";
+import path48 from "node:path";
 var ITEM_SEMVER_RE = /^\d+\.\d+\.\d+$/;
 function auditForbiddenStacks(items) {
   const failures = [];
@@ -7367,14 +8033,14 @@ function checkRequiredFrontmatter(text, label) {
 }
 function readForAudit(absPath, label, failures) {
   try {
-    return fs35.readFileSync(absPath, "utf8");
+    return fs36.readFileSync(absPath, "utf8");
   } catch (err) {
     failures.push(`${label}: unreadable (${err instanceof Error ? err.message : String(err)})`);
     return null;
   }
 }
 function auditTemplateContent(manifestDir, absPath, itemId) {
-  const rel = path43.relative(manifestDir, absPath);
+  const rel = path48.relative(manifestDir, absPath);
   const failures = [];
   const text = readForAudit(absPath, `${itemId}: ${rel}`, failures);
   if (text === null) return failures;
@@ -7396,47 +8062,47 @@ function auditShippedFiles(manifestDir, items) {
   const failures = [];
   for (const item of items) {
     if (!item.path || !isSafeCatalogPath(item.path)) continue;
-    const absPath = path43.join(manifestDir, item.path);
+    const absPath = path48.join(manifestDir, item.path);
     if (item.type === "skill") {
-      const skillMd = path43.join(absPath, "SKILL.md");
-      if (!fs35.existsSync(skillMd)) {
-        failures.push(`${item.id}: missing ${path43.relative(manifestDir, skillMd)}`);
+      const skillMd = path48.join(absPath, "SKILL.md");
+      if (!fs36.existsSync(skillMd)) {
+        failures.push(`${item.id}: missing ${path48.relative(manifestDir, skillMd)}`);
         continue;
       }
       const text = readForAudit(skillMd, `${item.id}: SKILL.md`, failures);
       if (text === null) continue;
       failures.push(...checkRequiredFrontmatter(text, `${item.id}: SKILL.md`));
       failures.push(
-        ...auditForbiddenTagsInText(text, `${item.id}: ${path43.relative(manifestDir, skillMd)}`)
+        ...auditForbiddenTagsInText(text, `${item.id}: ${path48.relative(manifestDir, skillMd)}`)
       );
     } else if (item.type === "agent") {
-      if (!fs35.existsSync(absPath)) {
+      if (!fs36.existsSync(absPath)) {
         failures.push(`${item.id}: missing agent file ${item.path}`);
         continue;
       }
-      const rel = path43.relative(manifestDir, absPath);
+      const rel = path48.relative(manifestDir, absPath);
       const text = readForAudit(absPath, `${item.id}: ${rel}`, failures);
       if (text === null) continue;
       failures.push(...checkRequiredFrontmatter(text, `${item.id}: ${rel}`));
       failures.push(...auditForbiddenTagsInText(text, `${item.id}: ${rel}`));
     } else if (item.type === "template") {
-      if (!fs35.existsSync(absPath)) {
+      if (!fs36.existsSync(absPath)) {
         failures.push(`${item.id}: missing template file ${item.path}`);
         continue;
       }
       failures.push(...auditTemplateContent(manifestDir, absPath, item.id));
     } else if (item.type === "command") {
-      if (!fs35.existsSync(absPath)) {
+      if (!fs36.existsSync(absPath)) {
         failures.push(`${item.id}: missing command file ${item.path}`);
         continue;
       }
-      const rel = path43.relative(manifestDir, absPath);
+      const rel = path48.relative(manifestDir, absPath);
       const text = readForAudit(absPath, `${item.id}: ${rel}`, failures);
       if (text === null) continue;
       failures.push(...checkRequiredFrontmatter(text, `${item.id}: ${rel}`));
       failures.push(...auditTemplateContent(manifestDir, absPath, item.id));
     } else if (item.type === "config") {
-      if (!fs35.existsSync(absPath)) {
+      if (!fs36.existsSync(absPath)) {
         failures.push(`${item.id}: missing config path ${item.path}`);
       }
     }
@@ -7453,7 +8119,7 @@ var CONTENT_ROOTS = ["skills", "agents", "templates", "commands", "configs"];
 function walkAllFiles(dir, fn, failures) {
   let entries;
   try {
-    entries = fs35.readdirSync(dir, { withFileTypes: true });
+    entries = fs36.readdirSync(dir, { withFileTypes: true });
   } catch (err) {
     failures.push(
       `${dir}: unreadable subtree (${err instanceof Error ? err.message : String(err)})`
@@ -7462,7 +8128,7 @@ function walkAllFiles(dir, fn, failures) {
   }
   for (const entry of entries) {
     if (entry.name === ".DS_Store") continue;
-    const full = path43.join(dir, entry.name);
+    const full = path48.join(dir, entry.name);
     if (entry.isDirectory()) walkAllFiles(full, fn, failures);
     else fn(full);
   }
@@ -7480,12 +8146,12 @@ function auditDiskOrphans(manifestDir, items) {
   const failures = [];
   const claimedPaths = items.filter((item) => item.path && isSafeCatalogPath(item.path)).map((item) => item.path.replace(/\\/g, "/"));
   for (const dir of CONTENT_ROOTS) {
-    const abs = path43.join(manifestDir, dir);
-    if (!fs35.existsSync(abs)) continue;
+    const abs = path48.join(manifestDir, dir);
+    if (!fs36.existsSync(abs)) continue;
     walkAllFiles(
       abs,
       (file) => {
-        const relPath = path43.relative(manifestDir, file).replace(/\\/g, "/");
+        const relPath = path48.relative(manifestDir, file).replace(/\\/g, "/");
         if (!isPathClaimed(relPath, claimedPaths)) {
           failures.push(`orphaned on disk, claimed by no manifest item: ${relPath}`);
         }
@@ -7498,7 +8164,7 @@ function auditDiskOrphans(manifestDir, items) {
 function walkMd(dir, fn, failures) {
   let entries;
   try {
-    entries = fs35.readdirSync(dir, { withFileTypes: true });
+    entries = fs36.readdirSync(dir, { withFileTypes: true });
   } catch (err) {
     failures.push(
       `${dir}: unreadable subtree (${err instanceof Error ? err.message : String(err)})`
@@ -7506,7 +8172,7 @@ function walkMd(dir, fn, failures) {
     return;
   }
   for (const entry of entries) {
-    const full = path43.join(dir, entry.name);
+    const full = path48.join(dir, entry.name);
     if (entry.isDirectory()) walkMd(full, fn, failures);
     else if (entry.name.endsWith(".md")) fn(full);
   }
@@ -7515,13 +8181,13 @@ function auditMarkdownContent(manifestDir, items) {
   const failures = [];
   const pathSourceMap = buildItemPathSourceMap(items);
   for (const dir of ["skills", "agents", "templates", "commands"]) {
-    const abs = path43.join(manifestDir, dir);
-    if (!fs35.existsSync(abs)) continue;
+    const abs = path48.join(manifestDir, dir);
+    if (!fs36.existsSync(abs)) continue;
     const dirType = DIR_ITEM_TYPE[dir] ?? "";
     walkMd(
       abs,
       (file) => {
-        const rel = path43.relative(manifestDir, file);
+        const rel = path48.relative(manifestDir, file);
         const text = readForAudit(file, rel, failures);
         if (text === null) return;
         const norm = rel.replace(/\\/g, "/");
@@ -7566,8 +8232,8 @@ async function runValidateCatalog(manifestPath2) {
     process.exitCode = 1;
     return;
   }
-  const abs = path44.resolve(process.cwd(), manifestPath2);
-  const manifestDir = path44.dirname(abs);
+  const abs = path49.resolve(process.cwd(), manifestPath2);
+  const manifestDir = path49.dirname(abs);
   const data = await readJson(abs);
   if (!data?.items) {
     error(`Could not read catalog manifest at ${abs}`);
@@ -7583,231 +8249,1026 @@ async function runValidateCatalog(manifestPath2) {
   log(`Catalog valid. ${result.items.length} items checked.`);
 }
 
-// src/commands/workspace.ts
-import { existsSync as existsSync6, statSync as statSync3 } from "node:fs";
-import path52 from "node:path";
+// src/workspace/worktree/add.ts
+import path56 from "node:path";
+import fs40 from "fs-extra";
 
-// src/commands/workspace/aggregate.ts
-async function writeWorkspaceArtifacts(workspaceRoot, repos, relationships = []) {
-  const summaries = repos.map((repo) => ({
-    name: repo.name,
-    path: repo.path,
-    roles: repo.context.repoRoles ?? [],
-    packageManager: repo.context.packageManager,
-    deps: repo.context.dependencies ?? []
-  }));
-  const ownership = {};
-  for (const repo of summaries) {
-    for (const dep2 of repo.deps) {
-      ownership[dep2] ??= [];
-      ownership[dep2].push(repo.name);
-    }
+// src/workspace/worktree/git-worktree.ts
+init_exec();
+async function branchExists(cwd, branch) {
+  const result = await runGit(["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], { cwd });
+  return result.exitCode === 0;
+}
+async function resolveDefaultBranch(cwd) {
+  const symbolic = await runGit(["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], { cwd });
+  if (symbolic.exitCode === 0 && symbolic.stdout.trim()) {
+    return { ref: symbolic.stdout.trim(), source: "origin-head" };
   }
-  const roles = [...new Set(summaries.flatMap((r) => r.roles))].sort();
-  const crossRepoHints = [...new Set(repos.flatMap((r) => r.context.crossRepoHints ?? []))].sort();
-  const summaryPath = hausPath(workspaceRoot, "workspace-summary.json");
-  const ownershipPath = hausPath(workspaceRoot, "dependency-ownership-map.json");
-  const crossRepoPath = hausPath(workspaceRoot, "cross-repo-summary.md");
-  const contextMapPath = hausPath(workspaceRoot, "workspace-context-map.json");
-  await writeJson(summaryPath, {
-    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    repos: summaries
-  });
-  await writeJson(ownershipPath, ownership);
-  await writeText(
-    crossRepoPath,
-    `# Cross Repo Summary
-
-${summaries.map(
-      (repo) => `- ${repo.name} (${repo.path}) roles: ${repo.roles.join(", ") || "unknown"}; package manager: ${repo.packageManager}`
-    ).join("\n")}
-`
-  );
-  await writeJson(contextMapPath, {
-    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    roles,
-    crossRepoHints,
-    repos: summaries.map((r) => ({
-      name: r.name,
-      path: r.path,
-      roles: r.roles,
-      packageManager: r.packageManager
-    })),
-    relationships
-  });
-  return [summaryPath, ownershipPath, crossRepoPath, contextMapPath];
+  if (await branchExists(cwd, "main")) return { ref: "main", source: "local-main" };
+  if (await branchExists(cwd, "master")) return { ref: "master", source: "local-master" };
+  return void 0;
 }
-
-// src/commands/workspace/config.ts
-import path45 from "node:path";
-import YAML from "yaml";
-var WORKSPACE_FILE = "haus.workspace.yaml";
-function parseWorkspaceConfig(text) {
-  if (!text) return void 0;
-  let parsed;
-  try {
-    parsed = YAML.parse(text);
-  } catch {
-    return void 0;
+var CHECKED_OUT_ELSEWHERE_PATTERNS = [/already checked out at/i, /already used by worktree/i];
+function isBranchCheckedOutElsewhereError(stderr) {
+  return CHECKED_OUT_ELSEWHERE_PATTERNS.some((re) => re.test(stderr));
+}
+async function addWorktree(cwd, worktreePath2, branch, opts = {}) {
+  const exists = await branchExists(cwd, branch);
+  if (exists) {
+    const result2 = await runGit(["worktree", "add", worktreePath2, branch], { cwd });
+    return {
+      ok: result2.exitCode === 0,
+      branchAction: "checkout",
+      stderr: result2.exitCode === 0 ? void 0 : result2.stderr,
+      checkedOutElsewhere: result2.exitCode !== 0 && isBranchCheckedOutElsewhereError(result2.stderr)
+    };
   }
-  if (!parsed || typeof parsed !== "object") return void 0;
-  const obj = parsed;
-  const repos = Array.isArray(obj.repos) ? obj.repos.filter(
-    (r) => typeof r === "object" && r !== null && typeof r.name === "string" && typeof r.path === "string"
-  ) : [];
+  let startPoint;
+  if (opts.preferDefaultBranchFrom) {
+    const defaultBranch = await resolveDefaultBranch(cwd);
+    startPoint = defaultBranch?.ref;
+  }
+  const args = startPoint ? ["worktree", "add", worktreePath2, "-b", branch, startPoint] : ["worktree", "add", worktreePath2, "-b", branch];
+  const result = await runGit(args, { cwd });
   return {
-    client: typeof obj.client === "string" ? obj.client : "unknown",
-    repos,
-    relationships: Array.isArray(obj.relationships) ? obj.relationships : []
+    ok: result.exitCode === 0,
+    branchAction: "create",
+    startPoint,
+    stderr: result.exitCode === 0 ? void 0 : result.stderr,
+    checkedOutElsewhere: result.exitCode !== 0 && isBranchCheckedOutElsewhereError(result.stderr)
   };
 }
-async function readWorkspaceConfig(workspaceRoot) {
-  return parseWorkspaceConfig(await readText(path45.join(workspaceRoot, WORKSPACE_FILE)));
+async function removeWorktree(ownerRepo, worktreePath2, force = true) {
+  const args = ["worktree", "remove", worktreePath2];
+  if (force) args.push("--force");
+  const result = await runGit(args, { cwd: ownerRepo });
+  return { ok: result.exitCode === 0, stderr: result.exitCode === 0 ? void 0 : result.stderr };
 }
-
-// src/commands/workspace/discover.ts
-import path46 from "node:path";
-import fg4 from "fast-glob";
-import YAML2 from "yaml";
-var DEFAULT_MAX_DEPTH = 3;
-var REPO_MARKERS = ["**/.git", "**/package.json", "**/composer.json"];
-var IGNORE = [
-  "**/node_modules/**",
-  "**/.git/**",
-  "**/vendor/**",
-  "**/dist/**",
-  "**/.haus-workflow/**"
-];
-function isDescendant(child, ancestor) {
-  if (ancestor === ".") return child !== ".";
-  return child === ancestor ? false : child.startsWith(`${ancestor}/`);
+async function pruneWorktrees(ownerRepo) {
+  await runGit(["worktree", "prune"], { cwd: ownerRepo });
 }
-async function discoverRepos(workspaceRoot, maxDepth = DEFAULT_MAX_DEPTH) {
-  const matches = await fg4(REPO_MARKERS, {
-    cwd: workspaceRoot,
-    dot: true,
-    onlyFiles: false,
-    deep: maxDepth,
-    followSymbolicLinks: false,
-    // Discovery walks arbitrary directories under the workspace root; an
-    // unreadable subtree (EPERM/EACCES) must be skipped, not abort the whole scan.
-    suppressErrors: true,
-    ignore: IGNORE
+async function listWorktrees(ownerRepo) {
+  const result = await runGit(["worktree", "list", "--porcelain"], { cwd: ownerRepo });
+  if (result.exitCode !== 0) return [];
+  const entries = [];
+  let current = {};
+  for (const line2 of result.stdout.split("\n")) {
+    if (line2.startsWith("worktree ")) {
+      if (current.path) entries.push(current);
+      current = { path: line2.slice("worktree ".length).trim() };
+    } else if (line2.startsWith("branch ")) {
+      current.branch = line2.slice("branch ".length).replace("refs/heads/", "").trim();
+    } else if (line2.startsWith("HEAD ")) {
+      current.head = line2.slice("HEAD ".length).trim();
+    } else if (line2 === "bare") {
+      current.bare = true;
+    } else if (line2 === "detached") {
+      current.detached = true;
+    }
+  }
+  if (current.path) entries.push(current);
+  return entries;
+}
+async function currentBranch(cwd) {
+  const result = await runGit(["rev-parse", "--abbrev-ref", "HEAD"], { cwd });
+  return result.exitCode === 0 ? result.stdout.trim() : void 0;
+}
+async function hasUncommittedChanges(cwd, ignorePaths = []) {
+  const args = ["status", "--porcelain"];
+  if (ignorePaths.length > 0) {
+    args.push("--", ".", ...ignorePaths.map((p) => `:!${p}`));
+  }
+  const result = await runGit(args, { cwd });
+  return result.exitCode === 0 && result.stdout.trim().length > 0;
+}
+async function hasUnpushedWork(cwd) {
+  const upstream = await runGit(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"], {
+    cwd
   });
-  const gitDirs = /* @__PURE__ */ new Set();
-  const manifestDirs = /* @__PURE__ */ new Set();
-  for (const match of matches) {
-    const base = path46.posix.basename(match);
-    const dir = path46.posix.dirname(match);
-    const owner = dir === "." ? "." : dir;
-    if (base === ".git") gitDirs.add(owner);
-    else manifestDirs.add(owner);
+  if (upstream.exitCode === 0 && upstream.stdout.trim()) {
+    const upstreamRef = upstream.stdout.trim();
+    const ahead = await runGit(["rev-list", "--count", `${upstreamRef}..HEAD`], { cwd });
+    const count = Number.parseInt(ahead.stdout.trim(), 10);
+    if (Number.isFinite(count) && count > 0) {
+      return { unpushed: true, reason: `${count} commit(s) ahead of ${upstreamRef}` };
+    }
+    return { unpushed: false };
+  }
+  const defaultBranch = await resolveDefaultBranch(cwd);
+  if (!defaultBranch) return { unpushed: false };
+  const [head, defaultSha] = await Promise.all([
+    runGit(["rev-parse", "HEAD"], { cwd }),
+    runGit(["rev-parse", defaultBranch.ref], { cwd })
+  ]);
+  if (head.exitCode === 0 && defaultSha.exitCode === 0 && head.stdout.trim() === defaultSha.stdout.trim()) {
+    return { unpushed: false };
   }
-  const repoRoots = [...gitDirs];
-  const manifestSorted = [...manifestDirs].sort(
-    (a, b) => a.split("/").length - b.split("/").length || a.localeCompare(b)
-  );
-  for (const dir of manifestSorted) {
-    if (gitDirs.has(dir)) continue;
-    if (repoRoots.some((root) => isDescendant(dir, root))) continue;
-    repoRoots.push(dir);
+  return {
+    unpushed: true,
+    reason: `no upstream tracking branch configured, and HEAD differs from ${defaultBranch.ref}`
+  };
+}
+
+// src/workspace/worktree/hydrate.ts
+import path52 from "node:path";
+import fs38 from "fs-extra";
+
+// src/workspace/worktree/cow-copy.ts
+init_exec();
+import path50 from "node:path";
+import fs37 from "fs-extra";
+async function getMacFilesystemType(dir) {
+  const df = await runCommand("df", ["-P", dir]);
+  if (df.exitCode !== 0) return void 0;
+  const lines = df.stdout.trim().split("\n");
+  const dataLine = lines[lines.length - 1];
+  const device = dataLine?.split(/\s+/)[0];
+  if (!device) return void 0;
+  const mount = await runCommand("mount");
+  if (mount.exitCode !== 0) return void 0;
+  const line2 = mount.stdout.split("\n").find((l) => l.startsWith(`${device} `));
+  const match = line2?.match(/\(([^,)]+)/);
+  return match?.[1]?.trim();
+}
+async function getLinuxFilesystemType(dir) {
+  const result = await runCommand("stat", ["-f", "-c", "%T", dir]);
+  if (result.exitCode !== 0) return void 0;
+  return result.stdout.trim();
+}
+async function detectCowStrategy(dir) {
+  if (process.platform === "darwin") {
+    const fsType = await getMacFilesystemType(dir);
+    return fsType === "apfs" ? "darwin-clonefile" : "unsupported";
+  }
+  if (process.platform === "linux") {
+    const fsType = await getLinuxFilesystemType(dir);
+    return fsType === "btrfs" || fsType === "xfs" ? "linux-reflink" : "unsupported";
+  }
+  return "unknown-platform";
+}
+async function cowCopyDir(src, dest) {
+  const srcExists = await fs37.pathExists(src);
+  if (!srcExists)
+    return { strategy: "unsupported", attempted: false, ok: false, error: "source missing" };
+  const strategy = await detectCowStrategy(path50.dirname(dest));
+  if (strategy === "unsupported" || strategy === "unknown-platform") {
+    return { strategy, attempted: false, ok: false };
+  }
+  await fs37.ensureDir(path50.dirname(dest));
+  const args = strategy === "darwin-clonefile" ? ["-c", "-R", src, dest] : ["-a", "--reflink=always", src, dest];
+  const result = await runCommand("cp", args);
+  return {
+    strategy,
+    attempted: true,
+    ok: result.exitCode === 0,
+    error: result.exitCode === 0 ? void 0 : result.stderr
+  };
+}
+
+// src/workspace/worktree/install.ts
+init_exec();
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
+import path51 from "node:path";
+import fg5 from "fast-glob";
+function detectInstallPlan(signals) {
+  if (signals.hasYarnLock) {
+    return signals.hasPackageManagerField ? { manager: "yarn", command: "corepack", args: ["yarn", "install"] } : { manager: "yarn", command: "yarn", args: ["install"] };
   }
-  repoRoots.sort((a, b) => a.localeCompare(b));
-  return mapWithConcurrency(repoRoots, async (relDir) => {
-    const absDir = path46.resolve(workspaceRoot, relDir);
-    const pkg = await readJson(path46.join(absDir, "package.json"));
-    const name = typeof pkg?.name === "string" && pkg.name.length > 0 ? pkg.name : path46.basename(relDir === "." ? workspaceRoot : absDir);
-    let role = "auto";
+  if (signals.hasPnpmLock) {
+    return { manager: "pnpm", command: "pnpm", args: ["install", "--frozen-lockfile"] };
+  }
+  if (signals.hasPackageLock) {
+    return { manager: "npm", command: "npm", args: ["install"] };
+  }
+  if (signals.hasComposerLock) {
+    return { manager: "composer", command: "composer", args: ["install"] };
+  }
+  if (signals.hasDotnetProject) {
+    return { manager: "dotnet", command: "dotnet", args: ["restore"] };
+  }
+  return { manager: "none" };
+}
+async function computeLockfileSignals(dir) {
+  const hasYarnLock = existsSync3(path51.join(dir, "yarn.lock"));
+  const hasPnpmLock = existsSync3(path51.join(dir, "pnpm-lock.yaml"));
+  const hasPackageLock = existsSync3(path51.join(dir, "package-lock.json"));
+  const hasComposerLock = existsSync3(path51.join(dir, "composer.lock"));
+  const dotnetFiles = await fg5(["**/*.csproj", "**/*.sln"], {
+    cwd: dir,
+    onlyFiles: true,
+    suppressErrors: true,
+    // Consistent with this codebase's no-symlink-follow posture elsewhere
+    // (fs.ts's findNestedRepoDirs, discover.ts's discoverRepos): a symlink
+    // shouldn't be able to route this search outside the intended tree or
+    // reintroduce a symlink-cycle/perf concern.
+    followSymbolicLinks: false,
+    ignore: ["**/node_modules/**", "**/bin/**", "**/obj/**"]
+  });
+  const hasDotnetProject = dotnetFiles.length > 0;
+  let hasPackageManagerField = false;
+  const pkgPath = path51.join(dir, "package.json");
+  if (existsSync3(pkgPath)) {
     try {
-      const scan = await scanProject(absDir);
-      if (scan.repoRoles[0]) role = scan.repoRoles[0];
+      const pkg = JSON.parse(readFileSync3(pkgPath, "utf8"));
+      hasPackageManagerField = typeof pkg.packageManager === "string" && pkg.packageManager.length > 0;
     } catch {
     }
-    return { name, path: relDir === "." ? "." : relDir, role };
-  });
+  }
+  return {
+    hasYarnLock,
+    hasPackageManagerField,
+    hasPnpmLock,
+    hasPackageLock,
+    hasComposerLock,
+    hasDotnetProject
+  };
 }
-function mergeWorkspaceConfig(existing, discovered, opts = {}) {
-  const existingRepos = existing?.repos ?? [];
-  const byPath = new Map(existingRepos.map((r) => [r.path, r]));
-  for (const repo of discovered) {
-    if (!byPath.has(repo.path)) {
-      byPath.set(repo.path, { name: repo.name, path: repo.path, role: repo.role });
+async function runInstallPlan(dir, plan) {
+  if (plan.manager === "none") {
+    return { plan, ran: false, ok: true, skippedReason: "no recognized lockfile" };
+  }
+  const available = await commandExists(plan.command);
+  if (!available) {
+    return { plan, ran: false, ok: true, skippedReason: `${plan.command} not found on PATH` };
+  }
+  const result = await runCommand(plan.command, plan.args, { cwd: dir });
+  return {
+    plan,
+    ran: true,
+    ok: result.exitCode === 0,
+    exitCode: result.exitCode,
+    stderr: result.exitCode === 0 ? void 0 : result.stderr
+  };
+}
+
+// src/workspace/worktree/hydrate.ts
+var HYDRATION_TARGETS = ["node_modules", "vendor", "obj", "bin"];
+async function hydrateMember(mainMemberPath, worktreeMemberPath, opts = {}) {
+  const start = Date.now();
+  const targets = [];
+  for (const target of HYDRATION_TARGETS) {
+    const src = path52.join(mainMemberPath, target);
+    const dest = path52.join(worktreeMemberPath, target);
+    if (!await fs38.pathExists(src)) continue;
+    const destExists = await fs38.pathExists(dest);
+    if (!opts.force && destExists) continue;
+    if (opts.force && destExists) {
+      await fs38.remove(dest);
     }
+    const copy = await cowCopyDir(src, dest);
+    targets.push({ target, copy });
   }
-  const ordered = [];
-  const seen = /* @__PURE__ */ new Set();
-  for (const repo of existingRepos) {
-    ordered.push(byPath.get(repo.path));
-    seen.add(repo.path);
+  const signals = await computeLockfileSignals(worktreeMemberPath);
+  const plan = detectInstallPlan(signals);
+  const install = await runInstallPlan(worktreeMemberPath, plan);
+  return { targets, install, durationMs: Date.now() - start };
+}
+
+// src/workspace/worktree/local-files.ts
+init_exec();
+import path53 from "node:path";
+import fs39 from "fs-extra";
+var MACHINE_LOCAL_FILES = [
+  "docker-compose.local.yml",
+  path53.join(".claude", "settings.local.json")
+];
+async function isTracked(repoRoot, relFile) {
+  const gitPath = relFile.replace(/\\/g, "/");
+  const result = await runGit(["ls-files", "--error-unmatch", gitPath], { cwd: repoRoot });
+  return result.exitCode === 0;
+}
+async function copyMachineLocalFiles(mainMemberPath, worktreeMemberPath) {
+  const copied = [];
+  for (const rel of MACHINE_LOCAL_FILES) {
+    const src = path53.join(mainMemberPath, rel);
+    if (!await fs39.pathExists(src)) continue;
+    if (await isTracked(mainMemberPath, rel)) continue;
+    const dest = path53.join(worktreeMemberPath, rel);
+    await fs39.ensureDir(path53.dirname(dest));
+    await fs39.copy(src, dest, { overwrite: true });
+    copied.push(rel);
+  }
+  return copied;
+}
+
+// src/workspace/worktree/root.ts
+import { existsSync as existsSync4 } from "node:fs";
+import path54 from "node:path";
+async function resolveWorkspaceForWorktree(start) {
+  const rootInfo = await resolveRoots(start);
+  if (!rootInfo.isGitRepo) {
+    return { ok: false, reason: "Not inside a git repository." };
+  }
+  const workspaceRoot = rootInfo.mainRoot;
+  const hasYaml = existsSync4(path54.join(workspaceRoot, WORKSPACE_FILE));
+  const hasManifest = existsSync4(path54.join(workspaceRoot, REPOS_MANIFEST_FILE));
+  if (!hasYaml && !hasManifest) {
+    return {
+      ok: false,
+      reason: `No workspace found at ${workspaceRoot} \u2014 expected ${WORKSPACE_FILE} or ${REPOS_MANIFEST_FILE}. Run \`haus workspace discover --write\` or \`haus workspace init\` first.`
+    };
   }
-  for (const repo of discovered) {
-    if (seen.has(repo.path)) continue;
-    ordered.push(byPath.get(repo.path));
-    seen.add(repo.path);
+  return { ok: true, rootInfo, workspaceRoot };
+}
+
+// src/workspace/worktree/select-members.ts
+function selectMembers(members, only) {
+  if (!only || only.length === 0) return { selected: members, unknown: [] };
+  const wanted = new Set(only);
+  const selected = members.filter((m) => wanted.has(m.id) || wanted.has(m.folder));
+  const matchedKeys = /* @__PURE__ */ new Set();
+  for (const m of selected) {
+    if (wanted.has(m.id)) matchedKeys.add(m.id);
+    if (wanted.has(m.folder)) matchedKeys.add(m.folder);
+  }
+  const unknown = only.filter((name) => !matchedKeys.has(name));
+  return { selected, unknown };
+}
+
+// src/workspace/worktree/state.ts
+import path55 from "node:path";
+var WORKTREE_STATE_FILE = ".haus-worktree.json";
+function worktreesDir(mainRoot) {
+  return path55.join(mainRoot, ".claude", "worktrees");
+}
+function worktreePath(mainRoot, slug) {
+  return path55.join(worktreesDir(mainRoot), slug);
+}
+async function readWorktreeState(worktreeRoot) {
+  return readJson(path55.join(worktreeRoot, WORKTREE_STATE_FILE));
+}
+async function writeWorktreeState(worktreeRoot, state) {
+  await writeJson(path55.join(worktreeRoot, WORKTREE_STATE_FILE), state);
+}
+
+// src/workspace/worktree/add.ts
+async function runAdd(opts) {
+  const resolved = await resolveWorkspaceForWorktree();
+  if (!resolved.ok) return { ok: false, error: resolved.reason };
+  const { rootInfo, workspaceRoot } = resolved;
+  const allMembers = await readMembers(rootInfo);
+  const { selected, unknown } = selectMembers(allMembers, opts.only);
+  if (unknown.length > 0) {
+    return { ok: false, error: `Unknown --only repo(s): ${unknown.join(", ")}` };
+  }
+  const branch = opts.branch ?? opts.slug;
+  const wsWorktreePath = worktreePath(workspaceRoot, opts.slug);
+  if (await fs40.pathExists(wsWorktreePath)) {
+    return {
+      ok: false,
+      error: `Workspace worktree already exists at ${wsWorktreePath} \u2014 run \`haus workspace worktree hydrate\` or \`remove\` first.`
+    };
+  }
+  if (opts.dryRun) {
+    return runDryRun({ workspaceRoot, wsWorktreePath, slug: opts.slug, branch, selected });
+  }
+  const wsOutcome = await addWorktree(workspaceRoot, wsWorktreePath, branch);
+  if (!wsOutcome.ok) {
+    return {
+      ok: false,
+      error: wsOutcome.checkedOutElsewhere ? `Branch "${branch}" is already checked out elsewhere in the workspace repo \u2014 pick a different --branch.` : `Failed to create the workspace worktree: ${wsOutcome.stderr ?? "unknown error"}`
+    };
+  }
+  const memberResults = [];
+  for (const member of selected) {
+    const start = Date.now();
+    const memberWorktreePath = path56.join(wsWorktreePath, member.folder);
+    const outcome = await addWorktree(member.absPath, memberWorktreePath, branch, {
+      preferDefaultBranchFrom: true
+    });
+    if (!outcome.ok) {
+      memberResults.push({
+        member: member.id,
+        folder: member.folder,
+        status: "failed",
+        branch,
+        branchAction: outcome.branchAction,
+        error: outcome.checkedOutElsewhere ? `Branch "${branch}" is already checked out elsewhere in ${member.id} \u2014 pick a different --branch.` : outcome.stderr ?? "unknown error",
+        durationMs: Date.now() - start
+      });
+      continue;
+    }
+    memberResults.push({
+      member: member.id,
+      folder: member.folder,
+      status: "ok",
+      branch,
+      branchAction: outcome.branchAction,
+      startPoint: outcome.startPoint,
+      durationMs: Date.now() - start
+    });
   }
+  const okResults = memberResults.filter((m) => m.status === "ok");
+  await mapWithConcurrency(okResults, async (result) => {
+    const member = selected.find((m) => m.id === result.member);
+    if (!member) return;
+    const memberWorktreePath = path56.join(wsWorktreePath, member.folder);
+    const hydrationStart = Date.now();
+    if (opts.hydrate !== false) {
+      result.hydration = await hydrateMember(member.absPath, memberWorktreePath);
+    }
+    result.localFilesCopied = await copyMachineLocalFiles(member.absPath, memberWorktreePath);
+    result.durationMs += Date.now() - hydrationStart;
+  });
+  const stateMembers = okResults.map((m) => ({
+    id: m.member,
+    folder: m.folder,
+    branch: m.branch,
+    absPath: selected.find((s) => s.id === m.member)?.absPath
+  }));
+  await writeWorktreeState(wsWorktreePath, {
+    slug: opts.slug,
+    branch,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    members: stateMembers
+  });
+  const anyFailed = memberResults.some((m) => m.status === "failed");
   return {
-    client: opts.client ?? existing?.client ?? "unknown",
-    repos: ordered,
-    relationships: existing?.relationships ?? []
+    ok: !anyFailed,
+    dryRun: false,
+    workspaceRoot,
+    slug: opts.slug,
+    branch,
+    worktreePath: wsWorktreePath,
+    workspaceWorktree: { status: "ok", branchAction: wsOutcome.branchAction },
+    members: memberResults
   };
 }
-function renderWorkspaceYaml(config) {
-  return YAML2.stringify({
-    client: config.client,
-    repos: config.repos.map((r) => ({ name: r.name, path: r.path, role: r.role ?? "auto" })),
-    relationships: config.relationships
-  });
+async function runDryRun(args) {
+  const { workspaceRoot, wsWorktreePath, slug, branch, selected } = args;
+  const wsBranchExists = await branchExists(workspaceRoot, branch);
+  const members = [];
+  for (const member of selected) {
+    const exists = await branchExists(member.absPath, branch);
+    let startPoint;
+    if (!exists) {
+      const def = await resolveDefaultBranch(member.absPath);
+      startPoint = def?.ref;
+    }
+    members.push({
+      member: member.id,
+      folder: member.folder,
+      status: "planned",
+      branch,
+      branchAction: exists ? "checkout" : "create",
+      startPoint,
+      durationMs: 0
+    });
+  }
+  return {
+    ok: true,
+    dryRun: true,
+    workspaceRoot,
+    slug,
+    branch,
+    worktreePath: wsWorktreePath,
+    workspaceWorktree: { status: "planned", branchAction: wsBranchExists ? "checkout" : "create" },
+    members
+  };
 }
-async function runDiscover(workspaceRoot, opts = {}) {
-  const yamlPath = path46.join(workspaceRoot, "haus.workspace.yaml");
-  const existingText = await readText(yamlPath);
-  const existing = parseWorkspaceConfig(existingText);
-  if (existingText && !existing) {
+
+// src/workspace/worktree/doctor.ts
+import { existsSync as existsSync5 } from "node:fs";
+import path57 from "node:path";
+var HYDRATION_MARKERS = ["node_modules", "vendor", "obj", "bin"];
+function looksHydrated(memberPath) {
+  return HYDRATION_MARKERS.some((marker) => existsSync5(path57.join(memberPath, marker)));
+}
+async function runDoctor2() {
+  const rootInfo = await resolveRoots();
+  if (!rootInfo.isGitRepo) {
+    return {
+      isWorkspace: false,
+      inWorkspaceWorktree: false,
+      members: [],
+      orphans: [],
+      problems: ["Not inside a git repository."]
+    };
+  }
+  const workspaceRoot = rootInfo.mainRoot;
+  const isWorkspace = existsSync5(path57.join(workspaceRoot, WORKSPACE_FILE)) || existsSync5(path57.join(workspaceRoot, REPOS_MANIFEST_FILE));
+  if (!isWorkspace) {
+    return {
+      isWorkspace: false,
+      inWorkspaceWorktree: false,
+      members: [],
+      orphans: [],
+      problems: [
+        `Not a haus workspace \u2014 no ${WORKSPACE_FILE} or ${REPOS_MANIFEST_FILE} at ${workspaceRoot}.`
+      ]
+    };
+  }
+  const wsWorktreesDir = worktreesDir(workspaceRoot);
+  const underWorktreesDir = rootInfo.repoRoot.startsWith(`${wsWorktreesDir}${path57.sep}`);
+  const inWorkspaceWorktree = rootInfo.isLinkedWorktree && underWorktreesDir;
+  const members = await readMembers(rootInfo);
+  const problems = [];
+  const memberChecks = [];
+  let slug;
+  if (inWorkspaceWorktree) {
+    const wtPath = rootInfo.repoRoot;
+    slug = rootInfo.worktreeName ?? path57.basename(wtPath);
+    const state = await readWorktreeState(wtPath);
+    for (const member of members) {
+      const memberPath = path57.join(wtPath, member.folder);
+      const materialized = existsSync5(memberPath);
+      const expectedBranch = state?.members.find((m) => m.folder === member.folder)?.branch ?? state?.branch;
+      const actualBranch = materialized ? await currentBranch(memberPath) : void 0;
+      const branchMismatch = Boolean(
+        expectedBranch && actualBranch && expectedBranch !== actualBranch
+      );
+      const hydrated = materialized && looksHydrated(memberPath);
+      memberChecks.push({
+        id: member.id,
+        folder: member.folder,
+        materialized,
+        expectedBranch,
+        actualBranch,
+        branchMismatch,
+        hydrated
+      });
+      if (!materialized) problems.push(`${member.id}: not materialized in this worktree.`);
+      else if (branchMismatch) {
+        problems.push(`${member.id}: on branch "${actualBranch}", expected "${expectedBranch}".`);
+      } else if (!hydrated) {
+        problems.push(
+          `${member.id}: materialized but not hydrated (no node_modules/vendor/obj/bin). Run \`haus workspace worktree hydrate\` to fix.`
+        );
+      }
+    }
+  }
+  const orphans = [];
+  for (const member of members) {
+    const entries = await listWorktrees(member.absPath);
+    for (const entry of entries) {
+      const entryPath = path57.normalize(entry.path);
+      const marker = `${path57.sep}.claude${path57.sep}worktrees${path57.sep}`;
+      const idx = entryPath.indexOf(marker);
+      if (idx === -1) continue;
+      const rest = entryPath.slice(idx + marker.length);
+      const slugName = rest.split(path57.sep)[0];
+      if (!slugName) continue;
+      if (!existsSync5(path57.join(wsWorktreesDir, slugName))) {
+        orphans.push(
+          `${member.id}: worktree registered at ${entry.path} but ${path57.join(wsWorktreesDir, slugName)} no longer exists \u2014 run \`git -C "${member.absPath}" worktree prune\`.`
+        );
+      }
+    }
+  }
+  if (orphans.length > 0) problems.push(...orphans);
+  return { isWorkspace: true, inWorkspaceWorktree, slug, members: memberChecks, orphans, problems };
+}
+
+// src/workspace/worktree/hydrate-command.ts
+import { existsSync as existsSync6 } from "node:fs";
+import path58 from "node:path";
+async function runHydrateWorktree(opts) {
+  const rootInfo = await resolveRoots();
+  if (!rootInfo.isGitRepo || !rootInfo.isLinkedWorktree) {
+    return {
+      ok: false,
+      error: "Run this from inside a workspace worktree created by `haus workspace worktree add` (.claude/worktrees/<slug>)."
+    };
+  }
+  const workspaceRoot = rootInfo.mainRoot;
+  const wtPath = rootInfo.repoRoot;
+  if (!wtPath.startsWith(`${worktreesDir(workspaceRoot)}${path58.sep}`)) {
+    return {
+      ok: false,
+      error: "Current worktree is not one of this workspace's .claude/worktrees/<slug> checkouts."
+    };
+  }
+  const members = await readMembers(rootInfo);
+  const { selected, unknown } = selectMembers(members, opts.only);
+  if (unknown.length > 0) {
+    return { ok: false, error: `Unknown --only repo(s): ${unknown.join(", ")}` };
+  }
+  const state = await readWorktreeState(wtPath);
+  const slug = state?.slug ?? path58.basename(wtPath);
+  if (opts.dryRun) {
+    const results2 = selected.map((member) => {
+      const memberPath = path58.join(wtPath, member.folder);
+      return {
+        member: member.id,
+        folder: member.folder,
+        status: existsSync6(memberPath) ? "planned" : "skipped",
+        error: existsSync6(memberPath) ? void 0 : "not materialized in this worktree"
+      };
+    });
+    return { ok: true, dryRun: true, slug, results: results2 };
+  }
+  const results = await mapWithConcurrency(
+    selected,
+    async (member) => {
+      const memberPath = path58.join(wtPath, member.folder);
+      if (!existsSync6(memberPath)) {
+        return {
+          member: member.id,
+          folder: member.folder,
+          status: "skipped",
+          error: "not materialized in this worktree"
+        };
+      }
+      try {
+        const hydration = await hydrateMember(member.absPath, memberPath, { force: opts.force });
+        return { member: member.id, folder: member.folder, status: "ok", hydration };
+      } catch (err) {
+        return {
+          member: member.id,
+          folder: member.folder,
+          status: "failed",
+          error: err instanceof Error ? err.message : String(err)
+        };
+      }
+    }
+  );
+  return { ok: results.every((r) => r.status !== "failed"), dryRun: false, slug, results };
+}
+
+// src/workspace/worktree/list.ts
+import path59 from "node:path";
+import fs41 from "fs-extra";
+async function runList2() {
+  const resolved = await resolveWorkspaceForWorktree();
+  if (!resolved.ok) return { ok: false, error: resolved.reason };
+  const { rootInfo, workspaceRoot } = resolved;
+  const dir = worktreesDir(workspaceRoot);
+  if (!await fs41.pathExists(dir)) return { ok: true, workspaceRoot, worktrees: [] };
+  const entries = await fs41.readdir(dir, { withFileTypes: true });
+  const slugs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+  const configuredMembers = await readMembers(rootInfo);
+  const worktrees = [];
+  for (const slug of slugs) {
+    const wtPath = path59.join(dir, slug);
+    const state = await readWorktreeState(wtPath);
+    const members = [];
+    const source = state?.members ?? configuredMembers.map((m) => ({ id: m.id, folder: m.folder }));
+    for (const m of source) {
+      const memberPath = path59.join(wtPath, m.folder);
+      const materialized = await fs41.pathExists(memberPath);
+      const actualBranch = materialized ? await currentBranch(memberPath) : void 0;
+      members.push({
+        id: m.id,
+        folder: m.folder,
+        expectedBranch: m.branch,
+        materialized,
+        actualBranch
+      });
+    }
+    worktrees.push({
+      slug,
+      branch: state?.branch ?? await currentBranch(wtPath) ?? "unknown",
+      createdAt: state?.createdAt,
+      members
+    });
+  }
+  return { ok: true, workspaceRoot, worktrees };
+}
+
+// src/workspace/worktree/remove.ts
+import path60 from "node:path";
+import fs42 from "fs-extra";
+async function runRemove(opts) {
+  const resolved = await resolveWorkspaceForWorktree();
+  if (!resolved.ok) return { ok: false, error: resolved.reason };
+  const { rootInfo, workspaceRoot } = resolved;
+  const wsWorktreePath = worktreePath(workspaceRoot, opts.slug);
+  if (!await fs42.pathExists(wsWorktreePath)) {
+    return { ok: false, error: `No workspace worktree found at ${wsWorktreePath}.` };
+  }
+  const state = await readWorktreeState(wsWorktreePath);
+  const allMembers = await readMembers(rootInfo);
+  const stateMembers = state?.members.map((m) => ({ id: m.id, folder: m.folder, absPath: m.absPath })) ?? allMembers.map((m) => ({ id: m.id, folder: m.folder, absPath: m.absPath }));
+  const targets = [
+    { repo: "(workspace)", ownerRepo: workspaceRoot, path: wsWorktreePath }
+  ];
+  const unresolvedDroppedMembers = [];
+  for (const stateMember of stateMembers) {
+    const configMember = allMembers.find((m) => m.folder === stateMember.folder);
+    const ownerRepo = configMember?.absPath ?? stateMember.absPath;
+    if (!ownerRepo) {
+      if (!configMember) unresolvedDroppedMembers.push(stateMember.folder);
+      continue;
+    }
+    targets.push({
+      repo: configMember?.id ?? stateMember.id,
+      ownerRepo,
+      path: path60.join(wsWorktreePath, stateMember.folder)
+    });
+  }
+  const existingTargets = [];
+  for (const target of targets) {
+    if (await fs42.pathExists(target.path)) existingTargets.push(target);
+  }
+  if (!opts.force) {
+    const blockers = [];
+    for (const folder of unresolvedDroppedMembers) {
+      blockers.push({
+        repo: folder,
+        reason: "no longer in the workspace config and this worktree predates absPath tracking \u2014 cannot verify for uncommitted work or unregister its git worktree; removing anyway will delete its directory here but leak the registration in whatever repo it came from (run `git worktree prune` there manually afterward)"
+      });
+    }
+    for (const target of existingTargets) {
+      const ignorePaths = target.repo === "(workspace)" ? [WORKTREE_STATE_FILE, ...stateMembers.map((m) => m.folder)] : [];
+      if (await hasUncommittedChanges(target.path, ignorePaths)) {
+        blockers.push({ repo: target.repo, reason: "uncommitted changes" });
+        continue;
+      }
+      const unpushed = await hasUnpushedWork(target.path);
+      if (unpushed.unpushed) blockers.push({ repo: target.repo, reason: unpushed.reason });
+    }
+    if (blockers.length > 0) return { ok: false, blocked: true, blockers };
+  }
+  if (opts.dryRun) {
+    return {
+      ok: true,
+      dryRun: true,
+      slug: opts.slug,
+      wouldRemove: existingTargets.map((t) => t.repo)
+    };
+  }
+  const removed = [];
+  const failed = [];
+  for (const folder of unresolvedDroppedMembers) {
+    failed.push({
+      repo: folder,
+      error: "directory removed, but its git worktree registration could not be unregistered (no recorded absPath) \u2014 run `git worktree prune` in its original owning repo"
+    });
+  }
+  const memberTargets = existingTargets.filter((t) => t.repo !== "(workspace)");
+  for (const target of memberTargets) {
+    const result = await removeWorktree(target.ownerRepo, target.path);
+    if (result.ok) removed.push(target.repo);
+    else failed.push({ repo: target.repo, error: result.stderr ?? "unknown error" });
+    await pruneWorktrees(target.ownerRepo);
+  }
+  const wsTarget = existingTargets.find((t) => t.repo === "(workspace)");
+  if (wsTarget) {
+    const wsResult = await removeWorktree(workspaceRoot, wsWorktreePath);
+    if (wsResult.ok) removed.push("(workspace)");
+    else failed.push({ repo: "(workspace)", error: wsResult.stderr ?? "unknown error" });
+    await pruneWorktrees(workspaceRoot);
+  }
+  if (await fs42.pathExists(wsWorktreePath)) {
+    await fs42.remove(wsWorktreePath);
+  }
+  return { ok: failed.length === 0, dryRun: false, slug: opts.slug, removed, failed };
+}
+
+// src/commands/workspace/worktree.ts
+function normalizeOnly(only) {
+  if (!only) return void 0;
+  const list = Array.isArray(only) ? only : only.split(/[\s,]+/);
+  const cleaned = list.map((s) => s.trim()).filter(Boolean);
+  return cleaned.length > 0 ? cleaned : void 0;
+}
+function describeInstall(hydration) {
+  if (hydration.install.plan.manager === "none") return "no install step (no recognized lockfile)";
+  if (!hydration.install.ran)
+    return `install skipped (${hydration.install.skippedReason ?? "unavailable"})`;
+  return hydration.install.ok ? `hydrated via ${hydration.install.plan.manager}` : `install FAILED via ${hydration.install.plan.manager}`;
+}
+async function handleAdd(opts) {
+  if (!opts.slug) {
+    error("Usage: haus workspace worktree add <slug>");
+    process.exitCode = 1;
+    return;
+  }
+  const addOpts = {
+    slug: opts.slug,
+    branch: opts.branch,
+    only: normalizeOnly(opts.only),
+    hydrate: opts.hydrate !== false,
+    dryRun: Boolean(opts.dryRun)
+  };
+  const result = await runAdd(addOpts);
+  if ("error" in result) {
+    error(result.error);
+    process.exitCode = 1;
+    return;
+  }
+  if (result.dryRun) {
+    log(
+      `[dry-run] Would create the workspace worktree at ${result.worktreePath} on branch "${result.branch}" (${result.workspaceWorktree.branchAction}).`
+    );
+    for (const m of result.members) {
+      log(
+        `[dry-run]   ${m.member} (${m.folder}): ${m.branchAction}${m.startPoint ? ` from ${m.startPoint}` : ""}`
+      );
+    }
+    return;
+  }
+  log(
+    `Workspace worktree "${result.slug}" ready at ${result.worktreePath} (branch "${result.branch}", ${result.workspaceWorktree.branchAction}).`
+  );
+  for (const m of result.members) {
+    if (m.status === "ok") {
+      const hydrationNote = m.hydration ? describeInstall(m.hydration) : "not hydrated (--no-hydrate)";
+      log(`  ${m.member}: ${m.branchAction} "${m.branch}" \u2014 ${hydrationNote} (${m.durationMs}ms)`);
+    } else {
+      warn(`  ${m.member}: FAILED \u2014 ${m.error}`);
+    }
+  }
+  if (!result.ok) {
+    const failedCount = result.members.filter((m) => m.status === "failed").length;
     error(
-      "Existing haus.workspace.yaml is malformed \u2014 fix or remove it before running discover (refusing to overwrite)."
+      `${failedCount} member(s) failed to materialize \u2014 the worktree is partially built. See the per-member detail above for exactly what exists.`
     );
     process.exitCode = 1;
+  }
+}
+async function handleHydrate(opts) {
+  const hydrateOpts = {
+    only: normalizeOnly(opts.only),
+    force: Boolean(opts.force),
+    dryRun: Boolean(opts.dryRun)
+  };
+  const result = await runHydrateWorktree(hydrateOpts);
+  if (!result.ok && "error" in result) {
+    error(result.error);
+    process.exitCode = 1;
     return;
   }
-  const discovered = await discoverRepos(workspaceRoot, opts.maxDepth ?? DEFAULT_MAX_DEPTH);
-  if (discovered.length === 0) {
-    error("No repos discovered under the workspace root.");
+  if (result.dryRun) {
+    log(`[dry-run] Would hydrate "${result.slug}":`);
+    for (const r of result.results)
+      log(`[dry-run]   ${r.member}: ${r.status}${r.error ? ` (${r.error})` : ""}`);
+    return;
+  }
+  log(`Hydrated "${result.slug}":`);
+  for (const r of result.results) {
+    if (r.status === "ok" && r.hydration) log(`  ${r.member}: ${describeInstall(r.hydration)}`);
+    else warn(`  ${r.member}: ${r.status}${r.error ? ` \u2014 ${r.error}` : ""}`);
+  }
+  if (!result.ok) process.exitCode = 1;
+}
+async function handleRemove(opts) {
+  if (!opts.slug) {
+    error("Usage: haus workspace worktree remove <slug>");
     process.exitCode = 1;
     return;
   }
-  const merged = mergeWorkspaceConfig(existing, discovered, { client: opts.client });
-  const yamlText = renderWorkspaceYaml(merged);
-  if (opts.write) {
-    await writeText(yamlPath, yamlText);
-    if (opts.json) {
-      log(JSON.stringify({ discovered, config: merged, wrote: yamlPath }, null, 2));
-    } else {
-      log(`Wrote ${merged.repos.length} repo(s) to haus.workspace.yaml`);
+  const removeOpts = {
+    slug: opts.slug,
+    force: Boolean(opts.force),
+    dryRun: Boolean(opts.dryRun)
+  };
+  const result = await runRemove(removeOpts);
+  if (!result.ok && "error" in result) {
+    error(result.error);
+    process.exitCode = 1;
+    return;
+  }
+  if (!result.ok && "blocked" in result && result.blocked) {
+    error(`Refusing to remove "${opts.slug}" \u2014 uncommitted or unpushed work found:`);
+    for (const b of result.blockers) error(`  ${b.repo}: ${b.reason}`);
+    error("Re-run with --force to remove anyway.");
+    process.exitCode = 1;
+    return;
+  }
+  if ("dryRun" in result && result.dryRun) {
+    log(`[dry-run] Would remove: ${result.wouldRemove.join(", ") || "(nothing)"}`);
+    return;
+  }
+  if ("removed" in result) {
+    log(`Removed: ${result.removed.join(", ") || "(nothing)"}`);
+    if (result.failed.length > 0) {
+      for (const f of result.failed) error(`  Failed to remove ${f.repo}: ${f.error}`);
+      process.exitCode = 1;
     }
+  }
+}
+async function handleList() {
+  const result = await runList2();
+  if (!result.ok) {
+    error(result.error);
+    process.exitCode = 1;
     return;
   }
-  if (opts.json) {
-    log(JSON.stringify({ discovered, config: merged }, null, 2));
+  if (result.worktrees.length === 0) {
+    log("No workspace worktrees under .claude/worktrees/.");
     return;
   }
-  log("Proposed haus.workspace.yaml (run with --write to persist):\n");
-  log(yamlText);
+  for (const wt of result.worktrees) {
+    log(`${wt.slug}  (branch: ${wt.branch})`);
+    for (const m of wt.members) {
+      const status = m.materialized ? `ok, branch ${m.actualBranch ?? "unknown"}` : "MISSING";
+      log(`  ${m.id}: ${status}`);
+    }
+  }
+}
+async function handleDoctor(opts) {
+  try {
+    const report = await runDoctor2();
+    if (!report.isWorkspace) {
+      if (!opts.fromHook) {
+        warn(report.problems[0] ?? "Not a haus workspace.");
+        process.exitCode = 1;
+      }
+      return;
+    }
+    if (report.problems.length === 0) {
+      log(
+        report.inWorkspaceWorktree ? `Workspace worktree "${report.slug}" looks healthy.` : "No issues found."
+      );
+      return;
+    }
+    for (const p of report.problems) warn(p);
+    if (!opts.fromHook) process.exitCode = 1;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (opts.fromHook) {
+      warn(`worktree doctor: ${message}`);
+    } else {
+      error(message);
+      process.exitCode = 1;
+    }
+  }
+}
+async function runWorktree(action, opts = {}) {
+  switch (action) {
+    case "add":
+      return handleAdd(opts);
+    case "hydrate":
+      return handleHydrate(opts);
+    case "remove":
+      return handleRemove(opts);
+    case "list":
+      return handleList();
+    case "doctor":
+      return handleDoctor(opts);
+  }
+}
+
+// src/commands/workspace.ts
+import { existsSync as existsSync10, statSync as statSync3 } from "node:fs";
+import path69 from "node:path";
+
+// src/commands/workspace/aggregate.ts
+async function writeWorkspaceArtifacts(workspaceRoot, repos, relationships = []) {
+  const summaries = repos.map((repo) => ({
+    name: repo.name,
+    path: repo.path,
+    roles: repo.context.repoRoles ?? [],
+    packageManager: repo.context.packageManager,
+    deps: repo.context.dependencies ?? []
+  }));
+  const ownership = {};
+  for (const repo of summaries) {
+    for (const dep2 of repo.deps) {
+      ownership[dep2] ??= [];
+      ownership[dep2].push(repo.name);
+    }
+  }
+  const roles = [...new Set(summaries.flatMap((r) => r.roles))].sort();
+  const crossRepoHints = [...new Set(repos.flatMap((r) => r.context.crossRepoHints ?? []))].sort();
+  const summaryPath = hausPath(workspaceRoot, "workspace-summary.json");
+  const ownershipPath = hausPath(workspaceRoot, "dependency-ownership-map.json");
+  const crossRepoPath = hausPath(workspaceRoot, "cross-repo-summary.md");
+  const contextMapPath = hausPath(workspaceRoot, "workspace-context-map.json");
+  await writeJson(summaryPath, {
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    repos: summaries
+  });
+  await writeJson(ownershipPath, ownership);
+  await writeText(
+    crossRepoPath,
+    `# Cross Repo Summary
+
+${summaries.map(
+      (repo) => `- ${repo.name} (${repo.path}) roles: ${repo.roles.join(", ") || "unknown"}; package manager: ${repo.packageManager}`
+    ).join("\n")}
+`
+  );
+  await writeJson(contextMapPath, {
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    roles,
+    crossRepoHints,
+    repos: summaries.map((r) => ({
+      name: r.name,
+      path: r.path,
+      roles: r.roles,
+      packageManager: r.packageManager
+    })),
+    relationships
+  });
+  return [summaryPath, ownershipPath, crossRepoPath, contextMapPath];
 }
 
 // src/commands/workspace/doctor.ts
-import { existsSync as existsSync3 } from "node:fs";
-import path48 from "node:path";
+import { existsSync as existsSync7 } from "node:fs";
+import path62 from "node:path";
 
 // src/commands/workspace/manifest.ts
-import { readFileSync as readFileSync3 } from "node:fs";
-import path47 from "node:path";
+import { readFileSync as readFileSync4 } from "node:fs";
+import path61 from "node:path";
 var MANIFEST_FILE = "workspace.manifest.json";
 function manifestPath(workspaceRoot) {
   return hausPath(workspaceRoot, MANIFEST_FILE);
 }
 function hausVersion() {
   try {
-    const pkg = JSON.parse(readFileSync3(path47.join(packageRoot(), "package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync4(path61.join(packageRoot(), "package.json"), "utf8"));
     return pkg.version ?? "0.0.0";
   } catch {
     return "0.0.0";
@@ -7831,7 +9292,8 @@ function buildManifest2(opts) {
       catalogRef: repo.catalogRef,
       status: repo.status,
       ...repo.error ? { error: repo.error } : {}
-    }))
+    })),
+    ...opts.linkedContext ? { linkedContext: opts.linkedContext } : {}
   };
 }
 async function readManifest2(workspaceRoot) {
@@ -7842,6 +9304,22 @@ async function writeWorkspaceManifest(workspaceRoot, manifest) {
   await writeJson(target, manifest);
   return target;
 }
+async function readLinkedContext(workspaceRoot) {
+  const manifest = await readManifest2(workspaceRoot);
+  return manifest?.linkedContext ?? [];
+}
+async function writeLinkedContext(workspaceRoot, linkedContext) {
+  const prior = await readManifest2(workspaceRoot);
+  const next = prior ? { ...prior, generatedAt: (/* @__PURE__ */ new Date()).toISOString(), linkedContext } : {
+    version: 1,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    hausVersion: hausVersion(),
+    client: "unknown",
+    repos: [],
+    linkedContext
+  };
+  return writeWorkspaceManifest(workspaceRoot, next);
+}
 
 // src/commands/workspace/doctor.ts
 async function runWorkspaceDoctor(workspaceRoot, opts = {}) {
@@ -7874,7 +9352,7 @@ async function runWorkspaceDoctor(workspaceRoot, opts = {}) {
   const manifestByName = new Map(manifest.repos.map((r) => [r.name, r]));
   const catalogRefByRepo = [];
   for (const repo of config.repos) {
-    const repoRoot = path48.resolve(workspaceRoot, repo.path);
+    const repoRoot = path62.resolve(workspaceRoot, repo.path);
     const entry = manifestByName.get(repo.name);
     if (!entry) {
       flag({
@@ -7899,7 +9377,7 @@ async function runWorkspaceDoctor(workspaceRoot, opts = {}) {
         detail: `Set up at haus ${entry.hausVersionAtSetup}, current is ${currentVersion} \u2014 re-run setup.`
       });
     }
-    if (!existsSync3(claudePath(repoRoot))) {
+    if (!existsSync7(claudePath(repoRoot))) {
       flag({
         repo: repo.name,
         kind: "missing-claude",
@@ -7908,7 +9386,7 @@ async function runWorkspaceDoctor(workspaceRoot, opts = {}) {
     }
     const lock = await checkLock(repoRoot);
     if (lock.catalogRef) catalogRefByRepo.push({ repo: repo.name, ref: lock.catalogRef });
-    if (!existsSync3(hausPath(repoRoot, "haus.lock.json"))) {
+    if (!existsSync7(hausPath(repoRoot, "haus.lock.json"))) {
       flag({
         repo: repo.name,
         kind: "missing-lock",
@@ -7933,6 +9411,40 @@ async function runWorkspaceDoctor(workspaceRoot, opts = {}) {
       detail: `Repos are on different catalog refs \u2014 ${catalogRefByRepo.map((r) => `${r.repo}: ${r.ref}`).join(", ")}. Run \`haus workspace setup --write\` to bring them onto the same ref.`
     });
   }
+  if (manifest.linkedContext && manifest.linkedContext.length > 0) {
+    const rootInfo = await resolveRoots(workspaceRoot);
+    const members = await readMembers(rootInfo);
+    const memberById = new Map(members.map((m) => [m.id, m]));
+    for (const entry of manifest.linkedContext) {
+      const member = memberById.get(entry.repo);
+      if (!member || !existsSync7(member.absPath)) {
+        flag({
+          repo: entry.repo,
+          kind: "missing-linked-context-source",
+          detail: `Linked ${entry.type} "${entry.name}" (${entry.path}) \u2014 source repo no longer configured or cloned. Re-run \`haus workspace link-context\` to clean up.`
+        });
+        continue;
+      }
+      if (!existsSync7(path62.join(workspaceRoot, entry.path))) {
+        flag({
+          repo: entry.repo,
+          kind: "missing-linked-context-copy",
+          detail: `Linked ${entry.type} "${entry.name}" is recorded in the manifest but ${entry.path} no longer exists at the workspace root. Re-run \`haus workspace link-context\` to restore it.`
+        });
+        continue;
+      }
+      const liveHash = await hashInstalledPaths(member.absPath, [entry.sourceRelPath], {
+        followSymlinks: false
+      });
+      if (liveHash !== entry.sourceHash) {
+        flag({
+          repo: entry.repo,
+          kind: "stale-linked-context",
+          detail: `Linked ${entry.type} "${entry.name}" (${entry.path}) is stale \u2014 the source in ${entry.repo} changed since it was linked. Re-run \`haus workspace link-context\`.`
+        });
+      }
+    }
+  }
   return emit({ workspaceRoot, manifest, drift, detail, json: opts.json });
 }
 function emit(args) {
@@ -7955,13 +9467,256 @@ function emit(args) {
   return { workspaceRoot, manifest, drift };
 }
 
+// src/workspace/link-context/link.ts
+import path65 from "node:path";
+import fs45 from "fs-extra";
+
+// src/workspace/link-context/plan.ts
+import path64 from "node:path";
+import fs44 from "fs-extra";
+
+// src/workspace/link-context/scan-source.ts
+import path63 from "node:path";
+import fs43 from "fs-extra";
+var ASSET_SUBDIR = {
+  skill: "skills",
+  agent: "agents",
+  command: "commands"
+};
+async function hasLinkableContext(member) {
+  for (const subdir of Object.values(ASSET_SUBDIR)) {
+    if (await fs43.pathExists(path63.join(member.absPath, ".claude", subdir))) return true;
+  }
+  return false;
+}
+async function collectSkills(member) {
+  const dir = path63.join(member.absPath, ".claude", "skills");
+  if (!await fs43.pathExists(dir)) return [];
+  const names = await fs43.readdir(dir);
+  const out = [];
+  for (const name of [...names].sort()) {
+    const abs = path63.join(dir, name);
+    const stat = await fs43.lstat(abs);
+    if (!stat.isDirectory()) continue;
+    if (!await fs43.pathExists(path63.join(abs, "SKILL.md"))) continue;
+    out.push({ type: "skill", name, sourceRelPath: path63.posix.join(".claude", "skills", name) });
+  }
+  return out;
+}
+async function collectFlatMarkdown(member, type) {
+  const subdir = ASSET_SUBDIR[type];
+  const dir = path63.join(member.absPath, ".claude", subdir);
+  if (!await fs43.pathExists(dir)) return [];
+  const names = await fs43.readdir(dir);
+  const out = [];
+  for (const fileName of [...names].sort()) {
+    if (!fileName.endsWith(".md")) continue;
+    const abs = path63.join(dir, fileName);
+    if (!(await fs43.lstat(abs)).isFile()) continue;
+    const name = fileName.slice(0, -".md".length);
+    out.push({ type, name, sourceRelPath: path63.posix.join(".claude", subdir, fileName) });
+  }
+  return out;
+}
+async function collectSourceAssets(member) {
+  const [skills, agents, commands] = await Promise.all([
+    collectSkills(member),
+    collectFlatMarkdown(member, "agent"),
+    collectFlatMarkdown(member, "command")
+  ]);
+  return [...skills, ...agents, ...commands];
+}
+
+// src/workspace/link-context/plan.ts
+function repoFolderPrefix(member) {
+  const base = path64.posix.basename(member.folder);
+  if (base && base !== "." && base !== "/") return base;
+  const fromAbs = path64.basename(member.absPath);
+  return fromAbs || member.id;
+}
+function assetKey(type, destKey) {
+  return `${type}:${destKey}`;
+}
+function splitAssetKey(key) {
+  const idx = key.indexOf(":");
+  return { type: key.slice(0, idx), destKey: key.slice(idx + 1) };
+}
+async function buildLinkPlan(members) {
+  const skipped = [];
+  const byKey = /* @__PURE__ */ new Map();
+  const membersById = new Map(members.map((m) => [m.id, m]));
+  for (const member of members) {
+    if (!await fs44.pathExists(member.absPath)) {
+      skipped.push({ repo: member.id, reason: `not cloned locally (${member.absPath}) \u2014 skipped` });
+      continue;
+    }
+    if (!await hasLinkableContext(member)) {
+      skipped.push({
+        repo: member.id,
+        reason: "no .claude/skills, .claude/agents, or .claude/commands \u2014 nothing to link"
+      });
+      continue;
+    }
+    const assets = await collectSourceAssets(member);
+    const prefix = repoFolderPrefix(member);
+    for (const asset of assets) {
+      const destKey = `${prefix}--${asset.name}`;
+      const key = assetKey(asset.type, destKey);
+      const list = byKey.get(key) ?? [];
+      list.push({ repo: member.id, asset });
+      byKey.set(key, list);
+    }
+  }
+  const collisions = [];
+  const entries = [];
+  for (const [key, list] of byKey) {
+    const { type, destKey } = splitAssetKey(key);
+    const distinctRepos = [...new Set(list.map((l) => l.repo))];
+    if (distinctRepos.length > 1) {
+      collisions.push({ type, destKey, repos: distinctRepos });
+      continue;
+    }
+    const { repo, asset } = list[0];
+    const member = membersById.get(repo);
+    if (!member) continue;
+    const sourceHash = await hashInstalledPaths(member.absPath, [asset.sourceRelPath], {
+      followSymlinks: false
+    });
+    entries.push({
+      repo,
+      type,
+      name: asset.name,
+      destKey,
+      sourceRelPath: asset.sourceRelPath,
+      sourceAbsPath: path64.join(member.absPath, asset.sourceRelPath),
+      sourceHash
+    });
+  }
+  return { entries, skipped, collisions };
+}
+
+// src/workspace/link-context/link.ts
+function destRelPathFor(type, destKey) {
+  const subdir = `${type}s`;
+  const leaf = type === "skill" ? destKey : `${destKey}.md`;
+  return path65.posix.join(".claude", subdir, leaf);
+}
+async function runLinkContext(workspaceRoot, opts = {}) {
+  const write = opts.write ?? false;
+  const say = opts.json ? () => {
+  } : log;
+  const rootInfo = await resolveRoots(workspaceRoot);
+  const members = await readMembers(rootInfo);
+  const plan = await buildLinkPlan(members);
+  if (plan.collisions.length > 0) {
+    const detail = plan.collisions.map((c) => `${c.type} "${c.destKey}" claimed by: ${c.repos.join(", ")}`).join("; ");
+    return {
+      ok: false,
+      error: `Name collision(s) after the repo-folder prefix \u2014 refusing to overwrite either copy. Rename one of the conflicting repos' folders (in haus.workspace.yaml/repos.manifest.json) or the conflicting skill/agent/command itself to resolve: ${detail}`,
+      collisions: plan.collisions
+    };
+  }
+  for (const s of plan.skipped) say(`  skip ${s.repo}: ${s.reason}`);
+  const priorManifest = await readManifest2(workspaceRoot);
+  const prior = priorManifest?.linkedContext ?? [];
+  const priorPaths = new Set(prior.map((e) => e.path));
+  const nextEntries = [];
+  const added = [];
+  const linkedAt = (/* @__PURE__ */ new Date()).toISOString();
+  for (const entry of plan.entries) {
+    const destRel = destRelPathFor(entry.type, entry.destKey);
+    const destAbs = path65.join(workspaceRoot, destRel);
+    if (write) {
+      await fs45.ensureDir(path65.dirname(destAbs));
+      if (await fs45.pathExists(destAbs)) await fs45.remove(destAbs);
+      await fs45.copy(entry.sourceAbsPath, destAbs, {
+        overwrite: true,
+        errorOnExist: false,
+        dereference: false,
+        filter: (s) => {
+          try {
+            return !fs45.lstatSync(s).isSymbolicLink();
+          } catch {
+            return false;
+          }
+        }
+      });
+    }
+    if (!priorPaths.has(destRel)) added.push(destRel);
+    nextEntries.push({
+      repo: entry.repo,
+      type: entry.type,
+      name: entry.name,
+      path: destRel,
+      sourceRelPath: entry.sourceRelPath,
+      sourceHash: entry.sourceHash,
+      linkedAt
+    });
+  }
+  const nextPaths = new Set(nextEntries.map((e) => e.path));
+  const removed = [];
+  for (const old of prior) {
+    if (nextPaths.has(old.path)) continue;
+    removed.push(old.path);
+    if (write) {
+      const abs = path65.join(workspaceRoot, old.path);
+      if (await fs45.pathExists(abs)) await fs45.remove(abs);
+    }
+  }
+  if (write) {
+    await writeLinkedContext(workspaceRoot, nextEntries);
+    await writeLinkContextGitignore(workspaceRoot, false);
+  }
+  return {
+    ok: true,
+    workspaceRoot,
+    dryRun: !write,
+    linked: nextEntries,
+    added,
+    removed,
+    skipped: plan.skipped
+  };
+}
+
+// src/commands/workspace/link-context.ts
+async function runWorkspaceLinkContext(workspaceRoot, opts = {}) {
+  const options = { write: opts.write, json: opts.json };
+  const result = await runLinkContext(workspaceRoot, options);
+  if (!result.ok) {
+    if (opts.json) {
+      log(JSON.stringify(result, null, 2));
+    } else {
+      error(result.error);
+    }
+    process.exitCode = 1;
+    return;
+  }
+  if (opts.json) {
+    log(JSON.stringify(result, null, 2));
+    return;
+  }
+  for (const s of result.skipped) warn(`  skip ${s.repo}: ${s.reason}`);
+  if (result.dryRun) {
+    log(
+      `[dry-run] Would link ${result.linked.length} skill/agent/command copy(ies) into .claude/ (${result.added.length} new, ${result.removed.length} to remove). Re-run with --write to apply.`
+    );
+    return;
+  }
+  log(
+    `Linked ${result.linked.length} skill/agent/command copy(ies) into .claude/ (${result.added.length} new, ${result.removed.length} removed).`
+  );
+  log(
+    "Source of truth for each copy stays in its own member repo \u2014 do not edit the copies directly; re-run `haus workspace link-context` after editing a source, or when `haus workspace doctor` flags one stale."
+  );
+}
+
 // src/commands/workspace/setup.ts
-import { existsSync as existsSync4, statSync } from "node:fs";
-import path50 from "node:path";
+import { existsSync as existsSync8, statSync } from "node:fs";
+import path67 from "node:path";
 
 // src/claude/write-workspace-claude-md.ts
-import path49 from "node:path";
-import fs36 from "fs-extra";
+import path66 from "node:path";
+import fs46 from "fs-extra";
 function buildWorkspaceImportBlock(client, members) {
   const memberLines = members.map((m) => `- ${m.name} (${m.path})`);
   const body = [
@@ -7979,11 +9734,11 @@ ${BLOCK_END}`;
 async function writeWorkspaceClaudeMd(workspaceRoot, opts) {
   const block = buildWorkspaceImportBlock(opts.client, opts.members);
   const dryRun = opts.dryRun ?? false;
-  const filePath = opts.collision ? hausPath(workspaceRoot, "WORKSPACE.md") : path49.join(workspaceRoot, "CLAUDE.md");
+  const filePath = opts.collision ? hausPath(workspaceRoot, "WORKSPACE.md") : path66.join(workspaceRoot, "CLAUDE.md");
   const say = opts.quiet ? () => {
   } : log;
-  const existed = await fs36.pathExists(filePath);
-  const prev = existed ? await fs36.readFile(filePath, "utf8") : "";
+  const existed = await fs46.pathExists(filePath);
+  const prev = existed ? await fs46.readFile(filePath, "utf8") : "";
   const next = opts.collision ? `${block}
 ` : injectHausBlock(prev, block);
   const printable = displayPath(workspaceRoot, filePath);
@@ -8010,20 +9765,20 @@ async function writeWorkspaceClaudeMd(workspaceRoot, opts) {
 
 // src/commands/workspace/setup.ts
 function resolveWorkspaceRoot(start = process.cwd()) {
-  let dir = path50.resolve(start);
+  let dir = path67.resolve(start);
   for (; ; ) {
-    if (existsSync4(path50.join(dir, WORKSPACE_FILE))) return dir;
-    const parent = path50.dirname(dir);
-    if (parent === dir) return path50.resolve(start);
+    if (existsSync8(path67.join(dir, WORKSPACE_FILE))) return dir;
+    const parent = path67.dirname(dir);
+    if (parent === dir) return path67.resolve(start);
     dir = parent;
   }
 }
 function isRootRepo(workspaceRoot, repoPath) {
-  return path50.resolve(workspaceRoot, repoPath) === path50.resolve(workspaceRoot);
+  return path67.resolve(workspaceRoot, repoPath) === path67.resolve(workspaceRoot);
 }
 async function runWorkspaceSetup(workspaceRoot, options = {}) {
   const apply = options.write ?? false;
-  const configText = await readText(path50.join(workspaceRoot, WORKSPACE_FILE));
+  const configText = await readText(path67.join(workspaceRoot, WORKSPACE_FILE));
   if (!configText) {
     error(`Missing ${WORKSPACE_FILE}. Run \`haus workspace discover\` or \`init\` first.`);
     process.exitCode = 1;
@@ -8050,11 +9805,11 @@ async function runWorkspaceSetup(workspaceRoot, options = {}) {
   const statuses = [];
   const aggregateInputs = [];
   for (const repo of repos) {
-    const repoRoot = path50.resolve(workspaceRoot, repo.path);
+    const repoRoot = path67.resolve(workspaceRoot, repo.path);
     say(`
 \u2192 ${repo.name} (${repo.path})`);
     try {
-      if (!existsSync4(repoRoot) || !statSync(repoRoot).isDirectory()) {
+      if (!existsSync8(repoRoot) || !statSync(repoRoot).isDirectory()) {
         throw new Error(`Repo path is not a directory: ${repo.path}`);
       }
       const res = await runSetupCore(repoRoot, {
@@ -8110,7 +9865,7 @@ async function runWorkspaceSetup(workspaceRoot, options = {}) {
   if (apply && !options.dryRun) {
     const statusByName = new Map(statuses.map((s) => [s.name, s]));
     const prior = await readManifest2(workspaceRoot);
-    if (!prior && existsSync4(manifestPath(workspaceRoot))) {
+    if (!prior && existsSync8(manifestPath(workspaceRoot))) {
       warn(
         "Existing workspace.manifest.json is unreadable \u2014 prior per-repo state will not be carried forward."
       );
@@ -8121,7 +9876,7 @@ async function runWorkspaceSetup(workspaceRoot, options = {}) {
       const status = statusByName.get(repo.name);
       const role = repo.role ?? status?.roles?.[0] ?? "auto";
       if (status?.status === "ok") {
-        const lock = await checkLock(path50.resolve(workspaceRoot, repo.path));
+        const lock = await checkLock(path67.resolve(workspaceRoot, repo.path));
         manifestRepos.push({
           name: repo.name,
           path: repo.path,
@@ -8164,9 +9919,33 @@ async function runWorkspaceSetup(workspaceRoot, options = {}) {
         );
       }
     }
-    const manifest = buildManifest2({ client: config.client, repos: manifestRepos });
+    const manifest = buildManifest2({
+      client: config.client,
+      repos: manifestRepos,
+      // buildManifest rebuilds the manifest from scratch each run — carry the prior
+      // `linkedContext` section forward so a plain `setup --write` never silently
+      // drops entries `link-context` wrote on an earlier run.
+      linkedContext: prior?.linkedContext
+    });
     const manifestFile = await writeWorkspaceManifest(workspaceRoot, manifest);
     written.push(manifestFile);
+    try {
+      const linkResult = await runLinkContext(workspaceRoot, { write: true, json: options.json });
+      if (linkResult.ok) {
+        written.push(...linkResult.added.map((rel) => path67.join(workspaceRoot, rel)));
+        if (!options.json) {
+          say(
+            `Linked ${linkResult.linked.length} cross-repo skill/agent/command copy(ies) into .claude/ (${linkResult.added.length} new, ${linkResult.removed.length} removed)${linkResult.skipped.length > 0 ? ` \u2014 ${linkResult.skipped.length} member(s) skipped, see above` : ""}.`
+          );
+        }
+      } else {
+        warn(`Skipping workspace link-context: ${linkResult.error}`);
+      }
+    } catch (err) {
+      warn(
+        `Workspace link-context failed: ${err instanceof Error ? err.message : String(err)} \u2014 run \`haus workspace link-context\` directly to retry.`
+      );
+    }
   }
   const ok = statuses.filter((s) => s.status === "ok").length;
   const failed = statuses.length - ok;
@@ -8184,9 +9963,9 @@ Workspace setup complete: ${ok} ok, ${failed} failed. Wrote ${written.length} fi
 }
 
 // src/commands/workspace/undo.ts
-import { existsSync as existsSync5, statSync as statSync2 } from "node:fs";
-import path51 from "node:path";
-import fs37 from "fs-extra";
+import { existsSync as existsSync9, statSync as statSync2 } from "node:fs";
+import path68 from "node:path";
+import fs47 from "fs-extra";
 var WORKSPACE_AGGREGATE_FILES = [
   "workspace-summary.json",
   "dependency-ownership-map.json",
@@ -8214,11 +9993,11 @@ async function runWorkspaceUndo(workspaceRoot, options = {}) {
   }
   let anyRepoFailed = false;
   for (const repo of config.repos) {
-    const repoRoot = path51.resolve(workspaceRoot, repo.path);
+    const repoRoot = path68.resolve(workspaceRoot, repo.path);
     log(`
 \u2192 ${repo.name} (${repo.path})`);
     try {
-      if (!existsSync5(repoRoot) || !statSync2(repoRoot).isDirectory()) {
+      if (!existsSync9(repoRoot) || !statSync2(repoRoot).isDirectory()) {
         throw new Error(`Repo path is not a directory: ${repo.path}`);
       }
       await runUndo({ yes: true, root: repoRoot });
@@ -8227,33 +10006,41 @@ async function runWorkspaceUndo(workspaceRoot, options = {}) {
       warn(`Undo failed for ${repo.name}: ${err instanceof Error ? err.message : String(err)}`);
     }
   }
+  const linkedContext = await readLinkedContext(workspaceRoot);
+  for (const entry of linkedContext) {
+    const abs = path68.join(workspaceRoot, entry.path);
+    if (await fs47.pathExists(abs)) {
+      await fs47.remove(abs);
+      log(`Removed ${entry.path} (linked ${entry.type} from ${entry.repo})`);
+    }
+  }
   for (const rel of WORKSPACE_AGGREGATE_FILES) {
     const abs = hausPath(workspaceRoot, rel);
-    if (await fs37.pathExists(abs)) {
-      await fs37.remove(abs);
-      log(`Removed ${path51.relative(workspaceRoot, abs)}`);
+    if (await fs47.pathExists(abs)) {
+      await fs47.remove(abs);
+      log(`Removed ${path68.relative(workspaceRoot, abs)}`);
     }
   }
   const manifestFile = manifestPath(workspaceRoot);
-  if (await fs37.pathExists(manifestFile)) {
-    await fs37.remove(manifestFile);
-    log(`Removed ${path51.relative(workspaceRoot, manifestFile)}`);
+  if (await fs47.pathExists(manifestFile)) {
+    await fs47.remove(manifestFile);
+    log(`Removed ${path68.relative(workspaceRoot, manifestFile)}`);
   }
   const workspaceMdPath = hausPath(workspaceRoot, "WORKSPACE.md");
-  if (await fs37.pathExists(workspaceMdPath)) {
-    await fs37.remove(workspaceMdPath);
-    log(`Removed ${path51.relative(workspaceRoot, workspaceMdPath)}`);
+  if (await fs47.pathExists(workspaceMdPath)) {
+    await fs47.remove(workspaceMdPath);
+    log(`Removed ${path68.relative(workspaceRoot, workspaceMdPath)}`);
   } else {
-    const claudeMdPath = path51.join(workspaceRoot, "CLAUDE.md");
-    if (existsSync5(claudeMdPath)) {
+    const claudeMdPath = path68.join(workspaceRoot, "CLAUDE.md");
+    if (existsSync9(claudeMdPath)) {
       const prev = await readText(claudeMdPath);
       if (prev?.includes(BLOCK_BEGIN)) {
         const next = stripHausBlock(prev);
         if (next.length === 0) {
-          await fs37.remove(claudeMdPath);
+          await fs47.remove(claudeMdPath);
           log("Removed CLAUDE.md (only contained the workspace haus import block).");
         } else {
-          await fs37.writeFile(claudeMdPath, next, "utf8");
+          await fs47.writeFile(claudeMdPath, next, "utf8");
           log("Removed haus import block from CLAUDE.md (user content preserved).");
         }
       }
@@ -8269,7 +10056,7 @@ async function runWorkspaceUndo(workspaceRoot, options = {}) {
 }
 
 // src/commands/workspace.ts
-function normalizeOnly(only) {
+function normalizeOnly2(only) {
   if (!only) return void 0;
   const list = Array.isArray(only) ? only : only.split(/[\s,]+/);
   const cleaned = list.map((s) => s.trim()).filter(Boolean);
@@ -8296,7 +10083,7 @@ relationships: []
   log("Workspace initialized.");
 }
 async function scanWorkspace(workspaceRoot, opts) {
-  const configText = await readText(path52.join(workspaceRoot, WORKSPACE_FILE));
+  const configText = await readText(path69.join(workspaceRoot, WORKSPACE_FILE));
   if (!configText) {
     error(`Missing ${WORKSPACE_FILE}. Run \`haus workspace discover\` or \`init\` first.`);
     process.exitCode = 1;
@@ -8318,9 +10105,9 @@ async function scanWorkspace(workspaceRoot, opts) {
   const inputs = [];
   const failures = [];
   for (const repo of config.repos) {
-    const repoRoot = path52.resolve(workspaceRoot, repo.path);
+    const repoRoot = path69.resolve(workspaceRoot, repo.path);
     try {
-      if (!existsSync6(repoRoot) || !statSync3(repoRoot).isDirectory()) {
+      if (!existsSync10(repoRoot) || !statSync3(repoRoot).isDirectory()) {
         throw new Error("path is not a directory");
       }
       const result = await scanProject(repoRoot);
@@ -8366,7 +10153,7 @@ async function runWorkspace(action, options = {}) {
         dryRun: options.dryRun,
         json: options.json,
         continueOnError: options.continueOnError,
-        only: normalizeOnly(options.only)
+        only: normalizeOnly2(options.only)
       });
       return;
     case "doctor":
@@ -8375,14 +10162,17 @@ async function runWorkspace(action, options = {}) {
     case "undo":
       await runWorkspaceUndo(workspaceRoot, { yes: options.yes });
       return;
+    case "link-context":
+      await runWorkspaceLinkContext(workspaceRoot, { write: options.write, json: options.json });
+      return;
   }
 }
 
 // src/cli.ts
 function cliVersion() {
   try {
-    const pkgPath = path53.join(packageRoot(), "package.json");
-    const pkg = JSON.parse(readFileSync4(pkgPath, "utf8"));
+    const pkgPath = path70.join(packageRoot(), "package.json");
+    const pkg = JSON.parse(readFileSync5(pkgPath, "utf8"));
     return pkg.version ?? "0.0.0";
   } catch {
     return "0.0.0";
@@ -8391,8 +10181,8 @@ function cliVersion() {
 var program = new Command();
 function validateRuntimeNodeVersion() {
   try {
-    const pkgPath = path53.join(packageRoot(), "package.json");
-    const pkg = JSON.parse(readFileSync4(pkgPath, "utf8"));
+    const pkgPath = path70.join(packageRoot(), "package.json");
+    const pkg = JSON.parse(readFileSync5(pkgPath, "utf8"));
     const requiredRange = pkg.engines?.node;
     if (requiredRange && !satisfiesVersion(process.version, requiredRange)) {
       throw new Error(`Node ${process.version} does not satisfy required range ${requiredRange}`);
@@ -8410,7 +10200,10 @@ program.command("recommend").option("--json").option(
   "--include <ids...>",
   "Force opt-in catalog items into the recommendation as manual selections (space- or comma-separated ids)"
 ).action(runRecommend);
-program.command("setup-project").option("--json").action(runSetupProject);
+program.command("setup-project").option("--json").option(
+  "--force",
+  "Write recommendation.json/haus.lock.json even when zero catalog items matched at all"
+).action(runSetupProject);
 program.command("doctor").option("--hooks", "Verify .claude/settings.json matches the hook contract").action(runDoctor);
 program.command("fetch-refs").description("Fetch and cache llms.txt content from catalog item references").option("--all", "Fetch for all catalog items (default)").option("--id <id>", "Fetch for a single catalog item by id").option("--json", "Emit machine-readable JSON summary to stdout").action(runFetchRefs);
 program.command("apply").option("--dry-run").option("--write").option("--select", "Interactively select catalog items before applying").option(
@@ -8472,6 +10265,31 @@ workspace.command("scan").description("Aggregate a cross-repo summary from a fas
 workspace.command("setup").description("Per-repo setup loop + workspace layer + manifest").option("--write", "Apply changes (default previews only)").option("--dry-run", "Preview changes without writing").option("--json", "Emit machine-readable per-repo output").option("--continue-on-error", "Keep going past a failed repo (default fail-fast)").option("--only <names>", "Restrict to comma-separated repo names").action((opts) => runWorkspace("setup", opts));
 workspace.command("doctor").description("Report workspace drift against the manifest").option("--json", "Output the manifest and drift array as JSON").action((opts) => runWorkspace("doctor", opts));
 workspace.command("undo").description("Revert haus setup for every configured repo, plus workspace-root artifacts").option("-y, --yes", "Skip confirmation").action((opts) => runWorkspace("undo", opts));
+workspace.command("link-context").description(
+  "Copy each member repo's skill/agent/command into the workspace root's .claude/, prefixed to avoid collisions"
+).option("--write", "Persist copies + manifest + gitignore (default previews only)").option("--json", "Output the link result as JSON").action((opts) => runWorkspace("link-context", opts));
+var worktree = workspace.command("worktree").description(
+  "Materialize workspace member repos as real git worktrees (per docs/plans/workspace-worktree-materialization.md, Task 4)"
+);
+worktree.command("add <slug>").description(
+  "Create a workspace worktree plus one member worktree per repo, on a mirrored branch"
+).option("--branch <name>", "Branch to create/checkout (default: the slug)").option("--only <repos>", "Restrict to comma- or space-separated member ids/folders").option("--no-hydrate", "Skip hydration (CoW clone + install-reconciliation)").option("--dry-run", "Preview without writing or running anything").action(
+  (slug, opts) => runWorktree("add", {
+    slug,
+    branch: opts.branch,
+    only: opts.only,
+    hydrate: opts.hydrate,
+    dryRun: opts.dryRun
+  })
+);
+worktree.command("hydrate").description("Re-run CoW clone + install-reconciliation for the current workspace worktree").option("--only <repos>", "Restrict to comma- or space-separated member ids/folders").option("--force", "Re-clone hydration targets even if already present").option("--dry-run", "Preview without writing or running anything").action(
+  (opts) => runWorktree("hydrate", { only: opts.only, force: opts.force, dryRun: opts.dryRun })
+);
+worktree.command("list").description("List materialized workspace worktrees and their member status").action(() => runWorktree("list"));
+worktree.command("remove <slug>").description("Remove a workspace worktree and its member worktrees").option("--force", "Bypass the uncommitted/unpushed-work refusal").option("--dry-run", "Preview without removing anything").action(
+  (slug, opts) => runWorktree("remove", { slug, force: opts.force, dryRun: opts.dryRun })
+);
+worktree.command("doctor").description("Fast, side-effect-free health check for the current workspace worktree").option("--from-hook", "Emit for the SessionStart hook \u2014 always exits 0").action((opts) => runWorktree("doctor", { fromHook: opts.fromHook }));
 program.parseAsync(process.argv).catch((err) => {
   const message = err instanceof Error ? err.message : String(err);
   error(message);