gsdd-cli 0.1.0 → 0.2.0

package/distilled/templates/approach.md

@@ -0,0 +1,232 @@
+# Phase Approach Template
+
+Template for `.planning/phases/XX-name/{phase_num}-APPROACH.md` — captures implementation decisions and validated assumptions for a phase.
+
+**Purpose:** Document decisions that downstream agents need. Planner uses this to know WHAT choices are locked vs flexible. Plan-checker verifies plans honor these decisions.
+
+**Key principle:** The top-level structure (`<domain>`, `<decisions>`, `<assumptions>`, `<deferred>`) is fixed. Section names WITHIN `<decisions>` emerge from what was actually discussed for THIS phase — a CLI phase has CLI-relevant sections, a UI phase has UI-relevant sections.
+
+**Downstream consumers:**
+- `planner` — Reads decisions to constrain implementation choices. Locked decisions must be implemented. Agent's Discretion items allow planner flexibility.
+- `plan-checker` — Reads decisions to verify plans implement chosen approaches (approach_alignment dimension). Flags plans that contradict explicit user choices.
+
+---
+
+## File Template
+
+```markdown
+# Phase [X]: [Name] - Approach
+
+**Explored:** [date]
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+[Clear statement of what this phase delivers — the scope anchor. This comes from ROADMAP.md and is fixed. Discussion clarifies implementation within this boundary.]
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### [Gray Area 1 that was discussed]
+**Chosen approach:** [name]
+**Alternatives considered:** [Option B], [Option C]
+**Why this one:** [reasoning from research + user preference]
+- [Specific decision from questioning]
+- [Another decision if applicable]
+
+### [Gray Area 2 that was discussed]
+**Chosen approach:** [name]
+**Alternatives considered:** [Option B]
+**Why this one:** [reasoning]
+- [Specific decision]
+
+### Agent's Discretion
+[Areas where user explicitly said "you decide" — the agent has flexibility here during planning/implementation]
+
+</decisions>
+
+<assumptions>
+## Validated Assumptions
+
+### Confirmed
+- [confident] [assumption confirmed by user]
+
+### Accepted (not challenged)
+- [assuming] [assumption user didn't challenge — planner should still honor but note it]
+
+### Corrected
+- [corrected] [original assumption] → [user's correction]
+
+</assumptions>
+
+<deferred>
+## Deferred Ideas
+
+[Ideas that came up during discussion but belong in other phases. Captured here so they're not lost, but explicitly out of scope for this phase.]
+
+[If none: "None — discussion stayed within phase scope"]
+
+</deferred>
+
+---
+
+*Phase: XX-name*
+*Approach explored: [date]*
+```
+
+## Good Examples
+
+**Example 1: Visual feature (Dashboard)**
+
+```markdown
+# Phase 3: Interactive Dashboard - Approach
+
+**Explored:** 2026-03-22
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Build an interactive dashboard with configurable widgets. Users can view metrics and rearrange layout. Widget creation and custom data sources are separate phases.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Chart rendering
+**Chosen approach:** Recharts
+**Alternatives considered:** D3 + custom components, Chart.js
+**Why this one:** React-native, SSR-friendly, good defaults. Matches existing React patterns. D3 would give more control but requires more code for standard charts.
+- Bar charts and line charts for metrics — no pie charts in v1
+- Charts should be interactive (hover tooltips) but not editable
+- Responsive: charts resize with widget container
+
+### Widget layout
+**Chosen approach:** react-grid-layout
+**Alternatives considered:** CSS Grid + custom drag, @dnd-kit grid
+**Why this one:** Purpose-built for dashboard grids. Layout serialization to JSON for persistence. Mature production usage.
+- Drag-to-reorder enabled
+- Resize handles on bottom-right corner
+- 12-column grid, responsive breakpoints
+- Layout persisted to localStorage (not server)
+
+### Agent's Discretion
+- Loading skeleton design
+- Exact spacing and typography within widgets
+- Error state handling for failed data fetches
+
+</decisions>
+
+<assumptions>
+## Validated Assumptions
+
+### Confirmed
+- [confident] Using existing Tailwind patterns from Phase 1-2
+
+### Accepted (not challenged)
+- [assuming] Dashboard data comes from static JSON for v1 (no real API)
+
+### Corrected
+- [corrected] Dashboard is read-only → Widgets DO need drag reorder
+
+</assumptions>
+
+<deferred>
+## Deferred Ideas
+
+- Real-time data updates — future phase
+- Custom widget creation — add to backlog
+- Dashboard sharing/export — out of scope for v1
+
+</deferred>
+
+---
+
+*Phase: 03-dashboard*
+*Approach explored: 2026-03-22*
+```
+
+**Example 2: API feature (Authentication)**
+
+```markdown
+# Phase 1: Authentication - Approach
+
+**Explored:** 2026-03-22
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Users can register and log in with email/password. Session management via JWT. OAuth and MFA are separate phases.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Session handling
+**Chosen approach:** HTTP-only cookies with JWT
+**Alternatives considered:** localStorage JWT, session-based (server-side)
+**Why this one:** HTTP-only cookies prevent XSS token theft. JWT avoids server-side session storage. Standard pattern for Next.js apps.
+- Access token: 15-minute expiry
+- Refresh token: 7-day expiry, rotation on use
+- Logout clears both tokens
+
+### Error responses
+**Chosen approach:** Structured JSON errors
+**Alternatives considered:** Plain text errors, RFC 7807 Problem Details
+**Why this one:** Consistent with existing API patterns. RFC 7807 is overkill for this project size.
+- Always include: status code, error code, user-facing message
+- Never include: stack traces, internal IDs
+- Rate limit errors: include retry-after header
+
+### Agent's Discretion
+- Password hashing library (bcrypt vs argon2)
+- Exact JWT payload structure
+- Email validation regex vs library
+
+</decisions>
+
+<assumptions>
+## Validated Assumptions
+
+### Confirmed
+- [confident] Email/password only for v1 (no OAuth)
+
+### Accepted (not challenged)
+- [assuming] No email verification required for v1
+
+### Corrected
+- [corrected] Single-device sessions → Allow multi-device (don't invalidate other sessions on login)
+
+</assumptions>
+
+<deferred>
+## Deferred Ideas
+
+- OAuth providers (Google, GitHub) — Phase 4
+- MFA/2FA — add to backlog
+
+</deferred>
+
+---
+
+*Phase: 01-authentication*
+*Approach explored: 2026-03-22*
+```
+
+## Guidelines
+
+**This template captures DECISIONS for downstream agents.**
+
+The output should answer: "What choices are locked for the planner? Where does the planner have discretion?"
+
+**After creation:**
+- File lives in phase directory: `.planning/phases/XX-name/{phase_num}-APPROACH.md`
+- Planner reads decisions to constrain implementation tasks
+- Plan-checker verifies approach_alignment: plans must implement chosen approaches
+- Downstream agents should NOT need to ask the user again about captured decisions

