worclaude 2.7.1 → 2.8.0

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to worclaude are documented in this file. Format loosely fol
 
 ## [Unreleased]
 
+## [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/package.json

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

package/src/commands/doctor.js

@@ -838,6 +838,73 @@ 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\`)`
+  );
+}
+
 async function checkPendingReviewFiles(projectRoot) {
   const pending = [];
   try {
@@ -943,6 +1010,7 @@ export async function doctorCommand(options = {}) {
   // Git Integration
   section('Git Integration');
   record('git', await checkGitignore(projectRoot));
+  record('git', await checkOriginHead(projectRoot));
   spacer();
 
   // Integrity

package/templates/agents/optional/quality/bug-fixer.md

@@ -6,6 +6,18 @@ isolation: worktree
 maxTurns: 50
 ---
 
+## Worktree freshness preamble
+
+Before making any code changes, synchronize this worktree to the parent checkout's committed state. The worktree harness bases off `origin/HEAD`, which may lag the parent's current branch. Follow these steps and report the result:
+
+1. Run `git fetch origin`.
+2. Run `git worktree list --porcelain`. Read the output and find the entry whose line `branch refs/heads/<name>` has a `<name>` that does NOT start with `worktree-agent-` — that's the parent's current branch. Strip the `refs/heads/` prefix and use it as `PARENT_BRANCH`.
+3. Run `git reset --hard "origin/${PARENT_BRANCH}"`.
+
+If step 2 yields no match, or step 3 fails, stop and report the issue — do not make changes against an unsynchronized worktree.
+
+---
+
 You are a senior developer who specializes in diagnosing and fixing
 bugs. You follow a disciplined approach: understand the bug, find the
 root cause, make a minimal fix, and verify it with a regression test.

package/templates/agents/universal/test-writer.md

@@ -9,6 +9,18 @@ skills:
   - testing
 ---
 
+## Worktree freshness preamble
+
+Before writing tests, synchronize this worktree to the parent checkout's committed state. The worktree harness bases off `origin/HEAD`, which may lag the parent's current branch. Follow these steps and report the result:
+
+1. Run `git fetch origin`.
+2. Run `git worktree list --porcelain`. Read the output and find the entry whose line `branch refs/heads/<name>` has a `<name>` that does NOT start with `worktree-agent-` — that's the parent's current branch. Strip the `refs/heads/` prefix and use it as `PARENT_BRANCH`.
+3. Run `git reset --hard "origin/${PARENT_BRANCH}"`.
+
+If step 2 yields no match, or step 3 fails, stop and report the issue — tests written against a stale worktree will not cover the code you were asked about.
+
+---
+
 You are a test specialist. You write comprehensive, meaningful tests
 for recently changed code. You focus on testing behavior (what the code
 does) not implementation (how it does it). You work in a worktree to

package/templates/agents/universal/verify-app.md

@@ -9,6 +9,18 @@ initialPrompt: "/start"
 criticalSystemReminder: "CRITICAL: You are verification-only. Do NOT edit or fix code. Report findings with exact reproduction steps."
 ---
 
+## Worktree freshness preamble
+
+Before running any verification, synchronize this worktree to the parent checkout's committed state. The worktree harness bases off `origin/HEAD`, which may lag the parent's current branch. Follow these steps and report the result:
+
+1. Run `git fetch origin`.
+2. Run `git worktree list --porcelain`. Read the output and find the entry whose line `branch refs/heads/<name>` has a `<name>` that does NOT start with `worktree-agent-` — that's the parent's current branch. Strip the `refs/heads/` prefix and use it as `PARENT_BRANCH`.
+3. Run `git reset --hard "origin/${PARENT_BRANCH}"`.
+
+If step 2 yields no match, or step 3 fails, stop and report the issue — verification against a stale worktree is meaningless.
+
+---
+
 You are a verification specialist. You test the actual running
 application to confirm that implemented features work correctly
 end-to-end. Unit tests passing is not enough — you verify the real

package/templates/skills/universal/subagent-usage.md

@@ -67,7 +67,7 @@ coordination overhead grows.
 Some agents use `git worktree` to make changes without affecting your working tree:
 
 How it works:
-1. Agent creates a worktree from your current branch
+1. Agent creates a worktree based on `origin/HEAD` (see gotcha below)
 2. Makes changes in the worktree (isolated from your files)
 3. Commits changes
 4. You merge or cherry-pick the results
@@ -75,6 +75,19 @@ How it works:
 Agents with worktree isolation: code-simplifier, test-writer, verify-app, ci-fixer,
 bug-fixer, refactorer, doc-writer.
 
+### Base-branch gotcha
+
+Both `claude --worktree` and the Agent `isolation: "worktree"` option create the
+worktree from `origin/HEAD`, **not** your current branch. If your working branch is
+ahead of whatever `origin/HEAD` points to (typically `origin/main`), the worktree
+will miss those commits.
+
+Run `worclaude doctor` to diagnose. Fix locally with `git remote set-head origin
+<your-branch>` (reversible via `--auto` or `main`). The bundled `bug-fixer`,
+`verify-app`, and `test-writer` agents include a freshness preamble that resets
+their worktree to match the parent's current branch automatically; other worktree
+agents do not.
+
 Benefits:
 - Agent's changes don't conflict with your uncommitted work
 - You can review agent changes before merging