@haus-tech/haus-workflow 0.32.1 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,159 @@
 # 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

package/dist/cli.js

@@ -1811,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) {
@@ -1910,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" }]
+      }
     ]
   }
 };
@@ -2414,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);
@@ -2441,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");
@@ -2461,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"),
@@ -2479,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
@@ -2781,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,
@@ -2917,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)}`
@@ -3927,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`,
@@ -5081,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");
@@ -5093,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));
       }
     }
   }
@@ -5534,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));
@@ -5778,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(
@@ -5841,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";
@@ -5906,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 {
@@ -6981,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/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.1",
+  "version": "1.0.0",
   "description": "Haus AI workflow CLI for Claude Code.",
   "type": "module",
   "bin": {

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.