package/distilled/templates/delegates/approach-explorer.md

@@ -0,0 +1,25 @@
+**Role contract:** Read `.planning/templates/roles/approach-explorer.md` before starting. Follow its algorithm, scope, anti-patterns, and quality standards.
+
+You are the approach explorer delegate for the plan workflow.
+
+**Your job:** Identify gray areas in the target phase, research viable approaches for technical decisions, conduct an adaptive conversation with the user to capture locked decisions, and write APPROACH.md to the phase directory.
+
+Read only the explicit inputs provided by the orchestrator:
+- target phase goal and requirement IDs from `.planning/ROADMAP.md`
+- locked decisions and deferred items from `.planning/SPEC.md`
+- phase research file (if exists)
+- relevant codebase files (existing patterns and conventions)
+- approach template at `.planning/templates/approach.md`
+
+## Gray Area Classification
+
+Classify each gray area before acting on it:
+- **Taste:** Ask directly, no research needed
+- **Technical:** Research 2-3 approaches first, then present with trade-offs
+- **Hybrid:** Research the technical part, ask about taste
+
+## Output
+
+Write `{padded_phase}-APPROACH.md` to the phase directory using the approach template.
+
+Return structured summary: gray areas explored, decisions captured, assumptions validated/corrected, deferred ideas, path to APPROACH.md.

