worclaude 2.7.0 → 2.7.1

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to worclaude are documented in this file. Format loosely fol
 
 ## [Unreleased]
 
+## [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.7.1",
   "description": "The Workflow Layer for Claude Code — scaffold agents, commands, skills, hooks, and memory into any project",
   "type": "module",
   "bin": {

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/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:
 
 ```