@haus-tech/haus-workflow 0.32.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,165 @@
 # Changelog
 
+## [1.0.0](https://github.com/WeAreHausTech/haus-workflow/compare/v0.32.1...v1.0.0) (2026-07-02)
+
+### ⚠ BREAKING CHANGES
+
+- **workflow:** the standalone /haus-setup, /haus-clone,
+  /haus-cloneandsetup, /haus-doctor, and /haus-fix slash commands no longer
+  exist. Use /haus-workflow <task> instead (e.g. /haus-workflow project:init,
+  /haus-workflow project:doctor). Existing global installs self-clean the
+  old files on the next `haus update`/`haus install` via the installer's
+  existing orphan-pruning.
+
+- docs(decisions): add ADR-0011 for the haus-workflow command consolidation
+
+Satisfies the decisions-gate CI check for the breaking-change command
+removal + skill-install mechanism change in the prior commit.
+
+- fix(workflow): clarify the Step 1 menu is two sequential AskUserQuestion calls
+
+Copilot review flagged ambiguous wording ("split into two grouped
+questions in one call") that could read as cramming both question
+blocks into a single AskUserQuestion invocation. AskUserQuestion is
+not guaranteed multi-question across every environment this skill
+runs in, so make the instruction unambiguous: ask Question 1, read
+the answer, then ask Question 2 as a second, separate call.
+
+- feat(workflow): upgrade project:refresh to a full non-destructive sync
+
+Previously project:refresh just ran `haus apply --write` (reapply from
+the already-computed recommendation, no package/catalog update, no
+rescan, no docs refresh). Upgrade it to: run `haus update` first (npm
+package + catalog + global install), then re-run the project:init
+pipeline in place (rescan, redo the deep docs read, re-recommend,
+apply) — nothing removed first, contrasting with project:reinit which
+wipes everything before re-running the same pipeline.
+
+Moves the root-CLAUDE.md-imports check from a now-orphaned SKILL.md
+section into references/init.md's own apply step, since project:init,
+project:reinit, and project:refresh all funnel through it.
+
+- feat(workflow): full project:refresh sync + SessionStart staleness hook
+
+project:refresh now runs `haus update` (npm package + catalog) first,
+then re-runs the project:init pipeline in place (rescan, redo docs,
+re-recommend, apply) instead of just `haus apply --write`. The `update`
+task's own post-run steps cascade into the same pipeline when run
+inside an already-set-up project, so its "also refreshes this project"
+scope note is now literally true.
+
+Adds a new SessionStart hook (`haus.update-check`, in both
+PROJECT_HOOK_FRAGMENTS and CANONICAL_HOOKS) running `haus update
+--from-hook`: silent when the project is up to date, emits a
+SessionStart hookSpecificOutput note nudging `/haus-workflow
+project:refresh` when the npm package, catalog, or lockfile has
+drifted. Never blocks session start on a network failure.
+
+Fixes found by adversarial review before landing:
+
+- fetchNpmVersionStatus had no test-mode gate, so the new --from-hook
+  tests hit the real npm registry; added HAUS_SKIP_NPM_CHECK (mirrors
+  HAUS_CATALOG_REMOTE_BASE's test-only-when-explicit pattern) rather
+  than gating on bare HAUS_TEST_MODE, which the whole test run already
+  sets and would have broken tests/npm-version.test.js's fetch mocks.
+- checkLock() now runs before the npm/catalog network calls in the
+  hook check, so a non-haus directory costs nothing.
+- matcher parity between the two hardcoded hook-fragment lists.
+- project:refresh's step 1 now explicitly inherits the "After `haus
+update`" reactions (version bump, WORKFLOW.md nudge, catalog
+  summary), which it was silently skipping despite running the same
+  command.
+- runbook entry: doctor --hooks going red right after an upgrade,
+  before the next apply, is expected (same as any new required rule)
+  — documented with the fix (re-apply once).
+
+yarn verify: 627/627 tests green.
+
+- fix(workflow): drop expensive lock-hash check from the SessionStart hook, add help to the menu
+
+Copilot review, two fixes:
+
+- runFromHookCheck() called checkLock(), which hashes the content of
+  every installed managed path on every single SessionStart. Replaced
+  with a new readLockSummary() (count + catalogRef only, no hashing) —
+  the hook only ever needed those two cheap facts. Drops the
+  lock-drift reason from the hook's output entirely; doctor/project:fix
+  remain the tools for catching local file tamper, which is a
+  different concern than "is this project behind the installed
+  package/catalog" (what this hook actually checks).
+- The Step 1 no-arg menu didn't offer `help`, even though it's a real
+  task in the alias table. Added as Question 2 option 4 (still within
+  the 4-option cap).
+
+Test changes: replaced the lock-drift `--from-hook` test (no longer
+applicable — the hook no longer looks at hashes) with a "healthy
+project with a real lock stays silent" integration test, plus a new
+direct unit test for the "npm behind" JSON-emission path (mocked
+fetch, same style as tests/npm-version.test.js) — there's no way to
+force fetchLatestCatalogTag/fetchNpmVersionStatus to report "behind"
+via env vars alone, so this exercises the actual behind branch and its
+JSON shape deterministically instead of only ever testing silence.
+
+yarn verify: 628/628 tests green.
+
+- fix(test): use exact hostname match instead of substring for npm registry mock
+
+CodeQL flagged String(url).includes('registry.npmjs.org') as an
+incomplete URL substring sanitization (a host like
+evil.com/registry.npmjs.org or registry.npmjs.org.evil.com would also
+match). Not exploitable here (url comes from our own hardcoded fetch
+call, not untrusted input), but the check should still be precise —
+parse the URL and compare new URL(url).hostname exactly.
+
+- fix(workflow): stop false-positive catalog-behind nudges, fix docs
+
+Copilot review, four fixes:
+
+- docs/runbook.md: a backtick code span was split across a line wrap
+  ("`/haus-workflow\nproject:refresh`"), rendering broken. Rewrapped.
+- docs/cli.md: --from-hook's description said it checks npm/catalog/
+  lock; it never inspected lock content (no hashing) and only reads
+  the lock to confirm this is a haus project and get its catalogRef.
+  Corrected the wording.
+- readLockSummary() only ever read catalogRef from lock item 0. An
+  older/mixed lock could have it missing there while later items carry
+  it. Now searches all items for the first defined catalogRef.
+- runFromHookCheck() fell back to 'main' when catalogRef was absent,
+  which then almost always compared "behind" against any real release
+  tag — a false-positive nudge, and a wrong claim ("installed from
+  main") when the ref was actually unknown. Now skips the catalog
+  comparison entirely when catalogRef is null.
+
+New tests: readLockSummary's cross-item catalogRef fallback (and that
+it never hashes file content, unlike checkLock), plus a regression
+test proving no false "behind" nudge fires when catalogRef is missing
+even if the catalog has newer tags (mocked GitHub tags API).
+
+yarn verify: 633/633 tests green.
+
+- fix(docs): avoid a prettier-reflowed broken inline code span in cli.md
+
+The previous commit's own pre-commit prettier pass reflowed the
+--from-hook bullet and split a `/haus-workflow project:refresh`
+code span across the wrap (the same bug class Copilot flagged in
+runbook.md moments earlier) — verified by re-running prettier on
+docs/cli.md, docs/runbook.md, and SKILL.md directly; all three are
+now stable ("unchanged") under formatting.
+
+### Features
+
+- **workflow:** consolidate haus-\* commands into /haus-workflow skill ([#161](https://github.com/WeAreHausTech/haus-workflow/issues/161)) ([e5c34f7](https://github.com/WeAreHausTech/haus-workflow/commit/e5c34f73f723520041d54523f6cf384d890d6c99))
+
+### Bug Fixes
+
+- **apply:** scope llms.txt cache to items actually installed ([#162](https://github.com/WeAreHausTech/haus-workflow/issues/162)) ([f331f08](https://github.com/WeAreHausTech/haus-workflow/commit/f331f08a5c2e58bff2d8beda062f30515661685e))
+
+## [0.32.1](https://github.com/WeAreHausTech/haus-workflow/compare/v0.32.0...v0.32.1) (2026-06-30)
+
+### Bug Fixes
+
+- **security:** audit hardening — fail-closed, recommender gates, CI hardening ([#157](https://github.com/WeAreHausTech/haus-workflow/issues/157)) ([e545194](https://github.com/WeAreHausTech/haus-workflow/commit/e545194fd3d3eb553bc2955a7ca17574bd98be71))
+
 ## [0.32.0](https://github.com/WeAreHausTech/haus-workflow/compare/v0.31.1...v0.32.0) (2026-06-24)
 
 ### Features

package/dist/cli.js

@@ -650,48 +650,103 @@ function parseManifest(json) {
 }
 
 // src/catalog/remote-catalog.ts
+function isTestMode() {
+  return process.env["HAUS_TEST_MODE"] === "1" || process.env["NODE_ENV"] === "test";
+}
 function getCacheDir() {
   return process.env["HAUS_CATALOG_CACHE_DIR_OVERRIDE"] ?? path3.join(os2.homedir(), CATALOG_CACHE_SUBDIR);
 }
 var cachedCatalogRef;
 var cachedBlobPaths;
+function getBundledCatalogRef() {
+  try {
+    const manifestPath2 = path3.join(packageRoot(), "library/catalog/manifest.json");
+    const raw = fs2.readFileSync(manifestPath2, "utf8");
+    const data = JSON.parse(raw);
+    if (typeof data.version === "string" && data.version) {
+      return data.version.startsWith("v") ? data.version : `v${data.version}`;
+    }
+  } catch {
+  }
+  return void 0;
+}
 function getResolvedCatalogRef() {
-  return cachedCatalogRef ?? process.env["HAUS_CATALOG_REF"] ?? "main";
+  const resolved = cachedCatalogRef ?? process.env["HAUS_CATALOG_REF"] ?? getBundledCatalogRef();
+  if (!resolved) {
+    warn(
+      "Could not determine catalog ref from cache, env, or bundled snapshot \u2014 falling back to main (moving target)."
+    );
+    return "main";
+  }
+  return resolved;
 }
 function isCatalogRefResolved() {
   return cachedCatalogRef !== void 0 || process.env["HAUS_CATALOG_REF"] !== void 0;
 }
 async function resolveCatalogRef(opts) {
   const env = opts?.env ?? process.env;
-  if (env["HAUS_CATALOG_REF"]) return env["HAUS_CATALOG_REF"];
+  if (env["HAUS_CATALOG_REF"]) {
+    if (env["HAUS_CATALOG_REF"] === "main") {
+      warn(
+        "HAUS_CATALOG_REF=main is set \u2014 fetching from the moving main branch. Pin to a release tag for reproducible installs."
+      );
+    }
+    return env["HAUS_CATALOG_REF"];
+  }
   const fetchLatest = opts?.fetchLatestTag ?? fetchLatestCatalogTag;
   const tag = await fetchLatest();
-  return tag ?? "main";
+  if (tag !== null) return tag;
+  const fallback = opts?.fallbackRef;
+  if (fallback) {
+    warn(
+      `Tag resolution failed \u2014 using cached ref ${fallback}. To use latest, retry or set HAUS_CATALOG_REF explicitly.`
+    );
+    return fallback;
+  }
+  const bundled = getBundledCatalogRef();
+  if (bundled) {
+    warn(
+      `Tag resolution failed \u2014 using bundled snapshot ref ${bundled}. To use latest, retry or set HAUS_CATALOG_REF explicitly.`
+    );
+    return bundled;
+  }
+  warn(
+    "Tag resolution failed and no fallback ref is available. Set HAUS_CATALOG_REF explicitly to avoid fetching from main."
+  );
+  return "main";
 }
 async function remoteBase() {
-  if (process.env["HAUS_CATALOG_REMOTE_BASE"]) {
+  if (isTestMode() && process.env["HAUS_CATALOG_REMOTE_BASE"]) {
     return process.env["HAUS_CATALOG_REMOTE_BASE"];
   }
   if (cachedCatalogRef === void 0) {
-    cachedCatalogRef = await resolveCatalogRef();
+    cachedCatalogRef = await resolveCatalogRef({ fallbackRef: getBundledCatalogRef() });
   }
   return `${CATALOG_REPO_URL}/${cachedCatalogRef}`;
 }
 async function fetchText(url) {
   try {
     const res = await fetch(url, { signal: AbortSignal.timeout(1e4) });
-    if (!res.ok) return null;
+    if (!res.ok) {
+      warn(`Catalog fetch HTTP ${res.status}: ${url}`);
+      return null;
+    }
     return await res.text();
-  } catch {
+  } catch (e) {
+    warn(`Catalog fetch failed (${e instanceof Error ? e.constructor.name : String(e)}): ${url}`);
     return null;
   }
 }
 async function fetchBytes(url) {
   try {
     const res = await fetch(url, { signal: AbortSignal.timeout(1e4) });
-    if (!res.ok) return null;
+    if (!res.ok) {
+      warn(`Catalog fetch HTTP ${res.status}: ${url}`);
+      return null;
+    }
     return Buffer.from(await res.arrayBuffer());
-  } catch {
+  } catch (e) {
+    warn(`Catalog fetch failed (${e instanceof Error ? e.constructor.name : String(e)}): ${url}`);
     return null;
   }
 }
@@ -828,7 +883,7 @@ async function fetchGitHubRecursiveBlobPaths(ref) {
 }
 async function fetchCatalogBlobPaths(_base) {
   if (cachedBlobPaths) return cachedBlobPaths;
-  if (process.env["HAUS_CATALOG_REMOTE_BASE"]) return null;
+  if (isTestMode() && process.env["HAUS_CATALOG_REMOTE_BASE"]) return null;
   const ref = getResolvedCatalogRef();
   const paths = await fetchGitHubRecursiveBlobPaths(ref);
   if (paths) cachedBlobPaths = paths;
@@ -838,7 +893,7 @@ async function listFilesUnderCatalogPrefix(prefix, base) {
   const normalized = prefix.replace(/\\/g, "/").replace(/\/+$/, "");
   const prefixSlash = `${normalized}/`;
   let relFiles;
-  if (process.env["HAUS_CATALOG_REMOTE_BASE"]) {
+  if (isTestMode() && process.env["HAUS_CATALOG_REMOTE_BASE"]) {
     relFiles = await listMockPrefixFiles(base, normalized);
   } else {
     const blobs = await fetchCatalogBlobPaths(base);
@@ -985,7 +1040,7 @@ async function syncConfigItem(item, base) {
   if (relFiles && relFiles.length > 0) {
     try {
       return await syncDirectoryFromPrefix(item, item.path, dest, base, {
-        validateMarkdown: false,
+        validateMarkdown: true,
         requireSkillMd: false,
         relFiles
       });
@@ -1125,7 +1180,7 @@ function compareSemver(a, b) {
   return 0;
 }
 async function fetchLatestCatalogTag() {
-  if (process.env["HAUS_CATALOG_REMOTE_BASE"]) return null;
+  if (isTestMode() && process.env["HAUS_CATALOG_REMOTE_BASE"]) return null;
   try {
     const res = await fetch(CATALOG_TAGS_API_URL, {
       signal: AbortSignal.timeout(5e3),
@@ -1756,6 +1811,13 @@ var PROJECT_HOOK_FRAGMENTS = [
     event: "Stop",
     matcher: "*",
     command: "haus decisions suggest --from-hook"
+  },
+  {
+    id: "haus.update-check",
+    gate: "keep",
+    event: "SessionStart",
+    matcher: "*",
+    command: "haus update --from-hook"
   }
 ];
 async function readProjectSettings(root) {
@@ -1855,6 +1917,12 @@ var CANONICAL_HOOKS = {
         matcher: "*",
         hooks: [{ type: "command", command: "haus decisions suggest --from-hook" }]
       }
+    ],
+    SessionStart: [
+      {
+        matcher: "*",
+        hooks: [{ type: "command", command: "haus update --from-hook" }]
+      }
     ]
   }
 };
@@ -2290,15 +2358,32 @@ ${templateContent}`;
       return null;
     }
     const existingContent = existing.slice(firstLine.length + 1);
-    if (!parsed.hash && !force) {
-      warn(
-        `${printable}: managed header missing hash \u2014 cannot verify tamper status, skipping. Use --force to overwrite.`
-      );
-      return null;
-    }
-    if (parsed.hash && hashText(normaliseLF(existingContent)) !== parsed.hash && !force) {
-      warn(`${printable}: content modified by user \u2014 skipping. Use --force to overwrite.`);
-      return null;
+    const bodyMatchesTemplate = hashText(normaliseLF(existingContent)) === contentHash;
+    if (parsed.hash) {
+      const bodyIntact = hashText(normaliseLF(existingContent)) === parsed.hash;
+      if (!bodyIntact && !force) {
+        warn(`${printable}: content modified by user \u2014 skipping. Use --force to overwrite.`);
+        return null;
+      }
+    } else {
+      if (!bodyMatchesTemplate && !force) {
+        const migratedHeader = makeWorkflowHeader(
+          pkgVersion,
+          hashText(normaliseLF(existingContent))
+        );
+        const migrated = `${migratedHeader}
+${existingContent}`;
+        if (hasTextChanged(existing, migrated)) {
+          if (dryRun) {
+            log(`${printable}: migrating legacy hash header (body preserved)`);
+          } else {
+            await writeText(destPath, migrated);
+          }
+        } else if (dryRun) {
+          log(`${printable}: unchanged`);
+        }
+        return destPath;
+      }
     }
     if (!hasTextChanged(existing, next)) {
       if (dryRun) log(`${printable}: unchanged`);
@@ -2342,11 +2427,7 @@ async function writeClaudeFiles(root, dryRun, selectedIds, opts = {}) {
   };
   const pkgRoot = packageRoot();
   const hausVersion2 = (await readJson(path14.join(pkgRoot, "package.json")))?.version ?? "0.0.0";
-  const coreFiles = [
-    claudePath(root, "settings.json"),
-    claudePath(root, "rules", "haus.md"),
-    claudePath(root, "commands", "haus-doctor.md")
-  ];
+  const coreFiles = [claudePath(root, "settings.json"), claudePath(root, "rules", "haus.md")];
   const rootClaudeMdPath = await writeRootClaudeMd(root, dryRun);
   const decisionsSeedPath = await writeDecisionsSeed(root, dryRun);
   const workflowPath = await writeWorkflow(root, hausVersion2, dryRun, opts.force);
@@ -2369,12 +2450,6 @@ async function writeClaudeFiles(root, dryRun, selectedIds, opts = {}) {
     await applyProjectSettingsMerge(root);
     await assertPostApplySettingsHausContract(root);
   }
-  await writeManagedText(
-    root,
-    claudePath(root, "commands", "haus-doctor.md"),
-    "Run `haus doctor`.",
-    dryRun
-  );
   const legacyReviewPath = claudePath(root, "commands", "haus-review.md");
   if (await fs14.pathExists(legacyReviewPath)) {
     const content2 = await fs14.readFile(legacyReviewPath, "utf8");
@@ -2389,6 +2464,20 @@ async function writeClaudeFiles(root, dryRun, selectedIds, opts = {}) {
       }
     }
   }
+  const legacyDoctorPath = claudePath(root, "commands", "haus-doctor.md");
+  if (await fs14.pathExists(legacyDoctorPath)) {
+    const content2 = await fs14.readFile(legacyDoctorPath, "utf8");
+    const stub = "Run `haus doctor`.";
+    if (content2 === stub || content2 === `${stub}
+` || content2 === `${stub}\r
+`) {
+      if (dryRun) {
+        say(`[dry-run] would remove stale ${displayPath(root, legacyDoctorPath)}`);
+      } else {
+        await fs14.remove(legacyDoctorPath);
+      }
+    }
+  }
   await writeManagedText(
     root,
     claudePath(root, "rules", "haus.md"),
@@ -2407,7 +2496,7 @@ async function writeClaudeFiles(root, dryRun, selectedIds, opts = {}) {
       "results in plain language \u2014 never make them use a terminal or read JSON.",
       "- Set up / configure / fix / check \u2192 `haus setup-project`, `haus apply --write`, `haus doctor`",
       "- Update package + catalog \u2192 `haus update`",
-      "- The `/haus-workflow`, `/haus-setup`, `/haus-doctor`, and `/haus-fix` commands do the same.",
+      "- `/haus-workflow <task>` does the same conversationally (e.g. `init`, `fix`, `doctor`, `reinit`).",
       ""
     ].join("\n"),
     dryRun
@@ -2491,11 +2580,50 @@ async function writeClaudeFiles(root, dryRun, selectedIds, opts = {}) {
           `${displayPath(root, destination)}: ${exists ? "would overwrite" : "would create"} (${item.id})`
         );
       } else if (item.type === "skill") {
+        const skillFiles = (await fs14.readdir(sourcePath, { recursive: true })).filter(
+          (f) => typeof f === "string" && f.endsWith(".md")
+        );
+        let skillValid = true;
+        for (const relFile of skillFiles) {
+          const mdPath = path14.join(sourcePath, relFile);
+          const mdContent = await fs14.readFile(mdPath, "utf8");
+          const mdValidation = validateCatalogItem(
+            {
+              id: manifestItem.id,
+              type: "skill",
+              path: manifestItem.path,
+              source: manifestItem.source
+            },
+            mdContent
+          );
+          if (!mdValidation.ok) {
+            warn(
+              `Skipping ${item.id}: pre-copy validation failed (${relFile}) \u2014 ${mdValidation.reason}`
+            );
+            skillValid = false;
+            break;
+          }
+        }
+        if (!skillValid) continue;
         await installCatalogSkill(sourcePath, destination, {
           originSourceId: manifestItem.originSourceId,
           dryRun: false
         });
       } else {
+        const fileContent = await fs14.readFile(sourcePath, "utf8");
+        const validation = validateCatalogItem(
+          {
+            id: manifestItem.id,
+            type: manifestItem.type,
+            path: manifestItem.path,
+            source: manifestItem.source
+          },
+          fileContent
+        );
+        if (!validation.ok) {
+          warn(`Skipping ${item.id}: pre-copy validation failed \u2014 ${validation.reason}`);
+          continue;
+        }
         await fs14.ensureDir(path14.dirname(destination));
         await fs14.copy(sourcePath, destination, { overwrite: true, errorOnExist: false });
       }
@@ -2670,8 +2798,25 @@ async function fetchSingleRef(url, cacheDir, meta) {
     return { result: "failed" };
   }
 }
+function collectLlmsTxtUrls(items) {
+  return [...new Set(items.flatMap((item) => (item.references ?? []).filter(isLlmsTxtUrl)))];
+}
+async function pruneOrphanedRefs(cacheDir, keepUrls) {
+  const meta = await readCacheMeta(cacheDir);
+  let removed = 0;
+  for (const [url, entry] of Object.entries(meta)) {
+    if (keepUrls.has(url)) continue;
+    delete meta[url];
+    removed++;
+    const safeFile = typeof entry.file === "string" && entry.file === path16.basename(entry.file);
+    if (safeFile) await fs16.remove(path16.join(cacheDir, entry.file)).catch(() => {
+    });
+  }
+  if (removed > 0) await writeCacheMeta(cacheDir, meta);
+  return removed;
+}
 async function fetchRefsForItems(items, cacheDir) {
-  const urls = [...new Set(items.flatMap((item) => (item.references ?? []).filter(isLlmsTxtUrl)))];
+  const urls = collectLlmsTxtUrls(items);
   const summary = {
     fetched: 0,
     unchanged: 0,
@@ -2806,14 +2951,22 @@ async function runApply(options) {
   if (!isDryRun) {
     try {
       const cacheDir = hausPath(root, "llms-cache");
+      const lock = await readJson(hausPath(root, "haus.lock.json")) ?? [];
+      const installedIds = new Set(lock.map((entry) => entry.id));
       const allItems = await loadCatalog(root);
-      const summary = await fetchRefsForItems(allItems, cacheDir);
+      const installedItems = allItems.filter((item) => installedIds.has(item.id));
+      const summary = await fetchRefsForItems(installedItems, cacheDir);
       if (summary.fetched > 0)
         log(`Fetched ${summary.fetched} llms.txt reference(s) to ${cacheDir}`);
       if (summary.failed > 0)
         warn(
           `Failed to fetch ${summary.failed} llms.txt reference(s): ${summary.failedUrls.join(", ")}`
         );
+      const pruned = await pruneOrphanedRefs(cacheDir, new Set(collectLlmsTxtUrls(installedItems)));
+      if (pruned > 0)
+        log(
+          `Removed ${pruned} orphaned llms.txt cache entr${pruned === 1 ? "y" : "ies"} from ${cacheDir}`
+        );
     } catch (err) {
       warn(
         `Could not fetch llms.txt references: ${err instanceof Error ? err.message : String(err)}`
@@ -3705,7 +3858,7 @@ function buildSourcesReport(items) {
   }
   return {
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    items: [...statusBySource.entries()].map(([id, status]) => ({ id, status })).sort((a, b) => a.id.localeCompare(b.id))
+    items: [...statusBySource.entries()].map(([source, status]) => ({ source, status })).sort((a, b) => a.source.localeCompare(b.source))
   };
 }
 async function writeSourcesReport(root) {
@@ -3816,7 +3969,13 @@ async function readContextOrScan(root) {
 
 // src/update/npm-version.ts
 var NPM_PACKAGE_NAME = "@haus-tech/haus-workflow";
+function isTestMode2() {
+  return process.env["HAUS_TEST_MODE"] === "1" || process.env["NODE_ENV"] === "test";
+}
 async function fetchNpmVersionStatus(currentVersion) {
+  if (isTestMode2() && process.env["HAUS_SKIP_NPM_CHECK"]) {
+    return { current: currentVersion, latest: null, updateAvailable: false };
+  }
   try {
     const res = await fetch(
       `https://registry.npmjs.org/${encodeURIComponent(NPM_PACKAGE_NAME)}/latest`,
@@ -4417,9 +4576,7 @@ function mergeRecommendationWarnings(context) {
 // src/recommender/recommend.ts
 async function recommend(root, context, opts = {}) {
   const items = await loadCatalog(root);
-  const sources = await readJson(
-    hausPath(root, "sources-report.json")
-  ) ?? {};
+  const sources = buildSourcesReport(items);
   const deep = await readJson(hausPath(root, "deep-context.json")) ?? {};
   const scannerStacks = buildStackSet(context);
   const scannerRoles = new Set(context.repoRoles.map((r) => r.toLowerCase()));
@@ -4437,7 +4594,7 @@ async function recommend(root, context, opts = {}) {
   const depSet = scannerDeps;
   const recommended = [];
   const skipped = [];
-  const sourceTrust = new Map((sources.items ?? []).map((x) => [x.id, x.status ?? "candidate"]));
+  const sourceTrust = new Map(sources.items.map((x) => [x.source, x.status]));
   const changedFiles = await readChangedFiles(root);
   const skip = (id, code, message, signal) => {
     skipped.push({ id, reason: message, skipReasons: [{ code, message, signal }] });
@@ -4445,8 +4602,13 @@ async function recommend(root, context, opts = {}) {
   const roleSignal = (name) => scannerRoles.has(name.toLowerCase()) ? `role:${name}` : `deep:role:${name}`;
   const stackSignal = (name) => scannerStacks.has(name.toLowerCase()) ? `tag:${name}` : `deep:tag:${name}`;
   for (const item of items) {
-    const itemSearchText = `${item.id} ${item.tags.join(" ")}`.toLowerCase();
-    if (UNSUPPORTED.some((x) => itemSearchText.includes(x))) {
+    const normSource = typeof item.source === "string" ? item.source.trim() : "";
+    if (!normSource) {
+      skip(item.id, "invalid-source", "Item source is missing or empty");
+      continue;
+    }
+    const itemTags = item.tags.map((t) => t.toLowerCase());
+    if (UNSUPPORTED.some((x) => itemTags.includes(x))) {
       skip(item.id, "unsupported-policy", "Unsupported stack policy");
       continue;
     }
@@ -4454,7 +4616,7 @@ async function recommend(root, context, opts = {}) {
       skip(item.id, "deprecated", "Catalog item is deprecated", "reviewStatus:deprecated");
       continue;
     }
-    if (item.source === "curated") {
+    if (normSource === "curated") {
       const rs = item.reviewStatus;
       if (!rs || rs !== "approved") {
         skip(
@@ -4475,17 +4637,19 @@ async function recommend(root, context, opts = {}) {
         continue;
       }
     }
-    if (SENSITIVE_ITEM_KEYWORDS.some((x) => itemSearchText.includes(x))) {
+    const sensitiveInId = SENSITIVE_ITEM_KEYWORDS.some((x) => item.id.toLowerCase().includes(x));
+    const sensitiveInTags = SENSITIVE_ITEM_KEYWORDS.some((x) => itemTags.includes(x));
+    if (sensitiveInId || sensitiveInTags) {
       skip(item.id, "sensitive-policy", "Sensitive content policy block");
       continue;
     }
-    const trust = sourceTrust.get(item.source);
+    const trust = sourceTrust.get(normSource);
     if (trust === "candidate" || trust === "rejected") {
       skip(item.id, "source-trust", "Source trust policy block", `trust:${trust}`);
       continue;
     }
-    if (item.source && item.source !== "haus" && trust !== "approved") {
-      skip(item.id, "source-approval", "Source not approved", `source:${item.source}`);
+    if (normSource !== "haus" && trust !== "approved") {
+      skip(item.id, "source-approval", "Source not approved", `source:${normSource}`);
       continue;
     }
     if (item.id === "haus.nx21-monorepo-patterns" && !roleSet.has("nx-monorepo")) {
@@ -4510,15 +4674,6 @@ async function recommend(root, context, opts = {}) {
       skip(item.id, "required-role-missing", "Required role missing: database", "role:database");
       continue;
     }
-    if (item.id === "haus.ecc-typescript-reviewer" && (stackSet.has("react") || stackSet.has("react19") || stackSet.has("nextjs") || stackSet.has("next") || roleSet.has("react-app") || roleSet.has("next-app"))) {
-      skip(
-        item.id,
-        "co-install-react-reviewer",
-        "Skip typescript-reviewer on React/Next stacks (use react-reviewer)",
-        "stack:react|nextjs|role:react-app|next-app"
-      );
-      continue;
-    }
     const isDefaultBaseline = item.default === true;
     const reasons = [];
     const push = (code, message, signal) => reasons.push({ code, message, signal });
@@ -4536,9 +4691,11 @@ async function recommend(root, context, opts = {}) {
         `packageManager:${context.packageManager}`
       );
     }
-    const configSignal = item.tags.find(
-      (t) => context.warnings.join(" ").toLowerCase().includes(t.toLowerCase())
-    );
+    const configSignal = item.tags.find((t) => {
+      const escaped = t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const re = new RegExp(`(?:^|\\W)${escaped}(?:\\W|$)`, "i");
+      return context.warnings.some((w) => re.test(w));
+    });
     if (configSignal) push("config-signal-match", "config signal match", `warning:${configSignal}`);
     const idSegment = item.id.split(".").pop() ?? "";
     const changedMatch = idSegment ? changedFiles.find((f) => f.includes(idSegment)) : void 0;
@@ -4671,6 +4828,13 @@ function applyCoInstallSuppression(recommended, skipped) {
       code: "co-install-redis-official",
       message: "Skip ecc-redis-patterns when official redis-connections skill is selected",
       signal: "co-install:redis-connections"
+    },
+    {
+      suppress: "haus.ecc-typescript-reviewer",
+      whenAnyRecommended: ["haus.ecc-react-reviewer"],
+      code: "co-install-react-reviewer",
+      message: "Skip typescript-reviewer on React/Next stacks (use react-reviewer)",
+      signal: "co-install:react-reviewer"
     }
   ];
   for (const rule of rules) {
@@ -4951,7 +5115,7 @@ ${content2}`;
 // src/install/apply.ts
 var SCHEMA_VERSION2 = "1";
 function hashContent(content2) {
-  return `sha256-${crypto2.createHash("sha256").update(content2).digest("hex")}`;
+  return `sha256-${crypto2.createHash("sha256").update(normaliseLF(content2)).digest("hex")}`;
 }
 function sourceVersion() {
   try {
@@ -4965,6 +5129,22 @@ function sourceVersion() {
 function globalSrcDir() {
   return path30.join(packageRoot(), "library", "global");
 }
+function collectSkillAuxFiles(skillsDir, claudeDir, skillName) {
+  const skillDir = path30.join(skillsDir, skillName);
+  const entries = [];
+  for (const rel of fs24.readdirSync(skillDir, { recursive: true })) {
+    if (rel === "SKILL.md") continue;
+    const abs = path30.join(skillDir, rel);
+    if (!fs24.statSync(abs).isFile()) continue;
+    const posixRel = rel.split(path30.sep).join("/");
+    entries.push({
+      stableId: `skill.${skillName}.${posixRel.replace(/\//g, ".")}`,
+      srcRelPath: path30.join("library", "global", "skills", skillName, rel),
+      destPath: path30.join(claudeDir, "skills", skillName, rel)
+    });
+  }
+  return entries;
+}
 function collectSourceFiles(srcDir, claudeDir) {
   const entries = [];
   const skillsDir = path30.join(srcDir, "skills");
@@ -4977,6 +5157,7 @@ function collectSourceFiles(srcDir, claudeDir) {
           srcRelPath: path30.join("library", "global", "skills", skillName, "SKILL.md"),
           destPath: path30.join(claudeDir, "skills", skillName, "SKILL.md")
         });
+        entries.push(...collectSkillAuxFiles(skillsDir, claudeDir, skillName));
       }
     }
   }
@@ -5418,7 +5599,7 @@ import path32 from "node:path";
 import fs26 from "fs-extra";
 
 // src/claude/managed-paths.ts
-var PROJECT_MANAGED_CLAUDE_REL = ["rules/haus.md", "commands/haus-doctor.md"];
+var PROJECT_MANAGED_CLAUDE_REL = ["rules/haus.md"];
 var PROJECT_MANAGED_HAUS_REL = ["haus.lock.json"];
 function coreManagedAbsolutePaths(root) {
   const claude = PROJECT_MANAGED_CLAUDE_REL.map((rel) => claudePath(root, rel));
@@ -5662,6 +5843,11 @@ function summarizeLockDiff(before, after) {
 // src/update/lockfile.ts
 import { mkdir, readFile as readFile2, copyFile } from "node:fs/promises";
 import path34 from "node:path";
+async function readLockSummary(root) {
+  const lock = await readJson(hausPath(root, "haus.lock.json")) ?? [];
+  const catalogRef = lock.find((item) => item.catalogRef)?.catalogRef ?? null;
+  return { count: lock.length, catalogRef };
+}
 async function checkLock(root) {
   const lock = await readJson(hausPath(root, "haus.lock.json")) ?? [];
   const hasValidVersions = lock.every(
@@ -5725,6 +5911,10 @@ async function hasLocalOverrides(root) {
 var NPM_PACKAGE_NAME2 = "@haus-tech/haus-workflow";
 async function runUpdate(options) {
   const root = process.cwd();
+  if (options.fromHook) {
+    await runFromHookCheck(root);
+    return;
+  }
   if (options.check) {
     const pkgJson2 = await readJson(path35.join(packageRoot(), "package.json"));
     const currentVersion2 = pkgJson2?.version ?? "0.0.0";
@@ -5790,6 +5980,36 @@ async function runUpdate(options) {
   await refreshProjectFiles(root);
   log("Update applied with backup in .haus-workflow/backups/. Run haus doctor.");
 }
+async function runFromHookCheck(root) {
+  try {
+    const summary = await readLockSummary(root);
+    if (summary.count === 0) return;
+    const pkgJson = await readJson(path35.join(packageRoot(), "package.json"));
+    const currentVersion = pkgJson?.version ?? "0.0.0";
+    const [npmVersion, latestCatalogTag] = await Promise.all([
+      fetchNpmVersionStatus(currentVersion),
+      fetchLatestCatalogTag()
+    ]);
+    const installedRef = summary.catalogRef;
+    const catalogBehind = installedRef !== null && latestCatalogTag !== null && installedRef !== latestCatalogTag;
+    const npmBehind = npmVersion.updateAvailable && npmVersion.latest !== null;
+    if (!npmBehind && !catalogBehind) return;
+    const reasons = [];
+    if (npmBehind) reasons.push(`haus package ${currentVersion} \u2192 ${npmVersion.latest} available`);
+    if (catalogBehind) {
+      reasons.push(`catalog installed from ${installedRef}, latest is ${latestCatalogTag}`);
+    }
+    log(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "SessionStart",
+          additionalContext: `This project's haus setup is behind: ${reasons.join("; ")}. Suggest running \`/haus-workflow project:refresh\` to bring it up to date.`
+        }
+      })
+    );
+  } catch {
+  }
+}
 async function refreshProjectFiles(root) {
   log("Refreshing project .claude/ files...");
   try {
@@ -5838,7 +6058,6 @@ import path37 from "node:path";
 import fs29 from "node:fs";
 import path36 from "node:path";
 var ITEM_SEMVER_RE = /^\d+\.\d+\.\d+$/;
-var MANIFEST_SEMVER_RE = /^\d+\.\d+\.\d+(?:-[\w.-]+)?(?:\+[\w.-]+)?$/;
 function isSafeCatalogPath2(itemPath) {
   if (!itemPath || path36.isAbsolute(itemPath) || itemPath.includes("\\")) return false;
   const normalized = path36.normalize(itemPath);
@@ -5892,10 +6111,8 @@ function auditManifestStructure(manifestVersion, items) {
   const failures = [];
   const seenIds = /* @__PURE__ */ new Map();
   const seenPaths = /* @__PURE__ */ new Map();
-  if (typeof manifestVersion !== "string" || !MANIFEST_SEMVER_RE.test(manifestVersion)) {
-    failures.push(
-      'manifest.json: top-level "version" is not valid semver (expected X.Y.Z or X.Y.Z-pre)'
-    );
+  if (typeof manifestVersion !== "string" || !ITEM_SEMVER_RE.test(manifestVersion)) {
+    failures.push('manifest.json: top-level "version" is not valid semver (expected X.Y.Z)');
   }
   for (let i = 0; i < items.length; i++) {
     const item = items[i];
@@ -6868,7 +7085,7 @@ program.command("clone").description("Clone a single git repository by URL").arg
 program.command("refresh").action(runRefresh);
 program.command("catalog-audit").action(runCatalogAudit);
 program.command("validate-catalog").argument("[manifest]").action(runValidateCatalog);
-program.command("update").option("--check").action(runUpdate);
+program.command("update").option("--check").option("--from-hook", "Emit JSON for the Claude Code SessionStart hook (silent if up to date)").action(runUpdate);
 program.command("install").option("--dry-run").option("--force").option("--check", "Exit non-zero if any HAUS-MANAGED file is out of date").option("--postinstall", "Run by the npm postinstall hook; prints a plain-language change notice").action(runInstall);
 program.command("scaffold [ids...]").description(
   "Copy catalog config items (ESLint, Prettier) into the project root. Pass item IDs to scaffold specific items, or omit to scaffold all available config items."

package/library/catalog/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.2.0",
+  "version": "3.2.1",
   "items": [
     {
       "id": "haus.agentic-workflow-standard",
@@ -1754,7 +1754,7 @@
     },
     {
       "id": "haus.sentry-sentry-nestjs-sdk",
-      "version": "1.0.0",
+      "version": "1.0.1",
       "source": "curated",
       "type": "skill",
       "path": "skills/sentry/sentry-nestjs-sdk",
@@ -1773,8 +1773,8 @@
       "license": "MIT",
       "licenseConfidence": "high",
       "originSourceId": "getsentry-sentry-for-ai",
-      "originUrl": "https://github.com/getsentry/sentry-for-ai/blob/9ab3551758913a4144517d4fafb71476a48c64f8/skills/sentry-nestjs-sdk/SKILL.md",
-      "pinnedRef": "9ab3551758913a4144517d4fafb71476a48c64f8",
+      "originUrl": "https://github.com/getsentry/sentry-for-ai/blob/cc302403ebf647fd21c3ca736e1ec7ef6e4ed5a3/skills/sentry-nestjs-sdk/SKILL.md",
+      "pinnedRef": "cc302403ebf647fd21c3ca736e1ec7ef6e4ed5a3",
       "ecosystem": "sentry",
       "requiresAny": [
         {
@@ -1787,7 +1787,7 @@
     },
     {
       "id": "haus.sentry-sentry-nextjs-sdk",
-      "version": "1.0.1",
+      "version": "1.0.2",
       "source": "curated",
       "type": "skill",
       "path": "skills/sentry/sentry-nextjs-sdk",
@@ -1806,8 +1806,8 @@
       "license": "MIT",
       "licenseConfidence": "high",
       "originSourceId": "getsentry-sentry-for-ai",
-      "originUrl": "https://github.com/getsentry/sentry-for-ai/blob/bd84576db74e3e1d13361c7eda3bb303ae017b90/skills/sentry-nextjs-sdk/SKILL.md",
-      "pinnedRef": "bd84576db74e3e1d13361c7eda3bb303ae017b90",
+      "originUrl": "https://github.com/getsentry/sentry-for-ai/blob/cc302403ebf647fd21c3ca736e1ec7ef6e4ed5a3/skills/sentry-nextjs-sdk/SKILL.md",
+      "pinnedRef": "cc302403ebf647fd21c3ca736e1ec7ef6e4ed5a3",
       "ecosystem": "sentry",
       "requiresAny": [
         {
@@ -1820,7 +1820,7 @@
     },
     {
       "id": "haus.sentry-sentry-node-sdk",
-      "version": "1.0.1",
+      "version": "1.0.2",
       "source": "curated",
       "type": "skill",
       "path": "skills/sentry/sentry-node-sdk",
@@ -1839,8 +1839,8 @@
       "license": "MIT",
       "licenseConfidence": "high",
       "originSourceId": "getsentry-sentry-for-ai",
-      "originUrl": "https://github.com/getsentry/sentry-for-ai/blob/bd84576db74e3e1d13361c7eda3bb303ae017b90/skills/sentry-node-sdk/SKILL.md",
-      "pinnedRef": "bd84576db74e3e1d13361c7eda3bb303ae017b90",
+      "originUrl": "https://github.com/getsentry/sentry-for-ai/blob/cc302403ebf647fd21c3ca736e1ec7ef6e4ed5a3/skills/sentry-node-sdk/SKILL.md",
+      "pinnedRef": "cc302403ebf647fd21c3ca736e1ec7ef6e4ed5a3",
       "ecosystem": "sentry",
       "requiresAny": [
         {
@@ -1978,7 +1978,7 @@
     },
     {
       "id": "haus.stripe-stripe-best-practices",
-      "version": "1.0.2",
+      "version": "1.0.3",
       "source": "curated",
       "type": "skill",
       "path": "skills/stripe/stripe-best-practices",
@@ -1988,7 +1988,7 @@
       "whenNotToUse": "Do not use when a more specific skill or command applies.",
       "tags": ["workflow", "stripe", "payments"],
       "repoRoles": [],
-      "tokenEstimate": 7509,
+      "tokenEstimate": 1018,
       "installMode": "copy-selected",
       "default": false,
       "reviewStatus": "approved",
@@ -1997,8 +1997,8 @@
       "license": "MIT",
       "licenseConfidence": "medium",
       "originSourceId": "stripe-ai",
-      "originUrl": "https://github.com/stripe/ai/blob/7e7f72eb42e06f79e7bc75f86e9395f4c8232c00/skills/stripe-best-practices/SKILL.md",
-      "pinnedRef": "7e7f72eb42e06f79e7bc75f86e9395f4c8232c00",
+      "originUrl": "https://github.com/stripe/ai/blob/f54c9e6c0e8b6cfe4e648745eec68ecab3ddc994/skills/stripe-best-practices/SKILL.md",
+      "pinnedRef": "f54c9e6c0e8b6cfe4e648745eec68ecab3ddc994",
       "ecosystem": "stripe",
       "requiresAny": [
         {

package/library/global/skills/haus-workflow/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: haus-workflow
-description: Haus all-in-one workflow skill. Handles project setup, update, catalog refresh, and CLAUDE.md regeneration. Invoke with a task name or without to get a menu.
+description: Haus all-in-one workflow skill. Handles project setup, re-init, update, catalog refresh, health checks, and CLAUDE.md regeneration. Invoke with a task name or without to get a menu.
 ---
 
 # haus-workflow
 
-All-in-one entry point for the Haus AI workflow.
+All-in-one entry point for the Haus AI workflow. Everything haus-related runs through
+this skill — there are no separate `/haus-setup`, `/haus-clone`, `/haus-cloneandsetup`,
+`/haus-doctor`, or `/haus-fix` commands.
 
 ## Invocation
 
@@ -17,43 +19,56 @@ All-in-one entry point for the Haus AI workflow.
 
 Task names use an asymmetric scope convention. The **project:** namespace marks tasks that
 act on **this repo** (`./.claude`, `./.haus-workflow`) — type `project:` to see them all.
-The unprefixed verbs (`update`, `install`, `uninstall`) act on **this machine's
-haus install** (`~/.claude`, npm) — they manage the haus tool itself, like `npm install -g`.
-The short legacy aliases still work but the names below are canonical.
-
-| Task name (legacy aliases)                                        | Command                         | Scope   | What it does                                                                                                                                                                              |
-| ----------------------------------------------------------------- | ------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `project:init` (`setup`, `init`)                                  | _Setup procedure below_         | project | First-time setup of an **existing** repo: adds AI skills, commands, workflow + project docs                                                                                               |
-| `project:clone [name]` (`clone`)                                  | _Clone procedure below_         | project | No name: clone a **workspace**'s repos from `repos.manifest.json`. With a `name`: find & clone one repo by name from GitHub                                                               |
-| `project:cloneandsetup [name]` (`cloneandsetup`)                  | _Clone & setup procedure below_ | project | Run `project:clone`, then set up each repo for local dev — deps, databases, cross-repo links, and env — via each repo's `.haus-workflow/localdev.yml` (+ the workspace's order/links/env) |
-| `project:add-skills` (`add-skills`, `opt-in`)                     | _Add-skills procedure below_    | project | Add optional skills, agents, or config (ESLint/Prettier) to an already-set-up project without re-running full setup                                                                       |
-| `project:refresh` (`apply`, `refresh`, `claude-md`, `regenerate`) | `haus apply --write`            | project | Re-run setup / refresh `.claude/` context + regenerate root `CLAUDE.md` import block                                                                                                      |
-| `project:doctor` (`doctor`, `check`)                              | `haus doctor`                   | project | Check for install drift                                                                                                                                                                   |
-| `update` (`upgrade`)                                              | `haus update`                   | global  | Update npm package + catalog + `~/.claude/` (also refreshes this project)                                                                                                                 |
-| `install` (`global`)                                              | `haus install`                  | global  | Seed `~/.claude/` with haus-owned files                                                                                                                                                   |
-| `uninstall`                                                       | `haus uninstall`                | global  | Remove all haus global files from `~/.claude/`                                                                                                                                            |
+The unprefixed verbs (`update`, `install`, `uninstall`, `help`) act on **this machine's
+haus install** (`~/.claude`, npm) or are purely informational — they don't act on this
+repo's files. The short legacy aliases still work but the names below are canonical.
+
+| Task name (legacy aliases)                                        | Command                         | Scope   | What it does                                                                                                                                                                                                                                                                              |
+| ----------------------------------------------------------------- | ------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `project:init` (`setup`, `init`)                                  | _Setup procedure below_         | project | First-time setup of an **existing** repo: adds AI skills, commands, workflow + project docs                                                                                                                                                                                               |
+| `project:reinit` (`reinit`, `re-init`)                            | _Reinit procedure below_        | project | **Full re-setup.** Removes all haus-managed project files (backed up first, user content preserved), then re-runs `project:init` from scratch                                                                                                                                             |
+| `project:clone [name]` (`clone`)                                  | _Clone procedure below_         | project | No name: clone a **workspace**'s repos from `repos.manifest.json`. With a `name`: find & clone one repo by name from GitHub                                                                                                                                                               |
+| `project:cloneandsetup [name]` (`cloneandsetup`)                  | _Clone & setup procedure below_ | project | Run `project:clone`, then set up each repo for local dev — deps, databases, cross-repo links, and env — via each repo's `.haus-workflow/localdev.yml` (+ the workspace's order/links/env)                                                                                                 |
+| `project:add-skills` (`add-skills`, `opt-in`)                     | _Add-skills procedure below_    | project | Add optional skills, agents, or config (ESLint/Prettier) to an already-set-up project without re-running full setup                                                                                                                                                                       |
+| `project:refresh` (`apply`, `refresh`, `claude-md`, `regenerate`) | _Refresh procedure below_       | project | **Full non-destructive sync.** Updates the haus package + catalog first, then re-runs `project:init`'s pipeline in place — nothing is removed up front; new catalog items get added, changed ones updated, and anything removed upstream gets pruned by `apply`'s existing orphan-pruning |
+| `project:doctor` (`doctor`, `check`)                              | `haus doctor`                   | project | Check for install drift                                                                                                                                                                                                                                                                   |
+| `project:fix` (`fix`)                                             | _Fix procedure below_           | project | Diagnose and fix install drift: run doctor, apply the suggested fixes, confirm green                                                                                                                                                                                                      |
+| `update` (`upgrade`)                                              | `haus update`                   | global  | Update npm package + catalog + `~/.claude/`; if run inside an already-set-up project, fully refreshes it too (same pipeline as `project:refresh`)                                                                                                                                         |
+| `install` (`global`)                                              | `haus install`                  | global  | Seed `~/.claude/` with haus-owned files                                                                                                                                                                                                                                                   |
+| `uninstall`                                                       | `haus uninstall`                | global  | Remove all haus global files from `~/.claude/`                                                                                                                                                                                                                                            |
+| `help` (`?`)                                                      | _Answer directly below_         | —       | Explain what haus-workflow is, list available tasks, point to deeper docs — touches no files                                                                                                                                                                                              |
 
 ## Step 1 — Determine the task
 
 **If a task argument was passed:** look it up in the alias table above. If no match, tell the user and list valid options. If matched, skip to Step 2.
 
-**If no task was passed:** use `AskUserQuestion` to present this menu:
+**If no task was passed:** the menu has more options than one `AskUserQuestion` question can
+hold (max 4 options per question). Ask two separate questions, one after another — first
+Question 1, read the answer, then ask Question 2 (a second, sequential `AskUserQuestion`
+call; do not try to cram both into a single question):
 
 ```
-Question: "What would you like to do?"
+Question 1: "What would you like to do?"
 Options:
   1. [project] project:init — add haus to an existing project for the first time
      (AI skills + commands + workflow into a repo you already have, then a deep read to write the CLAUDE.md docs body + docs/)
-  2. [project] project:refresh — refresh this project's setup
-     (haus apply --write — re-runs setup, regenerates CLAUDE.md imports)
-  3. [global] update — update haus package + catalog + global files
-     (haus update — checks npm for new version, fetches catalog, refreshes ~/.claude/)
-  4. [project] project:clone [name] — clone repos
+  2. [project] project:refresh — full non-destructive sync with the latest haus
+     (updates the haus package + catalog, then re-runs setup in place — nothing removed first)
+  3. [project] project:clone [name] — clone repos
      (no name: clone a workspace from repos.manifest.json; with a name: find & clone one repo by name from GitHub)
-  5. [project] project:cloneandsetup [name] — clone repos, then set them up for local dev
+  4. [project] project:cloneandsetup [name] — clone repos, then set them up for local dev
      (project:clone, then per-repo deps + databases + cross-repo links + env from localdev.yml)
-  6. [project] project:add-skills — add optional skills, agents, or config to this project
+
+Question 2: "Anything else?"
+Options:
+  1. [project] project:add-skills — add optional skills, agents, or config to this project
      (offers opt-in helpers matching your stack that aren't installed yet — no full re-setup)
+  2. [project] project:reinit — full re-setup from scratch
+     (removes all haus-managed project files, backed up first, then re-runs project:init)
+  3. [global] update — update haus package + catalog + global files
+     (haus update — checks npm for new version, fetches catalog, refreshes ~/.claude/)
+  4. [—] help — explain what haus-workflow is and list all available tasks
+     (touches no files — points to docs/cli.md and docs/runbook.md for depth)
 ```
 
 Map the user's selection to the command from the alias table, then continue to Step 2.
@@ -64,28 +79,69 @@ Run the mapped command via Bash. Quote the exact command you are running before
 
 **Exception — `project:init` (`setup` / `init`):** this maps to a multi-step procedure, not a single command. Do not run a bare `haus init`. Skip to **Setup (`project:init`)** under Step 3 and follow it.
 
+**Exception — `project:reinit` (`reinit` / `re-init`):** removes files before re-running setup. Skip to **Reinit (`project:reinit`)** under Step 3 and follow it.
+
 **Exception — `project:clone` (`clone`):** this asks the user a question before running, so it is a short procedure too. Skip to **Clone (`project:clone`)** under Step 3 and follow it.
 
 **Exception — `project:cloneandsetup` (`cloneandsetup`):** clone followed by a per-repo setup pass, with confirmations. Skip to **Clone & setup (`project:cloneandsetup`)** under Step 3 and follow it.
 
 **Exception — `project:add-skills` (`add-skills` / `opt-in`):** a short scan → recommend → choose → apply procedure. Skip to **Add optional skills (`project:add-skills`)** under Step 3 and follow it.
 
+**Exception — `project:refresh` (`apply` / `refresh` / `claude-md` / `regenerate`):** updates the haus package first, then re-runs the setup pipeline — not a single command. Skip to **Refresh (`project:refresh`)** under Step 3 and follow it.
+
+**Exception — `project:fix` (`fix`):** diagnose-then-fix loop, not a single command. Skip to **Fix (`project:fix`)** under Step 3 and follow it.
+
+**Exception — `help` (`?`):** no command runs at all. Skip Step 2 and Step 3 — answer directly from the task alias table above, plus `docs/cli.md` and `docs/runbook.md` for deeper detail on any specific task.
+
 ## Step 3 — Post-run steps
 
 After the command completes, follow the relevant post-run steps below.
 
 ### Setup (`project:init`)
 
-1. Open and follow `~/.claude/commands/haus-setup.md` — the installed `haus-setup` command (in some projects also `.claude/commands/haus-setup.md`). Run every step in order. It detects the stack, runs `haus apply --write` (scaffolding, skills, commands, rules, docs skill), writes the **project docs** (`CLAUDE.md` body + `docs/`) and `.haus-workflow/deep-context.json`, runs `haus recommend`, applies the newly-matched helpers, and confirms.
+1. Open and follow `references/init.md` in this skill's directory. Run every step in order. It detects the stack, runs `haus apply --write` (scaffolding, skills, commands, rules, docs skill), writes the **project docs** (`CLAUDE.md` body + `docs/`) and `.haus-workflow/deep-context.json`, runs `haus recommend`, applies the newly-matched helpers, and confirms.
 2. Then fill `.haus-workflow/workflow-config.md` — replace every placeholder (`TODO`, `n/a`, empty): test/lint/typecheck/build commands (check `package.json`), docs paths, validation library, pre-commit tool, highest-stakes logic (ask if unclear). Leave none.
 
+### Reinit (`project:reinit`)
+
+Full re-setup — removes everything haus manages in this project and starts over. Use when
+the project's haus setup is badly out of sync and a plain `project:fix`/`project:refresh`
+isn't enough, or the user explicitly wants a clean slate.
+
+1. **Confirm first, always** — via `AskUserQuestion`. Explain plainly: this removes all
+   haus-managed files in this project (commands, skills, rules, workflow docs; `haus undo`
+   backs them up first and never touches user-owned `.claude/` content or `.haus-workflow`
+   docs you've edited), then re-runs setup from scratch. Offer **Cancel**.
+2. On confirm, run `haus undo --yes` (already backs up + preserves user content — no need
+   to ask a second time).
+3. Immediately follow **Setup (`project:init`)** above, end to end.
+4. Report what was removed, backed up (path), and re-added, in plain language.
+
+### Refresh (`project:refresh`)
+
+Full non-destructive sync — nothing is removed up front (contrast with `project:reinit`,
+which wipes first). Use for routine "bring this project up to date with the latest haus"
+maintenance: new catalog items get added, changed ones updated, and anything removed
+upstream gets pruned automatically by `apply`'s existing orphan-pruning.
+
+1. Run `haus update`. This bumps the npm package (or reports one's available), syncs the
+   catalog cache, refreshes `~/.claude/`, and does a light re-apply of this project's
+   already-tracked files. Apply the same reactions as **After `haus update`** below
+   (version-bump command, `WORKFLOW.md` update nudge, catalog-changes summary).
+2. Immediately follow **Setup (`project:init`)** above, end to end. Re-running it is safe
+   on an already-set-up project — it re-scans, re-applies, redoes the deep docs read (so
+   `CLAUDE.md`/`docs/` catch up with any code drift), and re-recommends against the
+   now-current catalog.
+3. Report what changed in plain language — package/catalog version bumps, docs
+   refreshed, helpers added/updated/removed.
+
 ### Clone (`project:clone`)
 
-1. Open and follow `~/.claude/commands/haus-clone.md` — the installed `haus-clone` command. With a `name` argument it finds and clones one matching repo from GitHub; with no argument it clones a workspace's repos from `repos.manifest.json`. This task only clones — to also install dependencies, use `project:cloneandsetup`.
+1. Open and follow `references/clone.md` in this skill's directory. With a `name` argument it finds and clones one matching repo from GitHub; with no argument it clones a workspace's repos from `repos.manifest.json`. This task only clones — to also install dependencies, use `project:cloneandsetup`.
 
 ### Clone & setup (`project:cloneandsetup`)
 
-1. Open and follow `~/.claude/commands/haus-cloneandsetup.md` — it runs the full `project:clone` flow, then sets up each cloned repo locally: selects the node version (`nvm install` from `.nvmrc`), enables corepack, installs JS/PHP dependencies, and seeds `.env`, confirming before each phase. It does not start servers.
+1. Open and follow `references/cloneandsetup.md` in this skill's directory — it runs the full `project:clone` flow, then sets up each cloned repo locally: selects the node version (`nvm install` from `.nvmrc`), enables corepack, installs JS/PHP dependencies, and seeds `.env`, confirming before each phase. It does not start servers.
 
 ### Add optional skills (`project:add-skills`)
 
@@ -112,27 +168,40 @@ choices.
 5. Confirm with the names added and their combined token estimate, e.g.
    "Added 2 optional helpers: Code review workflow, TDD workflow (~3k tokens)."
 
-### After `haus apply --write`
-
-Verify that the root `CLAUDE.md` imports all three haus files:
+### Fix (`project:fix`)
 
-```
-@.haus-workflow/WORKFLOW.md
-@.haus-workflow/workflow-config.md
-@.haus-workflow/project.md
-```
+1. Run `haus doctor` and read the verdict.
+2. If the project is already healthy, say so in one line and stop.
+3. Otherwise, for each item that needs attention, run the exact fix command the
+   doctor named (commonly `haus apply --write` or `haus apply --refill-config`).
+4. Re-run `haus doctor` to confirm the verdict is now green.
+5. Report what you changed in plain language — what was wrong, what you ran, and
+   that it's now resolved.
 
-If any import is missing, add it.
+Only run haus commands and the fixes the doctor suggests. If a fix needs a
+decision you can't make safely, stop and ask in plain language.
 
 ### After `haus update`
 
 1. If CLI output says a new version is available, run `npm i -g @haus-tech/haus-workflow` and confirm the version bump.
 2. If `WORKFLOW.md` was updated, remind the user: "WORKFLOW.md updated — review `workflow-config.md` for any new sections that need project-specific values."
 3. If CLI output shows catalog changes, summarise which templates changed.
-
-### After `haus doctor`
-
-Report findings clearly. For each drift item, suggest the exact fix command.
+4. **If the current directory has a `.haus-workflow/` folder** (this project was already
+   set up by haus), don't stop at the global update — continue immediately into
+   **Setup (`project:init`)** above to fully sync this project too (rescan, redo the deep
+   docs read, re-recommend, apply). This is what makes `update`'s scope note ("also
+   refreshes this project") literally true, not just a light lock-replay. No `.haus-workflow/`
+   folder → nothing more to do here, `update` only touched global files.
+
+### After `haus doctor` (`project:doctor`)
+
+1. Read the output. The first line is a plain-language verdict (green = healthy,
+   amber = things need attention).
+2. Relay that verdict to the person in one or two sentences. If anything needs
+   attention, list each item as a short sentence plus the exact command that
+   fixes it — and offer to run the fix for them (or suggest `project:fix`).
+
+Don't show raw command output unless they ask for detail.
 
 ### After `haus install` / `haus uninstall`
 

package/library/global/{commands/haus-clone.md → skills/haus-workflow/references/clone.md}

@@ -1,10 +1,8 @@
----
-description: Clone this project's repositories onto disk (per-repo setup is separate).
----
+# project:clone procedure
 
 Clone repositories for this project. Per-repo setup (install, Docker, `.env`) is a separate step that isn't wired yet — this command only gets repos onto disk.
 
-Cloning a single repo is always `haus clone <url> [dir]`. This command picks _which_ repos to clone and runs that primitive for each. There are two modes, chosen by whether a name was given.
+Cloning a single repo is always `haus clone <url> [dir]`. This procedure picks _which_ repos to clone and runs that primitive for each. There are two modes, chosen by whether a name was given.
 
 **Always ask before cloning — never assume.** The user may already have the repos on disk. Do not start cloning until they have confirmed. A missing `repos.local.json` does **not** mean they want a fresh clone; it just means nothing is recorded yet — you must still ask.
 

package/library/global/{commands/haus-cloneandsetup.md → skills/haus-workflow/references/cloneandsetup.md}

@@ -1,6 +1,4 @@
----
-description: Clone a project's repos and set each one up for local development.
----
+# project:cloneandsetup procedure
 
 Clone a project's repos **and** set each one up for local development — node version, dependencies, databases, cross-repo links, and env. This is `project:clone` followed by a per-repo setup pass and a localdev orchestration pass.
 
@@ -8,7 +6,7 @@ Clone a project's repos **and** set each one up for local development — node v
 
 ## Step 1 — Clone
 
-Run the full `project:clone` flow by following `~/.claude/commands/haus-clone.md` end to end (name → one repo; no name → workspace repos from `repos.manifest.json`). Carry the resulting repo list into Step 2.
+Run the full `project:clone` flow by following `references/clone.md` end to end (name → one repo; no name → workspace repos from `repos.manifest.json`). Carry the resulting repo list into Step 2.
 
 ## Step 2 — Prerequisite gate (one consolidated check)
 

package/library/global/{commands/haus-setup.md → skills/haus-workflow/references/init.md}

@@ -1,6 +1,4 @@
----
-description: Set up this project with haus, conversationally — no terminal needed.
----
+# project:init procedure
 
 Set up this project with haus, conversationally. The person you're helping may
 not be a developer — never make them open a terminal or read JSON. You run the
@@ -59,11 +57,18 @@ Do this in order:
 
 6. **Apply the rest.** Run `haus apply --write` again. It only writes what changed,
    so this adds the newly-matched helpers from step 4 plus any opt-ins from step 5.
+   Then verify the root `CLAUDE.md` imports all three haus files — add any missing:
+
+   ```
+   @.haus-workflow/WORKFLOW.md
+   @.haus-workflow/workflow-config.md
+   @.haus-workflow/project.md
+   ```
 
 7. **Confirm.** End with one plain-language line, for example:
    "✅ Your project is configured — I wrote your project docs, added N guardrails
    and M coding helpers (K matched after reading your code in depth), plus the J
-   optional helpers you chose: <name them>. Run `/haus-doctor` any time to
+   optional helpers you chose: <name them>. Run `/haus-workflow doctor` any time to
    re-check." Fill the numbers from the apply output, and name the opt-ins the
    user picked in step 5 (omit that clause if they chose none).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haus-tech/haus-workflow",
-  "version": "0.32.0",
+  "version": "1.0.0",
   "description": "Haus AI workflow CLI for Claude Code.",
   "type": "module",
   "bin": {
@@ -47,13 +47,13 @@
     "execa": "9.6.1",
     "fast-glob": "3.3.3",
     "fs-extra": "11.3.5",
-    "semver": "7.8.0",
+    "semver": "7.8.5",
     "yaml": "2.9.0"
   },
   "devDependencies": {
     "@release-it/conventional-changelog": "11.0.1",
     "@types/fs-extra": "11.0.4",
-    "@types/node": "22.19.17",
+    "@types/node": "22.20.0",
     "@types/semver": "7.7.1",
     "@typescript-eslint/eslint-plugin": "8.59.3",
     "@typescript-eslint/parser": "8.59.3",

package/library/global/commands/haus-doctor.md

@@ -1,14 +0,0 @@
----
-description: Check this project's haus setup health and explain it in plain language.
----
-
-Check the health of this project's haus setup and explain it in plain language.
-
-1. Run `haus doctor`.
-2. Read the output. The first line is a plain-language verdict (green = healthy,
-   amber = things need attention).
-3. Relay that verdict to the person in one or two sentences. If anything needs
-   attention, list each item as a short sentence plus the exact command that
-   fixes it — and offer to run the fix for them (or suggest `/haus-fix`).
-
-Don't show raw command output unless they ask for detail.

package/library/global/commands/haus-fix.md

@@ -1,16 +0,0 @@
----
-description: Diagnose and fix this project's haus setup.
----
-
-Diagnose and fix this project's haus setup.
-
-1. Run `haus doctor` and read the verdict.
-2. If the project is already healthy, say so in one line and stop.
-3. Otherwise, for each item that needs attention, run the exact fix command the
-   doctor named (commonly `haus apply --write` or `haus apply --refill-config`).
-4. Re-run `haus doctor` to confirm the verdict is now green.
-5. Report what you changed in plain language — what was wrong, what you ran, and
-   that it's now resolved.
-
-Only run haus commands and the fixes the doctor suggests. If a fix needs a
-decision you can't make safely, stop and ask in plain language.