npm - @haus-tech/haus-workflow - Versions diffs - 5.10.1 → 5.12.0 - Mend

@haus-tech/haus-workflow 5.10.1 → 5.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/CHANGELOG.md +18 -0
package/dist/cli.js +502 -308
package/library/catalog/manifest.json +409 -210
package/library/global/skills/haus-workflow/SKILL.md +7 -1
package/library/global/skills/haus-workflow/references/init.md +13 -4
package/package.json +1 -1

package/dist/cli.js CHANGED Viewed

@@ -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
@@ -8909,11 +8910,13 @@ var BOLD_SPAN = /\*\*([^*\n]+)\*\*/g;
 var BARE_NAME = /^[a-z0-9][a-z0-9-]{2,}$/;
 var KEBAB_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)+$/;
 var AGENT_WORD = /\bagents?\b/i;
+var SENTENCE_END = /[.!?](?=\s|$)/g;
 var ITEMS_HEADING = /\b(?:skills?|agents?)\b/i;
 var LIST_ITEM = /^(\s*(?:[-*+]|\d+[.)])\s+)(.*)$/;
 var LIST_LABEL = /^[A-Za-z][A-Za-z /]{0,24}:\s*/;
 var KEYWORD_BEFORE = /(?:sub)?(?:skills?|agents?)\s*[:=-]*\s*$/i;
 var KEYWORD_AFTER = /^\s+(?:[A-Za-z]+\s+)?(?:sub)?(?:skills?|agents?)\b/i;
+var ARTICLE_BEFORE = /\b(?:a|an)\s+$/i;
 var ROUTER_BEFORE = /\b(?:routes?|routing|delegates?|dispatch(?:es)?|hands? off)\s*(?:to|→|->|:)?\s*$/i;
 var RUN_SEPARATOR = /^\s*(?:\([^)\n]*\))?\s*(?:,|;|\/|\band\b|\bor\b|\bplus\b)\s*(?:the\s+)?$/i;
 var INLINE_KEYWORD_NAME = /^(?:sub)?(?:skills?|agents?)\s*[:=]\s*(\S+)$/i;
@@ -8947,7 +8950,15 @@ function groupRuns(line2, spans) {
   }
   return runs;
 }
-function isAgentContext(line2, nearestHeading) {
+function sentenceAround(line2, token) {
+  let start = 0;
+  for (const end of line2.matchAll(SENTENCE_END)) {
+    if (end.index >= token.end) return [start, end.index + 1];
+    start = end.index + 1;
+  }
+  return [start, line2.length];
+}
+function isAgentContext(line2, token, nearestHeading) {
   let blanked = "";
   let cursor = 0;
   for (const span of boldNameSpans(line2)) {
@@ -8955,7 +8966,8 @@ function isAgentContext(line2, nearestHeading) {
     cursor = span.end;
   }
   blanked += line2.slice(cursor);
-  return AGENT_WORD.test(blanked) || AGENT_WORD.test(nearestHeading);
+  const [start, end] = sentenceAround(line2, token);
+  return AGENT_WORD.test(blanked.slice(start, end)) || AGENT_WORD.test(nearestHeading);
 }
 function extractNameReferences(lines, { knownNames = /* @__PURE__ */ new Set() } = {}) {
   const out = [];
@@ -8969,16 +8981,17 @@ function extractNameReferences(lines, { knownNames = /* @__PURE__ */ new Set() }
     const itemBody = listMatch?.[2]?.replace(LIST_LABEL, "");
     const itemBodyStart = itemBody === void 0 ? -1 : line2.length - itemBody.length;
     const underItemsHeading = ITEMS_HEADING.test(nearestHeading);
-    const looseContext = isAgentContext(line2, nearestHeading);
+    const looseContext = (span) => KEBAB_NAME.test(span.text) && isAgentContext(line2, span, nearestHeading);
     for (const run of groupRuns(line2, boldNameSpans(line2))) {
       const before = line2.slice(0, run[0].start);
       const after = line2.slice(run.at(-1).end);
-      const positional = KEYWORD_BEFORE.test(before) || ROUTER_BEFORE.test(before) || KEYWORD_AFTER.test(after) || // Two co-listed installed items make the run an item list. One is not enough:
+      const classifier = ARTICLE_BEFORE.test(before);
+      const positional = KEYWORD_BEFORE.test(before) || ROUTER_BEFORE.test(before) || !classifier && KEYWORD_AFTER.test(after) || // Two co-listed installed items make the run an item list. One is not enough:
       // package names share basenames with skills.
       run.filter((span) => knownNames.has(span.text)).length >= 2 || underItemsHeading && run[0].start === itemBodyStart;
       for (const span of run) {
         if (inCodeSpan(span.start)) continue;
-        if (!positional && !(KEBAB_NAME.test(span.text) && looseContext)) continue;
+        if (!positional && (classifier || !looseContext(span))) continue;
         out.push({ line: lineNumber, name: span.text, kind: "bold" });
       }
     }
@@ -9044,14 +9057,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 +9125,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 +9152,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 +9204,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 +9217,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 +9266,8 @@ async function collectDiffStats(root, opts) {
   }
   return {
     files,
+    presentFiles,
+    renames,
     linesAdded,
     linesRemoved,
     linesByFile,
@@ -9262,12 +9315,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 +9330,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 +9358,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 +9403,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 +9490,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 (newDecisionFiles.length === 0) {
-    errors.push(`no new or updated decision under ${input2.decisionsRel}/`);
-    return errors;
+  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))
+  );
+  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 +9583,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 +9595,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 };
+  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"
+    );
   }
