feat(gsd-tools): frontmatter CRUD, verification suite, template fill, state progression (#485)

* feat(gsd-tools): add frontmatter CRUD, verification suite, template fill, and state progression

Four new command groups that delegate deterministic operations from AI agents to code:

- frontmatter get/set/merge/validate: Safe YAML frontmatter manipulation with schema validation
- verify plan-structure/phase-completeness/references/commits/artifacts/key-links: Structural checks agents previously burned context on
- template fill summary/plan/verification: Pre-filled document skeletons so agents only fill creative content
- state advance-plan/record-metric/update-progress/add-decision/add-blocker/resolve-blocker/record-session: Automate arithmetic and formatting in STATE.md

Adds reconstructFrontmatter() + spliceFrontmatter() helpers for safe frontmatter roundtripping,
and parseMustHavesBlock() for 3-level YAML parsing of must_haves structures.

20 new functions, ~1037 new lines.

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

* feat: wire gsd-tools commands into agents and workflows

- gsd-verifier: use `verify artifacts` and `verify key-links` instead of
  manual grep patterns for stub detection and wiring verification
- gsd-executor: use `state advance-plan`, `state update-progress`,
  `state record-metric`, `state add-decision`, `state record-session`
  instead of manual STATE.md manipulation
- gsd-plan-checker: use `verify plan-structure` and `frontmatter get`
  for structural validation and must_haves extraction
- gsd-planner: add validation step using `frontmatter validate` and
  `verify plan-structure` after writing PLAN.md
- execute-plan.md: use gsd-tools state commands for position/progress updates
- verify-phase.md: use gsd-tools for must_haves extraction and artifact/link verification

This makes the gsd-tools commands from PR #485 actually used by the system.

---------

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

agents/gsd-executor.md

@@ -323,22 +323,44 @@ Do NOT skip. Do NOT proceed to state updates if self-check fails.
 </self_check>
 
 <state_updates>
-After SUMMARY.md, update STATE.md:
+After SUMMARY.md, update STATE.md using gsd-tools:
 
-**Current Position:**
-```markdown
-Phase: [current] of [total] ([phase name])
-Plan: [just completed] of [total in phase]
-Status: [In progress / Phase complete]
-Last activity: [today] - Completed {phase}-{plan}-PLAN.md
-Progress: [progress bar]
+```bash
+# Advance plan counter (handles edge cases automatically)
+node ~/.claude/get-shit-done/bin/gsd-tools.js state advance-plan
+
+# Recalculate progress bar from disk state
+node ~/.claude/get-shit-done/bin/gsd-tools.js state update-progress
+
+# Record execution metrics
+node ~/.claude/get-shit-done/bin/gsd-tools.js state record-metric \
+  --phase "${PHASE}" --plan "${PLAN}" --duration "${DURATION}" \
+  --tasks "${TASK_COUNT}" --files "${FILE_COUNT}"
+
+# Add decisions (extract from SUMMARY.md key-decisions)
+for decision in "${DECISIONS[@]}"; do
+  node ~/.claude/get-shit-done/bin/gsd-tools.js state add-decision \
+    --phase "${PHASE}" --summary "${decision}"
+done
+
+# Update session info
+node ~/.claude/get-shit-done/bin/gsd-tools.js state record-session \
+  --stopped-at "Completed ${PHASE}-${PLAN}-PLAN.md"
 ```
 
-**Progress bar:** Count total plans, count completed (SUMMARY.md files), render █ for complete, ░ for incomplete.
+**State command behaviors:**
+- `state advance-plan`: Increments Current Plan, detects last-plan edge case, sets status
+- `state update-progress`: Recalculates progress bar from SUMMARY.md counts on disk
+- `state record-metric`: Appends to Performance Metrics table
+- `state add-decision`: Adds to Decisions section, removes placeholders
+- `state record-session`: Updates Last session timestamp and Stopped At fields
 
-**Extract from SUMMARY.md:** Decisions → add to STATE.md Decisions table. Next Phase Readiness blockers → add to STATE.md.
+**Extract decisions from SUMMARY.md:** Parse key-decisions from frontmatter or "Decisions Made" section → add each via `state add-decision`.
 
-**Session Continuity:** Last session date, stopped at, resume file path.
+**For blockers found during execution:**
+```bash
+node ~/.claude/get-shit-done/bin/gsd-tools.js state add-blocker "Blocker description"
+```
 </state_updates>
 
 <final_commit>