gsdd-cli 0.18.5 → 0.19.0

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,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
+# 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/auth-matrix.md

@@ -1,78 +1,78 @@
-# Authorization Matrix Template
-
-> OWASP-style authorization matrix for systematic auth verification.
-> Create `.planning/AUTH_MATRIX.md` using this template when your project has multiple user roles or protected resources.
-
-## When to Create This Matrix
-
-Create an authorization matrix when your project has:
-- Multiple user roles (e.g., anonymous, user, admin, owner)
-- Protected resources that vary by role
-- Ownership-scoped data (users can only access their own records)
-- Admin or operator surfaces that must be restricted
-
-Skip this matrix for single-role projects or projects with no auth requirements.
-
-## Matrix Format
-
-Use the OWASP pivot format: rows are resources, columns are roles, cells are permissions.
-
-### Permission Values
-
-| Value | Meaning |
-|-------|---------|
-| ALLOW | Role can perform this action on any matching resource |
-| DENY  | Role must be explicitly rejected (not just "no route") |
-| OWN   | Role can perform this action only on resources they own |
-| N/A   | Action does not apply to this resource |
-
-### Matrix Table
-
-```markdown
-| Resource | Action | anonymous | user | admin |
-|----------|--------|-----------|------|-------|
-| /login   | POST   | ALLOW     | ALLOW| ALLOW |
-| /profile | GET    | DENY      | OWN  | ALLOW |
-| /profile | PUT    | DENY      | OWN  | ALLOW |
-| /users   | GET    | DENY      | DENY | ALLOW |
-| /users   | DELETE | DENY      | DENY | ALLOW |
-| /posts   | GET    | ALLOW     | ALLOW| ALLOW |
-| /posts   | POST   | DENY      | ALLOW| ALLOW |
-| /posts   | DELETE | DENY      | OWN  | ALLOW |
-```
-
-Adapt the table to your project's actual resources, actions, and roles. Add or remove columns as needed.
-
-## Sensitive Surfaces
-
-The following resource categories MUST have matrix coverage when they exist in your project:
-
-- **User-scoped data** (profiles, settings, personal records) — require OWN or DENY
-- **Admin surfaces** (user management, system config, audit logs) — require DENY for non-admin roles
-- **Financial data** (billing, payments, subscriptions) — require explicit DENY or OWN
-- **Destructive actions** (delete, bulk operations, account removal) — require explicit role gates
-- **API keys and credentials** — require DENY for non-owner roles
-
-If a sensitive surface exists in your codebase but is missing from the matrix, the integration checker's narrative auth check (Step 4) will still flag it — Step 4 runs unconditionally regardless of whether this matrix exists. Step 4a only verifies cells that are already in the matrix.
-
-## How the Integration Checker Uses This Matrix
-
-During milestone audits, the integration checker (Step 4a) will:
-
-1. Parse each row of the matrix table(s)
-2. For each cell (resource x role x expected permission):
-   - **ALLOW**: Verify the role can access the resource (no auth gate blocks it)
-   - **DENY**: Verify explicit rejection exists (middleware, guard, or policy denies access)
-   - **OWN**: Verify ownership check is enforced (not just auth, but scoped to the user's records)
-3. Report each cell as:
-   - **VERIFIED**: Implementation matches the matrix expectation
-   - **MISMATCH**: Implementation contradicts the matrix (e.g., DENY expected but no guard found)
-   - **UNTESTED**: Cannot determine from static analysis (e.g., dynamic policy evaluation)
-
-The narrative auth check (Step 4) always runs regardless of whether this matrix exists.
-
-## File Location
-
-Save your project's authorization matrix as `.planning/AUTH_MATRIX.md`.
-
-The integration checker will automatically detect and consume it when present. No configuration needed.
+# Authorization Matrix Template
+
+> OWASP-style authorization matrix for systematic auth verification.
+> Create `.planning/AUTH_MATRIX.md` using this template when your project has multiple user roles or protected resources.
+
+## When to Create This Matrix
+
+Create an authorization matrix when your project has:
+- Multiple user roles (e.g., anonymous, user, admin, owner)
+- Protected resources that vary by role
+- Ownership-scoped data (users can only access their own records)
+- Admin or operator surfaces that must be restricted
+
+Skip this matrix for single-role projects or projects with no auth requirements.
+
+## Matrix Format
+
+Use the OWASP pivot format: rows are resources, columns are roles, cells are permissions.
+
+### Permission Values
+
+| Value | Meaning |
+|-------|---------|
+| ALLOW | Role can perform this action on any matching resource |
+| DENY  | Role must be explicitly rejected (not just "no route") |
+| OWN   | Role can perform this action only on resources they own |
+| N/A   | Action does not apply to this resource |
+
+### Matrix Table
+
+```markdown
+| Resource | Action | anonymous | user | admin |
+|----------|--------|-----------|------|-------|
+| /login   | POST   | ALLOW     | ALLOW| ALLOW |
+| /profile | GET    | DENY      | OWN  | ALLOW |
+| /profile | PUT    | DENY      | OWN  | ALLOW |
+| /users   | GET    | DENY      | DENY | ALLOW |
+| /users   | DELETE | DENY      | DENY | ALLOW |
+| /posts   | GET    | ALLOW     | ALLOW| ALLOW |
+| /posts   | POST   | DENY      | ALLOW| ALLOW |
+| /posts   | DELETE | DENY      | OWN  | ALLOW |
+```
+
+Adapt the table to your project's actual resources, actions, and roles. Add or remove columns as needed.
+
+## Sensitive Surfaces
+
+The following resource categories MUST have matrix coverage when they exist in your project:
+
+- **User-scoped data** (profiles, settings, personal records) — require OWN or DENY
+- **Admin surfaces** (user management, system config, audit logs) — require DENY for non-admin roles
+- **Financial data** (billing, payments, subscriptions) — require explicit DENY or OWN
+- **Destructive actions** (delete, bulk operations, account removal) — require explicit role gates
+- **API keys and credentials** — require DENY for non-owner roles
+
+If a sensitive surface exists in your codebase but is missing from the matrix, the integration checker's narrative auth check (Step 4) will still flag it — Step 4 runs unconditionally regardless of whether this matrix exists. Step 4a only verifies cells that are already in the matrix.
+
+## How the Integration Checker Uses This Matrix
+
+During milestone audits, the integration checker (Step 4a) will:
+
+1. Parse each row of the matrix table(s)
+2. For each cell (resource x role x expected permission):
+   - **ALLOW**: Verify the role can access the resource (no auth gate blocks it)
+   - **DENY**: Verify explicit rejection exists (middleware, guard, or policy denies access)
+   - **OWN**: Verify ownership check is enforced (not just auth, but scoped to the user's records)
+3. Report each cell as:
+   - **VERIFIED**: Implementation matches the matrix expectation
+   - **MISMATCH**: Implementation contradicts the matrix (e.g., DENY expected but no guard found)
+   - **UNTESTED**: Cannot determine from static analysis (e.g., dynamic policy evaluation)
+
+The narrative auth check (Step 4) always runs regardless of whether this matrix exists.
+
+## File Location
+
+Save your project's authorization matrix as `.planning/AUTH_MATRIX.md`.
+
+The integration checker will automatically detect and consume it when present. No configuration needed.