worclaude 2.4.5 → 2.4.7

package/CHANGELOG.md

@@ -4,6 +4,44 @@ All notable changes to worclaude are documented in this file. Format loosely fol
 
 ## [Unreleased]
 
+## [2.4.7] — 2026-04-20
+
+Bug fix release — the learn-capture Stop hook writes `.claude/.stop-hook-active` as a runtime re-entry guard, but the scaffolded `.gitignore` never covered it. Every project scaffolded or upgraded to 2.4.6 saw a dirty `git status` right after the Stop hook fired. `worclaude delete` also left the now-stale line in `.gitignore`. Both are fixed symmetrically.
+
+### Fixed
+
+- `worclaude init` and `worclaude upgrade` now append `.claude/.stop-hook-active` to `.gitignore`. Pre-v2.4.7 installs pick up the missing entry on the next `upgrade`.
+- `worclaude delete` now removes the `.claude/.stop-hook-active` line from `.gitignore` alongside the other worclaude entries. `.claude-backup-*/` and `.claude/learnings/` remain intentionally preserved so personal/backup content stays ignored after uninstall.
+
+### Changed
+
+- `docs/reference/configuration.md` — gitignore entries reference now lists all 7 entries (previously out of date — missing `.claude/learnings/` too) with a one-line note on the stop-hook flag.
+
+## [2.4.6] — 2026-04-19
+
+Bug fix release — `worclaude upgrade` was silently no-oping when the installed and CLI versions matched, even when on-disk files were missing. `worclaude doctor` flagged drift, but the upgrade command refused to reconcile it. This release adds a drift-repair pass to `upgrade` and exposes new flags.
+
+### Fixed
+
+- `upgrade` now repairs on-disk drift (files listed in `workflow-meta.json` `fileHashes` but missing from disk) instead of pruning their hash entries. When versions match and drift exists, `upgrade` enters a "Repair-only" flow (preview → confirm → apply), version unchanged. When the installation is clean, behavior is unchanged — `Already up to date (vX.Y.Z)` and exit.
+- Hook scripts (`.claude/hooks/*.{cjs,js}`) and `AGENTS.md` (tracked as `root/AGENTS.md`) are now part of `buildTemplateHashMap`, so missing copies are detected and restored. Pre-v2.4.6 installs pick them up via the `newFiles` path on first upgrade. User-edited copies on disk with no corresponding `fileHashes` entry are preserved — a `.workflow-ref` sidecar is written instead of overwriting.
+- `.claude/learnings/` directory is re-created (with `.gitkeep`) when missing.
+- When `CLAUDE.md` lacks memory-architecture guidance keywords, `CLAUDE.md.workflow-ref.md` is written alongside with suggested additions. `CLAUDE.md` itself is never auto-modified.
+
+### Added
+
+- `worclaude upgrade --dry-run` — preview repair + template changes without writing.
+- `worclaude upgrade --yes` — skip confirmation prompts (useful in CI / scripted flows).
+- `worclaude upgrade --repair-only` — restore missing files without applying template updates, even when versions differ.
+- New `src/core/drift-checks.js` module (`hasClaudeMdMemoryGuidance`, `ensureLearningsDir`, `writeMemoryGuidanceSidecar`) shared by `doctor` and `upgrade` so keyword checks stay aligned.
+- New `src/core/variables.js` module — extracted `LANGUAGE_COMMANDS` / `buildCommandsBlock` from `init.js` and added `buildAgentsMdVariables(meta, projectRoot)` for repair flows. `init.js` now imports from it.
+
+### Changed
+
+- `categorizeFiles` now returns `missingExpected` and `missingUntracked` instead of a single `deleted` array. `diff.js` renders them as "Missing (will be restored by upgrade)" and "Deleted (removed in current version)" respectively. `upgrade.js` only prunes hashes for `missingUntracked`.
+- `doctor.js` `checkClaudeMdMemoryGuidance` now points users to the sidecar flow: `"Run worclaude upgrade to write a CLAUDE.md.workflow-ref.md sidecar with suggested additions."`
+- `computeFileHashes` now also hashes `AGENTS.md` at the project root (as `root/AGENTS.md`) so freshly-initialized projects track it from the start.
+
 ## [2.4.5] — 2026-04-19
 
 Internal CI tooling patch. No change to the scaffolded output or the npm package surface — `worclaude init` / `upgrade` produce identical output to 2.4.4.

package/README.md

