worclaude 2.7.0 → 2.8.0

package/CHANGELOG.md

@@ -4,6 +4,42 @@ 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.
+
+### Fixed
+
+- **`/setup` `?` help trigger → `help` keyword** (PR #119) — 9 occurrences across CONFIRM_HIGH + CONFIRM_MEDIUM prompt templates, response-parsing bullets, error restates, and the Field-help table intro. Explanatory notes added so future maintainers don't re-add `?`.
+- **`worclaude init` prompt-type consistency** (PR #119) — `runOptionalExtras` (src/commands/init.js:77-93) converted the plugin.json and gtd-memory prompts from `type: 'confirm'` (the only `(y/N)` text inputs in init) to `type: 'list'` with boolean-valued Yes/No choices. Regression test inspects `inquirer.prompt.mock.calls` directly.
+
+### Changed
+
+- **`/setup` CONFIRM_MEDIUM (≤4 options) uses `AskUserQuestion`** (PR #119) — State 3 split into Path 1 (AskUserQuestion path) and Path 2 (verbatim text fallback, >4 options). Rule #5 widens the AskUserQuestion permit to include CONFIRM_MEDIUM. Rule #7 picks up an explicit EXCEPTION paragraph. Storage rule from v2.6.5 (`mediumResolved[field]` must be a string) applies uniformly across both paths.
+
+### Docs
+
+- **`docs/spec/SPEC.md` `/setup` section** (this /sync) — reflects the `help`-keyword-only trigger and the CONFIRM_MEDIUM ≤4-option AskUserQuestion path.
+- **`docs/spec/PROGRESS.md`** (this /sync) — new v2.7.1 release entry; Stats refreshed (782 → 788 tests).
+
 ## [2.7.0] — 2026-04-23
 
 `/setup` hardening + UX revamp release. PR #115 closes 8 backend bug clusters surfaced by the v2.6.3 manual test matrix (upgrade-flow correctness, downgrade guard, doctor ghost detection, scaffolder exec bits, Commander routing). PR #116 fixes four `/setup` template failure modes — missing `schemaVersion` in SCAN state, `readme` object-shape mismatch in CONFIRM_MEDIUM, all-22-questions-asked despite detection, accept-off-topic-as-answer — and adds a `--from-file` flag to `worclaude setup-state save` plus `Bash(worclaude:*)` permissions so `/setup` runs without approval-prompt interruption. PR #117 adopts Claude Code's `AskUserQuestion` tool for 10 enumerable interview questions (arrow-key selection instead of free-text), redesigns CONFIRM prompts with a "Will be saved as" consequence sub-line and `?` / `help` command, and drops the 80-char readme truncation so users can read the full description before accepting. Dogfood-relevant: `.claude/commands/setup.md` auto-updates on `worclaude upgrade` to pick up the new template.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worclaude",
-  "version": "2.7.0",
+  "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/src/commands/init.js

@@ -77,16 +77,24 @@ async function runAgents(selections) {
 async function runOptionalExtras(selections) {
   const { generatePluginJson, scaffoldGtdMemory } = await inquirer.prompt([
     {
-      type: 'confirm',
+      type: 'list',
       name: 'generatePluginJson',
       message: 'Generate .claude-plugin/plugin.json for marketplace compatibility?',
-      default: selections.generatePluginJson || false,
+      choices: [
+        { name: 'Yes', value: true },
+        { name: 'No', value: false },
+      ],
+      default: selections.generatePluginJson === true ? 0 : 1,
     },
     {
-      type: 'confirm',
+      type: 'list',
       name: 'scaffoldGtdMemory',
       message: 'Scaffold structured memory files (decisions.md, preferences.md)?',
-      default: selections.scaffoldGtdMemory || false,
+      choices: [
+        { name: 'Yes', value: true },
+        { name: 'No', value: false },
+      ],
+      default: selections.scaffoldGtdMemory === true ? 0 : 1,
     },
   ]);
   return { ...selections, generatePluginJson, scaffoldGtdMemory };

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/commands/setup.md

@@ -65,11 +65,16 @@ normally apply.
    - Read: `.claude/cache/setup-state.json`
    - Write: `.claude/cache/setup-state.draft.json` (state-save staging
      only — overwritten each save).
-   - Tool: `AskUserQuestion` (INTERVIEW states only, per the
-     Interaction mode contract — `selectable` / `multi-selectable`
-     questions). Not permitted at CONFIRM_HIGH / CONFIRM_MEDIUM:
-     those render VERBATIM per rule #7 so the text-parser contract
-     stays stable.
+   - Tool: `AskUserQuestion` permitted at:
+     - INTERVIEW states, per the Interaction mode contract
+       (`selectable` / `multi-selectable` / `hybrid` questions).
+     - CONFIRM_MEDIUM when the per-item option count (candidates + 1
+       for "Other") is ≤ 4 — AskUserQuestion's own `maxItems: 4`
+       schema cap. When the count exceeds 4, fall back to the verbatim
+       text-parse rendering defined in State 3 below.
+     Not permitted at CONFIRM_HIGH: the detection list routinely has
+     12+ items in real projects, which exceeds the 4-option schema cap.
+     CONFIRM_HIGH renders VERBATIM per rule #7.
 
    At WRITE state the whitelist RELAXES to additionally permit:
 
@@ -92,15 +97,23 @@ normally apply.
    project only. Only use information the user provides during THIS
    interview and the detection report for THIS project.
 
-7. **RENDER PROMPTS VERBATIM.** Where a state specifies a prompt format
-   with `[x] 1. ...` syntax or other structured output, render it
-   EXACTLY as specified AND wrap it in a triple-backtick fenced code
-   block so Markdown rendering does not reformat checkboxes or
-   renumber lines. The format is part of the contract with the
+7. **RENDER PROMPTS VERBATIM.** Where a state specifies a text-parse
+   prompt format with `[x] 1. ...` syntax or other structured output,
+   render it EXACTLY as specified AND wrap it in a triple-backtick
+   fenced code block so Markdown rendering does not reformat checkboxes
+   or renumber lines. The format is part of the contract with the
    user-response parser — paraphrasing or reformatting breaks parsing.
    You MAY add a brief conversational sentence before or after a
    verbatim prompt, but NOT within it.
 
+   EXCEPTION — CONFIRM_MEDIUM via AskUserQuestion: when the per-item
+   option count is ≤ 4 (candidates + "Other"), State 3 uses the
+   `AskUserQuestion` tool path instead of the verbatim text prompt
+   (see rule #5 and State 3). The verbatim-rendering requirement does
+   not apply to tool invocations. When the count exceeds 4, the text
+   fallback kicks in and this rule applies as written. CONFIRM_HIGH
+   never uses AskUserQuestion (detection lists routinely exceed 4).
+
    KNOWN FAILURE MODES: reformatting `[x] 1. X: Y` as `- [x] X: Y`
    (loses numbering); paraphrasing labels; collapsing items onto one
    line; rendering outside a fenced block (Markdown may convert `[x]`
@@ -235,7 +248,7 @@ ENTRY:
   ```
   I scanned your project. Please confirm the high-confidence
   detections below. Reply with the numbers of any items that are
-  WRONG (e.g., "2, 5"), or reply "ok" to accept all, or "?" for help.
+  WRONG (e.g., "2, 5"), or reply "ok" to accept all, or type "help".
 
     [x] 1. <formatField(item1.field)>: <renderValue(item1)> (from <item1.source>)
            → Will be saved as: <target1>
@@ -257,13 +270,15 @@ Response parsing (case-insensitive, whitespace trimmed):
 - One or more integers (comma or space separated) in range 1..N →
   those items are rejected; split fields into accepted/rejected
   accordingly (in rendered order).
-- `?` | `help` → render the **Field-help** block for EACH displayed
-  field (description + target + example) without advancing state. Then
+- `help` → render the **Field-help** block for EACH displayed field
+  (description + target + example) without advancing state. Then
   restate the prompt above (same text, same items). Do NOT persist a
-  mutation for the help render.
+  mutation for the help render. (`?` is intentionally NOT a trigger —
+  Claude Code binds it to a keyboard-shortcut overlay that intercepts
+  the keystroke before /setup sees it.)
 - Anything else (including integers out of range) → rule #3 fires:
   restate with "I need either 'ok', numbers from 1 to `<N>` matching
-  the items above (e.g., '2, 5'), or `?` for help. To cancel, type
+  the items above (e.g., '2, 5'), or type `help`. To cancel, type
   `cancel setup`."
 
 State file mutation: persist the updated arrays via
@@ -280,69 +295,117 @@ ENTRY:
   report.
 - If there are zero medium-confidence items: persist
   `mediumResolved: {}`, transition to INTERVIEW_STORY.
-- Otherwise iterate in report order. For each medium item, render ONE
-  prompt VERBATIM in a fenced code block. The prompt shape depends on
-  `item.candidates`:
+- Otherwise iterate in report order. For each medium item, compute the
+  total option count:
+  - Shape A (`candidates === null`, emitted by `readme`):
+    `1 + 1` = 2 (detected value + "Other").
+  - Shape B (`candidates` is a non-empty array): `candidates.length + 1`.
+  If the total is ≤ 4, use the **AskUserQuestion path** (Path 1).
+  Otherwise fall back to the **verbatim text-parse path** (Path 2).
+  The threshold is the `maxItems: 4` schema cap of AskUserQuestion.
+
+#### Path 1 — AskUserQuestion (option count ≤ 4)
+
+Invoke the `AskUserQuestion` tool once per medium item with exactly
+this shape:
+
+- `question`: `<formatField(field)> — detected from <source>. Which
+  should I use?`
+- `header`: short label for the sidebar (≤ 12 chars) — typically
+  `formatField(field)` truncated.
+- `multiSelect`: `false`
+- `options`: built from the Shape above:
+  - Shape A: `[{ label: <renderValue(item)>, description: "Will be
+    saved as <target>. Accept the detected value." },
+    { label: "Other (I'll type my own)", description: "Supply a
+    custom value via free-text follow-up." }]`
+  - Shape B: one option per `candidates[k]` with
+    `description: "Will be saved as <target>."`; append
+    `{ label: "Other (I'll type my own)", description: "Supply a
+    custom value via free-text follow-up." }` as the final option.
+
+`<target>` comes from the **Field-help table** below. Render it
+verbatim per the table.
+
+On response:
+- User selects a candidate label → store that label string in
+  `mediumResolved[field]` (Storage rule applies).
+- User selects "Other (I'll type my own)" → follow up with a free-text
+  prompt: "Go ahead — what's the value you'd like to use?". Store the
+  trimmed reply.
+
+`AskUserQuestion` does not expose a `help` trigger; the per-option
+`description` text carries the equivalent content inline. The text
+fallback's `help` keyword is scoped to Path 2 only.
+
+#### Path 2 — Verbatim text prompt (option count > 4)
+
+Render ONE prompt VERBATIM in a fenced code block. The prompt shape
+depends on `item.candidates`:
+
+**Shape A — `candidates === null`** (rare in this path — only 2
+options, typically handled by Path 1 above; included here for
+completeness in case AskUserQuestion is unavailable):
 
-  **Shape A — `candidates === null`** (emitted by `readme`):
-
-  ```
-  <formatField(field)> (detected from <source>):
-
-    1. <renderValue(item)>
-       → Will be saved as: <target>
-    2. Other (I'll type my own)
-
-  Reply with the number of your choice (default: 1), or `?` for help:
-  ```
+```
+<formatField(field)> (detected from <source>):
 
-  **Shape B — `candidates` is a non-empty array** (emitted by
-  `package-manager` when multiple lockfile groups disagree):
+  1. <renderValue(item)>
+     → Will be saved as: <target>
+  2. Other (I'll type my own)
 
-  ```
-  <formatField(field)> (detected from <source>):
-  → Will be saved as: <target>
+Reply with the number of your choice (default: 1), or type `help`:
+```
 
-    1. <candidates[0]>
-    2. <candidates[1]>
-    ...
-    N. <candidates[N-1]>
-    N+1. Other (I'll type my own)
+**Shape B — `candidates` is a non-empty array** (e.g.,
+`package-manager` when multiple lockfile groups disagree and produce
+4+ candidates):
 
-  Reply with the number of your choice (default: 1), or `?` for help:
-  ```
+```
+<formatField(field)> (detected from <source>):
+→ Will be saved as: <target>
 
-  `<target>` comes from the **Field-help table** below. Render it
-  verbatim per the table.
+  1. <candidates[0]>
+  2. <candidates[1]>
+  ...
+  N. <candidates[N-1]>
+  N+1. Other (I'll type my own)
 
-  `candidates[0]` equals `item.value` — default-1 accepts the detected
-  value.
+Reply with the number of your choice (default: 1), or type `help`:
+```
 
-**Storage rule:** `mediumResolved[field]` MUST be a string. Store the
-exact `renderValue(item)` that was shown to the user on option 1, or
-the user's trimmed free-text on "Other", or `candidates[k-1]` (shape
-B) for a numbered pick. **NEVER store the raw `item.value` object** —
-for fields like `readme` whose detected value is an object
-(`{projectDescription, setupInstructions, fullPath}`) the validator
-will reject the mutation with `state.mediumResolved.<field> must be a
-string`.
+`<target>` comes from the **Field-help table** below. Render it
+verbatim per the table. `candidates[0]` equals `item.value` —
+default-1 accepts the detected value.
 
-Response parsing (per item):
+Response parsing (Path 2 only):
 
 - `""` | `1` | `default` → accept item 1; store `renderValue(item)`
-  as a string per the Storage rule above.
+  as a string per the Storage rule.
 - The final "Other" number (`2` in shape A, `N+1` in shape B) →
   follow-up free-text prompt: "Go ahead — what's the value you'd like
   to use?". Store the trimmed reply.
 - Integer in range `2..N` (shape B only) → store `candidates[k-1]`.
-- `?` | `help` → render the **Field-help** block for this field
+- `help` → render the **Field-help** block for this field
   (description + target + example) without advancing state. Then
   restate the prompt above. Do NOT persist a mutation for the help
-  render.
+  render. (`?` is intentionally NOT a trigger — Claude Code binds it
+  to a keyboard-shortcut overlay that intercepts the keystroke.)
 - Anything else → restate with "I need a number from 1 to `<max>`,
-  empty for the default, or `?` for help. To cancel, type
+  empty for the default, or type `help`. To cancel, type
   `cancel setup`."
 
+#### Storage rule (both paths)
+
+`mediumResolved[field]` MUST be a string. Store the exact label that
+was shown to the user (Path 1: `AskUserQuestion` `label`; Path 2:
+`renderValue(item)` or `candidates[k-1]`), or the user's trimmed
+free-text on "Other". **NEVER store the raw `item.value` object** —
+for fields like `readme` whose detected value is an object
+(`{projectDescription, setupInstructions, fullPath}`) the validator
+will reject the mutation with `state.mediumResolved.<field> must be a
+string`.
+
 State file mutation: after EACH item is resolved (not batched),
 append to `mediumResolved` and persist.
 
@@ -635,7 +698,7 @@ knowledge the detector has no access to).
 
 ### Field-help table
 
-Drives the `?` / `help` command (CONFIRM_HIGH, CONFIRM_MEDIUM, and
+Drives the `help` command (CONFIRM_HIGH, CONFIRM_MEDIUM, and
 INTERVIEW states) AND the "→ Will be saved as: `<target>`" line on
 every CONFIRM prompt. Keep the `<target>` column stable — parsers
 downstream don't match on it, but users read it for orientation.
@@ -686,7 +749,7 @@ Interview questions (used at INTERVIEW states):
 | `verification.staging`         | Whether there's a staging / preview env                   | `## Verification` of `docs/spec/SPEC.md`                       | `yes — Vercel preview per PR`                 |
 | `verification.required_checks` | CI required checks gating merge                           | `## Verification` of `docs/spec/SPEC.md`                       | `tests, lint, type-check`                     |
 
-Help-render format when the user types `?` at a CONFIRM or INTERVIEW
+Help-render format when the user types `help` at a CONFIRM or INTERVIEW
 prompt — render in a fenced code block:
 
 ```

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