gsdd-cli 0.18.5 → 0.19.1

package/distilled/templates/research/features.md

@@ -1,23 +1,23 @@
-# FEATURES.md — Feature Landscape
-
-## Table Stakes
-Features users expect. Without them, your product feels broken.
-
-- [ ] [feature] — [why it's expected]
-- [ ] [feature] — [why it's expected]
-
-## Differentiators
-Features that set you apart from competitors.
-
-- [ ] [feature] — [what makes this unique]
-- [ ] [feature] — [competitive advantage]
-
-## Anti-Features
-Things to deliberately NOT build. Complexity traps.
-
-- [ ] [feature to avoid] — [why: complexity trap / scope creep / premature optimization]
-- [ ] [feature to avoid] — [why]
-
-## Sources
-- [Competitor 1] — [what they do well / poorly]
-- [Competitor 2] — [what they do well / poorly]
+# FEATURES.md — Feature Landscape
+
+## Table Stakes
+Features users expect. Without them, your product feels broken.
+
+- [ ] [feature] — [why it's expected]
+- [ ] [feature] — [why it's expected]
+
+## Differentiators
+Features that set you apart from competitors.
+
+- [ ] [feature] — [what makes this unique]
+- [ ] [feature] — [competitive advantage]
+
+## Anti-Features
+Things to deliberately NOT build. Complexity traps.
+
+- [ ] [feature to avoid] — [why: complexity trap / scope creep / premature optimization]
+- [ ] [feature to avoid] — [why]
+
+## Sources
+- [Competitor 1] — [what they do well / poorly]
+- [Competitor 2] — [what they do well / poorly]

package/distilled/templates/research/pitfalls.md

@@ -1,46 +1,46 @@
-# Pitfalls Research Template
-
-Use when researching common mistakes and gotchas for a domain or technology.
-
-Write to: `.planning/research/PITFALLS.md`
-
----
-
-```markdown
-# Pitfalls
-
-**Domain**: [what we're building]
-**Researched**: [date]
-
-## Pitfall 1: [Name]
-
-**What goes wrong**: [description]
-**Why it happens**: [root cause]
-**How to avoid**: [prevention strategy]
-**Warning signs**: [how to detect early]
-
-## Pitfall 2: [Name]
-
-**What goes wrong**: [description]
-**Why it happens**: [root cause]
-**How to avoid**: [prevention strategy]
-**Warning signs**: [how to detect early]
-
-## Pitfall 3: [Name]
-
-**What goes wrong**: [description]
-**Why it happens**: [root cause]
-**How to avoid**: [prevention strategy]
-**Warning signs**: [how to detect early]
-
----
-*These pitfalls should inform verification criteria in the roadmap.*
-```
-
-## Guidelines
-
-- **Be specific to the domain** — not generic advice like "write tests"
-- **Warning signs** are crucial — they let you catch problems early
-- **Prevention strategies** should be actionable, not vague
-- 3-5 pitfalls is the sweet spot — more than 5 and none get remembered
-- **Link to phases**: note which roadmap phase should address each pitfall
+# Pitfalls Research Template
+
+Use when researching common mistakes and gotchas for a domain or technology.
+
+Write to: `.planning/research/PITFALLS.md`
+
+---
+
+```markdown
+# Pitfalls
+
+**Domain**: [what we're building]
+**Researched**: [date]
+
+## Pitfall 1: [Name]
+
+**What goes wrong**: [description]
+**Why it happens**: [root cause]
+**How to avoid**: [prevention strategy]
+**Warning signs**: [how to detect early]
+
+## Pitfall 2: [Name]
+
+**What goes wrong**: [description]
+**Why it happens**: [root cause]
+**How to avoid**: [prevention strategy]
+**Warning signs**: [how to detect early]
+
+## Pitfall 3: [Name]
+
+**What goes wrong**: [description]
+**Why it happens**: [root cause]
+**How to avoid**: [prevention strategy]
+**Warning signs**: [how to detect early]
+
+---
+*These pitfalls should inform verification criteria in the roadmap.*
+```
+
+## Guidelines
+
+- **Be specific to the domain** — not generic advice like "write tests"
+- **Warning signs** are crucial — they let you catch problems early
+- **Prevention strategies** should be actionable, not vague
+- 3-5 pitfalls is the sweet spot — more than 5 and none get remembered
+- **Link to phases**: note which roadmap phase should address each pitfall

package/distilled/templates/research/stack.md

@@ -1,45 +1,45 @@
-# Stack Research Template
-
-Use when researching the technology stack for a project or phase.
-
-Write to: `.planning/research/STACK.md`
-
----
-
-```markdown
-# Stack Research
-
-**Domain**: [what we're building]
-**Researched**: [date]
-
-## Recommended Stack
-
-| Library/Tool | Version | Purpose | Why This One |
-|-------------|---------|---------|--------------|
-| [name] | [ver] | [what it does] | [why it's the right choice] |
-| [name] | [ver] | [what it does] | [why it's the right choice] |
-
-## Alternatives Considered
-
-| Recommended | Alternative | Why Not |
-|-------------|------------|---------|
-| [choice] | [option] | [tradeoff] |
-
-## Don't Hand-Roll
-
-Problems that look simple but have battle-tested solutions:
-
-| Problem | Don't Build | Use Instead | Why |
-|---------|------------|-------------|-----|
-| [problem] | [custom solution] | [library] | [edge cases you'd miss] |
-
----
-*Confidence: [HIGH/MEDIUM/LOW]*
-```
-
-## Guidelines
-
-- **Specific versions** — not "latest", give actual numbers
-- **"Why This One"** matters more than "What It Does"
-- **Don't Hand-Roll** is the highest-value section — prevents wasted effort on solved problems
-- Keep to ~30-40 lines when filled out
+# Stack Research Template
+
+Use when researching the technology stack for a project or phase.
+
+Write to: `.planning/research/STACK.md`
+
+---
+
+```markdown
+# Stack Research
+
+**Domain**: [what we're building]
+**Researched**: [date]
+
+## Recommended Stack
+
+| Library/Tool | Version | Purpose | Why This One |
+|-------------|---------|---------|--------------|
+| [name] | [ver] | [what it does] | [why it's the right choice] |
+| [name] | [ver] | [what it does] | [why it's the right choice] |
+
+## Alternatives Considered
+
+| Recommended | Alternative | Why Not |
+|-------------|------------|---------|
+| [choice] | [option] | [tradeoff] |
+
+## Don't Hand-Roll
+
+Problems that look simple but have battle-tested solutions:
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|------------|-------------|-----|
+| [problem] | [custom solution] | [library] | [edge cases you'd miss] |
+
+---
+*Confidence: [HIGH/MEDIUM/LOW]*
+```
+
+## Guidelines
+
+- **Specific versions** — not "latest", give actual numbers
+- **"Why This One"** matters more than "What It Does"
+- **Don't Hand-Roll** is the highest-value section — prevents wasted effort on solved problems
+- Keep to ~30-40 lines when filled out

package/distilled/templates/research/summary.md

@@ -1,67 +1,67 @@
-# Research Summary
-
-**Date:** [YYYY-MM-DD]
-**Topic:** [Domain/feature area]
-**Milestone context:** [greenfield | subsequent]
-
-## Executive Summary (5-10 bullets)
-- [What we learned, in actionable terms — one concrete insight per bullet]
-
-## Confidence Assessment
-
-| Area | Confidence | Rationale |
-|------|-----------|-----------|
-| Stack choices | ✅ verified / ⚠️ likely / ❓ uncertain | [why] |
-| Feature set | ✅ verified / ⚠️ likely / ❓ uncertain | [why] |
-| Architecture pattern | ✅ verified / ⚠️ likely / ❓ uncertain | [why] |
-| Key pitfalls | ✅ verified / ⚠️ likely / ❓ uncertain | [why] |
-
-## Recommendations (Prescriptive)
-
-For each recommendation, include confidence and the evidence.
-
-1. Recommendation: [Use X / Avoid Y]
-   - Confidence: [verified | likely | uncertain]
-   - Why: [short rationale]
-   - Evidence: [URL(s)]
-   - Counterpoints / tradeoffs: [what would change the decision]
-
-## Non-Goals / Anti-Features
-- [What we explicitly will not do in v1, and why — grounded in research findings]
-
-## Pitfalls To Avoid
-- [Concrete mistakes teams make in this domain — phase-mapped where possible]
-
-## Open Questions (Blockers)
-- [What must be decided before planning can proceed]
-
-## Implications for Roadmap
-
-This section is the critical handoff from research to ROADMAP.md. The roadmapper reads this.
-
-### Suggested Phase Structure
-Derived from architecture build order + pitfall avoidance priorities:
-
-| Phase | Focus | Rationale |
-|-------|-------|-----------|
-| Phase 1 | [Foundation: e.g., data model + auth] | [why this must come first — dependency or risk] |
-| Phase 2 | [Core: e.g., primary user workflow] | [what unblocks after Phase 1] |
-| Phase 3 | [Integration: e.g., external services] | [why deferred — complexity or dependency] |
-| Phase N | [Polish / edge cases] | [why last] |
-
-### Research Flags (Phase-Level)
-These are signals for the planner — which phases need deeper domain research vs standard patterns:
-
-| Phase | Flag | Reason |
-|-------|------|--------|
-| Phase 1 | ⚠️ Needs deeper research | [e.g., "auth pattern depends on regulatory context"] |
-| Phase 2 | ✅ Standard pattern | [e.g., "CRUD with established library — no surprises"] |
-| Phase N | ❓ Uncertain | [e.g., "real-time sync has multiple viable approaches"] |
-
-## Sources
-
-| Claim | URL | Accessed |
-|-------|-----|---------|
-| [Stack recommendation] | [URL] | [YYYY-MM-DD] |
-| [Architecture pattern] | [URL] | [YYYY-MM-DD] |
-| [Pitfall] | [URL] | [YYYY-MM-DD] |
+# Research Summary
+
+**Date:** [YYYY-MM-DD]
+**Topic:** [Domain/feature area]
+**Milestone context:** [greenfield | subsequent]
+
+## Executive Summary (5-10 bullets)
+- [What we learned, in actionable terms — one concrete insight per bullet]
+
+## Confidence Assessment
+
+| Area | Confidence | Rationale |
+|------|-----------|-----------|
+| Stack choices | ✅ verified / ⚠️ likely / ❓ uncertain | [why] |
+| Feature set | ✅ verified / ⚠️ likely / ❓ uncertain | [why] |
+| Architecture pattern | ✅ verified / ⚠️ likely / ❓ uncertain | [why] |
+| Key pitfalls | ✅ verified / ⚠️ likely / ❓ uncertain | [why] |
+
+## Recommendations (Prescriptive)
+
+For each recommendation, include confidence and the evidence.
+
+1. Recommendation: [Use X / Avoid Y]
+   - Confidence: [verified | likely | uncertain]
+   - Why: [short rationale]
+   - Evidence: [URL(s)]
+   - Counterpoints / tradeoffs: [what would change the decision]
+
+## Non-Goals / Anti-Features
+- [What we explicitly will not do in v1, and why — grounded in research findings]
+
+## Pitfalls To Avoid
+- [Concrete mistakes teams make in this domain — phase-mapped where possible]
+
+## Open Questions (Blockers)
+- [What must be decided before planning can proceed]
+
+## Implications for Roadmap
+
+This section is the critical handoff from research to ROADMAP.md. The roadmapper reads this.
+
+### Suggested Phase Structure
+Derived from architecture build order + pitfall avoidance priorities:
+
+| Phase | Focus | Rationale |
+|-------|-------|-----------|
+| Phase 1 | [Foundation: e.g., data model + auth] | [why this must come first — dependency or risk] |
+| Phase 2 | [Core: e.g., primary user workflow] | [what unblocks after Phase 1] |
+| Phase 3 | [Integration: e.g., external services] | [why deferred — complexity or dependency] |
+| Phase N | [Polish / edge cases] | [why last] |
+
+### Research Flags (Phase-Level)
+These are signals for the planner — which phases need deeper domain research vs standard patterns:
+
+| Phase | Flag | Reason |
+|-------|------|--------|
+| Phase 1 | ⚠️ Needs deeper research | [e.g., "auth pattern depends on regulatory context"] |
+| Phase 2 | ✅ Standard pattern | [e.g., "CRUD with established library — no surprises"] |
+| Phase N | ❓ Uncertain | [e.g., "real-time sync has multiple viable approaches"] |
+
+## Sources
+
+| Claim | URL | Accessed |
+|-------|-----|---------|
+| [Stack recommendation] | [URL] | [YYYY-MM-DD] |
+| [Architecture pattern] | [URL] | [YYYY-MM-DD] |
+| [Pitfall] | [URL] | [YYYY-MM-DD] |

package/distilled/templates/roadmap.md

@@ -1,62 +1,74 @@
-# ROADMAP.md Template
-
-Use this template when creating `.planning/ROADMAP.md` (phase breakdown + progress tracker).
-
-```markdown
-# Roadmap: [Project Name]
-
-## Overview
-
-[One paragraph: what v1 delivers and why.]
-
-## Phases (Status Legend: [ ] not started, [-] in progress, [x] complete)
-
-- [ ] **Phase 1: [Name]** - [One-line goal]
-- [ ] **Phase 2: [Name]** - [One-line goal]
-- [ ] **Phase 3: [Name]** - [One-line goal]
-
-## Phase Details
-
-### Phase 1: [Name]
-
-**Goal**: [What this phase delivers]
-**Status**: [ ] / [-] / [x]
-**Requirements**: [REQ-IDs from `.planning/SPEC.md`]
-**Success Criteria** (must be TRUE when done):
-1. [Observable behavior]
-2. [Observable behavior]
-
-### Phase 2: [Name]
-
-**Goal**: [What this phase delivers]
-**Status**: [ ] / [-] / [x]
-**Depends on**: Phase 1
-**Requirements**: [REQ-IDs]
-**Success Criteria**:
-1. [Observable behavior]
-2. [Observable behavior]
-
----
-*Created: [YYYY-MM-DD]*
-```
-
-## Guidelines
-
-- Prefer 3-8 phases for most projects.
-- Every v1 requirement in `.planning/SPEC.md` must map to exactly one phase (no orphans).
-- Success criteria are 2-5 observable behaviors per phase.
-- No time estimates: focus on verifiable outcomes.
-- These status markers are the portable source of truth. Workflow files and summaries should use `[ ]`, `[-]`, and `[x]` consistently.
-
-## Coverage Verification
-
-After creating the roadmap, verify:
-```
-For each v1 requirement in .planning/SPEC.md:
-  [ ] Requirement appears in exactly one phase's "Requirements" list
-  [ ] The phase's success criteria would prove the requirement is met
-```
-
-If a requirement doesn't map to any phase: add a phase or expand an existing one.
-If a requirement maps to multiple phases: clarify which phase owns it.
-
+# ROADMAP.md Template
+
+Use this template when creating `.planning/ROADMAP.md` (phase breakdown + progress tracker).
+
+```markdown
+# Roadmap: [Project Name]
+
+## Overview
+
+[One paragraph: what v1 delivers and why.]
+
+## Phases (Status Legend: [ ] not started, [-] in progress, [x] complete)
+
+- [ ] **Phase 1: [Name]** - [One-line goal]
+- [ ] **Phase 2: [Name]** - [One-line goal]
+- [ ] **Phase 3: [Name]** - [One-line goal]
+
+## Phase Details
+
+### Phase 1: [Name]
+
+**Goal**: [What this phase delivers]
+**Status**: [ ]
+**Requirements**: [REQ-IDs from `.planning/SPEC.md`]
+**Success Criteria** (must be TRUE when done):
+1. [Observable behavior]
+2. [Observable behavior]
+
+### Phase 2: [Name]
+
+**Goal**: [What this phase delivers]
+**Status**: [ ]
+**Depends on**: Phase 1
+**Requirements**: [REQ-IDs]
+**Success Criteria**:
+1. [Observable behavior]
+2. [Observable behavior]
+
+### Phase 3: [Name]
+
+**Goal**: [What this phase delivers]
+**Status**: [ ]
+**Depends on**: Phase 2
+**Requirements**: [REQ-IDs]
+**Success Criteria**:
+1. [Observable behavior]
+2. [Observable behavior]
+
+---
+*Created: [YYYY-MM-DD]*
+```
+
+## Guidelines
+
+- Prefer 3-8 phases for most projects.
+- Every v1 requirement in `.planning/SPEC.md` must map to exactly one phase (no orphans).
+- Success criteria are 2-5 observable behaviors per phase.
+- No time estimates: focus on verifiable outcomes.
+- These status markers are the portable source of truth. Workflow files and summaries should use `[ ]`, `[-]`, and `[x]` consistently.
+- Keep each overview phase marker and its matching Phase Details `**Status**` marker identical. Use `gsdd phase-status <phase> <status>` instead of hand-editing either location.
+- Treat `<details>...</details>` sections as archived roadmap history only; lifecycle helpers ignore phases inside those blocks.
+
+## Coverage Verification
+
+After creating the roadmap, verify:
+```
+For each v1 requirement in .planning/SPEC.md:
+  [ ] Requirement appears in exactly one phase's "Requirements" list
+  [ ] The phase's success criteria would prove the requirement is met
+```
+
+If a requirement doesn't map to any phase: add a phase or expand an existing one.
+If a requirement maps to multiple phases: clarify which phase owns it.
+