gsd-remix 1.0.0

package/get-shit-done/workflows/graduation.md

@@ -0,0 +1,195 @@
+# graduation.md — LEARNINGS.md Cross-Phase Graduation Helper
+
+**Invoked by:** `transition.md` step `graduation_scan`. Never invoked directly by users.
+
+This workflow clusters recurring items across the last N phases' LEARNINGS.md files and surfaces promotion candidates to the developer via HITL. No item is promoted without explicit developer approval.
+
+---
+
+## Configuration
+
+Read from project config (`config.json`):
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `features.graduation` | `true` | Master on/off switch. `false` skips silently. |
+| `features.graduation_window` | `5` | How many prior phases to scan |
+| `features.graduation_threshold` | `3` | Minimum cluster size to surface |
+
+---
+
+## Step 1: Guard Checks
+
+```bash
+GRADUATION_ENABLED=$(gsd-remix-sdk query config-get features.graduation 2>/dev/null || echo "true")
+GRADUATION_WINDOW=$(gsd-remix-sdk query config-get features.graduation_window 2>/dev/null || echo "5")
+GRADUATION_THRESHOLD=$(gsd-remix-sdk query config-get features.graduation_threshold 2>/dev/null || echo "3")
+```
+
+**Skip silently (print nothing) if:**
+- `features.graduation` is `false`
+- Fewer than `graduation_threshold` completed prior phases exist (not enough data)
+
+**Skip silently (print nothing) if total items across all LEARNINGS.md files in the window is fewer than 5.**
+
+---
+
+## Step 2: Collect LEARNINGS.md Files
+
+Find LEARNINGS.md files from the last N completed phases (excluding the phase currently completing):
+
+```bash
+find .planning/phases -name "*-LEARNINGS.md" | sort | tail -n "$GRADUATION_WINDOW"
+```
+
+For each file found:
+1. Parse the four category sections: `## Decisions`, `## Lessons`, `## Patterns`, `## Surprises`
+2. Extract each `### Item Title` + body as a single item record: `{ category, title, body, source_phase, source_file }`
+3. **Skip items that already contain `**Graduated:**`** — they have been promoted and must not re-surface
+
+---
+
+## Step 3: Cluster by Lexical Similarity
+
+For each category independently, cluster items using Jaccard similarity on tokenized title+body:
+
+**Tokenization:** lowercase, strip punctuation, split on whitespace, remove stop words (a, an, the, is, was, in, on, at, to, for, of, and, or, but, with, from, that, this, by, as).
+
+**Jaccard similarity:** `|A ∩ B| / |A ∪ B|` where A and B are token sets. Two items are in the same cluster if similarity ≥ 0.25.
+
+**Clustering algorithm:** single-pass greedy — process items in phase order; add to the first cluster whose centroid (union of all cluster tokens) has similarity ≥ 0.25 with the new item; otherwise start a new cluster.
+
+**Cluster size filter:** only surface clusters with distinct source phases ≥ `graduation_threshold` (not just total items — same item repeated in one phase still counts as 1 distinct phase).
+
+---
+
+## Step 4: Check graduation_backlog in STATE.md
+
+Read `.planning/STATE.md` `graduation_backlog` section (if present). Format:
+
+```yaml
+graduation_backlog:
+  - cluster_id: "{sha256-of-cluster-title}"
+    status: "dismissed"   # or "deferred"
+    deferred_until: "phase-N"  # only for deferred entries
+    cluster_title: "{representative title}"
+```
+
+**Skip any cluster whose `cluster_id` matches a `dismissed` entry.**
+
+**Skip any cluster whose `cluster_id` matches a `deferred` entry where `deferred_until` phase has not yet completed.**
+
+---
+
+## Step 5: Surface Promotion Candidates
+
+For each qualifying cluster, determine the suggested target file:
+
+| Category | Suggested Target |
+|----------|-----------------|
+| `decisions` | `PROJECT.md` — append under `## Validated Decisions` (create section if absent) |
+| `patterns` | `PATTERNS.md` — append under the appropriate category section (create file if absent) |
+| `lessons` | `PROJECT.md` — append under `## Invariants` (create section if absent) |
+| `surprises` | Flag for human review — if genuinely surprising 3+ times, something structural is wrong |
+
+Print the graduation report:
+
+```text
+📚 Graduation scan across phases {M}–{N}:
+
+  HIGH RECURRENCE ({K}/{WINDOW} phases)
+  ├─ Cluster: "{representative title}"
+  ├─ Category: {category}
+  ├─ Sources: {list of NN-LEARNINGS filenames}
+  └─ Suggested target: {target file} § {section}
+
+  [repeat for each qualifying cluster, ordered HIGH→LOW recurrence]
+
+For each cluster above, choose an action:
+  P = Promote now   D = Defer (re-surface next transition)   X = Dismiss (never re-surface)   A = Defer all remaining
+```
+
+---
+
+## Step 6: HITL — Process Each Cluster
+
+For each cluster (in order from Step 5), ask the developer:
+
+```text
+Cluster: "{title}" [{category}, {K} phases] → {target}
+Action [P/D/X/A]:
+```
+
+Use `AskUserQuestion` (or equivalent HITL primitive for the current runtime). If `TEXT_MODE` is true, display the cluster question as plain text and accept typed input. Accept single-character input: `P`, `D`, `X`, `A` (case-insensitive).
+
+**On `P` (Promote now):**
+
+1. Read the target file (or create it with a standard header if absent)
+2. Append the cluster entry under the suggested section:
+   ```markdown
+   ### {Cluster representative title}
+   {Merged body — combine unique sentences across cluster items}
+
+   **Sources:** Phase {A}, Phase {B}, Phase {C}
+   **Promoted:** {ISO_DATE}
+   ```
+3. For each source LEARNINGS.md item in the cluster, append `**Graduated:** {target-file}:{ISO_DATE}` after its last existing field
+4. Commit both the target file and all annotated LEARNINGS.md files in a single atomic commit:
+   `docs(learnings): graduate "{cluster title}" to {target-file}`
+
+**On `D` (Defer):**
+
+Write to `.planning/STATE.md` under `graduation_backlog`:
+```yaml
+- cluster_id: "{sha256}"
+  status: "deferred"
+  deferred_until: "phase-{NEXT_PHASE_NUMBER}"
+  cluster_title: "{title}"
+```
+
+**On `X` (Dismiss):**
+
+Write to `.planning/STATE.md` under `graduation_backlog`:
+```yaml
+- cluster_id: "{sha256}"
+  status: "dismissed"
+  cluster_title: "{title}"
+```
+
+**On `A` (Defer all):**
+
+Defer the current cluster (same as `D`) and skip all remaining clusters for this run, deferring each to the next transition. Print:
+```text
+[graduation: deferred all remaining clusters to next transition]
+```
+Then proceed directly to Step 7.
+
+---
+
+## Step 7: Completion Report
+
+After processing all clusters, print:
+
+```text
+Graduation complete: {promoted} promoted, {deferred} deferred, {dismissed} dismissed.
+```
+
+If no clusters qualified (all filtered by backlog or threshold), print:
+```text
+[graduation: no qualifying clusters in phases {M}–{N}]
+```
+
+---
+
+## First-Run Behaviour
+
+On the first transition after upgrading to a version that includes this workflow, all extant LEARNINGS.md files may produce a large batch of candidates at once. A `[Defer all]` shorthand is available: if the developer enters `A` at any cluster prompt, all remaining clusters for this run are deferred to the next transition.
+
+---
+
+## No-Op Conditions (silent skip)
+
+- `features.graduation = false`
+- Fewer than `graduation_threshold` prior phases with LEARNINGS.md
+- Total items < 5 across the window
+- All qualifying clusters are in `graduation_backlog` as dismissed

