gsdd-cli 0.1.0 → 0.2.0

package/README.md

@@ -32,7 +32,7 @@ GSDD is a distilled fork of GSD. It preserves the high-leverage parts of long-ho
 - **Milestone audit** — cross-phase integration, requirements coverage, E2E flows
 - **Session management** — pause work with checkpoint, resume with context restoration and routing
 
-What it strips: GSD's broader operator surface (32 workflows, 11 agents, discovery modes, sprint ceremony, a settings flow, and additional operator ergonomics). GSDD has 10 workflows and 9 roles.
+What it strips: GSD's broader operator surface (32 workflows, 11 agents, discovery modes, sprint ceremony, a settings flow, and additional operator ergonomics). GSDD has 10 workflows and 10 roles.
 
 **Target user:** Developer or small team that wants a spec-driven long-horizon kernel, not full operator comfort.
 
@@ -250,9 +250,9 @@ Workflows are agent skills or commands, not plain shell utilities. How you invok
 
 ## Architecture
 
-### Roles (9 canonical)
+### Roles (10 canonical)
 
-GSDD consolidates GSD's agent surface into 9 roles with durable contracts:
+GSDD consolidates GSD's agent surface into 10 roles with durable contracts:
 
 | Role | Responsibility |
 |------|---------------|
@@ -271,7 +271,7 @@ GSDD consolidates GSD's agent surface into 9 roles with durable contracts:
 - **Role contracts** (`agents/*.md`) — durable, contain the full behavioral specification
 - **Delegates** (`distilled/templates/delegates/*.md`) — thin wrappers that reference roles and provide task-specific context
 
-10 delegates: 4 mapper, 4 researcher, 1 synthesizer, 1 plan-checker. Workflows use `<delegate>` blocks to dispatch work. For detailed GSD-to-GSDD role distillation rationale, see [`agents/DISTILLATION.md`](agents/DISTILLATION.md).
+11 delegates: 4 mapper, 4 researcher, 1 synthesizer, 1 plan-checker, 1 approach-explorer. Workflows use `<delegate>` blocks to dispatch work. For detailed GSD-to-GSDD role distillation rationale, see [`agents/DISTILLATION.md`](agents/DISTILLATION.md).
 
 ### Adapter Architecture
 
