@haus-tech/haus-workflow 0.31.1 → 0.32.0

package/dist/cli.js

@@ -1,18 +1,74 @@
 #!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/utils/exec.ts
+var exec_exports = {};
+__export(exec_exports, {
+  commandExists: () => commandExists,
+  runCommand: () => runCommand,
+  runGit: () => runGit
+});
+import { execa } from "execa";
+async function runCommand(command, args = [], options = {}) {
+  try {
+    const result = await execa(command, args, {
+      reject: false,
+      // non-zero exits are returned, not thrown
+      ...options
+    });
+    return {
+      command,
+      args,
+      stdout: String(result.stdout ?? ""),
+      stderr: String(result.stderr ?? ""),
+      exitCode: result.exitCode ?? 0
+    };
+  } catch (error2) {
+    const message = error2 instanceof Error ? error2.message : String(error2);
+    throw new Error(`Failed to run command: ${command} ${args.join(" ")} (${message})`);
+  }
+}
+async function runGit(args, options = {}) {
+  return runCommand("git", args, options);
+}
+async function commandExists(command) {
+  try {
+    const result = await runCommand(command, ["--version"]);
+    return result.exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+var init_exec = __esm({
+  "src/utils/exec.ts"() {
+    "use strict";
+  }
+});
 
 // src/cli.ts
 import { readFileSync as readFileSync4 } from "node:fs";
-import path37 from "node:path";
+import path45 from "node:path";
 import { Command } from "commander";
 
 // src/commands/apply.ts
-import path14 from "node:path";
+import path17 from "node:path";
 import checkbox from "@inquirer/checkbox";
 
-// src/catalog/remote-catalog.ts
-import os from "node:os";
-import path2 from "node:path";
-import fs2 from "fs-extra";
+// src/catalog/load-catalog.ts
+import path4 from "node:path";
 
 // src/utils/fs.ts
 import crypto from "node:crypto";
@@ -90,6 +146,7 @@ async function listFiles(root, patterns) {
     cwd: root,
     dot: true,
     onlyFiles: true,
+    suppressErrors: true,
     ignore: ["**/node_modules/**", "**/.git/**", "**/dist/**"]
   });
   return files.sort((a, b) => a.localeCompare(b));
@@ -108,6 +165,57 @@ async function mapWithConcurrency(items, fn, concurrency = 24) {
   return results;
 }
 
+// src/utils/paths.ts
+import { existsSync, readFileSync } from "node:fs";
+import os from "node:os";
+import path2 from "node:path";
+import { fileURLToPath } from "node:url";
+var HAUS_DIR = ".haus-workflow";
+function hausPath(root, ...parts) {
+  return path2.join(root, HAUS_DIR, ...parts);
+}
+function claudePath(root, ...parts) {
+  return path2.join(root, ".claude", ...parts);
+}
+function displayPath(root, targetPath) {
+  const rel = path2.relative(root, targetPath).replace(/\\/g, "/");
+  if (rel && !rel.startsWith("../") && rel !== "..") {
+    return rel.startsWith("./") ? rel : `./${rel}`;
+  }
+  const home = os.homedir();
+  const normalized = targetPath.replace(/\\/g, "/");
+  if (home && home.trim().length > 0) {
+    const homeRel = path2.relative(home, targetPath).replace(/\\/g, "/");
+    if (homeRel && !homeRel.startsWith("../") && homeRel !== "..") {
+      return `~/${homeRel}`;
+    }
+  }
+  return normalized;
+}
+function packageRoot() {
+  let dir = path2.dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 12; i++) {
+    const pkgPath = path2.join(dir, "package.json");
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        if (pkg.name === "haus" || pkg.name === "@haus-tech/haus-workflow") return dir;
+      } catch {
+      }
+    }
+    const parent = path2.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  const file = fileURLToPath(import.meta.url);
+  return path2.resolve(path2.dirname(file), "../..");
+}
+
+// src/catalog/remote-catalog.ts
+import os2 from "node:os";
+import path3 from "node:path";
+import fs2 from "fs-extra";
+
 // src/utils/logger.ts
 var log = (msg, ...args) => {
   console.log(msg, ...args);
@@ -543,7 +651,7 @@ function parseManifest(json) {
 
 // src/catalog/remote-catalog.ts
 function getCacheDir() {
-  return process.env["HAUS_CATALOG_CACHE_DIR_OVERRIDE"] ?? path2.join(os.homedir(), CATALOG_CACHE_SUBDIR);
+  return process.env["HAUS_CATALOG_CACHE_DIR_OVERRIDE"] ?? path3.join(os2.homedir(), CATALOG_CACHE_SUBDIR);
 }
 var cachedCatalogRef;
 var cachedBlobPaths;
@@ -606,13 +714,13 @@ async function writeTextIfChanged(dest, text) {
     await fs2.writeFile(dest, text, "utf8");
     return "updated";
   }
-  await fs2.ensureDir(path2.dirname(dest));
+  await fs2.ensureDir(path3.dirname(dest));
   await fs2.writeFile(dest, text, "utf8");
   return "created";
 }
 var WORKFLOW_TEMPLATE_REL = "templates/agentic-workflow-standard.md";
 async function readWorkflowTemplate(opts = {}) {
-  const dest = path2.join(getCacheDir(), WORKFLOW_TEMPLATE_REL);
+  const dest = path3.join(getCacheDir(), WORKFLOW_TEMPLATE_REL);
   const base = await remoteBase();
   const text = await fetchText(`${base}/${WORKFLOW_TEMPLATE_REL}`);
   if (text === null) {
@@ -627,14 +735,14 @@ async function readWorkflowTemplate(opts = {}) {
   return text;
 }
 function isSafeCatalogPath(itemPath) {
-  if (!itemPath || path2.isAbsolute(itemPath) || itemPath.includes("\\")) return false;
-  const normalized = path2.normalize(itemPath);
+  if (!itemPath || path3.isAbsolute(itemPath) || itemPath.includes("\\")) return false;
+  const normalized = path3.normalize(itemPath);
   return !normalized.startsWith("..") && !normalized.includes("/..");
 }
 function isSafeRelativeFilePath(rel) {
   if (!rel || rel.startsWith("/") || rel.includes("\\") || rel.includes("//")) return false;
-  if (path2.isAbsolute(rel)) return false;
-  const normalized = path2.posix.normalize(rel.replace(/\\/g, "/"));
+  if (path3.isAbsolute(rel)) return false;
+  const normalized = path3.posix.normalize(rel.replace(/\\/g, "/"));
   return normalized !== ".." && !normalized.startsWith("../") && !normalized.includes("/../");
 }
 function githubApiHeaders() {
@@ -656,8 +764,8 @@ function sanitizeRelativeFilePaths(files, label) {
 }
 function safeJoin(base, itemPath) {
   if (!isSafeCatalogPath(itemPath)) return null;
-  const resolved = path2.resolve(base, itemPath);
-  return resolved.startsWith(base + path2.sep) || resolved === base ? resolved : null;
+  const resolved = path3.resolve(base, itemPath);
+  return resolved.startsWith(base + path3.sep) || resolved === base ? resolved : null;
 }
 var KNOWN_ITEM_TYPES = /* @__PURE__ */ new Set(["skill", "agent", "template", "command", "config"]);
 function isMarkdownPath(rel) {
@@ -665,13 +773,19 @@ function isMarkdownPath(rel) {
 }
 async function listFilesRecursive(dir, base = dir) {
   const out = [];
-  if (!await fs2.pathExists(dir)) return out;
-  for (const entry of await fs2.readdir(dir, { withFileTypes: true })) {
-    const full = path2.join(dir, entry.name);
+  let entries;
+  try {
+    if (!await fs2.pathExists(dir)) return out;
+    entries = await fs2.readdir(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    const full = path3.join(dir, entry.name);
     if (entry.isDirectory()) {
       out.push(...await listFilesRecursive(full, base));
     } else if (entry.isFile()) {
-      out.push(path2.relative(base, full).replace(/\\/g, "/"));
+      out.push(path3.relative(base, full).replace(/\\/g, "/"));
     }
   }
   return out.sort();
@@ -776,7 +890,7 @@ async function directoryMatchesFetched(destDir, fetched) {
     if (!relSet.has(rel)) return false;
   }
   for (const file of fetched) {
-    const dest = path2.join(destDir, file.rel);
+    const dest = path3.join(destDir, file.rel);
     if (!await fs2.pathExists(dest)) return false;
     if (file.kind === "text") {
       const local = await fs2.readFile(dest, "utf8");
@@ -794,8 +908,8 @@ async function writeFetchedDirectory(destDir, fetched) {
   }
   await fs2.ensureDir(destDir);
   for (const file of fetched) {
-    const dest = path2.join(destDir, file.rel);
-    await fs2.ensureDir(path2.dirname(dest));
+    const dest = path3.join(destDir, file.rel);
+    await fs2.ensureDir(path3.dirname(dest));
     if (file.kind === "text") {
       await fs2.writeFile(dest, file.body, "utf8");
     } else {
@@ -939,7 +1053,7 @@ async function syncOneItem(item, base) {
     return "failed";
   }
   const text = await fetchText(`${base}/${item.path}`);
-  if (!text) {
+  if (text === null) {
     warn(`Failed to fetch content for ${item.id}`);
     return "failed";
   }
@@ -967,7 +1081,7 @@ async function syncRemoteCatalog() {
   try {
     await fs2.ensureDir(cacheDir);
     await fs2.writeFile(
-      path2.join(cacheDir, "manifest.json"),
+      path3.join(cacheDir, "manifest.json"),
       `${JSON.stringify({ version, items }, null, 2)}
 `,
       "utf8"
@@ -1035,66 +1149,13 @@ async function fetchLatestCatalogTag() {
 }
 async function getCacheManifestAge() {
   try {
-    const stat = await fs2.stat(path2.join(getCacheDir(), "manifest.json"));
+    const stat = await fs2.stat(path3.join(getCacheDir(), "manifest.json"));
     return Date.now() - stat.mtimeMs;
   } catch {
     return null;
   }
 }
 
-// src/claude/write-claude-files.ts
-import path13 from "node:path";
-import fs13 from "fs-extra";
-
-// src/catalog/load-catalog.ts
-import path4 from "node:path";
-
-// src/utils/paths.ts
-import { existsSync, readFileSync } from "node:fs";
-import os2 from "node:os";
-import path3 from "node:path";
-import { fileURLToPath } from "node:url";
-var HAUS_DIR = ".haus-workflow";
-function hausPath(root, ...parts) {
-  return path3.join(root, HAUS_DIR, ...parts);
-}
-function claudePath(root, ...parts) {
-  return path3.join(root, ".claude", ...parts);
-}
-function displayPath(root, targetPath) {
-  const rel = path3.relative(root, targetPath).replace(/\\/g, "/");
-  if (rel && !rel.startsWith("../") && rel !== "..") {
-    return rel.startsWith("./") ? rel : `./${rel}`;
-  }
-  const home = os2.homedir();
-  const normalized = targetPath.replace(/\\/g, "/");
-  if (home && home.trim().length > 0) {
-    const homeRel = path3.relative(home, targetPath).replace(/\\/g, "/");
-    if (homeRel && !homeRel.startsWith("../") && homeRel !== "..") {
-      return `~/${homeRel}`;
-    }
-  }
-  return normalized;
-}
-function packageRoot() {
-  let dir = path3.dirname(fileURLToPath(import.meta.url));
-  for (let i = 0; i < 12; i++) {
-    const pkgPath = path3.join(dir, "package.json");
-    if (existsSync(pkgPath)) {
-      try {
-        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
-        if (pkg.name === "haus" || pkg.name === "@haus-tech/haus-workflow") return dir;
-      } catch {
-      }
-    }
-    const parent = path3.dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  const file = fileURLToPath(import.meta.url);
-  return path3.resolve(path3.dirname(file), "../..");
-}
-
 // src/catalog/load-catalog.ts
 async function loadCatalogContext(root) {
   const envPath = process.env["HAUS_FIXTURE_CATALOG"];
@@ -1137,6 +1198,10 @@ function catalogItemContentPath(contentRoot, item) {
   return path4.join(contentRoot, item.path);
 }
 
+// src/claude/write-claude-files.ts
+import path14 from "node:path";
+import fs14 from "fs-extra";
+
 // src/update/hash-installed.ts
 import path5 from "node:path";
 import fg2 from "fast-glob";
@@ -1660,8 +1725,8 @@ function buildDenyRules() {
   for (const command of DENY_COMMANDS) {
     rules.push(`Bash(${command}:*)`);
   }
-  for (const path38 of DENY_PATHS) {
-    const pattern = DENY_DIRS.has(path38) ? `${path38}/**` : path38;
+  for (const path46 of DENY_PATHS) {
+    const pattern = DENY_DIRS.has(path46) ? `${path46}/**` : path46;
     for (const tool of FILE_TOOLS) {
       rules.push(`${tool}(${pattern})`);
     }
@@ -1684,6 +1749,13 @@ var PROJECT_HOOK_FRAGMENTS = [
     event: "PreToolUse",
     matcher: "Bash",
     command: "haus guard bash --from-hook"
+  },
+  {
+    id: "haus.decisions-suggest",
+    gate: "keep",
+    event: "Stop",
+    matcher: "*",
+    command: "haus decisions suggest --from-hook"
   }
 ];
 async function readProjectSettings(root) {
@@ -1777,6 +1849,12 @@ var CANONICAL_HOOKS = {
         matcher: "Bash",
         hooks: [{ type: "command", command: "haus guard bash --from-hook" }]
       }
+    ],
+    Stop: [
+      {
+        matcher: "*",
+        hooks: [{ type: "command", command: "haus decisions suggest --from-hook" }]
+      }
     ]
   }
 };
@@ -1798,9 +1876,11 @@ function collectHookCommands(settings) {
 }
 function hausHookContractSatisfied(project, canonical) {
   const present = new Set(collectHookCommands(project));
-  for (const block of canonical.hooks.PreToolUse) {
-    for (const h of block.hooks) {
-      if (!present.has(h.command)) return false;
+  for (const blocks of Object.values(canonical.hooks)) {
+    for (const block of blocks ?? []) {
+      for (const h of block.hooks) {
+        if (!present.has(h.command)) return false;
+      }
     }
   }
   const denySet = new Set(project.permissions?.deny ?? []);
@@ -1851,9 +1931,62 @@ async function verifyProjectSettingsHooksContract(root) {
   return { ok: true, message: "settings.json carries required haus hook contract." };
 }
 
-// src/claude/write-prettierignore.ts
+// src/claude/write-decisions-seed.ts
 import path9 from "node:path";
 import fs8 from "fs-extra";
+
+// library/catalog/decisions-triggers.json
+var decisions_triggers_default = {
+  decisionsDir: "docs/decisions",
+  legacyDecisionsDir: "docs/adr",
+  pathGlobs: [
+    "**/package.json",
+    "**/pnpm-lock.yaml",
+    "**/yarn.lock",
+    "**/package-lock.json",
+    "**/migrations/**",
+    "**/prisma/schema.prisma",
+    "**/.github/workflows/**",
+    "**/Dockerfile*",
+    "**/docker-compose*.yml",
+    "**/terraform/**",
+    "**/openapi*.yaml",
+    "**/schema.graphql"
+  ],
+  securityPathGlobs: ["**/.env.example", "**/auth/**", "**/middleware/**"],
+  pathRegex: ["(^|/)src/.*/auth/", "(^|/)middleware/", "\\.env\\.example$"],
+  minFilesChanged: 8,
+  minLinesChanged: 200,
+  exemptGlobs: ["docs/**", "tests/**", "**/*.md", ".haus-workflow/**"],
+  requiredSections: ["## Context", "## Decision", "## Consequences"],
+  recommendedSections: ["## Motivation (why)", "## Alternatives considered"],
+  decisionFilePattern: "^\\d{4}-.+\\.md$"
+};
+
+// src/decisions/triggers.ts
+var DECISIONS_TRIGGERS = decisions_triggers_default;
+var DECISION_FILE_RE = new RegExp(DECISIONS_TRIGGERS.decisionFilePattern);
+
+// src/claude/write-decisions-seed.ts
+var SEED_README = `# Architecture Decision Records (ADRs)
+
+Why we chose X \u2014 short, dated, write-once decision log for humans and agents.
+
+| ADR | Title | Why (one line) | Status |
+| --- | ----- | -------------- | ------ |
+`;
+async function writeDecisionsSeed(root, dryRun) {
+  const decisionsDir = path9.join(root, DECISIONS_TRIGGERS.decisionsDir);
+  const readmePath = path9.join(decisionsDir, "README.md");
+  if (await fs8.pathExists(readmePath)) return null;
+  if (!dryRun) await fs8.ensureDir(decisionsDir);
+  await writeManagedText(root, readmePath, SEED_README, dryRun);
+  return readmePath;
+}
+
+// src/claude/write-prettierignore.ts
+import path10 from "node:path";
+import fs9 from "fs-extra";
 var PRETTIERIGNORE_BEGIN = "# HAUS:BEGIN haus-managed v=1";
 var PRETTIERIGNORE_END = "# HAUS:END haus-managed";
 var IGNORED_PATHS = [".haus-workflow/"];
@@ -1909,20 +2042,21 @@ ${block}
 `;
 }
 async function writePrettierIgnore(root, dryRun) {
-  const filePath = path9.join(root, ".prettierignore");
-  const prev = await fs8.pathExists(filePath) ? await fs8.readFile(filePath, "utf8") : "";
+  const filePath = path10.join(root, ".prettierignore");
+  const prev = await fs9.pathExists(filePath) ? await fs9.readFile(filePath, "utf8") : "";
   const next = injectPrettierIgnoreBlock(prev, buildPrettierIgnoreBlock());
   await writeManagedText(root, filePath, next, dryRun);
   return filePath;
 }
 
 // src/claude/write-root-claude-md.ts
-import path10 from "node:path";
-import fs9 from "fs-extra";
+import path11 from "node:path";
+import fs10 from "fs-extra";
 var BLOCK_BEGIN = "<!-- HAUS:BEGIN haus-imports v=1 -->";
 var BLOCK_END = "<!-- HAUS:END haus-imports -->";
 var IMPORT_CONTENT = `@.haus-workflow/WORKFLOW.md
-@.haus-workflow/workflow-config.md`;
+@.haus-workflow/workflow-config.md
+@docs/decisions/README.md`;
 function buildImportBlock() {
   return `${BLOCK_BEGIN}
 ${IMPORT_CONTENT}
@@ -1983,21 +2117,21 @@ ${block}
 `;
 }
 async function writeRootClaudeMd(root, dryRun) {
-  const filePath = path10.join(root, "CLAUDE.md");
+  const filePath = path11.join(root, "CLAUDE.md");
   const block = buildImportBlock();
-  const prev = await fs9.pathExists(filePath) ? await fs9.readFile(filePath, "utf8") : "";
+  const prev = await fs10.pathExists(filePath) ? await fs10.readFile(filePath, "utf8") : "";
   const next = injectHausBlock(prev, block);
   await writeManagedText(root, filePath, next, dryRun);
   return filePath;
 }
 
 // src/claude/write-workflow-config.ts
-import path12 from "node:path";
-import fs11 from "fs-extra";
+import path13 from "node:path";
+import fs12 from "fs-extra";
 
 // src/claude/derive-workflow-config.ts
-import path11 from "node:path";
-import fs10 from "fs-extra";
+import path12 from "node:path";
+import fs11 from "fs-extra";
 function binCmd(pm, bin, args) {
   const tail = args ? ` ${args}` : "";
   if (pm === "yarn") return `yarn ${bin}${tail}`;
@@ -2006,7 +2140,7 @@ function binCmd(pm, bin, args) {
 }
 async function deriveWorkflowConfig(root, ctx) {
   const pm = ctx.packageManager === "unknown" ? "npm" : ctx.packageManager;
-  const pkg = await readJson(path11.join(root, "package.json"));
+  const pkg = await readJson(path12.join(root, "package.json"));
   const scripts = pkg?.scripts ?? {};
   const deps = new Set(ctx.dependencies);
   const stacks = Object.values(ctx.detectedStacks ?? {}).flat();
@@ -2016,7 +2150,7 @@ async function deriveWorkflowConfig(root, ctx) {
     return null;
   };
   const hasDep = (name) => deps.has(name);
-  const exists = (rel) => fs10.pathExistsSync(path11.join(root, rel));
+  const exists = (rel) => fs11.pathExistsSync(path12.join(root, rel));
   const hasPlaywright = hasDep("@playwright/test") || stacks.includes("playwright");
   const hasCypress = hasDep("cypress");
   const preCommitTool = exists("lefthook.yml") || exists("lefthook.yaml") ? "lefthook" : exists(".husky") || hasDep("husky") || (scripts.prepare ?? "").includes("husky") ? "husky" : exists(".pre-commit-config.yaml") ? "pre-commit (Python framework)" : null;
@@ -2084,7 +2218,7 @@ var FALLBACK_CONTEXT = {
 async function writeWorkflowConfig(root, dryRun, opts = {}) {
   const destPath = hausPath(root, "workflow-config.md");
   const printable = displayPath(root, destPath);
-  const exists = await fs11.pathExists(destPath);
+  const exists = await fs12.pathExists(destPath);
   if (exists && !opts.refill) {
     if (dryRun) log(printable + ": exists (project-owned, skipping)");
     return null;
@@ -2092,11 +2226,11 @@ async function writeWorkflowConfig(root, dryRun, opts = {}) {
   const ctx = await readJson(hausPath(root, "context-map.json")) ?? {
     ...FALLBACK_CONTEXT,
     root,
-    repoName: path12.basename(root)
+    repoName: path13.basename(root)
   };
   const values = await deriveWorkflowConfig(root, ctx);
   if (exists) {
-    const current = await fs11.readFile(destPath, "utf8");
+    const current = await fs12.readFile(destPath, "utf8");
     const refilled = refillContent(current, values);
     if (refilled === current) {
       if (dryRun) log(printable + ": no blank fields to refill");
@@ -2118,7 +2252,7 @@ async function writeWorkflowConfig(root, dryRun, opts = {}) {
 }
 
 // src/claude/write-workflow.ts
-import fs12 from "fs-extra";
+import fs13 from "fs-extra";
 var STABLE_ID = "template.workflow";
 function makeWorkflowHeader(pkgVersion, contentHash) {
   return `<!-- HAUS-MANAGED id=${STABLE_ID} v=${SCHEMA_VERSION} source=@haus-tech/haus-workflow@${pkgVersion} hash=${contentHash} -->`;
@@ -2137,8 +2271,8 @@ async function writeWorkflow(root, pkgVersion, dryRun, force = false) {
 ${templateContent}`;
   const destPath = hausPath(root, "WORKFLOW.md");
   const printable = displayPath(root, destPath);
-  if (await fs12.pathExists(destPath)) {
-    const existing = await fs12.readFile(destPath, "utf8");
+  if (await fs13.pathExists(destPath)) {
+    const existing = await fs13.readFile(destPath, "utf8");
     const firstLine = existing.split("\n")[0] ?? "";
     const parsed = parseHausManagedHeader(firstLine);
     if (!parsed) {
@@ -2172,7 +2306,7 @@ ${templateContent}`;
     }
   }
   if (dryRun) {
-    const prev = await fs12.pathExists(destPath) ? await fs12.readFile(destPath, "utf8") : "";
+    const prev = await fs13.pathExists(destPath) ? await fs13.readFile(destPath, "utf8") : "";
     if (!prev) {
       log(createUnifiedDiff(printable, "", next));
     } else {
@@ -2195,6 +2329,8 @@ function targetDirForType(type) {
   return null;
 }
 async function writeClaudeFiles(root, dryRun, selectedIds, opts = {}) {
+  const say = opts.quiet ? () => {
+  } : log;
   const rec = await readJson(hausPath(root, "recommendation.json")) ?? {
     recommended: [],
     skipped: [],
@@ -2205,13 +2341,14 @@ async function writeClaudeFiles(root, dryRun, selectedIds, opts = {}) {
     estimatedTokenReductionPct: 0
   };
   const pkgRoot = packageRoot();
-  const hausVersion2 = (await readJson(path13.join(pkgRoot, "package.json")))?.version ?? "0.0.0";
+  const hausVersion2 = (await readJson(path14.join(pkgRoot, "package.json")))?.version ?? "0.0.0";
   const coreFiles = [
     claudePath(root, "settings.json"),
     claudePath(root, "rules", "haus.md"),
     claudePath(root, "commands", "haus-doctor.md")
   ];
   const rootClaudeMdPath = await writeRootClaudeMd(root, dryRun);
+  const decisionsSeedPath = await writeDecisionsSeed(root, dryRun);
   const workflowPath = await writeWorkflow(root, hausVersion2, dryRun, opts.force);
   const workflowConfigPath = await writeWorkflowConfig(root, dryRun, {
     refill: opts.refillConfig
@@ -2219,6 +2356,7 @@ async function writeClaudeFiles(root, dryRun, selectedIds, opts = {}) {
   const prettierIgnorePath = await writePrettierIgnore(root, dryRun);
   const p6Files = [
     rootClaudeMdPath,
+    ...decisionsSeedPath ? [decisionsSeedPath] : [],
     ...workflowPath ? [workflowPath] : [],
     ...workflowConfigPath ? [workflowConfigPath] : [],
     prettierIgnorePath
@@ -2238,16 +2376,16 @@ async function writeClaudeFiles(root, dryRun, selectedIds, opts = {}) {
     dryRun
   );
   const legacyReviewPath = claudePath(root, "commands", "haus-review.md");
-  if (await fs13.pathExists(legacyReviewPath)) {
-    const content2 = await fs13.readFile(legacyReviewPath, "utf8");
+  if (await fs14.pathExists(legacyReviewPath)) {
+    const content2 = await fs14.readFile(legacyReviewPath, "utf8");
     const stub = 'Run `haus context --task "code review"` then review diff.';
     if (content2 === stub || content2 === `${stub}
 ` || content2 === `${stub}\r
 `) {
       if (dryRun) {
-        log(`[dry-run] would remove stale ${displayPath(root, legacyReviewPath)}`);
+        say(`[dry-run] would remove stale ${displayPath(root, legacyReviewPath)}`);
       } else {
-        await fs13.remove(legacyReviewPath);
+        await fs14.remove(legacyReviewPath);
       }
     }
   }
@@ -2275,16 +2413,16 @@ async function writeClaudeFiles(root, dryRun, selectedIds, opts = {}) {
     dryRun
   );
   const legacySecurityPath = claudePath(root, "rules", "security.md");
-  if (await fs13.pathExists(legacySecurityPath)) {
-    const content2 = await fs13.readFile(legacySecurityPath, "utf8");
+  if (await fs14.pathExists(legacySecurityPath)) {
+    const content2 = await fs14.readFile(legacySecurityPath, "utf8");
     const stub = "- Never read secrets.\n- Block dangerous shell commands.";
     if (content2 === stub || content2 === `${stub}
 ` || content2 === `${stub}\r
 `) {
       if (dryRun) {
-        log(`[dry-run] would remove stale ${displayPath(root, legacySecurityPath)}`);
+        say(`[dry-run] would remove stale ${displayPath(root, legacySecurityPath)}`);
       } else {
-        await fs13.remove(legacySecurityPath);
+        await fs14.remove(legacySecurityPath);
       }
     }
   }
@@ -2299,11 +2437,11 @@ async function writeClaudeFiles(root, dryRun, selectedIds, opts = {}) {
   ];
   for (const rel of LEGACY_PRUNED_ARTIFACTS) {
     const legacyPath = hausPath(root, rel);
-    if (await fs13.pathExists(legacyPath)) {
+    if (await fs14.pathExists(legacyPath)) {
       if (dryRun) {
-        log(`[dry-run] would remove stale ${displayPath(root, legacyPath)}`);
+        say(`[dry-run] would remove stale ${displayPath(root, legacyPath)}`);
       } else {
-        await fs13.remove(legacyPath);
+        await fs14.remove(legacyPath);
       }
     }
   }
@@ -2345,11 +2483,11 @@ async function writeClaudeFiles(root, dryRun, selectedIds, opts = {}) {
       );
       continue;
     }
-    const destination = claudePath(root, target, path13.basename(sourcePath));
-    if (await fs13.pathExists(sourcePath)) {
+    const destination = claudePath(root, target, path14.basename(sourcePath));
+    if (await fs14.pathExists(sourcePath)) {
       if (dryRun) {
-        const exists = await fs13.pathExists(destination);
-        log(
+        const exists = await fs14.pathExists(destination);
+        say(
           `${displayPath(root, destination)}: ${exists ? "would overwrite" : "would create"} (${item.id})`
         );
       } else if (item.type === "skill") {
@@ -2358,17 +2496,17 @@ async function writeClaudeFiles(root, dryRun, selectedIds, opts = {}) {
           dryRun: false
         });
       } else {
-        await fs13.ensureDir(path13.dirname(destination));
-        await fs13.copy(sourcePath, destination, { overwrite: true, errorOnExist: false });
+        await fs14.ensureDir(path14.dirname(destination));
+        await fs14.copy(sourcePath, destination, { overwrite: true, errorOnExist: false });
       }
       files.push(destination);
-      const relPaths = [path13.relative(root, destination)];
+      const relPaths = [path14.relative(root, destination)];
       if (!superpowersSharedInstalled && manifestItem.originSourceId === SUPERPOWERS_ORIGIN_SOURCE_ID && item.type === "skill") {
         const sharedRel = await installSuperpowersShared(contentRoot, root, dryRun);
         if (sharedRel) {
           superpowersSharedInstalled = true;
           relPaths.push(sharedRel);
-          files.push(path13.join(root, sharedRel));
+          files.push(path14.join(root, sharedRel));
         }
       }
       const current = installedPathsByItem.get(item.id) ?? [];
@@ -2385,7 +2523,7 @@ async function writeClaudeFiles(root, dryRun, selectedIds, opts = {}) {
       `${curatedReviewStatusSkips} curated items skipped: reviewStatus is not approved \u2014 possible catalog field rename upstream`
     );
   }
-  await cleanupStaleCatalogItems(root, manifestById, dryRun);
+  await cleanupStaleCatalogItems(root, manifestById, dryRun, opts.quiet);
   if (dryRun) return [...new Set(files)];
   const installedItems = catalogItems.filter((r) => installedIds.has(r.id));
   const prevLock = await readJson(hausPath(root, "haus.lock.json"));
@@ -2422,7 +2560,9 @@ async function writeClaudeFiles(root, dryRun, selectedIds, opts = {}) {
   await writeManagedJson(root, hausPath(root, "haus.lock.json"), lock, false);
   return [...new Set(files)];
 }
-async function cleanupStaleCatalogItems(root, manifestById, dryRun) {
+async function cleanupStaleCatalogItems(root, manifestById, dryRun, quiet) {
+  const say = quiet ? () => {
+  } : log;
   const prevLock = await readJson(hausPath(root, "haus.lock.json"));
   if (!prevLock?.length) return;
   for (const entry of prevLock) {
@@ -2435,7 +2575,7 @@ async function cleanupStaleCatalogItems(root, manifestById, dryRun) {
     if (relPaths.length === 0) continue;
     const existing = [];
     for (const rel of relPaths) {
-      if (await fs13.pathExists(path13.join(root, rel))) existing.push(rel);
+      if (await fs14.pathExists(path14.join(root, rel))) existing.push(rel);
     }
     if (existing.length === 0) continue;
     const pruneReason = deprecated ? "deprecated" : "stale";
@@ -2453,18 +2593,115 @@ async function cleanupStaleCatalogItems(root, manifestById, dryRun) {
       continue;
     }
     for (const rel of existing) {
-      const abs = path13.join(root, rel);
+      const abs = path14.join(root, rel);
       if (dryRun) {
-        log(`[dry-run] would remove ${pruneReason} ${displayPath(root, abs)} (${entry.id})`);
+        say(`[dry-run] would remove ${pruneReason} ${displayPath(root, abs)} (${entry.id})`);
         continue;
       }
-      await fs13.remove(abs);
-      await pruneEmptyDir(path13.dirname(abs));
-      log(`Removed ${pruneReason} ${displayPath(root, abs)} (${entry.id})`);
+      await fs14.remove(abs);
+      await pruneEmptyDir(path14.dirname(abs));
+      say(`Removed ${pruneReason} ${displayPath(root, abs)} (${entry.id})`);
     }
   }
 }
 
+// src/refs/fetch-refs.ts
+import path16 from "node:path";
+import fs16 from "fs-extra";
+
+// src/refs/cache-meta.ts
+import path15 from "node:path";
+import fs15 from "fs-extra";
+var META_FILENAME = "cache-meta.json";
+async function readCacheMeta(cacheDir) {
+  const metaPath = path15.join(cacheDir, META_FILENAME);
+  try {
+    const raw = await fs15.readFile(metaPath, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+async function writeCacheMeta(cacheDir, meta) {
+  await fs15.ensureDir(cacheDir);
+  const metaPath = path15.join(cacheDir, META_FILENAME);
+  await fs15.writeFile(metaPath, JSON.stringify(meta, null, 2) + "\n", "utf8");
+}
+
+// src/refs/fetch-refs.ts
+function urlToSlug(url) {
+  const u = new URL(url);
+  return (u.host + u.pathname).replace(/[^a-zA-Z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").toLowerCase();
+}
+function isLlmsTxtUrl(ref) {
+  try {
+    const u = new URL(ref);
+    return (u.protocol === "https:" || u.protocol === "http:") && u.pathname.endsWith("/llms.txt");
+  } catch {
+    return false;
+  }
+}
+async function fetchSingleRef(url, cacheDir, meta) {
+  const existing = meta[url];
+  const headers = {};
+  const safeFile = existing?.file && existing.file === path16.basename(existing.file);
+  const cachedFileExists = safeFile && await fs16.pathExists(path16.join(cacheDir, existing.file));
+  if (cachedFileExists) {
+    if (existing?.etag) headers["If-None-Match"] = existing.etag;
+    if (existing?.lastModified) headers["If-Modified-Since"] = existing.lastModified;
+  }
+  try {
+    const res = await fetch(url, { headers, signal: AbortSignal.timeout(1e4) });
+    if (res.status === 304) return { result: "unchanged" };
+    if (!res.ok) return { result: "failed" };
+    const text = await res.text();
+    const file = `${urlToSlug(url)}.md`;
+    await fs16.ensureDir(cacheDir);
+    await fs16.writeFile(path16.join(cacheDir, file), text, "utf8");
+    meta[url] = {
+      url,
+      etag: res.headers.get("etag") ?? void 0,
+      lastModified: res.headers.get("last-modified") ?? void 0,
+      fetchedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      file
+    };
+    return { result: "fetched", file };
+  } catch {
+    return { result: "failed" };
+  }
+}
+async function fetchRefsForItems(items, cacheDir) {
+  const urls = [...new Set(items.flatMap((item) => (item.references ?? []).filter(isLlmsTxtUrl)))];
+  const summary = {
+    fetched: 0,
+    unchanged: 0,
+    failed: 0,
+    failedUrls: [],
+    cachedFiles: {}
+  };
+  if (urls.length === 0) return summary;
+  const meta = await readCacheMeta(cacheDir);
+  await Promise.all(
+    urls.map(async (url) => {
+      const outcome = await fetchSingleRef(url, cacheDir, meta);
+      if (outcome.result === "fetched") {
+        summary.fetched++;
+        summary.cachedFiles[url] = path16.join(cacheDir, outcome.file);
+      } else if (outcome.result === "unchanged") {
+        summary.unchanged++;
+        if (meta[url]?.file) summary.cachedFiles[url] = path16.join(cacheDir, meta[url].file);
+      } else {
+        summary.failed++;
+        summary.failedUrls.push(url);
+      }
+    })
+  );
+  if (summary.fetched > 0) {
+    await writeCacheMeta(cacheDir, meta);
+  }
+  return summary;
+}
+
 // src/utils/args.ts
 function parseIdList(value) {
   if (!value) return [];
@@ -2474,7 +2711,7 @@ function parseIdList(value) {
 
 // src/commands/apply.ts
 async function cacheHasItems() {
-  const data = await readJson(path14.join(getCacheDir(), "manifest.json"));
+  const data = await readJson(path17.join(getCacheDir(), "manifest.json"));
   return Array.isArray(data?.items) && data.items.length > 0;
 }
 function installableRecommendedItems(recommended) {
@@ -2566,6 +2803,23 @@ async function runApply(options) {
     refillConfig: options.refillConfig,
     force: options.force
   });
+  if (!isDryRun) {
+    try {
+      const cacheDir = hausPath(root, "llms-cache");
+      const allItems = await loadCatalog(root);
+      const summary = await fetchRefsForItems(allItems, cacheDir);
+      if (summary.fetched > 0)
+        log(`Fetched ${summary.fetched} llms.txt reference(s) to ${cacheDir}`);
+      if (summary.failed > 0)
+        warn(
+          `Failed to fetch ${summary.failed} llms.txt reference(s): ${summary.failedUrls.join(", ")}`
+        );
+    } catch (err) {
+      warn(
+        `Could not fetch llms.txt references: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
   if (isDryRun) {
     log(`Dry-run complete \u2014 ${files.length} file(s) planned, none written. Run --write to apply.`);
   } else {
@@ -2579,7 +2833,7 @@ function auditForbiddenTags(items) {
   const failures = [];
   const forbidden = new Set(FORBIDDEN_TAGS.map((w) => w.toLowerCase()));
   for (const item of items) {
-    for (const tag of item.tags) {
+    for (const tag of Array.isArray(item.tags) ? item.tags : []) {
       if (forbidden.has(tag.toLowerCase())) failures.push(`${item.id} has unsupported tag ${tag}`);
     }
     for (const token of item.id.toLowerCase().split(/[^a-z0-9+]+/)) {
@@ -2600,84 +2854,509 @@ async function runCatalogAudit() {
 }
 
 // src/commands/clone.ts
+init_exec();
 import { existsSync as existsSync2 } from "node:fs";
-import path15 from "node:path";
+import path18 from "node:path";
+var GIT_LOCATION_VARS = [
+  "GIT_DIR",
+  "GIT_WORK_TREE",
+  "GIT_INDEX_FILE",
+  "GIT_COMMON_DIR",
+  "GIT_OBJECT_DIRECTORY",
+  "GIT_NAMESPACE",
+  "GIT_PREFIX"
+];
+function cloneEnv() {
+  const env = { ...process.env };
+  for (const key of GIT_LOCATION_VARS) delete env[key];
+  return env;
+}
+function repoNameFromUrl(url) {
+  const trimmed = url.trim().replace(/\.git$/, "").replace(/\/+$/, "");
+  const tail = trimmed.split(/[/:]/).pop() ?? "";
+  return tail || "repo";
+}
+async function runClone(url, opts = {}) {
+  if (!url || !url.trim()) {
+    error("A git URL is required: `haus clone <url> [dir]`.");
+    process.exitCode = 1;
+    return;
+  }
+  const target = path18.resolve(opts.dir?.trim() || repoNameFromUrl(url));
+  if (existsSync2(target)) {
+    log(`\u2022 ${path18.basename(target)} already present at ${target} \u2014 skipped`);
+    return;
+  }
+  if (opts.dryRun) {
+    log(`would clone ${url} \u2192 ${target}`);
+    return;
+  }
+  const res = await runGit(["clone", "--", url, target], { env: cloneEnv(), extendEnv: false });
+  if (res.exitCode !== 0) {
+    error(`clone failed for ${url}: ${(res.stderr || res.stdout).trim()}`);
+    process.exitCode = 1;
+    return;
+  }
+  log(`\u2713 cloned ${url} \u2192 ${target}`);
+}
 
-// src/utils/exec.ts
-import { execa } from "execa";
-async function runCommand(command, args = [], options = {}) {
-  try {
-    const result = await execa(command, args, {
-      reject: false,
-      // non-zero exits are returned, not thrown
-      ...options
-    });
+// src/commands/decisions.ts
+import path22 from "node:path";
+
+// src/decisions/check.ts
+import path21 from "node:path";
+import fs19 from "fs-extra";
+
+// src/decisions/diff.ts
+init_exec();
+async function collectDiffStats(root, opts) {
+  const gitArgs = opts.staged ? ["diff", "--cached", "--name-only"] : ["diff", "--name-only", opts.range ?? "HEAD"];
+  const names = await runGit(gitArgs, { cwd: root });
+  const files = names.stdout.split("\n").map((f) => f.trim()).filter(Boolean);
+  const numstatArgs = opts.staged ? ["diff", "--cached", "--numstat"] : ["diff", "--numstat", opts.range ?? "HEAD"];
+  const numstat = await runGit(numstatArgs, { cwd: root });
+  let linesAdded = 0;
+  let linesRemoved = 0;
+  for (const line2 of numstat.stdout.split("\n")) {
+    const parts = line2.trim().split(/\s+/);
+    if (parts.length < 3) continue;
+    const added = parts[0] === "-" ? 0 : Number(parts[0]);
+    const removed = parts[1] === "-" ? 0 : Number(parts[1]);
+    if (!Number.isNaN(added)) linesAdded += added;
+    if (!Number.isNaN(removed)) linesRemoved += removed;
+  }
+  return { files, linesAdded, linesRemoved };
+}
+
+// src/decisions/match.ts
+function segmentToRegex(segment) {
+  if (segment === "**") return ".*";
+  return segment.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*");
+}
+function globToRegExp(pattern) {
+  const pat = pattern.replace(/\\/g, "/");
+  if (pat.startsWith("**/") && pat.endsWith("/**")) {
+    const middle = pat.slice(3, -3);
+    const midRe = middle.split("/").map(segmentToRegex).join("/");
+    return new RegExp(`(^|/)${midRe}(/|$)`);
+  }
+  if (pat.startsWith("**/")) {
+    const rest = pat.slice(3).split("/").map(segmentToRegex).join("/");
+    return new RegExp(`^(?:.*/)?${rest}$`);
+  }
+  const reSource = pat.split("/").map(segmentToRegex).join("/");
+  return new RegExp(`^${reSource}$`);
+}
+function matchesPathGlob(filePath, pattern) {
+  const norm = filePath.replace(/\\/g, "/");
+  return globToRegExp(pattern).test(norm);
+}
+function matchesAnyGlob(filePath, patterns) {
+  return patterns.some((p) => matchesPathGlob(filePath, p));
+}
+function matchesAnyRegex(filePath, patterns) {
+  const norm = filePath.replace(/\\/g, "/");
+  return patterns.some((p) => new RegExp(p).test(norm));
+}
+
+// src/decisions/paths.ts
+import path19 from "node:path";
+import fs17 from "fs-extra";
+async function resolveDecisionsDir(root) {
+  const primary = path19.join(root, DECISIONS_TRIGGERS.decisionsDir);
+  if (await fs17.pathExists(primary)) return primary;
+  const legacy = path19.join(root, DECISIONS_TRIGGERS.legacyDecisionsDir ?? "docs/adr");
+  if (await fs17.pathExists(legacy)) return legacy;
+  return primary;
+}
+function relativeDecisionPath(decisionsDir, root) {
+  return path19.relative(root, decisionsDir).replace(/\\/g, "/");
+}
+
+// src/decisions/validate.ts
+import path20 from "node:path";
+import fs18 from "fs-extra";
+function validateDecisionContent(content2) {
+  const errors = [];
+  for (const section of DECISIONS_TRIGGERS.requiredSections) {
+    if (!content2.includes(section)) {
+      errors.push(`missing required section: ${section}`);
+    }
+  }
+  if (!/^#\s+ADR-\d{4}:/m.test(content2)) {
+    errors.push('heading must match "# ADR-NNNN: Title"');
+  }
+  return errors.length === 0 ? { ok: true } : { ok: false, errors };
+}
+function indexReferencesNumber(readme, number) {
+  const padded = number.padStart(4, "0");
+  return readme.includes(`[${padded}]`) || readme.includes(`(${padded}-`) || readme.includes(`ADR-${padded}`);
+}
+async function validateDecisionFile(filePath) {
+  const content2 = await readText(filePath) ?? "";
+  return validateDecisionContent(content2);
+}
+function isDecisionFileName(name) {
+  return DECISION_FILE_RE.test(name);
+}
+function decisionNumberFromFile(name) {
+  const match = /^(\d{4})-/.exec(name);
+  return match?.[1] ?? null;
+}
+async function validateIndexSync(decisionsDir, decisionFiles) {
+  const readmePath = path20.join(decisionsDir, "README.md");
+  if (!await fs18.pathExists(readmePath)) {
+    return ["docs/decisions/README.md is missing"];
+  }
+  const readme = await readText(readmePath) ?? "";
+  const errors = [];
+  for (const file of decisionFiles) {
+    const num = decisionNumberFromFile(path20.basename(file));
+    if (num && !indexReferencesNumber(readme, num)) {
+      errors.push(`README.md missing index row for ADR-${num}`);
+    }
+  }
+  return errors;
+}
+
+// src/decisions/check.ts
+function isExempt(file) {
+  return matchesAnyGlob(file, DECISIONS_TRIGGERS.exemptGlobs);
+}
+function countTopLevelDirs(files) {
+  const dirs = /* @__PURE__ */ new Set();
+  for (const f of files) {
+    const parts = f.split("/");
+    if (parts.length > 1) dirs.add(parts[0]);
+  }
+  return dirs.size;
+}
+function isDecisionTriggered(stats) {
+  const relevant = stats.files.filter((f) => !isExempt(f));
+  if (relevant.length === 0) return false;
+  for (const file of relevant) {
+    if (matchesAnyGlob(file, DECISIONS_TRIGGERS.pathGlobs)) return true;
+    if (matchesAnyRegex(file, DECISIONS_TRIGGERS.pathRegex)) return true;
+  }
+  const totalLines = stats.linesAdded + stats.linesRemoved;
+  if (relevant.length >= DECISIONS_TRIGGERS.minFilesChanged && countTopLevelDirs(relevant) >= 2) {
+    return true;
+  }
+  if (totalLines >= DECISIONS_TRIGGERS.minLinesChanged && relevant.some((f) => !f.startsWith("docs/"))) {
+    return true;
+  }
+  return false;
+}
+function isSecurityTriggered(stats) {
+  const relevant = stats.files.filter((f) => !isExempt(f));
+  const security = DECISIONS_TRIGGERS.securityPathGlobs ?? [];
+  return relevant.some(
+    (f) => matchesAnyGlob(f, security) || matchesAnyRegex(f, DECISIONS_TRIGGERS.pathRegex)
+  );
+}
+async function readGateMode(root) {
+  const cfg = await readJson(hausPath(root, "adr-gate.json"));
+  return cfg?.mode === "off" ? "off" : "on";
+}
+function hasSkipToken(text) {
+  return text.includes("[adr-skip]");
+}
+async function checkSatisfaction(input2) {
+  const errors = [];
+  const decisionsPrefix = `${input2.decisionsRel}/`;
+  const newDecisionFiles = input2.changedFiles.filter(
+    (f) => f.startsWith(decisionsPrefix) && isDecisionFileName(path21.basename(f))
+  );
+  if (newDecisionFiles.length === 0) {
+    errors.push(`no new or updated decision under ${input2.decisionsRel}/`);
+    return errors;
+  }
+  const decisionsDir = path21.join(input2.root, input2.decisionsRel);
+  for (const rel of newDecisionFiles) {
+    const abs = path21.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) => path21.basename(f))
+  );
+  errors.push(...indexErrors);
+  return errors;
+}
+async function runDecisionsCheck(root, opts = {}) {
+  const reasons = [];
+  if (await readGateMode(root) === "off") {
+    return {
+      triggered: false,
+      satisfied: true,
+      reasons: ["gate disabled via .haus-workflow/adr-gate.json"],
+      securityTriggered: false
+    };
+  }
+  const stats = await collectDiffStats(root, opts);
+  const triggered = isDecisionTriggered(stats);
+  const securityTriggered = isSecurityTriggered(stats);
+  if (!triggered) {
     return {
-      command,
-      args,
-      stdout: String(result.stdout ?? ""),
-      stderr: String(result.stderr ?? ""),
-      exitCode: result.exitCode ?? 0
+      triggered: false,
+      satisfied: true,
+      reasons: ["no decision-worthy changes"],
+      securityTriggered
+    };
+  }
+  const skipText = `${opts.prBody ?? ""}
+${opts.commitMessages ?? ""}`;
+  if (hasSkipToken(skipText) && !securityTriggered) {
+    reasons.push("[adr-skip] present \u2014 gate waived (non-security change)");
+    return { triggered: true, satisfied: true, reasons, securityTriggered };
+  }
+  if (hasSkipToken(skipText) && securityTriggered) {
+    reasons.push("[adr-skip] ignored for security/auth path changes");
+  }
+  const decisionsDir = await resolveDecisionsDir(root);
+  const decisionsRel = relativeDecisionPath(decisionsDir, root);
+  const legacyRel = DECISIONS_TRIGGERS.legacyDecisionsDir ?? "docs/adr";
+  let satisfactionErrors = await checkSatisfaction({
+    root,
+    decisionsRel,
+    changedFiles: stats.files
+  });
+  if (satisfactionErrors.length > 0 && decisionsRel !== legacyRel) {
+    const legacyExists = await fs19.pathExists(path21.join(root, legacyRel));
+    if (legacyExists && !await fs19.pathExists(decisionsDir)) {
+      satisfactionErrors = await checkSatisfaction({
+        root,
+        decisionsRel: legacyRel,
+        changedFiles: stats.files
+      });
+    }
+  }
+  if (satisfactionErrors.length === 0) {
+    return {
+      triggered: true,
+      satisfied: true,
+      reasons: ["decision record present"],
+      securityTriggered
     };
-  } catch (error2) {
-    const message = error2 instanceof Error ? error2.message : String(error2);
-    throw new Error(`Failed to run command: ${command} ${args.join(" ")} (${message})`);
   }
+  reasons.push(...satisfactionErrors);
+  return { triggered: true, satisfied: false, reasons, securityTriggered };
 }
-async function runGit(args, options = {}) {
-  return runCommand("git", args, options);
+async function listDecisionNumbers(decisionsDir) {
+  if (!await fs19.pathExists(decisionsDir)) return [];
+  const entries = await fs19.readdir(decisionsDir);
+  return entries.map((name) => decisionNumberFromFile(name)).filter((n) => n != null).map((n) => Number(n));
 }
 
-// src/commands/clone.ts
-var GIT_LOCATION_VARS = [
-  "GIT_DIR",
-  "GIT_WORK_TREE",
-  "GIT_INDEX_FILE",
-  "GIT_COMMON_DIR",
-  "GIT_OBJECT_DIRECTORY",
-  "GIT_NAMESPACE",
-  "GIT_PREFIX"
-];
-function cloneEnv() {
-  const env = { ...process.env };
-  for (const key of GIT_LOCATION_VARS) delete env[key];
-  return env;
+// src/decisions/next-number.ts
+async function nextDecisionNumber(root) {
+  const decisionsDir = await resolveDecisionsDir(root);
+  const numbers = await listDecisionNumbers(decisionsDir);
+  const max = numbers.length === 0 ? 0 : Math.max(...numbers);
+  return String(max + 1).padStart(4, "0");
 }
-function repoNameFromUrl(url) {
-  const trimmed = url.trim().replace(/\.git$/, "").replace(/\/+$/, "");
-  const tail = trimmed.split(/[/:]/).pop() ?? "";
-  return tail || "repo";
+
+// src/decisions/suggest.ts
+function draftTemplate(number, title) {
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  return `# ADR-${number}: ${title}
+
+- **Status:** Proposed
+- **Date:** ${today}
+- **Decided by:** _(pending approval)_ (draft by haus decisions suggest)
+- **Affects:** _(paths/components)_
+- **Related:** _(PR/issue link)_
+
+## Context
+
+_(What problem or situation triggered this decision?)_
+
+## Decision
+
+_(One clear sentence: what we chose.)_
+
+## Motivation (why)
+
+_(Why this over alternatives \u2014 the line agents read for "why".)_
+
+## Alternatives considered
+
+- _(Alternative)_ \u2014 rejected because _(reason)_.
+
+## Consequences
+
+- _(Positive and negative follow-ons.)_
+`;
 }
-async function runClone(url, opts = {}) {
-  if (!url || !url.trim()) {
-    error("A git URL is required: `haus clone <url> [dir]`.");
-    process.exitCode = 1;
+async function runDecisionsSuggest(root, opts = {}) {
+  const stats = await collectDiffStats(root, { staged: true });
+  const stagedCheck = await runDecisionsCheck(root, { staged: true });
+  const unstagedStats = await collectDiffStats(root, {});
+  const triggered = isDecisionTriggered(stats) || isDecisionTriggered(unstagedStats);
+  if (!triggered) return;
+  if (stagedCheck.triggered && stagedCheck.satisfied) return;
+  const number = await nextDecisionNumber(root);
+  const title = opts.title ?? "Decision from current changes";
+  const draft = draftTemplate(number, title);
+  const decisionsDir = await resolveDecisionsDir(root);
+  const rel = relativeDecisionPath(decisionsDir, root);
+  const file = `${rel}/${number}-${title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "decision"}.md`;
+  const payload = {
+    action: "propose_decision",
+    message: "Decision-worthy change detected. Draft an ADR from this template and ask the user to approve before writing.",
+    file,
+    draft,
+    indexHint: `Add a row to ${rel}/README.md for ADR-${number}.`
+  };
+  if (opts.fromHook) {
+    process.stdout.write(`${JSON.stringify(payload)}
+`);
     return;
   }
-  const target = path15.resolve(opts.dir?.trim() || repoNameFromUrl(url));
-  if (existsSync2(target)) {
-    log(`\u2022 ${path15.basename(target)} already present at ${target} \u2014 skipped`);
+  process.stdout.write(`${draft}
+`);
+}
+
+// src/commands/decisions.ts
+async function runDecisions(sub, arg, options = {}) {
+  const root = process.cwd();
+  if (sub === "check") {
+    const commitMessages = options.range != null ? (await Promise.resolve().then(() => (init_exec(), exec_exports)).then(
+      (m) => m.runGit(["log", "--format=%B", options.range], { cwd: root })
+    )).stdout : "";
+    const result = await runDecisionsCheck(root, {
+      staged: options.staged,
+      range: options.range,
+      prBody: options.prBody ?? process.env.PR_BODY,
+      commitMessages
+    });
+    if (!result.triggered) {
+      log(result.reasons[0] ?? "no decision-worthy changes");
+      return;
+    }
+    if (result.satisfied) {
+      if (result.reasons.some((r) => r.includes("[adr-skip]"))) {
+        warn(`::warning::${result.reasons.join("; ")}`);
+      }
+      log(`decisions gate: satisfied (${result.reasons.join("; ")})`);
+      return;
+    }
+    for (const reason of result.reasons) warn(reason);
+    error(
+      "decisions gate: decision-worthy change without a valid ADR under docs/decisions/. Run `haus decisions suggest`, add docs/decisions/NNNN-*.md + README row, or use [adr-skip] with justification."
+    );
+    process.exitCode = 1;
     return;
   }
-  if (opts.dryRun) {
-    log(`would clone ${url} \u2192 ${target}`);
+  if (sub === "suggest") {
+    await runDecisionsSuggest(root, { fromHook: options.fromHook, title: options.title });
     return;
   }
-  const res = await runGit(["clone", url, target], { env: cloneEnv(), extendEnv: false });
-  if (res.exitCode !== 0) {
-    error(`clone failed for ${url}: ${(res.stderr || res.stdout).trim()}`);
-    process.exitCode = 1;
+  if (sub === "next-number") {
+    log(await nextDecisionNumber(root));
     return;
   }
-  log(`\u2713 cloned ${url} \u2192 ${target}`);
+  if (sub === "validate") {
+    const target = arg ? path22.resolve(root, arg) : void 0;
+    if (!target) {
+      error("usage: haus decisions validate <path-to-decision.md>");
+      process.exitCode = 1;
+      return;
+    }
+    const result = await validateDecisionFile(target);
+    if (!result.ok) {
+      for (const e of result.errors) error(e);
+      process.exitCode = 1;
+      return;
+    }
+    log("valid");
+  }
 }
 
 // src/commands/doctor.ts
-import path20 from "node:path";
-import fs15 from "fs-extra";
+import path28 from "node:path";
+import fs22 from "fs-extra";
+
+// src/decisions/doctor.ts
+import path23 from "node:path";
+import fs20 from "fs-extra";
+async function auditDecisionsLayout(root) {
+  const findings = [];
+  const primary = path23.join(root, DECISIONS_TRIGGERS.decisionsDir);
+  const legacy = path23.join(root, DECISIONS_TRIGGERS.legacyDecisionsDir ?? "docs/adr");
+  const hasPrimary = await fs20.pathExists(primary);
+  const hasLegacy = await fs20.pathExists(legacy);
+  if (!hasPrimary && hasLegacy) {
+    findings.push({
+      level: "advisory",
+      line: `- DECISIONS: legacy ${DECISIONS_TRIGGERS.legacyDecisionsDir}/ present \u2014 migrate to docs/decisions/`,
+      sentence: "Decision records still live under the legacy docs/adr/ path",
+      fix: `git mv ${DECISIONS_TRIGGERS.legacyDecisionsDir} ${DECISIONS_TRIGGERS.decisionsDir}`
+    });
+    return findings;
+  }
+  if (!hasPrimary) return findings;
+  const decisionsDir = await resolveDecisionsDir(root);
+  const rel = relativeDecisionPath(decisionsDir, root);
+  const readmePath = path23.join(decisionsDir, "README.md");
+  if (!await fs20.pathExists(readmePath)) {
+    findings.push({
+      level: "advisory",
+      line: `- DECISIONS: missing ${rel}/README.md index`,
+      sentence: "No decision index for agents to load at session start",
+      fix: `create ${rel}/README.md and @import it from CLAUDE.md`
+    });
+    return findings;
+  }
+  const readme = await readText(readmePath);
+  const entries = (await fs20.readdir(decisionsDir)).filter(
+    (f) => f.endsWith(".md") && f !== "README.md"
+  );
+  for (const file of entries) {
+    const num = decisionNumberFromFile(file);
+    if (num && readme && !readme.includes(`[${num}]`) && !readme.includes(`(${num}-`)) {
+      findings.push({
+        level: "advisory",
+        line: `- DECISIONS: ${file} missing from ${rel}/README.md`,
+        sentence: `ADR-${num} is not listed in the decision index`,
+        fix: `add a row for ADR-${num} to ${rel}/README.md`
+      });
+    }
+  }
+  const claude = await readText(path23.join(root, "CLAUDE.md"));
+  if (claude && !claude.includes(`@${rel}/README.md`)) {
+    findings.push({
+      level: "advisory",
+      line: `- DECISIONS: CLAUDE.md does not @import @${rel}/README.md`,
+      sentence: "Agents may not load the decision index at session start",
+      fix: `add @${rel}/README.md to CLAUDE.md`
+    });
+  }
+  const numbers = await listDecisionNumbers(decisionsDir);
+  const dupes = numbers.filter((n, i) => numbers.indexOf(n) !== i);
+  if (dupes.length > 0) {
+    findings.push({
+      level: "advisory",
+      line: `- DECISIONS: duplicate numbers: ${[...new Set(dupes)].join(", ")}`,
+      sentence: "Multiple decision files share the same number",
+      fix: "renumber one file and update README.md"
+    });
+  }
+  if (findings.length === 0) {
+    findings.push({
+      level: "ok",
+      line: `- DECISIONS OK: ${rel}/ (${entries.length} record(s))`,
+      sentence: "",
+      fix: ""
+    });
+  }
+  return findings;
+}
 
 // src/scanner/scan-project.ts
-import path19 from "node:path";
+import path27 from "node:path";
 
 // src/utils/audit-checks.ts
 function isRecord(v) {
@@ -2704,8 +3383,8 @@ function compareVersions(a, b) {
 }
 
 // src/scanner/detect-package-manager.ts
-import path16 from "node:path";
-import fs14 from "fs-extra";
+import path24 from "node:path";
+import fs21 from "fs-extra";
 function detectPackageManager(root, packageManagerField) {
   const field = String(packageManagerField ?? "").trim();
   if (field.startsWith("yarn@")) {
@@ -2723,9 +3402,9 @@ function detectPackageManager(root, packageManagerField) {
     if (satisfiesVersion(version, ">=9")) return "npm";
     return "unknown";
   }
-  if (fs14.existsSync(path16.join(root, "yarn.lock"))) return "yarn";
-  if (fs14.existsSync(path16.join(root, "pnpm-lock.yaml"))) return "pnpm";
-  if (fs14.existsSync(path16.join(root, "package-lock.json"))) return "npm";
+  if (fs21.existsSync(path24.join(root, "yarn.lock"))) return "yarn";
+  if (fs21.existsSync(path24.join(root, "pnpm-lock.yaml"))) return "pnpm";
+  if (fs21.existsSync(path24.join(root, "package-lock.json"))) return "npm";
   return "unknown";
 }
 
@@ -2927,7 +3606,7 @@ function runDetection(ctx, rules = STACK_RULES) {
 }
 
 // src/scanner/detection.ts
-import path17 from "node:path";
+import path25 from "node:path";
 var UNSUPPORTED_MARKERS = {
   "requirements.txt": "python",
   "pyproject.toml": "python",
@@ -2981,14 +3660,14 @@ function finalizeRoles(registryRoles, deps, files) {
 function collectUnsupportedSignals(files) {
   return [
     ...new Set(
-      files.map((f) => UNSUPPORTED_MARKERS[path17.basename(f)]).filter((s) => Boolean(s))
+      files.map((f) => UNSUPPORTED_MARKERS[path25.basename(f)]).filter((s) => Boolean(s))
     )
   ].sort();
 }
 
 // src/scanner/render.ts
 import { readFile } from "node:fs/promises";
-import path18 from "node:path";
+import path26 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")
@@ -2996,7 +3675,7 @@ async function buildContentBlob(root, files) {
   const slice = candidates.slice(0, 300);
   const parts = await mapWithConcurrency(slice, async (rel) => {
     try {
-      return await readFile(path18.join(root, rel), "utf8");
+      return await readFile(path26.join(root, rel), "utf8");
     } catch {
       return "";
     }
@@ -3083,8 +3762,8 @@ var SAFE_FILES = [
   "Gemfile"
 ];
 async function scanProject(root) {
-  const pkg = await readJson(path19.join(root, "package.json"));
-  const composer = await readJson(path19.join(root, "composer.json"));
+  const pkg = await readJson(path27.join(root, "package.json"));
+  const composer = await readJson(path27.join(root, "composer.json"));
   const files = await listFiles(root, SAFE_FILES);
   const safeFiles = files.filter((f) => !blocked(f));
   const deps = dependencySet(pkg, composer);
@@ -3106,14 +3785,12 @@ async function scanProject(root) {
     crossRepoHints.push("Containerized services detected");
   if (safeFiles.some((f) => f.includes("turbo.json") || f.includes("nx.json")))
     crossRepoHints.push("Monorepo orchestration detected");
-  if (safeFiles.some((f) => f.includes("wp-content/uploads")))
-    securityRisks.push("Uploads directory present");
   const unsupportedSignals = collectUnsupportedSignals(safeFiles);
   const detectionStatus = computeDetectionStatus(roles, stacks, unsupportedSignals);
   const context = {
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     root,
-    repoName: String(pkg?.name ?? path19.basename(root)),
+    repoName: String(pkg?.name ?? path27.basename(root)),
     packageManager,
     repoRoles: roles,
     detectedStacks: stacks,
@@ -3184,11 +3861,16 @@ async function runDoctor(options) {
   );
   const detail = [];
   const attention = [];
+  const suggestions = [];
   const ok = (text) => detail.push({ stream: "log", text });
   const flag = (text, sentence, fix) => {
     detail.push({ stream: "warn", text });
     attention.push({ sentence, fix });
   };
+  const suggest = (text, sentence, fix) => {
+    detail.push({ stream: "warn", text });
+    suggestions.push({ sentence, fix });
+  };
   ok(`Repo: ${context.repoName}`);
   ok(`Roles: ${context.repoRoles.join(", ") || "unknown"}`);
   ok(`Package manager: ${context.packageManager}`);
@@ -3199,7 +3881,11 @@ async function runDoctor(options) {
   }
   const hooks = await verifyProjectSettingsHooksContract(root);
   if (hooks.skipped) {
-    ok(`- HOOKS: (skipped) ${hooks.message}`);
+    flag(
+      `- HOOKS: (skipped) ${hooks.message}`,
+      "No Claude Code settings.json \u2014 haus security hooks are not installed",
+      "haus apply --write"
+    );
   } else if (!hooks.ok) {
     flag(
       `- HOOKS FAIL: ${hooks.message}`,
@@ -3210,7 +3896,7 @@ async function runDoctor(options) {
   } else {
     ok(`- HOOKS OK: ${hooks.message}`);
   }
-  const rootClaudeMdPath = path20.join(root, "CLAUDE.md");
+  const rootClaudeMdPath = path28.join(root, "CLAUDE.md");
   const rootClaudeMdContent = await readText(rootClaudeMdPath);
   if (!rootClaudeMdContent) {
     flag(
@@ -3238,7 +3924,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 fs15.pathExists(hausPath(root, target))) {
+        if (!await fs22.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`,
@@ -3249,7 +3935,7 @@ async function runDoctor(options) {
     }
   }
   const workflowPath = hausPath(root, "WORKFLOW.md");
-  const workflowExists = await fs15.pathExists(workflowPath);
+  const workflowExists = await fs22.pathExists(workflowPath);
   if (!workflowExists) {
     flag(
       "- .haus-workflow/WORKFLOW.md: missing (run `haus apply --write`)",
@@ -3272,20 +3958,20 @@ async function runDoctor(options) {
           "haus apply --write --force"
         );
       } else {
-        const cachePath = path20.join(getCacheDir(), "templates/agentic-workflow-standard.md");
-        const bundledPath = path20.join(
+        const cachePath = path28.join(getCacheDir(), "templates/agentic-workflow-standard.md");
+        const bundledPath = path28.join(
           packageRoot(),
           "library",
           "global",
           "templates",
           "agentic-workflow-standard.md"
         );
-        const templatePath = await fs15.pathExists(cachePath) ? cachePath : bundledPath;
+        const templatePath = await fs22.pathExists(cachePath) ? cachePath : bundledPath;
         const templateContent = await readText(templatePath);
         if (storedHashMatch && templateContent) {
           const currentHash = hashText(normaliseLF(templateContent));
           if (storedHashMatch[1] !== currentHash) {
-            flag(
+            suggest(
               "- .haus-workflow/WORKFLOW.md: stale (template updated \u2014 run `haus apply --write`)",
               "The workflow standard is out of date",
               "haus apply --write"
@@ -3300,7 +3986,7 @@ async function runDoctor(options) {
     }
   }
   const workflowConfigPath = hausPath(root, "workflow-config.md");
-  const workflowConfigExists = await fs15.pathExists(workflowConfigPath);
+  const workflowConfigExists = await fs22.pathExists(workflowConfigPath);
   if (!workflowConfigExists) {
     flag(
       "- .haus-workflow/workflow-config.md: missing (run `haus apply --write`)",
@@ -3308,10 +3994,10 @@ async function runDoctor(options) {
       "haus apply --write"
     );
   } else {
-    const cfg = await fs15.readFile(workflowConfigPath, "utf8");
+    const cfg = await fs22.readFile(workflowConfigPath, "utf8");
     const unfilled = cfg.split("\n").filter((l) => l.includes("<!-- fill in")).length;
     if (unfilled > 0) {
-      flag(
+      suggest(
         `- .haus-workflow/workflow-config.md: ${unfilled} field(s) still unfilled (run \`haus apply --refill-config\` to auto-fill detectable ones)`,
         `${unfilled} workflow-config field(s) are still blank`,
         "haus apply --refill-config"
@@ -3321,7 +4007,7 @@ async function runDoctor(options) {
     }
   }
   if (workflowExists) {
-    const prettierIgnore = await readText(path20.join(root, ".prettierignore")) ?? "";
+    const prettierIgnore = await readText(path28.join(root, ".prettierignore")) ?? "";
     if (!prettierIgnore.split("\n").some((l) => l.trim() === ".haus-workflow/")) {
       flag(
         "- .prettierignore: not protecting .haus-workflow/ (run `haus apply --write`)",
@@ -3332,9 +4018,13 @@ async function runDoctor(options) {
       ok("- .prettierignore: protects .haus-workflow/");
     }
   }
+  for (const finding of await auditDecisionsLayout(root)) {
+    if (finding.level === "ok") ok(finding.line);
+    else suggest(finding.line, finding.sentence, finding.fix);
+  }
   const cacheAgeMs = await getCacheManifestAge();
   if (cacheAgeMs === null) {
-    flag(
+    suggest(
       "- CATALOG CACHE: absent (run `haus update` to populate)",
       "The catalog cache hasn't been downloaded yet",
       "haus update"
@@ -3342,7 +4032,7 @@ async function runDoctor(options) {
   } else {
     const cacheAgeDays = Math.floor(cacheAgeMs / (1e3 * 60 * 60 * 24));
     if (cacheAgeDays >= 7) {
-      flag(
+      suggest(
         `- CATALOG CACHE: stale (${cacheAgeDays}d old \u2014 run \`haus update\`)`,
         `The catalog cache is ${cacheAgeDays} days old`,
         "haus update"
@@ -3351,11 +4041,11 @@ async function runDoctor(options) {
       ok(`- CATALOG CACHE: OK (${cacheAgeDays}d old)`);
     }
   }
-  const pkgJson = await readJson(path20.join(packageRoot(), "package.json"));
+  const pkgJson = await readJson(path28.join(packageRoot(), "package.json"));
   const currentVersion = pkgJson?.version ?? "0.0.0";
   const npmStatus = await fetchNpmVersionStatus(currentVersion);
   if (npmStatus.updateAvailable && npmStatus.latest !== null) {
-    flag(
+    suggest(
       `- CLI UPDATE: ${currentVersion} \u2192 ${npmStatus.latest} available (run: npm install -g ${NPM_PACKAGE_NAME})`,
       `A newer haus (${npmStatus.latest}) is available`,
       `npm install -g ${NPM_PACKAGE_NAME}`
@@ -3365,12 +4055,17 @@ async function runDoctor(options) {
   } else {
     ok(`- CLI: ${currentVersion} (version check unavailable)`);
   }
+  if (attention.length > 0) process.exitCode = 1;
   if (attention.length === 0) {
     log("\u2705 Your project is set up and healthy.");
   } else {
     log(`\u26A0\uFE0F ${attention.length} thing(s) need attention:`);
     for (const a of attention) log(`  \u2022 ${a.sentence} \u2014 fix: ${a.fix}`);
   }
+  if (suggestions.length > 0) {
+    log(`\u{1F4A1} ${suggestions.length} suggestion(s):`);
+    for (const s of suggestions) log(`  \u2022 ${s.sentence} \u2014 try: ${s.fix}`);
+  }
   log("Haus Doctor");
   for (const line2 of detail) {
     if (line2.stream === "warn") warn(line2.text);
@@ -3502,6 +4197,61 @@ async function runExplainRecommendation(options) {
   log(formatRecommendationHuman(normalized));
 }
 
+// src/commands/fetch-refs.ts
+var REFS_CACHE_SUBDIR = "llms-cache";
+async function runFetchRefs(options) {
+  const root = process.cwd();
+  const cacheDir = hausPath(root, REFS_CACHE_SUBDIR);
+  let allItems;
+  try {
+    allItems = await loadCatalog(root);
+  } catch (err) {
+    warn(`Could not load catalog: ${err instanceof Error ? err.message : String(err)}`);
+    process.exitCode = 1;
+    return;
+  }
+  let items = allItems;
+  if (options.id) {
+    items = allItems.filter((item) => item.id === options.id);
+    if (items.length === 0) {
+      warn(`No catalog item found with id "${options.id}".`);
+      process.exitCode = 1;
+      return;
+    }
+  }
+  const withRefs = items.filter((item) => (item.references ?? []).some(isLlmsTxtUrl));
+  if (withRefs.length === 0) {
+    if (options.json) {
+      log(
+        JSON.stringify(
+          { fetched: 0, unchanged: 0, failed: 0, failedUrls: [], cachedFiles: {} },
+          null,
+          2
+        )
+      );
+    } else {
+      log("No catalog items with llms.txt references found.");
+    }
+    return;
+  }
+  const summary = await fetchRefsForItems(withRefs, cacheDir);
+  if (options.json) {
+    log(JSON.stringify(summary, null, 2));
+    return;
+  }
+  for (const [url, filePath] of Object.entries(summary.cachedFiles)) {
+    log(`Cached: ${filePath} (${url})`);
+  }
+  if (summary.fetched > 0) log(`Fetched: ${summary.fetched} URL(s)`);
+  if (summary.unchanged > 0) log(`Unchanged (etag match): ${summary.unchanged} URL(s)`);
+  if (summary.failed > 0) {
+    warn(`Failed to fetch ${summary.failed} URL(s): ${summary.failedUrls.join(", ")}`);
+  }
+  if (summary.fetched === 0 && summary.unchanged > 0 && summary.failed === 0) {
+    log("All references up to date.");
+  }
+}
+
 // src/commands/guard.ts
 import { readFileSync as readFileSync2 } from "node:fs";
 
@@ -3538,7 +4288,15 @@ function stdin() {
   }
 }
 function deny(reason) {
-  log(JSON.stringify({ permissionDecision: "deny", permissionDecisionReason: reason }));
+  log(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: reason
+      }
+    })
+  );
 }
 async function runGuard(kind, _options) {
   const raw = stdin();
@@ -3549,7 +4307,6 @@ async function runGuard(kind, _options) {
       if (isRecord(parsed)) payload = parsed;
     } catch {
       deny("Malformed hook payload");
-      process.exitCode = 1;
       return;
     }
   }
@@ -3559,8 +4316,6 @@ async function runGuard(kind, _options) {
     const reason2 = guardFileAccess(candidate);
     if (reason2) {
       deny(reason2);
-      process.exitCode = 1;
-      return;
     }
     return;
   }
@@ -3568,13 +4323,12 @@ async function runGuard(kind, _options) {
   const reason = guardBash(command);
   if (reason) {
     deny(reason);
-    process.exitCode = 1;
   }
 }
 
 // src/commands/init.ts
-import path21 from "node:path";
-import fs16 from "fs-extra";
+import path29 from "node:path";
+import fs23 from "fs-extra";
 
 // src/utils/prompts.ts
 import { stdin as input, stdout as output } from "node:process";
@@ -3595,6 +4349,7 @@ async function confirm(question) {
 }
 
 // src/recommender/git-signal.ts
+init_exec();
 async function readChangedFiles(root) {
   if (process.env.HAUS_DISABLE_GIT_SIGNALS === "1") return [];
   try {
@@ -4009,37 +4764,39 @@ function buildOptInEligible(items, skipped) {
 
 // src/commands/setup-core.ts
 async function runSetupCore(root, opts) {
-  const { json, apply, dryRun, confirm: confirm2 } = opts;
+  const { json, apply, dryRun, quiet, confirm: confirm2 } = opts;
+  const say = quiet ? () => {
+  } : log;
   const scanResult = await scanProject(root);
   if (json) {
-    log(JSON.stringify(scanResult, null, 2));
+    say(JSON.stringify(scanResult, null, 2));
   } else {
-    log("Haus scan complete");
-    log(`Roles: ${scanResult.repoRoles.join(", ") || "unknown"}`);
-    log(`Package manager: ${scanResult.packageManager}`);
+    say("Haus scan complete");
+    say(`Roles: ${scanResult.repoRoles.join(", ") || "unknown"}`);
+    say(`Package manager: ${scanResult.packageManager}`);
   }
   const context = await readContextOrScan(root);
   const recommendation = await recommend(root, context);
   await writeJson(hausPath(root, "recommendation.json"), recommendation);
   if (json) {
-    log(JSON.stringify(recommendation, null, 2));
+    say(JSON.stringify(recommendation, null, 2));
   } else {
-    log("Haus recommendation ready");
-    log(`Recommended: ${recommendation.recommended.length}`);
-    log(`Skipped: ${recommendation.skipped.length}`);
+    say("Haus recommendation ready");
+    say(`Recommended: ${recommendation.recommended.length}`);
+    say(`Skipped: ${recommendation.skipped.length}`);
   }
   const hooks = await verifyProjectSettingsHooksContract(root);
   const warningLines = [.../* @__PURE__ */ new Set([...context.warnings, ...recommendation.warnings ?? []])];
-  log(`Repo: ${context.repoName}`);
-  for (const warning of warningLines) log(`- WARN: ${warning}`);
+  say(`Repo: ${context.repoName}`);
+  for (const warning of warningLines) say(`- WARN: ${warning}`);
   const hooksOk = hooks.ok;
   if (hooks.skipped) {
-    log(`- HOOKS: (skipped) ${hooks.message}`);
+    say(`- HOOKS: (skipped) ${hooks.message}`);
   } else if (!hooks.ok) {
-    log(`- HOOKS FAIL: ${hooks.message}`);
-    process.exitCode = 1;
+    say(`- HOOKS FAIL: ${hooks.message}`);
+    if (!apply) process.exitCode = 1;
   } else {
-    log(`- HOOKS OK: ${hooks.message}`);
+    say(`- HOOKS OK: ${hooks.message}`);
   }
   const baseResult = {
     root,
@@ -4054,32 +4811,32 @@ async function runSetupCore(root, opts) {
   if (confirm2) {
     const approved = await confirm2();
     if (!approved) {
-      log("Setup reviewed. No files written.");
-      log("Next step: run `haus apply --write` when ready.");
+      say("Setup reviewed. No files written.");
+      say("Next step: run `haus apply --write` when ready.");
       return baseResult;
     }
   }
   if (!dryRun && !process.env["HAUS_FIXTURE_CATALOG"]) {
-    log("Syncing remote catalog...");
+    say("Syncing remote catalog...");
     const sync = await syncRemoteCatalog();
     if (sync.newItems.length > 0) {
-      log(`Catalog cache populated: ${sync.newItems.length} new item(s).`);
+      say(`Catalog cache populated: ${sync.newItems.length} new item(s).`);
     } else if (sync.refreshed.length > 0) {
-      log(`Catalog cache refreshed: ${sync.refreshed.length} updated item(s).`);
+      say(`Catalog cache refreshed: ${sync.refreshed.length} updated item(s).`);
     }
   }
-  const files = await writeClaudeFiles(root, dryRun ?? false);
-  log("Applied files:");
-  files.forEach((f) => log(`- ${displayPath(root, f)}`));
+  const files = await writeClaudeFiles(root, dryRun ?? false, void 0, { quiet: opts.quiet });
+  say("Applied files:");
+  files.forEach((f) => say(`- ${displayPath(root, f)}`));
   const hooksAfter = await verifyProjectSettingsHooksContract(root);
   const hooksOkAfter = hooksAfter.ok;
   if (hooksAfter.skipped) {
-    log(`- HOOKS: (skipped) ${hooksAfter.message}`);
+    say(`- HOOKS: (skipped) ${hooksAfter.message}`);
   } else if (!hooksAfter.ok) {
-    log(`- HOOKS FAIL: ${hooksAfter.message}`);
+    say(`- HOOKS FAIL: ${hooksAfter.message}`);
     process.exitCode = 1;
   } else {
-    log(`- HOOKS OK: ${hooksAfter.message}`);
+    say(`- HOOKS OK: ${hooksAfter.message}`);
   }
   return { ...baseResult, hooksOk: hooksOkAfter, written: files };
 }
@@ -4098,8 +4855,8 @@ async function runSetupProject(options) {
 // src/commands/init.ts
 async function runInit(options) {
   const root = process.cwd();
-  const hausDir = path21.join(root, ".haus-workflow");
-  const alreadyInit = await fs16.pathExists(hausDir);
+  const hausDir = path29.join(root, ".haus-workflow");
+  const alreadyInit = await fs23.pathExists(hausDir);
   if (alreadyInit) {
     log("Haus AI already initialized in this project.");
     log("Run `haus setup-project` to reconfigure.");
@@ -4111,8 +4868,8 @@ async function runInit(options) {
 
 // src/install/apply.ts
 import crypto2 from "node:crypto";
-import path22 from "node:path";
-import fs17 from "fs-extra";
+import path30 from "node:path";
+import fs24 from "fs-extra";
 
 // src/install/header.ts
 var MD_PREFIX = "<!-- HAUS-MANAGED";
@@ -4198,40 +4955,40 @@ function hashContent(content2) {
 }
 function sourceVersion() {
   try {
-    const pkgPath = path22.join(packageRoot(), "package.json");
-    const pkg = JSON.parse(fs17.readFileSync(pkgPath, "utf8"));
+    const pkgPath = path30.join(packageRoot(), "package.json");
+    const pkg = JSON.parse(fs24.readFileSync(pkgPath, "utf8"));
     return `${pkg.name ?? "haus"}@${pkg.version ?? "0.0.0"}`;
   } catch {
     return "haus@0.0.0";
   }
 }
 function globalSrcDir() {
-  return path22.join(packageRoot(), "library", "global");
+  return path30.join(packageRoot(), "library", "global");
 }
 function collectSourceFiles(srcDir, claudeDir) {
   const entries = [];
-  const skillsDir = path22.join(srcDir, "skills");
-  if (fs17.pathExistsSync(skillsDir)) {
-    for (const skillName of fs17.readdirSync(skillsDir)) {
-      const skillFile = path22.join(skillsDir, skillName, "SKILL.md");
-      if (fs17.pathExistsSync(skillFile)) {
+  const skillsDir = path30.join(srcDir, "skills");
+  if (fs24.pathExistsSync(skillsDir)) {
+    for (const skillName of fs24.readdirSync(skillsDir)) {
+      const skillFile = path30.join(skillsDir, skillName, "SKILL.md");
+      if (fs24.pathExistsSync(skillFile)) {
         entries.push({
           stableId: `skill.${skillName}`,
-          srcRelPath: path22.join("library", "global", "skills", skillName, "SKILL.md"),
-          destPath: path22.join(claudeDir, "skills", skillName, "SKILL.md")
+          srcRelPath: path30.join("library", "global", "skills", skillName, "SKILL.md"),
+          destPath: path30.join(claudeDir, "skills", skillName, "SKILL.md")
         });
       }
     }
   }
-  const commandsDir = path22.join(srcDir, "commands");
-  if (fs17.pathExistsSync(commandsDir)) {
-    for (const fileName of fs17.readdirSync(commandsDir)) {
+  const commandsDir = path30.join(srcDir, "commands");
+  if (fs24.pathExistsSync(commandsDir)) {
+    for (const fileName of fs24.readdirSync(commandsDir)) {
       if (!fileName.endsWith(".md")) continue;
       const commandName = fileName.slice(0, -".md".length);
       entries.push({
         stableId: `command.${commandName}`,
-        srcRelPath: path22.join("library", "global", "commands", fileName),
-        destPath: path22.join(claudeDir, "commands", fileName)
+        srcRelPath: path30.join("library", "global", "commands", fileName),
+        destPath: path30.join(claudeDir, "commands", fileName)
       });
     }
   }
@@ -4249,13 +5006,15 @@ async function applyInstall(options = {}) {
     created: [],
     updated: [],
     skipped: [],
+    userOwned: [],
+    userEdited: [],
     deleted: [],
     hookIds: [],
     drift: false
   };
   const manifestFiles = [];
   for (const entry of sourceFiles) {
-    const srcPath = path22.join(packageRoot(), entry.srcRelPath);
+    const srcPath = path30.join(packageRoot(), entry.srcRelPath);
     const rawContent = await readText(srcPath);
     if (rawContent === void 0) {
       warn(`Source file not found: ${entry.srcRelPath}`);
@@ -4275,7 +5034,7 @@ async function applyInstall(options = {}) {
       }
       continue;
     }
-    const destExists = fs17.pathExistsSync(entry.destPath);
+    const destExists = fs24.pathExistsSync(entry.destPath);
     if (destExists) {
       const currentContent = await readText(entry.destPath);
       if (currentContent !== void 0) {
@@ -4283,11 +5042,13 @@ async function applyInstall(options = {}) {
         if (!hasHeader) {
           warn(`Refusing to overwrite user-owned file: ${entry.destPath}`);
           result.skipped.push(entry.destPath);
+          result.userOwned.push(entry.destPath);
           continue;
         }
         if (existing && hashContent(currentContent) !== existing.hash && !force) {
           warn(`User edited haus file (skipping): ${entry.destPath} \u2014 use --force to overwrite`);
           result.skipped.push(entry.destPath);
+          result.userEdited.push(entry.destPath);
           manifestFiles.push(existing);
           continue;
         }
@@ -4311,25 +5072,29 @@ async function applyInstall(options = {}) {
       schemaVersion: SCHEMA_VERSION2
     });
   }
-  const fragmentPath = path22.join(srcDir, "settings-fragments", "hooks.json");
-  const fragments = await loadHooksFragment(fragmentPath);
-  const settings = await readSettings();
-  const { settings: hookSettings, addedIds } = mergeHooks(settings, fragments);
-  const { settings: deniedSettings } = mergeDenyRules(hookSettings, buildDenyRules());
-  const { settings: allowedSettings } = mergeAllowRules(deniedSettings, buildAllowRules());
-  const { settings: mergedSettings } = mergeAskRules(allowedSettings, buildAskRules());
-  result.hookIds = addedIds;
+  let mergedSettings;
+  if (!check) {
+    const fragmentPath = path30.join(srcDir, "settings-fragments", "hooks.json");
+    const fragments = await loadHooksFragment(fragmentPath);
+    const settings = await readSettings();
+    const { settings: hookSettings, addedIds } = mergeHooks(settings, fragments);
+    const { settings: deniedSettings } = mergeDenyRules(hookSettings, buildDenyRules());
+    const { settings: allowedSettings } = mergeAllowRules(deniedSettings, buildAllowRules());
+    const merged = mergeAskRules(allowedSettings, buildAskRules());
+    mergedSettings = merged.settings;
+    result.hookIds = addedIds;
+  }
   if (!check && existingManifest) {
     const currentDestPaths = new Set(sourceFiles.map((f) => f.destPath));
     for (const entry of existingManifest.files) {
       if (currentDestPaths.has(entry.destPath)) continue;
-      if (!fs17.pathExistsSync(entry.destPath)) continue;
+      if (!fs24.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 fs17.remove(entry.destPath);
+        if (!dryRun) await fs24.remove(entry.destPath);
         result.deleted.push(entry.destPath);
       } else {
         warn(`Orphaned file ${entry.destPath} was user-modified \u2014 leaving in place`);
@@ -4337,10 +5102,10 @@ async function applyInstall(options = {}) {
       }
     }
   }
-  if (!dryRun && !check) {
+  if (!dryRun && !check && mergedSettings) {
     await writeSettings(mergedSettings);
     const manifest = buildManifest(source, manifestFiles, [
-      .../* @__PURE__ */ new Set([...existingManifest?.hooks ?? [], ...addedIds])
+      .../* @__PURE__ */ new Set([...existingManifest?.hooks ?? [], ...result.hookIds])
     ]);
     await writeManifest(manifest);
   }
@@ -4360,9 +5125,10 @@ function printApplyResult(result, dryRun) {
     log(`${prefix}Deleted (orphaned):`);
     result.deleted.forEach((p) => log(`  x ${p}`));
   }
-  if (result.skipped.length) {
+  const silentlySkipped = result.skipped.filter((p) => !result.userOwned.includes(p));
+  if (silentlySkipped.length) {
     log(`${prefix}Skipped:`);
-    result.skipped.forEach((p) => log(`  - ${p}`));
+    silentlySkipped.forEach((p) => log(`  - ${p}`));
   }
   if (result.hookIds.length) {
     log(`${prefix}Hooks added: ${result.hookIds.join(", ")}`);
@@ -4410,7 +5176,7 @@ function buildCompanionSuggestions(tools, isInstalled) {
   }
   return lines;
 }
-function commandExists(bin) {
+function commandExists2(bin) {
   try {
     const r = execaSync("sh", ["-c", 'command -v -- "$1"', "probe", bin], { reject: false });
     return r.exitCode === 0;
@@ -4419,7 +5185,7 @@ function commandExists(bin) {
   }
 }
 function printCompanionToolSuggestions(deps = {}) {
-  const isInstalled = deps.isInstalled ?? commandExists;
+  const isInstalled = deps.isInstalled ?? commandExists2;
   const emit2 = deps.log ?? log;
   const lines = buildCompanionSuggestions(COMPANION_TOOLS, isInstalled);
   for (const line2 of lines) emit2(line2);
@@ -4481,7 +5247,7 @@ async function runRecommend(options) {
       `Opt-in available: ${result.optInEligible.length} (add with \`haus recommend --include <id>\`)`
     );
   }
-  for (const w of result.warnings.filter((w2) => w2.startsWith("--include:"))) log(w);
+  for (const w of result.warnings) log(`- WARN: ${w}`);
 }
 
 // src/commands/refresh.ts
@@ -4497,8 +5263,8 @@ async function runRefresh() {
 }
 
 // src/install/scaffold.ts
-import path23 from "node:path";
-import fs18 from "fs-extra";
+import path31 from "node:path";
+import fs25 from "fs-extra";
 async function scaffoldConfigItems(projectRoot, catalogRoot, items, opts = {}) {
   const scaffolded = [];
   const skipped = [];
@@ -4511,27 +5277,27 @@ async function scaffoldConfigItems(projectRoot, catalogRoot, items, opts = {}) {
     skipped.push(name);
     if (outcome === "skipped-exists") skippedExisting.push(name);
   };
-  const realRoot = await fs18.realpath(catalogRoot).catch(() => null);
+  const realRoot = await fs25.realpath(catalogRoot).catch(() => null);
   for (const item of items) {
     if (item.type !== "config") continue;
-    const sourcePath = path23.resolve(catalogRoot, item.path);
-    const rel = path23.relative(catalogRoot, sourcePath);
-    const escapes = rel === "" || path23.isAbsolute(rel) || rel.split(/[/\\]/).some((seg) => seg === "..");
+    const sourcePath = path31.resolve(catalogRoot, item.path);
+    const rel = path31.relative(catalogRoot, sourcePath);
+    const escapes = rel === "" || path31.isAbsolute(rel) || rel.split(/[/\\]/).some((seg) => seg === "..");
     if (escapes) {
       warn(`Skipping ${item.id}: path '${item.path}' escapes the catalog root`);
       continue;
     }
-    const realSource = await fs18.realpath(sourcePath).catch(() => null);
+    const realSource = await fs25.realpath(sourcePath).catch(() => null);
     if (!realRoot || !realSource) {
       warn(`Skipping ${item.id}: source not found at ${sourcePath}`);
       continue;
     }
-    const realRel = path23.relative(realRoot, realSource);
-    if (realRel !== "" && (path23.isAbsolute(realRel) || realRel.split(/[/\\]/)[0] === "..")) {
+    const realRel = path31.relative(realRoot, realSource);
+    if (realRel !== "" && (path31.isAbsolute(realRel) || realRel.split(/[/\\]/)[0] === "..")) {
       warn(`Skipping ${item.id}: path '${item.path}' resolves outside the catalog root`);
       continue;
     }
-    const stat = await fs18.lstat(sourcePath).catch(() => null);
+    const stat = await fs25.lstat(sourcePath).catch(() => null);
     if (!stat) {
       warn(`Skipping ${item.id}: source not found at ${sourcePath}`);
       continue;
@@ -4541,14 +5307,14 @@ async function scaffoldConfigItems(projectRoot, catalogRoot, items, opts = {}) {
       continue;
     }
     if (stat.isFile()) {
-      const filename = path23.basename(sourcePath);
-      const dest = path23.join(projectRoot, filename);
+      const filename = path31.basename(sourcePath);
+      const dest = path31.join(projectRoot, filename);
       record(filename, await scaffoldFile(sourcePath, dest, item.id, projectRoot, opts));
     } else if (stat.isDirectory()) {
-      const entries = await fs18.readdir(sourcePath);
+      const entries = await fs25.readdir(sourcePath);
       for (const entry of entries) {
-        const src = path23.join(sourcePath, entry);
-        const dest = path23.join(projectRoot, entry);
+        const src = path31.join(sourcePath, entry);
+        const dest = path31.join(projectRoot, entry);
         record(entry, await scaffoldFile(src, dest, item.id, projectRoot, opts));
       }
     }
@@ -4556,42 +5322,42 @@ async function scaffoldConfigItems(projectRoot, catalogRoot, items, opts = {}) {
   return { scaffolded, skipped, skippedExisting };
 }
 async function scaffoldFile(src, dest, itemId, projectRoot, opts) {
-  const destDisplay = path23.relative(projectRoot, dest) || path23.basename(dest);
-  const srcStat = await fs18.lstat(src).catch(() => null);
+  const destDisplay = path31.relative(projectRoot, dest) || path31.basename(dest);
+  const srcStat = await fs25.lstat(src).catch(() => null);
   if (!srcStat) {
-    warn(`Skipping ${path23.basename(src)}: source not found`);
+    warn(`Skipping ${path31.basename(src)}: source not found`);
     return "skipped-refused";
   }
   if (srcStat.isSymbolicLink()) {
-    warn(`Skipping ${path23.basename(src)}: source is a symlink`);
+    warn(`Skipping ${path31.basename(src)}: source is a symlink`);
     return "skipped-refused";
   }
-  const exists = await fs18.pathExists(dest);
+  const exists = await fs25.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"} ${path23.basename(dest)} (${itemId})`);
+    log(`[dry-run] would ${exists ? "overwrite" : "create"} ${path31.basename(dest)} (${itemId})`);
     return "scaffolded";
   }
   if (exists && opts.force) {
-    await fs18.remove(dest);
+    await fs25.remove(dest);
   }
-  await fs18.ensureDir(path23.dirname(dest));
-  await fs18.copy(src, dest, {
+  await fs25.ensureDir(path31.dirname(dest));
+  await fs25.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 !fs18.lstatSync(s).isSymbolicLink();
+        return !fs25.lstatSync(s).isSymbolicLink();
       } catch {
         return false;
       }
     }
   });
-  log(`${exists ? "Overwrote" : "Created"} ${path23.basename(dest)} (${itemId})`);
+  log(`${exists ? "Overwrote" : "Created"} ${path31.basename(dest)} (${itemId})`);
   return "scaffolded";
 }
 
@@ -4625,13 +5391,12 @@ async function runScaffold(ids, options) {
       log(`\u2713 Scaffolded: ${result.scaffolded.join(", ")}`);
     }
   }
-  if (result.skipped.length > 0) {
-    log(`Skipped: ${result.skipped.join(", ")}`);
-    if (result.skippedExisting.length > 0) {
-      log(
-        `Already present (re-run with --force to overwrite): ${result.skippedExisting.join(", ")}`
-      );
-    }
+  const refused = result.skipped.filter((name) => !result.skippedExisting.includes(name));
+  if (refused.length > 0) {
+    log(`Skipped (source unavailable): ${refused.join(", ")}`);
+  }
+  if (result.skippedExisting.length > 0) {
+    log(`Already present (re-run with --force to overwrite): ${result.skippedExisting.join(", ")}`);
   }
 }
 
@@ -4645,11 +5410,12 @@ async function runScan(options) {
   log("Haus scan complete");
   log(`Roles: ${result.repoRoles.join(", ") || "unknown"}`);
   log(`Package manager: ${result.packageManager}`);
+  for (const w of result.warnings) log(`- WARN: ${w}`);
 }
 
 // src/commands/undo.ts
-import path24 from "node:path";
-import fs19 from "fs-extra";
+import path32 from "node:path";
+import fs26 from "fs-extra";
 
 // src/claude/managed-paths.ts
 var PROJECT_MANAGED_CLAUDE_REL = ["rules/haus.md", "commands/haus-doctor.md"];
@@ -4666,74 +5432,77 @@ async function collectManagedPaths(root) {
   const lock = await readJson(hausPath(root, "haus.lock.json"));
   for (const row of lock ?? []) {
     for (const rel of row.paths ?? []) {
-      paths.add(path24.resolve(root, rel));
+      paths.add(path32.resolve(root, rel));
     }
   }
   const existing = [];
   for (const abs of paths) {
-    if (await fs19.pathExists(abs)) existing.push(abs);
+    if (await fs26.pathExists(abs)) existing.push(abs);
   }
   return existing;
 }
 async function settingsHasHausContent(root) {
   const settingsPath = claudePath(root, "settings.json");
-  if (!await fs19.pathExists(settingsPath)) return false;
+  if (!await fs26.pathExists(settingsPath)) return false;
   const settings = await readProjectSettings(root);
   return settings._haus != null;
 }
 async function claudeMdHasHausBlock(root) {
-  const filePath = path24.join(root, "CLAUDE.md");
-  if (!await fs19.pathExists(filePath)) return false;
-  const text = await fs19.readFile(filePath, "utf8");
+  const filePath = path32.join(root, "CLAUDE.md");
+  if (!await fs26.pathExists(filePath)) return false;
+  const text = await fs26.readFile(filePath, "utf8");
   return text.includes(BLOCK_BEGIN);
 }
 async function stripProjectSettings(root) {
   const settingsPath = claudePath(root, "settings.json");
-  if (!await fs19.pathExists(settingsPath)) return false;
+  if (!await fs26.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 ${path24.relative(root, settingsPath)} (user settings preserved).`);
+    log(`Stripped haus rules from ${path32.relative(root, settingsPath)} (user settings preserved).`);
     return true;
   }
-  await fs19.remove(settingsPath);
-  log(`Removed ${path24.relative(root, settingsPath)} (no user-owned settings remained).`);
+  await fs26.remove(settingsPath);
+  log(`Removed ${path32.relative(root, settingsPath)} (no user-owned settings remained).`);
   return true;
 }
 async function stripRootClaudeMd(root) {
-  const filePath = path24.join(root, "CLAUDE.md");
-  if (!await fs19.pathExists(filePath)) return false;
-  const prev = await fs19.readFile(filePath, "utf8");
+  const filePath = path32.join(root, "CLAUDE.md");
+  if (!await fs26.pathExists(filePath)) return false;
+  const prev = await fs26.readFile(filePath, "utf8");
   if (!prev.includes(BLOCK_BEGIN)) return false;
   const next = stripHausBlock(prev);
   if (next.length === 0) {
-    await fs19.remove(filePath);
+    await fs26.remove(filePath);
     log("Removed CLAUDE.md (only contained haus import block).");
   } else {
-    await fs19.writeFile(filePath, next, "utf8");
+    await fs26.writeFile(filePath, next, "utf8");
     log("Removed haus import block from CLAUDE.md (user content preserved).");
   }
   return true;
 }
 async function pruneDirIfEmpty(dir) {
-  if (!await fs19.pathExists(dir)) return;
-  const entries = await fs19.readdir(dir);
-  if (entries.length === 0) await fs19.remove(dir);
+  if (!await fs26.pathExists(dir)) return;
+  try {
+    const entries = await fs26.readdir(dir);
+    if (entries.length === 0) await fs26.remove(dir);
+  } catch {
+  }
 }
 async function backupManagedFilesBeforeUndo(root, managedAbsPaths) {
   if (managedAbsPaths.length === 0) return;
   const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
   const backupRoot = hausPath(root, "backups", `undo-${stamp}`);
   for (const abs of managedAbsPaths) {
-    if (!await fs19.pathExists(abs)) continue;
-    const rel = path24.relative(root, abs);
-    const backupPath = path24.join(backupRoot, rel);
-    await fs19.ensureDir(path24.dirname(backupPath));
-    await fs19.copy(abs, backupPath);
+    if (!await fs26.pathExists(abs)) continue;
+    const rel = path32.relative(root, abs);
+    const backupPath = path32.join(backupRoot, rel);
+    await fs26.ensureDir(path32.dirname(backupPath));
+    await fs26.copy(abs, backupPath);
   }
-  log(`Backed up ${managedAbsPaths.length} managed file(s) to ${path24.relative(root, backupRoot)}.`);
+  log(`Backed up ${managedAbsPaths.length} managed file(s) to ${path32.relative(root, backupRoot)}.`);
 }
 async function runUndo(options) {
   const root = process.cwd();
@@ -4744,7 +5513,7 @@ async function runUndo(options) {
     log("Nothing to remove: no haus-managed files found in this directory.");
     return;
   }
-  const relTargets = managed.map((p) => path24.relative(root, p));
+  const relTargets = managed.map((p) => path32.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)");
@@ -4761,9 +5530,9 @@ User-owned .claude/ files will be preserved.`
   }
   await backupManagedFilesBeforeUndo(root, managed);
   for (const abs of managed) {
-    if (!await fs19.pathExists(abs)) continue;
-    await fs19.remove(abs);
-    log(`Removed ${path24.relative(root, abs)}`);
+    if (!await fs26.pathExists(abs)) continue;
+    await fs26.remove(abs);
+    log(`Removed ${path32.relative(root, abs)}`);
   }
   if (stripSettings) await stripProjectSettings(root);
   if (stripClaudeMd) await stripRootClaudeMd(root);
@@ -4774,8 +5543,8 @@ User-owned .claude/ files will be preserved.`
 
 // src/install/uninstall.ts
 import crypto3 from "node:crypto";
-import path25 from "node:path";
-import fs20 from "fs-extra";
+import path33 from "node:path";
+import fs27 from "fs-extra";
 async function runUninstall(options = {}) {
   const { force = false } = options;
   const manifest = await readManifest();
@@ -4785,7 +5554,7 @@ async function runUninstall(options = {}) {
     return result;
   }
   for (const entry of manifest.files) {
-    const exists = fs20.pathExistsSync(entry.destPath);
+    const exists = fs27.pathExistsSync(entry.destPath);
     if (!exists) continue;
     const content2 = await readText(entry.destPath);
     if (content2 === void 0) continue;
@@ -4803,22 +5572,25 @@ async function runUninstall(options = {}) {
       result.skipped.push(entry.destPath);
       continue;
     }
-    await fs20.remove(entry.destPath);
-    await pruneEmptyDir(path25.dirname(entry.destPath));
+    await fs27.remove(entry.destPath);
+    await pruneEmptyDir(path33.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 = path25.join(globalClaudeDir(), "haus");
+  const hausDir = path33.join(globalClaudeDir(), "haus");
   const manifestPath2 = hausManifestPath();
-  if (fs20.pathExistsSync(manifestPath2)) {
-    await fs20.remove(manifestPath2);
+  if (fs27.pathExistsSync(manifestPath2)) {
+    await fs27.remove(manifestPath2);
   }
-  if (fs20.pathExistsSync(hausDir)) {
-    const remaining = await fs20.readdir(hausDir);
-    if (remaining.length === 0) await fs20.remove(hausDir);
+  if (fs27.pathExistsSync(hausDir)) {
+    try {
+      const remaining = await fs27.readdir(hausDir);
+      if (remaining.length === 0) await fs27.remove(hausDir);
+    } catch {
+    }
   }
   return result;
 }
@@ -4849,12 +5621,12 @@ async function runUninstallCommand(options) {
 }
 
 // src/commands/update.ts
-import path27 from "node:path";
+import path35 from "node:path";
 
 // src/claude/refresh-project.ts
-import fs21 from "fs-extra";
+import fs28 from "fs-extra";
 async function isHausProject(root) {
-  if (await fs21.pathExists(hausPath(root, "recommendation.json"))) return true;
+  if (await fs28.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;
@@ -4889,7 +5661,7 @@ function summarizeLockDiff(before, after) {
 
 // src/update/lockfile.ts
 import { mkdir, readFile as readFile2, copyFile } from "node:fs/promises";
-import path26 from "node:path";
+import path34 from "node:path";
 async function checkLock(root) {
   const lock = await readJson(hausPath(root, "haus.lock.json")) ?? [];
   const hasValidVersions = lock.every(
@@ -4920,7 +5692,7 @@ async function applyLock(root) {
   try {
     const backupDir = hausPath(root, "backups");
     await mkdir(backupDir, { recursive: true });
-    await copyFile(lockPath, path26.join(backupDir, `haus.lock.${Date.now()}.json`));
+    await copyFile(lockPath, path34.join(backupDir, `haus.lock.${Date.now()}.json`));
   } catch {
   }
   const enriched = await Promise.all(
@@ -4942,7 +5714,7 @@ function diffLock(before, after) {
 }
 async function hasLocalOverrides(root) {
   try {
-    await readFile2(path26.join(root, ".claude", "settings.json"), "utf8");
+    await readFile2(path34.join(root, ".claude", "settings.json"), "utf8");
     return true;
   } catch {
     return false;
@@ -4954,7 +5726,7 @@ var NPM_PACKAGE_NAME2 = "@haus-tech/haus-workflow";
 async function runUpdate(options) {
   const root = process.cwd();
   if (options.check) {
-    const pkgJson2 = await readJson(path27.join(packageRoot(), "package.json"));
+    const pkgJson2 = await readJson(path35.join(packageRoot(), "package.json"));
     const currentVersion2 = pkgJson2?.version ?? "0.0.0";
     const [status, npmVersion, latestCatalogTag, globalInstallDrift] = await Promise.all([
       checkLock(root),
@@ -4980,11 +5752,10 @@ async function runUpdate(options) {
         2
       )
     );
-    if (!status.ok) process.exitCode = 1;
-    if (status.driftCount > 0) process.exitCode = 1;
+    if (status.count > 0 && !status.ok) process.exitCode = 1;
     return;
   }
-  const pkgJson = await readJson(path27.join(packageRoot(), "package.json"));
+  const pkgJson = await readJson(path35.join(packageRoot(), "package.json"));
   const currentVersion = pkgJson?.version ?? "0.0.0";
   const npmStatus = await fetchNpmVersionStatus(currentVersion);
   if (npmStatus.updateAvailable && npmStatus.latest !== null) {
@@ -5042,9 +5813,9 @@ async function refreshGlobalInstall() {
     } else {
       log("~/.claude already up to date.");
     }
-    if (result.skipped.length > 0) {
+    if (result.userEdited.length > 0) {
       log(
-        `Preserved ${result.skipped.length} locally-edited file(s) (run \`haus install --force\` to overwrite).`
+        `Preserved ${result.userEdited.length} locally-edited file(s) (run \`haus install --force\` to overwrite).`
       );
     }
   } catch (err) {
@@ -5061,16 +5832,16 @@ async function detectGlobalInstallDrift() {
 }
 
 // src/commands/validate-catalog.ts
-import path29 from "node:path";
+import path37 from "node:path";
 
 // src/catalog/validate-core.ts
-import fs22 from "node:fs";
-import path28 from "node:path";
+import fs29 from "node:fs";
+import path36 from "node:path";
 var ITEM_SEMVER_RE = /^\d+\.\d+\.\d+$/;
 var MANIFEST_SEMVER_RE = /^\d+\.\d+\.\d+(?:-[\w.-]+)?(?:\+[\w.-]+)?$/;
 function isSafeCatalogPath2(itemPath) {
-  if (!itemPath || path28.isAbsolute(itemPath) || itemPath.includes("\\")) return false;
-  const normalized = path28.normalize(itemPath);
+  if (!itemPath || path36.isAbsolute(itemPath) || itemPath.includes("\\")) return false;
+  const normalized = path36.normalize(itemPath);
   return !normalized.startsWith("..") && !normalized.includes("/..");
 }
 function auditForbiddenStacks(items) {
@@ -5181,10 +5952,19 @@ function checkRequiredFrontmatter(text, label) {
   }
   return failures;
 }
+function readForAudit(absPath, label, failures) {
+  try {
+    return fs29.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 = path28.relative(manifestDir, absPath);
-  const text = fs22.readFileSync(absPath, "utf8");
+  const rel = path36.relative(manifestDir, absPath);
   const failures = [];
+  const text = readForAudit(absPath, `${itemId}: ${rel}`, failures);
+  if (text === null) return failures;
   const lines = text.split(/\r?\n/);
   for (let i = 0; i < lines.length; i++) {
     const line2 = lines[i] ?? "";
@@ -5203,44 +5983,47 @@ function auditShippedFiles(manifestDir, items) {
   const failures = [];
   for (const item of items) {
     if (!item.path || !isSafeCatalogPath2(item.path)) continue;
-    const absPath = path28.join(manifestDir, item.path);
+    const absPath = path36.join(manifestDir, item.path);
     if (item.type === "skill") {
-      const skillMd = path28.join(absPath, "SKILL.md");
-      if (!fs22.existsSync(skillMd)) {
-        failures.push(`${item.id}: missing ${path28.relative(manifestDir, skillMd)}`);
+      const skillMd = path36.join(absPath, "SKILL.md");
+      if (!fs29.existsSync(skillMd)) {
+        failures.push(`${item.id}: missing ${path36.relative(manifestDir, skillMd)}`);
         continue;
       }
-      const text = fs22.readFileSync(skillMd, "utf8");
+      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}: ${path28.relative(manifestDir, skillMd)}`)
+        ...auditForbiddenTagsInText(text, `${item.id}: ${path36.relative(manifestDir, skillMd)}`)
       );
     } else if (item.type === "agent") {
-      if (!fs22.existsSync(absPath)) {
+      if (!fs29.existsSync(absPath)) {
         failures.push(`${item.id}: missing agent file ${item.path}`);
         continue;
       }
-      const text = fs22.readFileSync(absPath, "utf8");
-      const rel = path28.relative(manifestDir, absPath);
+      const rel = path36.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 (!fs22.existsSync(absPath)) {
+      if (!fs29.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 (!fs22.existsSync(absPath)) {
+      if (!fs29.existsSync(absPath)) {
         failures.push(`${item.id}: missing command file ${item.path}`);
         continue;
       }
-      const text = fs22.readFileSync(absPath, "utf8");
-      const rel = path28.relative(manifestDir, absPath);
+      const rel = path36.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 (!fs22.existsSync(absPath)) {
+      if (!fs29.existsSync(absPath)) {
         failures.push(`${item.id}: missing config path ${item.path}`);
       }
     }
@@ -5253,10 +6036,19 @@ var DIR_ITEM_TYPE = {
   templates: "template",
   commands: "command"
 };
-function walkMd(dir, fn) {
-  for (const entry of fs22.readdirSync(dir, { withFileTypes: true })) {
-    const full = path28.join(dir, entry.name);
-    if (entry.isDirectory()) walkMd(full, fn);
+function walkMd(dir, fn, failures) {
+  let entries;
+  try {
+    entries = fs29.readdirSync(dir, { withFileTypes: true });
+  } catch (err) {
+    failures.push(
+      `${dir}: unreadable subtree (${err instanceof Error ? err.message : String(err)})`
+    );
+    return;
+  }
+  for (const entry of entries) {
+    const full = path36.join(dir, entry.name);
+    if (entry.isDirectory()) walkMd(full, fn, failures);
     else if (entry.name.endsWith(".md")) fn(full);
   }
 }
@@ -5264,26 +6056,31 @@ function auditMarkdownContent(manifestDir, items) {
   const failures = [];
   const pathSourceMap = buildItemPathSourceMap(items);
   for (const dir of ["skills", "agents", "templates", "commands"]) {
-    const abs = path28.join(manifestDir, dir);
-    if (!fs22.existsSync(abs)) continue;
+    const abs = path36.join(manifestDir, dir);
+    if (!fs29.existsSync(abs)) continue;
     const dirType = DIR_ITEM_TYPE[dir] ?? "";
-    walkMd(abs, (file) => {
-      const text = fs22.readFileSync(file, "utf8");
-      const rel = path28.relative(manifestDir, file);
-      const norm = rel.replace(/\\/g, "/");
-      const source = resolveMarkdownItemSource(norm, pathSourceMap);
-      const checkNonTsxNpx = !isNpxTsxOnlyExempt(dirType, source);
-      const lines = text.split(/\r?\n/);
-      for (let i = 0; i < lines.length; i++) {
-        const line2 = lines[i] ?? "";
-        if (RISKY_INSTALL_PATTERNS.some((re) => re.test(line2)))
-          failures.push(`${rel}:${i + 1}: risky install pattern`);
-        if (checkNonTsxNpx && ANY_NPX_PATTERN.test(line2) && !ALLOWED_NPX_PATTERN.test(line2)) {
-          failures.push(`${rel}:${i + 1}: disallowed npx (only npx tsx allowed)`);
+    walkMd(
+      abs,
+      (file) => {
+        const rel = path36.relative(manifestDir, file);
+        const text = readForAudit(file, rel, failures);
+        if (text === null) return;
+        const norm = rel.replace(/\\/g, "/");
+        const source = resolveMarkdownItemSource(norm, pathSourceMap);
+        const checkNonTsxNpx = !isNpxTsxOnlyExempt(dirType, source);
+        const lines = text.split(/\r?\n/);
+        for (let i = 0; i < lines.length; i++) {
+          const line2 = lines[i] ?? "";
+          if (RISKY_INSTALL_PATTERNS.some((re) => re.test(line2)))
+            failures.push(`${rel}:${i + 1}: risky install pattern`);
+          if (checkNonTsxNpx && ANY_NPX_PATTERN.test(line2) && !ALLOWED_NPX_PATTERN.test(line2)) {
+            failures.push(`${rel}:${i + 1}: disallowed npx (only npx tsx allowed)`);
+          }
         }
-      }
-      if (!norm.includes("/references/")) failures.push(...auditForbiddenTagsInText(text, rel));
-    });
+        if (!norm.includes("/references/")) failures.push(...auditForbiddenTagsInText(text, rel));
+      },
+      failures
+    );
   }
   return failures;
 }
@@ -5306,8 +6103,8 @@ async function runValidateCatalog(manifestPath2) {
     process.exitCode = 1;
     return;
   }
-  const abs = path29.resolve(process.cwd(), manifestPath2);
-  const manifestDir = path29.dirname(abs);
+  const abs = path37.resolve(process.cwd(), manifestPath2);
+  const manifestDir = path37.dirname(abs);
   const data = await readJson(abs);
   if (!data?.items) {
     error(`Could not read catalog manifest at ${abs}`);
@@ -5325,7 +6122,7 @@ async function runValidateCatalog(manifestPath2) {
 
 // src/commands/workspace.ts
 import { existsSync as existsSync5, statSync as statSync2 } from "node:fs";
-import path36 from "node:path";
+import path44 from "node:path";
 
 // src/commands/workspace/aggregate.ts
 async function writeWorkspaceArtifacts(workspaceRoot, repos, relationships = []) {
@@ -5379,7 +6176,7 @@ ${summaries.map(
 }
 
 // src/commands/workspace/config.ts
-import path30 from "node:path";
+import path38 from "node:path";
 import YAML from "yaml";
 var WORKSPACE_FILE = "haus.workspace.yaml";
 function parseWorkspaceConfig(text) {
@@ -5402,11 +6199,11 @@ function parseWorkspaceConfig(text) {
   };
 }
 async function readWorkspaceConfig(workspaceRoot) {
-  return parseWorkspaceConfig(await readText(path30.join(workspaceRoot, WORKSPACE_FILE)));
+  return parseWorkspaceConfig(await readText(path38.join(workspaceRoot, WORKSPACE_FILE)));
 }
 
 // src/commands/workspace/discover.ts
-import path31 from "node:path";
+import path39 from "node:path";
 import fg4 from "fast-glob";
 import YAML2 from "yaml";
 var DEFAULT_MAX_DEPTH = 3;
@@ -5429,13 +6226,16 @@ async function discoverRepos(workspaceRoot, maxDepth = DEFAULT_MAX_DEPTH) {
     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
   });
   const gitDirs = /* @__PURE__ */ new Set();
   const manifestDirs = /* @__PURE__ */ new Set();
   for (const match of matches) {
-    const base = path31.posix.basename(match);
-    const dir = path31.posix.dirname(match);
+    const base = path39.posix.basename(match);
+    const dir = path39.posix.dirname(match);
     const owner = dir === "." ? "." : dir;
     if (base === ".git") gitDirs.add(owner);
     else manifestDirs.add(owner);
@@ -5451,9 +6251,9 @@ async function discoverRepos(workspaceRoot, maxDepth = DEFAULT_MAX_DEPTH) {
   }
   repoRoots.sort((a, b) => a.localeCompare(b));
   return mapWithConcurrency(repoRoots, async (relDir) => {
-    const absDir = path31.resolve(workspaceRoot, relDir);
-    const pkg = await readJson(path31.join(absDir, "package.json"));
-    const name = typeof pkg?.name === "string" && pkg.name.length > 0 ? pkg.name : path31.basename(relDir === "." ? workspaceRoot : absDir);
+    const absDir = path39.resolve(workspaceRoot, relDir);
+    const pkg = await readJson(path39.join(absDir, "package.json"));
+    const name = typeof pkg?.name === "string" && pkg.name.length > 0 ? pkg.name : path39.basename(relDir === "." ? workspaceRoot : absDir);
     let role = "auto";
     try {
       const scan = await scanProject(absDir);
@@ -5496,7 +6296,7 @@ function renderWorkspaceYaml(config) {
   });
 }
 async function runDiscover(workspaceRoot, opts = {}) {
-  const yamlPath = path31.join(workspaceRoot, "haus.workspace.yaml");
+  const yamlPath = path39.join(workspaceRoot, "haus.workspace.yaml");
   const existingText = await readText(yamlPath);
   const existing = parseWorkspaceConfig(existingText);
   if (existingText && !existing) {
@@ -5514,34 +6314,37 @@ async function runDiscover(workspaceRoot, opts = {}) {
   }
   const merged = mergeWorkspaceConfig(existing, discovered, { client: opts.client });
   const yamlText = renderWorkspaceYaml(merged);
-  if (opts.json) {
-    log(JSON.stringify({ discovered, config: merged }, null, 2));
-  }
   if (opts.write) {
     await writeText(yamlPath, yamlText);
-    log(`Wrote ${merged.repos.length} repo(s) to haus.workspace.yaml`);
+    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("Proposed haus.workspace.yaml (run with --write to persist):\n");
-    log(yamlText);
+  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/commands/workspace/doctor.ts
 import { existsSync as existsSync3 } from "node:fs";
-import path33 from "node:path";
+import path41 from "node:path";
 
 // src/commands/workspace/manifest.ts
 import { readFileSync as readFileSync3 } from "node:fs";
-import path32 from "node:path";
+import path40 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(path32.join(packageRoot(), "package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync3(path40.join(packageRoot(), "package.json"), "utf8"));
     return pkg.version ?? "0.0.0";
   } catch {
     return "0.0.0";
@@ -5607,7 +6410,7 @@ async function runWorkspaceDoctor(workspaceRoot, opts = {}) {
   }
   const manifestByName = new Map(manifest.repos.map((r) => [r.name, r]));
   for (const repo of config.repos) {
-    const repoRoot = path33.resolve(workspaceRoot, repo.path);
+    const repoRoot = path41.resolve(workspaceRoot, repo.path);
     const entry = manifestByName.get(repo.name);
     if (!entry) {
       flag({
@@ -5681,11 +6484,11 @@ function emit(args) {
 
 // src/commands/workspace/setup.ts
 import { existsSync as existsSync4, statSync } from "node:fs";
-import path35 from "node:path";
+import path43 from "node:path";
 
 // src/claude/write-workspace-claude-md.ts
-import path34 from "node:path";
-import fs23 from "fs-extra";
+import path42 from "node:path";
+import fs30 from "fs-extra";
 function buildWorkspaceImportBlock(client, members) {
   const memberLines = members.map((m) => `- ${m.name} (${m.path})`);
   const body = [
@@ -5703,25 +6506,27 @@ ${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") : path34.join(workspaceRoot, "CLAUDE.md");
-  const prev = await fs23.pathExists(filePath) ? await fs23.readFile(filePath, "utf8") : "";
+  const filePath = opts.collision ? hausPath(workspaceRoot, "WORKSPACE.md") : path42.join(workspaceRoot, "CLAUDE.md");
+  const say = opts.quiet ? () => {
+  } : log;
+  const prev = await fs30.pathExists(filePath) ? await fs30.readFile(filePath, "utf8") : "";
   const next = opts.collision ? `${block}
 ` : injectHausBlock(prev, block);
   const printable = displayPath(workspaceRoot, filePath);
   if (dryRun) {
     if (!prev) {
-      log(createUnifiedDiff(printable, "", next));
+      say(createUnifiedDiff(printable, "", next));
     } else if (hasTextChanged(prev, next)) {
-      log(createUnifiedDiff(printable, prev, next));
+      say(createUnifiedDiff(printable, prev, next));
     } else {
-      log(`${printable}: unchanged`);
+      say(`${printable}: unchanged`);
     }
     return filePath;
   }
   if (hasTextChanged(prev, next) && prev.length > 0) {
     const diffText = createUnifiedDiff(printable, prev, next);
     const summary = summarizeDiff(diffText);
-    log(`Overwriting ${printable} (diff +${summary.additions} -${summary.deletions})`);
+    say(`Overwriting ${printable} (diff +${summary.additions} -${summary.deletions})`);
   }
   await writeText(filePath, next);
   return filePath;
@@ -5729,20 +6534,20 @@ async function writeWorkspaceClaudeMd(workspaceRoot, opts) {
 
 // src/commands/workspace/setup.ts
 function resolveWorkspaceRoot(start = process.cwd()) {
-  let dir = path35.resolve(start);
+  let dir = path43.resolve(start);
   for (; ; ) {
-    if (existsSync4(path35.join(dir, WORKSPACE_FILE))) return dir;
-    const parent = path35.dirname(dir);
-    if (parent === dir) return path35.resolve(start);
+    if (existsSync4(path43.join(dir, WORKSPACE_FILE))) return dir;
+    const parent = path43.dirname(dir);
+    if (parent === dir) return path43.resolve(start);
     dir = parent;
   }
 }
 function isRootRepo(workspaceRoot, repoPath) {
-  return path35.resolve(workspaceRoot, repoPath) === path35.resolve(workspaceRoot);
+  return path43.resolve(workspaceRoot, repoPath) === path43.resolve(workspaceRoot);
 }
 async function runWorkspaceSetup(workspaceRoot, options = {}) {
   const apply = options.write ?? false;
-  const configText = await readText(path35.join(workspaceRoot, WORKSPACE_FILE));
+  const configText = await readText(path43.join(workspaceRoot, WORKSPACE_FILE));
   if (!configText) {
     error(`Missing ${WORKSPACE_FILE}. Run \`haus workspace discover\` or \`init\` first.`);
     process.exitCode = 1;
@@ -5754,22 +6559,34 @@ async function runWorkspaceSetup(workspaceRoot, options = {}) {
     process.exitCode = 1;
     return { workspaceRoot, statuses: [], written: [] };
   }
+  const say = options.json ? () => {
+  } : log;
   const onlySet = options.only && options.only.length > 0 ? new Set(options.only) : void 0;
+  if (onlySet) {
+    const unknown = [...onlySet].filter((name) => !config.repos.some((r) => r.name === name));
+    if (unknown.length > 0) {
+      error(`--only matched no configured repo(s): ${unknown.join(", ")}`);
+      process.exitCode = 1;
+      return { workspaceRoot, statuses: [], written: [] };
+    }
+  }
   const repos = onlySet ? config.repos.filter((r) => onlySet.has(r.name)) : config.repos;
   const statuses = [];
   const aggregateInputs = [];
   for (const repo of repos) {
-    const repoRoot = path35.resolve(workspaceRoot, repo.path);
-    log(`
+    const repoRoot = path43.resolve(workspaceRoot, repo.path);
+    say(`
 \u2192 ${repo.name} (${repo.path})`);
     try {
       if (!existsSync4(repoRoot) || !statSync(repoRoot).isDirectory()) {
         throw new Error(`Repo path is not a directory: ${repo.path}`);
       }
       const res = await runSetupCore(repoRoot, {
-        json: options.json,
         apply,
-        dryRun: options.dryRun
+        dryRun: options.dryRun,
+        // Under --json, mute the inner pipeline entirely; we serialize the
+        // aggregated result below. Otherwise let it print its normal human output.
+        quiet: options.json
       });
       statuses.push({
         name: repo.name,
@@ -5809,9 +6626,10 @@ async function runWorkspaceSetup(workspaceRoot, options = {}) {
       client: config.client,
       members: config.repos.map((r) => ({ name: r.name, path: r.path })),
       collision,
-      dryRun: options.dryRun
+      dryRun: options.dryRun,
+      quiet: options.json
     });
-    written.push(docPath);
+    if (!options.dryRun) written.push(docPath);
   }
   if (apply && !options.dryRun) {
     const statusByName = new Map(statuses.map((s) => [s.name, s]));
@@ -5827,7 +6645,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(path35.resolve(workspaceRoot, repo.path));
+        const lock = await checkLock(path43.resolve(workspaceRoot, repo.path));
         manifestRepos.push({
           name: repo.name,
           path: repo.path,
@@ -5876,9 +6694,17 @@ async function runWorkspaceSetup(workspaceRoot, options = {}) {
   }
   const ok = statuses.filter((s) => s.status === "ok").length;
   const failed = statuses.length - ok;
-  log(`
-Workspace setup complete: ${ok} ok, ${failed} failed.`);
-  return { workspaceRoot, statuses, written };
+  const result = { workspaceRoot, statuses, written };
+  if (options.json) {
+    log(JSON.stringify(result, null, 2));
+  } else if (!apply) {
+    say(`
+Workspace preview complete: ${ok} ok, ${failed} failed. Re-run with --write to apply.`);
+  } else {
+    say(`
+Workspace setup complete: ${ok} ok, ${failed} failed. Wrote ${written.length} file(s).`);
+  }
+  return result;
 }
 
 // src/commands/workspace.ts
@@ -5891,7 +6717,9 @@ function normalizeOnly(only) {
 function normalizeMaxDepth(maxDepth) {
   if (maxDepth === void 0) return void 0;
   const n = typeof maxDepth === "number" ? maxDepth : Number.parseInt(maxDepth, 10);
-  return Number.isFinite(n) && n > 0 ? Math.floor(n) : void 0;
+  if (Number.isFinite(n) && n > 0) return Math.floor(n);
+  warn(`Ignoring invalid --max-depth "${String(maxDepth)}"; using the default depth.`);
+  return void 0;
 }
 async function initWorkspace() {
   await writeText(
@@ -5907,7 +6735,7 @@ relationships: []
   log("Workspace initialized.");
 }
 async function scanWorkspace(workspaceRoot, opts) {
-  const configText = await readText(path36.join(workspaceRoot, WORKSPACE_FILE));
+  const configText = await readText(path44.join(workspaceRoot, WORKSPACE_FILE));
   if (!configText) {
     error(`Missing ${WORKSPACE_FILE}. Run \`haus workspace discover\` or \`init\` first.`);
     process.exitCode = 1;
@@ -5927,20 +6755,31 @@ async function scanWorkspace(workspaceRoot, opts) {
     return;
   }
   const inputs = [];
+  const failures = [];
   for (const repo of config.repos) {
-    const repoRoot = path36.resolve(workspaceRoot, repo.path);
-    if (!existsSync5(repoRoot) || !statSync2(repoRoot).isDirectory()) {
-      throw new Error(`Repo path is not a directory: ${repo.path}`);
+    const repoRoot = path44.resolve(workspaceRoot, repo.path);
+    try {
+      if (!existsSync5(repoRoot) || !statSync2(repoRoot).isDirectory()) {
+        throw new Error("path is not a directory");
+      }
+      const result = await scanProject(repoRoot);
+      inputs.push({ name: repo.name, path: repo.path, context: result });
+    } catch (err) {
+      failures.push(
+        `${repo.name} (${repo.path}): ${err instanceof Error ? err.message : String(err)}`
+      );
     }
-    const result = await scanProject(repoRoot);
-    inputs.push({ name: repo.name, path: repo.path, context: result });
   }
   const written = await writeWorkspaceArtifacts(workspaceRoot, inputs, config.relationships);
   if (opts.json) {
-    log(JSON.stringify({ written }, null, 2));
+    log(JSON.stringify({ written, scanned: inputs.length, failed: failures }, null, 2));
   } else {
-    log(`Workspace scan complete. Wrote ${written.length} artifact(s) under .haus-workflow/.`);
+    log(
+      `Workspace scan complete. Scanned ${inputs.length} repo(s); wrote ${written.length} artifact(s) under .haus-workflow/.`
+    );
+    for (const f of failures) warn(`- skipped ${f}`);
   }
+  if (failures.length > 0) process.exitCode = 1;
 }
 async function runWorkspace(action, options = {}) {
   if (action === "init") {
@@ -5978,7 +6817,7 @@ async function runWorkspace(action, options = {}) {
 // src/cli.ts
 function cliVersion() {
   try {
-    const pkgPath = path37.join(packageRoot(), "package.json");
+    const pkgPath = path45.join(packageRoot(), "package.json");
     const pkg = JSON.parse(readFileSync4(pkgPath, "utf8"));
     return pkg.version ?? "0.0.0";
   } catch {
@@ -5988,7 +6827,7 @@ function cliVersion() {
 var program = new Command();
 function validateRuntimeNodeVersion() {
   try {
-    const pkgPath = path37.join(packageRoot(), "package.json");
+    const pkgPath = path45.join(packageRoot(), "package.json");
     const pkg = JSON.parse(readFileSync4(pkgPath, "utf8"));
     const requiredRange = pkg.engines?.node;
     if (requiredRange && !satisfiesVersion(process.version, requiredRange)) {
@@ -6009,6 +6848,7 @@ program.command("recommend").option("--json").option(
 ).action(runRecommend);
 program.command("setup-project").option("--json").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(
   "--ids <ids...>",
   "Install exactly these recommended item ids non-interactively (skill backend; space- or comma-separated)"
@@ -6037,6 +6877,17 @@ program.command("uninstall").option("--force").action(runUninstallCommand);
 var guard = program.command("guard");
 guard.command("file-access").option("--from-hook").action((opts) => runGuard("file-access", opts));
 guard.command("bash").option("--from-hook").action((opts) => runGuard("bash", opts));
+function registerDecisionsCommand(name) {
+  const cmd = program.command(name).description("Architecture decision records (ADR) gate and drafts");
+  cmd.command("check").option("--staged", "Check staged changes only").option("--range <range>", "Git revision range (e.g. origin/main..HEAD)").action((opts) => runDecisions("check", void 0, opts));
+  cmd.command("suggest").option("--from-hook", "Emit JSON for Claude Code Stop hook").option("--title <title>", "Draft title").action(
+    (opts) => runDecisions("suggest", void 0, opts)
+  );
+  cmd.command("next-number").action(() => runDecisions("next-number"));
+  cmd.command("validate").argument("[path]", "Decision markdown file").action((filePath) => runDecisions("validate", filePath));
+}
+registerDecisionsCommand("decisions");
+registerDecisionsCommand("adr");
 var workspace = program.command("workspace");
 workspace.command("init").action(() => runWorkspace("init"));
 workspace.command("discover").description("Auto-find member repos and write/merge haus.workspace.yaml").option("--write", "Persist haus.workspace.yaml (default previews only)").option("--json", "Output the discovered repos and proposed config as JSON").option("--max-depth <n>", "Max directory depth to traverse (default 3)").option("--client <name>", "Set the workspace client name").action((opts) => runWorkspace("discover", opts));