worclaude 2.7.1 → 2.9.0

package/templates/commands/commit-push-pr.md

@@ -5,6 +5,10 @@ description: "Commit, push, and create PR — branch-aware with session summary"
 Determine which branch you're on, then follow the appropriate flow.
 Do not add Co-Authored-By trailers or AI-generated footers to commits or PR descriptions.
 
+## Invocation Contract
+
+Run this command only when the human explicitly invokes it (typed `/commit-push-pr` or one of the Trigger Phrases at the bottom of this file). Do not auto-launch from a "we're done" inference. The `Version bump:` AskUserQuestion at step 6 is mandatory and never auto-answerable — refuse to proceed without an explicit human selection. See CLAUDE.md Critical Rule 13.
+
 ## Worktree Awareness
 
 If you are in a git worktree session:
@@ -17,11 +21,17 @@ If you are in a git worktree session:
 Feature branches contain ONLY the task changes. Do NOT touch shared-state
 files (see git-conventions.md for the canonical list).
 
-1. Write a session summary to .claude/sessions/:
-   - Filename: YYYY-MM-DD-HHMM-{short-branch-name}.md
+1. Stage all changes: `git add -A`
+2. Write a clear, conventional commit message and create the commit.
+3. Capture the new HEAD SHA: `git rev-parse HEAD` — this is the value to
+   embed in the session summary's `sha:` line so the next `/start` can
+   compute drift accurately (`git log <sha>..HEAD`).
+4. Write a session summary to `.claude/sessions/`:
+   - Filename: `YYYY-MM-DD-HHMM-{short-branch-name}.md`
    - Content format:
      ```
      # Session: {date}
+     sha: {full HEAD SHA captured in step 3}
      **Branch:** {current branch}
      **Task:** {one-line summary of what was worked on}
 
@@ -39,32 +49,45 @@ files (see git-conventions.md for the canonical list).
      - **Commands used:** {all slash commands run earlier in this session, e.g. /start, /verify, /refactor-clean. Do NOT include the current /commit-push-pr or /end that is writing this summary. Write "none" if no other commands were used.}
      - **Verification result:** {if /verify was run: passed/failed with brief summary; otherwise "not run".}
      ```
+   - The `sha:` line MUST be its own line starting with `sha:` (case-
+     sensitive, no leading whitespace, no markdown formatting around it).
+     `/start` parses it with `grep -oP '^sha:\s*\K[a-f0-9]+'`.
    - Keep it concise — this is for machine consumption at session start,
-     not a detailed report
-2. Stage all changes: git add -A
-3. Write a clear, conventional commit message
-4. Push to the current branch
-5. Create a PR targeting develop: gh pr create --base develop
-6. Determine the version bump level for this PR. Read the Versioning Policy
-   in the project's git-conventions document to decide: `major`, `minor`,
-   `patch`, or `none`.
-   - `major` — breaking change to public API, CLI, or scaffold contract
-   - `minor` — new feature, command, agent, or flag
-   - `patch` — bug fix or user-visible behavior change with no new surface
-   - `none` — docs, CI, tests, internal refactor (nothing consumers notice)
+     not a detailed report.
+   - The `.claude/sessions/` directory is gitignored; do not stage it.
+5. Push to the current branch.
+6. **Required: prompt for `Version bump:` declaration via AskUserQuestion.**
+   Use AskUserQuestion with these four options and one-line descriptions:
+
+   ```
+   Question: "What version bump does this PR declare?"
+
+   - major  — breaking change to public API, CLI, or scaffold contract
+   - minor  — new feature, command, agent, or flag
+   - patch  — bug fix or user-visible behavior change with no new surface
+   - none   — docs, CI, tests, internal refactor (nothing consumers notice)
+   ```
 
    For revert PRs: declare the same bump level as the PR being reverted.
 
-   If the change is ambiguous, ASK THE USER. Do not guess.
+   **Refuse to proceed without an answer.** No PR opens until the user
+   selects one of the four options. This is the upstream enforcement of
+   `/sync`'s release-time aggregation — every PR carries an explicit
+   declaration so `/sync` can pick max without surprises.
 