@@ -122,7 +122,7 @@ claude --worktree --tmux
 | Command             | Description                                                 |
 | ------------------- | ----------------------------------------------------------- |
 | `worclaude init`    | Scaffold workflow into new or existing project              |
-| `worclaude upgrade` | Update universal components to the latest version           |
+| `worclaude upgrade` | Update universal components and repair on-disk drift        |
 | `worclaude status`  | Show current workflow state, version, and npm update status |
 | `worclaude backup`  | Create a timestamped backup of workflow files               |
 | `worclaude restore` | Restore from a previous backup                              |
@@ -130,7 +130,7 @@ claude --worktree --tmux
 | `worclaude delete`  | Remove worclaude workflow from project                      |
 | `worclaude doctor`  | Validate workflow installation health                       |
 
-The `init` command detects existing setups and merges intelligently — no data is overwritten without your confirmation. Use `upgrade` to pull in new features while preserving your customizations.
+The `init` command detects existing setups and merges intelligently — no data is overwritten without your confirmation. Use `upgrade` to pull in new features, restore missing files, and preserve your customizations. `upgrade` accepts `--dry-run`, `--yes`, and `--repair-only` for scripted flows.
 
 See the [full command reference](https://sefaertunc.github.io/Worclaude/reference/commands) for detailed usage and options.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worclaude",
-  "version": "2.4.5",
+  "version": "2.4.7",
   "description": "The Workflow Layer for Claude Code — scaffold agents, commands, skills, hooks, and memory into any project",
   "type": "module",
   "bin": {

package/src/commands/diff.js

@@ -32,10 +32,19 @@ export async function diffCommand() {
     display.newline();
   }
 
-  if (categories.deleted.length > 0) {
+  if (categories.missingExpected.length > 0) {
     hasChanges = true;
-    display.barLine(`${display.red('-')} Deleted (removed since install):`);
-    for (const { key } of categories.deleted) {
+    display.barLine(`${display.red('-')} Missing (will be restored by upgrade):`);
+    for (const { key } of categories.missingExpected) {
+      display.barLine(`  ${display.red(key)}`);
+    }
+    display.newline();
+  }
+
+  if (categories.missingUntracked.length > 0) {
+    hasChanges = true;
+    display.barLine(`${display.red('-')} Deleted (removed in current version):`);
+    for (const { key } of categories.missingUntracked) {
       display.barLine(`  ${display.red(key)}`);
     }
     display.newline();

package/src/commands/doctor.js

@@ -10,6 +10,7 @@ import {
   UNIVERSAL_SKILLS,
   TEMPLATE_SKILLS,
 } from '../data/agents.js';
+import { hasClaudeMdMemoryGuidance, readClaudeMd } from '../core/drift-checks.js';
 import * as display from '../utils/display.js';
 
 // Check categories
@@ -138,14 +139,6 @@ async function checkClaudeMd(projectRoot) {
 // Returns CLAUDE.md content or null when missing/unreadable. Missing-file
 // reporting is owned by checkClaudeMd — callers that use this helper should
 // skip reporting (return []) to avoid duplicate complaints.
-async function readClaudeMd(projectRoot) {
-  try {
-    return await readFile(path.join(projectRoot, 'CLAUDE.md'));
-  } catch {
-    return null;
-  }
-}
-
 async function checkClaudeMdSize(projectRoot) {
   const content = await readClaudeMd(projectRoot);
   if (content === null) return [];
@@ -201,23 +194,14 @@ async function checkClaudeMdLineCount(projectRoot) {
 async function checkClaudeMdMemoryGuidance(projectRoot) {
   const content = await readClaudeMd(projectRoot);
   if (content === null) return [];
-  const indicators = [
-    'memory architecture',
-    'native memory',
-    '.claude/learnings',
-    '[LEARN]',
-    '/learn',
-  ];
-  const lower = content.toLowerCase();
-  const hasGuidance = indicators.some((i) => lower.includes(i.toLowerCase()));
-  if (hasGuidance) {
+  if (hasClaudeMdMemoryGuidance(content)) {
     return [result(PASS, 'CLAUDE.md memory guidance', null)];
   }
   return [
     result(
       WARN,
       'CLAUDE.md memory guidance',
-      'CLAUDE.md has no memory architecture guidance. Auto-learnings may pollute this file. Run worclaude upgrade to add.'
+      'CLAUDE.md lacks memory-architecture guidance. Run worclaude upgrade to write a CLAUDE.md.workflow-ref.md sidecar with suggested additions.'
     ),
   ];
 }

package/src/commands/init.js

@@ -34,154 +34,10 @@ import {
   SPEC_MD_TEMPLATE_MAP,
 } from '../data/agents.js';
 import { buildAgentRoutingSkill } from '../generators/agent-routing.js';
+import { buildCommandsBlock } from '../core/variables.js';
 
 // --- Helper functions ---
 
-const LANGUAGE_COMMANDS = {
-  python: {
-    heading: 'Python',
-    commands: [
-      'python -m pytest                # Run tests',
-      'ruff check .                    # Lint',
-      'ruff format .                   # Format',
-    ],
-  },
-  node: {
-    heading: 'Node.js / TypeScript',
-    commands: [
-      'npm test                        # Run tests',
-      'npx eslint .                    # Lint',
-      'npx prettier --write .          # Format',
-    ],
-  },
-  java: {
-    heading: 'Java',
-    commands: [
-      'mvn test                        # Run tests',
-      'mvn checkstyle:check            # Lint',
-      'mvn spotless:apply              # Format',
-    ],
-  },
-  csharp: {
-    heading: 'C# / .NET',
-    commands: [
-      'dotnet test                     # Run tests',
-      'dotnet format --verify-no-changes # Lint',
-      'dotnet format                   # Format',
-    ],
-  },
-  cpp: {
-    heading: 'C / C++',
-    commands: [
-      'cmake --build build && ctest    # Build & test',
-      'clang-tidy src/*.cpp            # Lint',
-      'clang-format -i src/*.[ch]pp    # Format',
-    ],
-  },
-  go: {
-    heading: 'Go',
-    commands: [
-      'go test ./...                   # Run tests',
-      'golangci-lint run               # Lint',
-      'gofmt -w .                      # Format',
-    ],
-  },
-  php: {
-    heading: 'PHP',
-    commands: [
-      'vendor/bin/phpunit              # Run tests',
-      'vendor/bin/phpstan analyse      # Lint',
-      'vendor/bin/php-cs-fixer fix .   # Format',
-    ],
-  },
-  ruby: {
-    heading: 'Ruby',
-    commands: [
-      'bundle exec rspec               # Run tests',
-      'rubocop                         # Lint',
-      'rubocop -A                      # Format',
-    ],
-  },
-  kotlin: {
-    heading: 'Kotlin',
-    commands: [
-      'gradle test                     # Run tests',
-      'detekt                          # Lint',
-      'ktlint -F                       # Format',
-    ],
-  },
-  swift: {
-    heading: 'Swift',
-    commands: [
-      'swift test                      # Run tests',
-      'swiftlint                       # Lint',
-      'swift-format format -r . -i     # Format',
-    ],
-  },
-  rust: {
-    heading: 'Rust',
-    commands: [
-      'cargo test                      # Run tests',
-      'cargo clippy                    # Lint',
-      'cargo fmt                       # Format',
-    ],
-  },
-  dart: {
-    heading: 'Dart / Flutter',
-    commands: [
-      'dart test                       # Run tests',
-      'dart analyze                    # Lint',
-      'dart format .                   # Format',
-    ],
-  },
-  scala: {
-    heading: 'Scala',
-    commands: [
-      'sbt test                        # Run tests',
-      'sbt scalafix                    # Lint',
-      'scalafmt                        # Format',
-    ],
-  },
-  elixir: {
-    heading: 'Elixir',
-    commands: [
-      'mix test                        # Run tests',
-      'mix credo                       # Lint',
-      'mix format                      # Format',
-    ],
-  },
-  zig: {
-    heading: 'Zig',
-    commands: [
-      'zig build test                  # Run tests',
-      'zig build                       # Build (lint via compiler)',
-      'zig fmt .                       # Format',
-    ],
-  },
-};
-
-function buildCommandsBlock(languages, useDocker) {
-  const lines = ['```bash'];
-  for (const lang of languages) {
-    const entry = LANGUAGE_COMMANDS[lang];
-    if (!entry) continue;
-    if (lines.length > 1) lines.push('');
-    lines.push(`# ${entry.heading}`);
-    lines.push(...entry.commands);
-  }
-  if (useDocker) {
-    if (lines.length > 1) lines.push('');
-    lines.push('# Docker');
-    lines.push('docker compose up -d            # Start services');
-    lines.push('docker compose down             # Stop services');
-  }
-  if (lines.length === 1) {
-    lines.push('# Add your project-specific commands here');
-  }
-  lines.push('```');
-  return lines.join('\n');
-}
-
 // --- Step runner functions ---
 
 async function runProjectInfo(selections) {