gsdd-cli 0.18.5 → 0.19.1

package/distilled/templates/agents.md

@@ -1,6 +1,6 @@
-# AGENTS.md - GSDD Governance
-
-<!-- BEGIN GSDD -->
-{{GSDD_BLOCK}}
-<!-- END GSDD -->
-
+# AGENTS.md - GSDD Governance
+
+<!-- BEGIN GSDD -->
+{{GSDD_BLOCK}}
+<!-- END GSDD -->
+

package/distilled/templates/approach.md

@@ -1,232 +1,272 @@
-# 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
+# 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.
+
+**Alignment proof:** When `.planning/config.json` has `workflow.discuss: true`, every APPROACH artifact must include an `## Alignment Proof` section before `<domain>`. It must record the canonical fields `alignment_status`, `alignment_method`, `user_confirmed_at`, `explicit_skip_approved`, `skip_scope`, `skip_rationale`, and `confirmed_decisions`. `Agent's Discretion` and agent-only "No questions needed" are not valid proof.
+
+**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
+
+## Alignment Proof
+
+- `workflow.discuss`: [true | false]
+- `alignment_status`: [user_confirmed | approved_skip | not_required]
+- `alignment_method`: [conversation source, e.g. runtime command or user message]
+- `user_confirmed_at`: [date or N/A]
+- `explicit_skip_approved`: [true | false]
+- `skip_scope`: [phase-wide / named gray area / N/A]
+- `skip_rationale`: [why the user approved skipping discussion, or N/A]
+- `confirmed_decisions`:
+  - [User-confirmed decision, or "N/A - approved skip"]
+
+<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
+
+## Alignment Proof
+
+- `workflow.discuss`: true
+- `alignment_status`: user_confirmed
+- `alignment_method`: planning conversation
+- `user_confirmed_at`: 2026-03-22
+- `explicit_skip_approved`: false
+- `skip_scope`: N/A
+- `skip_rationale`: N/A
+- `confirmed_decisions`:
+  - Use Recharts for chart rendering
+  - Use react-grid-layout for dashboard widgets
+
+<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
+
+## Alignment Proof
+
+- `workflow.discuss`: true
+- `alignment_status`: user_confirmed
+- `alignment_method`: planning conversation
+- `user_confirmed_at`: 2026-03-22
+- `explicit_skip_approved`: false
+- `skip_scope`: N/A
+- `skip_rationale`: N/A
+- `confirmed_decisions`:
+  - Use HTTP-only cookies with JWT
+  - Use structured JSON errors
+
+<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