gsdd-cli 0.18.4 → 0.19.0

package/distilled/templates/codebase/conventions.md

@@ -1,193 +1,193 @@
-# Codebase Conventions
-
-**Analysis Date:** [YYYY-MM-DD]
-
-<guidelines>
-- This document is durable intent (rules/patterns), not a directory dump.
-- Be prescriptive. If 80%+ of the codebase follows a pattern, document it as a rule ("Use X"), not as a survey ("Sometimes X").
-- Every non-trivial claim must include at least one concrete file path example.
-- Prefer "how to do it here" over general best practices.
-- Capture testing and mocking boundaries explicitly ("what NOT to mock"). Missing boundaries cause broken tests and slow CI.
-- Capture external integration patterns (webhook verification, auth session management). Missing these causes security vulnerabilities.
-</guidelines>
-
-## Naming Patterns
-
-Files:
-- [Pattern observed]
-
-Functions:
-- [Pattern observed]
-
-Variables:
-- [Pattern observed]
-
-Types:
-- [Pattern observed]
-
-## Code Style
-
-Formatting:
-- Tool: [Tool used]
-- Key settings: [Key settings]
-
-Linting:
-- Tool: [Tool used]
-- Key rules: [Key rules]
-
-## Import Organization
-
-Order:
-1. [First group]
-2. [Second group]
-3. [Third group]
-
-Path aliases:
-- [Aliases used]
-
-## Error Handling
-
-Patterns:
-- [How errors are handled]
-- Examples: `[file paths]`
-
-## Logging
-
-Framework:
-- [Tool or "console"]
-
-Patterns:
-- [When/how to log]
-- Examples: `[file paths]`
-
-## Module / Function Design
-
-Function size:
-- [Guidelines]
-
-Parameters:
-- [Pattern]
-
-Return values:
-- [Pattern]
-
-Exports:
-- [Pattern]
-
-## Convention Adoption Rates
-
-For each major convention documented above, estimate adoption rate using grep-counting (count occurrences in production source files, exclude `node_modules`, `vendor`, generated files). Use the format `~N% (stable|rising|declining)`.
-
-- Pattern requires ≥5 occurrences to estimate; below that, write "prevalence unknown — seen in multiple files."
-- Trend signal: stable = consistent across file age, rising = newer files adopt more, declining = older files adopt more.
-
-Examples:
-- Constructor injection: `~84% (declining)` — 37 of 44 service classes; newer files use factory functions
-- camelCase exports: `~100% (stable)` — enforced by lint rule, zero violations found
-- Inline error handling: `~62% (rising)` — 18 of 29 handlers; recent PRs consistently use this
-
-Replace examples with findings from this codebase.
-
-## Testing And Mocking (High-Leverage)
-
-Test types used:
-- Unit: [yes/no] (runner: [tool]) - examples: `[file paths]`
-- Integration: [yes/no] - examples: `[file paths]`
-- E2E: [yes/no] - examples: `[file paths]`
-
-Where tests live:
-- Unit tests: `[path pattern]`
-- Integration tests: `[path pattern]`
-- E2E tests: `[path pattern]`
-
-Fixtures and factories:
-- Where fixtures live: `[path pattern]`
-- Preferred factory pattern: [pattern]
-
-Mocking boundaries (explicit):
-- Do mock: [what is safe to mock here]
-- Do NOT mock: [what must remain real]
-- Why: [rationale grounded in this codebase]
-- Examples: `[file paths]`
-
-External calls:
-- Network calls in tests: [allowed/blocked]
-- How HTTP is stubbed: [pattern] - examples: `[file paths]`
-- DB usage in tests: [pattern] - examples: `[file paths]`
-
-CI reliability rules:
-- Timeouts: [standard value if any]
-- Flake policy: [rerun policy or "none"]
-- Test parallelism constraints: [if any]
-
-<good_examples>
-Example (good):
-- "All HTTP clients must be injected via `src/lib/http/client.ts` and mocked via `test/utils/mockHttp.ts` (do NOT mock `fetch` directly). See `src/services/billing.ts` and `test/services/billing.test.ts`."
-- "Integration tests use a real Postgres via Docker Compose. Do NOT mock DB queries; instead use `test/fixtures/dbSeed.ts`. See `test/integration/users.test.ts`."
-
-Example (bad):
-- "We use Jest and sometimes integration tests." (no paths, no boundaries, no rules)
-</good_examples>
-
-## External Integration Patterns (Security-Critical)
-
-Capture these only if external integrations exist. Missing these causes subtle security bugs.
-
-### Webhook Verification
-- Webhook endpoints: `[paths]`
-- Signature verification method: [HMAC-SHA256 / provider-specific / none]
-- Where verification happens: `[file path]` (middleware? route handler?)
-- Verified before or after parsing payload: [before — always verify raw body]
-- Do NOT: parse JSON before verifying signature (timing attacks)
-- Examples: `[file paths for webhook handlers]`
-
-### Authentication and Session Management
-- Auth provider: [JWT / session cookie / OAuth / API key / none]
-- Token storage (client): [httpOnly cookie / localStorage / memory]
-- Token storage (server): [Redis / DB / stateless]
-- Refresh logic: [how tokens are refreshed, where that code lives]
-- Where auth is enforced: [middleware path / per-route / both]
-- Protected vs public routes: [pattern or file]
-- Do NOT: store tokens in localStorage for sensitive apps (XSS risk)
-- Examples: `[file paths for auth middleware]`
-
-### Environment Configuration
-- Config loading: `[file path]` (e.g., `src/config/index.ts`)
-- Environment-specific overrides: [dev/staging/prod distinction]
-- Secrets access pattern: [env var / secrets manager / vault]
-- Do NOT: hardcode secrets; do NOT commit `.env` files
-- Examples: `[file paths]`
-
-### Observability Hooks
-- Request logging: [tool + where it's configured]
-- Error tracking: [tool + integration file path]
-- Performance monitoring: [tool + integration point]
-- Health check endpoint: `[path]` (e.g., `/health`)
-- Examples: `[file paths]`
-
-<good_examples>
-Example (good):
-- "Stripe webhooks are verified via `src/webhooks/stripe.ts:verifyStripeSignature()` using the raw request body before JSON parsing. Do NOT route Stripe events through the JSON body parser middleware. See `src/middleware/webhooks.ts`."
-- "Auth tokens are httpOnly cookies (not localStorage). Refresh happens via `src/auth/refresh.ts` called by the global axios interceptor. Token expiry = 15min access, 7-day refresh. See `src/lib/http.ts`."
-- "All secrets come from env vars loaded via `src/config/env.ts`. Never read `process.env` directly outside that file. Dev/staging/prod configs are in `.env.example`, `.env.staging`, `.env.production` (secrets redacted, committed)."
-
-Example (bad):
-- "We use JWT and have some webhooks." (no paths, no security rules, no boundaries)
-</good_examples>
-
-## Golden Files
-
-Identify 3–5 files that best exemplify this codebase's conventions. Selection algorithm: highest density of documented conventions in production feature files (not scaffolding, not generated code, not test files).
-
-Format: `file path — what makes it a good example`
-
-- `[path/to/file.ts]` — [which conventions it demonstrates, e.g., "named exports, constructor injection, custom error class, full test coverage"]
-- `[path/to/file.ts]` — [conventions it demonstrates]
-- `[path/to/file.ts]` — [conventions it demonstrates]
-
-If no single file exemplifies multiple conventions, list the best per-category file instead.
-
----
-
-*Convention analysis: [date]*
-
+# Codebase Conventions
+
+**Analysis Date:** [YYYY-MM-DD]
+
+<guidelines>
+- This document is durable intent (rules/patterns), not a directory dump.
+- Be prescriptive. If 80%+ of the codebase follows a pattern, document it as a rule ("Use X"), not as a survey ("Sometimes X").
+- Every non-trivial claim must include at least one concrete file path example.
+- Prefer "how to do it here" over general best practices.
+- Capture testing and mocking boundaries explicitly ("what NOT to mock"). Missing boundaries cause broken tests and slow CI.
+- Capture external integration patterns (webhook verification, auth session management). Missing these causes security vulnerabilities.
+</guidelines>
+
+## Naming Patterns
+
+Files:
+- [Pattern observed]
+
+Functions:
+- [Pattern observed]
+
+Variables:
+- [Pattern observed]
+
+Types:
+- [Pattern observed]
+
+## Code Style
+
+Formatting:
+- Tool: [Tool used]
+- Key settings: [Key settings]
+
+Linting:
+- Tool: [Tool used]
+- Key rules: [Key rules]
+
+## Import Organization
+
+Order:
+1. [First group]
+2. [Second group]
+3. [Third group]
+
+Path aliases:
+- [Aliases used]
+
+## Error Handling
+
+Patterns:
+- [How errors are handled]
+- Examples: `[file paths]`
+
+## Logging
+
+Framework:
+- [Tool or "console"]
+
+Patterns:
+- [When/how to log]
+- Examples: `[file paths]`
+
+## Module / Function Design
+
+Function size:
+- [Guidelines]
+
+Parameters:
+- [Pattern]
+
+Return values:
+- [Pattern]
+
+Exports:
+- [Pattern]
+
+## Convention Adoption Rates
+
+For each major convention documented above, estimate adoption rate using grep-counting (count occurrences in production source files, exclude `node_modules`, `vendor`, generated files). Use the format `~N% (stable|rising|declining)`.
+
+- Pattern requires ≥5 occurrences to estimate; below that, write "prevalence unknown — seen in multiple files."
+- Trend signal: stable = consistent across file age, rising = newer files adopt more, declining = older files adopt more.
+
+Examples:
+- Constructor injection: `~84% (declining)` — 37 of 44 service classes; newer files use factory functions
+- camelCase exports: `~100% (stable)` — enforced by lint rule, zero violations found
+- Inline error handling: `~62% (rising)` — 18 of 29 handlers; recent PRs consistently use this
+
+Replace examples with findings from this codebase.
+
+## Testing And Mocking (High-Leverage)
+
+Test types used:
+- Unit: [yes/no] (runner: [tool]) - examples: `[file paths]`
+- Integration: [yes/no] - examples: `[file paths]`
+- E2E: [yes/no] - examples: `[file paths]`
+
+Where tests live:
+- Unit tests: `[path pattern]`
+- Integration tests: `[path pattern]`
+- E2E tests: `[path pattern]`
+
+Fixtures and factories:
+- Where fixtures live: `[path pattern]`
+- Preferred factory pattern: [pattern]
+
+Mocking boundaries (explicit):
+- Do mock: [what is safe to mock here]
+- Do NOT mock: [what must remain real]
+- Why: [rationale grounded in this codebase]
+- Examples: `[file paths]`
+
+External calls:
+- Network calls in tests: [allowed/blocked]
+- How HTTP is stubbed: [pattern] - examples: `[file paths]`
+- DB usage in tests: [pattern] - examples: `[file paths]`
+
+CI reliability rules:
+- Timeouts: [standard value if any]
+- Flake policy: [rerun policy or "none"]
+- Test parallelism constraints: [if any]
+
+<good_examples>
+Example (good):
+- "All HTTP clients must be injected via `src/lib/http/client.ts` and mocked via `test/utils/mockHttp.ts` (do NOT mock `fetch` directly). See `src/services/billing.ts` and `test/services/billing.test.ts`."
+- "Integration tests use a real Postgres via Docker Compose. Do NOT mock DB queries; instead use `test/fixtures/dbSeed.ts`. See `test/integration/users.test.ts`."
+
+Example (bad):
+- "We use Jest and sometimes integration tests." (no paths, no boundaries, no rules)
+</good_examples>
+
+## External Integration Patterns (Security-Critical)
+
+Capture these only if external integrations exist. Missing these causes subtle security bugs.
+
+### Webhook Verification
+- Webhook endpoints: `[paths]`
+- Signature verification method: [HMAC-SHA256 / provider-specific / none]
+- Where verification happens: `[file path]` (middleware? route handler?)
+- Verified before or after parsing payload: [before — always verify raw body]
+- Do NOT: parse JSON before verifying signature (timing attacks)
+- Examples: `[file paths for webhook handlers]`
+
+### Authentication and Session Management
+- Auth provider: [JWT / session cookie / OAuth / API key / none]
+- Token storage (client): [httpOnly cookie / localStorage / memory]
+- Token storage (server): [Redis / DB / stateless]
+- Refresh logic: [how tokens are refreshed, where that code lives]
+- Where auth is enforced: [middleware path / per-route / both]
+- Protected vs public routes: [pattern or file]
+- Do NOT: store tokens in localStorage for sensitive apps (XSS risk)
+- Examples: `[file paths for auth middleware]`
+
+### Environment Configuration
+- Config loading: `[file path]` (e.g., `src/config/index.ts`)
+- Environment-specific overrides: [dev/staging/prod distinction]
+- Secrets access pattern: [env var / secrets manager / vault]
+- Do NOT: hardcode secrets; do NOT commit `.env` files
+- Examples: `[file paths]`
+
+### Observability Hooks
+- Request logging: [tool + where it's configured]
+- Error tracking: [tool + integration file path]
+- Performance monitoring: [tool + integration point]
+- Health check endpoint: `[path]` (e.g., `/health`)
+- Examples: `[file paths]`
+
+<good_examples>
+Example (good):
+- "Stripe webhooks are verified via `src/webhooks/stripe.ts:verifyStripeSignature()` using the raw request body before JSON parsing. Do NOT route Stripe events through the JSON body parser middleware. See `src/middleware/webhooks.ts`."
+- "Auth tokens are httpOnly cookies (not localStorage). Refresh happens via `src/auth/refresh.ts` called by the global axios interceptor. Token expiry = 15min access, 7-day refresh. See `src/lib/http.ts`."
+- "All secrets come from env vars loaded via `src/config/env.ts`. Never read `process.env` directly outside that file. Dev/staging/prod configs are in `.env.example`, `.env.staging`, `.env.production` (secrets redacted, committed)."
+
+Example (bad):
+- "We use JWT and have some webhooks." (no paths, no security rules, no boundaries)
+</good_examples>
+
+## Golden Files
+
+Identify 3–5 files that best exemplify this codebase's conventions. Selection algorithm: highest density of documented conventions in production feature files (not scaffolding, not generated code, not test files).
+
+Format: `file path — what makes it a good example`
+
+- `[path/to/file.ts]` — [which conventions it demonstrates, e.g., "named exports, constructor injection, custom error class, full test coverage"]
+- `[path/to/file.ts]` — [conventions it demonstrates]
+- `[path/to/file.ts]` — [conventions it demonstrates]
+
+If no single file exemplifies multiple conventions, list the best per-category file instead.
+
+---
+
+*Convention analysis: [date]*
+

package/distilled/templates/codebase/stack.md

@@ -1,96 +1,96 @@
-# Codebase Stack
-
-**Analysis Date:** [YYYY-MM-DD]
-
-<guidelines>
-- List versions only when they matter (compatibility, breaking changes, reproducibility).
-- Prefer commands and sources of truth (package.json, lockfiles, tool config) over memory.
-- Capture the minimum needed for another agent to run, test, and ship changes safely.
-- Include concrete commands and file paths.
-</guidelines>
-
-## Languages
-
-Primary:
-- [Language] [Version if relevant] - used in: `[paths]`
-
-Secondary:
-- [Language] [Version if relevant] - used in: `[paths]`
-
-## Runtime
-
-Environment:
-- [Runtime] [Version if relevant]
-
-Package manager:
-- [Manager] [Version if relevant]
-- Lockfile: [present/missing] - `[path]`
-
-## Frameworks And Tooling
-
-Core framework(s):
-- [Framework] [Version if relevant] - purpose: [purpose]
-
-Testing:
-- [Tool] [Version if relevant] - purpose: [purpose]
-
-Build / dev:
-- [Tool] [Version if relevant] - purpose: [purpose]
-
-Lint / format:
-- [Tool] - config: `[path]`
-
-## Key Dependencies (Only What Drives Architecture)
-
-Critical libraries:
-- [Package] - why it matters: [reason] - examples: `[paths]`
-
-Infra/observability:
-- [Package] - purpose: [reason] - config: `[paths]`
-
-## Must-Know Packages
-
-Flag 3–5 packages that new contributors must understand before making changes. These are not necessarily the most-used packages — they are the ones where misuse causes hard-to-debug problems.
-
-Each entry: `package-name — why it's critical — risk: low|medium|high — common mistake: what goes wrong`
-
-Risk levels: low (causes build errors — immediately visible), medium (causes runtime bugs — visible in testing), high (causes data corruption or silent failures — hard to detect).
-
-- `[package]` — [why critical] — risk: [level] — common mistake: [what goes wrong]
-- `[package]` — [why critical] — risk: [level] — common mistake: [what goes wrong]
-- `[package]` — [why critical] — risk: [level] — common mistake: [what goes wrong]
-
-## How To Run
-
-Install:
-- Command(s): `[commands]`
-
-Dev:
-- Command(s): `[commands]`
-
-Test:
-- Command(s): `[commands]`
-
-Build:
-- Command(s): `[commands]`
-
-## Configuration
-
-Env:
-- How configured: [dotenv, env vars, config files]
-- Key config files: `[paths]`
-
-CI/CD:
-- CI location: `[path]`
-- Main checks: [list]
-
-<good_examples>
-Example (good):
-- "Node 20, pnpm. Install: `pnpm i`. Tests: `pnpm test` (Vitest) + `pnpm test:e2e` (Playwright). Formatting: Prettier (`.prettierrc`). Lint: ESLint (`eslint.config.mjs`)."
-- "DB migrations run via `pnpm db:migrate` (see `package.json` scripts)."
-</good_examples>
-
----
-
-*Stack analysis: [date]*
-
+# Codebase Stack
+
+**Analysis Date:** [YYYY-MM-DD]
+
+<guidelines>
+- List versions only when they matter (compatibility, breaking changes, reproducibility).
+- Prefer commands and sources of truth (package.json, lockfiles, tool config) over memory.
+- Capture the minimum needed for another agent to run, test, and ship changes safely.
+- Include concrete commands and file paths.
+</guidelines>
+
+## Languages
+
+Primary:
+- [Language] [Version if relevant] - used in: `[paths]`
+
+Secondary:
+- [Language] [Version if relevant] - used in: `[paths]`
+
+## Runtime
+
+Environment:
+- [Runtime] [Version if relevant]
+
+Package manager:
+- [Manager] [Version if relevant]
+- Lockfile: [present/missing] - `[path]`
+
+## Frameworks And Tooling
+
+Core framework(s):
+- [Framework] [Version if relevant] - purpose: [purpose]
+
+Testing:
+- [Tool] [Version if relevant] - purpose: [purpose]
+
+Build / dev:
+- [Tool] [Version if relevant] - purpose: [purpose]
+
+Lint / format:
+- [Tool] - config: `[path]`
+
+## Key Dependencies (Only What Drives Architecture)
+
+Critical libraries:
+- [Package] - why it matters: [reason] - examples: `[paths]`
+
+Infra/observability:
+- [Package] - purpose: [reason] - config: `[paths]`
+
+## Must-Know Packages
+
+Flag 3–5 packages that new contributors must understand before making changes. These are not necessarily the most-used packages — they are the ones where misuse causes hard-to-debug problems.
+
+Each entry: `package-name — why it's critical — risk: low|medium|high — common mistake: what goes wrong`
+
+Risk levels: low (causes build errors — immediately visible), medium (causes runtime bugs — visible in testing), high (causes data corruption or silent failures — hard to detect).
+
+- `[package]` — [why critical] — risk: [level] — common mistake: [what goes wrong]
+- `[package]` — [why critical] — risk: [level] — common mistake: [what goes wrong]
+- `[package]` — [why critical] — risk: [level] — common mistake: [what goes wrong]
+
+## How To Run
+
+Install:
+- Command(s): `[commands]`
+
+Dev:
+- Command(s): `[commands]`
+
+Test:
+- Command(s): `[commands]`
+
+Build:
+- Command(s): `[commands]`
+
+## Configuration
+
+Env:
+- How configured: [dotenv, env vars, config files]
+- Key config files: `[paths]`
+
+CI/CD:
+- CI location: `[path]`
+- Main checks: [list]
+
+<good_examples>
+Example (good):
+- "Node 20, pnpm. Install: `pnpm i`. Tests: `pnpm test` (Vitest) + `pnpm test:e2e` (Playwright). Formatting: Prettier (`.prettierrc`). Lint: ESLint (`eslint.config.mjs`)."
+- "DB migrations run via `pnpm db:migrate` (see `package.json` scripts)."
+</good_examples>
+
+---
+
+*Stack analysis: [date]*
+

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

@@ -1,25 +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.
+**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.