package/distilled/templates/delegates/plan-checker.md

@@ -5,6 +5,7 @@ You are the fresh-context plan checker for `/gsdd:plan`.
 Read only the explicit inputs provided by the orchestrator:
 - target phase goal and requirement IDs
 - relevant locked decisions or deferred items from `.planning/SPEC.md`
+- approach decisions from `.planning/phases/*-APPROACH.md` (if provided)
 - any relevant phase research file
 - the produced `.planning/phases/*-PLAN.md` file(s)
 
@@ -21,6 +22,11 @@ Verify these dimensions:
 - `scope_sanity`: plans are sized so an executor can complete them without context collapse
 - `must_have_quality`: success criteria and must-haves are specific, observable, and reflected in tasks
 - `context_compliance`: locked decisions are honored and deferred ideas stay out of scope
+- `approach_alignment`: when APPROACH.md is provided, verify that plan tasks implement the chosen approaches from the user's decisions. Check:
+  - **Chosen honored?** Does each plan task align with the approach chosen in APPROACH.md for its gray area? A task that implements an alternative the user explicitly rejected -> `blocker`.
+  - **Discretion respected?** "Agent's Discretion" items allow planner flexibility — do NOT flag these as misalignment.
+  - **Deferred excluded?** Deferred ideas from APPROACH.md must not appear in plan tasks -> `blocker` if found.
+  - If no APPROACH.md was provided, skip this dimension entirely.
 
 Return JSON only as a single object with this shape:
 
