worclaude 2.5.0 → 2.6.0

package/CHANGELOG.md

@@ -4,6 +4,71 @@ All notable changes to worclaude are documented in this file. Format loosely fol
 
 ## [Unreleased]
 
+## [2.6.0] — 2026-04-22
+
+Diagnose-first `/setup`. This release lands both halves of Phase Setup Diagnose in a single version: Part A (PR #103) ships the static project scanner and the new `worclaude scan` subcommand, and Part B (PR #104) rewrites `/setup` on top of it as a deterministic 12-state state machine with on-disk persistence, a tool-call whitelist, and a Claude-rendered selectable UI. Running `/setup` against a mature project now scans first (14 Tier 1 detectors produce a `DetectionReport`), presents the high-confidence facts as a numbered checklist for the user to confirm or uncheck, handles multi-candidate medium-confidence items (e.g., competing lockfiles), and only asks residual questions during the interview — cutting the interview from ~30 questions to whatever detection didn't cover. State survives interruption via `.claude/cache/setup-state.json`, persisted after every mutation through the new `worclaude setup-state` CLI (the sole write path `setup.md` is permitted to use under its tool whitelist). WRITE merges into existing output files conservatively: `CLAUDE.md` replaces `## Tech Stack` and `## Commands` sections by ATX heading; `SPEC.md` and SKILL files are rewritten only when template-only per CRLF-normalized SHA-256 match against `workflow-meta.json`, otherwise append a timestamped section; `PROGRESS.md` is append-only.
+
+### Added
+
+- **`worclaude scan` subcommand + detection engine** (PR #103, Part A) — new CLI subcommand that statically scans a project and produces a structured `DetectionReport` describing what it found. The report lands at `.claude/cache/detection-report.json` (machine-generated, gitignored, overwritten on every run). Ships 14 Tier 1 detectors under `src/core/project-scanner/detectors/` — one file per concern: `package-manager`, `language`, `frameworks`, `testing`, `linting`, `orm`, `deployment`, `ci`, `scripts`, `env-variables`, `external-apis`, `readme`, `spec-docs`, `monorepo`. Detector registration is directory-scan-based — adding a new detector means adding a new `.js` file, not editing the scanner. Each detector runs in parallel with a 5-second timeout; failures and timeouts are recorded in a per-report `errors` array without aborting the scan.
+- **CLI options for `scan`** (PR #103): `--path <dir>` (defaults to `process.cwd()`), `--json` (prints the full report to stdout, suppresses summary), `--quiet` (suppresses summary, still writes the cache file). Exit codes: `0` on any completed scan (even with per-detector errors), `1` on fatal errors (invalid path, un-writable cache).
+- **`pyproject.toml` dep flattening** (PR #103) — `frameworks`/`testing`/`linting`/`orm` detectors read all five dep locations (`[project.dependencies]`, `[project.optional-dependencies.*]`, `[tool.poetry.dependencies]`, `[tool.poetry.group.*.dependencies]`, `[dependency-groups.*]`) and flatten into a single map before matching. Fixtures exist for PEP 621, PEP 735, and Poetry-group layouts.
+- **Runtime dependencies** (PR #103): `smol-toml` (TOML parsing for `pyproject.toml`, `Cargo.toml`) and `yaml` (for `pnpm-workspace.yaml`, `Taskfile.yml`). Both are small, pure-JS, and zero-runtime-cost.
+- **`/setup` state machine rewrite** (PR #104, Part B) — `templates/commands/setup.md` is rewritten top-to-bottom as a 12-state state machine (`INIT → SCAN → CONFIRM_HIGH → CONFIRM_MEDIUM → INTERVIEW_STORY/ARCH/FEATURES/WORKFLOW/CONVENTIONS/VERIFICATION → WRITE → DONE`). `/setup` now invokes the Part A scanner at SCAN, presents detected facts via a Claude-rendered numbered checklist at CONFIRM_HIGH (user confirms or unchecks), handles multi-candidate medium-confidence items (`package-manager` with multiple lockfiles → numbered candidate list) at CONFIRM_MEDIUM, asks only residual questions during the six INTERVIEW states, and merge-writes the six output files at WRITE (CLAUDE.md is section-replaced by ATX heading, SPEC/SKILL files are rewritten only when template-only per CRLF-normalized SHA-256 match against `workflow-meta.json`, PROGRESS.md is append-only).
+- **`src/core/setup-state.js`** (PR #104) — persistence module for `.claude/cache/setup-state.json` (schemaVersion 1). Exports `loadSetupState`, `saveSetupState`, `clearSetupState`, `isSetupStateStale`, plus the `STATE_NAMES`, `QUESTION_IDS`, and `UNCHECKED_ROUTING` contract constants. Schema validation rejects unknown `currentState` values, `interviewAnswers` keys outside the QuestionId enumeration, mis-routed `<state>.unchecked.<field>` prefixes, and non-string answer values. `saveSetupState` preserves `startedAt` from an existing file across re-saves and refreshes `updatedAt` automatically.
+- **`worclaude setup-state` CLI subcommand** (PR #104) — four sub-subcommands: `show` (prints state JSON or `no state`), `save --stdin` (reads JSON from stdin, validates, persists — the ONLY mechanism `/setup` uses to write state), `reset` (idempotent delete), `resume-info` (pre-formatted `state: X, age: N unit(s), staleness: fresh|stale` line so Claude echoes rather than computes relative time). Exit codes: `0` success, `1` fatal, `2` invalid args.
+- **Anti-drift rules embedded in `setup.md`** (PR #104) — seven CRITICAL EXECUTION RULES pinned at the top of the command file. Sequential state advance only; no backward advance within an invocation; off-topic input triggers a restate, never an answer; `cancel setup` matches regex `/^(cancel|stop|abort)( setup)?[.!?\s]*$/i` and preserves state; tool use is whitelisted (scanner + `setup-state` CLI + two cache reads between SCAN and WRITE; the six target file reads/writes only at WRITE, plus `workflow-meta.json` for hash lookup); no memory pre-fill from prior sessions; prompts render verbatim in fenced code blocks, including state-machine control prose (resume preamble, back rejection, off-topic restate prefix, cancel acknowledgment).
+- **QuestionId enumeration** (PR #104) as the load-bearing `interviewAnswers` key contract (22 IDs across 6 INTERVIEW states) plus a `<state>.unchecked.<field>` prefix namespace for rejected high-confidence field re-asks, routed per a documented table (e.g., `scripts` rejected at CONFIRM_HIGH → re-asked in INTERVIEW_WORKFLOW under key `workflow.unchecked.scripts`).
+- **Field rendering table** reproduced in `setup.md` (PR #104) — the contract between detection report shapes and the human-readable value strings rendered at CONFIRM_HIGH and CONFIRM_MEDIUM. Mirrors `src/commands/scan.js:summarizeValue` semantics for all 14 detector fields plus the fallback scalar/array/object cases.
+
+### Changed
+
+- **`.gitignore` scaffolder** (PR #103) — `updateGitignore()` in `src/core/scaffolder.js` now writes `.claude/cache/` in addition to the existing seven entries. `cleanGitignore()` in `src/core/remover.js` removes the new entry on `worclaude delete`.
+- **`/setup` precondition** (PR #104) — `.claude/workflow-meta.json` must exist (canonical Worclaude init marker). Non-init'd projects get a clear "Run `worclaude init` first" message and exit, replacing the prior behavior of proceeding with undefined semantics.
+
+### Tests
+
+- **107 new scanner tests** (PR #103) across `tests/core/project-scanner/detectors/*.test.js` (14 files, 83 tests — positive, negative, and edge cases including multiple lockfiles, all four pyproject dep locations, quoted/prefixed env lines, monorepo with and without workspaces), `tests/core/project-scanner/index.test.js` (12 tests — happy path against six real fixtures, broken-detector and slow-detector handling via the `overrideDetectors` test seam, JSON round-trip), `tests/core/project-scanner/write-report.test.js` (7 tests), `tests/commands/scan.test.js` (5 tests — `--path`, `--json`, `--quiet`, cwd default, and exit-code-1 paths). 8 fixtures under `tests/fixtures/scanner/`: `nextjs-pnpm/`, `fastapi-poetry/`, `fastapi-pep621/`, `fastapi-pep735/`, `rust-cli/`, `monorepo-pnpm/`, `empty/`, `mixed-lockfiles/`.
+- **47 new setup-state tests** (PR #104) — `tests/core/setup-state.test.js` (24 unit tests covering load/save/clear/isStale happy paths, corrupt JSON, unsupported schemaVersion, unknown currentState, unknown interviewAnswers keys, mis-routed unchecked prefixes, startedAt preservation, updatedAt refresh, custom staleHours) and `tests/commands/setup-state.test.js` (23 CLI tests — four subcommands' happy and error paths, `save --stdin` round-trip with an in-process `inputStream` injection seam plus one end-to-end `spawnSync` smoke test, `resume-info` unit picking at minute/hour/day boundaries, invalid-arg exit 2). Total suite: **729/729 pass**.
+
+### Non-goals (explicitly deferred)
+
+- No `/setup --edit <field>` flow for correcting prior answers (Tier 2).
+- No automated state-machine test harness (mock-Claude driver walking every transition). Tier 2.
+- No automated end-to-end testing of `/setup` across fixture projects — manual e2e per the 13-case checklist in the phase prompt.
+- No schema migrator for `setup-state.json`. v1 policy is "reset on schema bump."
+- No architecture classification, directory-tree module inference, CI required-check detection (GitHub API), or monorepo sub-package scanning — all Tier 2.
+- No rename of the existing `src/core/detector.js` (scenario detection). The new scanner lives under `src/core/project-scanner/` to avoid name collision.
+
+## [2.5.1] — 2026-04-21
+
+Patch release fixing a user-visible bug found while dogfooding the v2.5.0 upgrade: reference-copy template files (the copies worclaude writes when your customized file and the shipped template both change) were being placed as `.workflow-ref.md` siblings next to the live file — including inside `.claude/commands/`, where Claude Code's command loader discovered them as phantom slash commands like `/sync.workflow-ref`, and inside `.claude/agents/`, where they could shadow live agents. Reference copies now live in a dedicated `.claude/workflow-ref/` tree that Claude Code does not scan. Installs upgrading from pre-v2.5.1 have their legacy reference files automatically relocated on the next `worclaude upgrade`.
+
+### Fixed
+
+- **Phantom slash commands from reference-copy siblings** (PR #101) — ref files are now written under `.claude/workflow-ref/<original-path>/` with the original filename preserved, instead of as `<name>.workflow-ref.md` siblings next to the live file. `.claude/commands/` and `.claude/agents/` are no longer polluted by `.workflow-ref` artifacts, so Claude Code's command and subagent loaders don't register them as live. `diff .claude/workflow-ref/commands/sync.md .claude/commands/sync.md` now reads cleanly.
+
+### Added
+
+- **`migrateWorkflowRefLocation()` in `src/core/migration.js`** (PR #101) — runs unconditionally at the start of every `worclaude upgrade`. Sweeps legacy `*.workflow-ref.md` siblings under `.claude/{commands,agents,skills}/` (plus root-level `CLAUDE.md.workflow-ref.md` and `AGENTS.md.workflow-ref`) into the new `.claude/workflow-ref/<original-path>/` tree. Idempotent (skips when target already exists, never overwrites). Scoped scan avoids re-stat'ing `.claude/sessions/` on every upgrade. Deliberately not version-gated — semver-gating this kind of cleanup migration creates a new bug class for users who downgrade then re-upgrade.
+- **Shared helpers in `src/core/file-categorizer.js`** (PR #101) — `WORKFLOW_REF_DIR` constant, `workflowRefRelPath(keyOrRelPath)` returning project-root-relative paths for `scaffoldFile`, `resolveRefPath(keyOrRelPath, projectRoot)` for absolute writes, and `isWorkflowRefFile(absPath, claudeDir)` predicate that unifies new-location-or-legacy-suffix detection so `status`, `doctor`, and `remover` stay in sync across the transition window.
+
+### Changed
+
+- **`worclaude upgrade` report output** (PR #101) — "Conflicts: N files (saved as .workflow-ref.md)" → "Conflicts: N files (saved under .claude/workflow-ref/)". New "Relocated: N legacy ref file(s) → .claude/workflow-ref/" line surfaces the one-time migration when it fires. Final hint reads "Review files under .claude/workflow-ref/ and merge what's useful."
+- **`worclaude init` and `worclaude status` output** (PR #101) — Scenario B conflict block, Next Steps, and Pending Review list all updated to reference the new location. Status continues to surface legacy `*.workflow-ref.md` siblings anywhere under `.claude/` so users upgrading from pre-v2.5.1 still see what they need to resolve before the next upgrade migrates them.
+- **`src/core/remover.js`** (PR #101) — the entire `.claude/workflow-ref/` subtree is classified as safe-to-delete on `worclaude delete`; the empty-subdir cleanup list extended to include `workflow-ref`.
+
+### Docs
+
+- **Upgrading guide** (PR #101) — 7 inline references updated plus a new "Upgrading from pre-v2.5.1 installs" subsection explaining what the automatic relocation does and how the skip-on-collision rule works.
+- **Existing-projects guide** (PR #101) — Tier 2 "Safe Alongside" section rewritten to describe the new `.claude/workflow-ref/` layout; post-merge report sample updated; the "Reviewing reference files" section now shows the clean `diff workflow-ref/commands/sync.md commands/sync.md` idiom.
+- **Commands reference, agents reference, SPEC.md, project-patterns skill** (PR #101) — all references to `.workflow-ref.md` sibling layout updated; `docs/spec/SPEC.md` edited on the feature branch as a shared-state override (PR #79 precedent: the SPEC update describes the very behavior the PR adds).
+
+### Tests
+
+- **Relocation migration coverage** (PR #101) — 8 new cases in `tests/core/migration.test.js` covering command/agent/skill subdir sweeps, root-level `CLAUDE.md.workflow-ref.md` / `AGENTS.md.workflow-ref` handling, target-collision skip behavior, idempotency on repeated runs, no-op on projects with files already at the new location, and clean-project no-ops. Regression assertions in `tests/commands/upgrade.test.js`, `tests/commands/init.test.js`, and `tests/core/merger.test.js` explicitly verify that `.workflow-ref.md` siblings are NEVER created inside `.claude/commands/` or `.claude/agents/`, so the phantom-command class of bug cannot silently return. 575/575 pass (567 prior + 8 new).
+
 ## [2.5.0] — 2026-04-21
 
 First release under the new per-PR bump declaration workflow. Shifts release mechanism from "every `/sync` publishes" to "every PR declares a bump, `/sync` aggregates, and only user-visible work ships." PR authors now declare `Version bump: {major|minor|patch|none}` in their PR body; `/sync` picks the highest declared bump since the last tag using precedence `major > minor > patch > none`. All-`none` batches update shared-state files on develop but never cut a release — internal-only work (docs, CI, tests) accumulates without triggering noisy publishes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worclaude",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "The Workflow Layer for Claude Code — scaffold agents, commands, skills, hooks, and memory into any project",
   "type": "module",
   "bin": {
@@ -68,7 +68,9 @@
     "commander": "^13.1.0",
     "fs-extra": "^11.3.0",
     "inquirer": "^12.5.0",
-    "ora": "^8.2.0"
+    "ora": "^8.2.0",
+    "smol-toml": "^1.6.1",
+    "yaml": "^2.8.3"
   },
   "devDependencies": {
     "eslint": "^9.22.0",

package/src/commands/doctor.js

@@ -11,7 +11,7 @@ import {
   TEMPLATE_SKILLS,
 } from '../data/agents.js';
 import { hasClaudeMdMemoryGuidance, readClaudeMd } from '../core/drift-checks.js';
-import { resolveKeyPath } from '../core/file-categorizer.js';
+import { resolveKeyPath, isWorkflowRefFile } from '../core/file-categorizer.js';
 import * as display from '../utils/display.js';
 
 // Check categories
@@ -202,7 +202,7 @@ async function checkClaudeMdMemoryGuidance(projectRoot) {
     result(
       WARN,
       'CLAUDE.md memory guidance',
-      'CLAUDE.md lacks memory-architecture guidance. Run worclaude upgrade to write a CLAUDE.md.workflow-ref.md sidecar with suggested additions.'
+      'CLAUDE.md lacks memory-architecture guidance. Run worclaude upgrade to write a sidecar under .claude/workflow-ref/CLAUDE.md with suggested additions.'
     ),
   ];
 }
@@ -828,10 +828,8 @@ async function checkPendingReviewFiles(projectRoot) {
     const claudeDir = path.join(projectRoot, '.claude');
     const allFiles = await listFilesRecursive(claudeDir);
     for (const fp of allFiles) {
-      const rel = path.relative(claudeDir, fp).split(path.sep).join('/');
-      if (rel.endsWith('.workflow-ref.md')) {
-        pending.push(rel);
-      }
+      if (!isWorkflowRefFile(fp, claudeDir)) continue;
+      pending.push(path.relative(claudeDir, fp).split(path.sep).join('/'));
     }
   } catch {
     // .claude dir might not exist

package/src/commands/init.js

@@ -528,7 +528,7 @@ function displayMergeReport(report, backupPath) {
     }
     if (report.added.skills.length > 0) {
       display.barLine(
-        `  ${display.green('✓')} ${report.added.skills.length} skills added${report.conflicts.skills.length > 0 ? ` (${report.conflicts.skills.length} conflicts saved as .workflow-ref.md)` : ''}`
+        `  ${display.green('✓')} ${report.added.skills.length} skills added${report.conflicts.skills.length > 0 ? ` (${report.conflicts.skills.length} conflicts saved under .claude/workflow-ref/)` : ''}`
       );
     }
     if (report.added.permissions > 0) {
@@ -549,10 +549,11 @@ function displayMergeReport(report, backupPath) {
     ...report.conflicts.commands,
   ];
   if (allConflicts.length > 0) {
-    display.barLine(`${display.yellow('~')} Conflicts (saved alongside for review):`);
+    display.barLine(
+      `${display.yellow('~')} Conflicts (template copy saved under .claude/workflow-ref/):`
+    );
     for (const file of allConflicts) {
-      const refName = file.replace('.md', '.workflow-ref.md');
-      display.barLine(`  ${display.yellow('⚠')} ${file} → ${refName}`);
+      display.barLine(`  ${display.yellow('⚠')} ${file}`);
     }
     display.newline();
   }
@@ -606,12 +607,14 @@ function displayMergeReport(report, backupPath) {
   display.divider('NEXT');
   display.newline();
   if (allConflicts.length > 0) {
-    console.log(`  ${display.white('1.')} Review .workflow-ref.md files and merge what's useful`);
+    console.log(
+      `  ${display.white('1.')} Review files under .claude/workflow-ref/ and merge what's useful`
+    );
   }
   if (report.claudeMdHandling === 'suggestions-generated') {
     console.log(`  ${display.white('2.')} Review CLAUDE.md.workflow-suggestions`);
     console.log(
-      `  ${display.white('3.')} Delete .workflow-ref.md and .workflow-suggestions files when done`
+      `  ${display.white('3.')} Delete .claude/workflow-ref/ and .workflow-suggestions when done`
     );
   }
   console.log(

package/src/commands/scan.js

@@ -0,0 +1,126 @@
+import path from 'node:path';
+import { scanProject, writeDetectionReport } from '../core/project-scanner/index.js';
+import * as display from '../utils/display.js';
+
+function truncate(text, max) {
+  if (text.length <= max) return text;
+  return text.slice(0, max - 1) + '…';
+}
+
+function summarizeValue(result) {
+  const { value, field } = result;
+
+  switch (field) {
+    case 'readme':
+      return truncate(value.projectDescription || '(no description extracted)', 80);
+    case 'ci': {
+      const n = value.workflows?.length || 0;
+      return `${value.provider}, ${n} workflow${n === 1 ? '' : 's'}`;
+    }
+    case 'testing':
+      return value.framework + (value.configFile ? ` (${value.configFile})` : '');
+    case 'scripts': {
+      const parts = [];
+      for (const key of ['dev', 'test', 'build', 'lint']) {
+        if (value[key]) parts.push(`${key}=${value[key].key}`);
+      }
+      return parts.join(' ') || '(no standard scripts)';
+    }
+    case 'envVariables':
+      return `${value.names.length} variables`;
+    case 'orm':
+      return value.name;
+    case 'monorepo':
+      return `${value.tool} (${value.packagePaths.length} packages)`;
+    case 'specDocs':
+      return `${value.length} doc${value.length === 1 ? '' : 's'}`;
+    case 'frameworks':
+      return value.map((v) => (v.version ? `${v.name} ${v.version}` : v.name)).join(', ');
+    default:
+      if (typeof value === 'string') return value;
+      if (Array.isArray(value)) return value.join(', ');
+      return JSON.stringify(value);
+  }
+}
+
+function formatField(field) {
+  return field.replace(/([A-Z])/g, ' $1').replace(/^./, (c) => c.toUpperCase());
+}
+
+function renderSummary(report, reportPath) {
+  const byConfidence = { high: [], medium: [], low: [] };
+  for (const r of report.results) {
+    byConfidence[r.confidence]?.push(r);
+  }
+
+  display.newline();
+  display.sectionHeader('WORCLAUDE SCAN');
+  display.dim(`Path: ${report.projectRoot}`);
+  display.newline();
+
+  for (const tier of ['high', 'medium', 'low']) {
+    const items = byConfidence[tier];
+    display.barLine(
+      display.white(`${tier[0].toUpperCase() + tier.slice(1)} confidence (${items.length})`)
+    );
+    if (items.length === 0) {
+      display.dim('(none)');
+    } else {
+      for (const item of items) {
+        const label = formatField(item.field).padEnd(20);
+        const summary = summarizeValue(item);
+        const source = item.source ? display.dimColor(`(${item.source})`) : '';
+        console.log(`  ${display.green('✓')} ${label} ${summary} ${source}`);
+      }
+    }
+    display.newline();
+  }
+
+  display.barLine(display.white(`Errors (${report.errors.length})`));
+  if (report.errors.length === 0) {
+    display.dim('(none)');
+  } else {
+    for (const err of report.errors) {
+      console.log(`  ${display.red('✗')} ${err.detector}: ${err.kind} — ${err.message}`);
+    }
+  }
+  display.newline();
+
+  display.success(
+    `Report written to ${path.relative(report.projectRoot, reportPath) || reportPath}`
+  );
+  display.newline();
+}
+
+export async function scanCommand(options = {}) {
+  const projectRoot = path.resolve(options.path || process.cwd());
+  const quiet = !!options.quiet;
+  const jsonMode = !!options.json;
+
+  let report;
+  try {
+    report = await scanProject(projectRoot);
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  let reportPath;
+  try {
+    reportPath = await writeDetectionReport(report, projectRoot);
+  } catch (err) {
+    console.error(`Error writing detection report: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (jsonMode) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  if (!quiet) {
+    renderSummary(report, reportPath);
+  }
+}

package/src/commands/setup-state.js

@@ -0,0 +1,113 @@
+import path from 'node:path';
+import { text } from 'node:stream/consumers';
+import {
+  loadSetupState,
+  saveSetupState,
+  clearSetupState,
+  isSetupStateStale,
+} from '../core/setup-state.js';
+
+function formatAge(updatedAtIso) {
+  const ageMs = Date.now() - Date.parse(updatedAtIso);
+  const minutes = Math.floor(ageMs / (60 * 1000));
+  if (minutes < 90) {
+    return `${minutes} minute${minutes === 1 ? '' : 's'}`;
+  }
+  const hours = Math.floor(ageMs / (60 * 60 * 1000));
+  if (hours < 48) {
+    return `${hours} hour${hours === 1 ? '' : 's'}`;
+  }
+  const days = Math.floor(ageMs / (24 * 60 * 60 * 1000));
+  return `${days} day${days === 1 ? '' : 's'}`;
+}
+
+async function runOrExit(fn, { errorPrefix = 'Error' } = {}) {
+  try {
+    await fn();
+  } catch (err) {
+    console.error(`${errorPrefix}: ${err.message}`);
+    process.exitCode = 1;
+  }
+}
+
+async function showSubcommand(projectRoot) {
+  await runOrExit(async () => {
+    const state = await loadSetupState(projectRoot);
+    if (state === null) {
+      console.log('no state');
+      return;
+    }
+    console.log(JSON.stringify(state, null, 2));
+  });
+}
+
+async function saveSubcommand(projectRoot, options) {
+  if (!options.stdin) {
+    console.error('Error: save requires --stdin');
+    process.exitCode = 2;
+    return;
+  }
+
+  const inputStream = options.inputStream || process.stdin;
+  let raw;
+  try {
+    raw = await text(inputStream);
+  } catch (err) {
+    console.error(`Error reading stdin: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    console.error(`Error: invalid JSON on stdin: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  await runOrExit(() => saveSetupState(projectRoot, parsed));
+}
+
+async function resetSubcommand(projectRoot) {
+  await runOrExit(() => clearSetupState(projectRoot));
+}
+
+async function resumeInfoSubcommand(projectRoot) {
+  await runOrExit(async () => {
+    const state = await loadSetupState(projectRoot);
+    if (state === null) {
+      console.log('no state');
+      return;
+    }
+    const age = formatAge(state.updatedAt);
+    const staleness = isSetupStateStale(state) ? 'stale' : 'fresh';
+    console.log(`state: ${state.currentState}, age: ${age}, staleness: ${staleness}`);
+  });
+}
+
+const SUBCOMMANDS = new Set(['show', 'save', 'reset', 'resume-info']);
+
+export async function setupStateCommand(subcommand, options = {}) {
+  if (!SUBCOMMANDS.has(subcommand)) {
+    console.error(
+      `Error: unknown subcommand: ${subcommand} (expected one of show, save, reset, resume-info)`
+    );
+    process.exitCode = 2;
+    return;
+  }
+
+  const projectRoot = path.resolve(options.path || process.cwd());
+
+  switch (subcommand) {
+    case 'show':
+      return showSubcommand(projectRoot);
+    case 'save':
+      return saveSubcommand(projectRoot, options);
+    case 'reset':
+      return resetSubcommand(projectRoot);
+    case 'resume-info':
+      return resumeInfoSubcommand(projectRoot);
+  }
+}

package/src/commands/status.js

@@ -3,6 +3,7 @@ import { requireWorkflowMeta, getPackageVersion } from '../core/config.js';
 import { hashFile } from '../utils/hash.js';
 import { fileExists, readFile, listFilesRecursive } from '../utils/file.js';
 import { getLatestNpmVersion } from '../utils/npm.js';
+import { isWorkflowRefFile } from '../core/file-categorizer.js';
 import { TECH_STACKS } from '../data/agents.js';
 import * as display from '../utils/display.js';
 
@@ -99,16 +100,17 @@ export async function statusCommand() {
     display.newline();
   }
 
-  // Pending review files
+  // Pending review files — anything isWorkflowRefFile() recognizes. That
+  // covers the v2.5.1+ .claude/workflow-ref/ tree plus legacy .workflow-ref.md
+  // siblings, so users mid-migration still see what they need to resolve.
   const pendingReview = [];
   try {
     const claudeDir = path.join(projectRoot, '.claude');
     const allFiles = await listFilesRecursive(claudeDir);
     for (const fp of allFiles) {
+      if (!isWorkflowRefFile(fp, claudeDir)) continue;
       const rel = path.relative(claudeDir, fp).split(path.sep).join('/');
-      if (rel.endsWith('.workflow-ref.md')) {
-        pendingReview.push(`.claude/${rel}`);
-      }
+      pendingReview.push(`.claude/${rel}`);
     }
   } catch {
     // .claude dir might not exist

package/src/commands/upgrade.js

@@ -5,7 +5,7 @@ import inquirer from 'inquirer';
 import ora from 'ora';
 import { requireWorkflowMeta, writeWorkflowMeta, getPackageVersion } from '../core/config.js';
 import { createBackup } from '../core/backup.js';
-import { categorizeFiles, resolveKeyPath } from '../core/file-categorizer.js';
+import { categorizeFiles, resolveKeyPath, resolveRefPath } from '../core/file-categorizer.js';
 import { buildSettingsJson, mergeSettingsPermissionsAndHooks } from '../core/merger.js';
 import { readTemplate, substituteVariables, updateGitignore } from '../core/scaffolder.js';
 import { buildAgentsMdVariables } from '../core/variables.js';
@@ -19,7 +19,12 @@ import { writeFile, readFile, fileExists } from '../utils/file.js';
 import { hashFile } from '../utils/hash.js';
 import { getLatestNpmVersion } from '../utils/npm.js';
 import * as display from '../utils/display.js';
-import { semverLessThan, migrateSkillFormat, patchAgentDescriptions } from '../core/migration.js';
+import {
+  semverLessThan,
+  migrateSkillFormat,
+  patchAgentDescriptions,
+  migrateWorkflowRefLocation,
+} from '../core/migration.js';
 
 const CONFLICT_CHECK_TYPES = new Set(['hook', 'root-file']);
 
@@ -41,12 +46,6 @@ function selfUpdate(latestVersion) {
   }
 }
 
-function sidecarPathFor(dest) {
-  const ext = path.extname(dest);
-  const base = ext ? dest.slice(0, dest.length - ext.length) : dest;
-  return `${base}.workflow-ref${ext}`;
-}
-
 async function renderTemplate({ templatePath, type }, variables) {
   const templateContent = await readTemplate(templatePath);
   return type === 'root-file' ? substituteVariables(templateContent, variables) : templateContent;
@@ -57,8 +56,8 @@ async function writeTemplateToDest(entry, dest, variables) {
   await writeFile(dest, await renderTemplate(entry, variables));
 }
 
-async function writeSidecarFor(entry, dest, variables) {
-  const sidecarPath = sidecarPathFor(dest);
+async function writeSidecarFor(entry, projectRoot, variables) {
+  const sidecarPath = resolveRefPath(entry.key, projectRoot);
   await writeFile(sidecarPath, await renderTemplate(entry, variables));
   return sidecarPath;
 }
@@ -122,7 +121,7 @@ function renderRepairPreview(plan) {
   }
   if (plan.claudeMdNeedsSidecar) {
     sidecarLines.push(
-      '  ~ CLAUDE.md memory guidance missing (will write CLAUDE.md.workflow-ref.md)'
+      '  ~ CLAUDE.md memory guidance missing (will write .claude/workflow-ref/CLAUDE.md sidecar)'
     );
   }
   if (sidecarLines.length > 0) {
@@ -197,7 +196,7 @@ async function applyRepairPass(projectRoot, plan, variables) {
     if (await fileExists(dest)) {
       const matches = await diskContentMatchesTemplate(entry, dest, variables);
       if (!matches) {
-        const sidecarPath = await writeSidecarFor(entry, dest, variables);
+        const sidecarPath = await writeSidecarFor(entry, projectRoot, variables);
         result.migrationConflicts.push({ key: entry.key, dest, sidecarPath });
         continue;
       }
@@ -282,7 +281,7 @@ async function runRepairOnlyFlow({ projectRoot, meta, plan, variables, dryRun, y
     }
     if (result.migrationConflicts.length > 0) {
       display.barLine(
-        `Conflicts:   ${result.migrationConflicts.length} files ${display.dimColor('(saved as .workflow-ref)')}`
+        `Conflicts:   ${result.migrationConflicts.length} files ${display.dimColor('(saved under .claude/workflow-ref/)')}`
       );
     }
     if (result.createdDirs.length > 0) {
@@ -295,7 +294,7 @@ async function runRepairOnlyFlow({ projectRoot, meta, plan, variables, dryRun, y
 
     if (result.migrationConflicts.length > 0 || result.sidecars.length > 0) {
       display.newline();
-      display.barLine(`Review .workflow-ref files and merge what's useful.`);
+      display.barLine(`Review files under .claude/workflow-ref/ and merge what's useful.`);
     }
   } catch (err) {
     spinner.fail('Repair failed.');
@@ -440,17 +439,25 @@ export async function upgradeCommand(options = {}) {
       spinner.start('Applying updates...');
     }
 
+    // v2.5.1 migration: relocate legacy ref files out of Claude-Code-scanned
+    // dirs. Runs unconditionally since it's idempotent and the fix applies
+    // to any project with legacy refs, regardless of source version.
+    const refRelocationReport = await migrateWorkflowRefLocation(projectRoot);
+    if (refRelocationReport.moved > 0) {
+      spinner.text = `Relocated ${refRelocationReport.moved} legacy ref file(s)...`;
+    }
+
     // Auto-update files
     for (const { key, templatePath } of categories.autoUpdate) {
       const content = await readTemplate(templatePath);
       await writeFile(resolveKeyPath(key, projectRoot), content);
     }
 
-    // Conflict files: save as .workflow-ref.md
+    // Conflict files: save under .claude/workflow-ref/ so they never collide
+    // with Claude Code's command/agent discovery.
     for (const { key, templatePath } of categories.conflict) {
       const content = await readTemplate(templatePath);
-      const refKey = key.replace(/\.md$/, '.workflow-ref.md');
-      await writeFile(resolveKeyPath(refKey, projectRoot), content);
+      await writeFile(resolveRefPath(key, projectRoot), content);
     }
 
     // New files (non-migration types handled here; migration types were
@@ -510,7 +517,7 @@ export async function upgradeCommand(options = {}) {
     }
     if (repairResult.migrationConflicts.length > 0) {
       display.barLine(
-        `Migration conflicts: ${repairResult.migrationConflicts.length} ${display.dimColor('(saved as .workflow-ref)')}`
+        `Migration conflicts: ${repairResult.migrationConflicts.length} ${display.dimColor('(saved under .claude/workflow-ref/)')}`
       );
     }
     if (categories.autoUpdate.length > 0) {
@@ -518,7 +525,12 @@ export async function upgradeCommand(options = {}) {
     }
     if (categories.conflict.length > 0) {
       display.barLine(
-        `Conflicts:   ${categories.conflict.length} files ${display.dimColor('(saved as .workflow-ref.md)')}`
+        `Conflicts:   ${categories.conflict.length} files ${display.dimColor('(saved under .claude/workflow-ref/)')}`
+      );
+    }
+    if (refRelocationReport.moved > 0) {
+      display.barLine(
+        `Relocated:   ${refRelocationReport.moved} legacy ref file(s) ${display.dimColor('→ .claude/workflow-ref/')}`
       );
     }
     if (plan.templateNewFiles.length > 0) {
@@ -558,7 +570,7 @@ export async function upgradeCommand(options = {}) {
       repairResult.sidecars.length > 0
     ) {
       display.newline();
-      display.barLine(`Review .workflow-ref files and merge what's useful.`);
+      display.barLine(`Review files under .claude/workflow-ref/ and merge what's useful.`);
     }
   } catch (err) {
     spinner.fail('Upgrade failed.');

package/src/core/drift-checks.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import fs from 'fs-extra';
 import { fileExists, readFile, writeFile } from '../utils/file.js';
+import { resolveRefPath } from './file-categorizer.js';
 
 export const MEMORY_GUIDANCE_KEYWORDS = [
   'memory architecture',
@@ -47,7 +48,7 @@ export function buildMemoryGuidanceSidecar() {
 }
 
 export async function writeMemoryGuidanceSidecar(projectRoot) {
-  const dest = path.join(projectRoot, 'CLAUDE.md.workflow-ref.md');
+  const dest = resolveRefPath('root/CLAUDE.md', projectRoot);
   await writeFile(dest, buildMemoryGuidanceSidecar());
   return dest;
 }

package/src/core/file-categorizer.js

@@ -36,6 +36,7 @@ export function isAlwaysScaffolded(entry, meta) {
 }
 
 export const ROOT_KEY_PREFIX = 'root/';
+export const WORKFLOW_REF_DIR = 'workflow-ref';
 
 export function resolveKeyPath(key, projectRoot) {
   if (key.startsWith(ROOT_KEY_PREFIX)) {
@@ -45,6 +46,43 @@ export function resolveKeyPath(key, projectRoot) {
   return path.join(projectRoot, '.claude', ...key.split('/'));
 }
 
+/**
+ * Project-root-relative path for a ref file. Useful for scaffoldFile() which
+ * takes a destRelativePath. Returns e.g. ".claude/workflow-ref/commands/sync.md".
+ * Accepts a workflow key ("commands/sync.md", "root/CLAUDE.md") or a plain
+ * relative path. Root-level files (CLAUDE.md, AGENTS.md) land directly
+ * under workflow-ref/, not under workflow-ref/root/.
+ */
+export function workflowRefRelPath(keyOrRelPath) {
+  const rel = keyOrRelPath.startsWith(ROOT_KEY_PREFIX)
+    ? keyOrRelPath.slice(ROOT_KEY_PREFIX.length)
+    : keyOrRelPath;
+  return path.join('.claude', WORKFLOW_REF_DIR, ...rel.split('/'));
+}
+
+/**
+ * Resolve an absolute ref file destination for a given relative path.
+ * Wraps workflowRefRelPath with projectRoot.
+ */
+export function resolveRefPath(keyOrRelPath, projectRoot) {
+  return path.join(projectRoot, workflowRefRelPath(keyOrRelPath));
+}
+
+/**
+ * Predicate for "is this file a reference copy?". Matches both the v2.5.1+
+ * layout (anywhere under .claude/workflow-ref/) and the legacy sibling
+ * convention (.workflow-ref.md suffix). Used by status, doctor, and remover
+ * so they stay in sync across the two location schemes.
+ *
+ * @param {string} absPath — absolute path on disk
+ * @param {string} claudeDir — absolute path to the project's .claude/ directory
+ */
+export function isWorkflowRefFile(absPath, claudeDir) {
+  const refDirPrefix = path.join(claudeDir, WORKFLOW_REF_DIR) + path.sep;
+  if (absPath.startsWith(refDirPrefix)) return true;
+  return absPath.endsWith('.workflow-ref.md');
+}
+
 /**
  * Build a map of all workflow template files to their hash keys, template paths, and hashes.
  * Hash keys match the format stored in workflow-meta.json (relative to .claude/).