@opengsd/gsd-core 1.13.0 → 1.14.0

package/gsd-core/workflows/help/modes/full.compact.md

@@ -0,0 +1,398 @@
+Apply response_language to all user-facing prose — narration between tool calls, status updates, progress notes, and findings included; preserve code, paths, and identifiers.
+
+<purpose>
+Display the complete GSD Core command reference. Output ONLY the reference content. Do NOT add project-specific analysis, git status, next-step suggestions, or any commentary beyond the reference.
+</purpose>
+
+<reference>
+# GSD Core Command Reference
+
+**GSD Core** (Git. Ship. Done.) creates hierarchical project plans optimized for solo agentic development with Claude Code.
+
+## Quick Start
+
+1. `/gsd:new-project` — Initialize project (research, requirements, roadmap)
+2. `/gsd:plan-phase 1` — Create detailed plan for first phase
+3. `/gsd:execute-phase 1` — Execute the phase
+
+Not sure where to start? `/gsd:next` reads your project state and routes you to the right next action.
+
+### Smart Entry
+
+**`/gsd:next`** — State-aware front door. Detects your situation via `gsd-tools smart-entry` (no-project, paused, blocked, planning, executing, needs-verify, idle, complete, …) and shows a menu with one recommended action. Launcher only; falls back to `/gsd:progress`.
+
+Usage: `/gsd:next`
+
+## Staying Updated
+
+```bash
+npx @opengsd/gsd-core@latest
+```
+
+## Core Workflow
+
+```text
+/gsd:new-project → /gsd:plan-phase → /gsd:execute-phase → repeat
+```
+
+### Project Initialization
+
+**`/gsd:new-project`** — Unified flow from idea to ready-for-planning: deep questioning, optional domain research (4 parallel researchers), requirements with v1/v2/out-of-scope scoping, roadmap with phase breakdown. Creates `.planning/`: `PROJECT.md`, `config.json`, `research/`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`.
+
+Usage: `/gsd:new-project`
+
+**`/gsd:onboard [--fast] [--text]`** — Guides first-time onboarding for an existing codebase: detects brownfield state, routes through `/gsd:map-codebase` → `/gsd:ingest-docs` → `/gsd:new-project` in safe order, idempotent.
+
+Usage: `/gsd:onboard`
+
+**`/gsd:map-codebase [--fast] [--focus <area>] [--query <term>]`** — Maps an existing codebase with parallel Explore agents into `.planning/codebase/` (stack, architecture, structure, conventions, testing, integrations, concerns). `--fast` for rapid assessment, `--query` to search the intel index.
+
+Usage: `/gsd:map-codebase`
+
+### Phase Planning
+
+**`/gsd:discuss-phase <number> [--chain | --analyze | --power | --assumptions] [--batch[=N]]`** — Articulate your vision for a phase before planning; creates CONTEXT.md. `--chain` chained flow, `--analyze` assumption analysis, `--power` extended questions, `--assumptions` surfaces implementation assumptions non-interactively, `--batch` groups 2-5 questions per turn.
+
+Usage: `/gsd:discuss-phase 2`
+Usage: `/gsd:discuss-phase 2 --batch=3`
+
+**`/gsd:plan-phase <number> [--research] [--skip-research] [--research-phase <N>] [--view] [--gaps] [--skip-verify] [--skip-ui] [--prd <file>] [--ingest <path-or-glob>] [--ingest-format <auto|nygard|madr|narrative>] [--reviews] [--text] [--bounce] [--skip-bounce] [--chunked] [--tdd] [--mvp] [--granularity <coarse|standard|fine>] [--no-tracer] [--no-reversibility-gates]`** — Creates `.planning/phases/XX-phase-name/XX-YY-PLAN.md` with concrete tasks, verification criteria, and success measures (multiple plans per phase supported).
+
+Key flags: `--research-phase <N>` runs research only and writes `RESEARCH.md` then exits (replaces the deleted `gsd-research-phase`; `--research` forces refresh, `--view` prints existing without spawning). `--gaps` closes gaps from a prior plan-check. `--ingest`/`--ingest-format` pre-ingest external ADRs/PRDs/SPECs (see PRD Express Path). `--bounce`/`--skip-bounce` toggle the optional external refinement pass (`workflow.plan_bounce`). `--chunked` splits planning into short, individually-committed passes for crash resilience (`workflow.plan_chunked`), resumable. `--tdd` tests-before-code order. `--mvp` adds user story + Walking Skeleton (see `/gsd:mvp-phase`). `--granularity` overrides resolved plan granularity. `--no-tracer` opts out of tracer-first ordering. `--no-reversibility-gates` suppresses the one-way-door checkpoint for unattended runs.
+
+Usage: `/gsd:plan-phase 1`
+Result: Creates `.planning/phases/01-foundation/01-01-PLAN.md`
+
+**PRD Express Path:** Pass `--prd path/to/requirements.md` to skip discuss-phase — your PRD becomes locked decisions in CONTEXT.md.
+
+### Execution
+
+**`/gsd:execute-phase <phase-number> [--wave N] [--gaps-only] [--tdd]`** — Groups plans by wave (frontmatter), executes sequentially with parallel plans per wave via Task tool, verifies phase goal, updates REQUIREMENTS/ROADMAP/STATE. `--wave N` runs only wave N; `--gaps-only` re-runs verifier-flagged plans; `--tdd` enforces test-driven order.
+
+Usage: `/gsd:execute-phase 5`
+Usage: `/gsd:execute-phase 5 --wave 2`
+
+### Smart Router
+
+**`/gsd:progress --do "<description>"`** — Routes freeform text to the best-matching GSD command; asks you to pick between top matches on ambiguity. Never does the work itself.
+
+Usage: `/gsd:progress --do "fix the login button"`
+
+### Quick Mode
+
+**`/gsd:quick [--full] [--validate] [--discuss] [--research]`** — Small ad-hoc tasks in `.planning/quick/` (updates STATE.md, not ROADMAP.md); spawns planner+executor only by default. `--full` = discuss+research+plan-check+verify; `--validate` = plan-check + post-execution verify; `--discuss`/`--research` add one step each; flags compose.
+
+Usage: `/gsd:quick`
+Result: Creates `.planning/quick/NNN-slug/PLAN.md`, `.planning/quick/NNN-slug/NNN-slug-SUMMARY.md`
+
+---
+
+**`/gsd:quick-batch [--file <path>] [--jobs auto|N] [--validate] [--research] [--resume <batch-id>] [task list]`** — Batches several quick-shaped tasks (inline or `--file`); one coordinator plans/dispatches/merges. `--jobs` caps concurrency, `--resume` dispatches only eligible items; `--discuss`/`--full` are rejected.
+
+Usage: `/gsd:quick-batch --jobs 3 --validate`
+Result: Per-item artifacts under `.planning/quick/`; batch state in `.planning/quick-batches/<batch-id>/BATCH.json`
+
+---
+
+**`/gsd:fast [description]`** — Trivial task inline, no subagent, no planning files: typo fixes, config changes, ≤3 file edits (redirects to `/gsd:quick` above that). Atomic commit, logs to STATE.md.
+
+Usage: `/gsd:fast "fix the typo in README"`
+
+### Roadmap Management
+
+**`/gsd:phase <description>`** — Appends a new phase (next sequential number) to ROADMAP.md.
+
+Usage: `/gsd:phase "Add admin dashboard"`
+
+**`/gsd:phase --insert <after> <description>`** — Inserts a decimal phase (e.g. 7.1) between existing phases for discovered mid-milestone work.
+
+Usage: `/gsd:phase --insert 7 "Fix critical auth bug"`
+Result: Creates Phase 7.1
+
+**`/gsd:phase --remove <number>`** — Deletes a future (unstarted) phase and renumbers subsequent phases; git commit preserves history.
+
+Usage: `/gsd:phase --remove 17`
+Result: Phase 17 deleted, phases 18-20 become 17-19
+
+**`/gsd:phase --edit <number> [--force]`** — Edits title/description/requirements/dependencies in place; `--force` allows editing already-started phases.
+
+### Milestone Management
+
+**`/gsd:new-milestone <name>`** — Mirrors `/gsd:new-project`'s flow for brownfield (existing PROJECT.md): questioning, optional research, requirements, roadmap. `--reset-phase-numbers` restarts at Phase 1 (archives old dirs first); `--ws <name>` scopes to a workstream, skipping the shared PROJECT.md write.
+
+Usage: `/gsd:new-milestone "v2.0 Features"`
+
+**`/gsd:complete-milestone <version>`** — Archives to MILESTONES.md + milestones/ dir, tags the release, preps workspace for next version.
+
+Usage: `/gsd:complete-milestone 1.0.0`
+
+### Progress Tracking
+
+**`/gsd:progress [--next | --forensic | --do "<description>"]`** — Progress bar, SUMMARY recap, current position, key decisions, offers to execute/create next plan, detects 100% completion.
+
+Modes: default (report+routing) · `--next` (auto-advance; `--force` bypasses safety gates) · `--next --auto` (chains steps until milestone completion or a blocking decision) · `--next --converge` (routes planning through `/gsd:plan-review-convergence`, requires `workflow.plan_review_convergence`; reviewer flags and `--max-cycles` forward) · `--forensic` (appends a 6-check integrity audit) · `--do "<text>"` (smart router, see above).
+
+Usage: `/gsd:progress`
+Usage: `/gsd:progress --next --auto`
+
+### Session Management
+
+**`/gsd:resume-work`** — Reads STATE.md, shows position and recent progress, offers next actions.
+
+Usage: `/gsd:resume-work`
+
+**`/gsd:pause-work [--report]`** — Creates a `.continue-here` handoff, updates STATE.md's session-continuity section. `--report` also writes a post-session summary to `.planning/reports/`.
+
+Usage: `/gsd:pause-work`
+
+### Debugging
+
+**`/gsd:debug [issue description] [--diagnose]`** — Adaptive-question symptom gathering, `.planning/debug/[slug].md` tracking, scientific-method investigation, survives `/clear` (resume with no args), archives resolved issues. `--diagnose` runs a one-shot pass without a persistent session.
+
+Usage: `/gsd:debug "login button doesn't work"`
+
+### Spiking & Sketching
+
+**`/gsd:spike [idea] [--quick]`** — Decomposes into 2-5 risk-ordered Given/When/Then experiments, builds minimum code, captures VALIDATED/INVALIDATED/PARTIAL, saves to `.planning/spikes/` with MANIFEST.md. Works in any repo, no `/gsd:new-project` needed. `--quick` skips decomposition.
+
+Usage: `/gsd:spike "can we stream LLM output over WebSockets?"`
+
+**`/gsd:sketch [idea] [--quick]`** — Conversational mood intake, 2-3 tabbed HTML variants per sketch, shared CSS theme system, saves to `.planning/sketches/` with MANIFEST.md. `--quick` skips mood intake.
+
+Usage: `/gsd:sketch "dashboard layout for the admin panel"`
+
+**`/gsd:spike --wrap-up`** — Curates spikes one-at-a-time (include/exclude/partial/UAT), generates a project skill under `./.claude/skills/spike-findings-[project]/`, writes `.planning/spikes/WRAP-UP-SUMMARY.md`, adds a CLAUDE.md auto-load line.
+
+Usage: `/gsd:spike --wrap-up`
+
+**`/gsd:sketch --wrap-up`** — Same curation flow for sketches, generating `./.claude/skills/sketch-findings-[project]/` with design decisions/CSS/HTML structures.
+
+Usage: `/gsd:sketch --wrap-up`
+
+### Capturing Ideas, Notes, and Todos
+
+**`/gsd:capture [description]`** — Extracts context from conversation (or uses the given text), creates a todo in `.planning/todos/pending/`, infers area, checks duplicates, updates STATE.md count.
+
+Usage: `/gsd:capture Add auth token refresh`
+
+**`/gsd:capture --note <text>`** — Zero-friction timestamped note to `.planning/notes/` (or `~/.claude/notes/` globally). Subcommands: append (default), list, promote (note → todo). Works without a project.
+
+Usage: `/gsd:capture --note refactor the hook system`
+Usage: `/gsd:capture --note promote 3`
+
+**`/gsd:capture --list [area]`** — Lists pending todos (optional area filter), loads full context for the one you pick, routes to work-now/add-to-phase/brainstorm, moves it to completed/ on start.
+
+Usage: `/gsd:capture --list api`
+
+**`/gsd:capture --list-seeds [status]`** — Read-only listing of captured seeds (ID, status, scope, trigger, title); optional status filter. Enrich via `/gsd:capture --seed --enrich SEED-NNN`.
+
+Usage: `/gsd:capture --list-seeds dormant`
+
+### User Acceptance Testing
+
+**`/gsd:verify-work [phase]`** — Extracts testable deliverables from SUMMARY.md, presents tests one at a time (yes/no), auto-diagnoses failures into fix plans, ready for re-execution.
+
+Usage: `/gsd:verify-work 3`
+
+### Ship Work
+
+**`/gsd:ship [phase]`** — Pushes branch, opens a PR with a body from SUMMARY/VERIFICATION/REQUIREMENTS, optionally requests review, updates STATE.md. Requires a verified phase and authenticated `gh`.
+
+Usage: `/gsd:ship 4` or `/gsd:ship 4 --draft`
+
+---
+
+**`/gsd:review --phase N [--gemini] [--claude] [--codex] [--coderabbit] [--opencode] [--qwen] [--cursor] [--agy] [--all]`** — Detects available external AI CLIs, each independently reviews the phase's plans with the same structured prompt (CodeRabbit reviews the live diff, up to ~5 min), produces REVIEWS.md with consensus. Feed back via `/gsd:plan-phase N --reviews`.
+
+Usage: `/gsd:review --phase 3 --all`
+
+---
+
+**`/gsd:pr-branch [target]`** — Classifies commits (code-only/planning-only/mixed), cherry-picks code onto a clean branch so reviewers see no `.planning/` artifacts.
+
+Usage: `/gsd:pr-branch` or `/gsd:pr-branch main`
+
+---
+
+**`/gsd:capture --seed [idea]`** — Captures a forward-looking idea with WHY/WHEN-to-surface trigger conditions; auto-surfaces during `/gsd:new-milestone` when triggers match.
+
+Usage: `/gsd:capture --seed "add real-time notifications when we build the events system"`
+
+**`/gsd:capture --backlog [description]`** — Adds an idea to the 999.x backlog without committing to the current milestone; promote later via `/gsd:review-backlog`.
+
+Usage: `/gsd:capture --backlog "real-time notifications when events ship"`
+
+---
+
+**`/gsd:audit-uat`** — Cross-phase audit of all outstanding UAT/verification items (pending, skipped, blocked, human_needed), cross-references the codebase for stale docs, produces a prioritized test plan. Run before a new milestone.
+
+Usage: `/gsd:audit-uat`
+
+### Milestone Auditing
+
+**`/gsd:audit-milestone [version]`** — Reads all phase VERIFICATION.md files, checks requirements coverage, spawns an integration checker for cross-phase wiring, creates MILESTONE-AUDIT.md.
+
+Usage: `/gsd:audit-milestone`
+
+### Configuration
+
+**`/gsd:settings`** — Interactively toggles researcher/plan-checker/verifier agents and the model profile (quality/balanced/budget/inherit); updates `.planning/config.json`.
+
+Usage: `/gsd:settings`
+
+**`/gsd:config [--profile <profile> | --advanced | --integrations]`** — `--profile` quick-switches model profile (`quality` = Opus everywhere but verification, `balanced` = Opus planning/Sonnet execution (default), `budget` = Sonnet writing/Haiku research-verification, `inherit` = current session model). `--advanced` = plan bounce, timeouts, branch templates, cross-AI execution. `--integrations` = third-party API keys, code-review CLI routing, agent-skill injection.
+
+Usage: `/gsd:config --profile budget`
+
+**`/gsd:surface [list|status|profile <name>|disable <cluster>|enable <cluster>|reset]`** — Toggles which skills are surfaced without reinstalling: `list`/`status` show enabled/disabled + token cost, `profile <name>` switches base profile (`core`/`standard`/`full`), `disable`/`enable` a cluster, `reset` returns to install-time profile.
+
+Usage: `/gsd:surface profile standard`
+
+### Utility Commands
+
+**`/gsd:cleanup`** — Dry-run then moves completed-milestone phase dirs from `.planning/phases/` to `.planning/milestones/v{X.Y}-phases/`.
+
+Usage: `/gsd:cleanup`
+
+**`/gsd:help [--brief | --full | <topic> | --brief <topic>]`** — `--brief` = ~10-line refresher; no flag = one-page newcomer tour; `--full` = this complete reference; `<topic>` = matching section only (e.g. `/gsd:help debug`); `--brief <topic>` = compact scoped lookup. Every topic output starts with a `**Topic:** \`<alias>\` → \`<heading>\` *(scope: full | compact)*` preamble. See `gsd-core/workflows/help/modes/topic.md` for the alias table.
+
+Usage: `/gsd:help debug`
+Usage: `/gsd:help --brief debug`
+
+**`/gsd:update [--sync] [--reapply] [--next | --rc]`** — Shows installed-vs-latest, changelog since your version, breaking changes, confirms before installing. `--sync` syncs managed skills across runtime roots; `--reapply` reapplies local modifications post-update; `--next`/`--rc` installs from the `@next` RC dist-tag (ADR #660) instead of `@latest`.
+
+Usage: `/gsd:update`
+
+## Additional Commands
+
+Every command below is also a live `/gsd-*` slash command, grouped by purpose.
+
+### Discovery & Specification
+
+- **`/gsd:explore`** — Socratic ideation and idea routing before committing to plans.
+- **`/gsd:spec-phase <phase> [--auto] [--text]`** — Clarify WHAT a phase delivers with ambiguity scoring; produces SPEC.md before discuss-phase.
+- **`/gsd:ai-integration-phase [phase]`** — Generate an AI-SPEC.md design contract for phases building AI systems.
+- **`/gsd:ui-phase [phase]`** — Generate UI design contract (UI-SPEC.md) for frontend phases.
+- **`/gsd:import --from <filepath> | --from-gsd2`** — Ingest external plans with conflict detection, or reverse-migrate a GSD-2 project to v1 format.
+- **`/gsd:ingest-docs [path] [--mode new|merge] [--manifest <file>] [--resolve auto|interactive]`** — Bootstrap or merge `.planning/` from existing ADRs/PRDs/SPECs/docs.
+
+### Planning & Execution
+
+- **`/gsd:mvp-phase <phase-number>`** — Plans a phase as a vertical MVP slice (user story + SPIDR splitting) before handoff to plan-phase; same end-state as `/gsd:plan-phase --mvp` with a guided intro.
+- **`/gsd:ultraplan-phase [phase]`** — [BETA] Offload plan phase to Claude Code's ultraplan cloud; review in browser, import back.
+- **`/gsd:plan-review-convergence <phase> [--gemini] [--claude] [--codex] [--coderabbit] [--opencode] [--qwen] [--cursor] [--agy/--antigravity] [--ollama] [--lm-studio] [--llama-cpp] [--kimi-code] [--all] [--text] [--ws <name>] [--max-cycles N]`** — Cross-AI convergence loop: replan with review feedback until no HIGH concerns remain (cloud and local-model reviewers).
+- **`/gsd:autonomous [--from N] [--to N] [--only N] [--interactive] [--converge]`** — Runs all remaining phases unattended: discuss → plan → execute per phase; `--converge`/`--cross-ai` routes planning through convergence.
+
+### Quality, Review & Verification
+
+- **`/gsd:code-review <phase> [--depth=quick|standard|deep] [--files file1,file2,...] [--fix [--all] [--auto]]`** — Reviews phase-changed source for bugs, security, quality.
+- **`/gsd:secure-phase [phase]`** — Retroactively verifies threat mitigations for a completed phase.
+- **`/gsd:validate-phase [phase]`** — Retroactively audits and fills Nyquist validation gaps.
+- **`/gsd:ui-review [phase]`** — Retroactive 6-pillar visual audit of implemented frontend code.
+- **`/gsd:eval-review [phase]`** — Audits an executed AI phase's evaluation coverage; produces EVAL-REVIEW.md.
+- **`/gsd:audit-fix --source <audit-uat> [--severity medium|high|all] [--max N] [--dry-run]`** — Autonomous audit-to-fix: find, classify, fix, test, commit.
+- **`/gsd:add-tests <phase> [additional instructions]`** — Generates tests for a completed phase from UAT criteria and implementation.
+
+### Diagnostics & Maintenance
+
+- **`/gsd:health [--repair] [--context]`** — Diagnoses planning-directory health, optionally repairs.
+- **`/gsd:forensics [problem description]`** — Post-mortem investigation for failed GSD workflows.
+- **`/gsd:undo --last N | --phase NN | --plan NN-MM`** — Safe git revert using the phase manifest with dependency checks.
+- **`/gsd:docs-update [--force] [--verify-only]`** — Generates/updates docs verified against the codebase.
+- **`/gsd:extract-learnings <phase>`** — Extracts decisions, lessons, patterns, surprises from phase artifacts.
+
+### Knowledge & Context
+
+- **`/gsd:graphify [build|query <term>|status|diff]`** — Builds/queries/inspects the project knowledge graph in `.planning/graphs/`.
+- **`/gsd:mempalace-recall`** — Recalls prior decisions/patterns/surprises from MemPalace before planning.
+- **`/gsd:mempalace-capture [artifact-type]`** — Files a phase artifact into MemPalace, mirrors decisions into its temporal KG.
+- **`/gsd:thread [list [--open|--resolved] | close <slug> | status <slug> | name | description]`** — Manages persistent context threads across sessions.
+- **`/gsd:profile-user [--questionnaire] [--refresh]`** — Generates a developer behavioral profile + Claude-discoverable artifacts.
+- **`/gsd:stats`** — Project statistics: phases, plans, requirements, git metrics, timeline.
+
+### Workflow & Orchestration
+
+- **`/gsd:manager [--analyze-deps]`** — Interactive command center for multiple phases from one terminal; `--analyze-deps` scans dependency relationships before parallel execution.
+- **`/gsd:workspace [--new | --list | --remove] [name]`** — Creates/lists/removes isolated GSD workspace environments.
+- **`/gsd:workstreams`** — List, create, switch, status, progress, complete, and resume parallel workstreams.
+- **`/gsd:review-backlog`** — Reviews and promotes backlog items to the active milestone.
+- **`/gsd:milestone-summary [version]`** — Comprehensive project summary from milestone artifacts, for onboarding/review.
+
+### Repository Integration
+
+- **`/gsd:inbox [--issues] [--prs] [--label] [--close-incomplete] [--repo owner/repo]`** — Triages open GitHub issues/PRs against project templates and contribution guidelines.
+
+### Namespace Routers (model-facing meta-skills)
+
+Six skills for two-stage hierarchical routing across 60+ skills; invoke directly to browse a category interactively:
+
+- **`/gsd-context`** — Codebase intelligence (map, graphify, docs, learnings, mempalace).
+- **`/gsd-ideate`** — Exploration/capture (explore, sketch, spike, spec, capture).
+- **`/gsd-manage`** — Configuration/workspace (workstreams, thread, update, ship, inbox).
+- **`/gsd-project`** — Project-lifecycle (milestones, audits, summary).
+- **`/gsd-quality`** — Quality gates (code review, debug, audit, security, eval, ui).
+- **`/gsd-workflow`** — Phase pipeline (discuss, plan, execute, verify, phase, progress).
+
+## Files & Structure
+
+```text
+.planning/
+├── PROJECT.md            # Project vision
+├── ROADMAP.md            # Current phase breakdown
+├── STATE.md              # Project memory & context
+├── RETROSPECTIVE.md      # Living retrospective (updated per milestone)
+├── config.json           # Workflow mode & gates
+├── todos/                # Captured ideas and tasks (pending/, completed/)
+├── spikes/               # Spike experiments — MANIFEST.md + NNN-name/ dirs
+├── sketches/             # Design sketches — MANIFEST.md, themes/, NNN-name/ dirs
+├── debug/                # Active debug sessions (resolved/ archive)
+├── milestones/           # Archived roadmap/requirements snapshots + v{X.Y}-phases/
+├── codebase/             # Codebase map (brownfield): STACK/ARCHITECTURE/STRUCTURE/
+│                         # CONVENTIONS/TESTING/INTEGRATIONS/CONCERNS.md
+└── phases/               # 01-foundation/01-01-PLAN.md + -SUMMARY.md, etc.
+```
+
+## Workflow Modes
+
+Set during `/gsd:new-project`, changeable anytime in `.planning/config.json`:
+
+- **Interactive** — confirms each major decision, pauses at checkpoints, more guidance.
+- **YOLO** — auto-approves most decisions, executes without confirmation, stops only for critical checkpoints.
+
+## Planning Configuration
+
+`.planning/config.json`:
+
+- **`planning.commit_docs`** (default `true`) — `false` keeps planning artifacts local-only (add `.planning/` to `.gitignore`); useful for OSS/client projects wanting private planning.
+- **`planning.search_gitignored`** (default `false`) — `true` adds `--no-ignore` to broad ripgrep searches when `.planning/` is gitignored.
+
+```json
+{
+  "planning": {
+    "commit_docs": false,
+    "search_gitignored": true
+  }
+}
+```
+
+## Common Workflows
+
+**New project:** `/gsd:new-project` → `/clear` → `/gsd:plan-phase 1` → `/clear` → `/gsd:execute-phase 1`
+
+**Resuming:** `/gsd:progress`
+
+**Urgent mid-milestone work:** `/gsd:phase --insert 5 "Critical security fix"` → `/gsd:plan-phase 5.1` → `/gsd:execute-phase 5.1`
+
+**Completing a milestone:** `/gsd:complete-milestone 1.0.0` → `/clear` → `/gsd:new-milestone`
+
+**Capturing ideas:** `/gsd:capture` (from context) · `/gsd:capture --note ...` (quick note) · `/gsd:capture --seed "..."` (forward-looking) · `/gsd:capture --list` (review)
+
+**Debugging:** `/gsd:debug "symptom"` → (investigate, context fills) → `/clear` → `/gsd:debug` (resumes)
+
+## Getting Help
+
+- Read `.planning/PROJECT.md` for project vision
+- Read `.planning/STATE.md` for current context
+- Check `.planning/ROADMAP.md` for phase status
+- Run `/gsd:progress` to check where you're up to
+</reference>

package/gsd-core/workflows/help.md

@@ -10,7 +10,7 @@ Display GSD command help at the tier the user asked for. Output ONLY the referen
 | When `$ARGUMENTS` is | Read |
 |---|---|
 | `--brief` (or `-b`) alone | `workflows/help/modes/brief.md` |
-| `--full` (or `-f`, `--all`) alone | `workflows/help/modes/full.md` |
+| `--full` (or `-f`, `--all`) alone | `workflows/help/modes/full.md` (or its `workflows/help/modes/full.compact.md` variant per `gsd-core/references/compact-content-gate.md` §"Streams 1b and 4 — variant resolution") |
 | empty / unset | `workflows/help/modes/default.md` |
 | `--brief <topic>` (or `-b <topic>`) | `workflows/help/modes/topic.md` in compact scope (signature + one-line summary of the matched section) |
 | anything else — bare topic, `--full <topic>`, or topic with leading `--` | `workflows/help/modes/topic.md` in full scope (entire matched section) |

package/gsd-core/workflows/map-codebase.md

@@ -41,8 +41,9 @@ operates in **incremental-remap mode**:
 - Reject path values that contain `..`, start with `/`, or include shell
   metacharacters (`;`, `` ` ``, `$`, `&`, `|`, `<`, `>`). If all provided
   paths are invalid, fall back to a normal whole-repo run.
-- On write, each mapper stamps `last_mapped_commit: <HEAD sha>` into the YAML
-  frontmatter of every document it produces (see `bin/lib/drift.cjs:writeMappedCommit`).
+- The `last_mapped_commit` baseline is NOT the mapper's job. It is stamped
+  deterministically by the `stamp_codebase_map` step below, on every run,
+  incremental or full. See that step for why.
 
 **Explicit contract — propagate `--paths` through a single normalized
 variable.** Downstream steps (`spawn_agents`, `sequential_mapping`, and any
@@ -103,9 +104,21 @@ What's next?
 Wait for user response.
 
 If "Refresh": Delete .planning/codebase/, continue to create_structure
-If "Update": Ask which documents to update, continue to spawn_agents (filtered)
+If "Update": Ask which documents to update, then record the selection for the
+stamp step below and continue to spawn_agents (filtered):
+
+```bash
+# Comma-separated filenames the user selected, e.g. "STACK.md,CONCERNS.md":
+UPDATED_DOCS="<selected documents>"
+```
+
 If "Skip": Exit workflow
 
+`UPDATED_DOCS` narrows `stamp_codebase_map`. Leave it empty on every other
+path (Refresh, first run, `--paths`), which regenerate all seven documents.
+An Update run does not touch the documents the user did not select, so
+stamping those at HEAD would claim a freshness they do not have.
+
 **If doesn't exist:**
 Continue to create_structure.
 </step>
@@ -347,6 +360,40 @@ wc -l .planning/codebase/*.md
 
 If any documents missing or empty, note which agents may have failed.
 
+Continue to stamp_codebase_map.
+</step>
+
+<step name="stamp_codebase_map">
+Stamp the drift baseline into every document that was just written:
+
+```bash
+gsd_run stamp-codebase-map ${UPDATED_DOCS:+--files "$UPDATED_DOCS"}
+```
+
+This writes `last_mapped_commit: <HEAD sha>` and `last_mapped_at: <date>` into
+the YAML frontmatter of each `.planning/codebase/*.md` that exists. It runs on
+every mapping run, incremental (`--paths`) and full alike. `--files` narrows it
+to the documents an Update run actually refreshed; `--paths` needs no narrowing
+because all seven are regenerated, just scoped in content.
+
+**Why this is a shell step and not an instruction to the mapper.** The stamp is
+the only machine-readable freshness marker: the `verify codebase-drift` gate
+reads it to decide what to diff HEAD against. The human-readable markers the
+mapper writes (`**Analysis Date:**`, `<!-- refreshed: ... -->`) are restamped
+unconditionally on an Update run, so a mapper that decides its work is already
+done and rewrites only the dates still looks fresh to a human. Leaving the
+machine-readable stamp to the same agent reproduces exactly the failure the
+stamp exists to detect. A shell step cannot be skipped by a confident agent.
+
+The command is non-blocking: it emits `skipped` with a `reason` outside a git
+repo or when no documents exist. Report `stamped` and `commit` in the summary
+if any entry in `failed` is non-empty; otherwise continue silently.
+
+Run in this position, before `commit_codebase_map`, the stamp lands on
+documents the mapper just wrote, so its markdown whitespace normalization is
+folded into the same commit. Running `stamp-codebase-map` by hand against an
+already-committed map reflows that map's whitespace as a side effect.
+
 Continue to scan_for_secrets.
 </step>
 

package/gsd-core/workflows/new-milestone.md

@@ -34,6 +34,10 @@ _GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-pars
 GSD_WS=""
 echo "$ARGUMENTS" | grep -qE -- '--ws[[:space:]]+[A-Za-z0-9._-]+' && GSD_WS=$(echo "$ARGUMENTS" | grep -oE -- '--ws[[:space:]]+[A-Za-z0-9._-]+')
 MILESTONE_ARG=$(echo "$ARGUMENTS" | sed -E 's/--ws[[:space:]]+[A-Za-z0-9._-]+//g' | xargs)
+# #4456: persist GSD_WS to a file so later steps' bash fences (each a
+# separate shell) can forward it — the same cross-fence problem Step 5/6
+# already solve for OUTGOING_MILESTONE via .gsd-outgoing-milestone.
+printf '%s' "$GSD_WS" > .planning/.gsd-ws-arg 2>/dev/null || true
 RESPONSE_LANGUAGE=$(gsd_run query config-get response_language --raw --default "" 2>/dev/null || echo "")
 # #2994: EARLY, section-manifest-only init.new-milestone call — needed here
 # (before Step 4) to gate the project-md-milestone-write section. This is
@@ -44,7 +48,11 @@ RESPONSE_LANGUAGE=$(gsd_run query config-get response_language --raw --default "
 # fields too early and corrupt the roadmapper's phase-numbering context.
 # init.new-milestone is a pure read (no mutation), so calling it twice is
 # safe; only `section_manifest` is consumed from this early call.
-INIT_EARLY=$(gsd_run query init.new-milestone)
+# #4456: $GSD_WS forwarded (same fence as the parse above, no round-trip
+# needed here) so the section manifest — and the shared PROJECT.md write
+# guard it gates — reflects the EXPLICITLY requested workstream, not
+# whatever ambient GSD_WORKSTREAM/session pointer happens to be active.
+INIT_EARLY=$(gsd_run query init.new-milestone $GSD_WS)
 if [[ "$INIT_EARLY" == @file:* ]]; then INIT_EARLY=$(cat "${INIT_EARLY#@file:}"); fi
 ```
 
@@ -195,10 +203,11 @@ blockers, todos) is preserved across the switch — symmetric with
 `milestone.complete`.
 
 ```bash
-OUTGOING_MILESTONE=$(gsd_run query state.get milestone --raw 2>/dev/null || true)
+GSD_WS_ARG=$(cat .planning/.gsd-ws-arg 2>/dev/null || true)
+OUTGOING_MILESTONE=$(gsd_run query state.get milestone --raw $GSD_WS_ARG 2>/dev/null || true)
 printf '%s' "$OUTGOING_MILESTONE" > .planning/.gsd-outgoing-milestone 2>/dev/null || true
 echo "Outgoing milestone (phase history archives under THIS version in step 6): ${OUTGOING_MILESTONE:-<unknown>}"
-gsd_run query state.milestone-switch --milestone "v[X.Y]" --name "[Name]"
+gsd_run query state.milestone-switch --milestone "v[X.Y]" --name "[Name]" $GSD_WS_ARG
 ```
 
 **Capture the outgoing version now.** The lines above read the *current* (previous) milestone
@@ -239,11 +248,12 @@ the captured value into the command, so untrusted STATE.md content cannot be re-
 shell:
 
 ```bash
+GSD_WS_ARG=$(cat .planning/.gsd-ws-arg 2>/dev/null || true)
 OUTGOING_MILESTONE=$(cat .planning/.gsd-outgoing-milestone 2>/dev/null || true)
 if [ -n "$OUTGOING_MILESTONE" ]; then
-  gsd_run query phases.clear --confirm --archive-version "$OUTGOING_MILESTONE"
+  gsd_run query phases.clear --confirm --archive-version "$OUTGOING_MILESTONE" $GSD_WS_ARG
 else
-  gsd_run query phases.clear --confirm
+  gsd_run query phases.clear --confirm $GSD_WS_ARG
 fi
 rm -f .planning/.gsd-outgoing-milestone 2>/dev/null || true
 ```
@@ -258,31 +268,48 @@ Stage the phase archive move + source removal so they land in the same commit as
 
 ```bash
 COMMIT_DOCS=$(gsd_run query config-get commit_docs --raw 2>/dev/null || echo "true")
+GSD_WS_ARG=$(cat .planning/.gsd-ws-arg 2>/dev/null || true)
+INIT_STAGE=$(gsd_run query init.new-milestone $GSD_WS_ARG)
+if [[ "$INIT_STAGE" == @file:* ]]; then INIT_STAGE=$(cat "${INIT_STAGE#@file:}"); fi
+_gsd_field() { node -e "const o=JSON.parse(process.argv[1]); const v=o[process.argv[2]]; process.stdout.write(v==null?'':String(v))" "$1" "$2"; }
+ARCHIVE_DIR=$(_gsd_field "$INIT_STAGE" archive_dir)
+PHASES_DIR=$(_gsd_field "$INIT_STAGE" phases_dir)
 if [ "$COMMIT_DOCS" != "false" ]; then
-  git add .planning/milestones/ .planning/phases/ 2>/dev/null || true
+  git add "$ARCHIVE_DIR/" "$PHASES_DIR/" 2>/dev/null || true
 fi
 ```
 
 When `commit_docs` is false, the archive move and phase removals are deliberately left unstaged here — not a bug — since Step 6's commit is skipped too.
 
-Stage PROJECT.md in both modes. Step 4's Part A guard — not this commit — is what protects the shared `## Current Milestone` heading (#2308): when a workstream is active Part A never writes it, so the only change PROJECT.md can carry here is Part B's idempotent `## Evolution` backfill, which must be committed rather than stranded as a dangling edit. Do NOT reintroduce a `[ -n "$GSD_WS" ]` branch around this commit: `GSD_WS` is set in Step 1's shell and each step's bash block runs in its own shell (the same reason Step 5 round-trips `OUTGOING_MILESTONE` through a file), so such a guard reads an unset variable, always takes the flat-mode branch, and only appears to work.
+Stage PROJECT.md in both modes. Step 4's Part A guard — not this commit — is what protects the shared `## Current Milestone` heading (#2308): when a workstream is active Part A never writes it, so the only change PROJECT.md can carry here is Part B's idempotent `## Evolution` backfill, which must be committed rather than stranded as a dangling edit. Do NOT reintroduce a `[ -n "$GSD_WS" ]` branch around this commit: `GSD_WS` is set in Step 1's shell and each step's bash block runs in its own shell (the same reason Step 5 round-trips `OUTGOING_MILESTONE` through a file), so such a guard reads an unset variable, always takes the flat-mode branch, and only appears to work. STATE.md, unlike PROJECT.md, IS workstream-scoped (Step 5's switch just wrote the workstream's own copy) — resolved below via `init.new-milestone` rather than a literal `.planning/STATE.md`, which would commit the wrong (or a stale, unrelated) file under an active workstream.
 
 ```bash
-gsd_run query commit "docs: start milestone v[X.Y] [Name]" --files .planning/PROJECT.md .planning/STATE.md
+GSD_WS_ARG=$(cat .planning/.gsd-ws-arg 2>/dev/null || true)
+INIT_COMMIT=$(gsd_run query init.new-milestone $GSD_WS_ARG)
+if [[ "$INIT_COMMIT" == @file:* ]]; then INIT_COMMIT=$(cat "${INIT_COMMIT#@file:}"); fi
+_gsd_field() { node -e "const o=JSON.parse(process.argv[1]); const v=o[process.argv[2]]; process.stdout.write(v==null?'':String(v))" "$1" "$2"; }
+STATE_PATH=$(_gsd_field "$INIT_COMMIT" state_path)
+PROJECT_PATH=$(_gsd_field "$INIT_COMMIT" project_path)
+gsd_run query commit "docs: start milestone v[X.Y] [Name]" --files "$PROJECT_PATH" "$STATE_PATH"
 ```
 
 ## 7. Load Context and Resolve Models
 
 ```bash
 RESET_PHASE_NUMBERS_PARAM=""; if [[ "$ARGUMENTS" =~ (^|[[:space:]])--reset-phase-numbers([[:space:]]|$) ]]; then RESET_PHASE_NUMBERS_PARAM="--reset-phase-numbers"; fi
-INIT=$(gsd_run query init.new-milestone $RESET_PHASE_NUMBERS_PARAM)
+GSD_WS_ARG=$(cat .planning/.gsd-ws-arg 2>/dev/null || true)
+INIT=$(gsd_run query init.new-milestone $RESET_PHASE_NUMBERS_PARAM $GSD_WS_ARG)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 AGENT_SKILLS_RESEARCHER=$(gsd_run query agent-skills gsd-project-researcher)
 AGENT_SKILLS_SYNTHESIZER=$(gsd_run query agent-skills gsd-research-synthesizer)
 AGENT_SKILLS_ROADMAPPER=$(gsd_run query agent-skills gsd-roadmapper)
 ```
+<!-- #4456: .planning/.gsd-ws-arg is NOT cleaned up here — Steps 9 and 10
+below still need to re-read it (each is its own shell) to resolve
+REQUIREMENTS.md/ROADMAP.md/STATE.md correctly under a workstream. It is
+removed in Step 10, its true last consumer. -->
 
-Extract from init JSON: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `research_enabled`, `current_milestone`, `project_exists`, `roadmap_exists`, `latest_completed_milestone`, `phase_dir_count`, `phase_archive_path`, `agents_installed`, `missing_agents`, `project_path`, `roadmap_path`, `requirements_path`, `config_path`, `research_dir`, `milestones_path`.
+Extract from init JSON: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `research_enabled`, `current_milestone`, `project_exists`, `roadmap_exists`, `latest_completed_milestone`, `phase_dir_count`, `phase_archive_path`, `agents_installed`, `missing_agents`, `project_path`, `roadmap_path`, `requirements_path`, `config_path`, `research_dir`, `milestones_path`, `phases_dir`, `archive_dir`.
 
 **If `agents_installed` is false:** Display a warning before proceeding:
 ```
@@ -495,7 +522,12 @@ If "adjust": Return to scoping.
 
 **Commit requirements:**
 ```bash
-gsd_run query commit "docs: define milestone v[X.Y] requirements" --files .planning/REQUIREMENTS.md
+GSD_WS_ARG=$(cat .planning/.gsd-ws-arg 2>/dev/null || true)
+INIT_REQ=$(gsd_run query init.new-milestone $GSD_WS_ARG)
+if [[ "$INIT_REQ" == @file:* ]]; then INIT_REQ=$(cat "${INIT_REQ#@file:}"); fi
+_gsd_field() { node -e "const o=JSON.parse(process.argv[1]); const v=o[process.argv[2]]; process.stdout.write(v==null?'':String(v))" "$1" "$2"; }
+REQUIREMENTS_PATH=$(_gsd_field "$INIT_REQ" requirements_path)
+gsd_run query commit "docs: define milestone v[X.Y] requirements" --files "$REQUIREMENTS_PATH"
 ```
 
 ## 10. Create Roadmap
@@ -579,7 +611,17 @@ Success criteria:
 
 **Commit roadmap** (after approval):
 ```bash
-gsd_run query commit "docs: create milestone v[X.Y] roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
+GSD_WS_ARG=$(cat .planning/.gsd-ws-arg 2>/dev/null || true)
+INIT_ROADMAP=$(gsd_run query init.new-milestone $GSD_WS_ARG)
+if [[ "$INIT_ROADMAP" == @file:* ]]; then INIT_ROADMAP=$(cat "${INIT_ROADMAP#@file:}"); fi
+_gsd_field() { node -e "const o=JSON.parse(process.argv[1]); const v=o[process.argv[2]]; process.stdout.write(v==null?'':String(v))" "$1" "$2"; }
+ROADMAP_PATH=$(_gsd_field "$INIT_ROADMAP" roadmap_path)
+STATE_PATH=$(_gsd_field "$INIT_ROADMAP" state_path)
+REQUIREMENTS_PATH=$(_gsd_field "$INIT_ROADMAP" requirements_path)
+gsd_run query commit "docs: create milestone v[X.Y] roadmap ([N] phases)" --files "$ROADMAP_PATH" "$STATE_PATH" "$REQUIREMENTS_PATH"
+# #4456: true last consumer of the persisted --ws in this workflow — the
+# round-trip file is no longer needed after this commit.
+rm -f .planning/.gsd-ws-arg 2>/dev/null || true
 ```
 
 ## 10.5. Link Pending Todos to Roadmap Phases