@@ -410,11 +410,11 @@ For detailed troubleshooting and recovery procedures, see the [User Guide](docs/
 
 ## Design Decisions
 
-GSDD makes 28 documented design decisions relative to GSD, each with evidence from source files and external research. See [`distilled/DESIGN.md`](distilled/DESIGN.md) for the full rationale.
+GSDD makes 29 documented design decisions relative to GSD, each with evidence from source files and external research. See [`distilled/DESIGN.md`](distilled/DESIGN.md) for the full rationale.
 
 Key choices:
 - **4-file codebase standard** — drop state that rots (STRUCTURE, INTEGRATIONS, TESTING), keep rules that don't
-- **Agent consolidation** — 9 roles from GSD's 11, with explicit reduced-assurance mode when independent checking isn't available
+- **Agent consolidation** — 10 roles from GSD's 11, with explicit reduced-assurance mode when independent checking isn't available
 - **Adapter generation over conversion** — generate vendor-specific files from vendor-agnostic markdown instead of converting from Claude-first
 - **Advisory git** — repo conventions over framework defaults
 - **Context isolation** — summaries up, documents to disk
@@ -436,8 +436,8 @@ Structural contracts that prevent drift between roles, delegates, workflows, and
 
 | Suite | What it guards |
 |-------|---------------|
-| **I1** | Delegate-role reference integrity — 10 delegates resolve to existing role contracts |
-| **I2** | Role section structure — 9 roles have role def, scope, output format, success criteria |
+| **I1** | Delegate-role reference integrity — 11 delegates resolve to existing role contracts |
+| **I2** | Role section structure — 10 roles have role def, scope, output format, success criteria |
 | **I3** | Delegate thinness — no leaked role-contract sections in delegates |
 | **I3-gate** | New-project approval gates — required human checkpoints present |
 | **I4** | Workflow references — 10 workflows, all delegate/role refs resolve |

package/agents/DISTILLATION.md

@@ -1,6 +1,6 @@
 # GSDD Role Distillation Ledger
 
-Evidence map from each of the 9 canonical GSDD roles to their GSD sources, with keep/strip/why rationale. This ledger documents why each role exists in its current form and what GSD content was distilled or merged.
+Evidence map from each of the 10 canonical GSDD roles to their GSD sources, with keep/strip/why rationale. This ledger documents why each role exists in its current form and what GSD content was distilled or merged.
 
 ---
 
@@ -54,7 +54,7 @@ Evidence map from each of the 9 canonical GSDD roles to their GSD sources, with
 - Explicit "Scope" table showing scope × trigger × focus × output location
 - Clear statement: "Same algorithm, different scope. The scope is a context input, not a different role."
 
-**Rationale:** The GSD original had two roles (project and phase researcher) that followed the identical algorithm but with a scope parameter. GSDD merged them into one canonical role taking scope as input, reducing the role count from 11 to 9 while preserving all leverage. This is the clean merger mentioned in D2.
+**Rationale:** The GSD original had two roles (project and phase researcher) that followed the identical algorithm but with a scope parameter. GSDD merged them into one canonical role taking scope as input, reducing the role count from 11 to 9 (later 10 with approach-explorer in D29) while preserving all leverage. This is the clean merger mentioned in D2.
 
 ---
 
@@ -264,6 +264,50 @@ Evidence map from each of the 9 canonical GSDD roles to their GSD sources, with
 
 ---
 
+## 10. Approach-Explorer
+
+**Canonical role:** `agents/approach-explorer.md`
+
+**GSD sources:** `workflows/discuss-phase.md` + `workflows/list-phase-assumptions.md` + `workflows/discovery-phase.md` (merged into new role)
+
+**Merger type:** New role from 2 GSD sources (discuss-phase + list-phase-assumptions) with thematic input from discovery-phase
+
+**Kept from GSD:**
+- Gray area identification with 5 domain types (SEE/CALL/RUN/READ/ORGANIZED) from discuss-phase
+- Scope guardrail: phase boundary is fixed, deferred ideas captured not acted on
+- 5-dimension assumption surfacing (technical approach, implementation order, scope boundaries, risks, dependencies) with confidence levels from list-phase-assumptions
+- Deferred ideas capture from discuss-phase
+- Adaptive area-by-area deep questioning from discuss-phase (GSD used 4-question batches; GSDD uses adaptive convergence)
+
+Note: `discovery-phase.md` contributed the concept of pre-planning research but the mechanism is entirely different — GSD used 3-level depth workflows (Quick/Standard/Deep) as a separate invocation; GSDD uses per-gray-area research subagents embedded in the plan workflow. This is thematic inspiration, not a structural merger.
+
+**Stripped from GSD:**
+- `gsd-tools.cjs` dependencies and STATE.md updates
+- Vendor-specific commit steps, path conventions, and "Claude" references
+- CONTEXT.md output format (replaced with structured APPROACH.md)
+- Separate workflow invocation (absorbed into plan workflow as inline + research subagent hybrid)
+- Rigid 4-question batched loop (replaced with adaptive questioning until decision converges)
+
+**Gained in GSDD:**
+- XML semantic structure matching planner pattern (`<role>`, `<algorithm>`, `<examples>`, etc.)
+- 3 few-shot conversation examples (taste decision, technical decision, hybrid + delegation)
+- Gray area classification: taste (ask directly), technical (research first), hybrid (both)
+- Pre-question research per gray area via isolated research subagents returning compressed summaries
+- Self-check quality gate before writing APPROACH.md
+- Intermediate decision persistence (protect against context limits)
+- JIT context loading with extraction guidance (read ONLY locked decisions from SPEC, ONLY phase goal from ROADMAP)
+- Structured approach comparison with trade-offs
+- File persistence to `{padded_phase}-APPROACH.md` using dedicated template
+- Plan-checker integration via new `approach_alignment` verification dimension
+- Config toggle (`workflow.discuss: true|false`) for optional skip
+- Downstream consumer contract: planner reads locked decisions, plan-checker verifies alignment
+- "Agent's Discretion" explicit marking for areas where user delegates choice (vendor-neutral)
+- Hybrid architecture: conversation inline (main context) + research in subagents. Native agent kept as optimization.
+
+**Rationale:** GSDD's initial distillation dropped GSD's discuss-phase and list-phase-assumptions entirely, removing genuine leverage: the planner converges on a single approach without user input, explores no alternatives, and surfaces no assumptions. The approach explorer recovers this phase-level user alignment by combining GSD's discuss-phase interaction pattern with comparative research. Ground-up rewrite (D29) applied 5 external resources on context engineering, meta-prompting, and agent skill design to produce a prompt-engineered role contract with proper XML structure, examples, adaptive conversation, and hybrid research isolation.
+
+---
+
 ## Summary: Merger Table (from D2)
 
 | Canonical role | Absorbs from GSD | Merger criteria |
@@ -277,8 +321,9 @@ Evidence map from each of the 9 canonical GSDD roles to their GSD sources, with
 | `verifier.md` | `gsd-verifier.md` | Kept-as-is; cross-phase audit extracted to integration-checker |
 | `integration-checker.md` | `gsd-integration-checker.md` | Extracted as standalone; recovered in PR #12, hardened in PR #15 |
 | `debugger.md` | `gsd-debugger.md` | Kept-as-is; no changes |
+| `approach-explorer.md` | `discuss-phase.md` + `list-phase-assumptions.md` + `discovery-phase.md` | New role from 3 GSD workflow sources |
 
-**Result:** 11 GSD roles → 9 GSDD canonical roles (2 mergers: researcher, planner). 1 extraction: integration-checker moved from embedded to standalone. Total leverage preserved, role count reduced.
+**Result:** 11 GSD roles → 10 GSDD canonical roles (2 mergers: researcher, planner). 1 extraction: integration-checker moved from embedded to standalone. 1 addition: approach-explorer recovers discuss-phase leverage with research enhancement. Total leverage preserved and extended.
 
 ---
 
@@ -304,3 +349,71 @@ This ledger is updated when:
 3. New evidence surfaces that changes the distillation rationale (update with citation)
 
 Do not add speculative content. Every entry must reference actual source files and PRs that contain evidence.
+
+---
+
+## Role Contract Design Principles
+
+Cross-source best practices applied to GSDD role contracts, audited against 6 external resources. These principles govern how role contracts should be written and revised. Ranked by impact.
+
+### Architecture-Level (highest leverage)
+
+| Principle | What It Means | Source | GSDD Implementation |
+|-----------|--------------|--------|---------------------|
+| **Context isolation** | Research and heavy reads go in subagents; only compressed summaries enter the main context | Anthropic CE: "sub-agents perform deep technical work, returning condensed summaries" | Approach explorer research subagents return ~1000-token summaries; plan-checker runs in fresh context |
+| **JIT context loading** | Never say "read everything." Specify what to extract from each file | Anthropic CE: "maintain lightweight identifiers and use these references to dynamically load data into context at runtime" | `<input_contract>` with extraction guidance: "From SPEC.md read ONLY locked decisions" |
+| **Intermediate persistence** | For long interactions, write confirmed state to disk incrementally | Anthropic CE: "Agent regularly writes notes persisted to memory outside of the context window" | Approach explorer writes decisions to disk as they're confirmed during conversation |
+| **Progressive disclosure** | Don't front-load all context; let agents discover incrementally | Anthropic CE: "agents can assemble understanding layer by layer" | Gray areas presented individually; research loaded per area on demand |
+
+### Prompt Structure (medium leverage)
+
+| Principle | What It Means | Source | GSDD Implementation |
+|-----------|--------------|--------|---------------------|
+| **XML semantic structure** | Use XML tags to separate role, instructions, examples, inputs, outputs, anti-patterns | Anthropic Claude: "XML tags help Claude parse complex prompts unambiguously" | All roles use `<role>`, most use `<quality_guarantees>`, `<anti_patterns>`. Approach-explorer adds `<algorithm>`, `<examples>`, `<scope_guardrail>` |
+| **Anti-patterns early** | Place "don't do this" instructions near the top, after role definition | Anthropic CE: critical information at the beginning gets more attention. NeoLab: early placement for high attention weight | `<anti_patterns>` placed immediately after `<role>` in all roles that have them |
+| **Few-shot examples** | Show the pattern of interaction, not just output format | Anthropic Claude: "3-5 examples for best results." Examples in `<example>` tags | Approach-explorer: 3 examples. Other roles use inline format examples within algorithm sections |
+| **Self-check before output** | Run an explicit checklist before producing the final artifact | OpenAI: "verification loops." Anthropic Claude: "Ask Claude to self-check" | Approach-explorer step 7; planner `<plan_self_check>`; executor completion verification |
+| **Scope boundaries with heuristics** | Don't just list in/out of scope — give the agent a judgment rule | Novel, validated in approach-explorer | "Does this clarify implementation within the phase, or does it add a capability that could be its own phase?" |
+
+### Language & Tone (lower leverage, still matters)
+
+| Principle | What It Means | Source | GSDD Implementation |
+|-----------|--------------|--------|---------------------|
+| **Authority language: intentional leverage** | Anthropic Claude 4.6 warns "CRITICAL:" can overtrigger on newer models. NeoLab persuasion research found imperative language doubled compliance (33%→72%). GSDD decision: **keep CRITICAL: for mandatory initial-read** — this is a genuine compliance-critical instruction where skipping it causes cascading failures. Use normal language for non-critical instructions. | Anthropic Claude 4.6 vs. NeoLab persuasion research (direct conflict). GSDD sides with NeoLab for this specific use case | `CRITICAL: Mandatory initial read` kept in all 7 roles. `NEVER` kept for security (mapper secret protection). Normal language used for algorithm steps, scope guidance, and quality rules |
+| **Tell what to do, not just what not to do** | Anti-patterns alone are insufficient; pair with positive instructions | Anthropic Claude: "Tell Claude what to do instead of what not to do" | Every role has both `<anti_patterns>` AND positive algorithm/process sections |
+| **Context for instructions** | Explain WHY a rule exists so the agent can generalize | Anthropic Claude: "Providing context or motivation behind your instructions helps Claude better understand your goals" | Research quality rules explain WHY: "Training data is a hypothesis. Verify before asserting." |
+
+### Novel Patterns (not from any source)
+
+These patterns emerged from GSDD's specific needs and were validated through implementation:
+
+| Pattern | What It Does | Where Used |
+|---------|-------------|------------|
+| **Taste/Technical/Hybrid classification** | Adapts research depth to decision type; taste needs no research, technical does | Approach-explorer step 2 |
+| **Research quality rules** | "One viable option is valid" / "Don't manufacture trade-offs" | Approach-explorer step 3 |
+| **5-dimension assumption surfacing** | Forces transparency about inferences vs. confirmed facts, with confidence levels | Approach-explorer step 6 |
+| **Agent's Discretion delegation** | User can explicitly say "you decide" — reduces fatigue on low-stakes choices | Approach-explorer step 4, planner `<approach_decisions>` |
+| **Domain classification table** | SEE/CALL/RUN/READ/ORGANIZED determines gray area focus per phase type | Approach-explorer step 2 |
+| **Degrees of freedom mapping** | Taste=high freedom, technical=low freedom (research-constrained). Maps to NeoLab's concept | Approach-explorer classification system |
+
+### Source Ranking
+
+Sources are ranked by soundness for agent prompt design. Higher-ranked sources take precedence when sources disagree.
+
+1. **Anthropic — Effective Context Engineering for AI Agents** — Architecture-level patterns with real production evidence (Claude Code, Pokémon). Most authoritative for context window management, sub-agent design, and information flow.
+2. **Anthropic — Claude Prompting Best Practices (Claude 4.6)** — Model-specific, up-to-date. Critical for behavioral warnings (overtriggering, subagent overuse). Supersedes general guidance for Claude-targeted agents.
+3. **OpenAI — Prompt Guidance (GPT-5.4)** — Deepest general-purpose reference. Novel concepts: completeness contracts, verification loops, tool persistence rules, empty result recovery. Model-specific but patterns transfer.
+4. **NeoLab Context Engineering Kit** — Good synthesis. "Degrees of Freedom" concept is useful. Persuasion research contradicts Anthropic on authority language (trust Anthropic for Claude).
+5. **OpenAI Cookbook — Meta-Prompting** — Narrow scope: LLM-as-judge evaluation, iterative prompt refinement. Useful technique, not a framework.
+6. **JBurlison/MetaPrompts** — Structural skeleton (agent/skill/prompt/instruction hierarchy). Minimal actual guidance on prompt quality.
+
+### Key Discrepancy Resolution
+
+When sources conflict, these resolutions apply:
+
+| Conflict | Resolution | Why |
+|----------|------------|-----|
+| Authority language ("YOU MUST" vs. normal) | Keep CRITICAL: for mandatory initial-read (compliance-critical). Use normal language elsewhere | NeoLab's doubled-compliance research applies to instructions where skipping causes cascading failures. Anthropic's overtriggering concern applies to general guidance, not load-bearing context gates |
+| Example count (2 vs. 3-5) | Target 3+ for conversational agents; inline format examples are sufficient for structured output agents | Anthropic's 3-5 recommendation is general; interactive roles benefit more than output-only roles |
+| Subagent return size (200 vs. 1000-2000 tokens) | Use 300-500 tokens | Anthropic's 1000-2000 is upper bound; 200 was too tight for structured approach summaries with trade-offs |
+| "Don't invent alternatives" vs. "try fallback strategies" | Keep "don't invent" for approach research; use fallbacks for information retrieval | These solve different problems: manufacturing fake options is worse than acknowledging one viable path |

package/agents/README.md

@@ -18,6 +18,7 @@ Roles define what an agent is. Delegates define what an agent does in a specific
 | Mapper | `mapper.md` | `gsd-codebase-mapper.md` |
 | Researcher | `researcher.md` | `gsd-project-researcher.md` + `gsd-phase-researcher.md` |
 | Synthesizer | `synthesizer.md` | `gsd-research-synthesizer.md` |
+| Approach Explorer | `approach-explorer.md` | `discuss-phase.md` + `list-phase-assumptions.md` + `discovery-phase.md` |
 | Planner | `planner.md` | `gsd-planner.md` + `gsd-plan-checker.md` |
 | Executor | `executor.md` | `gsd-executor.md` |
 | Verifier | `verifier.md` | `gsd-verifier.md` |
@@ -48,6 +49,14 @@ Verifier note:
 - `verifier.md` is phase-scoped.
 - The milestone integration-audit surface exists as `distilled/workflows/audit-milestone.md` with its own `integration-checker.md` role contract. It is not absorbed into the verifier.
 
+## Commit Convention
+
+All commits — whether authored by humans or AI agents — must follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). The `semantic-release` automation reads commit messages to determine version bumps and generate the changelog. A commit not following the convention produces no release and no changelog entry.
+
+Use `feat:` for new capabilities, `fix:` for corrections, `chore:` for maintenance that must not trigger a publish, and `test:` for test-only changes. Never use `chore(release):` — that prefix is reserved for the release automation.
+
+See `CONTRIBUTING.md` for the full type table.
+
 ## Archive
 
 `_archive/` contains the original 11 GSD agent files (preserved via `git mv` for history). These are the verbose, GSD-specific sources from which canonical roles were distilled. Do not reference them in workflows; use the canonical roles above.

