worclaude 2.7.1 → 2.9.0

package/CHANGELOG.md

@@ -4,6 +4,77 @@ All notable changes to worclaude are documented in this file. Format loosely fol
 
 ## [Unreleased]
 
+## [2.9.0] — 2026-04-28
+
+Audit-driven workflow rebuild executing the canonical 7-phase plan derived from the 2026-04 master architecture audit, plus the @claude GitHub Action surface and post-phase polish. Phase 1 cleaned drift and gap-filled hooks. Phase 2 rebuilt the slash-command surface, retired three superseded commands, and split `/start`/`/end` into distinct forward-looking-handoff and backward-looking-session-summary artifacts with `sha:` frontmatter for SHA-based drift detection. Phase 3 made agent files the routing source of truth via a new frontmatter contract (`category`, `triggerType`, `whenToUse`, `whatItDoes`, `expectBack`, `situationLabel`) regenerated on every `/sync` and `worclaude upgrade`. Phase 4 introduced the memory-architecture skill and the `/update-claude-md` promotion algorithm. Phase 5 added the `worclaude doc-lint` subcommand. Phase 6a shipped end-to-end observability — capture, the `worclaude observability` aggregator, and the `/observability` slash command. Phase 7 added an `init` opt-in for the @claude GitHub Action workflow. Post-phase polish required explicit human invocation of `/commit-push-pr` or `/sync` for any git write (no more conversational "yes" authorizations) and extracted multi-line bash from three slash commands into POSIX helper scripts under `templates/scripts/` so each invocation matches a single allow rule. Test surface grew from 804/58 files to 947/69 files.
+
+### Added
+
+- **`worclaude observability` subcommand + `/observability` slash command** (PR #144) — aggregates per-session captured signals into a Markdown report; `/observability` surfaces it in-session.
+- **Observability capture infrastructure** (PR #143) — per-session signal capture wired into hooks; foundation that PR #144 reads from.
+- **Observability upgrade-path integration + VitePress docs** (PR #145) — existing installs pick up observability infra; new VitePress page documents the flow.
+- **`worclaude doc-lint` subcommand** (PR #142) — validates `<!-- references … -->` markers and surfaces tech-stack drift between code and prose; T5.9 of the canonical plan.
+- **`worclaude regenerate-routing` subcommand** (PR #137, T3.1 Path B) — rebuilds `.claude/skills/agent-routing/SKILL.md` from agent-file routing-fields frontmatter (`category`, `triggerType`, `whenToUse`, `whatItDoes`, `expectBack`, `situationLabel`). Preserves user prose outside `<!-- AUTO-GENERATED-START/END -->` markers. Auto-runs during `/sync` and `worclaude upgrade`. New `src/utils/agent-frontmatter.js` parser/validator and `src/generators/agent-routing.js` builder.
+- **`worclaude worktrees clean` subcommand** (PR #128) — removes stale agent worktrees left behind by Claude Code's worktree harness.
+- **`/sync` refreshes test/file metrics in CLAUDE.md and AGENTS.md** (PR #128) — fixes silent drift of `\d+ tests, \d+ files` claims.
+- **Default `sandbox.network.deniedDomains` in `templates/settings/base.json`** (PR #128) — opinionated baseline deny-list shipped to every fresh init.
+- **`e2e-runner` agent** (PR #130) — end-to-end test orchestration; new bundled agent.
+- **`Version bump:` enforcement in `/commit-push-pr`** (PR #131) — uses `AskUserQuestion` to demand a declaration on every PR; refuses to open without one.
+- **Session-lifecycle redesign** (PR #132) — `/start` and `/end` write distinct artifacts: handoff (forward-looking, `docs/handoffs/HANDOFF-{branch}-{date}.md`) vs session summary (backward-looking, `.claude/sessions/{YYYY-MM-DD-HHMM}-{branch}.md`). Both carry `sha:` frontmatter for drift detection. New `/learn` and `/update-claude-md` meta/memory commands.
+- **`.claude/scratch/` and `.claude/plans/` infrastructure** (PR #133) — five dependent commands (`/review-changes`, `/refactor-clean`, `/review-plan`, `/test-coverage`, `/observability`) write SHA-tagged artifacts that `/start` surfaces, distinguishing fresh from stale findings.
+- **T3.6 installation rationale + T3.8 drift detect surfaces** (PR #138) — exposes detection signals to slash commands.
+- **T3.9 optional features registry** (PR #139) — opt-in toggles for non-default flows surfaced through `init` and `upgrade`.
+- **Memory-architecture skill + `/update-claude-md` promotion algorithm** (PR #140) — five-layer memory model (CLAUDE.md, learnings, scratch, sessions, auto-memory). `/update-claude-md` reviews learnings and proposes targeted CLAUDE.md edits with diff preview.
+- **`@claude` GitHub Action surface via `init` opt-in** (PR #146) — scaffolds `.github/workflows/claude-code.yml` exposing the @claude bot; docs document the OIDC + token-exchange contract.
+- **POSIX helper scripts under `templates/scripts/`** (PR #151) — `start-drift.sh`, `sync-release-scope.sh`, `test-coverage-changed-files.sh` extract multi-line bash from `/start`, `/sync`, `/test-coverage` so each invocation matches a single allow rule. New `scaffoldScripts` function wired into Scenarios A/B/C (init, merger, upgrade flows). New `'script'` file class.
+- **Expanded `templates/settings/base.json` allow list** (PR #151) — `Bash(test:*)`, `Bash([:*)`, `Bash(bash:*)`, `WebFetch(domain:docs.anthropic.com|docs.claude.com|github.com|api.github.com)`, `WebSearch`, `Skill(update-config)`, `Skill(fewer-permission-prompts)` — closes the most common in-session permission-prompt fragmentation paths.
+- **CLAUDE.md Critical Rule #16** (PR #150) — commit/push/PR only when the human invokes `/commit-push-pr` or `/sync` explicitly. Conversational "yes" no longer authorizes git writes; agents refuse without a slash-command trigger.
+
+### Changed
+
+- ⚠ **PR #125 — 2026-04 master architecture audit + canonical 7-phase plan** — no `Version bump:` declaration (under-documented; treated as `none`). Pure docs landing into `docs/phases/`, `docs/archive/audits/2026-04/master-architecture-audit.md`, and `docs/archive/decisions/2026-04/`. Establishes the deliberation history that subsequent PRs execute against.
+- **Retired 3 slash commands** (PR #130) — superseded by other workflows; net slash-command count drops from 18 to 16.
+- **`/verify`, `/conflict-resolver`, `/build-fix` polished** (PR #131) — alongside the versioning enforcement work.
+- **BACKLOG.md is rolling** (PR #127) — single file, items removed when scheduled; no per-release archive, no version-suffixed BACKLOG files.
+- **Skill rewrite + hooks gap-fill** (PR #127) — every hook event documented in SPEC has a scaffolded handler; skills updated to current voice.
+
+### Fixed
+
+- **Misleading static test count in drift display** (PR #147) — `worclaude doc-lint` no longer reports a hard-coded test count when the actual count differs.
+- **Phase 1 PR A drift cleanup — text + agent metadata** (PR #126) — aligns scaffold-template prose and agent frontmatter with the routing-fields contract.
+
+### Tests
+
+- **947 tests across 69 files** (was 804/58 at v2.8.0 release). Net +143 tests across the seven phases.
+
+### Docs
+
+- **Comprehensive post-Phase-1-7 docs refresh** (PR #148) — counts, new commands, observability flow surfaced consistently across CLAUDE.md, README, VitePress site.
+- **Phase plans archived under `docs/archive/phases/`** (PR #149) — Phase 1, 2, 3, 4, 5, 6a, 7 deliberation history preserved post-execution.
+- **Phase 1 + Phase 2 retrospectives** (PRs #129, #134) — what landed vs what slipped, lessons forward.
+- **Phase 3 PR A — docs contracts T3.4/T3.5/T3.7** (PR #135) — PR template, drift-allowed sentinel, consequence lines.
+- **Phase 3 PR B — small wins T3.10/T3.11** (PR #136) — handoff TTL + `sha:` frontmatter dogfood across templates.
+- **Phase 5 PR A — SoT markers, SPEC ToC, PR template** (PR #141) — source-of-truth markers across templates.
+- **`docs/reference/permissions.md` — "Why prompts still fire" section** (PR #151) — env-var-prefix gotcha, multi-line fragmentation, pipes/redirects, the `additionalDirectories` directory-access layer, and pointer to Claude Code's built-in `/fewer-permission-prompts` skill.
+
+## [2.8.0] — 2026-04-24
+
+Fixes a long-standing agent worktree correctness bug. Both `claude --worktree` and the `Agent` tool's `isolation: "worktree"` option create their isolated checkout from `origin/HEAD` — which on most worclaude-convention repos resolves to `origin/main`. When the working branch (typically `develop`) is ahead of main (the normal state mid-release-cycle), agent worktrees get a stale checkout that misses recent commits, producing "missing develop files" symptoms easy to misattribute to tooling flakiness. This release ships two complementary fixes: a new `worclaude doctor` check that detects and warns on the at-risk configuration with a local, reversible remedy (`git remote set-head origin <branch>`), and a freshness preamble on the three bundled worktree agents (`bug-fixer`, `verify-app`, `test-writer`) that resets the worktree to match the parent's current branch regardless of `origin/HEAD`. Documentation in `subagent-usage` now correctly describes the harness behavior instead of the previous "creates a worktree from your current branch" claim.
+
+### Added
+
+- **`worclaude doctor` Git Integration / `origin/HEAD` divergence check** (PR #121) — warns when the current branch is ahead of `origin/HEAD`'s target, naming the branch and commit count. Suggests `git remote set-head origin <branch>` (local-only, reversible via `--auto` or `main`) as the fix. Skips silently outside a git repo or when `origin/HEAD` is unset. Shared `runGit(cwd, args)` helper added alongside for future checks to reuse the same spawn pattern.
+- **Worktree freshness preamble on `bug-fixer`, `verify-app`, `test-writer` agent templates** (PR #121) — on worktree start the agent runs `git fetch origin`, identifies the parent's current branch from `git worktree list --porcelain` (filtering out auto-named `worktree-agent-*` branches), then `git reset --hard "origin/${PARENT_BRANCH}"`. Protects correctness even when the user hasn't run `set-head`. LLM-driven parsing (no `awk`/`sed` pipelines) for cross-platform portability.
+
+### Changed
+
+- **`subagent-usage` skill (both `.claude/skills/subagent-usage/SKILL.md` and `templates/skills/universal/subagent-usage.md`)** (PR #121) — "How it works" item 1 corrected from "creates a worktree from your current branch" to "creates a worktree based on `origin/HEAD` (see gotcha below)". New "Base-branch gotcha" subsection cross-links to `worclaude doctor` and the `git remote set-head` remedy, and notes that the three bundled agents include a freshness preamble while other worktree agents do not.
+
+### Docs
+
+- **`docs/spec/SPEC.md` doctor section** (this /sync) — adds a `### Git Integration` subsection documenting both the gitignore coverage check and the new origin/HEAD divergence check.
+- **`docs/spec/PROGRESS.md`** (this /sync) — new v2.8.0 release entry; Stats refreshed (788 → 804 tests, 57 → 58 files).
+
 ## [2.7.1] — 2026-04-24
 
 Three `/setup` UX follow-ups from v2.7.0 confirmation testing, shipped as a single patch PR. The `?` / `help` trigger introduced in v2.7.0 turned out to collide with Claude Code's built-in keyboard-shortcut overlay (pressing `?` opens the shortcut panel before /setup's parser sees the keystroke); switched to the `help` keyword only. `worclaude init`'s `runOptionalExtras` was the only place in the init flow still using `inquirer type: 'confirm'` (rendered as `(y/N)`) — converted to `type: 'list'` arrow-key menus so every yes/no in init behaves consistently. CONFIRM_MEDIUM now invokes `AskUserQuestion` directly when the per-item option count fits the tool's `maxItems: 4` schema cap, with the consequence info ("Will be saved as") carried inside each option's `description` field; falls back to the verbatim text prompt (using `help` instead of `?`) when the count exceeds 4. CONFIRM_HIGH stays text-parse — detection lists routinely exceed 4 items. No consumer-visible schema or CLI surface additions.

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="assets/worclaude.png" alt="Worclaude — The Workflow Layer for Claude Code" width="100%" />
+  <img src="assets/banner.png" alt="Worclaude: The Workflow Layer for Claude Code" width="100%" />
 </p>
 
 <p align="center">
@@ -23,16 +23,16 @@
   <a href="https://github.com/sefaertunc/Worclaude/issues">Issues</a>
 </p>
 
-# Worclaude — The Workflow Layer for Claude Code
+# Worclaude: The Workflow Layer for Claude Code
 
-Worclaude scaffolds a complete Claude Code workflow into any project in seconds. One `init` command installs 26 agents, 18 slash commands, 16 skills, 8 lifecycle hooks, a two-store memory system, and a CLAUDE.md template tuned for your tech stack. It implements the patterns in [howborisusesclaudecode.com](https://www.howborisusesclaudecode.com/) as a reusable, upgradable scaffold, so you stop rebuilding the same configuration for every new project.
+Worclaude scaffolds a complete Claude Code workflow into any project in seconds. One `init` command installs 25 agents, 16 slash commands, 17 skills, an 11-event hook layer, local observability capture, a five-layer memory system, and a CLAUDE.md template tuned for your tech stack. It implements the patterns in [howborisusesclaudecode.com](https://www.howborisusesclaudecode.com/) as a reusable, upgradable scaffold, so you stop rebuilding the same configuration for every new project.
 
 <div align="center">
 
-| CLI Commands |          Agents           | Slash Commands |        Skills         |      Hooks       |  Tech Stacks  |
-| :----------: | :-----------------------: | :------------: | :-------------------: | :--------------: | :-----------: |
-|      8       | 6 universal + 20 optional |       18       |          16           |     8 events     |      16       |
-| subcommands  |    across 6 categories    | session tools  | universal + templates | lifecycle events | auto-detected |
+| CLI Commands |          Agents           | Slash Commands |        Skills         |     Hooks      |  Tech Stacks  |
+| :----------: | :-----------------------: | :------------: | :-------------------: | :------------: | :-----------: |
+|      14      | 6 universal + 19 optional |       16       |          17           |   11 events    |      16       |
+| subcommands  |    across 6 categories    | session tools  | universal + templates | 7 hook scripts | auto-detected |
 
 </div>
 
@@ -42,42 +42,52 @@ Worclaude scaffolds a complete Claude Code workflow into any project in seconds.
 
 `worclaude init` installs a production-ready Claude Code workflow:
 
-### Agents (26 total)
+### Agents (25 total)
 
 - **6 universal:** plan-reviewer (Opus), code-simplifier (Sonnet, worktree), test-writer (Sonnet, worktree), build-validator (Haiku), verify-app (Sonnet, worktree), upstream-watcher (Sonnet)
-- **20 optional** across 6 categories — Backend, Frontend, DevOps, Quality, Documentation, Data/AI. Worclaude recommends agents based on your project type.
+- **19 optional** across 6 categories: Backend, Frontend, DevOps, Quality, Documentation, Data/AI. Worclaude recommends agents based on your project type.
 
-### Slash Commands (18)
+### Slash Commands (16)
 
-Session lifecycle, review, verification, memory, upstream awareness, and git automation:
+Session lifecycle, review, verification, memory, observability, and git automation:
 
-`/start` `/end` `/commit-push-pr` `/review-plan` `/techdebt` `/verify` `/compact-safe` `/status` `/update-claude-md` `/learn` `/setup` `/sync` `/conflict-resolver` `/review-changes` `/build-fix` `/refactor-clean` `/test-coverage` `/upstream-check`
+`/start` `/end` `/commit-push-pr` `/review-plan` `/verify` `/compact-safe` `/update-claude-md` `/learn` `/setup` `/sync` `/conflict-resolver` `/review-changes` `/build-fix` `/refactor-clean` `/test-coverage` `/observability`
 
-### Skills (16)
+### Skills (17 total)
 
-- **12 universal** — context-management, git-conventions, planning-with-files, review-and-handoff, prompt-engineering, verification, testing, claude-md-maintenance, coding-principles, subagent-usage, security-checklist, coordinator-mode
-- **3 project templates** filled in automatically by `/setup` — backend-conventions, frontend-design-system, project-patterns
-- **1 generated** — agent-routing, dynamically built from your agent selections
+- **13 universal**: context-management, git-conventions, planning-with-files, review-and-handoff, prompt-engineering, verification, testing, claude-md-maintenance, coding-principles, subagent-usage, security-checklist, coordinator-mode, memory-architecture
+- **3 project templates** filled in automatically by `/setup`: backend-conventions, frontend-design-system, project-patterns
+- **1 generated**: agent-routing, dynamically built from your agent selections
 
 Skills use Claude Code's directory format (`skill-name/SKILL.md`) and support **conditional activation** via path globs, so Claude only carries knowledge relevant to the current file.
 
-### Hooks (8 lifecycle events)
+### Hooks (11 events, 7 hook scripts)
 
-Worclaude scaffolds hooks across the full Claude Code lifecycle:
+Worclaude scaffolds 14 hook entries across 11 Claude Code events:
 
-- **SessionStart** — auto-loads CLAUDE.md, PROGRESS.md, last session summary, and recent learnings
-- **PostToolUse** — auto-formats code after every edit, using the right formatter for your stack
-- **PostCompact** — re-reads key files after context compaction so Claude stays oriented
-- **PreCompact** — emergency git snapshot before auto-compaction
-- **UserPromptSubmit** — detects correction signals and suggests skills based on prompt content
-- **Stop** — extracts `[LEARN]` blocks from the transcript and persists them to disk
-- **SessionEnd / Notification** — quiet-by-default session-end and desktop alerts
+- **SessionStart**: auto-loads CLAUDE.md, PROGRESS.md, last session summary, and recent learnings
+- **PostToolUse**: auto-formats code after every edit (formatter chosen by stack); strict profile adds a TypeScript check
+- **PostCompact**: re-reads key files after context compaction so Claude stays oriented
+- **PreCompact**: emergency git snapshot before auto-compaction (`pre-compact-save.cjs`)
+- **UserPromptSubmit**: three handlers run in sequence (correction-detection, skill-hint matching, and command-invocation observability capture)
+- **Stop**: extracts `[LEARN]` blocks from the transcript and persists them (`learn-capture.cjs`)
+- **InstructionsLoaded**: captures skill loads to `.claude/observability/skill-loads.jsonl` (`obs-skill-loads.cjs`)
+- **SubagentStart / SubagentStop**: captures agent invocations to `.claude/observability/agent-events.jsonl` (`obs-agent-events.cjs`)
+- **SessionEnd / Notification**: quiet-by-default session-end and desktop alerts
 
-Three profiles via `WORCLAUDE_HOOK_PROFILE`: `minimal` (context hooks only), `standard` (all hooks, default), `strict` (standard + TypeScript checking on every edit).
+Three profiles via `WORCLAUDE_HOOK_PROFILE`: `minimal` (context hooks only; disables observability and notifications), `standard` (all hooks, default), `strict` (standard + TypeScript checking on every edit).
+
+### Observability
+
+A privacy-first per-project signal layer captures skill loads, command invocations, and agent timings to `.claude/observability/*.jsonl` (gitignored). The `worclaude observability` CLI and `/observability` slash command aggregate the signals into a Markdown report: top skills, top commands, agent failure rates, and anomalies. Zero data leaves the machine; opt out via `WORCLAUDE_HOOK_PROFILE=minimal` or by deleting the folder.
+
+### GitHub Action Integration
+
+When `worclaude init` finishes it offers to surface Claude Code's `/install-github-action` flow. If installed, `@claude` mentions in PR comments will automatically propose CLAUDE.md updates, slotting cleanly into the `/sync`-driven release flow. Worclaude itself never shells out to the install command; it just points you at it.
 
 ### Learnings System
 
-A personal, gitignored store at `.claude/learnings/` captures corrections and rules Claude picks up mid-session and replays them at the start of future sessions. The `correction-detect.cjs` and `learn-capture.cjs` hooks do this automatically; the `/learn` slash command is the explicit capture path. Unlike CLAUDE.md (shared rules, in git), learnings are yours — useful for personal conventions that should not leak into the repo. Promote a learning to CLAUDE.md when it matures into something every contributor should follow.
+A personal, gitignored store at `.claude/learnings/` captures corrections and rules Claude picks up mid-session and replays them at the start of future sessions. The `correction-detect.cjs` and `learn-capture.cjs` hooks do this automatically; the `/learn` slash command is the explicit capture path. Unlike CLAUDE.md (shared rules, in git), learnings are yours; useful for personal conventions that should not leak into the repo. Promote a learning to CLAUDE.md when it matures into something every contributor should follow.
 
 ### Cross-Tool Compatibility
 
@@ -119,18 +129,24 @@ claude --worktree --tmux
 
 ## Commands
 
-| Command             | Description                                                 |
-| ------------------- | ----------------------------------------------------------- |
-| `worclaude init`    | Scaffold workflow into new or existing project              |
-| `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                              |
-| `worclaude diff`    | Compare current setup vs latest template                    |
-| `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, restore missing files, and preserve your customizations. `upgrade` accepts `--dry-run`, `--yes`, and `--repair-only` for scripted flows.
+| Command                        | Description                                                              |
+| ------------------------------ | ------------------------------------------------------------------------ |
+| `worclaude init`               | Scaffold workflow into new or existing project                           |
+| `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                                           |
+| `worclaude diff`               | Compare current setup vs latest template                                 |
+| `worclaude delete`             | Remove worclaude workflow from project                                   |
+| `worclaude doctor`             | Validate workflow installation health                                    |
+| `worclaude doc-lint`           | Validate `<!-- references … -->` markers; surface tech-stack drift       |
+| `worclaude observability`      | Aggregate per-project signals into a Markdown report (`--json`, `--out`) |
+| `worclaude regenerate-routing` | Rebuild `agent-routing/SKILL.md` from `templates/agents/`                |
+| `worclaude scan`               | Detect project type/stack via the project-scanner detectors              |
+| `worclaude setup-state`        | Inspect / save / reset / resume `/setup` interview persistence           |
+| `worclaude worktrees clean`    | Remove stale agent worktrees (locked or orphaned)                        |
+
+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. `doctor` accepts `--json` for CI dashboards. `doc-lint` accepts `--strict` to exit non-zero on drift (CI-friendly).
 
 See the [full command reference](https://sefaertunc.github.io/Worclaude/reference/commands) for detailed usage and options.
 
@@ -139,11 +155,11 @@ See the [full command reference](https://sefaertunc.github.io/Worclaude/referenc
 ## Why Worclaude
 
 - **Split architecture.** CLAUDE.md stays under 200 lines for speed; detail lives in skills loaded on demand. Personal rules live in `.claude/learnings/` (gitignored); shared rules live in CLAUDE.md.
-- **Learning loop.** Correct Claude once, it captures the rule, the next session picks it up at start — no re-stating.
+- **Learning loop.** Correct Claude once, it captures the rule, the next session picks it up at start; no re-stating.
 - **Cross-tool ready.** `AGENTS.md` generated from the same source as CLAUDE.md, so your rules work in Cursor / Codex / Copilot too.
 - **Hook profiles.** Dial strictness up or down via one environment variable. `minimal` for CI, `standard` for daily work, `strict` for type-heavy projects.
-- **Smart merge.** Detects existing Claude Code setups and merges additively — existing files never overwritten without confirmation. Three-tier strategy: additive for missing content, safe-alongside for conflicts, interactive for CLAUDE.md.
-- **Self-healing doctor.** Catches drift, stale hashes, deprecated models, broken learnings — before they bite.
+- **Smart merge.** Detects existing Claude Code setups and merges additively; existing files never overwritten without confirmation. Three-tier strategy: additive for missing content, safe-alongside for conflicts, interactive for CLAUDE.md.
+- **Self-healing doctor.** Catches drift, stale hashes, deprecated models, broken learnings; before they bite.
 - **Batched releases.** Every PR declares `Version bump: {major|minor|patch|none}` in its body; `/sync` aggregates declarations across merged PRs and only cuts a release when at least one rises above `none`. Internal-only work (docs, CI, tests) accumulates on `develop` without triggering noisy publishes.
 
 ---
@@ -152,25 +168,25 @@ See the [full command reference](https://sefaertunc.github.io/Worclaude/referenc
 
 Worclaude draws from patterns and insights across the Claude Code ecosystem:
 
-- [Boris Cherny's Claude Code tips](https://howborisusesclaudecode.com/) — The foundational workflow patterns: multi-terminal pipelines, plan-then-execute, CLAUDE.md as shared knowledge, verification-first development
-- [everything-claude-code](https://github.com/affaan-m/everything-claude-code) by Affaan Mir (Anthropic hackathon winner) — Session persistence, hook profiles, confidence filtering, security scanning patterns
-- [Andrej Karpathy's coding principles](https://github.com/multica-ai/andrej-karpathy-skills) — Think before coding, simplicity first, surgical changes ([original post](https://x.com/karpathy/status/2015883857489522876))
-- [pro-workflow](https://github.com/peterHoburg/pro-workflow) — Correction detection, learning capture hooks, loop prevention patterns
-- [Anthropic Engineering Blog](https://www.anthropic.com/engineering) — Agent design, context engineering, harness patterns
-- [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) by hesreallyhim — Community resource discovery and ecosystem awareness
-- [awesome-claude-code-toolkit](https://github.com/rohitg00/awesome-claude-code-toolkit) by rohitg00 — Toolkit patterns and companion app references
-- [claude-skills-cli](https://github.com/anthropics/skills) — Skill activation patterns and conditional loading insights
-- [SuperClaude](https://github.com/andyholst/SuperClaude) — Persona and mode system analysis (informed what NOT to build)
-- [ccusage](https://github.com/yashikota/ccusage) / [claude-devtools](https://github.com/nicobailey/claude-devtools) — Observability patterns (informed what NOT to build)
-- [claude-flow](https://github.com/Ruflo/claude-flow) by Ruflo — Runtime orchestration patterns (informed the scaffolding-only philosophy)
-- [Vercel SkillKit](https://github.com/vercel/skillkit) — Skill packaging and marketplace patterns
-- [claude-code-templates](https://github.com/danielsalas/claude-code-templates) by Daniel Avila — Template gallery and component catalog reference
+- [Boris Cherny's Claude Code tips](https://howborisusesclaudecode.com/): The foundational workflow patterns: multi-terminal pipelines, plan-then-execute, CLAUDE.md as shared knowledge, verification-first development
+- [everything-claude-code](https://github.com/affaan-m/everything-claude-code) by Affaan Mir (Anthropic hackathon winner): Session persistence, hook profiles, confidence filtering, security scanning patterns
+- [Andrej Karpathy's coding principles](https://github.com/multica-ai/andrej-karpathy-skills): Think before coding, simplicity first, surgical changes ([original post](https://x.com/karpathy/status/2015883857489522876))
+- [pro-workflow](https://github.com/peterHoburg/pro-workflow): Correction detection, learning capture hooks, loop prevention patterns
+- [Anthropic Engineering Blog](https://www.anthropic.com/engineering): Agent design, context engineering, harness patterns
+- [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) by hesreallyhim: Community resource discovery and ecosystem awareness
+- [awesome-claude-code-toolkit](https://github.com/rohitg00/awesome-claude-code-toolkit) by rohitg00: Toolkit patterns and companion app references
+- [claude-skills-cli](https://github.com/anthropics/skills): Skill activation patterns and conditional loading insights
+- [SuperClaude](https://github.com/andyholst/SuperClaude): Persona and mode system analysis (informed what NOT to build)
+- [ccusage](https://github.com/yashikota/ccusage) / [claude-devtools](https://github.com/nicobailey/claude-devtools): Observability patterns (informed what NOT to build)
+- [claude-flow](https://github.com/Ruflo/claude-flow) by Ruflo: Runtime orchestration patterns (informed the scaffolding-only philosophy)
+- [Vercel SkillKit](https://github.com/vercel/skillkit): Skill packaging and marketplace patterns
+- [claude-code-templates](https://github.com/danielsalas/claude-code-templates) by Daniel Avila: Template gallery and component catalog reference
 
 ---
 
 ## Links
 
-- [Full Documentation](https://sefaertunc.github.io/Worclaude/) — VitePress site with guides and reference
+- [Full Documentation](https://sefaertunc.github.io/Worclaude/): VitePress site with guides and reference
 - [npm Package](https://www.npmjs.com/package/worclaude)
 - [GitHub Issues](https://github.com/sefaertunc/Worclaude/issues)
 - [Contributing](CONTRIBUTING.md)

package/package.json

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

package/src/commands/doc-lint.js

@@ -0,0 +1,37 @@
+import { lintRepo } from '../utils/doc-lint.js';
+import * as display from '../utils/display.js';
+
+export async function docLintCommand(options = {}) {
+  const projectRoot = process.cwd();
+  const result = await lintRepo(projectRoot);
+
+  if (!result.hasDrift) {
+    display.success(`doc-lint clean — ${result.markerCount} marker(s) checked, no drift.`);
+    return;
+  }
+
+  display.newline();
+  display.barLine(`Drift in ${result.findings.length} location(s):`);
+  for (const f of result.findings) {
+    if (f.kind === 'test-count-drift') {
+      display.barLine(
+        `  ${f.file}:${f.claimLine} — claims ${f.claimed.files} test files (actual ${f.actual.files})`
+      );
+    } else if (f.kind === 'missing-npm-script') {
+      display.barLine(
+        `  ${f.file}:${f.markerLine} — references \`npm run ${f.scriptName}\` but no such script in package.json`
+      );
+    } else {
+      display.barLine(`  ${f.file}:${f.markerLine} — ${f.kind}`);
+    }
+  }
+
+  display.newline();
+  display.dim(
+    'Fix by running /sync (refreshes both test count and file count in step 10c via the test runner) or by editing the cited section.'
+  );
+
+  if (options.strict) {
+    process.exitCode = 1;
+  }
+}

package/src/commands/doctor.js

@@ -11,6 +11,7 @@ import {
   TEMPLATE_SKILLS,
 } from '../data/agents.js';
 import { hasClaudeMdMemoryGuidance, readClaudeMd } from '../core/drift-checks.js';
+import { lintRepo } from '../utils/doc-lint.js';
 import { resolveKeyPath, isWorkflowRefFile } from '../core/file-categorizer.js';
 import * as display from '../utils/display.js';
 
@@ -98,6 +99,42 @@ function printResult(r) {
   }
 }
 
+function checkInstallationRationale(meta) {
+  // Old installs scaffolded before T3.6 lack the field — do not flag.
+  if (!meta || !meta.installation) return null;
+  const { rationale } = meta.installation;
+  if (typeof rationale !== 'string' || rationale.trim() === '') {
+    return result(WARN, 'Installation rationale', 'Field present but rationale is empty');
+  }
+  return result(PASS, `Installation rationale: ${rationale}`, null);
+}
+
+async function checkDocLint(projectRoot) {
+  const lint = await lintRepo(projectRoot);
+  if (lint.markerCount === 0) return null;
+  if (!lint.hasDrift) {
+    return result(PASS, `doc-lint: ${lint.markerCount} marker(s) match their source`, null);
+  }
+  const summary = lint.findings
+    .slice(0, 3)
+    .map((f) => {
+      if (f.kind === 'test-count-drift') {
+        return `${f.file}:${f.claimLine} claims ${f.claimed.files} files (actual ${f.actual.files})`;
+      }
+      if (f.kind === 'missing-npm-script') {
+        return `${f.file}:${f.markerLine} references missing script \`npm run ${f.scriptName}\``;
+      }
+      return `${f.file}:${f.markerLine} ${f.kind}`;
+    })
+    .join('; ');
+  const more = lint.findings.length > 3 ? ` (+${lint.findings.length - 3} more)` : '';
+  return result(
+    WARN,
+    `doc-lint: ${lint.findings.length} drift finding(s)`,
+    `${summary}${more}. Run /sync to refresh tech-stack metrics, or fix the cited section.`
+  );
+}
+
 async function checkWorkflowMeta(projectRoot) {
   if (!(await workflowMetaExists(projectRoot))) {
     return result(FAIL, 'workflow-meta.json', 'Missing — run `worclaude init` to create');
@@ -838,6 +875,108 @@ async function checkGitignore(projectRoot) {
   return results;
 }
 
+function runGit(projectRoot, args) {
+  try {
+    const r = spawnSync('git', args, { cwd: projectRoot, encoding: 'utf8' });
+    if (r.error) return { status: -1, stdout: '', stderr: String(r.error) };
+    return {
+      status: r.status,
+      stdout: (r.stdout || '').trim(),
+      stderr: (r.stderr || '').trim(),
+    };
+  } catch (err) {
+    return { status: -1, stdout: '', stderr: String(err) };
+  }
+}
+
+async function checkOriginHead(projectRoot) {
+  const skipped = result(PASS, 'origin/HEAD check skipped', null);
+
+  const headRef = runGit(projectRoot, ['symbolic-ref', 'refs/remotes/origin/HEAD']);
+  if (headRef.status === 128) return skipped;
+  if (headRef.status !== 0) {
+    return result(
+      WARN,
+      'origin/HEAD not set',
+      'Run `git remote set-head origin --auto` (or `git remote set-head origin <branch>`) so worktree agents have a defined base'
+    );
+  }
+
+  const defaultBranch = headRef.stdout.replace(/^refs\/remotes\/origin\//, '');
+  if (!defaultBranch) {
+    return result(WARN, 'origin/HEAD malformed', `Unexpected ref: ${headRef.stdout}`);
+  }
+
+  const currentRef = runGit(projectRoot, ['branch', '--show-current']);
+  if (currentRef.status !== 0) return skipped;
+
+  const currentBranch = currentRef.stdout;
+  if (!currentBranch) {
+    return result(PASS, `origin/HEAD → ${defaultBranch} (detached HEAD, skipped)`, null);
+  }
+  if (currentBranch === defaultBranch) {
+    return result(PASS, `origin/HEAD → ${defaultBranch} (matches current branch)`, null);
+  }
+
+  const ahead = runGit(projectRoot, [
+    'rev-list',
+    '--count',
+    `origin/${defaultBranch}..${currentBranch}`,
+  ]);
+  if (ahead.status !== 0) {
+    return result(PASS, `origin/HEAD → ${defaultBranch}`, null);
+  }
+  const aheadCount = Number.parseInt(ahead.stdout, 10) || 0;
+  if (aheadCount === 0) {
+    return result(
+      PASS,
+      `origin/HEAD → ${defaultBranch}, current '${currentBranch}' not ahead`,
+      null
+    );
+  }
+
+  return result(
+    WARN,
+    `Current branch '${currentBranch}' is ${aheadCount} commit(s) ahead of origin/${defaultBranch}`,
+    `Worktree agents (claude --worktree, Agent isolation:worktree) base off origin/${defaultBranch} and will miss those commits. Fix: \`git remote set-head origin ${currentBranch}\` (local-only, reversible with \`--auto\` or \`main\`)`
+  );
+}
+
+const STALE_WORKTREE_THRESHOLD = 3;
+
+async function checkStaleWorktrees(projectRoot) {
+  const worktreesDir = path.join(projectRoot, '.claude', 'worktrees');
+  if (!(await fs.pathExists(worktreesDir))) {
+    return result(PASS, '.claude/worktrees/ (none)', null);
+  }
+
+  let entries;
+  try {
+    entries = await fs.readdir(worktreesDir);
+  } catch {
+    return result(PASS, '.claude/worktrees/ (unreadable, skipped)', null);
+  }
+
+  const dirs = [];
+  for (const name of entries) {
+    if (name.startsWith('.')) continue;
+    const stat = await fs.stat(path.join(worktreesDir, name)).catch(() => null);
+    if (stat && stat.isDirectory()) dirs.push(name);
+  }
+
+  if (dirs.length === 0) {
+    return result(PASS, '.claude/worktrees/ (empty)', null);
+  }
+  if (dirs.length <= STALE_WORKTREE_THRESHOLD) {
+    return result(PASS, `.claude/worktrees/ (${dirs.length} present)`, null);
+  }
+  return result(
+    WARN,
+    `.claude/worktrees/ has ${dirs.length} entries (threshold ${STALE_WORKTREE_THRESHOLD})`,
+    'Locked agent worktrees survive `git worktree prune`. Run `worclaude worktrees clean` to force-remove them.'
+  );
+}
+
 async function checkPendingReviewFiles(projectRoot) {
   const pending = [];
   try {
@@ -933,6 +1072,10 @@ export async function doctorCommand(options = {}) {
   // Documentation
   section('Documentation');
   record('docs', await checkDocSpecs(projectRoot));
+  const rationaleCheck = checkInstallationRationale(meta);
+  if (rationaleCheck) record('docs', rationaleCheck);
+  const lintCheck = await checkDocLint(projectRoot);
+  if (lintCheck) record('docs', lintCheck);
   spacer();
 
   // Learnings
@@ -943,12 +1086,14 @@ export async function doctorCommand(options = {}) {
   // Git Integration
   section('Git Integration');
   record('git', await checkGitignore(projectRoot));
+  record('git', await checkOriginHead(projectRoot));
   spacer();
 
   // Integrity
   section('Integrity');
   record('integrity', await checkHashIntegrity(projectRoot, meta));
   record('integrity', await checkPendingReviewFiles(projectRoot));
+  record('integrity', await checkStaleWorktrees(projectRoot));
   spacer();
 
   // Exit code