@@ -30,7 +36,7 @@ Return JSON only as a single object with this shape:
   "summary": "One sentence overall assessment",
   "issues": [
     {
-      "dimension": "requirement_coverage",
+      "dimension": "requirement_coverage | approach_alignment",
       "severity": "blocker",
       "description": "What is wrong",
       "plan": "01-PLAN",

package/distilled/workflows/plan.md

@@ -10,8 +10,9 @@ Before starting, read these files:
 1. `.planning/SPEC.md` - requirements, constraints, key decisions, current state
 2. `.planning/ROADMAP.md` - find the target phase, its goal, requirements, and success criteria
 3. `.planning/research/*.md` - if research exists and is relevant to this phase
-4. `.planning/phases/*-PLAN.md` - any previous plans that affect this phase
-5. Relevant source code - if this phase builds on existing code, read the key files
+4. `.planning/phases/*-APPROACH.md` - approach decisions from user discussion (if exists)
+5. `.planning/phases/*-PLAN.md` - any previous plans that affect this phase
+6. Relevant source code - if this phase builds on existing code, read the key files
 
 Identify the target phase: the first phase with status `[ ]` or `[-]` in `ROADMAP.md`.
 </load_context>
@@ -20,8 +21,9 @@ Identify the target phase: the first phase with status `[ ]` or `[-]` in `ROADMA
 Before planning, acknowledge what is locked:
 
 - Decisions in `.planning/SPEC.md` "Key Decisions" - do not revisit them.
+- Decisions in APPROACH.md "Implementation Decisions" - these are user-validated choices. Implement the chosen approaches, not alternatives. "Agent's Discretion" items give you flexibility.
 - Patterns from previous phases - match existing conventions. Do not introduce new patterns without cause.
-- Deferred items - items marked v2, nice-to-have, or out of scope. Do not plan for them.
+- Deferred items - items marked v2, nice-to-have, or out of scope in SPEC.md or APPROACH.md. Do not plan for them.
 
 If you need to challenge a locked decision: stop, ask the developer, and document the new decision explicitly.
 </context_fidelity>
@@ -250,15 +252,79 @@ must_haves:
 ```
 </plan_structure>
 
-<clarify_approach>
-If there is ambiguity in how to implement:
+<approach_exploration>
+### When This Runs
 
-1. Ask the developer about preferences when the choice materially changes the design.
-2. Surface your assumptions explicitly.
-3. Present trade-offs when multiple approaches are valid.
+Check `.planning/config.json` for `workflow.discuss`:
+- If `workflow.discuss: false` (or key missing): skip this section, go to `<goal_backward_planning>`. Note `reduced_alignment` in the orchestration summary.
+- If `workflow.discuss: true`: mandatory before planning.
 
-If the approach is obvious or fully defined by `.planning/SPEC.md`, skip questions and proceed.
-</clarify_approach>
+### Check for Existing APPROACH.md
+
+Check if `{phase_dir}/{padded_phase}-APPROACH.md` exists.
+
+**If exists:**
+Offer the user a choice:
+- "Use existing" — load decisions from APPROACH.md, skip to `<goal_backward_planning>`
+- "Update it" — run the approach explorer to revise decisions
+- "View it" — display APPROACH.md contents, then offer "Use existing" / "Update"
+
+**If does not exist (or user chose "Update"):**
+Run the approach explorer.
+
+### Running the Approach Explorer
+
+**Primary path — inline conversation with research subagents:**
+
+The conversation with the user runs inline in the main context. For each technical gray area, a read-only research subagent is spawned to isolate heavy codebase and documentation reads, returning only compressed summaries.
+
+1. Load context: read ONLY locked decisions from `.planning/SPEC.md` and the target phase goal/requirements from `.planning/ROADMAP.md`.
+
+2. Identify 3-4 domain-specific gray areas. Classify each as **taste** (preference, no research needed), **technical** (trade-offs, research first), or **hybrid** (both).
+
+3. For each **technical or hybrid** gray area, spawn a read-only research subagent.
+   Use the prompt template from `.planning/templates/roles/approach-explorer.md` (`<research_subagent_prompt>` section), substituting the gray area name, classification, phase context, and relevant codebase files. Each subagent returns a structured summary under 1000 tokens.
+
+4. Present each gray area to the user individually:
+   - For taste areas: ask directly
+   - For technical/hybrid: present the research summary, lead with recommendation
+   - Ask: "Discuss this, or should I use my judgment?"
+
+5. For each area the user chose to discuss, ask adaptive questions until the decision converges. Persist each confirmed decision to disk incrementally.
+
+6. Surface assumptions across 5 dimensions with confidence levels. Wait for corrections.
+
+7. Self-check: verify every decision is concrete enough for the planner before writing.
+
+8. Write `{padded_phase}-APPROACH.md` to the phase directory.
+
+**Native agent optimization:**
+
+If your runtime provides an interactive `gsdd-approach-explorer` agent:
+- Invoke it with: target phase goal, requirement IDs, locked decisions, phase research (if exists), relevant codebase files
+- The native agent runs the full exploration in its own context window
+- This is an optimization — the output (APPROACH.md) is identical to the primary path
+
+**Inline fallback (reduced alignment):**
+
+If neither the primary path nor native agent is available (e.g., the runtime cannot spawn research subagents):
+- Read the phase goal and identify 2-3 obvious gray areas
+- Present them to the user with your best assessment
+- Capture any decisions the user provides
+- Explicitly report `reduced_alignment` — the user did not get full research-backed exploration
+
+### Using APPROACH.md Decisions
+
+After approach exploration completes (or existing APPROACH.md is loaded):
+- Treat decisions from APPROACH.md as locked constraints, same priority as `.planning/SPEC.md` decisions
+- "Agent's Discretion" items from APPROACH.md give the planner flexibility — do not treat them as locked
+- Thread the APPROACH.md file path to both the planner prompt and the plan-checker prompt
+- Deferred ideas from APPROACH.md must not appear in the plan
+
+### Role Contract
+
+The approach explorer's full role contract is at `.planning/templates/roles/approach-explorer.md`. The portable workflow describes the orchestration; the role contract describes the agent's behavior.
+</approach_exploration>
 
 <plan_check_orchestration>
 ### How Plan Checking Works
@@ -274,6 +340,7 @@ After the planner produces a draft plan, an independent checker reviews it in fr
 5. `scope_sanity` - plans are sized so an executor can complete them without context collapse
 6. `must_have_quality` - success criteria are specific, observable, and reflected in tasks
 7. `context_compliance` - locked decisions are honored and deferred ideas stay out of scope
+8. `approach_alignment` - when APPROACH.md exists, plans implement the chosen approaches, not alternatives. Blocker if plan contradicts an explicit user choice. Warning if plan drifts from recommendation without justification. Skipped when no APPROACH.md is provided.
 
 ### Invoking the Checker
 
@@ -282,6 +349,7 @@ After the planner produces a draft plan, an independent checker reviews it in fr
 3. If a native checker agent is available, invoke it in a fresh context with only these explicit inputs:
    - target phase goal and requirement IDs
    - relevant locked decisions / deferred items from `.planning/SPEC.md`
+   - approach decisions from `.planning/phases/*-APPROACH.md` (if exists)
    - relevant phase research file(s)
    - produced `.planning/phases/*-PLAN.md` file(s)
 4. Require the checker to return a single JSON object:
@@ -291,7 +359,7 @@ After the planner produces a draft plan, an independent checker reviews it in fr
      "summary": "One sentence overall assessment",
      "issues": [
        {
-         "dimension": "requirement_coverage | task_completeness | dependency_correctness | key_link_completeness | scope_sanity | must_have_quality | context_compliance",
+         "dimension": "requirement_coverage | task_completeness | dependency_correctness | key_link_completeness | scope_sanity | must_have_quality | context_compliance | approach_alignment",
          "severity": "blocker | warning",
          "description": "What is wrong",
          "plan": "01-PLAN",
@@ -354,6 +422,8 @@ For each task:
 Planning is done when all of these are true:
 
 - [ ] Target phase identified from `ROADMAP.md`
+- [ ] Approach exploration completed or explicitly skipped with `reduced_alignment` reported
+- [ ] When `workflow.discuss: true`: user alignment confirmed via APPROACH.md before planning
 - [ ] Research check completed where needed
 - [ ] Plan self-check passed
 - [ ] Success criteria from `ROADMAP.md` are represented as must-haves
@@ -362,7 +432,7 @@ Planning is done when all of these are true:
 - [ ] Every task has XML structure with `id`, `type`, `files`, `action`, `verify`, and `done`
 - [ ] Every task has at least one runnable verify command
 - [ ] Plan sizing stays within 2-5 tasks, preferring 2-3
-- [ ] Locked decisions from `.planning/SPEC.md` are honored
+- [ ] Locked decisions from `.planning/SPEC.md` and APPROACH.md are honored
 - [ ] Any git guidance stays repo-native and follows `.planning/config.json`
 </success_criteria>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsdd-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "GSDD — a portable, spec-driven development kernel for AI coding agents. Works with Claude Code, Codex CLI, OpenCode, Cursor, Copilot, and Gemini CLI.",
   "type": "module",
   "bin": {
@@ -9,6 +9,14 @@
   "scripts": {
     "test:gsdd": "node tests/gsdd.init.test.cjs && node tests/gsdd.models.test.cjs && node tests/gsdd.manifest.test.cjs && node tests/gsdd.plan.adapters.test.cjs && node tests/gsdd.audit-milestone.test.cjs && node tests/gsdd.invariants.test.cjs && node tests/gsdd.guards.test.cjs && node tests/gsdd.health.test.cjs && node tests/gsdd.scenarios.test.cjs"
   },
+  "devDependencies": {
+    "semantic-release": "^24.2.3",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
   "files": [
     "bin/adapters/",
     "bin/lib/",