@haus-tech/haus-workflow 5.10.1 → 5.11.0

package/dist/cli.js

@@ -337,13 +337,6 @@ var init_constants = __esm({
 });
 
 // src/utils/exec.ts
-var exec_exports = {};
-__export(exec_exports, {
-  assertNeverCommandProbe: () => assertNeverCommandProbe,
-  probeCommand: () => probeCommand,
-  runCommand: () => runCommand,
-  runGit: () => runGit
-});
 import { execa } from "execa";
 async function runCommand(command, args = [], options = {}) {
   try {
@@ -2965,6 +2958,14 @@ async function addProjectIncludedIds(root, ids) {
     includedIds: [.../* @__PURE__ */ new Set([...normalizeIdList(existing.includedIds), ...toAdd])].sort()
   }));
 }
+async function addProjectDeclaredRoles(root, roles) {
+  const toAdd = normalizeSignalList(roles.map((role) => role.replace(/^role=/i, "")));
+  if (toAdd.length === 0) return;
+  await updateProjectConfig(root, (existing) => ({
+    ...existing,
+    declaredRoles: [.../* @__PURE__ */ new Set([...normalizeSignalList(existing.declaredRoles), ...toAdd])].sort()
+  }));
+}
 function withdrawIncludedIds(existing, ids) {
   const drop = new Set(ids);
   return normalizeIdList(existing.includedIds).filter((id) => !drop.has(id));
@@ -8704,7 +8705,7 @@ async function runBundleImport(file, options = {}) {
 
 // src/commands/doctor.ts
 import path50 from "node:path";
-import fs42 from "fs-extra";
+import fs43 from "fs-extra";
 init_manifest_format();
 
 // src/claude/former-install-orphans.ts
@@ -9044,14 +9045,14 @@ async function readScannedMarkdown(root) {
 
 // src/decisions/doctor.ts
 import path48 from "node:path";
-import fs40 from "fs-extra";
+import fs41 from "fs-extra";
 init_fs();
 
 // src/decisions/check.ts
 init_fs();
 init_paths();
 import path47 from "node:path";
-import fs39 from "fs-extra";
+import fs40 from "fs-extra";
 
 // src/decisions/dep-bump.ts
 var DEP_SECTIONS = [
@@ -9112,6 +9113,7 @@ function isDependencyBumpOnly(beforeText, afterText) {
 init_exec();
 init_fs();
 import path44 from "node:path";
+import fs37 from "fs-extra";
 var NUL = String.fromCharCode(0);
 function parseNumstat(output) {
   const fields = output.split(NUL);
@@ -9138,6 +9140,27 @@ function parseNumstat(output) {
   }
   return { linesByFile, linesAdded, linesRemoved };
 }
+function parseNameStatus(output) {
+  const fields = output.split(NUL);
+  const files = [];
+  const presentFiles = [];
+  const renames = [];
+  for (let i = 0; i < fields.length; i++) {
+    const status = fields[i];
+    if (!status) continue;
+    const step = /^[RC]/.test(status) ? 2 : 1;
+    const from = fields[i + 1];
+    const file = fields[i + step];
+    i += step;
+    if (!file) continue;
+    files.push(file);
+    if (status !== "D") presentFiles.push(file);
+    if (status.startsWith("R") && from) {
+      renames.push({ from, to: file, similarity: Number(status.slice(1)) });
+    }
+  }
+  return { files, presentFiles, renames };
+}
 function isPackageJsonPath(file) {
   return file === "package.json" || file.endsWith("/package.json");
 }
@@ -9169,6 +9192,10 @@ function toAncestryLogRange(range) {
   if (!parsed) return `${range}..HEAD`;
   return `${parsed.left}..${parsed.right}`;
 }
+async function readCommitMessages(root, range) {
+  const log2 = await runGit(["log", "-z", "--format=%B", toAncestryLogRange(range)], { cwd: root });
+  return log2.stdout.split(NUL).filter((message2) => message2.trim().length > 0);
+}
 async function getCurrentBranch(root) {
   const result = await runGit(["rev-parse", "--abbrev-ref", "HEAD"], { cwd: root });
   if (result.exitCode !== 0) return void 0;
@@ -9178,33 +9205,45 @@ async function getCurrentBranch(root) {
   if (gha) return gha;
   return void 0;
 }
-async function resolvePackageJsonPair(root, file, opts) {
-  const empty = "{}";
-  if (opts.staged) {
-    const before2 = await readBlob(root, `HEAD:${file}`) ?? empty;
-    const after2 = await readBlob(root, `:${file}`) ?? empty;
-    return { before: before2, after: after2 };
-  }
+async function diffBaseRev(root, opts) {
+  if (opts.staged) return "HEAD";
   const range = opts.range ?? "HEAD";
   const parsed = parseDiffRange(range);
-  if (parsed) {
-    let leftRev = parsed.left;
-    if (parsed.triple) {
-      const mb = await runGit(["merge-base", parsed.left, parsed.right], { cwd: root });
-      leftRev = mb.exitCode === 0 ? mb.stdout.trim() : parsed.left;
-    }
-    const before2 = await readBlob(root, `${leftRev}:${file}`) ?? empty;
-    const after2 = await readBlob(root, `${parsed.right}:${file}`) ?? empty;
-    return { before: before2, after: after2 };
-  }
-  const before = await readBlob(root, `${range}:${file}`) ?? empty;
-  const after = await readText(path44.join(root, file)) ?? empty;
+  if (!parsed) return range;
+  if (!parsed.triple) return parsed.left;
+  const mb = await runGit(["merge-base", parsed.left, parsed.right], { cwd: root });
+  return mb.exitCode === 0 ? mb.stdout.trim() : parsed.left;
+}
+async function resolvePackageJsonPair(root, file, opts) {
+  const empty = "{}";
+  const before = await readBlob(root, `${await diffBaseRev(root, opts)}:${file}`) ?? empty;
+  const after = await readDiffContent(root, file, opts) ?? empty;
   return { before, after };
 }
+async function existsAtDiffBase(root, relPath, opts) {
+  const base = await diffBaseRev(root, opts);
+  return (await runGit(["cat-file", "-e", `${base}:${relPath}`], { cwd: root })).exitCode === 0;
+}
+async function readDiffContent(root, file, opts) {
+  if (opts.staged) return await readBlob(root, `:${file}`) ?? void 0;
+  const parsed = parseDiffRange(opts.range ?? "HEAD");
+  if (parsed) return await readBlob(root, `${parsed.right}:${file}`) ?? void 0;
+  return readText(path44.join(root, file));
+}
+async function listDiffDirectory(root, dirRel, opts) {
+  const prefix = `${dirRel}/`;
+  const listDirect = async (args) => (await runGit(args, { cwd: root })).stdout.split(NUL).filter((rel) => rel.startsWith(prefix) && !rel.slice(prefix.length).includes("/"));
+  if (opts.staged) return listDirect(["ls-files", "-z", "--", prefix]);
+  const parsed = parseDiffRange(opts.range ?? "HEAD");
+  if (parsed) return listDirect(["ls-tree", "-z", "--name-only", parsed.right, "--", prefix]);
+  const dir = path44.join(root, dirRel);
+  if (!await fs37.pathExists(dir)) return [];
+  return (await fs37.readdir(dir)).map((name) => `${prefix}${name}`);
+}
 async function collectDiffStats(root, opts) {
-  const gitArgs = opts.staged ? ["diff", "--cached", "--name-only"] : ["diff", "--name-only", opts.range ?? "HEAD"];
+  const gitArgs = opts.staged ? ["diff", "--cached", "--name-status", "-z"] : ["diff", "--name-status", "-z", opts.range ?? "HEAD"];
   const names = await runGit(gitArgs, { cwd: root });
-  const files = names.stdout.split("\n").map((f) => f.trim()).filter(Boolean);
+  const { files, presentFiles, renames } = parseNameStatus(names.stdout);
   const numstatArgs = opts.staged ? ["diff", "--cached", "--numstat", "-z"] : ["diff", "--numstat", "-z", opts.range ?? "HEAD"];
   const numstat = await runGit(numstatArgs, { cwd: root });
   const { linesByFile, linesAdded, linesRemoved } = parseNumstat(numstat.stdout);
@@ -9215,6 +9254,8 @@ async function collectDiffStats(root, opts) {
   }
   return {
     files,
+    presentFiles,
+    renames,
     linesAdded,
     linesRemoved,
     linesByFile,
@@ -9262,12 +9303,12 @@ function firstMatchingRegex(filePath, patterns) {
 
 // src/decisions/paths.ts
 import path45 from "node:path";
-import fs37 from "fs-extra";
+import fs38 from "fs-extra";
 async function resolveDecisionsDir(root) {
   const primary = path45.join(root, DECISIONS_TRIGGERS.decisionsDir);
-  if (await fs37.pathExists(primary)) return primary;
+  if (await fs38.pathExists(primary)) return primary;
   const legacy = path45.join(root, DECISIONS_TRIGGERS.legacyDecisionsDir ?? "docs/adr");
-  if (await fs37.pathExists(legacy)) return legacy;
+  if (await fs38.pathExists(legacy)) return legacy;
   return primary;
 }
 function relativeDecisionPath(decisionsDir, root) {
@@ -9277,7 +9318,7 @@ function relativeDecisionPath(decisionsDir, root) {
 // src/decisions/validate.ts
 init_fs();
 import path46 from "node:path";
-import fs38 from "fs-extra";
+import fs39 from "fs-extra";
 function validateDecisionContent(content2) {
   const errors = [];
   for (const section of DECISIONS_TRIGGERS.requiredSections) {
@@ -9305,10 +9346,38 @@ function decisionNumberFromFile(name) {
   const match = /^(\d{4})-/.exec(name);
   return match?.[1] ?? null;
 }
-async function validateIndexSync(decisionsDir, decisionFiles) {
+var ADR_HEADING_RE = /^#\s+ADR-\d{4}\b/;
+function firstHeading(content2) {
+  const lines = content2.split(/\r?\n/);
+  let start = 0;
+  if (lines[0]?.trim() === "---") {
+    const end = lines.findIndex((line2, i) => i > 0 && line2.trim() === "---");
+    if (end > 0) start = end + 1;
+  }
+  let fence;
+  for (const line2 of lines.slice(start)) {
+    const marker = /^ {0,3}(`{3,}|~{3,})/.exec(line2)?.[1];
+    if (marker != null) {
+      if (fence == null) fence = marker;
+      else if (marker[0] === fence[0] && marker.length >= fence.length) fence = void 0;
+      continue;
+    }
+    if (fence == null && /^#{1,6}(\s|$)/.test(line2)) return line2;
+  }
+  return void 0;
+}
+function isAdrShaped(relPath, content2) {
+  const segments = relPath.replace(/\\/g, "/").toLowerCase().split("/");
+  const dirs = segments.slice(0, -1);
+  if (!/\.md$/i.test(relPath) || dirs.includes("templates")) return false;
+  if (dirs.includes("adr")) return true;
+  const heading = firstHeading(content2);
+  return heading != null && ADR_HEADING_RE.test(heading);
+}
+async function validateIndexSync(decisionsDir, decisionFiles, decisionsRel) {
   const readmePath = path46.join(decisionsDir, "README.md");
-  if (!await fs38.pathExists(readmePath)) {
-    return ["docs/decisions/README.md is missing"];
+  if (!await fs39.pathExists(readmePath)) {
+    return [`${decisionsRel}/README.md is missing`];
   }
   const readme = await readText(readmePath) ?? "";
   const errors = [];
@@ -9322,6 +9391,9 @@ async function validateIndexSync(decisionsDir, decisionFiles) {
 }
 
 // src/decisions/check.ts
+function noRecordFailure() {
+  return { missingDecision: false, recordErrors: [], recordWayOut: "" };
+}
 var MANIFEST_LOCK_BASENAMES = /* @__PURE__ */ new Set([
   "package.json",
   "yarn.lock",
@@ -9406,34 +9478,92 @@ async function readGateMode(root) {
   const cfg = await readJson(hausPath(root, "adr-gate.json"));
   return cfg?.mode === "off" ? "off" : "on";
 }
+var SKIP_DIRECTIVE = "[adr-skip]";
+function textLines(text) {
+  return text.split(/\r\n|\r|\n/);
+}
 function hasSkipToken(text) {
-  return text.includes("[adr-skip]");
+  return textLines(text).some((line2) => line2.trimStart().startsWith(SKIP_DIRECTIVE));
 }
-async function checkSatisfaction(input2) {
-  const errors = [];
-  const decisionsPrefix = `${input2.decisionsRel}/`;
-  const newDecisionFiles = input2.changedFiles.filter(
-    (f) => f.startsWith(decisionsPrefix) && isDecisionFileName(path47.basename(f))
+function commitHasSkipDirective(message2) {
+  return hasSkipToken(textLines(message2).slice(1).join("\n"));
+}
+async function migratedRecords(root, decisionsRel, renames, diff) {
+  const legacyRel = DECISIONS_TRIGGERS.legacyDecisionsDir ?? "docs/adr";
+  if (decisionsRel === legacyRel) return /* @__PURE__ */ new Set();
+  const moved = renames.filter(
+    (r) => r.similarity === 100 && r.from.startsWith(`${legacyRel}/`) && r.to.startsWith(`${decisionsRel}/`)
+  );
+  if (moved.length === 0 || await existsAtDiffBase(root, decisionsRel, diff)) return /* @__PURE__ */ new Set();
+  return new Set(moved.map((r) => r.to));
+}
+async function duplicateNumbers(input2, records) {
+  if (records.length === 0) return [];
+  const numberOf = (rel) => decisionNumberFromFile(path47.basename(rel));
+  const listed = (await listDiffDirectory(input2.root, input2.decisionsRel, input2.diff)).filter(
+    (rel) => isDecisionFileName(path47.basename(rel))
   );
-  if (newDecisionFiles.length === 0) {
-    errors.push(`no new or updated decision under ${input2.decisionsRel}/`);
-    return errors;
+  const messages = [];
+  for (const num of new Set(records.map(numberOf))) {
+    if (num == null) continue;
+    const changed = records.filter((rel) => numberOf(rel) === num).sort();
+    const others = listed.filter((rel) => numberOf(rel) === num && !changed.includes(rel)).sort();
+    if (changed.length + others.length < 2) continue;
+    messages.push(
+      `duplicate ADR number ${num}: ${[...changed, ...others].join(", ")}; take the next free number (haus decisions next-number)`
+    );
   }
+  return messages;
+}
+async function auditChangedRecords(input2) {
+  const decisionsPrefix = `${input2.decisionsRel}/`;
   const decisionsDir = path47.join(input2.root, input2.decisionsRel);
-  for (const rel of newDecisionFiles) {
-    const abs = path47.join(input2.root, rel);
-    const content2 = await readText(abs) ?? "";
+  const audit = {
+    records: [],
+    misplaced: [],
+    failing: [],
+    duplicates: [],
+    errors: []
+  };
+  const indexErrors = /* @__PURE__ */ new Set();
+  for (const rel of input2.changedFiles) {
+    if (!/\.md$/i.test(rel)) continue;
+    const inside = rel.startsWith(decisionsPrefix);
+    if (inside && !isDecisionFileName(path47.basename(rel))) continue;
+    const content2 = await readDiffContent(input2.root, rel, input2.diff);
+    if (content2 === void 0) continue;
+    if (!inside) {
+      if (!isAdrShaped(rel, content2)) continue;
+      audit.misplaced.push(rel);
+      audit.errors.push(`no ADR outside ${decisionsPrefix}: ${rel}`);
+      continue;
+    }
+    audit.records.push(rel);
     const valid = validateDecisionContent(content2);
-    if (!valid.ok) errors.push(...valid.errors.map((e) => `${rel}: ${e}`));
-  }
-  const indexErrors = await validateIndexSync(
-    decisionsDir,
-    newDecisionFiles.map((f) => path47.basename(f))
-  );
-  errors.push(...indexErrors);
-  return errors;
+    const index = await validateIndexSync(decisionsDir, [path47.basename(rel)], input2.decisionsRel);
+    if (!valid.ok) audit.errors.push(...valid.errors.map((e) => `${rel}: ${e}`));
+    for (const e of index) indexErrors.add(e);
+    if (!valid.ok || index.length > 0) audit.failing.push(rel);
+  }
+  audit.duplicates = await duplicateNumbers(input2, audit.records);
+  audit.errors.push(...indexErrors, ...audit.duplicates);
+  return audit;
+}
+function waysOut(decisionsRel) {
+  return `Write an ADR under ${decisionsRel}/ (haus decisions suggest), or put [adr-skip] on its own line in the PR body or a commit body for non-security changes.`;
+}
+function recordWayOut(decisionsRel, audit, answersTrigger) {
+  if (audit.errors.length === 0) return "";
+  const answers = answersTrigger ? "; a record moved there also answers the trigger" : "";
+  const steps = [
+    ...audit.misplaced.length > 0 ? [
+      `Move ${audit.misplaced.join(", ")} into ${decisionsRel}/ under the next free number (haus decisions next-number) with the house heading${answers}.`
+    ] : [],
+    ...audit.duplicates.map((duplicate) => `${duplicate}.`),
+    ...audit.failing.length > 0 ? [`Fix ${audit.failing.join(", ")} in place.`] : []
+  ];
+  return `${steps.join(" ")} A record takes the house format: a \`# ADR-NNNN: Title\` heading, the sections ## Context, ## Decision and ## Consequences, and a row in ${decisionsRel}/README.md. Even [adr-skip] on its own line does not waive this.`;
 }
-var WAYS_OUT = "Write an ADR under docs/decisions/ (haus decisions suggest), or use [adr-skip] for non-security changes.";
 async function runDecisionsCheck(root, opts = {}) {
   const reasons = [];
   if (await readGateMode(root) === "off") {
@@ -9441,7 +9571,8 @@ async function runDecisionsCheck(root, opts = {}) {
       triggered: false,
       satisfied: true,
       reasons: ["gate disabled via .haus-workflow/adr-gate.json"],
-      securityTriggered: false
+      securityTriggered: false,
+      ...noRecordFailure()
     };
   }
   const stats = await collectDiffStats(root, opts);
@@ -9452,73 +9583,77 @@ async function runDecisionsCheck(root, opts = {}) {
       triggered: false,
       satisfied: true,
       reasons: ["catalog-sync branch \u2014 exempt"],
-      securityTriggered: false
+      securityTriggered: false,
+      ...noRecordFailure()
     };
   }
+  const decisionsDir = await resolveDecisionsDir(root);
+  const decisionsRel = relativeDecisionPath(decisionsDir, root);
+  const diff = { staged: opts.staged, range: opts.range };
+  const migrated = await migratedRecords(root, decisionsRel, stats.renames ?? [], diff);
+  const changed = await auditChangedRecords({
+    root,
+    decisionsRel,
+    changedFiles: (stats.presentFiles ?? stats.files).filter((rel) => !migrated.has(rel)),
+    diff
+  });
   const triggerReasons = explainDecisionTrigger(stats);
-  const triggered = triggerReasons.length > 0;
+  const triggered = triggerReasons.length > 0 || changed.errors.length > 0;
   if (!triggered) {
     return {
       triggered: false,
       satisfied: true,
       reasons: ["no decision-worthy changes"],
-      securityTriggered
+      securityTriggered,
+      ...noRecordFailure()
     };
   }
   reasons.push(...triggerReasons);
-  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 skip = hasSkipToken(opts.prBody ?? "") || (opts.commitMessages ?? []).some(commitHasSkipDirective);
+  const waived = skip && !securityTriggered;
+  if (waived && changed.errors.length === 0) {
+    reasons.push("gate waived by [adr-skip] on its own line (non-security change)");
+    return { triggered: true, satisfied: true, reasons, securityTriggered, ...noRecordFailure() };
+  }
+  if (waived) {
+    reasons.push(
+      "the trigger rules are waived by [adr-skip] on its own line, but a failing record is not"
+    );
   }
-  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 fs39.pathExists(path47.join(root, legacyRel));
-    if (legacyExists && !await fs39.pathExists(decisionsDir)) {
-      satisfactionErrors = await checkSatisfaction({
-        root,
-        decisionsRel: legacyRel,
-        changedFiles: stats.files
-      });
-    }
+  if (skip && securityTriggered) {
+    reasons.push("security/auth path changes ignore [adr-skip], even on its own line");
   }
-  if (satisfactionErrors.length === 0) {
+  const missingDecision = !waived && triggerReasons.length > 0 && changed.records.length === 0;
+  const wayOut = recordWayOut(decisionsRel, changed, missingDecision);
+  const recordFields = { missingDecision, recordErrors: changed.errors, recordWayOut: wayOut };
+  if (!missingDecision && changed.errors.length === 0) {
     reasons.push("decision record present");
-    return {
-      triggered: true,
-      satisfied: true,
-      reasons,
-      securityTriggered
-    };
+    return { triggered: true, satisfied: true, reasons, securityTriggered, ...recordFields };
   }
-  reasons.push(...satisfactionErrors);
-  reasons.push(WAYS_OUT);
-  return { triggered: true, satisfied: false, reasons, securityTriggered };
+  if (missingDecision) reasons.push(`no new or updated decision under ${decisionsRel}/`);
+  reasons.push(...changed.errors);
+  if (missingDecision && changed.errors.length === 0) reasons.push(waysOut(decisionsRel));
+  if (wayOut) reasons.push(wayOut);
+  return { triggered: true, satisfied: false, reasons, securityTriggered, ...recordFields };
 }
 async function listDecisionNumbers(decisionsDir) {
-  if (!await fs39.pathExists(decisionsDir)) return [];
-  const entries = await fs39.readdir(decisionsDir);
+  if (!await fs40.pathExists(decisionsDir)) return [];
+  const entries = await fs40.readdir(decisionsDir);
   return entries.map((name) => decisionNumberFromFile(name)).filter((n) => n != null).map((n) => Number(n));
 }
 
 // src/decisions/doctor.ts
+async function countMarkdownFiles(dir) {
+  if (!(await fs41.stat(dir)).isDirectory()) return 0;
+  const entries = await fs41.readdir(dir, { recursive: true, withFileTypes: true });
+  return entries.filter((entry) => entry.isFile() && /\.md$/i.test(entry.name)).length;
+}
 async function auditDecisionsLayout(root, profile) {
   const findings = [];
   const primary = path48.join(root, DECISIONS_TRIGGERS.decisionsDir);
   const legacy = path48.join(root, DECISIONS_TRIGGERS.legacyDecisionsDir ?? "docs/adr");
-  const hasPrimary = await fs40.pathExists(primary);
-  const hasLegacy = await fs40.pathExists(legacy);
+  const hasPrimary = await fs41.pathExists(primary);
+  const hasLegacy = await fs41.pathExists(legacy);
   if (!hasPrimary && hasLegacy) {
     if (PROFILES[profile].writesDecisionsSeed) {
       findings.push({
@@ -9531,10 +9666,20 @@ async function auditDecisionsLayout(root, profile) {
     return findings;
   }
   if (!hasPrimary) return findings;
+  if (hasLegacy) {
+    const legacyRel = DECISIONS_TRIGGERS.legacyDecisionsDir ?? "docs/adr";
+    const primaryRel = DECISIONS_TRIGGERS.decisionsDir;
+    findings.push({
+      level: "advisory",
+      line: `- DECISIONS: a second ADR home exists at ${legacyRel}/ (${await countMarkdownFiles(legacy)} file(s)); records there are invisible to the gate`,
+      sentence: `Decision records in ${legacyRel}/ never count: the decisions gate accepts records only in ${primaryRel}/, and a record moved there must pass haus decisions validate and take a free number`,
+      fix: `move each file to ${primaryRel}/ under the next free number (haus decisions next-number), with the # ADR-NNNN: Title heading and a README row`
+    });
+  }
   const decisionsDir = await resolveDecisionsDir(root);
   const rel = relativeDecisionPath(decisionsDir, root);
   const readmePath = path48.join(decisionsDir, "README.md");
-  if (!await fs40.pathExists(readmePath)) {
+  if (!await fs41.pathExists(readmePath)) {
     findings.push({
       level: "advisory",
       line: `- DECISIONS: missing ${rel}/README.md index`,
@@ -9544,7 +9689,7 @@ async function auditDecisionsLayout(root, profile) {
     return findings;
   }
   const readme = await readText(readmePath);
-  const entries = (await fs40.readdir(decisionsDir)).filter(
+  const entries = (await fs41.readdir(decisionsDir)).filter(
     (f) => f.endsWith(".md") && f !== "README.md"
   );
   for (const file of entries) {
@@ -9593,7 +9738,7 @@ init_fs();
 init_logger();
 init_paths();
 import path49 from "node:path";
-import fs41 from "fs-extra";
+import fs42 from "fs-extra";
 function manifestPathIn(configDir) {
   return path49.join(configDir, "haus", "install-manifest.json");
 }
@@ -9623,9 +9768,9 @@ async function pruneVacatedDirs(root, vacatedFiles) {
 async function destinationWritable(dir) {
   let candidate = path49.resolve(dir);
   for (; ; ) {
-    if (await fs41.pathExists(candidate)) {
+    if (await fs42.pathExists(candidate)) {
       try {
-        await fs41.access(candidate, fs41.constants.W_OK);
+        await fs42.access(candidate, fs42.constants.W_OK);
         return true;
       } catch (err) {
         return err instanceof Error ? err.message : String(err);
@@ -9657,7 +9802,7 @@ async function migrateGlobalConfigDir(options = {}) {
   if (!legacy || !Array.isArray(legacy.files)) {
     return { ...base, reason: "no install manifest under ~/.claude" };
   }
-  if (await fs41.pathExists(manifestPathIn(to))) {
+  if (await fs42.pathExists(manifestPathIn(to))) {
     return { ...base, reason: "an install manifest already exists in the resolved config dir" };
   }
   const writable = await destinationWritable(to);
@@ -9680,14 +9825,14 @@ async function migrateGlobalConfigDir(options = {}) {
       continue;
     }
     const newDest = path49.join(to, rel);
-    if (!await fs41.pathExists(entry.destPath)) {
+    if (!await fs42.pathExists(entry.destPath)) {
       rewritten.push({ ...entry, destPath: newDest });
       continue;
     }
-    if (await fs41.pathExists(newDest)) {
+    if (await fs42.pathExists(newDest)) {
       if (await sameContent(entry.destPath, newDest)) {
         if (!dryRun) {
-          await fs41.remove(entry.destPath);
+          await fs42.remove(entry.destPath);
           vacated.push(entry.destPath);
         }
         moved.push(newDest);
@@ -9704,7 +9849,7 @@ async function migrateGlobalConfigDir(options = {}) {
       continue;
     }
     try {
-      await fs41.move(entry.destPath, newDest);
+      await fs42.move(entry.destPath, newDest);
       vacated.push(entry.destPath);
       moved.push(newDest);
       rewritten.push({ ...entry, destPath: newDest });
@@ -9729,7 +9874,7 @@ async function migrateGlobalConfigDir(options = {}) {
   }
   try {
     await writeJson(manifestPathIn(to), { ...legacy, files: rewritten });
-    await fs41.remove(legacyManifestPath);
+    await fs42.remove(legacyManifestPath);
     vacated.push(legacyManifestPath);
   } catch (err) {
     return {
@@ -10027,7 +10172,7 @@ async function runDoctor(options) {
         const resolved = path50.resolve(root, target);
         const relFromRoot = path50.relative(root, resolved);
         const escapesRoot = relFromRoot === ".." || relFromRoot.startsWith(`..${path50.sep}`) || path50.isAbsolute(relFromRoot);
-        if (escapesRoot || !await fs42.pathExists(resolved)) {
+        if (escapesRoot || !await fs43.pathExists(resolved)) {
           flag(
             `- CLAUDE.md import: @${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`,
@@ -10045,7 +10190,7 @@ async function runDoctor(options) {
     );
   }
   const workflowPath = hausPath(root, "WORKFLOW.md");
-  const workflowExists = await fs42.pathExists(workflowPath);
+  const workflowExists = await fs43.pathExists(workflowPath);
   if (!workflowExists) {
     flag(
       "- .haus-workflow/WORKFLOW.md: missing (run `haus apply --write`)",
@@ -10068,7 +10213,7 @@ async function runDoctor(options) {
         "templates",
         path50.basename(PROFILES[profile].workflowTemplateRel)
       );
-      const templatePath = await fs42.pathExists(cachePath) ? cachePath : bundledPath;
+      const templatePath = await fs43.pathExists(cachePath) ? cachePath : bundledPath;
       const templateContent = await readText(templatePath);
       const verdict = checkManagedTamper(bodyContent, managedHeader.hash, templateContent ?? null);
       if (verdict.status === "tampered" || verdict.status === "legacy-diverged") {
@@ -10096,7 +10241,7 @@ async function runDoctor(options) {
     }
   }
   const workflowConfigPath = hausPath(root, "workflow-config.md");
-  const workflowConfigExists = await fs42.pathExists(workflowConfigPath);
+  const workflowConfigExists = await fs43.pathExists(workflowConfigPath);
   if (!workflowConfigExists) {
     flag(
       "- .haus-workflow/workflow-config.md: missing (run `haus apply --write`)",
@@ -10104,7 +10249,7 @@ async function runDoctor(options) {
       "haus apply --write"
     );
   } else {
-    const cfg = await fs42.readFile(workflowConfigPath, "utf8");
+    const cfg = await fs43.readFile(workflowConfigPath, "utf8");
     const unfilled = cfg.split("\n").filter((l) => l.includes("<!-- fill in")).length;
     if (unfilled > 0) {
       suggest(
@@ -10116,11 +10261,11 @@ async function runDoctor(options) {
       ok("- .haus-workflow/workflow-config.md: OK (project-owned)");
     }
   }
-  const docsSkillInstalled = await fs42.pathExists(
+  const docsSkillInstalled = await fs43.pathExists(
     path50.join(root, ".claude", "skills", "writing-documentation", "SKILL.md")
   );
   if (docsSkillInstalled) {
-    if (await fs42.pathExists(path50.join(root, "docs", "SUMMARY.md"))) {
+    if (await fs43.pathExists(path50.join(root, "docs", "SUMMARY.md"))) {
       ok("- PROJECT DOCS: OK (docs/SUMMARY.md present)");
     } else if (PROFILES[profile].runsDocsPass) {
       suggest(
@@ -10449,7 +10594,7 @@ async function runDoctor(options) {
       suggest(
         `- ELIGIBILITY DRIFT: ${drifted.length} installed item(s) are no longer recommended by the current signals (${drifted.slice(0, 3).join(", ")}${drifted.length > 3 ? ", \u2026" : ""})`,
         `${drifted.length} installed item(s) no longer match anything haus can detect in this repo \u2014 often a role that only \`deep-context.json\` knew about, which is not tracked in git`,
-        "declare the role or stack in .haus-workflow/haus.config.json (declaredRoles / declaredStacks), re-run the docs pass to regenerate deep-context.json, or `haus remove <id>` if the item is genuinely no longer wanted"
+        "declare the role with `haus recommend --declare-role <role>` or the stack in .haus-workflow/haus.config.json (declaredStacks), re-run the docs pass to regenerate deep-context.json, or `haus remove <id>` if the item is genuinely no longer wanted"
       );
     }
   }
@@ -10684,7 +10829,7 @@ async function runDoctor(options) {
       let onDisk = false;
       for (const rel of row.paths ?? []) {
         const abs = resolveContainedPath(root, rel);
-        if (abs !== null && await fs42.pathExists(abs)) {
+        if (abs !== null && await fs43.pathExists(abs)) {
           onDisk = true;
           break;
         }
@@ -10766,11 +10911,11 @@ init_github_rate_limit();
 init_private_catalog_access();
 
 // src/claude/refresh-project.ts
-import fs43 from "fs-extra";
+import fs44 from "fs-extra";
 init_fs();
 init_paths();
 async function isHausProject(root) {
-  if (await fs43.pathExists(hausPath(root, "recommendation.json"))) return true;
+  if (await fs44.pathExists(hausPath(root, "recommendation.json"))) return true;
   const settings = await readJsonDetailed(claudePath(root, "settings.json"));
   if (settings.status === "ok" && settings.value._haus != null) return true;
   const lock = await readJsonDetailed(hausPath(root, "haus.lock.json"));
@@ -10792,7 +10937,7 @@ async function refreshProjectApply(root) {
 
 // src/install/apply.ts
 import path52 from "node:path";
-import fs45 from "fs-extra";
+import fs46 from "fs-extra";
 init_fs();
 init_logger();
 init_paths();
@@ -10902,7 +11047,7 @@ ${content2}`;
 // src/install/internal-channel.ts
 init_fs();
 import path51 from "node:path";
-import fs44 from "fs-extra";
+import fs45 from "fs-extra";
 var INSTALL_CONFIG_SCHEMA = "haus-install-config/1";
 var INTERNAL_NAME_PREFIXES = ["request", "slack-cowork"];
 function internalPrefixMatch(name) {
@@ -10936,7 +11081,7 @@ async function writeInstallConfig(config) {
 }
 async function removeInstallConfig() {
   const p = installConfigPath();
-  if (fs44.pathExistsSync(p)) await fs44.remove(p);
+  if (fs45.pathExistsSync(p)) await fs45.remove(p);
 }
 function envOverride() {
   const raw = process.env.HAUS_INTERNAL_CHANNEL?.trim().toLowerCase();
@@ -10966,8 +11111,8 @@ async function pruneEmptyDirsUpward(dirs, stopAt) {
     let dir = start;
     while (dir.startsWith(stopAt) && dir !== stopAt) {
       try {
-        if ((await fs45.readdir(dir)).length > 0) break;
-        await fs45.remove(dir);
+        if ((await fs46.readdir(dir)).length > 0) break;
+        await fs46.remove(dir);
       } catch {
         break;
       }
@@ -10980,7 +11125,7 @@ function hashContent(content2) {
 }
 function destFileMissing(destPath) {
   try {
-    return !fs45.statSync(destPath).isFile();
+    return !fs46.statSync(destPath).isFile();
   } catch {
     return true;
   }
@@ -10988,7 +11133,7 @@ function destFileMissing(destPath) {
 function sourceVersion() {
   try {
     const pkgPath = path52.join(packageRoot(), "package.json");
-    const pkg = JSON.parse(fs45.readFileSync(pkgPath, "utf8"));
+    const pkg = JSON.parse(fs46.readFileSync(pkgPath, "utf8"));
     return `${pkg.name ?? "haus"}@${pkg.version ?? "0.0.0"}`;
   } catch {
     return "haus@0.0.0";
@@ -11000,10 +11145,10 @@ function globalSrcDir() {
 function collectSkillAuxFiles(skillsDir, claudeDir, skillName) {
   const skillDir = path52.join(skillsDir, skillName);
   const entries = [];
-  for (const rel of fs45.readdirSync(skillDir, { recursive: true })) {
+  for (const rel of fs46.readdirSync(skillDir, { recursive: true })) {
     if (rel === "SKILL.md") continue;
     const abs = path52.join(skillDir, rel);
-    if (!fs45.statSync(abs).isFile()) continue;
+    if (!fs46.statSync(abs).isFile()) continue;
     const posixRel = rel.split(path52.sep).join("/");
     entries.push({
       stableId: `skill.${skillName}.${posixRel.replace(/\//g, ".")}`,
@@ -11016,8 +11161,8 @@ function collectSkillAuxFiles(skillsDir, claudeDir, skillName) {
 function collectFlatChannel(srcDir, claudeDir, dirName, idPrefix) {
   const entries = [];
   const channelDir = path52.join(srcDir, dirName);
-  if (!fs45.pathExistsSync(channelDir)) return entries;
-  for (const fileName of fs45.readdirSync(channelDir)) {
+  if (!fs46.pathExistsSync(channelDir)) return entries;
+  for (const fileName of fs46.readdirSync(channelDir)) {
     if (!fileName.endsWith(".md")) continue;
     const name = fileName.slice(0, -".md".length);
     entries.push({
@@ -11031,10 +11176,10 @@ function collectFlatChannel(srcDir, claudeDir, dirName, idPrefix) {
 function collectSourceFiles(srcDir, claudeDir) {
   const entries = [];
   const skillsDir = path52.join(srcDir, "skills");
-  if (fs45.pathExistsSync(skillsDir)) {
-    for (const skillName of fs45.readdirSync(skillsDir)) {
+  if (fs46.pathExistsSync(skillsDir)) {
+    for (const skillName of fs46.readdirSync(skillsDir)) {
       const skillFile = path52.join(skillsDir, skillName, "SKILL.md");
-      if (fs45.pathExistsSync(skillFile)) {
+      if (fs46.pathExistsSync(skillFile)) {
         entries.push({
           stableId: `skill.${skillName}`,
           srcRelPath: path52.join("library", "global", "skills", skillName, "SKILL.md"),
@@ -11107,7 +11252,7 @@ async function applyInstall(options = {}) {
       }
       continue;
     }
-    const destExists = fs45.pathExistsSync(entry.destPath);
+    const destExists = fs46.pathExistsSync(entry.destPath);
     if (destExists) {
       const currentContent = await readText(entry.destPath);
       if (currentContent !== void 0) {
@@ -11167,13 +11312,13 @@ async function applyInstall(options = {}) {
         manifestFiles.push(entry);
         continue;
       }
-      if (!fs45.pathExistsSync(entry.destPath)) continue;
+      if (!fs46.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 fs45.remove(entry.destPath);
+        if (!dryRun) await fs46.remove(entry.destPath);
         emptiedDirs.add(path52.dirname(entry.destPath));
         result.deleted.push(entry.destPath);
       } else {
@@ -11857,7 +12002,7 @@ function isCatalogItemInstallable(item) {
 // src/install/scaffold.ts
 init_logger();
 import path56 from "node:path";
-import fs46 from "fs-extra";
+import fs47 from "fs-extra";
 async function scaffoldConfigItems(projectRoot, catalogRoot, items, opts = {}) {
   const scaffolded = [];
   const skipped = [];
@@ -11870,7 +12015,7 @@ async function scaffoldConfigItems(projectRoot, catalogRoot, items, opts = {}) {
     skipped.push(name);
     if (outcome === "skipped-exists") skippedExisting.push(name);
   };
-  const realRoot = await fs46.realpath(catalogRoot).catch(() => null);
+  const realRoot = await fs47.realpath(catalogRoot).catch(() => null);
   for (const item of items) {
     if (item.type !== "config") continue;
     const sourcePath = path56.resolve(catalogRoot, item.path);
@@ -11880,7 +12025,7 @@ async function scaffoldConfigItems(projectRoot, catalogRoot, items, opts = {}) {
       warn(`Skipping ${item.id}: path '${item.path}' escapes the catalog root`);
       continue;
     }
-    const realSource = await fs46.realpath(sourcePath).catch(() => null);
+    const realSource = await fs47.realpath(sourcePath).catch(() => null);
     if (!realRoot || !realSource) {
       warn(`Skipping ${item.id}: source not found at ${sourcePath}`);
       continue;
@@ -11890,7 +12035,7 @@ async function scaffoldConfigItems(projectRoot, catalogRoot, items, opts = {}) {
       warn(`Skipping ${item.id}: path '${item.path}' resolves outside the catalog root`);
       continue;
     }
-    const stat = await fs46.lstat(sourcePath).catch(() => null);
+    const stat = await fs47.lstat(sourcePath).catch(() => null);
     if (!stat) {
       warn(`Skipping ${item.id}: source not found at ${sourcePath}`);
       continue;
@@ -11904,7 +12049,7 @@ async function scaffoldConfigItems(projectRoot, catalogRoot, items, opts = {}) {
       const dest = path56.join(projectRoot, filename);
       record(filename, await scaffoldFile(sourcePath, dest, item.id, projectRoot, opts));
     } else if (stat.isDirectory()) {
-      const entries = await fs46.readdir(sourcePath);
+      const entries = await fs47.readdir(sourcePath);
       for (const entry of entries) {
         const src = path56.join(sourcePath, entry);
         const dest = path56.join(projectRoot, entry);
@@ -11916,7 +12061,7 @@ async function scaffoldConfigItems(projectRoot, catalogRoot, items, opts = {}) {
 }
 async function scaffoldFile(src, dest, itemId, projectRoot, opts) {
   const destDisplay = path56.relative(projectRoot, dest) || path56.basename(dest);
-  const srcStat = await fs46.lstat(src).catch(() => null);
+  const srcStat = await fs47.lstat(src).catch(() => null);
   if (!srcStat) {
     warn(`Skipping ${path56.basename(src)}: source not found`);
     return "skipped-refused";
@@ -11925,7 +12070,7 @@ async function scaffoldFile(src, dest, itemId, projectRoot, opts) {
     warn(`Skipping ${path56.basename(src)}: source is a symlink`);
     return "skipped-refused";
   }
-  const exists2 = await fs46.pathExists(dest);
+  const exists2 = await fs47.pathExists(dest);
   if (exists2 && !opts.force) {
     warn(`Skipping ${destDisplay}: already exists \u2014 re-run with --force to overwrite it`);
     return "skipped-exists";
@@ -11935,16 +12080,16 @@ async function scaffoldFile(src, dest, itemId, projectRoot, opts) {
     return "scaffolded";
   }
   if (exists2 && opts.force) {
-    await fs46.remove(dest);
+    await fs47.remove(dest);
   }
-  await fs46.ensureDir(path56.dirname(dest));
-  await fs46.copy(src, dest, {
+  await fs47.ensureDir(path56.dirname(dest));
+  await fs47.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 !fs46.lstatSync(s).isSymbolicLink();
+        return !fs47.lstatSync(s).isSymbolicLink();
       } catch {
         return false;
       }
@@ -12057,7 +12202,6 @@ async function resolveBaseRef(root) {
 }
 
 // src/commands/decisions-guard.ts
-init_exec();
 var PR_CREATE_PATTERN = /\bgh\s+pr\s+create\b/;
 function readPayload(options) {
   if (options.stdinPayload != null) {
@@ -12083,11 +12227,20 @@ async function runDecisionsGuard(options = {}) {
   const baseRef = await resolveBaseRef(root);
   if (!baseRef) return;
   const range = `${baseRef}...HEAD`;
-  const commitMessages = (await runGit(["log", "--format=%B", toAncestryLogRange(range)], { cwd: root })).stdout;
+  const commitMessages = await readCommitMessages(root, range);
   const result = await runDecisionsCheck(root, { range, commitMessages });
+  if (result.triggered && !result.satisfied && result.recordErrors.length > 0) {
+    const what = result.missingDecision ? "this change needs an ADR, and a decision record in it is misplaced or invalid" : "a decision record in this change is misplaced or invalid";
+    const why = result.missingDecision ? result.reasons.filter((r) => !r.startsWith("no new") && r !== result.recordWayOut) : result.recordErrors;
+    emitPreToolUseDeny(
+      `I didn't run that: ${what} (${why.join("; ")}). ${result.recordWayOut} Then retry.`
+    );
+    return;
+  }
   if (result.triggered && !result.satisfied) {
+    const rel = relativeDecisionPath(await resolveDecisionsDir(root), root);
     emitPreToolUseDeny(
-      `I didn't run that \u2014 this change needs an ADR before opening a PR (${result.reasons.join("; ")}). Run haus decisions suggest, add the decision under docs/decisions/, then retry \u2014 or use [adr-skip] for non-security changes.`
+      `I didn't run that \u2014 this change needs an ADR before opening a PR (${result.reasons.join("; ")}). Run haus decisions suggest, add the decision under ${rel}/, then retry, or put [adr-skip] on its own line in a commit body for non-security changes.`
     );
   }
 }
@@ -12104,6 +12257,14 @@ async function nextDecisionNumber(root) {
 }
 
 // src/decisions/suggest.ts
+function printRecordFailures(checks) {
+  const lines = /* @__PURE__ */ new Set([
+    ...checks.flatMap((check) => check.recordErrors),
+    ...checks.map((check) => check.recordWayOut).filter((wayOut) => wayOut.length > 0)
+  ]);
+  for (const line2 of lines) process.stdout.write(`${line2}
+`);
+}
 function draftTemplate(number, title) {
   const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   return `# ADR-${number}: ${title}
@@ -12136,11 +12297,18 @@ _(Why this over alternatives \u2014 the line agents read for "why".)_
 `;
 }
 async function runDecisionsSuggest(root, opts = {}) {
-  const stagedCheck = await runDecisionsCheck(root, { staged: true });
-  const unstagedCheck = await runDecisionsCheck(root, {});
-  const triggered = stagedCheck.triggered || unstagedCheck.triggered;
-  if (!triggered) return;
-  if (stagedCheck.triggered && stagedCheck.satisfied) return;
+  if (!opts.title) {
+    const stagedCheck = await runDecisionsCheck(root, { staged: true });
+    const unstagedCheck = await runDecisionsCheck(root, {});
+    const triggered = stagedCheck.triggered || unstagedCheck.triggered;
+    if (!triggered) return;
+    if (stagedCheck.triggered && stagedCheck.satisfied) return;
+    const wantsDraft = (check) => check.missingDecision && check.recordErrors.length === 0;
+    if (!wantsDraft(stagedCheck) && !wantsDraft(unstagedCheck)) {
+      if (!opts.fromHook) printRecordFailures([stagedCheck, unstagedCheck]);
+      return;
+    }
+  }
   const number = await nextDecisionNumber(root);
   const title = opts.title ?? "Decision from current changes";
   const draft = draftTemplate(number, title);
@@ -12168,9 +12336,7 @@ init_logger();
 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", toAncestryLogRange(options.range)], { cwd: root })
-    )).stdout : "";
+    const commitMessages = options.range != null ? await readCommitMessages(root, options.range) : [];
     const result = await runDecisionsCheck(root, {
       staged: options.staged,
       range: options.range,
@@ -12188,9 +12354,17 @@ async function runDecisions(sub, arg, options = {}) {
       log(`decisions gate: satisfied (${result.reasons.join("; ")})`);
       return;
     }
-    for (const reason of result.reasons) warn(reason);
+    for (const reason of result.reasons) if (reason !== result.recordWayOut) warn(reason);
+    if (result.recordErrors.length > 0) {
+      const what = result.missingDecision ? "this change needs an ADR, and a decision record in it is misplaced or invalid" : "a decision record in this change is misplaced or invalid";
+      const why = result.missingDecision ? result.reasons.filter((r) => !r.startsWith("no new") && r !== result.recordWayOut) : result.recordErrors;
+      error(`decisions gate: ${what}. Why: ${why.join("; ")}. ${result.recordWayOut}`);
+      process.exitCode = 1;
+      return;
+    }
+    const rel = relativeDecisionPath(await resolveDecisionsDir(root), root);
     error(
-      `decisions gate: decision-worthy change without a valid ADR under docs/decisions/. Why: ${result.reasons.filter((r) => !r.startsWith("no new")).join("; ") || "see above"}. Run \`haus decisions suggest\`, add docs/decisions/NNNN-*.md + README row, or use [adr-skip] with justification (ignored for security paths).`
+      `decisions gate: decision-worthy change without a valid ADR under ${rel}/. Why: ${result.reasons.filter((r) => !r.startsWith("no new")).join("; ") || "see above"}. Run \`haus decisions suggest\`, add ${rel}/NNNN-*.md + README row, or put [adr-skip] on its own line with a justification in the PR body or a commit body (ignored for security paths).`
     );
     process.exitCode = 1;
     return;
@@ -12720,7 +12894,7 @@ function matchDangerousCommandShape(command) {
 }
 
 // src/security/guard-file-access.ts
-import fs47 from "node:fs";
+import fs48 from "node:fs";
 import path58 from "node:path";
 function matchesDenyTier(candidate) {
   const normalized = normalizePathForMatch(candidate);
@@ -12728,11 +12902,11 @@ function matchesDenyTier(candidate) {
 }
 function resolveOnDisk(candidate) {
   try {
-    const resolved = fs47.realpathSync(candidate);
+    const resolved = fs48.realpathSync(candidate);
     return resolved === path58.resolve(candidate) ? {} : { resolved };
   } catch {
     try {
-      if (fs47.lstatSync(candidate).isSymbolicLink()) return { unverifiable: true };
+      if (fs48.lstatSync(candidate).isSymbolicLink()) return { unverifiable: true };
     } catch {
     }
     const parent = path58.dirname(candidate);
@@ -14861,7 +15035,7 @@ import path63 from "node:path";
 
 // src/new-project/create-project.ts
 import path62 from "node:path";
-import fs48 from "fs-extra";
+import fs49 from "fs-extra";
 init_exec();
 init_logger();
 
@@ -15049,7 +15223,7 @@ async function recordPackageManager(projectPath, pm, deps) {
   const pkgPath = path62.join(projectPath, "package.json");
   let pkg;
   try {
-    pkg = await fs48.readJson(pkgPath);
+    pkg = await fs49.readJson(pkgPath);
   } catch {
     return {};
   }
@@ -15064,7 +15238,7 @@ async function recordPackageManager(projectPath, pm, deps) {
       note: `installed ${pm} is ${version}, which haus does not support \u2014 the package manager was not recorded, so the scanner will report it as unknown until you upgrade`
     };
   }
-  await fs48.writeJson(pkgPath, { ...pkg, packageManager: field }, { spaces: 2 });
+  await fs49.writeJson(pkgPath, { ...pkg, packageManager: field }, { spaces: 2 });
   return {};
 }
 var CONFIG_TOOLING = {
@@ -15082,7 +15256,7 @@ async function ensureConfigTooling(projectPath, scaffolded) {
   const pkgPath = path62.join(projectPath, "package.json");
   let pkg;
   try {
-    pkg = await fs48.readJson(pkgPath);
+    pkg = await fs49.readJson(pkgPath);
   } catch {
     return [];
   }
@@ -15106,7 +15280,7 @@ async function ensureConfigTooling(projectPath, scaffolded) {
     }
   }
   if (!changed) return [];
-  await fs48.writeJson(pkgPath, { ...pkg, devDependencies, scripts }, { spaces: 2 });
+  await fs49.writeJson(pkgPath, { ...pkg, devDependencies, scripts }, { spaces: 2 });
   return added;
 }
 async function createProject(opts, deps = defaultDeps) {
@@ -15119,7 +15293,7 @@ async function createProject(opts, deps = defaultDeps) {
   };
   const stack = getStack(opts.stackId);
   if (!stack) return fail("preflight", `Unknown stack "${opts.stackId}". Run \`haus new --list\`.`);
-  const parentStat = await fs48.stat(path62.dirname(projectPath)).catch(() => null);
+  const parentStat = await fs49.stat(path62.dirname(projectPath)).catch(() => null);
   if (!parentStat?.isDirectory()) {
     return fail(
       "preflight",
@@ -15132,7 +15306,7 @@ async function createProject(opts, deps = defaultDeps) {
       `Invalid project name "${opts.name}" (lowercase letters, digits, . _ - only).`
     );
   }
-  if (await fs48.pathExists(projectPath)) {
+  if (await fs49.pathExists(projectPath)) {
     return fail("preflight", `Target ${projectPath} already exists \u2014 refusing to write into it.`);
   }
   const scaffoldArgs = stack.scaffold.args.map(
@@ -15208,13 +15382,13 @@ async function createProject(opts, deps = defaultDeps) {
     });
     if (scaffold.exitCode !== 0) {
       const why = scaffold.killed ? `${pinned} did not complete: ${scaffold.stderr.trim() || `timed out after ${SCAFFOLD_TIMEOUT_MS}ms`}. Scaffolders that stall this way are usually waiting on a prompt despite --yes \u2014 run it yourself to see: npx ${npxArgs.join(" ")}` : `${pinned} exited ${scaffold.exitCode}.`;
-      const leftBehind = await fs48.pathExists(projectPath) ? ` The directory was left for inspection \u2014 review it and remove it manually if unwanted (haus never auto-deletes).` : "";
+      const leftBehind = await fs49.pathExists(projectPath) ? ` The directory was left for inspection \u2014 review it and remove it manually if unwanted (haus never auto-deletes).` : "";
       return fail("scaffold", `${why}${leftBehind}`);
     }
     steps.push({ step: "scaffold", status: "done" });
     phase = "git";
     if (!opts.json) log("\u25B6 git: init/branch/commit");
-    if (!await fs48.pathExists(path62.join(projectPath, ".git"))) {
+    if (!await fs49.pathExists(path62.join(projectPath, ".git"))) {
       const init = await deps.git(["init"], { cwd: projectPath });
       if (init.exitCode !== 0) return fail("git", `git init failed: ${init.stderr}`);
     }
@@ -15525,7 +15699,9 @@ async function runRecommend(options) {
   const root = process.cwd();
   const context = await readContextOrScan(root);
   const include = parseIdList(options.include);
+  const declaredRoles = parseIdList(options.declareRole);
   if (include.length > 0) await addProjectIncludedIds(root, include);
+  if (declaredRoles.length > 0) await addProjectDeclaredRoles(root, declaredRoles);
   const activePluginIds = pluginIdsForInstall(await activeGlobalPluginIds(root));
   let result;
   try {
@@ -15546,7 +15722,7 @@ async function runRecommend(options) {
   log(`Skipped: ${result.skipped.length}`);
   if (result.optInEligible && result.optInEligible.length > 0) {
     log(
-      `Opt-in available: ${result.optInEligible.length} (add with \`haus recommend --include <id>\`)`
+      `Opt-in available: ${result.optInEligible.length} (add with \`haus recommend --include <id>\`, or with \`haus recommend --declare-role <role>\` for role-gated items)`
     );
   }
   for (const w of result.warnings) log(`- WARN: ${w}`);
@@ -15760,7 +15936,7 @@ async function runScan(options) {
 
 // src/commands/undo.ts
 import path65 from "node:path";
-import fs49 from "fs-extra";
+import fs50 from "fs-extra";
 
 // src/claude/managed-paths.ts
 init_paths();
@@ -15779,7 +15955,7 @@ init_paths();
 async function collectCoreManagedPaths(root) {
   const existing = [];
   for (const abs of coreManagedAbsolutePaths(root)) {
-    if (await fs49.pathExists(abs)) existing.push(abs);
+    if (await fs50.pathExists(abs)) existing.push(abs);
   }
   return existing;
 }
@@ -15809,19 +15985,19 @@ async function collectLockTrackedPaths(root) {
 }
 async function settingsHasHausContent(root) {
   const settingsPath = claudePath(root, "settings.json");
-  if (!await fs49.pathExists(settingsPath)) return false;
+  if (!await fs50.pathExists(settingsPath)) return false;
   const settings = await readProjectSettings(root);
   return settings._haus != null;
 }
 async function claudeMdHasHausBlock(root) {
   const filePath = path65.join(root, "CLAUDE.md");
-  if (!await fs49.pathExists(filePath)) return false;
-  const text = await fs49.readFile(filePath, "utf8");
+  if (!await fs50.pathExists(filePath)) return false;
+  const text = await fs50.readFile(filePath, "utf8");
   return text.includes(BLOCK_BEGIN);
 }
 async function stripProjectSettings(root) {
   const settingsPath = claudePath(root, "settings.json");
-  if (!await fs49.pathExists(settingsPath)) return false;
+  if (!await fs50.pathExists(settingsPath)) return false;
   let settings = await readProjectSettings(root);
   settings = stripHausHooks(
     stripHausAsk(stripHausAllow(stripHausDeny(stripHausEnabledPlugins(settings))))
@@ -15832,30 +16008,30 @@ async function stripProjectSettings(root) {
     log(`Stripped haus rules from ${path65.relative(root, settingsPath)} (user settings preserved).`);
     return true;
   }
-  await fs49.remove(settingsPath);
+  await fs50.remove(settingsPath);
   log(`Removed ${path65.relative(root, settingsPath)} (no user-owned settings remained).`);
   return true;
 }
 async function stripRootClaudeMd(root) {
   const filePath = path65.join(root, "CLAUDE.md");
-  if (!await fs49.pathExists(filePath)) return false;
-  const prev = await fs49.readFile(filePath, "utf8");
+  if (!await fs50.pathExists(filePath)) return false;
+  const prev = await fs50.readFile(filePath, "utf8");
   if (!prev.includes(BLOCK_BEGIN)) return false;
   const next = stripHausBlock(prev);
   if (next.length === 0) {
-    await fs49.remove(filePath);
+    await fs50.remove(filePath);
     log("Removed CLAUDE.md (only contained haus import block).");
   } else {
-    await fs49.writeFile(filePath, next, "utf8");
+    await fs50.writeFile(filePath, next, "utf8");
     log("Removed haus import block from CLAUDE.md (user content preserved).");
   }
   return true;
 }
 async function pruneDirIfEmpty(dir) {
-  if (!await fs49.pathExists(dir)) return;
+  if (!await fs50.pathExists(dir)) return;
   try {
-    const entries = await fs49.readdir(dir);
-    if (entries.length === 0) await fs49.remove(dir);
+    const entries = await fs50.readdir(dir);
+    if (entries.length === 0) await fs50.remove(dir);
   } catch {
   }
 }
@@ -15864,11 +16040,11 @@ async function backupManagedFilesBeforeUndo(root, managedAbsPaths) {
   const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
   const backupRoot = hausPath(root, "backups", dirBackupDirName("undo", stamp));
   for (const abs of managedAbsPaths) {
-    if (!await fs49.pathExists(abs)) continue;
+    if (!await fs50.pathExists(abs)) continue;
     const rel = path65.relative(root, abs);
     const backupPath = path65.join(backupRoot, rel);
-    await fs49.ensureDir(path65.dirname(backupPath));
-    await fs49.copy(abs, backupPath);
+    await fs50.ensureDir(path65.dirname(backupPath));
+    await fs50.copy(abs, backupPath);
   }
   log(`Backed up ${managedAbsPaths.length} managed file(s) to ${path65.relative(root, backupRoot)}.`);
 }
@@ -15910,8 +16086,8 @@ User-owned .claude/ files will be preserved.`
   }
   await backupManagedFilesBeforeUndo(root, managed);
   for (const abs of coreManaged) {
-    if (!await fs49.pathExists(abs)) continue;
-    await fs49.remove(abs);
+    if (!await fs50.pathExists(abs)) continue;
+    await fs50.remove(abs);
     log(`Removed ${path65.relative(root, abs)}`);
   }
   for (const { id, existing } of lockRemovable) {
@@ -15926,7 +16102,7 @@ User-owned .claude/ files will be preserved.`
 
 // src/install/uninstall.ts
 import path66 from "node:path";
-import fs50 from "fs-extra";
+import fs51 from "fs-extra";
 init_fs();
 init_logger();
 init_paths();
@@ -15960,7 +16136,7 @@ async function runUninstall(options = {}) {
     );
   }
   for (const entry of manifest.files) {
-    const exists2 = fs50.pathExistsSync(entry.destPath);
+    const exists2 = fs51.pathExistsSync(entry.destPath);
     if (!exists2) continue;
     const content2 = await readText(entry.destPath);
     if (content2 === void 0) continue;
@@ -15978,7 +16154,7 @@ async function runUninstall(options = {}) {
       result.skipped.push(entry.destPath);
       continue;
     }
-    await fs50.remove(entry.destPath);
+    await fs51.remove(entry.destPath);
     await pruneEmptyDir(path66.dirname(entry.destPath));
     result.deleted.push(entry.destPath);
   }
@@ -15990,14 +16166,14 @@ async function runUninstall(options = {}) {
   result.hooksStripped = true;
   const hausDir = path66.join(globalClaudeDir(), "haus");
   const manifestPath2 = hausManifestPath();
-  if (fs50.pathExistsSync(manifestPath2)) {
-    await fs50.remove(manifestPath2);
+  if (fs51.pathExistsSync(manifestPath2)) {
+    await fs51.remove(manifestPath2);
   }
   await removeInstallConfig();
-  if (fs50.pathExistsSync(hausDir)) {
+  if (fs51.pathExistsSync(hausDir)) {
     try {
-      const remaining = await fs50.readdir(hausDir);
-      if (remaining.length === 0) await fs50.remove(hausDir);
+      const remaining = await fs51.readdir(hausDir);
+      if (remaining.length === 0) await fs51.remove(hausDir);
     } catch {
     }
   }
@@ -16073,7 +16249,7 @@ init_forbidden_content();
 init_manifest_item_fields();
 init_path_safety();
 init_validation_rules2();
-import fs51 from "node:fs";
+import fs52 from "node:fs";
 import path67 from "node:path";
 var ITEM_SEMVER_RE = /^\d+\.\d+\.\d+$/;
 var ITEM_ID_PATTERN = /^haus\./;
@@ -16234,7 +16410,7 @@ function checkRequiredFrontmatter(text, label) {
 }
 function readForAudit(absPath, label, failures) {
   try {
-    return fs51.readFileSync(absPath, "utf8");
+    return fs52.readFileSync(absPath, "utf8");
   } catch (err) {
     failures.push(`${label}: unreadable (${err instanceof Error ? err.message : String(err)})`);
     return null;
@@ -16266,7 +16442,7 @@ function auditShippedFiles(manifestDir, items) {
     const absPath = path67.join(manifestDir, item.path);
     if (item.type === "skill") {
       const skillMd = path67.join(absPath, "SKILL.md");
-      if (!fs51.existsSync(skillMd)) {
+      if (!fs52.existsSync(skillMd)) {
         failures.push(`${item.id}: missing ${path67.relative(manifestDir, skillMd)}`);
         continue;
       }
@@ -16277,7 +16453,7 @@ function auditShippedFiles(manifestDir, items) {
         ...auditForbiddenTagsInText(text, `${item.id}: ${path67.relative(manifestDir, skillMd)}`)
       );
     } else if (item.type === "agent") {
-      if (!fs51.existsSync(absPath)) {
+      if (!fs52.existsSync(absPath)) {
         failures.push(`${item.id}: missing agent file ${item.path}`);
         continue;
       }
@@ -16287,13 +16463,13 @@ function auditShippedFiles(manifestDir, items) {
       failures.push(...checkRequiredFrontmatter(text, `${item.id}: ${rel}`));
       failures.push(...auditForbiddenTagsInText(text, `${item.id}: ${rel}`));
     } else if (item.type === "template") {
-      if (!fs51.existsSync(absPath)) {
+      if (!fs52.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 (!fs51.existsSync(absPath)) {
+      if (!fs52.existsSync(absPath)) {
         failures.push(`${item.id}: missing command file ${item.path}`);
         continue;
       }
@@ -16303,15 +16479,15 @@ function auditShippedFiles(manifestDir, items) {
       failures.push(...checkRequiredFrontmatter(text, `${item.id}: ${rel}`));
       failures.push(...auditTemplateContent(manifestDir, absPath, item.id));
     } else if (item.type === "config") {
-      if (!fs51.existsSync(absPath)) {
+      if (!fs52.existsSync(absPath)) {
         failures.push(`${item.id}: missing config path ${item.path}`);
       }
     } else if (item.type === "rule") {
-      if (!fs51.existsSync(absPath)) {
+      if (!fs52.existsSync(absPath)) {
         failures.push(`${item.id}: missing rule file ${item.path}`);
       }
     } else if (item.type === "asset") {
-      if (!fs51.existsSync(absPath)) {
+      if (!fs52.existsSync(absPath)) {
         failures.push(`${item.id}: missing asset file ${item.path}`);
       }
     }
@@ -16346,7 +16522,7 @@ function resolveItemType(relPath, pathTypeMap) {
 function walkAllFiles(dir, fn, failures) {
   let entries;
   try {
-    entries = fs51.readdirSync(dir, { withFileTypes: true });
+    entries = fs52.readdirSync(dir, { withFileTypes: true });
   } catch (err) {
     failures.push(
       `${dir}: unreadable subtree (${err instanceof Error ? err.message : String(err)})`
@@ -16380,7 +16556,7 @@ function auditDiskOrphans(manifestDir, items) {
   const claimedPaths = items.filter((item) => item.path && isSafeCatalogPath(item.path)).map((item) => item.path.replace(/\\/g, "/"));
   for (const dir of CONTENT_ROOTS) {
     const abs = path67.join(manifestDir, dir);
-    if (!fs51.existsSync(abs)) continue;
+    if (!fs52.existsSync(abs)) continue;
     walkAllFiles(
       abs,
       (file) => {
@@ -16397,7 +16573,7 @@ function auditDiskOrphans(manifestDir, items) {
 function walkMd(dir, fn, failures) {
   let entries;
   try {
-    entries = fs51.readdirSync(dir, { withFileTypes: true });
+    entries = fs52.readdirSync(dir, { withFileTypes: true });
   } catch (err) {
     failures.push(
       `${dir}: unreadable subtree (${err instanceof Error ? err.message : String(err)})`
@@ -16416,7 +16592,7 @@ function auditMarkdownContent(manifestDir, items) {
   const pathTypeMap = buildItemPathTypeMap(items);
   for (const dir of ["skills", "agents", "templates", "commands", "sources"]) {
     const abs = path67.join(manifestDir, dir);
-    if (!fs51.existsSync(abs)) continue;
+    if (!fs52.existsSync(abs)) continue;
     const dirType = DIR_ITEM_TYPE[dir] ?? "";
     walkMd(
       abs,
@@ -16492,7 +16668,7 @@ init_logger();
 // src/workspace/worktree/add.ts
 init_fs();
 import path75 from "node:path";
-import fs55 from "fs-extra";
+import fs56 from "fs-extra";
 
 // src/workspace/worktree/git-worktree.ts
 init_exec();
@@ -16613,12 +16789,12 @@ async function hasUnpushedWork(cwd) {
 
 // src/workspace/worktree/hydrate.ts
 import path71 from "node:path";
-import fs53 from "fs-extra";
+import fs54 from "fs-extra";
 
 // src/workspace/worktree/cow-copy.ts
 init_exec();
 import path69 from "node:path";
-import fs52 from "fs-extra";
+import fs53 from "fs-extra";
 async function getMacFilesystemType(dir) {
   const df = await runCommand("df", ["-P", dir]);
   if (df.exitCode !== 0) return void 0;
@@ -16649,14 +16825,14 @@ async function detectCowStrategy(dir) {
   return "unknown-platform";
 }
 async function cowCopyDir(src, dest) {
-  const srcExists = await fs52.pathExists(src);
+  const srcExists = await fs53.pathExists(src);
   if (!srcExists)
     return { strategy: "unsupported", attempted: false, ok: false, error: "source missing" };
   const strategy = await detectCowStrategy(path69.dirname(dest));
   if (strategy === "unsupported" || strategy === "unknown-platform") {
     return { strategy, attempted: false, ok: false };
   }
-  await fs52.ensureDir(path69.dirname(dest));
+  await fs53.ensureDir(path69.dirname(dest));
   const args = strategy === "darwin-clonefile" ? ["-c", "-R", src, dest] : ["-a", "--reflink=always", src, dest];
   const result = await runCommand("cp", args);
   return {
@@ -16849,11 +17025,11 @@ async function hydrateMember(mainMemberPath, worktreeMemberPath, opts = {}) {
   for (const target of HYDRATION_TARGETS) {
     const src = path71.join(mainMemberPath, target);
     const dest = path71.join(worktreeMemberPath, target);
-    if (!await fs53.pathExists(src)) continue;
-    const destExists = await fs53.pathExists(dest);
+    if (!await fs54.pathExists(src)) continue;
+    const destExists = await fs54.pathExists(dest);
     if (!opts.force && destExists) continue;
     if (opts.force && destExists) {
-      await fs53.remove(dest);
+      await fs54.remove(dest);
     }
     const copy = await cowCopyDir(src, dest);
     targets.push({ target, copy });
@@ -16867,7 +17043,7 @@ async function hydrateMember(mainMemberPath, worktreeMemberPath, opts = {}) {
 // src/workspace/worktree/local-files.ts
 init_exec();
 import path72 from "node:path";
-import fs54 from "fs-extra";
+import fs55 from "fs-extra";
 var MACHINE_LOCAL_FILES = [
   "docker-compose.local.yml",
   path72.join(".claude", "settings.local.json")
@@ -16881,11 +17057,11 @@ async function copyMachineLocalFiles(mainMemberPath, worktreeMemberPath) {
   const copied = [];
   for (const rel of MACHINE_LOCAL_FILES) {
     const src = path72.join(mainMemberPath, rel);
-    if (!await fs54.pathExists(src)) continue;
+    if (!await fs55.pathExists(src)) continue;
     if (await isTracked(mainMemberPath, rel)) continue;
     const dest = path72.join(worktreeMemberPath, rel);
-    await fs54.ensureDir(path72.dirname(dest));
-    await fs54.copy(src, dest, { overwrite: true });
+    await fs55.ensureDir(path72.dirname(dest));
+    await fs55.copy(src, dest, { overwrite: true });
     copied.push(rel);
   }
   return copied;
@@ -16973,7 +17149,7 @@ async function runAdd(opts) {
   }
   const branch = opts.branch ?? opts.slug;
   const wsWorktreePath = worktreePath(workspaceRoot, opts.slug);
-  if (await fs55.pathExists(wsWorktreePath)) {
+  if (await fs56.pathExists(wsWorktreePath)) {
     return {
       ok: false,
       error: `Workspace worktree already exists at ${wsWorktreePath} \u2014 run \`haus workspace worktree hydrate --materialize\` from inside it to check out any missing members (e.g. a worktree created by plain \`git worktree add\`), or \`remove\` first to start over.`
@@ -17091,7 +17267,7 @@ async function runDryRun(args) {
 import { spawn } from "node:child_process";
 import fsSync from "node:fs";
 import path81 from "node:path";
-import fs57 from "fs-extra";
+import fs58 from "fs-extra";
 
 // src/workspace/worktree/doctor.ts
 import { existsSync as existsSync7 } from "node:fs";
@@ -17100,7 +17276,7 @@ import path78 from "node:path";
 // src/workspace/worktree/hydrate-lock.ts
 init_paths();
 import path76 from "node:path";
-import fs56 from "fs-extra";
+import fs57 from "fs-extra";
 var STALE_LOCK_MS = 30 * 60 * 1e3;
 function locksDir(mainRoot) {
   return hausPath(mainRoot, "locks");
@@ -17135,7 +17311,7 @@ function defaultIsAlive(pid) {
 }
 async function readOwnerPid(lockPath) {
   try {
-    const raw = (await fs56.readFile(path76.join(lockPath, "pid"), "utf8")).trim();
+    const raw = (await fs57.readFile(path76.join(lockPath, "pid"), "utf8")).trim();
     if (raw === "") return void 0;
     const pid = Number.parseInt(raw, 10);
     return Number.isInteger(pid) && pid > 0 ? pid : void 0;
@@ -17144,13 +17320,13 @@ async function readOwnerPid(lockPath) {
   }
 }
 async function claim(lockPath, pid) {
-  await fs56.ensureDir(path76.dirname(lockPath));
+  await fs57.ensureDir(path76.dirname(lockPath));
   try {
-    await fs56.mkdir(lockPath);
+    await fs57.mkdir(lockPath);
   } catch {
     return false;
   }
-  await fs56.writeFile(path76.join(lockPath, "pid"), String(pid), "utf8");
+  await fs57.writeFile(path76.join(lockPath, "pid"), String(pid), "utf8");
   return true;
 }
 async function acquireHydrateLock(mainRoot, slug, deps = {}) {
@@ -17169,7 +17345,7 @@ async function acquireHydrateLock(mainRoot, slug, deps = {}) {
     }
     if (alive) return { acquired: false, reason: "live", ownerPid, lockPath };
   } else {
-    const stat = await fs56.stat(lockPath).catch(() => void 0);
+    const stat = await fs57.stat(lockPath).catch(() => void 0);
     if (stat === void 0) {
       return await claim(lockPath, pid) ? { acquired: true, lockPath } : { acquired: false, reason: "live", lockPath };
     }
@@ -17177,18 +17353,18 @@ async function acquireHydrateLock(mainRoot, slug, deps = {}) {
       return { acquired: false, reason: "starting", lockPath };
     }
   }
-  await fs56.remove(lockPath);
+  await fs57.remove(lockPath);
   return await claim(lockPath, pid) ? { acquired: true, lockPath } : { acquired: false, reason: "live", ownerPid, lockPath };
 }
 async function recordHydrateLockOwner(mainRoot, slug, pid) {
-  await fs56.writeFile(path76.join(hydrateLockPath(mainRoot, slug), "pid"), String(pid), "utf8");
+  await fs57.writeFile(path76.join(hydrateLockPath(mainRoot, slug), "pid"), String(pid), "utf8");
 }
 async function releaseHydrateLock(mainRoot, slug) {
-  await fs56.remove(hydrateLockPath(mainRoot, slug));
+  await fs57.remove(hydrateLockPath(mainRoot, slug));
 }
 async function readHydrateLock(mainRoot, slug) {
   const lockPath = hydrateLockPath(mainRoot, slug);
-  const stat = await fs56.stat(lockPath).catch(() => void 0);
+  const stat = await fs57.stat(lockPath).catch(() => void 0);
   if (stat === void 0) return { held: false };
   const ownerPid = await readOwnerPid(lockPath);
   return {
@@ -17568,11 +17744,11 @@ async function consumeLastRunFailure(mainRoot, slug) {
   const file = hydrateLastRunPath(mainRoot, slug);
   let parsed;
   try {
-    parsed = JSON.parse(await fs57.readFile(file, "utf8"));
+    parsed = JSON.parse(await fs58.readFile(file, "utf8"));
   } catch {
     return void 0;
   }
-  await fs57.remove(file).catch(() => void 0);
+  await fs58.remove(file).catch(() => void 0);
   if (parsed && parsed.ok === false) return parsed;
   return void 0;
 }
@@ -17644,7 +17820,7 @@ async function runAutoHydrate(opts = {}, deps = {}) {
       reason: "could not determine the haus CLI entry point to re-invoke"
     };
   }
-  await fs57.ensureDir(logsDir(mainRoot));
+  await fs58.ensureDir(logsDir(mainRoot));
   appendLog(
     logPath,
     `autohydrate: forking hydrate --materialize for "${slug}" (${missingMembers.join(", ")})`
@@ -17713,21 +17889,21 @@ async function runDetachedHydration() {
 async function writeLastRun(mainRoot, slug, ok, failures) {
   const file = hydrateLastRunPath(mainRoot, slug);
   if (ok) {
-    await fs57.remove(file).catch(() => void 0);
+    await fs58.remove(file).catch(() => void 0);
     return;
   }
   const record = { slug, finishedAt: (/* @__PURE__ */ new Date()).toISOString(), ok, failures };
-  await fs57.ensureDir(path81.dirname(file));
-  await fs57.writeJson(file, record, { spaces: 2 }).catch(() => void 0);
+  await fs58.ensureDir(path81.dirname(file));
+  await fs58.writeJson(file, record, { spaces: 2 }).catch(() => void 0);
 }
 
 // src/workspace/worktree/dematerialize.ts
 import path83 from "node:path";
-import fs59 from "fs-extra";
+import fs60 from "fs-extra";
 
 // src/workspace/worktree/member-targets.ts
 import path82 from "node:path";
-import fs58 from "fs-extra";
+import fs59 from "fs-extra";
 function normalizeStateMembers(state, allMembers) {
   return state?.members.map((m) => ({ id: m.id, folder: m.folder, absPath: m.absPath })) ?? allMembers.map((m) => ({ id: m.id, folder: m.folder, absPath: m.absPath }));
 }
@@ -17752,7 +17928,7 @@ function resolveMemberTargets(wsWorktreePath, stateMembers, allMembers) {
 async function filterExistingTargets(targets) {
   const existing = [];
   for (const target of targets) {
-    if (await fs58.pathExists(target.path)) existing.push(target);
+    if (await fs59.pathExists(target.path)) existing.push(target);
   }
   return existing;
 }
@@ -17797,7 +17973,7 @@ async function runDematerialize(opts) {
   } catch (err) {
     return { ok: false, error: err instanceof Error ? err.message : String(err) };
   }
-  if (!await fs59.pathExists(wsWorktreePath)) {
+  if (!await fs60.pathExists(wsWorktreePath)) {
     return { ok: false, error: `No workspace worktree found at ${wsWorktreePath}.` };
   }
   const lock = await readHydrateLock(workspaceRoot, slug);
@@ -17831,8 +18007,8 @@ async function runDematerialize(opts) {
   const failed = [];
   for (const folder of unresolvedDroppedMembers) {
     const droppedPath = path83.join(wsWorktreePath, folder);
-    if (await fs59.pathExists(droppedPath)) {
-      await fs59.remove(droppedPath);
+    if (await fs60.pathExists(droppedPath)) {
+      await fs60.remove(droppedPath);
       failed.push({ repo: folder, error: unresolvedDroppedFailureReason() });
     }
   }
@@ -17847,14 +18023,14 @@ async function runDematerialize(opts) {
 
 // src/workspace/worktree/list.ts
 import path84 from "node:path";
-import fs60 from "fs-extra";
+import fs61 from "fs-extra";
 async function runList2() {
   const resolved = await resolveWorkspaceForWorktree();
   if (!resolved.ok) return { ok: false, error: resolved.reason };
   const { rootInfo, workspaceRoot } = resolved;
   const dir = worktreesDir(workspaceRoot);
-  if (!await fs60.pathExists(dir)) return { ok: true, workspaceRoot, worktrees: [] };
-  const entries = await fs60.readdir(dir, { withFileTypes: true });
+  if (!await fs61.pathExists(dir)) return { ok: true, workspaceRoot, worktrees: [] };
+  const entries = await fs61.readdir(dir, { withFileTypes: true });
   const slugs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
   const configuredMembers = await readMembers(rootInfo);
   const worktrees = [];
@@ -17865,7 +18041,7 @@ async function runList2() {
     const source = state?.members ?? configuredMembers.map((m) => ({ id: m.id, folder: m.folder }));
     for (const m of source) {
       const memberPath = path84.join(wtPath, m.folder);
-      const materialized = await fs60.pathExists(memberPath);
+      const materialized = await fs61.pathExists(memberPath);
       const actualBranch = materialized ? await currentBranch(memberPath) : void 0;
       members.push({
         id: m.id,
@@ -17888,12 +18064,12 @@ async function runList2() {
 // src/workspace/worktree/reclaim.ts
 import { existsSync as existsSync9 } from "node:fs";
 import path85 from "node:path";
-import fs61 from "fs-extra";
+import fs62 from "fs-extra";
 var MS_PER_DAY = 24 * 60 * 60 * 1e3;
 async function lastTouchedMs(worktreeRoot) {
   const candidates = [worktreeRoot, path85.join(worktreeRoot, ".haus-worktree.json")];
   try {
-    const dotGit = await fs61.readFile(path85.join(worktreeRoot, ".git"), "utf8");
+    const dotGit = await fs62.readFile(path85.join(worktreeRoot, ".git"), "utf8");
     const match = /^gitdir:\s*(.+)$/m.exec(dotGit);
     if (match?.[1]) {
       const gitdir = match[1].trim();
@@ -17903,7 +18079,7 @@ async function lastTouchedMs(worktreeRoot) {
   }
   let newest = 0;
   for (const candidate of candidates) {
-    const stat = await fs61.stat(candidate).catch(() => void 0);
+    const stat = await fs62.stat(candidate).catch(() => void 0);
     if (stat && stat.mtimeMs > newest) newest = stat.mtimeMs;
   }
   return newest;
@@ -17930,7 +18106,7 @@ async function runReclaim(opts = {}) {
   if (!existsSync9(dir)) {
     return { ok: true, dryRun: !opts.write, olderThanDays, candidates: [], reclaimed: 0 };
   }
-  const allEntries = (await fs61.readdir(dir, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name).sort();
+  const allEntries = (await fs62.readdir(dir, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name).sort();
   const entries = allEntries.filter((name) => isValidWorktreeSlug(name));
   const unaddressable = allEntries.filter((name) => !isValidWorktreeSlug(name));
   const members = await readMembers(rootInfo);
@@ -18011,13 +18187,13 @@ async function runReclaim(opts = {}) {
 }
 
 // src/workspace/worktree/remove.ts
-import fs62 from "fs-extra";
+import fs63 from "fs-extra";
 async function runRemove2(opts) {
   const resolved = await resolveWorkspaceForWorktree();
   if (!resolved.ok) return { ok: false, error: resolved.reason };
   const { rootInfo, workspaceRoot } = resolved;
   const wsWorktreePath = worktreePath(workspaceRoot, opts.slug);
-  if (!await fs62.pathExists(wsWorktreePath)) {
+  if (!await fs63.pathExists(wsWorktreePath)) {
     return { ok: false, error: `No workspace worktree found at ${wsWorktreePath}.` };
   }
   const state = await readWorktreeState(wsWorktreePath);
@@ -18085,8 +18261,8 @@ async function runRemove2(opts) {
     }
     await pruneWorktrees(workspaceRoot);
   }
-  if (wsRemoveOk && await fs62.pathExists(wsWorktreePath)) {
-    await fs62.remove(wsWorktreePath);
+  if (wsRemoveOk && await fs63.pathExists(wsWorktreePath)) {
+    await fs63.remove(wsWorktreePath);
   }
   return { ok: failed.length === 0, dryRun: false, slug: opts.slug, removed, failed };
 }
@@ -18859,17 +19035,17 @@ init_logger();
 
 // src/workspace/link-context/link.ts
 import path90 from "node:path";
-import fs65 from "fs-extra";
+import fs66 from "fs-extra";
 init_fs();
 init_logger();
 
 // src/workspace/link-context/plan.ts
 import path89 from "node:path";
-import fs64 from "fs-extra";
+import fs65 from "fs-extra";
 
 // src/workspace/link-context/scan-source.ts
 import path88 from "node:path";
-import fs63 from "fs-extra";
+import fs64 from "fs-extra";
 var ASSET_SUBDIR = {
   skill: "skills",
   agent: "agents",
@@ -18877,20 +19053,20 @@ var ASSET_SUBDIR = {
 };
 async function hasLinkableContext(member) {
   for (const subdir of Object.values(ASSET_SUBDIR)) {
-    if (await fs63.pathExists(path88.join(member.absPath, ".claude", subdir))) return true;
+    if (await fs64.pathExists(path88.join(member.absPath, ".claude", subdir))) return true;
   }
   return false;
 }
 async function collectSkills(member) {
   const dir = path88.join(member.absPath, ".claude", "skills");
-  if (!await fs63.pathExists(dir)) return [];
-  const names = await fs63.readdir(dir);
+  if (!await fs64.pathExists(dir)) return [];
+  const names = await fs64.readdir(dir);
   const out = [];
   for (const name of [...names].sort()) {
     const abs = path88.join(dir, name);
-    const stat = await fs63.lstat(abs);
+    const stat = await fs64.lstat(abs);
     if (!stat.isDirectory()) continue;
-    if (!await fs63.pathExists(path88.join(abs, "SKILL.md"))) continue;
+    if (!await fs64.pathExists(path88.join(abs, "SKILL.md"))) continue;
     out.push({ type: "skill", name, sourceRelPath: path88.posix.join(".claude", "skills", name) });
   }
   return out;
@@ -18898,13 +19074,13 @@ async function collectSkills(member) {
 async function collectFlatMarkdown(member, type) {
   const subdir = ASSET_SUBDIR[type];
   const dir = path88.join(member.absPath, ".claude", subdir);
-  if (!await fs63.pathExists(dir)) return [];
-  const names = await fs63.readdir(dir);
+  if (!await fs64.pathExists(dir)) return [];
+  const names = await fs64.readdir(dir);
   const out = [];
   for (const fileName of [...names].sort()) {
     if (!fileName.endsWith(".md")) continue;
     const abs = path88.join(dir, fileName);
-    if (!(await fs63.lstat(abs)).isFile()) continue;
+    if (!(await fs64.lstat(abs)).isFile()) continue;
     const name = fileName.slice(0, -".md".length);
     out.push({ type, name, sourceRelPath: path88.posix.join(".claude", subdir, fileName) });
   }
@@ -18938,7 +19114,7 @@ async function buildLinkPlan(members) {
   const byKey = /* @__PURE__ */ new Map();
   const membersById = new Map(members.map((m) => [m.id, m]));
   for (const member of members) {
-    if (!await fs64.pathExists(member.absPath)) {
+    if (!await fs65.pathExists(member.absPath)) {
       skipped.push({ repo: member.id, reason: `not cloned locally (${member.absPath}) \u2014 skipped` });
       continue;
     }
@@ -19019,15 +19195,15 @@ async function runLinkContext(workspaceRoot, opts = {}) {
     const destRel = destRelPathFor(entry.type, entry.destKey);
     const destAbs = path90.join(workspaceRoot, destRel);
     if (write) {
-      await fs65.ensureDir(path90.dirname(destAbs));
-      if (await fs65.pathExists(destAbs)) await fs65.remove(destAbs);
-      await fs65.copy(entry.sourceAbsPath, destAbs, {
+      await fs66.ensureDir(path90.dirname(destAbs));
+      if (await fs66.pathExists(destAbs)) await fs66.remove(destAbs);
+      await fs66.copy(entry.sourceAbsPath, destAbs, {
         overwrite: true,
         errorOnExist: false,
         dereference: false,
         filter: (s) => {
           try {
-            return !fs65.lstatSync(s).isSymbolicLink();
+            return !fs66.lstatSync(s).isSymbolicLink();
           } catch {
             return false;
           }
@@ -19056,7 +19232,7 @@ async function runLinkContext(workspaceRoot, opts = {}) {
         warn(`Refusing to remove linked context path outside the workspace root: ${old.path}`);
         continue;
       }
-      if (await fs65.pathExists(abs)) await fs65.remove(abs);
+      if (await fs66.pathExists(abs)) await fs66.remove(abs);
     }
   }
   if (write) {
@@ -19112,7 +19288,7 @@ import path92 from "node:path";
 
 // src/claude/write-workspace-claude-md.ts
 import path91 from "node:path";
-import fs66 from "fs-extra";
+import fs67 from "fs-extra";
 init_fs();
 init_logger();
 init_paths();
@@ -19140,8 +19316,8 @@ async function writeWorkspaceClaudeMd(workspaceRoot, opts) {
   const filePath = opts.collision ? hausPath(workspaceRoot, "WORKSPACE.md") : path91.join(workspaceRoot, "CLAUDE.md");
   const say = opts.quiet ? () => {
   } : log;
-  const existed = await fs66.pathExists(filePath);
-  const prev = existed ? await fs66.readFile(filePath, "utf8") : "";
+  const existed = await fs67.pathExists(filePath);
+  const prev = existed ? await fs67.readFile(filePath, "utf8") : "";
   const next = opts.collision ? `${block}
 ` : injectHausBlock(prev, block, WORKSPACE_SENTINELS);
   const printable = displayPath(workspaceRoot, filePath);
@@ -19423,7 +19599,7 @@ Workspace setup complete: ${ok} ok, ${failed} failed. Wrote ${written.length} fi
 // src/commands/workspace/undo.ts
 import { existsSync as existsSync12, statSync as statSync2 } from "node:fs";
 import path93 from "node:path";
-import fs67 from "fs-extra";
+import fs68 from "fs-extra";
 init_fs();
 init_logger();
 init_paths();
@@ -19474,7 +19650,7 @@ async function runWorkspaceUndo(workspaceRoot, options = {}) {
         warn(`Refusing to remove linked context path outside the workspace root: ${entry.path}`);
         continue;
       }
-      if (await fs67.pathExists(abs)) {
+      if (await fs68.pathExists(abs)) {
         log(`[dry-run] Would remove ${entry.path} (linked ${entry.type} from ${entry.repo})`);
       }
     }
@@ -19484,11 +19660,11 @@ async function runWorkspaceUndo(workspaceRoot, options = {}) {
       hausPath(workspaceRoot, "WORKSPACE.md")
     ];
     for (const abs of workspaceArtifacts) {
-      if (await fs67.pathExists(abs)) {
+      if (await fs68.pathExists(abs)) {
         log(`[dry-run] Would remove ${path93.relative(workspaceRoot, abs)}`);
       }
     }
-    if (!await fs67.pathExists(hausPath(workspaceRoot, "WORKSPACE.md"))) {
+    if (!await fs68.pathExists(hausPath(workspaceRoot, "WORKSPACE.md"))) {
       const claudeMd = await readText(path93.join(workspaceRoot, "CLAUDE.md"));
       if (claudeMd?.includes(WORKSPACE_BLOCK_BEGIN) || claudeMd && hasLegacyWorkspaceBlock(claudeMd)) {
         log("[dry-run] Would remove the workspace haus import block from CLAUDE.md");
@@ -19528,26 +19704,26 @@ async function runWorkspaceUndo(workspaceRoot, options = {}) {
       warn(`Refusing to remove linked context path outside the workspace root: ${entry.path}`);
       continue;
     }
-    if (await fs67.pathExists(abs)) {
-      await fs67.remove(abs);
+    if (await fs68.pathExists(abs)) {
+      await fs68.remove(abs);
       log(`Removed ${entry.path} (linked ${entry.type} from ${entry.repo})`);
     }
   }
   for (const rel of WORKSPACE_AGGREGATE_FILES) {
     const abs = hausPath(workspaceRoot, rel);
-    if (await fs67.pathExists(abs)) {
-      await fs67.remove(abs);
+    if (await fs68.pathExists(abs)) {
+      await fs68.remove(abs);
       log(`Removed ${path93.relative(workspaceRoot, abs)}`);
     }
   }
   const manifestFile = manifestPath(workspaceRoot);
-  if (await fs67.pathExists(manifestFile)) {
-    await fs67.remove(manifestFile);
+  if (await fs68.pathExists(manifestFile)) {
+    await fs68.remove(manifestFile);
     log(`Removed ${path93.relative(workspaceRoot, manifestFile)}`);
   }
   const workspaceMdPath = hausPath(workspaceRoot, "WORKSPACE.md");
-  if (await fs67.pathExists(workspaceMdPath)) {
-    await fs67.remove(workspaceMdPath);
+  if (await fs68.pathExists(workspaceMdPath)) {
+    await fs68.remove(workspaceMdPath);
     log(`Removed ${path93.relative(workspaceRoot, workspaceMdPath)}`);
   } else {
     const claudeMdPath = path93.join(workspaceRoot, "CLAUDE.md");
@@ -19559,19 +19735,19 @@ async function runWorkspaceUndo(workspaceRoot, options = {}) {
           end: WORKSPACE_BLOCK_END
         });
         if (next.length === 0) {
-          await fs67.remove(claudeMdPath);
+          await fs68.remove(claudeMdPath);
           log("Removed CLAUDE.md (only contained the workspace haus import block).");
         } else {
-          await fs67.writeFile(claudeMdPath, next, "utf8");
+          await fs68.writeFile(claudeMdPath, next, "utf8");
           log("Removed haus import block from CLAUDE.md (user content preserved).");
         }
       } else if (prev && hasLegacyWorkspaceBlock(prev)) {
         const next = stripHausBlock(prev, { begin: BLOCK_BEGIN, end: BLOCK_END });
         if (next.length === 0) {
-          await fs67.remove(claudeMdPath);
+          await fs68.remove(claudeMdPath);
           log("Removed CLAUDE.md (only contained the pre-upgrade workspace haus import block).");
         } else {
-          await fs67.writeFile(claudeMdPath, next, "utf8");
+          await fs68.writeFile(claudeMdPath, next, "utf8");
           log(
             "Removed pre-upgrade workspace haus import block from CLAUDE.md (user content preserved)."
           );
@@ -19743,6 +19919,9 @@ program.command("scan").description(
 program.command("recommend").description("Score catalog items against the scanned context and write recommendation.json").option("--json").option(
   "--include <ids...>",
   "Force opt-in catalog items into the recommendation as manual selections (space- or comma-separated ids)"
+).option(
+  "--declare-role <roles...>",
+  "Declare a repo role (persisted in .haus-workflow/haus.config.json declaredRoles) so role-gated opt-in items are recommended"
 ).action(runRecommend);
 program.command("doctor").description(
   "Validate project setup: hooks contract, managed files, cache freshness, CLI version"
@@ -19841,7 +20020,10 @@ guard.command("bash").description("Block dangerous shell commands (run by the Cl
 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(
+  cmd.command("suggest").option("--from-hook", "Emit JSON for Claude Code Stop hook").option(
+    "--title <title>",
+    "Draft title; with a title the draft is printed even when the diff is not decision-worthy"
+  ).action(
     (opts) => runDecisions("suggest", void 0, opts)
   );
   cmd.command("next-number").action(() => runDecisions("next-number"));