package/get-shit-done/workflows/health.md

@@ -0,0 +1,314 @@
+<purpose>
+Validate `.planning/` directory integrity or runtime install health and report actionable issues. Checks for missing files, invalid configurations, inconsistent state, orphaned plans, unsupported runtime versions, and SDK availability. Optionally repairs auto-fixable planning issues or rebuilds the bundled SDK.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="parse_args">
+**Parse arguments:**
+
+Check if `--runtime`, `--repair`, or `--backfill` flags are present in the command arguments.
+
+```
+RUNTIME_FLAG=""
+REPAIR_FLAG=""
+BACKFILL_FLAG=""
+if arguments contain "--runtime"; then
+  RUNTIME_FLAG="--runtime"
+fi
+if arguments contain "--repair"; then
+  REPAIR_FLAG="--repair"
+fi
+if arguments contain "--backfill"; then
+  BACKFILL_FLAG="--backfill"
+fi
+```
+
+**Runtime SDK repair script path:**
+
+The installer rewrites this path for non-Claude runtimes and local installs.
+
+```bash
+RUNTIME_REPAIR_SCRIPT="$HOME/.claude/get-shit-done/bin/repair-sdk.cjs"
+```
+
+**If runtime repair is requested, repair before any SDK query:**
+
+```bash
+if [[ -n "$RUNTIME_FLAG" && -n "$REPAIR_FLAG" ]]; then
+  if [[ ! -f "$RUNTIME_REPAIR_SCRIPT" ]]; then
+    echo "✗ Runtime repair script not found:"
+    echo "  $RUNTIME_REPAIR_SCRIPT"
+    echo ""
+    echo "Re-run the gsd-remix installer to refresh runtime assets:"
+    echo "  npx gsd-remix@latest"
+    exit 1
+  fi
+
+  echo "Running GSD Remix SDK repair..."
+  node "$RUNTIME_REPAIR_SCRIPT"
+  REPAIR_STATUS=$?
+  if [[ "$REPAIR_STATUS" -ne 0 ]]; then
+    echo ""
+    echo "✗ GSD Remix SDK repair failed with exit $REPAIR_STATUS."
+    exit "$REPAIR_STATUS"
+  fi
+fi
+```
+
+**Guard `gsd-remix-sdk` before any query:**
+
+```bash
+if ! command -v gsd-remix-sdk &>/dev/null; then
+  echo "⚠ gsd-remix-sdk not found in PATH — /gsd-health requires it."
+  echo ""
+  echo "Repair the bundled SDK without reinstalling all runtime assets:"
+  echo "  /gsd-health --runtime --repair"
+  exit 1
+fi
+```
+
+**Runtime mode constraints:**
+
+If `RUNTIME_FLAG` is set, ignore `BACKFILL_FLAG` for this run. Runtime checks are read-only unless `REPAIR_FLAG` is also set. Runtime repair only rebuilds and reinstalls the bundled SDK from `get-shit-done/sdk/`; it does not reinstall commands, agents, hooks, or project artifacts.
+</step>
+
+<step name="run_health_check">
+**Run health validation:**
+
+**If `RUNTIME_FLAG` is set:**
+
+```bash
+HEALTH=$(gsd-remix-sdk query runtime.health 2>/dev/null || echo '{"passed":false,"blockers":[{"code":"runtime_health_unavailable","message":"Installed gsd-remix-sdk does not expose runtime.health.","fix":"Run /gsd-health --runtime --repair to rebuild the bundled SDK."}],"warnings":[],"checks":[]}')
+```
+
+Parse JSON output:
+- `passed`: boolean
+- `node_version`: Current Node version
+- `required_node_range`: Required Node range from package metadata
+- `runtime_identity`: Installed runtime identity marker (`distribution`, `package_name`, `version`, `runtime`, `install_scope`, `identity_path`) or null
+- `runtime_identity_path`: Expected identity marker path
+- `gsd_tools_source`: `bundled` | `project` | `user` | `custom` | `missing`
+- `gsd_tools_path`: Resolved `gsd-tools.cjs` path if found
+- `legacy_bridge_available`: boolean
+- `blockers[]`: Critical runtime issues
+- `warnings[]`: Non-blocking runtime issues
+- `checks[]`: Full deterministic runtime check results
+
+**If `RUNTIME_FLAG` is NOT set:** Run planning health validation:
+
+```bash
+HEALTH=$(gsd-remix-sdk query validate.health $REPAIR_FLAG $BACKFILL_FLAG)
+```
+
+Parse JSON output:
+- `status`: "healthy" | "degraded" | "broken"
+- `errors[]`: Critical issues (code, message, fix, repairable)
+- `warnings[]`: Non-critical issues
+- `info[]`: Informational notes
+- `repairable_count`: Number of auto-fixable issues
+- `repairs_performed[]`: Actions taken if --repair was used
+</step>
+
+<step name="format_output">
+**Format and display results:**
+
+**If `RUNTIME_FLAG` is set:**
+
+Determine status:
+- `BROKEN` when `blockers[]` is non-empty
+- `DEGRADED` when `blockers[]` is empty and `warnings[]` is non-empty
+- `HEALTHY` otherwise
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD Runtime Health Check
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Status: HEALTHY | DEGRADED | BROKEN
+Distribution: {runtime_identity.display_name or runtime_identity.distribution or "unknown"} {runtime_identity.version or ""}
+Package: {runtime_identity.package_name or "unknown"} ({runtime_identity.runtime or "unknown"} / {runtime_identity.install_scope or "unknown"})
+Node: {node_version} (required: {required_node_range or "unknown"})
+Legacy bridge: READY | DEGRADED | MISSING
+Source: {gsd_tools_source}
+Path: {gsd_tools_path or "not found"}
+Identity: {runtime_identity.identity_path or runtime_identity_path or "not found"}
+Warnings: N
+```
+
+**If blockers exist:**
+```
+## Blockers
+
+- [node_version_unsupported] Current Node v20.11.1 does not satisfy >=22.0.0
+  Fix: Use Node >=22.0.0 or newer, then rerun the workflow.
+```
+
+**If warnings exist:**
+```
+## Warnings
+
+- [legacy_bridge_missing] No gsd-tools.cjs bridge could be found for CJS fallback commands.
+  Fix: Run /gsd-update to restore the bundled bridge. Use /gsd-health --runtime --repair only for SDK CLI repair.
+```
+
+**Footer:**
+```
+---
+Runtime mode is read-only unless --repair is set. Use /gsd-health --runtime --repair to rebuild the bundled SDK, or /gsd-update to refresh all runtime assets.
+```
+
+Then STOP. Do not proceed to repair prompts.
+
+**If `RUNTIME_FLAG` is NOT set:** Use the existing planning health output:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD Health Check
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Status: HEALTHY | DEGRADED | BROKEN
+Errors: N | Warnings: N | Info: N
+```
+
+**If repairs were performed:**
+```
+## Repairs Performed
+
+- ✓ config.json: Created with defaults
+- ✓ STATE.md: Regenerated from roadmap
+```
+
+**If errors exist:**
+```
+## Errors
+
+- [E001] config.json: JSON parse error at line 5
+  Fix: Run /gsd-health --repair to reset to defaults
+
+- [E002] PROJECT.md not found
+  Fix: Run /gsd-new-project to create
+```
+
+**If warnings exist:**
+```
+## Warnings
+
+- [W002] STATE.md references phase 5, but only phases 1-3 exist
+  Fix: Review STATE.md manually before changing it; repair will not overwrite an existing STATE.md
+
+- [W005] Phase directory "1-setup" doesn't follow NN-name format
+  Fix: Rename to match pattern (e.g., 01-setup)
+```
+
+**If info exists:**
+```
+## Info
+
+- [I001] 02-implementation/02-01-PLAN.md has no SUMMARY.md
+  Note: May be in progress
+```
+
+**Footer (if repairable issues exist and --repair was NOT used):**
+```
+---
+N issues can be auto-repaired. Run: /gsd-health --repair
+```
+</step>
+
+<step name="offer_repair">
+**Skip if:** `RUNTIME_FLAG` is set.
+
+**If repairable issues exist and --repair was NOT used:**
+
+Ask user if they want to run repairs:
+
+```
+Would you like to run /gsd-health --repair to fix N issues automatically?
+```
+
+If yes, re-run with --repair flag and display results.
+</step>
+
+<step name="verify_repairs">
+**Skip if:** `RUNTIME_FLAG` is set.
+
+**If repairs were performed:**
+
+Re-run health check without --repair to confirm issues are resolved:
+
+```bash
+gsd-remix-sdk query validate.health
+```
+
+Report final status.
+</step>
+
+</process>
+
+<error_codes>
+
+| Code | Severity | Description | Repairable |
+|------|----------|-------------|------------|
+| E001 | error | .planning/ directory not found | No |
+| E002 | error | PROJECT.md not found | No |
+| E003 | error | ROADMAP.md not found | No |
+| E004 | error | STATE.md not found | Yes |
+| E005 | error | config.json parse error | Yes |
+| W001 | warning | PROJECT.md missing required section | No |
+| W002 | warning | STATE.md references invalid phase | No |
+| W003 | warning | config.json not found | Yes |
+| W004 | warning | config.json invalid field value | No |
+| W005 | warning | Phase directory naming mismatch | No |
+| W006 | warning | Phase in ROADMAP but no directory | No |
+| W007 | warning | Phase on disk but not in ROADMAP | No |
+| W008 | warning | config.json: workflow.nyquist_validation absent (defaults to enabled but agents may skip) | Yes |
+| W009 | warning | Phase has Validation Architecture in RESEARCH.md but no VALIDATION.md | No |
+| W018 | warning | MILESTONES.md missing entry for archived milestone snapshot | Yes (`--backfill`) |
+| W019 | warning | Unrecognized .planning/ root file — not a canonical GSD artifact | No |
+| I001 | info | Plan without SUMMARY (may be in progress) | No |
+
+</error_codes>
+
+<repair_actions>
+
+| Action | Effect | Risk |
+|--------|--------|------|
+| createConfig | Create config.json with defaults | None |
+| resetConfig | Delete + recreate config.json | Loses custom settings |
+| regenerateState | Create STATE.md from ROADMAP structure when it is missing | Loses session history |
+| addNyquistKey | Add workflow.nyquist_validation: true to config.json | None — matches existing default |
+| backfillMilestones | Synthesize missing MILESTONES.md entries from `.planning/milestones/vX.Y-ROADMAP.md` snapshots | None — additive only; triggered by `--backfill` flag |
+
+**Not repairable (too risky):**
+- PROJECT.md, ROADMAP.md content
+- Phase directory renaming
+- Orphaned plan cleanup
+
+</repair_actions>
+
+<stale_task_cleanup>
+**Windows-specific:** Check for stale Claude Code task directories that accumulate on crash/freeze.
+These are left behind when subagents are force-killed and consume disk space.
+
+When `--repair` is active, detect and clean up:
+
+```bash
+# Check for stale task directories (older than 24 hours)
+TASKS_DIR="$HOME/.claude/tasks"
+if [ -d "$TASKS_DIR" ]; then
+  STALE_COUNT=$( (find "$TASKS_DIR" -maxdepth 1 -type d -mtime +1 2>/dev/null || true) | wc -l )
+  if [ "$STALE_COUNT" -gt 0 ]; then
+    echo "⚠️  Found $STALE_COUNT stale task directories in ~/.claude/tasks/"
+    echo "   These are leftover from crashed subagent sessions."
+    echo "   Run: rm -rf ~/.claude/tasks/*  (safe — only affects dead sessions)"
+  fi
+fi
+```
+
+Report as info diagnostic: `I002 | info | Stale subagent task directories found | Yes (--repair removes them)`
+</stale_task_cleanup>