-   The PR description MUST include this line on its own, verbatim:
+   If the user's answer is genuinely ambiguous after seeing the four
+   options (rare), ask one targeted clarifying question, then re-prompt.
+
+7. Create the PR with `gh pr create --base develop`. The PR description
+   MUST include this line on its own, verbatim:
 
    ```
    Version bump: {major|minor|patch|none}
    ```
 
    `/sync` parses this string exactly — other phrasings will be ignored.
-7. Include in PR description: title, changes, testing done, reviewer notes
+
+8. Include in PR description: title, changes, testing done, reviewer notes
 
 ## On develop
 
@@ -74,13 +97,13 @@ Versioning happens in `/sync`, not here. The release PR body is pre-written
 by `/sync` with the aggregated bump summary and the list of feature PRs
 included in the release.
 
-1. Write a session summary to .claude/sessions/:
-   - Filename: YYYY-MM-DD-HHMM-{short-branch-name}.md
-   - Same format as the feature branch session summary above
-2. Stage all changes: git add -A
-3. Write a clear, conventional commit message
-4. Push to develop
-5. Create a PR targeting main: gh pr create --base main
+1. Stage all changes: `git add -A`
+2. Write a clear, conventional commit message and create the commit.
+3. Capture the new HEAD SHA: `git rev-parse HEAD`.
+4. Write a session summary to `.claude/sessions/` using the same format as
+   the feature branch session summary above (including the `sha:` line).
+5. Push to develop.
+6. Create a PR targeting main: `gh pr create --base main`.
 
 ## On any other branch
 

package/templates/commands/compact-safe.md

@@ -2,16 +2,88 @@
 description: "Compress context via /compact with safety checks"
 ---
 
-Run /compact to compress context.
-The PostCompact hook will automatically re-read CLAUDE.md
-and PROGRESS.md.
+`/compact-safe` adds pre-flight safety checks to bare `/compact`. Compaction
+loses fine-grained conversation state; running it on a session with
+uncommitted work, mid-implementation TODOs, or recent destructive operations
+risks losing context the user expected to keep. This command surfaces those
+risks before triggering compaction.
 
-After compaction, briefly confirm:
-- Current task
-- Current branch
-- What was just being worked on
+## Pre-flight safety checks
+
+Run all four checks. Report the findings as a short table. Stop and ask the
+user for confirmation if **any** check trips.
+
+### 1. Uncommitted changes
+
+```bash
+git status --porcelain
+```
+
+If output is non-empty, surface a warning: "You have N uncommitted changes.
+Compaction loses references to specific files and line numbers — consider
+committing or stashing first."
+
+Offer via `AskUserQuestion`:
+- `commit`  — write a WIP commit before compacting (reversible)
+- `stash`   — stash changes, compact, then `git stash pop` after
+- `proceed` — compact anyway (you accept the risk)
+- `cancel`  — abort compaction
+
+### 2. In-flight work signals
+
+Scan for indicators that compaction would lose useful context:
+
+- **Recent test failures** — check the last `npm test` / `vitest` / `pytest`
+  output if available. If there are failing tests, warn the user and offer
+  to run `/verify` first to capture the failure list before compacting.
+- **Mid-implementation TODOs** — `grep -rn "TODO(claude)\|FIXME\|XXX" src/`
+  on files changed in the last hour (`git diff --name-only HEAD@{1.hour.ago}`
+  if available, otherwise `--name-only HEAD~1`). If matches exist, surface
+  them — they may be context Claude needs to remember.
+
+### 3. Recent destructive operations
+
+Check the last 20 commands in transcript or shell history for destructive
+patterns: `rm -rf`, `git reset --hard`, `git push --force`, `DROP TABLE`,
+etc. If any were run within the last 30 minutes, warn the user — they may
+want to keep the conversation context until they verify the destructive
+op landed correctly.
+
+### 4. PostCompact hook verification
+
+Confirm `.claude/settings.json` has a `PostCompact` hook configured. Without
+it, compaction strips CLAUDE.md / PROGRESS.md context permanently. If the
+hook is missing, surface a warning and stop — compacting in this state
+silently breaks Claude's session orientation.
+
+```bash
+node -e 'const s = require("./.claude/settings.json"); console.log(JSON.stringify(s.hooks?.PostCompact || []))'
+```
+
+If the output is `[]`, halt and tell the user to either fix the hook config
+or accept the risk explicitly.
+
+## Compaction
+
+If all checks pass (or the user accepts each warning explicitly):
+
+1. Run `/compact` to compress context. The PostCompact hook re-reads
+   CLAUDE.md and PROGRESS.md automatically.
+
+2. **Post-compaction recap.** Briefly confirm:
+   - Current task
+   - Current branch
+   - What was just being worked on
+   - Any in-flight scratch artifacts the post-compact session should be aware
+     of (`.claude/scratch/last-review.md`, etc., if present and SHA-current)
+
+If the recap surfaces something Claude no longer remembers but should,
+that's a signal the safety checks missed something — flag it for the user
+so they can decide whether to roll back via `git reflog` if a recovery
+matters.
 
 ## Trigger Phrases
 - "compact context"
 - "free up context"
 - "running low on context"
