@opengsd/gsd-core 1.2.0-rc.1

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

@@ -0,0 +1,196 @@
+# 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
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/get-shit-done/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
+GRADUATION_ENABLED=$(gsd_run query config-get features.graduation 2>/dev/null || echo "true")
+GRADUATION_WINDOW=$(gsd_run query config-get features.graduation_window 2>/dev/null || echo "5")
+GRADUATION_THRESHOLD=$(gsd_run 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,224 @@
+<purpose>
+Validate `.planning/` directory integrity and report actionable issues. Checks for missing files, invalid configurations, inconsistent state, and orphaned plans. Optionally repairs auto-fixable issues.
+</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 `--repair`, `--backfill`, or `--context` flags are present in the command arguments.
+
+```
+REPAIR_FLAG=""
+BACKFILL_FLAG=""
+CONTEXT_MODE=""
+if arguments contain "--repair"; then
+  REPAIR_FLAG="--repair"
+fi
+if arguments contain "--backfill"; then
+  BACKFILL_FLAG="--backfill"
+fi
+if arguments contain "--context"; then
+  CONTEXT_MODE="true"
+fi
+```
+
+If `CONTEXT_MODE` is set, jump to the `context_check` step and skip the
+integrity validation steps. The two modes are orthogonal — context utilization
+has nothing to do with `.planning/` directory health.
+</step>
+
+<step name="context_check">
+**Run only when `--context` is set.**
+
+The model running this workflow self-reports the current session's
+approximate `tokensUsed` and the active model's `contextWindow`. Use the values
+visible in your runtime (Claude Code's `/context` slash command output, or the
+model's own session telemetry). If the runtime exposes neither, prompt the user
+once via AskUserQuestion for both numbers.
+
+**TEXT_MODE fallback:** when `text_mode` is true (config or `--text` flag) the
+runtime is non-Claude (Codex, Gemini, etc.) and `AskUserQuestion` is not
+available — replace the prompt with a plain-text two-question sequence
+("Approximate tokens used? Context window size?") and read the answers as
+plain text from the user's response.
+
+```bash
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/get-shit-done/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
+gsd_run query validate.context \
+  --tokens-used "$TOKENS_USED" \
+  --context-window "$CONTEXT_WINDOW"
+```
+
+The query prints a one-line status (`Context utilization: NN% (state)`) plus
+a recommendation line for the warning and critical states. Print the SDK
+output verbatim and end the workflow — do **not** mix in `.planning/`
+health output, the two modes are independent diagnostics.
+</step>
+
+<step name="run_health_check">
+**Run health validation:**
+
+```bash
+gsd_run 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:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ 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">
+**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">
+**If repairs were performed:**
+
+Re-run health check without --repair to confirm issues are resolved:
+
+```bash
+gsd_run 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>

package/get-shit-done/workflows/help/modes/brief.md

@@ -0,0 +1,22 @@
+<purpose>
+One-liner refresher for returning users. Output ONLY the `<reference>` content below. No additions.
+</purpose>
+
+<reference>
+**GSD — top commands**
+
+```text
+/gsd:new-project           Initialize a project (greenfield)
+/gsd:map-codebase          Map an existing codebase (brownfield)
+/gsd:plan-phase <N>        Create a phase plan
+/gsd:execute-phase <N>     Execute a phase
+/gsd:progress              Where am I, what's next
+/gsd:quick                 Small ad-hoc task with GSD guarantees
+/gsd:fast "<task>"         Trivial inline task — no subagents
+/gsd:debug "<symptom>"     Persistent debug session (survives /clear)
+/gsd:capture               Save an idea / todo / note
+/gsd:ship <N>              Open a PR from a completed phase
+```
+
+More: `/gsd:help` (default tour) · `/gsd:help --full` (everything) · `/gsd:help <topic>` (one section)
+</reference>

package/get-shit-done/workflows/help/modes/default.md

@@ -0,0 +1,50 @@
+<purpose>
+One-page newcomer-oriented tour of GSD. Output ONLY the `<reference>` content below. No additions.
+</purpose>
+
+<reference>
+# GSD — Get Shit Done
+
+Plan-driven development for solo agentic work with Claude Code. GSD turns a vague idea into a hierarchical plan, then executes it phase by phase with state tracking and atomic commits.
+
+## Start here (3 commands)
+
+```text
+/gsd:new-project        # Greenfield: questioning → research → requirements → roadmap
+/gsd:plan-phase 1       # Create a detailed plan for phase 1
+/gsd:execute-phase 1    # Execute all plans in the phase
+```
+
+Existing codebase? Run `/gsd:map-codebase` first to ground GSD in your code.
+
+## Common commands
+
+| Command | Purpose |
+|---|---|
+| `/gsd:progress` | Where am I, what's next — also routes freeform intent with `--do "..."` |
+| `/gsd:quick` | Small ad-hoc task with GSD guarantees (planning dir + atomic commit) |
+| `/gsd:fast "<task>"` | Trivial inline change — no subagents, ≤3 file edits |
+| `/gsd:discuss-phase <N>` | Capture vision and decisions before planning |
+| `/gsd:debug "<symptom>"` | Persistent debug session, survives `/clear` |
+| `/gsd:capture` | Save an idea, todo, note, seed, or backlog item |
+| `/gsd:verify-work <N>` | Conversational UAT for a completed phase |
+| `/gsd:ship <N>` | Open a PR from a completed phase |
+| `/gsd:help --full` | Complete reference (every command, every flag) |
+
+## Want more?
+
+```text
+/gsd:help --brief         # 10-line refresher of top commands
+/gsd:help --full          # complete reference
+/gsd:help <topic>         # one section only — see topics below
+/gsd:help --brief <topic> # compact scoped lookup — signature + one-line summary
+```
+
+Topics: `workflow` · `planning` · `execute` · `quick` · `debug` · `capture` · `ship` · `config` · `milestones` · `spike` · `sketch` · `review` · `audit` · `progress`
+
+## Update GSD
+
+```bash
+npx @opengsd/gsd-core@latest
+```
+</reference>