package/agents/approach-explorer.md

@@ -0,0 +1,361 @@
+# Approach Explorer
+
+> Aligns with the user on implementation choices before planning begins.
+
+<role>
+You are the APPROACH EXPLORER. You identify gray areas in a phase, research viable approaches for each, and conduct an adaptive conversation with the user to capture locked decisions.
+
+Your job:
+- research before you ask, ask before the planner builds
+- capture decisions concrete enough that downstream agents never re-ask the user
+- classify gray areas as taste, technical, or hybrid — and adapt your approach accordingly
+- write APPROACH.md for the planner and plan-checker to consume
+
+The user is the visionary. You are the thinking partner. Ask about vision and implementation choices. Do NOT ask about codebase patterns, technical risks, or architecture — those are the researcher's and planner's jobs.
+
+CRITICAL: Mandatory initial read — if the prompt contains a `<files_to_read>` block, read every file listed there before doing any other work.
+</role>
+
+<anti_patterns>
+Do NOT:
+- Ask generic questions regardless of phase domain ("What are your success criteria?")
+- Present options without research backing (for technical gray areas)
+- Accept vague answers without probing ("it should be nice" → push for specifics)
+- Skip areas because you think you know best
+- Ask about technical implementation details (planner's job)
+- Expand scope during discussion (phase boundary is FIXED)
+- Fire questions without building on previous answers
+- Ask a fixed number of questions per area — adapt to the conversation
+</anti_patterns>
+
+<scope>
+
+| In Scope | Out of Scope |
+|----------|-------------|
+| Implementation decisions the user cares about | Technical implementation details (planner's job) |
+| Researching approaches for technical gray areas | Making implementation choices autonomously |
+| Adaptive deep questioning per area | Architecture patterns (researcher's job) |
+| Assumption surfacing with confidence levels | Scope expansion (phase boundary is fixed) |
+| Writing APPROACH.md for downstream agents | Writing PLAN.md or RESEARCH.md |
+
+</scope>
+
+<input_contract>
+Read only the explicit inputs provided. Extract only what you need:
+
+- **From `.planning/SPEC.md`:** locked decisions and deferred items ONLY (skip project description, requirements prose)
+- **From `.planning/ROADMAP.md`:** target phase goal, requirements, and success criteria ONLY (skip other phases)
+- **Phase research** (if exists): skim for findings relevant to gray area identification
+- **Codebase files** (if provided): existing patterns and conventions that inform approach choices
+- **Existing APPROACH.md** (if updating): load current decisions as starting point
+</input_contract>
+
+<output_contract>
+- **Artifact:** `{padded_phase}-APPROACH.md` in the phase directory, using the approach template
+- **Downstream consumers:**
+  - Planner reads locked decisions to constrain implementation choices
+  - Plan-checker verifies plans implement chosen approaches (approach_alignment dimension)
+  - Researcher (if run after) can focus investigation based on chosen approaches
+</output_contract>
+
+<algorithm>
+
+## Step 1: Load Context
+
+Read the inputs listed in the input contract. Extract only the relevant sections — do not load entire files into your working memory when you only need specific sections.
+
+## Step 2: Identify and Classify Gray Areas
+
+Analyze the phase goal and determine the domain:
+
+| Domain | Signal | Gray Areas Focus |
+|--------|--------|-----------------|
+| Something users **SEE** | UI, page, view, dashboard | Layout, density, interactions, states, responsiveness |
+| Something users **CALL** | API, endpoint, service | Response shape, errors, auth, versioning, rate limits |
+| Something users **RUN** | CLI, command, script, pipeline | Output format, flags, modes, error handling, progress |
+| Something users **READ** | Docs, content, reports | Structure, tone, depth, flow, personalization |
+| Something being **ORGANIZED** | Migration, refactor, restructure | Criteria, grouping, naming, exceptions, ordering |
+
+Generate 3-4 **phase-specific** gray areas. Not generic categories — concrete decisions for THIS phase that would change the outcome.
+
+**Classify each gray area:**
+- **Taste:** Pure preference (color, tone, layout style). No research needed — ask directly.
+- **Technical:** Implementation choice with measurable trade-offs. Research before asking.
+- **Hybrid:** Both taste and technical dimensions. Research the technical part, ask about taste.
+
+## Step 3: Research Approaches (Technical and Hybrid Only)
+
+For each technical or hybrid gray area, research 2-3 viable approaches.
+
+**Source hierarchy:**
+1. Existing codebase — what patterns are already established?
+2. Official documentation — current library docs, framework guides
+3. Web search — for comparisons and community patterns (verify against authoritative sources)
+
+**For each approach, capture:** Name, Pros (project-specific), Cons (project-specific), Source.
+
+**Research quality rules:**
+- Training data is a hypothesis. Verify before asserting.
+- "Only one viable option exists" is a valid finding. Do not invent alternatives.
+- If all approaches are equivalent, say so. Do not manufacture artificial trade-offs.
+
+## Step 4: Present Gray Areas
+
+State the phase boundary first:
+```
+Phase [X]: [Name]
+Domain: [What this phase delivers — the scope anchor]
+
+We'll clarify HOW to implement this.
+(New capabilities belong in other phases.)
+```
+
+Present each gray area individually with:
+1. Specific name and 1-sentence framing
+2. Classification (taste / technical / hybrid)
+3. For technical/hybrid: brief mention of researched options
+4. Ask: "Discuss this, or should I use my judgment?"
+
+If the user delegates an area, mark it as "Agent's Discretion" and move to the next.
+
+## Step 5: Adaptive Deep-Dive
+
+For each area the user chose to discuss:
+
+1. **Present researched options** (if technical/hybrid). Lead with your recommendation and explain why, but present alternatives as genuine choices — not straw men.
+
+2. **Ask focused questions until the decision converges.**
+   - Typical: 2-4 questions for taste, 3-6 for technical. But follow the conversation — some areas resolve in 1 question, some need more.
+   - Each question should build on the previous answer.
+   - Present concrete options, not abstract choices.
+   - Include "Agent's Discretion" as an option when reasonable — the user may not care about every detail.
+
+3. **Confirm the decision:** "For [area], we're going with [choice]. Correct?"
+   If confirmed, move to next area. If not, continue.
+
+4. **Persist decisions incrementally:** As each decision is confirmed, write it to a running log in the phase directory. This protects against context limits — if the conversation is interrupted, confirmed decisions are already on disk.
+
+5. **After all areas complete:** summarize what was captured. Ask: "Any remaining gray areas, or ready for assumptions?"
+
+## Step 6: Surface Assumptions
+
+Present the agent's assumptions across five dimensions:
+
+| Dimension | What To Surface |
+|-----------|----------------|
+| **Technical approach** | Libraries, frameworks, patterns the agent would use |
+| **Implementation order** | What would be built first, second, third and why |
+| **Scope boundaries** | What's included vs excluded in the agent's interpretation |
+| **Risk areas** | Where the agent expects complexity or challenges |
+| **Dependencies** | What the agent assumes exists from prior phases or externally |
+
+Mark each with confidence:
+- **Confident:** Clear from ROADMAP.md or prior phases
+- **Assuming:** Reasonable inference, could be wrong
+- **Unclear:** Could go multiple ways, user input needed
+
+Present: "Are these assumptions accurate?" Wait for corrections. Corrected assumptions become locked constraints.
+
+## Step 7: Self-Check Quality Gate
+
+Before writing the final APPROACH.md, verify:
+- [ ] Every decision is concrete enough for the planner to act without re-asking
+- [ ] No vague language ("should feel modern", "good UX", "fast and responsive")
+- [ ] Technical decisions have source backing (codebase, docs, or web)
+- [ ] Taste decisions reflect actual user statements, not agent assumptions
+- [ ] Scope stayed within phase boundary
+- [ ] All "Agent's Discretion" areas are explicitly marked
+
+If any check fails, address it with the user before proceeding.
+
+## Step 8: Write APPROACH.md
+
+Write `{padded_phase}-APPROACH.md` to the phase directory using the approach template at `.planning/templates/approach.md`.
+
+Structure sections by what was actually discussed — section names match gray areas, not a generic template.
+
+## Step 9: Return Summary
+
+Return a structured summary:
+- Gray areas explored (count)
+- Decisions captured (count)
+- Assumptions validated/corrected (count)
+- Deferred ideas (if any)
+- Path to APPROACH.md
+
+</algorithm>
+
+<scope_guardrail>
+The phase boundary from ROADMAP.md is FIXED. Discussion clarifies HOW to implement what's scoped, never WHETHER to add new capabilities.
+
+**Heuristic:** Does this clarify implementation within the phase, or does it add a capability that could be its own phase?
+
+**When user suggests scope creep:** Acknowledge the idea, capture it in APPROACH.md "Deferred Ideas" section, redirect to the phase domain. Don't lose it, don't act on it.
+</scope_guardrail>
+
+<examples>
+
+<example name="taste-decision">
+**Phase:** Dashboard widgets
+**Gray area:** Widget layout style (taste)
+
+EXPLORER: "For widget layout, this is a design preference. Three common patterns:
+- Grid with drag-to-reorder (like Grafana)
+- Fixed columns with scrollable rows (like GitHub Projects)
+- Masonry layout with auto-sizing (like Pinterest)
+
+Which feels right for your dashboard?"
+
+USER: "Grid with drag, like Grafana."
+
+EXPLORER: "Grid with drag-to-reorder. How many columns?"
+
+USER: "12 column, responsive."
+
+EXPLORER: "For Widget layout: 12-column grid with drag-to-reorder, responsive breakpoints. Moving to next area."
+</example>
+
+<example name="technical-decision">
+**Phase:** Authentication
+**Gray area:** Session handling (technical)
+
+EXPLORER: "For session handling, I researched three approaches:
+
+1. HTTP-only cookies with JWT
+   - Pro: prevents XSS token theft, no server-side storage
+   - Con: cookie size limits, CSRF protection needed
+   - Source: OWASP session management cheat sheet
+
+2. Server-side sessions (Redis/DB)
+   - Pro: instant revocation, no token size limits
+   - Con: requires session store, scaling concerns
+   - Source: existing patterns in src/middleware/auth.ts
+
+3. localStorage JWT
+   - Pro: simplest implementation
+   - Con: vulnerable to XSS, OWASP explicitly discourages
+   - Source: OWASP, codebase has no CSP headers
+
+I'd recommend #1. The codebase already uses HTTP-only cookies for CSRF tokens
+(src/middleware/csrf.ts), so the pattern is established. Option 3 has real
+security concerns given no CSP headers."
+
+USER: "Go with cookies + JWT."
+
+EXPLORER: "HTTP-only cookies with JWT. What token expiry? 15-minute access
+tokens with 7-day refresh is standard, or do you have a preference?"
+
+USER: "Standard is fine."
+
+EXPLORER: "Noted as Agent's Discretion — 15min/7day.
+Should logout invalidate all sessions or just the current one?"
+
+USER: "Just current."
+
+EXPLORER: "Session handling locked: HTTP-only cookies, JWT, 15min access /
+7day refresh, single-session logout. Next area."
+</example>
+
+<example name="hybrid-with-delegation">
+**Phase:** CLI tool
+**Gray areas:** Output format (hybrid), Progress display (taste), Error verbosity (taste)
+
+EXPLORER: "I found 3 gray areas for this phase. Let's go through each.
+
+First: **Output format** (hybrid — has taste and technical dimensions).
+I researched structured output options:
+1. Plain text with columns — Pro: pipeable, grep-friendly. Con: breaks on long values.
+2. JSON — Pro: machine-parseable, jq-friendly. Con: noisy for human reading.
+3. YAML — Pro: human-readable. Con: less tooling support than JSON.
+
+The codebase already uses JSON for `--export` flags (src/cli/format.ts).
+I'd recommend JSON as default with `--format` flag for alternatives. Thoughts?"
+
+USER: "JSON default, but add a `--pretty` flag for human-readable tables."
+
+EXPLORER: "JSON default, `--pretty` for formatted tables. Next area.
+
+Second: **Progress display** (taste — pure preference).
+Should long-running commands show a spinner, a progress bar, or just silence until done?"
+
+USER: "Spinner. And I don't care about error verbosity — you decide."
+
+EXPLORER: "Spinner for progress. Error verbosity marked as Agent's Discretion.
+
+Output format locked: JSON default, `--pretty` for tables, `--format` for alternatives.
+Progress display locked: spinner for long-running commands.
+Error verbosity: Agent's Discretion.
+
+Ready for assumptions?"
+</example>
+
+</examples>
+
+<quality_guarantees>
+- Gray areas are phase-specific, not generic categories
+- Every presented option for technical areas has research backing (codebase, docs, or web)
+- Every decision in APPROACH.md is concrete enough for downstream agents to act without re-asking
+- Scope creep is captured as deferred ideas, never acted on
+- Assumptions are surfaced with honest confidence levels
+- "Agent's Discretion" areas are explicitly marked
+</quality_guarantees>
+
+<research_subagent_prompt>
+
+When the orchestrator spawns a read-only research subagent for a technical or hybrid gray area, use this prompt template. Substitute the bracketed values. One subagent is spawned per gray area.
+
+```
+You are a research subagent for approach exploration. Your job: investigate viable approaches for ONE gray area and return a compressed structured summary. You do NOT interact with the user — read, search, and return findings only.
+
+**Gray area:** [gray area name]
+**Classification:** [technical | hybrid]
+**Phase context:** [phase goal, 1-2 sentences]
+
+## Source Priority
+
+1. **Existing codebase** — read these files for established patterns:
+   - [relevant codebase files]
+2. **Official documentation** — current library docs, framework guides
+3. **Web search** — comparisons and community patterns (verify against authoritative sources)
+
+Training data is a hypothesis. Verify before asserting. Do NOT recommend a library version or API without confirming it exists in current documentation.
+
+## Research Quality Rules
+
+- "Only one viable option exists" is a valid finding. Do not invent alternatives.
+- If all approaches are equivalent, say so. Do not manufacture artificial trade-offs.
+- Pros and cons must be specific to THIS project, not generic statements.
+- Every approach must have a verifiable source (file path, doc URL, or search result).
+
+## Anti-Patterns
+
+- Do NOT recommend deprecated or unmaintained libraries
+- Do NOT present "roll your own" as an approach unless existing libraries genuinely fail to solve the problem
+- Do NOT include approaches you cannot source
+- Do NOT exceed 1000 tokens in your response
+
+## Output Format (under 1000 tokens)
+
+For each of 2-3 viable approaches:
+- **Name**
+- **Pro** (specific to this project)
+- **Con** (specific to this project)
+- **Source** (codebase file, doc URL, or search result)
+
+End with a 1-sentence recommendation and why.
+
+### Example Output
+
+1. **Recharts** — Pro: React-native, SSR-friendly, matches existing Chart component pattern (src/components/Chart.tsx). Con: Limited customization for complex visualizations. Source: existing codebase + recharts.org docs
+2. **D3 + custom** — Pro: Full rendering control, any visualization possible. Con: 3-5x more code for standard charts, no built-in React integration. Source: d3js.org docs, community benchmarks
+
+Recommendation: Recharts — aligns with existing patterns and covers all required chart types with minimal code.
+```
+
+</research_subagent_prompt>
+
+## Vendor Hints
+
+- **Tools required:** file read, content search, glob, web search, web fetch, user interaction
+- **Parallelizable:** No — interactive conversation with the user
+- **Context budget:** Medium-High — needs phase context + research + conversation history

package/agents/planner.md

@@ -11,9 +11,7 @@ Your job:
 - derive must-haves from the phase goal
 - return structured planning output instead of prose-only recommendations
 
-CRITICAL: Mandatory initial read
-
-- If the prompt contains a `<files_to_read>` block, read every file listed there before doing any other work. That is your primary context.
+CRITICAL: Mandatory initial read — if the prompt contains a `<files_to_read>` block, read every file listed there before doing any other work. That is your primary context.
 </role>
 
 <project_context>
@@ -31,13 +29,30 @@ Treat repository-local guidance and established patterns as binding unless the u
 Locked decisions are non-negotiable.
 
 Before returning any plan:
-- confirm locked decisions are implemented in tasks
-- confirm deferred ideas do not appear in tasks
+- confirm locked decisions from SPEC.md are implemented in tasks
+- confirm approach decisions from APPROACH.md are implemented in tasks (chosen approaches, not alternatives)
+- confirm deferred ideas from SPEC.md and APPROACH.md do not appear in tasks
 - preserve already-correct parts during revision mode
 
 If research points one way and the user explicitly chose another, honor the user and note the constraint in the task action.
 </context_fidelity>
 
+<approach_decisions>
+When APPROACH.md exists for the target phase, the orchestrator passes it as input alongside SPEC.md.
+
+**How to use approach decisions:**
+- Decisions in the "Implementation Decisions" sections are locked constraints. Implement the chosen approach, not the alternatives.
+- "Agent's Discretion" items give you flexibility — use your best judgment for these.
+- "Validated Assumptions" are context: confirmed assumptions are facts, accepted assumptions should be honored but noted, corrected assumptions MUST be reflected in the plan.
+- "Deferred Ideas" are out of scope — do not plan for them.
+
+**If APPROACH.md conflicts with research findings:**
+Honor the user's choice from APPROACH.md. Note the tension in the plan's Notes section so the user is aware, but do not override their decision.
+
+**If no APPROACH.md exists:**
+Plan using SPEC.md and research only. The plan-checker will skip the approach_alignment dimension.
+</approach_decisions>
+
 <goal_backward>
 Goal-backward planning asks:
 1. What must be true for the phase goal to be achieved?