gsdd-cli 0.18.5 → 0.19.1

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,28 @@
-**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.
+
+When `workflow.discuss: true`, APPROACH.md must prove user alignment before planning: use `alignment_status: user_confirmed` for real user-confirmed decisions or `alignment_status: approved_skip` only when the user explicitly approves skipping discussion. Record the canonical fields `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 alignment proof.
+
+Read only the explicit inputs provided by the orchestrator:
+- target phase goal and requirement IDs from `.planning/ROADMAP.md`
+- project config from `.planning/config.json`, especially `workflow.discuss`
+- 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/mapper-arch.md

@@ -1,26 +1,26 @@
-**Role contract:** Read `.planning/templates/roles/mapper.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
-
-Map the architecture and structure of this codebase. Read key source files to understand component boundaries, data flow, and patterns.
-
-Write ARCHITECTURE.md to `.planning/codebase/` using the template at `.planning/templates/codebase/architecture.md`.
-
-Include:
-- Major components and their responsibilities (what belongs in each, what doesn't)
-- Data flow direction (not just "they communicate" — which way does data move)
-- "Change Routing" table: where to add new code by change type (new endpoint? new model? new UI component?)
-- Key architectural patterns used (e.g., event-driven, layered, modular monolith)
-- Golden files per layer: for each major layer, the single most-imported file (highest inbound import count = most stable, most understood); use import frequency as the signal, not judgment
-
-**Anti-staleness:** Do NOT include static directory trees or full file inventories. DO include file paths for key components, entry points, and architectural boundaries (e.g., `src/services/user.ts`) -- downstream agents navigate directly to files.
-
-<quality_gate>
-- [ ] Components have clear responsibility boundaries
-- [ ] Data flow direction is explicit
-- [ ] Change Routing table is populated (where to add new code by type)
-- [ ] Hard-to-reverse architectural decisions flagged
-- [ ] Golden files table populated with at least one file per major layer
-</quality_gate>
-
-Write to: `.planning/codebase/ARCHITECTURE.md`
-Return: 3-5 sentence summary to the Orchestrator when done.
-Guardrails: Max Agent Hops = 3. No static directory dumps.
+**Role contract:** Read `.planning/templates/roles/mapper.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
+
+Map the architecture and structure of this codebase. Read key source files to understand component boundaries, data flow, and patterns.
+
+Write ARCHITECTURE.md to `.planning/codebase/` using the template at `.planning/templates/codebase/architecture.md`.
+
+Include:
+- Major components and their responsibilities (what belongs in each, what doesn't)
+- Data flow direction (not just "they communicate" — which way does data move)
+- "Change Routing" table: where to add new code by change type (new endpoint? new model? new UI component?)
+- Key architectural patterns used (e.g., event-driven, layered, modular monolith)
+- Golden files per layer: for each major layer, the single most-imported file (highest inbound import count = most stable, most understood); use import frequency as the signal, not judgment
+
+**Anti-staleness:** Do NOT include static directory trees or full file inventories. DO include file paths for key components, entry points, and architectural boundaries (e.g., `src/services/user.ts`) -- downstream agents navigate directly to files.
+
+<quality_gate>
+- [ ] Components have clear responsibility boundaries
+- [ ] Data flow direction is explicit
+- [ ] Change Routing table is populated (where to add new code by type)
+- [ ] Hard-to-reverse architectural decisions flagged
+- [ ] Golden files table populated with at least one file per major layer
+</quality_gate>
+
+Write to: `.planning/codebase/ARCHITECTURE.md`
+Return: 3-5 sentence summary to the Orchestrator when done.
+Guardrails: Max Agent Hops = 3. No static directory dumps.

package/distilled/templates/delegates/mapper-concerns.md

@@ -1,27 +1,27 @@
-**Role contract:** Read `.planning/templates/roles/mapper.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
-
-Map the technical debt, security concerns, and risks in this codebase.
-
-**Security check first (hard stop):** Follow the Hard stop directive in `.planning/templates/roles/mapper.md` — grep for secrets before writing anything. If found: STOP and report to Orchestrator immediately.
-
-If no secrets found, write CONCERNS.md to `.planning/codebase/` using the template at `.planning/templates/codebase/concerns.md`.
-
-Include:
-- Known bugs or fragile areas (with file references where possible)
-- Security vulnerabilities or missing validations
-- Performance bottlenecks
-- Missing test coverage for critical paths
-- Deprecated or end-of-life dependencies
-- Downstream impact ranking: top 3 concerns ranked by how much future work they block (concerns blocking multiple change-routing rows from ARCHITECTURE.md rank highest, not just by severity)
-
-<quality_gate>
-- [ ] Secret scan completed and result reported
-- [ ] Concerns are specific (file references, not vague "some places")
-- [ ] Severity assigned per concern: critical / moderate / minor
-- [ ] Deprecated dependencies listed with EOL dates if known
-- [ ] Downstream impact table ranks at least top 3 concerns with Blocks column populated
-</quality_gate>
-
-Write to: `.planning/codebase/CONCERNS.md`
-Return: 3-5 sentence summary to the Orchestrator when done. If secrets found, STOP and report immediately.
-Guardrails: Max Agent Hops = 3. Hard stop on secrets.
+**Role contract:** Read `.planning/templates/roles/mapper.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
+
+Map the technical debt, security concerns, and risks in this codebase.
+
+**Security check first (hard stop):** Follow the Hard stop directive in `.planning/templates/roles/mapper.md` — grep for secrets before writing anything. If found: STOP and report to Orchestrator immediately.
+
+If no secrets found, write CONCERNS.md to `.planning/codebase/` using the template at `.planning/templates/codebase/concerns.md`.
+
+Include:
+- Known bugs or fragile areas (with file references where possible)
+- Security vulnerabilities or missing validations
+- Performance bottlenecks
+- Missing test coverage for critical paths
+- Deprecated or end-of-life dependencies
+- Downstream impact ranking: top 3 concerns ranked by how much future work they block (concerns blocking multiple change-routing rows from ARCHITECTURE.md rank highest, not just by severity)
+
+<quality_gate>
+- [ ] Secret scan completed and result reported
+- [ ] Concerns are specific (file references, not vague "some places")
+- [ ] Severity assigned per concern: critical / moderate / minor
+- [ ] Deprecated dependencies listed with EOL dates if known
+- [ ] Downstream impact table ranks at least top 3 concerns with Blocks column populated
+</quality_gate>
+
+Write to: `.planning/codebase/CONCERNS.md`
+Return: 3-5 sentence summary to the Orchestrator when done. If secrets found, STOP and report immediately.
+Guardrails: Max Agent Hops = 3. Hard stop on secrets.

package/distilled/templates/delegates/mapper-quality.md

@@ -1,28 +1,28 @@
-**Role contract:** Read `.planning/templates/roles/mapper.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
-
-Map the conventions and quality patterns of this codebase. Read existing tests, lint config, and code samples.
-
-Write CONVENTIONS.md to `.planning/codebase/` using the template at `.planning/templates/codebase/conventions.md`.
-
-Include:
-- Naming patterns (files, functions, variables, exports)
-- Code style rules enforced by lint/format config
-- Testing and mocking boundaries — explicit "Do mock" / "Do NOT mock" rules with examples
-- External integration patterns: webhook signature verification, auth session management, environment config
-- CI reliability rules (what must pass before merge)
-- Convention adoption rates: for each major convention, estimate `~N% (stable|rising|declining)` using grep-counting (≥5 occurrences required; below that write "prevalence unknown — seen in multiple files")
-- Golden files: 2–3 production files with the highest density of documented conventions (not scaffolding, not generated, not tests); format: `file path — which conventions it demonstrates`
-
-**Anti-staleness:** Do NOT enumerate test files or list every convention observed. Document rules and patterns: the invariants, not the inventory.
-
-<quality_gate>
-- [ ] Mocking boundaries are explicit ("Do mock: X" / "Do NOT mock: Y")
-- [ ] External integration security rules included (webhook, auth, env config)
-- [ ] Rules are actionable ("always do X"), not descriptive ("the codebase uses X")
-- [ ] At least one convention has a quantified adoption rate (e.g., `~N% (stable|rising|declining)`)
-- [ ] Golden files section lists at least 2 files with rationale
-</quality_gate>
-
-Write to: `.planning/codebase/CONVENTIONS.md`
-Return: 3-5 sentence summary to the Orchestrator when done.
-Guardrails: Max Agent Hops = 3. Rules not inventories.
+**Role contract:** Read `.planning/templates/roles/mapper.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
+
+Map the conventions and quality patterns of this codebase. Read existing tests, lint config, and code samples.
+
+Write CONVENTIONS.md to `.planning/codebase/` using the template at `.planning/templates/codebase/conventions.md`.
+
+Include:
+- Naming patterns (files, functions, variables, exports)
+- Code style rules enforced by lint/format config
+- Testing and mocking boundaries — explicit "Do mock" / "Do NOT mock" rules with examples
+- External integration patterns: webhook signature verification, auth session management, environment config
+- CI reliability rules (what must pass before merge)
+- Convention adoption rates: for each major convention, estimate `~N% (stable|rising|declining)` using grep-counting (≥5 occurrences required; below that write "prevalence unknown — seen in multiple files")
+- Golden files: 2–3 production files with the highest density of documented conventions (not scaffolding, not generated, not tests); format: `file path — which conventions it demonstrates`
+
+**Anti-staleness:** Do NOT enumerate test files or list every convention observed. Document rules and patterns: the invariants, not the inventory.
+
+<quality_gate>
+- [ ] Mocking boundaries are explicit ("Do mock: X" / "Do NOT mock: Y")
+- [ ] External integration security rules included (webhook, auth, env config)
+- [ ] Rules are actionable ("always do X"), not descriptive ("the codebase uses X")
+- [ ] At least one convention has a quantified adoption rate (e.g., `~N% (stable|rising|declining)`)
+- [ ] Golden files section lists at least 2 files with rationale
+</quality_gate>
+
+Write to: `.planning/codebase/CONVENTIONS.md`
+Return: 3-5 sentence summary to the Orchestrator when done.
+Guardrails: Max Agent Hops = 3. Rules not inventories.

package/distilled/templates/delegates/mapper-tech.md

@@ -1,25 +1,25 @@
-**Role contract:** Read `.planning/templates/roles/mapper.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
-
-Map the technology stack of this codebase. Read package manifests, lockfiles, and entry points.
-
-Write STACK.md to `.planning/codebase/` using the template at `.planning/templates/codebase/stack.md`.
-
-Include:
-- Languages and runtimes (with versions)
-- Frameworks and key libraries (10-20 most important, not the full lockfile)
-- Infrastructure and deployment tooling
-- For each package: why it matters to this project (not just what it is)
-- Must-know packages: 3–5 packages where misuse causes the hardest-to-debug problems; include risk index (low/medium/high) and the common mistake to avoid
-
-**Anti-staleness:** Do NOT dump the full lockfile or dependency tree. Include only packages with architectural significance and note why they matter.
-
-<quality_gate>
-- [ ] 10-20 packages listed with version + rationale (not a lockfile dump)
-- [ ] Build/deploy tooling included
-- [ ] Any deprecated or risky dependencies flagged
-- [ ] Must-know packages section identifies at least 3 packages with risk index (low/medium/high)
-</quality_gate>
-
-Write to: `.planning/codebase/STACK.md`
-Return: 3-5 sentence summary to the Orchestrator when done.
-Guardrails: Max Agent Hops = 3. No static dependency dumps.
+**Role contract:** Read `.planning/templates/roles/mapper.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
+
+Map the technology stack of this codebase. Read package manifests, lockfiles, and entry points.
+
+Write STACK.md to `.planning/codebase/` using the template at `.planning/templates/codebase/stack.md`.
+
+Include:
+- Languages and runtimes (with versions)
+- Frameworks and key libraries (10-20 most important, not the full lockfile)
+- Infrastructure and deployment tooling
+- For each package: why it matters to this project (not just what it is)
+- Must-know packages: 3–5 packages where misuse causes the hardest-to-debug problems; include risk index (low/medium/high) and the common mistake to avoid
+
+**Anti-staleness:** Do NOT dump the full lockfile or dependency tree. Include only packages with architectural significance and note why they matter.
+
+<quality_gate>
+- [ ] 10-20 packages listed with version + rationale (not a lockfile dump)
+- [ ] Build/deploy tooling included
+- [ ] Any deprecated or risky dependencies flagged
+- [ ] Must-know packages section identifies at least 3 packages with risk index (low/medium/high)
+</quality_gate>
+
+Write to: `.planning/codebase/STACK.md`
+Return: 3-5 sentence summary to the Orchestrator when done.
+Guardrails: Max Agent Hops = 3. No static dependency dumps.