+- "compact safely"

package/templates/commands/conflict-resolver.md

@@ -23,7 +23,12 @@ For each conflicted file:
 For each conflict:
 - Changes in DIFFERENT parts of the code → keep both
 - Changes modify the SAME lines → combine intelligently based on intent
-- Changes truly contradict → ask the user which to keep
+- Changes truly contradict → use **AskUserQuestion** with three options:
+  - `keep A` — keep the incoming branch's version
+  - `keep B` — keep the current branch's version
+  - `combine` — merge both intents (you describe how)
+
+  Refuse to proceed without an answer. Never guess.
 - NEVER silently drop changes from either side
 
 ## Step 4: Verify clean
@@ -33,8 +38,7 @@ Search ALL tracked files for remaining conflict markers
 
 ## Step 5: Test
 
-Run /verify (or the project's test and lint commands).
-If anything fails, fix it.
+Run `/verify`. If anything fails, fix it.
 
 ## Step 6: Commit resolution only
 

package/templates/commands/end.md

@@ -21,24 +21,70 @@ If you are working in a git worktree (not the main checkout):
 
 ## Mid-task handoff
 
-1. Create docs/handoffs/HANDOFF-{branch-name}-{date}.md
-2. Include:
-   - What was being worked on
-   - What is done so far
-   - What is left to do
-   - Decisions or context the next session needs
-   - Files that were modified
-3. Write a session summary to .claude/sessions/:
-   - Filename: YYYY-MM-DD-HHMM-{short-branch-name}.md
-   - Same format as /commit-push-pr session summaries
-   - Mark the task as "IN PROGRESS" since /end means work is unfinished
-   - Fill in the ## Workflow Observability section: list agents invoked and
-     slash commands used so far (excluding the current /end). Verification
-     result is "not run" unless /verify was executed earlier in the session.
-4. git add -A
-5. git commit -m "wip: handoff for [task description]"
+`/end` writes two artifacts with **disjoint content**:
+
+- **Handoff** (`docs/handoffs/HANDOFF-{branch}-{date}.md`) — **forward-looking only.**
+  What's left, decisions still pending, where to pick up. Do NOT include
+  what got done or workflow observability — those belong in the session
+  summary.
+- **Session summary** (`.claude/sessions/{YYYY-MM-DD-HHMM}-{branch}.md`) —
+  **backward-looking only.** What got done, files modified, agents invoked,
+  commands used, verification result. Do NOT include "what's left" — that
+  belongs in the handoff.
+
+The split is deliberate: handoffs answer "where does the next session start?",
+session summaries answer "what happened in this session?". Mixing them makes
+both harder to consume.
+
+### Steps
+
+1. **Create the handoff** at `docs/handoffs/HANDOFF-{branch-name}-{date}.md`:
+   - **What's left to do** — concrete next steps, in priority order
+   - **Decisions still pending** — items that need a human call before the
+     next session can pick them up
+   - **Where to pick up** — exact file/line/command to start with, plus any
+     scratch artifacts (`.claude/scratch/last-review.md`, etc.) that are
+     SHA-relevant
+   - **Open questions** — anything ambiguous that the next session needs to
+     resolve before continuing
+
+2. `git add -A`
+
+3. `git commit -m "wip: handoff for [task description]"`
    Use exactly this message format — no trailers or Co-Authored-By lines.
-6. git push
+
+4. Capture the new HEAD SHA: `git rev-parse HEAD`. Embed it as the
+   `sha:` line in the session summary so the next `/start` can compute
+   drift accurately (`git log <sha>..HEAD`).
+
+5. **Write the session summary** at `.claude/sessions/YYYY-MM-DD-HHMM-{short-branch-name}.md`
+   using the same format as `/commit-push-pr` session summaries:
+   - First line: `# Session: {date}`
+   - Second line: `sha: {full HEAD SHA captured in step 4}` — own line,
+     case-sensitive, no leading whitespace, no markdown formatting around it.
+   - Mark the task as "IN PROGRESS" since `/end` means work is unfinished
+   - Fill in `## Completed` with what got done this session
+   - Fill in `## Files Modified`
+   - Fill in `## Workflow Observability`: agents invoked, slash commands
+     used so far (excluding the current `/end`), verification result
+   - Do NOT duplicate the handoff's forward-looking content here
+   - The `.claude/sessions/` directory is gitignored; do not stage it.
+
+6. **Required: prompt for push consent via `AskUserQuestion`.**
+
+   ```
+   Question: "Push the WIP commit to remote?"
+
+   - yes  — push to origin so this branch is recoverable from another machine
+   - no   — keep the WIP commit local; you'll push when you resume
+   ```
+
+   Refuse to proceed past this step without an answer. **Default to local-only**
+   if the user declines — pushing WIP commits to remote is sometimes unwanted
+   (work-in-progress visible to collaborators, broken intermediate state).
+
+7. On `yes`: `git push`. On `no`: skip push, report "WIP commit local-only.
+   Run `git push` when you resume."
 
 ## Trigger Phrases
 - "stop working"

package/templates/commands/learn.md

@@ -9,23 +9,87 @@ Example: `/learn Always use conventional commits for this project`
 
 If no arguments provided, ask the user what they want to remember.
 
-Format it as a [LEARN] block:
+## Format
 
+A learning is a `[LEARN]` block:
+
+```
 [LEARN] Category: One-line rule description
 Mistake: What went wrong (optional)
 Correction: What should happen instead (optional)
+```
+
+Write to `.claude/learnings/{category-slug}.md` with YAML frontmatter:
+
+```yaml
+---
+created: <today's date YYYY-MM-DD>
+category: <from the [LEARN] block>
+project: <package.json name, or directory name as fallback>
+---
+```
 
-Write this to `.claude/learnings/{category-slug}.md` with YAML frontmatter:
-- created: today's date (YYYY-MM-DD)
-- category: from the [LEARN] block
-- project: current project name (from package.json name field, or directory name)
-- times_applied: 0
+**Do NOT add a `times_applied` field.** The auto-capture hook never
+increments it; the field would be a lie. Removed in Phase 2 (2026-04).
 
-Update `.claude/learnings/index.json` to include the new entry.
-If index.json doesn't exist, create it with `{ "learnings": [] }`.
+After writing, **regenerate `.claude/learnings/index.json` from the
+directory contents** — never hand-maintain it. The regeneration walks
+`.claude/learnings/*.md`, parses each frontmatter, and writes the
+canonical `{ "learnings": [{file, category, created}, ...] }` index.
+This guarantees the index never drifts from the files on disk.
 
 Confirm to the user what was saved and where.
 
+## When to use `/learn` vs other memory layers
+
+The system has multiple memory layers; pick the right one for the
+trigger:
+
+| Trigger                                    | Lands in                                | Audience            |
+| ------------------------------------------ | --------------------------------------- | ------------------- |
+| Plain conversation ("user pushes back")    | Claude Code's auto-memory (autonomous)  | Personal, machine-local |
+| `/learn` or `[LEARN]` marker               | `.claude/learnings/`                    | **Team-relevant**   |
+| `/update-claude-md` (later promotion path) | `CLAUDE.md`                             | Team, every session |
+
+**`/learn` is the team signal.** Use it when the rule belongs to the
+project, not your personal preferences. Examples:
+
+- ✅ "We always use pnpm in this repo, not npm" → `/learn`
+- ✅ "The conflict-resolver must not push" → `/learn`
+- ❌ "I prefer terse responses" → leave to auto-memory; don't `/learn`
+- ❌ "User pushes back on overengineering" → leave to auto-memory
+
+If the rule starts personal but recurs across sessions, `/update-claude-md`
+can later promote a stable learning to CLAUDE.md.
+
+## Correction-triggered semi-auto path
+
+When `correction-detect.cjs` (UserPromptSubmit hook) flags a correction in
+the user's prompt, the hook emits a hint suggesting Claude propose a
+learning. Claude SHOULD then:
+
+1. Draft a one-line generalizable rule based on the correction
+2. Prompt the user via `AskUserQuestion`:
+
+   ```
+   Question: "You corrected me: '<short paraphrase>'.
+              Proposed learning: '<concrete rule>'.
+              Capture as team learning?"
+
+   - yes              — save as proposed
+   - yes, let me edit — show the text, I'll refine before saving
+   - no               — drop it
+   ```
+
+3. On `yes` / `yes-edit` → emit a `[LEARN]` block with the agreed text.
+   The Stop hook (`learn-capture.cjs`) persists it to
+   `.claude/learnings/` automatically.
+4. On `no` → no action. Don't re-prompt for the same correction.
+
+This path is **targeted, not blanket**: it only fires when the
+correction-detect regex matches. Random turns don't get a "did you
+learn something?" prompt — that would be noise.
+
 ## Trigger Phrases
 - "remember this"
 - "learn this"

package/templates/commands/observability.md

@@ -0,0 +1,59 @@
+---
+description: 'Per-project observability report — signal frequencies, anomalies, suggestions'
+---
+
+Surface the local observability report for this project. The data lives in
+`.claude/observability/` and is captured by hooks that fire on Claude Code's
+`InstructionsLoaded`, `UserPromptSubmit`, and `SubagentStart` / `SubagentStop`
+events. **Zero data leaves the machine** — the folder is gitignored.
+
+## Run
+
+```bash
+worclaude observability
+```
+
+The CLI reads the JSONL files (skill loads, command invocations, agent
+events), pairs agent start/stop events to compute durations, and emits a
+Markdown report covering:
+
+- **Top skills** by load count, with last-seen timestamp.
+- **Top commands** by invocation count.
+- **Agent invocations** with completed/failed counts and average duration.
+- **Anomalies** — installed skills that never loaded, agents that fail more
+  often than they complete.
+- **Suggestions** — skills not loaded in 30+ days (consider retiring).
+
+Flags:
+
+- `--json` — emit the raw report object as JSON (machine-readable).
+- `--out <file>` — write the report to a file instead of stdout.
+
+## Use cases
+
+1. **Skill hygiene.** Skills that never load are noise — either rename them
+   to match the prompts users actually type, update their description for
+   `skill-hint.cjs` keyword match, or retire them.
+2. **Agent reliability.** If an agent's failure ratio is high, look at what
+   the agent is being asked to do. The `bug-fixer` and `verify-app` agents
+   should sit near 100% completion in a healthy project.
+3. **Command surface review.** If `/some-command` has zero invocations after
+   weeks of use, it might not be earning its slot in the surface.
+
+## Privacy
+
+The report is built entirely from local files. No network egress, no
+upload, no opt-in dashboard. To disable capture entirely, set
+`WORCLAUDE_HOOK_PROFILE=minimal` — the observability hooks short-circuit on
+that profile (same as `learn-capture` and `correction-detect`).
+
+To purge captured data, delete `.claude/observability/`. It will be
+recreated empty on the next session start.
+
+## Trigger Phrases
+
+- "show observability"
+- "observability report"
+- "what's my project's observability report?"
+- "skill usage report"
+- "agent reliability"

package/templates/commands/refactor-clean.md

@@ -32,14 +32,56 @@ the files in the current working directory.
 
 ## Process
 
+### 0. Check for fresh `/review-changes` output
+
+Before doing your own analysis, look for `.claude/scratch/last-review.md`:
+
+```bash
+test -f .claude/scratch/last-review.md && head -10 .claude/scratch/last-review.md
+```
+
+If the file exists AND its `sha:` frontmatter matches `git rev-parse HEAD`,
+**use the review as your work plan**. Skip steps 1-3 below; jump straight
+to step 4 with the review's findings as your candidate list.
+
+If the SHA doesn't match, the review is stale — ignore it and proceed
+with your own analysis.
+
+### 1-6. Self-analysis path (only if no fresh review)
+
 1. Identify changed files: `git diff --name-only` (unstaged) and
    `git diff --cached --name-only` (staged). If no changes, check
    `git diff --name-only HEAD~5` for recent commits.
 2. Read each changed file fully — understand context before changing
 3. Check CLAUDE.md for project-specific conventions
 4. Make one improvement at a time, smallest meaningful change first
-5. Run the full test suite after EVERY change
-6. If tests fail, revert immediately — your change broke behavior
+5. **Scoped tests after each change.** Run only the tests related to
+   the files you changed (don't run the whole suite each time):
+   - Vitest: `npx vitest run --related <changed-files>`
+   - Jest: `npx jest --findRelatedTests <changed-files>`
+   - Other runners: scope to the relevant test directory or file pattern
+6. If scoped tests fail, revert immediately — your change broke behavior
+
+### 7. Full-suite safety net
+
+After all individual changes pass their scoped tests, run the **full
+test suite once** as a regression net:
+
+- `npx vitest run` (or `npm test`, `pytest`, etc. — whatever the project
+  uses for the full suite)
+
+If the full suite fails but scoped tests passed, the regression is
+cross-cutting. Bisect the changes to find the offender, revert it.
+
+### 8. Invalidate the review artifact
+
+After completion, **delete `.claude/scratch/last-review.md`** (or write a
+short marker indicating it was consumed). This prevents a future
+`/refactor-clean` invocation from picking up an already-applied review.
+
+```bash
+rm -f .claude/scratch/last-review.md
+```
 
 ## Confidence Filtering
 

package/templates/commands/review-changes.md

@@ -1,27 +1,56 @@
 ---
-description: "Code review — reports findings as prioritized table without modifying files"
+description: "Code review — reports findings as prioritized table and writes a scratch artifact"
 ---
 
 Review changed code for reuse, quality, and efficiency.
 
-CRITICAL: This is a READ-ONLY review. You MUST NOT edit any files.
-You MUST NOT make any commits. You MUST NOT stage changes.
-Only analyze and report.
+CRITICAL: This is a READ-ONLY review of source files. You MUST NOT edit
+source files. You MUST NOT make any commits. You MUST NOT stage changes.
+Only analyze, report, and write **one** scratch artifact (see step 4).
 
-1. Read recent changes (git diff HEAD~1 or staged changes)
+## Process
+
+1. Read recent changes (`git diff HEAD~1` or staged changes).
 2. Check for:
    - Duplicated code or missed reuse opportunities
    - Unnecessary complexity or abstraction
    - Inconsistency with project patterns
    - CLAUDE.md compliance issues
-3. Report findings as a prioritized table:
+3. Report findings as a prioritized table to the user:
+
+   ```
+   | Finding | Category | Action |
+   |---------|----------|--------|
+   | [what]  | [type]   | Fix / Skip — [reason] |
+   ```
+
+4. **Write the findings to `.claude/scratch/last-review.md`** with SHA
+   frontmatter so `/refactor-clean` can pick them up without re-analyzing.
+
+   ```markdown
+   ---
+   created: <YYYY-MM-DDTHH:MM:SSZ>
+   sha: <git rev-parse HEAD>
+   command: /review-changes
+   ---
+
+   # Findings
+
+   | Finding | Category | Action |
+   |---------|----------|--------|
+   | ...     | ...      | ...    |
+   ```
+
+   Capture the SHA via `git rev-parse HEAD` at the moment of writing. If
+   `.claude/scratch/last-review.md` already exists, **overwrite it** —
+   only the most recent review is consumed.
 
-| Finding | Category | Action |
-|---------|----------|--------|
-| [what]  | [type]   | Fix / Skip — [reason] |
+   Writing this file is the ONLY filesystem mutation `/review-changes`
+   performs. Source files remain untouched.
 
-The user will decide which findings to act on and apply fixes themselves.
-Do NOT apply any fixes. Do NOT touch any files. REPORT ONLY.
+The user will decide which findings to act on. They can run
+`/refactor-clean` next; it will read the scratch file and use the
+findings as a work plan (skipping its own analysis when the SHA matches).
 
 ## Trigger Phrases
 - "review my changes"