feat: extract repetitive bash patterns into gsd-tools commands (#472)

* feat(gsd-tools): add history-digest, atomic state operations, and summary variants

Adds new performance-focused commands to gsd-tools and introduces specialized
summary templates to reduce context tax:

- history-digest: Compiles phase summaries into structured JSON for JIT loading
- state get/patch: Enables atomic STATE.md operations instead of full rewrites
- template select: Automatically chooses optimal summary template based on plan complexity
- Adds minimal, standard, and complex summary templates

Part of the "Hydra" architecture for GSD context optimization.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* chore: add project config

* docs: define v1 requirements

* docs: create roadmap (6 phases)

* feat(history-digest): fix nested YAML parsing and add tests

- Fix extractFrontmatter() to handle nested YAML structures like
  dependency-graph.provides, tech-stack.added using stack-based parsing
- Add test infrastructure with Node test runner (npm test)
- Update gsd-planner to use digest fields directly instead of reading
  full SUMMARY.md files
- Add 6 schema validation tests covering nested fields, merging,
  malformed files, and backward compatibility

Closes: HIST-01, HIST-02, HIST-03, HIST-04

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(planner): use digest for selection, full SUMMARY for understanding

The previous commit went too far by eliminating full SUMMARY reads.
The digest is an index for smart selection, not a replacement for
understanding what actually happened.

Two-step approach:
1. Digest to score/select relevant phases (2-4 typically)
2. Full SUMMARY read for selected phases (implementation details)
3. Digest-level context retained for unselected phases

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat(gsd-tools): add phases, roadmap, and phase commands

TDD implementation of three new commands to replace repetitive bash:

phases list [--type plans|summaries] [--phase N]
- Lists phase directories sorted numerically (handles decimals)
- Filter by file type or specific phase
- Replaces: ls -d .planning/phases/*/ | sort -V (22 occurrences)

roadmap get-phase <N>
- Extracts phase section from ROADMAP.md
- Returns name, goal, full section content
- Replaces: grep -A20 "Phase X:" ROADMAP.md (19 occurrences)

phase next-decimal <N>
- Calculates next decimal phase (06 → 06.1, 06.2 → 06.3)
- Handles gaps, normalizes input
- Replaces: complex bash math in insert-phase (3 occurrences)

16 new tests, all passing.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* refactor: migrate agents/workflows to use gsd-tools commands

Replace inline bash patterns with centralized gsd-tools commands:

phases list:
- audit-milestone.md: ls -d .planning/phases/*/ | sort -V
- plan-milestone-gaps.md: ls -d ... | sort -V | tail -1

roadmap get-phase:
- plan-phase.md: grep -A5 "Phase X:" ROADMAP.md (2 occurrences)
- research-phase.md: grep patterns (2 occurrences)
- verify-phase.md: grep -A5 pattern
- gsd-verifier.md: grep -A5 pattern
- gsd-plan-checker.md: grep -A10 pattern
- commands/gsd/research-phase.md: grep patterns (2 occurrences)

phase next-decimal:
- insert-phase.md: complex bash decimal calculation
- decimal-phase-calculation.md: reference doc rewritten

phase-argument-parsing.md: updated to reference gsd-tools

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

agents/gsd-plan-checker.md

@@ -308,7 +308,7 @@ Orchestrator provides CONTEXT.md content in the verification prompt. If provided
 
 ```bash
 ls "$phase_dir"/*-PLAN.md 2>/dev/null
-grep -A 10 "Phase $phase_number" .planning/ROADMAP.md | head -15
+node ~/.claude/get-shit-done/bin/gsd-tools.js roadmap get-phase "$phase_number"
 ls "$phase_dir"/*-BRIEF.md 2>/dev/null
 ```
 

agents/gsd-planner.md

@@ -885,26 +885,40 @@ Apply discovery level protocol (see discovery_levels section).
 </step>
 
 <step name="read_project_history">
-**Intelligent context assembly from frontmatter dependency graph:**
+**Two-step context assembly: digest for selection, full read for understanding.**
 
-1. Scan all summary frontmatter:
+**Step 1 — Generate digest index:**
 ```bash
-for f in .planning/phases/*/*-SUMMARY.md; do
-  sed -n '1,/^---$/p; /^---$/q' "$f" | head -30
-done
+node ~/.claude/get-shit-done/bin/gsd-tools.js history-digest
 ```
 
-2. Build dependency graph for current phase:
-- `affects` field: Which prior phases affect current?
-- `subsystem`: Which prior phases share same subsystem?
-- `requires` chains: Transitive dependencies
-- Roadmap: Any phases marked as dependencies?
+**Step 2 — Select relevant phases (typically 2-4):**
 
-3. Select relevant summaries (typically 2-4 prior phases)
+Score each phase by relevance to current work:
+- `affects` overlap: Does it touch same subsystems?
+- `provides` dependency: Does current phase need what it created?
+- `patterns`: Are its patterns applicable?
+- Roadmap: Marked as explicit dependency?
 
-4. Extract from frontmatter: tech available, patterns established, key files, decisions.
+Select top 2-4 phases. Skip phases with no relevance signal.
 
-5. Read FULL summaries only for selected relevant phases.
+**Step 3 — Read full SUMMARYs for selected phases:**
+```bash
+cat .planning/phases/{selected-phase}/*-SUMMARY.md
+```
+
+From full SUMMARYs extract:
+- How things were implemented (file patterns, code structure)
+- Why decisions were made (context, tradeoffs)
+- What problems were solved (avoid repeating)
+- Actual artifacts created (realistic expectations)
+
+**Step 4 — Keep digest-level context for unselected phases:**
+
+For phases not selected, retain from digest:
+- `tech_stack`: Available libraries
+- `decisions`: Constraints on approach
+- `patterns`: Conventions to follow
 
 **From STATE.md:** Decisions → constrain approach. Pending todos → candidates.
 </step>

agents/gsd-verifier.md

@@ -54,7 +54,7 @@ Set `is_re_verification = false`, proceed with Step 1.
 ```bash
 ls "$PHASE_DIR"/*-PLAN.md 2>/dev/null
 ls "$PHASE_DIR"/*-SUMMARY.md 2>/dev/null
-grep -A 5 "Phase $PHASE_NUM" .planning/ROADMAP.md
+node ~/.claude/get-shit-done/bin/gsd-tools.js roadmap get-phase "$PHASE_NUM"
 grep -E "^| $PHASE_NUM" .planning/REQUIREMENTS.md 2>/dev/null
 ```