-  if (hasSkipToken(skipText) && securityTriggered) {
-    reasons.push("[adr-skip] ignored for security/auth path changes");
+  if (skip && securityTriggered) {
+    reasons.push("security/auth path changes ignore [adr-skip], even on its own line");
   }
-  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 (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 +9678,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 +9701,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 +9750,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 +9780,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 +9814,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 +9837,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 +9861,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 +9886,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 +10184,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 +10202,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 +10225,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 +10253,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 +10261,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 +10273,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 +10606,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 +10841,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 +10923,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 +10949,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 +11059,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 +11093,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 +11123,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 +11137,7 @@ function hashContent(content2) {
 }
 function destFileMissing(destPath) {
   try {
-    return !fs45.statSync(destPath).isFile();
+    return !fs46.statSync(destPath).isFile();
   } catch {
     return true;
   }
@@ -10988,7 +11145,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 +11157,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 +11173,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 +11188,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 +11264,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 +11324,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 +12014,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 +12027,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 +12037,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 +12047,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 +12061,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 +12073,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 +12082,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 +12092,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 +12214,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 +12239,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 +12269,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 +12309,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 +12348,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 +12366,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 +12906,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 +12914,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 +15047,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 +15235,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 +15250,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 +15268,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 +15292,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 +15305,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 +15318,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 +15394,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 +15711,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 +15734,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 +15948,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 +15967,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 +15997,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 +16020,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 +16052,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 +16098,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 +16114,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 +16148,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 +16166,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 +16178,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 +16261,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 +16422,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 +16454,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 +16465,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 +16475,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 +16491,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 +16534,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 +16568,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 +16585,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 +16604,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 +16680,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 +16801,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 +16837,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 +17037,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 +17055,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 +17069,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 +17161,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 +17279,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 +17288,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 +17323,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 +17332,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 +17357,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 +17365,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 +17756,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 +17832,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 +17901,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 +17940,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 +17985,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 +18019,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 +18035,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 +18053,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 +18076,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 +18091,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 +18118,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 +18199,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 +18273,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 +19047,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 +19065,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 +19086,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 +19126,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 +19207,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 +19244,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 +19300,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 +19328,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 +19611,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 +19662,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 +19672,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 +19716,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 +19747,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 +19931,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 +20032,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"));