@benzotti/jdi 0.1.46 → 0.1.47

package/dist/index.js

@@ -12791,7 +12791,7 @@ var stateCommand = defineCommand({
 // package.json
 var package_default = {
   name: "@benzotti/jdi",
-  version: "0.1.46",
+  version: "0.1.47",
   description: "JDI - Context-efficient AI development framework for Claude Code",
   type: "module",
   bin: {

package/framework/agents/jdi-planner.md

@@ -22,7 +22,7 @@ Do not add unrelated extras (tooling, testing, linting, CI) unless the user expl
 2. **DO investigate the full scope of the request.** "Scope discipline" means no unrelated additions — it does NOT mean ignoring requirements that are clearly implied by the request. If the user asks for a UI view with specific columns, you must verify those columns exist in the backend response, and plan to add them if they don't.
 3. **When reference PRs/tickets are provided, analyse them thoroughly.** Read the actual diff, files changed, patterns used, columns/fields added, routes created, and data flow. The user provides reference PRs so you follow the same pattern — extract the full pattern, don't just skim.
 4. **When the user says "backend is already done", verify it.** Read the actual API endpoint, check what fields it returns, and confirm they match the frontend requirements. If there's a gap, include it in the plan.
-5. **Do not make subjective decisions.** If something is ambiguous (e.g. folder structure, routing library, state management), list it as an open question and ask the user — do not guess.
+5. **Do not make subjective decisions.** If something is ambiguous (e.g. folder structure, routing library, state management), list it as an open question and ask the user — do not guess. If pre-answered questions cover a decision point, use the pre-answered value rather than listing it as open.
 6. **Suggest optional additions separately.** After presenting the plan, list 3-5 common additions the user might want. These are suggestions, NOT part of the plan.
 7. **Same request = same plan.** Two identical requests must produce structurally identical plans. Achieve this by following the templates exactly and not improvising.
 
@@ -33,6 +33,22 @@ Before planning, ALWAYS:
 2. Apply any team preferences found (e.g. "always use path aliases", "prefer Zustand over Redux")
 3. Learnings override your defaults — if the team has a preference, follow it
 
+## CRITICAL: Respect Pre-Answered Questions
+
+When the spawn prompt includes a `PRE_ANSWERED_QUESTIONS` block:
+
+1. Parse each question-id and chosen answer
+2. Treat these as settled decisions — do NOT re-ask them
+3. Do NOT surface them as "Open Questions" in the plan
+4. Reference them in relevant task descriptions as
+   "Decision: {question} → {answer} (pre-plan gate)"
+5. Only surface NEW questions that genuinely emerged DURING
+   planning and could not have been anticipated from the
+   feature description alone
+
+Pre-answered questions represent explicit user choices made via
+interactive prompts. Overriding them silently is forbidden.
+
 ## CRITICAL: File Writing is Mandatory
 
 You MUST write files using Write/Edit tools. Returning plan content as text is NOT acceptable.

package/framework/agents/jdi-researcher.md

@@ -55,6 +55,78 @@ Write to `.jdi/research/{topic}-research.md`.
 
 ---
 
+## Pre-Plan Discovery Mode
+
+**Trigger:** Spawned by `create-plan` with mode flag `--pre-plan-discovery`.
+
+This is a lightweight, fast mode — NOT a full research report. The goal is to identify decision points in the codebase that the user should resolve before planning begins.
+
+### Constraints
+
+- **Budget:** Read at most 15 files
+- **Output:** Under 400 words
+- **No file writes** — do not create `.jdi/research/` files in this mode
+
+### Input
+
+- Feature description
+- `PRE_DISCOVERED_CONTEXT` (scaffolding already read by the orchestrator)
+
+### What to Look For
+
+Scan the codebase for decision points relevant to the feature:
+
+- **Competing patterns** — e.g. two state management approaches, two API styles, inconsistent naming conventions
+- **Missing data/fields** — the feature implies data that doesn't exist yet in current schemas/models
+- **Architectural choices** — where to put new code, which module to extend, whether to create a new module
+- **Dependency/library choices** — feature needs a capability the project doesn't have yet
+- **Existing conventions** — patterns that constrain the approach (established test patterns, folder structure, naming)
+
+### Output Format
+
+Return a structured YAML `RESEARCH_QUESTIONS` block:
+
+```yaml
+RESEARCH_DISCOVERY:
+  research_questions:
+    - id: RQ-01
+      question: "The codebase uses both X and Y for Z — which should this feature follow?"
+      header: "PATTERN"
+      options:
+        - label: "Use X"
+          description: "Consistent with src/foo/ — the newer pattern"
+        - label: "Use Y"
+          description: "Consistent with src/bar/ — the legacy pattern"
+      context: "Found X in src/foo/*.ts (3 files), Y in src/bar/*.ts (7 files)"
+    - id: RQ-02
+      question: "..."
+      header: "..."
+      options:
+        - label: "..."
+          description: "..."
+      context: "..."
+  research_context: "Brief summary of what was found for the planner"
+```
+
+Each question must include:
+- `id`: Sequential ID (`RQ-01`, `RQ-02`, ...)
+- `question`: Clear, specific question text
+- `header`: Category tag, max 12 chars (`PATTERN`, `STACK`, `DATA`, `APPROACH`, `BOUNDARY`)
+- `options`: 2-4 options with `label` and `description` grounded in codebase findings
+- `context`: Brief note on what evidence was found
+
+### If No Questions Found
+
+Return an empty array with a brief context summary. This is a valid outcome for clear-cut features:
+
+```yaml
+RESEARCH_DISCOVERY:
+  research_questions: []
+  research_context: "Scanned src/components/ and src/api/. Single pattern in use (React Query + Zustand). No competing approaches or ambiguous extension points found."
+```
+
+---
+
 ## Structured Returns
 
 ```yaml

package/framework/commands/build.md

@@ -1,7 +1,7 @@
 ---
 name: build
 description: "JDI: Guided setup and state-aware entry point for new and returning users"
-allowed-tools: Read, Glob, Grep, Bash
+allowed-tools: Read, Glob, Grep, Bash, AskUserQuestion
 argument-hint: "[no arguments]"
 context: |
   !cat .jdi/config/state.yaml 2>/dev/null | head -20
@@ -51,6 +51,19 @@ If NEITHER condition is true, the user is new — proceed to step 3.
 
 Present exactly these four options. Frame them for software projects — no game-specific language, no engine/prototype vocabulary.
 
+**Preferred: AskUserQuestion.** Use AskUserQuestion with:
+- **header:** `STAGE`
+- **question:** `Which of these describes your situation best?`
+- **options:**
+  1. label: `No idea yet` — description: `I want to figure out what to build`
+  2. label: `Vague idea` — description: `I know the problem but not the shape of the solution`
+  3. label: `Clear concept` — description: `I know what I want to build and roughly how`
+  4. label: `Existing work` — description: `There's already code or scaffolding I want to continue from`
+
+The automatic "Other" option covers situations that don't fit. Route based on the selected option — same branch logic as step 4.
+
+**Fallback (if AskUserQuestion is unavailable):** Present as plain markdown instead:
+
 > **Welcome to JDI.**
 >
 > Before I suggest anything, I'd like to understand where you are. Which of these describes your situation best?
@@ -98,7 +111,16 @@ Each branch below is its own script. Follow the one that matches the user's choi
 
 ### 5. Confirm Before Handing Off
 
-After presenting your recommendation, ask this exact question:
+After presenting your recommendation, confirm with the user before proceeding.
+
+**Preferred: AskUserQuestion.** Use AskUserQuestion with:
+- **header:** `NEXT`
+- **question:** `Ready to proceed?`
+- **options:**
+  1. label: `{recommended command}` — description: `Start with the recommended next step`
+  2. label: `Something else` — description: `I want to do something different`
+
+**Fallback (if AskUserQuestion is unavailable):** Ask as plain text instead:
 
 > "Would you like to start with **{recommended command}**, or something else?"
 

package/framework/commands/create-plan.md

@@ -1,7 +1,7 @@
 ---
 name: create-plan
 description: "JDI: Create implementation plan"
-allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task, AskUserQuestion
 argument-hint: "<feature to plan> [--worktree | --worktree-lightweight | --status]"
 context: |
   !cat .jdi/config/state.yaml 2>/dev/null | head -25
@@ -12,7 +12,7 @@ context: |
 
 Create an implementation plan using a single planner agent (includes research). Deterministic workflow — every invocation follows the same numbered steps, in order, without skipping.
 
-**This skill follows `<JDI:StrictnessProtocol />` and `<JDI:SilentDiscovery />`. Read those components before executing any step below.**
+**This skill follows `<JDI:StrictnessProtocol />`, `<JDI:SilentDiscovery />`, and `<JDI:InteractiveGate />`. Read those components before executing any step below.**
 
 ---
 
@@ -89,6 +89,30 @@ If the feature description looks trivial (single file, <30 minutes, no architect
 
 **Wait for the user's answer. Do not proceed until they respond.** If they pick quick, STOP — do not spawn the planner.
 
+### 4a. Pre-Plan Research Spawn
+
+Spawn `jdi-researcher` in `pre-plan-discovery` mode via `Task(subagent_type="general-purpose")`. The spawn prompt MUST include:
+
+- The feature description (`$ARGUMENTS`)
+- `PRE_DISCOVERED_CONTEXT` as a YAML block
+- Mode: `--pre-plan-discovery`
+- Spec path: `.jdi/framework/agents/jdi-researcher.md`
+- Instruction: _"Scan the codebase for decision points relevant to this feature. Return RESEARCH_QUESTIONS YAML. Budget: <=15 file reads, <400 word report."_
+
+Store the return as `RESEARCH_DISCOVERY`.
+
+### 4b. Pre-Planning Questions (Interactive Gate)
+
+Execute `<JDI:InteractiveGate mode="pre-plan" />`:
+
+1. Collect surface-level ambiguity questions from the feature description
+2. Collect research-driven questions from `RESEARCH_DISCOVERY.research_questions`
+3. Merge, deduplicate, prioritise (research-driven first)
+4. If questions exist, present via `AskUserQuestion`. Wait for answers.
+5. If zero questions from both sources, skip silently.
+
+Store answers as `PRE_ANSWERED_QUESTIONS`.
+
 ### 5. Spawn Planner
 
 Spawn `jdi-planner` via `Task(subagent_type="general-purpose")`. The spawn prompt MUST include:
@@ -96,7 +120,9 @@ Spawn `jdi-planner` via `Task(subagent_type="general-purpose")`. The spawn promp
 - The feature description (`$ARGUMENTS`)
 - `PRE_DISCOVERED_CONTEXT` as a YAML block — planner must NOT re-read scaffolding
 - `AVAILABLE_AGENTS` catalogue — planner pins specialists via AgentRouter
-- Explicit instruction: _"Do NOT re-prompt the user for anything already in PRE_DISCOVERED_CONTEXT. Surface open questions ONLY for facts you cannot infer."_
+- `PRE_ANSWERED_QUESTIONS` YAML block (from step 4b, if any questions were asked)
+- `RESEARCH_DISCOVERY.research_context` (so the planner doesn't re-scan what the researcher already found)
+- Explicit instruction: _"Do NOT re-prompt the user for anything already in PRE_DISCOVERED_CONTEXT. These questions were already answered by the user — do NOT re-ask them. The research context below summarises what was found in the codebase — use it, don't re-scan. Only surface NEW questions that emerged during planning that could not have been anticipated."_
 - Spec path: `.jdi/framework/agents/jdi-planner.md`
 
 The planner creates split plan files (index `.plan.md` + per-task `.T{n}.md` files) directly via Write tool (sandbox override for plan files). It writes `available_agents:` into the index frontmatter and pins an `agent:` field in every task file.
@@ -156,7 +182,9 @@ Pre-written responses for known deviations. When one applies, follow the scripte
 |-----------|----------|
 | Scaffolding files missing (`.jdi/PROJECT.yaml` etc.) | Planner creates them from `framework/templates/` in step 5. Do NOT ask the user for values the template's defaults cover. |
 | `.claude/agents/` empty on both levels | Set `AVAILABLE_AGENTS = []`, note in summary, and proceed. The planner falls back to tech-stack defaults. |
-| Feature description is vague ("improve X") | Ask 2-3 targeted follow-ups BEFORE spawning the planner. Do not waste a planner invocation on an underspecified prompt. |
+| Feature description is vague ("improve X") | Steps 4a + 4b handle this: the researcher discovers codebase decision points, and the InteractiveGate surfaces ambiguity questions via AskUserQuestion. Do not waste a planner invocation on an underspecified prompt. |
+| Pre-plan researcher returns zero questions | Skip step 4b if surface-level analysis also yields zero questions. Proceed directly to step 5. This is expected for clear features. |
+| Pre-plan researcher returns >4 questions | Batch into multiple AskUserQuestion calls (max 4 per call). Present highest-priority questions first. |
 | Worktree flag but worktree already exists | Ask the user: reuse the existing worktree, or pick a new name? Do not silently proceed. |
 | `--status` with no current plan | Output "No current plan — run `/jdi:create-plan \"<feature>\"` to create one" and STOP. |
 | Planner returns without writing any files | STOP, report the failure, do NOT advance state. Ask the user to re-invoke or debug. |

package/framework/commands/implement-plan.md

@@ -1,7 +1,7 @@
 ---
 name: implement-plan
 description: "JDI: Execute implementation plan"
-allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task, AskUserQuestion
 argument-hint: "[--team | --single | --dry-run | --skip-qa]"
 context: |
   !cat .jdi/config/state.yaml 2>/dev/null | head -30
@@ -120,6 +120,27 @@ For split plans, the agent reads task files one at a time via the `file:` field
 
 **Wave-based execution:** honour `waves:` from the plan frontmatter. Spawn all tasks in wave N in parallel; wait for all returns before starting wave N+1.
 
+### 8a. Blocker Resolution
+
+When an agent returns `status: blocked`:
+
+1. Read the blocker context from the agent's structured return
+   (blocker_reason, blocker_context, suggested_options if any)
+2. Execute `<JDI:InteractiveGate mode="blocker-resolution" />`
+3. Present the blocker to the user via AskUserQuestion:
+   - header: "BLOCKED"
+   - question: "{task_name} is blocked: {blocker_reason}"
+   - options (pick 2-4 based on context):
+     a) Resolve with approach X (if agent suggested options)
+     b) Skip this task and continue
+     c) Modify the task scope
+     d) Halt the plan
+4. Route based on answer:
+   - Resolve: re-spawn the agent with the resolution context
+   - Skip: advance-task with skip status, continue to next
+   - Modify: enter inline edit of the task file, then re-spawn
+   - Halt: stop execution, enter review loop at step 14
+
 ### 9. Advance Task State
 
 After each task's programmer returns successfully, run:
@@ -185,7 +206,8 @@ Pre-written responses for known deviations. When one applies, follow the scripte
 | Plan status is not `approved` | STOP at step 2. Tell the user to approve the plan first. Do NOT force-advance. |
 | Pinned agent not installed | Downgrade to `general-purpose`, record the downgrade, continue. Surface in the final summary. |
 | Task file missing (listed in `task_files:` but not on disk) | STOP. Report the missing file. Do NOT advance state. |
-| Programmer returns with `status: blocked` | HALT the plan. Do NOT advance task state. Surface the blocker to the user and wait. |
+| Programmer returns with `status: blocked` | Enter step 8a (Blocker Resolution). Do NOT advance task state. Present the blocker interactively via AskUserQuestion and route based on user's choice. |
+| Agent suggests resolution options in structured return | Include agent's suggestions as the first AskUserQuestion options in step 8a, before the default options (skip/modify/halt). |
 | QA verification S1 or S2 failure | HALT the plan immediately. Record the failure in state. Wait for user direction before continuing. |
 | Verification gate failure at step 12 | STOP before completing. Report the failure, enter review loop. Do NOT advance state to `complete`. |
 | `--dry-run` with no changes needed | Output "no-op: plan is already at target state" and STOP. |

package/framework/components/meta/InteractiveGate.md

@@ -0,0 +1,138 @@
+# InteractiveGate Component
+
+A reusable question gate that presents structured decisions to the user via `AskUserQuestion` before a phase transition. Questions are sourced from two channels: surface-level ambiguity detection and research-driven codebase analysis.
+
+When a command references `<JDI:InteractiveGate mode="..." />`, execute the steps below. Do NOT skip the merge/dedup logic even if only one source produces questions.
+
+---
+
+## Modes
+
+| Mode | When | Question Sources |
+|------|------|-----------------|
+| `pre-plan` | Before planner spawn in `create-plan` | Surface-level analysis of feature description + `RESEARCH_QUESTIONS` from pre-plan research spawn |
+| `blocker-resolution` | During implementation when a task is blocked | Surface-level analysis of the blocker description + context from the blocking task |
+
+---
+
+## Question Sources
+
+### Surface-Level (Ambiguity Detection)
+
+Analyse the feature description (or blocker description) for ambiguity signals:
+
+- **Vague scope words** — "improve", "enhance", "refactor", "clean up", "optimise" without measurable targets
+- **Missing tech stack specifics** — feature implies a technology choice but doesn't state one
+- **Unclear boundaries** — "and more", "etc.", "various", "all the things"
+- **Multiple possible approaches** — description could be solved in fundamentally different ways
+- **Implicit assumptions** — feature assumes context the user hasn't stated
+
+Generate questions only for genuine ambiguities. Do NOT manufacture questions for clear descriptions.
+
+### Research-Driven
+
+Consume the `RESEARCH_QUESTIONS` YAML block produced by the pre-plan research spawn (or equivalent). These are decision points discovered by analysing the actual codebase:
+
+- Competing patterns (e.g. two state management approaches in use)
+- Missing data/fields the feature will need
+- Architectural choices (where to place new code, which module to extend)
+- Dependency/library choices
+- Existing conventions that constrain the approach
+
+Research-driven questions arrive pre-formatted with `id`, `question`, `header`, `options`, and `context`.
+
+---
+
+## Merge and Prioritise
+
+1. Collect surface-level questions (assign IDs `SQ-01`, `SQ-02`, ...)
+2. Collect research-driven questions (IDs `RQ-01`, `RQ-02`, ... from the researcher)
+3. Deduplicate: if a surface question covers the same decision as a research question, keep the research version (it has codebase-grounded options)
+4. Sort: research-driven questions first (higher signal), then surface-level
+5. Cap at a reasonable total — if more than 8 questions survive, drop the lowest-priority surface-level questions
+
+---
+
+## AskUserQuestion Format
+
+Each question presented via `AskUserQuestion` must follow this structure:
+
+- **`header`**: Short category tag — max 12 characters. Examples: `SCOPE`, `STACK`, `APPROACH`, `PATTERN`, `DATA`, `BOUNDARY`
+- **`question`**: The actual question text. Clear, specific, and actionable.
+- **`options`**: 2-4 options, each with:
+  - `label`: Short option name
+  - `description`: One-line explanation. For research-driven questions, ground this in what the researcher found in the codebase.
+- **`multiSelect`**: Set to `true` only for non-mutually-exclusive choices. Default `false`.
+- An automatic "Other" option is always available (built into the tool).
+
+**Batching rule:** Maximum 4 questions per `AskUserQuestion` call (tool limit). If more than 4 questions survive merge, batch into multiple sequential calls. Present the highest-priority questions first.
+
+---
+
+## Output Format
+
+Store all answers as `PRE_ANSWERED_QUESTIONS` in YAML:
+
+```yaml
+PRE_ANSWERED_QUESTIONS:
+  - id: RQ-01
+    source: research
+    question: "The codebase uses both Redux and Zustand — which should this feature follow?"
+    chosen: "Use Zustand"
+    custom_text: null
+  - id: SQ-01
+    source: surface
+    question: "What does 'improve performance' mean concretely?"
+    chosen: "Reduce load time below 2s"
+    custom_text: "Specifically the dashboard page load"
+```
+
+Fields:
+- `id`: Question ID (`RQ-*` for research, `SQ-*` for surface)
+- `source`: `research` or `surface`
+- `question`: The question text (for downstream reference)
+- `chosen`: The selected option label (or "Other" if custom)
+- `custom_text`: User's free-text input if they chose "Other", otherwise `null`
+
+---
+
+## Skip Condition
+
+If BOTH sources yield zero questions after analysis, skip the gate entirely. Do NOT present an empty AskUserQuestion call. Proceed directly to the next step in the parent workflow.
+
+Log internally: `InteractiveGate: 0 questions from surface + 0 from research — skipping gate.`
+
+---
+
+## Fallback
+
+If `AskUserQuestion` is not available (not in the skill's `allowed-tools` list), fall back to plain markdown:
+
+```
+Before we proceed, I have a few questions:
+
+1. **[PATTERN]** The codebase uses both X and Y for Z — which should this feature follow?
+   - A) Use X — consistent with src/foo/ (newer pattern)
+   - B) Use Y — consistent with src/bar/ (legacy pattern)
+   - C) Other (please specify)
+
+2. **[SCOPE]** What does "improve" mean concretely?
+   - A) Reduce load time below 2s
+   - B) Reduce memory usage
+   - C) Other (please specify)
+
+Please respond with your choices (e.g. "1A, 2B") or provide details.
+```
+
+Parse the user's response and populate `PRE_ANSWERED_QUESTIONS` accordingly.
+
+---
+
+## Usage
+
+```
+<JDI:InteractiveGate mode="pre-plan" />
+<JDI:InteractiveGate mode="blocker-resolution" />
+```
+
+Referenced within a skill's numbered workflow steps. Requires that question sources (surface analysis input and/or `RESEARCH_QUESTIONS` block) are available in the execution context before invocation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@benzotti/jdi",
-  "version": "0.1.46",
+  "version": "0.1.47",
   "description": "JDI - Context-efficient AI development framework for Claude Code",
   "type": "module",
   "bin": {