worclaude 2.8.0 → 2.9.1

package/CHANGELOG.md

@@ -4,6 +4,71 @@ All notable changes to worclaude are documented in this file. Format loosely fol
 
 ## [Unreleased]
 
+## [2.9.1] — 2026-04-28
+
+Security patch clearing three transitive dev-dep advisories surfaced by Socket.dev and `npm audit` (esbuild dev-server CORS, vite path-traversal in optimized-deps, postcss XSS in CSS stringify). All three were dev-only, gated behind running `npm run docs:dev` and visiting a hostile origin in the same session — neither CI nor end-user installs trigger the conditions — but they kept appearing in scanner output and drowning out signal. Resolved via `npm overrides` in `package.json` (esbuild ^0.25.0, vite ^6.4.2, postcss ^8.5.10) which forces vitepress 1.6.4 onto patched transitives despite its declared `vite ^5.4.14` peer range; `npm run docs:build` verified clean. SECURITY.md rewritten: stale "pending upstream fixes" section replaced with "fixed via overrides", new false-positive subsections for Socket's AI-typosquat alert ("Did you mean: claude") and URL-strings alert (template content, not endpoints), supported-version table bumped to 2.9.x.
+
+### Fixed
+
+- **Three transitive dev-dep CVEs cleared via `npm overrides`** (PR #153) — esbuild 0.21.5 → 0.25.12 ([GHSA-67mh-4wv8-2f99](https://github.com/advisories/GHSA-67mh-4wv8-2f99) / CVE-2026-41305), vite 5.4.21 → 6.4.2 ([GHSA-4w7w-66w2-5vf9](https://github.com/advisories/GHSA-4w7w-66w2-5vf9) / CVE-2026-39365), postcss 8.5.8 → 8.5.12 ([GHSA-qx2v-qp2m-jg93](https://github.com/advisories/GHSA-qx2v-qp2m-jg93)). `npm audit` now reports 0 vulnerabilities; all 947 tests still pass; `npm run docs:build` succeeds against vitepress 1.6.4.
+
+### Docs
+
+- **`SECURITY.md` refresh** (PR #153) — replaces the obsolete "pending upstream fixes" section with a "fixed via overrides" section listing each advisory and resolved version. Adds two new false-positive subsections documenting Socket's AI-typosquat alert ("Did you mean: claude" — permanent, package was published under this name from day one) and URL-strings alert (flagged hostnames/filenames are template prose under `templates/`, not runtime endpoints; only `src/utils/npm.js` makes a network call). Bumps the supported-version table from `2.6.x` to `2.9.x`.
+
+## [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.

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/SECURITY.md

@@ -4,8 +4,8 @@
 
 | Version | Supported          |
 | ------- | ------------------ |
-| 2.6.x   | :white_check_mark: |
-| < 2.6   | :x:                |
+| 2.9.x   | :white_check_mark: |
+| < 2.9   | :x:                |
 
 ## Reporting a Vulnerability
 
@@ -69,39 +69,33 @@ an opt-in `workflow-meta.json`. The `fs-extra`-based filesystem capability
 flag is a disclosure, not a vulnerability — removing it would delete the
 tool's core function.
 
-### Dev-only transitive advisories pending upstream fixes
-
-Two advisories sit deep in the dev-dependency tree and cannot currently be
-resolved without either forking `vitepress` or waiting for its next release:
-
-- **[GHSA-4w7w-66w2-5vf9](https://github.com/advisories/GHSA-4w7w-66w2-5vf9)** —
-  `vite@5.4.21` path traversal in optimized-deps handling. Fixed in
-  `vite@>=6.4.2`.
-- **[GHSA-67mh-4wv8-2f99](https://github.com/advisories/GHSA-67mh-4wv8-2f99)** —
-  `esbuild@0.21.5` dev-server CORS misconfiguration. Fixed in
-  `esbuild@>=0.25.0`.
-
-Both are pulled through `vitepress@1.6.4` (the current latest on npm),
-which pins `vite` at `^5.0.0`, which in turn pins `esbuild` at `^0.21.3`.
-`npm overrides` cannot force newer major versions without breaking the
-vite peer contract.
-
-Why these do not block a release:
-
-- Both packages are in `devDependencies` only. The `files` whitelist in
-  `package.json` does not include `tests/` or any dev tooling; end users
-  installing `worclaude` via npm do not get these packages.
-- Both advisories require an **active local dev server** to exploit. The
-  vite/vitest attack surface only exists while `npm run docs:dev` is
-  running and the operator browses to a hostile origin in the same
-  session. `npm test`, `npm run lint`, `npm run docs:build`, and CI
-  runs do not start a server.
-- Worclaude's CI does not run `docs:dev`; it runs `test`, `lint`, and
-  `docs:build` only.
-
-Tracking: a GitHub issue is opened to bump `vitepress` once a release
-using `vite@>=6.4.2` lands upstream. Until then the scanner will continue
-to flag these, and we accept the dev-only risk.
+### Dev-only transitive advisories (fixed via overrides)
+
+Three advisories sat deep in the dev-dependency tree, all pulled through
+`vitepress@1.6.4 → vite@5.x → esbuild@0.21.x`. They are now pinned to
+patched versions via `"overrides"` in `package.json`:
+
+- **[GHSA-67mh-4wv8-2f99](https://github.com/advisories/GHSA-67mh-4wv8-2f99)
+  / CVE-2026-41305** — `esbuild` dev-server CORS misconfiguration.
+  Override: `"esbuild": "^0.25.0"` (resolved 0.25.12).
+- **[GHSA-4w7w-66w2-5vf9](https://github.com/advisories/GHSA-4w7w-66w2-5vf9)
+  / CVE-2026-39365** — `vite` path traversal in optimized-deps handling
+  (affects vite 6.0.0–6.4.1; Socket's range matcher also flags 5.x).
+  Override: `"vite": "^6.4.2"` (resolved 6.4.2).
+- **[GHSA-qx2v-qp2m-jg93](https://github.com/advisories/GHSA-qx2v-qp2m-jg93)** —
+  `postcss` XSS via unescaped `</style>` in CSS stringify output.
+  Override: `"postcss": "^8.5.10"` (resolved 8.5.12).
+
+Verified clean: `npm audit` reports 0 vulnerabilities, `npm run docs:build`
+succeeds against `vitepress@1.6.4` despite its declared `vite@^5.4.14`
+peer range, and all 947 tests pass.
+
+These were not exploitable in worclaude's actual usage — every advisory
+required an active local dev server (`npm run docs:dev`) and the operator
+visiting a hostile origin in the same session. `npm test`, `npm run lint`,
+`npm run docs:build`, and CI never start a server. They are flagged
+nonetheless because Socket and `npm audit` scan the lockfile by version,
+not by exploit reachability.
 
 ### brace-expansion DoS (fixed via override)
 
@@ -109,3 +103,28 @@ to flag these, and we accept the dev-only risk.
 `brace-expansion@<1.1.13` zero-step sequence. Fixed in 1.1.13; enforced
 via `"overrides": { "brace-expansion": "^1.1.13" }` in `package.json`
 since v2.6.2. Pulled by `eslint@9.x → minimatch@3.x`.
+
+### AI-detected typosquat alert (false positive)
+
+Socket's "AI-detected possible typosquat — Did you mean: claude" flag
+triggers because the package name `worclaude` contains the substring
+`claude`. The package was published under this name from day one
+(2026-02), the npm namespace is owned by the original author
+(`sefaertunc`), and the package is the canonical home for the workflow
+described in this README. There is no upstream `claude` workflow
+scaffolder being typosquatted — `claude` on npm is an unrelated
+abandoned package. Renaming a published, indexed package would break
+every existing user's CLI alias and slash-command muscle memory; the
+alert is accepted as a permanent false positive.
+
+### URL-strings supply-chain alert (template content)
+
+Socket's "URL strings" alert lists hostnames and filenames extracted
+from the package's text content (e.g. `gitforwindows.org`, `Fly.io`,
+`Platform.sh`, `CLAUDE.md`, `SKILL.md`). Every match is documentation
+or template prose under `templates/` — instruction text the scaffolder
+writes into the user's project. Worclaude does not make network calls
+at runtime; the only HTTP code path is `src/utils/npm.js`, which
+queries the npm registry for the latest published version during
+`worclaude upgrade` and `worclaude status`. The flagged strings are
+content, not endpoints.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worclaude",
-  "version": "2.8.0",
+  "version": "2.9.1",
   "description": "The Workflow Layer for Claude Code — scaffold agents, commands, skills, hooks, and memory into any project",
   "type": "module",
   "bin": {
@@ -79,6 +79,9 @@
     "vitest": "^3.0.9"
   },
   "overrides": {
-    "brace-expansion": "^1.1.13"
+    "brace-expansion": "^1.1.13",
+    "esbuild": "^0.25.0",
+    "vite": "^6.4.2",
+    "postcss": "^8.5.10"
   }
 }

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');
@@ -905,6 +942,41 @@ async function checkOriginHead(projectRoot) {
   );
 }
 
+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 {
@@ -1000,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
@@ -1017,6 +1093,7 @@ export async function doctorCommand(options = {}) {
   section('Integrity');
   record('integrity', await checkHashIntegrity(projectRoot, meta));
   record('integrity', await checkPendingReviewFiles(projectRoot));
+  record('integrity', await checkStaleWorktrees(projectRoot));
   spacer();
 
   // Exit code