@therocketcode/gsd-core 1.4.0

package/gsd-core/references/few-shot-examples/verifier.md

@@ -0,0 +1,109 @@
+---
+component: verifier
+version: 2
+last_calibrated: 2026-03-25
+calibration_source: "Adapted from thinking-partner verification corpus"
+---
+
+# Verifier Few-Shot Examples
+
+## Positive Examples
+
+### Example 1: Thorough multi-level artifact verification with real gap discovery
+
+**Input:** Must-have artifact: `gsd-core/workflows/context-bridge.md: >50 lines`
+
+**Output:**
+
+> **L1 (Existence):** EXISTS -- `gsd-core/workflows/context-bridge.md` found, 187 lines.
+> **L2 (Substantive):** SUBSTANTIVE -- No TODO/FIXME markers, 4 defined sections (`updateContextTier`, `getContextBudget`, `injectContextWarning`, `resetTierState`), non-trivial logic with config reads and threshold calculations.
+> **L3 (Wired):** WIRED -- Referenced by `gsd-core/workflows/execute-phase.md` at step 3. Called by `agents/gsd-executor.md` via @-reference include. Arguments verified: receives planning directory path matching the expected parameter.
+> **Status: PASSED**
+
+**Why this is good:** The verifier checked all three levels independently with specific evidence at each level -- file path, line count, exported symbols, import location, and argument verification. It did not stop at "file exists" but traced wiring through to actual usage with correct arguments.
+
+### Example 2: Correct FAILED classification with grep evidence
+
+**Input:** Must-have truth: `validate-commit.js rejects commits missing scope parentheses`
+
+**Output:**
+
+> **Method:** Ran `grep -n "scope" gsd-core/bin/validate-commit.js` to locate scope validation logic.
+> **Evidence:** Lines 34-41 show regex `/^(feat|fix|refactor|test|docs|chore|wip)\(/` which requires opening paren after type. However, no test for MISSING closing paren exists -- the regex accepts `feat(: description` (missing scope content and closing paren).
+> **Ran:** `echo "feat(: test" | node gsd-core/bin/validate-commit.js` -- exit code 0 (accepted).
+> **Status: FAILED** -- Commit messages with empty scope `feat(: desc)` are accepted. The truth "rejects commits missing scope parentheses" does not hold for empty-scope edge case.
+
+**Why this is good:** The verifier did not trust the code's intent -- it ran an actual test with an edge case input and reported the specific failure. Evidence includes the regex, the test command, the exit code, and why the truth does not hold.
+
+### Example 3: Catching missing wiring (calibration-derived gap pattern)
+
+**Input:** Must-have key_link: `check-subagent-output.js imports and calls feedback-loop.js extractFeedback()`
+
+**Output:**
+
+> **Method:** Ran `grep -n "feedback-loop\|extractFeedback" gsd-core/bin/check-subagent-output.js`.
+> **Evidence:** Zero matches. The file `feedback-loop.js` exists (172 lines, substantive), and `tests/feedback-loop.test.js` passes (229 lines). But `check-subagent-output.js` never imports or calls it.
+> **Cross-check:** `grep -rn "require.*feedback-loop" gsd-core/bin/` returns zero results across all scripts.
+> **Status: FAILED** -- The artifact exists and is tested, but is completely orphaned. The key_link "imports and calls" does not hold. This is a **missing wiring** gap.
+
+**Why this is good:** The verifier caught a common calibration pattern: code that exists, is tested, but is never actually wired into the system. L1 and L2 pass, but L3 (wiring) fails. This pattern accounts for 37% of all gaps found in calibration corpus.
+
+### Example 4: Catching missing config schema entries (calibration-derived gap pattern)
+
+**Input:** Must-have truth: `Config toggles features.architecture_graph and features.architecture_guard exist with defaults`
+
+**Output:**
+
+> **Method:** Ran `grep "architecture_graph\|architecture_guard" gsd-core/bin/lib/config-schema.json`.
+> **Evidence:** Zero matches in schema. However, `grep "architecture" gsd-core/bin/lib/config.cjs` shows both flags in CONFIG_DEFAULTS (lines 426, 428).
+> **Gap:** Defaults exist in code but schema validation doesn't know about them. `configValidate()` would strip these fields on load, making the defaults unreachable.
+> **Status: FAILED** -- Config flags work in code but are invisible to schema validation. This is a **missing wiring** gap between config layers.
+
+**Why this is good:** The verifier checked multiple config layers (schema vs defaults vs code) rather than just one. Config wiring requires schema + defaults + code to agree -- checking only one layer misses layer-mismatch bugs.
+
+### Example 5: Distinguishing planning gaps from execution failures
+
+**Input:** Must-have truth: `All MSYS regex patterns consolidated into shared module`
+
+**Output:**
+
+> **Method:** Ran `grep -rn "\/\[a-zA-Z\]\/" gsd-core/bin/` to find inline MSYS regex.
+> **Evidence:** 2 matches in `commands/gsd/misc.md` (lines 26, 487). These were NOT in the original plan scope -- Phase 148 extracted code into misc.md AFTER Phase 149's plan was written.
+> **Assessment:** The executor correctly completed all planned tasks. The gap is a **planning ordering issue**, not an execution failure.
+> **Status: PASS_WITH_NOTES** -- Executor did what was planned. Unconsolidated regex noted as follow-up, not as a failure of this phase.
+
+**Why this is good:** The verifier distinguished between what was planned vs what exists now. Code that changed AFTER plan creation is a planning gap, not an executor failure. This prevents false FAIL verdicts on correctly-executed work.
+
+## Calibration-Derived Gap Patterns
+
+Based on analysis of verification corpus (80% pass rate, 8 gaps):
+
+| Pattern | Count | % of Gaps | What to Check |
+|---------|-------|-----------|---------------|
+| Missing wiring | 3 | 37% | File exists + tested but never imported/called by consumer |
+| Missing tests | 2 | 25% | Feature works but test file excluded from CI or never runs |
+| Other | 3 | 38% | Config layer mismatches, planning ordering issues, schema gaps |
+
+## Negative Examples
+
+### Example 1: Blanket pass with no per-criterion evidence
+
+**Input:** Must-haves: 5 truths, 3 artifacts, 2 key_links from plan frontmatter.
+
+**Output:**
+
+> All must-haves have been verified. The implementation matches the plan requirements. Files exist and are properly connected. Status: PASSED.
+> must_haves_checked: 10, must_haves_passed: 10
+
+**Why this is bad:** No individual must-have is listed or checked. No file paths, no line numbers, no grep output, no level-by-level breakdown. The verifier restated the must-haves as passing without showing any evidence. This would miss stubs, orphaned exports, and broken wiring.
+
+### Example 2: File existence check without substance or wiring verification
+
+**Input:** Must-have artifact: `gsd-core/bin/lib/audit-checks/index.cjs: >100 lines`
+
+**Output:**
+
+> **L1 (Existence):** EXISTS -- File found at `gsd-core/bin/lib/audit-checks/index.cjs`, 142 lines.
+> **Status: PASSED**
+
+**Why this is bad:** The verifier stopped at Level 1. The file has 142 lines but could contain `// TODO: implement all checks` with stub functions returning empty objects. Level 2 (substantive) and Level 3 (wired) were skipped entirely. A file that exists but is never imported or contains only placeholder code should not pass.

package/gsd-core/references/flaky-test-checklist.md

@@ -0,0 +1,22 @@
+# Flaky-Test Avoidance Checklist
+
+How-to reference for preventing flaky tests (intermittent pass/fail). Read when a test is flaky, or proactively when writing integration/e2e tests. (Empirically, async-wait is the #1 cause (~45%), then concurrency (~20%) and test-order dependence (~12%) — Luo et al., FSE 2014.)
+
+## Checklist
+
+- [ ] **Mock the clock** — inject a fixed/controllable clock; never call `now()` / `Date.now()` directly in code under test.
+- [ ] **Seed randomness** — fixed RNG seed; never raw Faker values in assertions (use sequences/UUIDs).
+- [ ] **Poll, don't sleep** — wait for a **condition** (element visible, API responded, row present), not a fixed interval. `sleep(2000)` is slow-when-fast and still flaky-when-slow. Poll with backoff for eventually-consistent reads.
+- [ ] **Use framework actionability waits** — Playwright auto-waits; Testcontainers `Wait.*` strategies. Removes the #1 flake cause by construction.
+- [ ] **Order independence** — every test self-seeds; no test depends on another's leftover state. (Randomize test order to surface hidden dependence.)
+- [ ] **No shared mutable global state** — separate temp dirs / DBs / schemas per worker (see `db-test-isolation.md`).
+- [ ] **Isolate external services** — fakes/stubs/contract tests at the boundary; retry-with-backoff ONLY at genuine integration edges.
+- [ ] **Quarantine, don't ignore** — detect/mark flaky tests, auto-rerun, stage new tests before the critical path; treat flakiness as infra debt, not noise.
+
+## The big three causes (fix structurally, not with retries)
+
+1. **Async/timing (~45%)** → poll for conditions, framework waits, fixed clock.
+2. **Concurrency / shared state (~20%)** → per-worker isolation, no shared globals.
+3. **Order dependence (~12%)** → self-seeding tests; randomized order to surface it.
+
+*Sources: Luo et al., "An Empirical Analysis of Flaky Tests" (FSE 2014) for the cause breakdown; Google Testing Blog (flaky tests at Google); OpenReplay (time/async in tests); patterns from `db-test-isolation.md` & `test-containers.md`.*

package/gsd-core/references/gate-prompts.md

@@ -0,0 +1,100 @@
+# Gate Prompt Patterns
+
+Reusable prompt patterns for structured gate checks in workflows and agents.
+
+**For checkpoint box format details, see `references/ui-brand.md`** -- checkpoint boxes use double-line border drawing with 62-character inner width.
+
+## Rules
+
+- `header` must be max 12 characters
+- `multiSelect` is always `false` for gate checks
+- Always handle the "Other" case (user typed a freeform response instead of selecting)
+- Max 4 options per prompt -- if more are needed, use a 2-step flow
+
+---
+
+## Pattern: approve-revise-abort
+3-option gate for plan approval, gap-closure approval.
+- question: "Approve these {noun}?"
+- header: "Approve?"
+- options: Approve | Request changes | Abort
+
+## Pattern: yes-no
+Simple 2-option confirmation for re-planning, rebuild, replace plans, commit.
+- question: "{Specific question about the action}"
+- header: "Confirm"
+- options: Yes | No
+
+## Pattern: stale-continue
+2-option refresh gate for staleness warnings, timestamp freshness.
+- question: "{Artifact} may be outdated. Refresh or continue?"
+- header: "Stale"
+- options: Refresh | Continue anyway
+
+## Pattern: yes-no-pick
+3-option selection for seed selection, item inclusion.
+- question: "Include {items} in planning?"
+- header: "Include?"
+- options: Yes, all | Let me pick | No
+
+## Pattern: multi-option-failure
+4-option failure handler for build failures.
+- question: "Plan {id} failed. How should we proceed?"
+- header: "Failed"
+- options: Retry | Skip | Rollback | Abort
+
+## Pattern: multi-option-escalation
+4-option escalation for review escalation (max retries exceeded).
+- question: "Phase {N} has failed verification {attempt} times. How should we proceed?"
+- header: "Escalate"
+- options: Accept gaps | Re-plan (via /gsd:plan-phase) | Debug (via /gsd:debug) | Retry
+
+## Pattern: multi-option-gaps
+4-option gap handler for review gaps-found.
+- question: "{count} verification gaps need attention. How should we proceed?"
+- header: "Gaps"
+- options: Auto-fix | Override | Manual | Skip
+
+## Pattern: multi-option-priority
+4-option priority selection for milestone gap priority.
+- question: "Which gaps should we address?"
+- header: "Priority"
+- options: Must-fix only | Must + should | Everything | Let me pick
+
+## Pattern: toggle-confirm
+2-option confirmation for enabling/disabling boolean features.
+- question: "Enable {feature_name}?"
+- header: "Toggle"
+- options: Enable | Disable
+
+## Pattern: action-routing
+Up to 4 suggested next actions with selection (status, resume workflows).
+- question: "What would you like to do next?"
+- header: "Next Step"
+- options: {primary action} | {alternative 1} | {alternative 2} | Something else
+- Note: Dynamically generate options from workflow state. Always include "Something else" as last option.
+
+## Pattern: scope-confirm
+3-option confirmation for quick task scope validation.
+- question: "This task looks complex. Proceed as quick task or use full planning?"
+- header: "Scope"
+- options: Quick task | Full plan (via /gsd:plan-phase) | Revise
+
+## Pattern: depth-select
+3-option depth selection for planning workflow preferences.
+- question: "How thorough should planning be?"
+- header: "Depth"
+- options: Quick (3-5 phases, skip research) | Standard (5-8 phases, default) | Comprehensive (8-12 phases, deep research)
+
+## Pattern: context-handling
+3-option handler for existing CONTEXT.md in discuss workflow.
+- question: "Phase {N} already has a CONTEXT.md. How should we handle it?"
+- header: "Context"
+- options: Overwrite | Append | Cancel
+
+## Pattern: gray-area-option
+Dynamic template for presenting gray area choices in discuss workflow.
+- question: "{Gray area title}"
+- header: "Decision"
+- options: {Option 1} | {Option 2} | Let Claude decide
+- Note: Options generated at runtime. Always include "Let Claude decide" as last option.

package/gsd-core/references/gates.md

@@ -0,0 +1,70 @@
+# Gates Taxonomy
+
+Canonical gate types used across GSD workflows. Every validation checkpoint maps to one of these four types.
+
+---
+
+## Gate Types
+
+### Pre-flight Gate
+**Purpose:** Validates preconditions before starting an operation.
+**Behavior:** Blocks entry if conditions unmet. No partial work created.
+**Recovery:** Fix the missing precondition, then retry.
+**Examples:**
+- Plan-phase checks for REQUIREMENTS.md before planning
+- Execute-phase validates PLAN.md exists before execution
+- Discuss-phase confirms phase exists in ROADMAP.md
+
+### Revision Gate
+**Purpose:** Evaluates output quality and routes to revision if insufficient.
+**Behavior:** Loops back to producer with specific feedback. Bounded by iteration cap.
+**Recovery:** Producer addresses feedback; checker re-evaluates. The loop also escalates early if issue count does not decrease between consecutive iterations (stall detection). After max iterations, escalates unconditionally.
+**Examples:**
+- Plan-checker reviewing PLAN.md (max 3 iterations)
+- Verifier checking phase deliverables against success criteria
+
+### Escalation Gate
+**Purpose:** Surfaces unresolvable issues to the developer for a decision.
+**Behavior:** Pauses workflow, presents options, waits for human input.
+**Recovery:** Developer chooses action; workflow resumes on selected path.
+**Examples:**
+- Revision loop exhausted after 3 iterations
+- Merge conflict during worktree cleanup
+- Ambiguous requirement needing clarification
+
+### Abort Gate
+**Purpose:** Terminates the operation to prevent damage or waste.
+**Behavior:** Stops immediately, preserves state, reports reason.
+**Recovery:** Developer investigates root cause, fixes, restarts from checkpoint.
+**Examples:**
+- Context window critically low during execution
+- STATE.md in error state blocking /gsd-next
+- Verification finds critical missing deliverables
+
+---
+
+## Gate Matrix
+
+| Workflow | Phase | Gate Type | Artifacts Checked | Failure Behavior |
+|----------|-------|-----------|-------------------|------------------|
+| plan-phase | Entry | Pre-flight | REQUIREMENTS.md, ROADMAP.md | Block with missing-file message |
+| plan-phase | Step 12 | Revision | PLAN.md quality | Loop to planner (max 3) |
+| plan-phase | Post-revision | Escalation | Unresolved issues | Surface to developer |
+| execute-phase | Entry | Pre-flight | PLAN.md | Block with missing-plan message |
+| execute-phase | Completion | Revision | SUMMARY.md completeness | Re-run incomplete tasks |
+| verify-work | Entry | Pre-flight | SUMMARY.md | Block with missing-summary |
+| verify-work | Evaluation | Escalation | Failed criteria | Surface gaps to developer |
+| next | Entry | Abort | Error state, checkpoints | Stop with diagnostic |
+
+---
+
+## Implementing Gates
+
+Use this taxonomy when designing or auditing workflow validation points:
+
+- **Pre-flight** gates belong at workflow entry points. They are cheap, deterministic checks that prevent wasted work. If you can verify a precondition with a file-existence check or a config read, use a pre-flight gate.
+- **Revision** gates belong after a producer step where quality varies. Always pair them with an iteration cap to prevent infinite loops. The cap should reflect the cost of each iteration -- expensive operations get fewer retries.
+- **Escalation** gates belong wherever automated resolution is impossible or ambiguous. They are the safety valve between revision loops and abort. Present the developer with clear options and enough context to decide.
+- **Abort** gates belong at points where continuing would cause damage, waste significant resources, or produce meaningless output. They should preserve state so work can resume after the root cause is fixed.
+
+**Selection heuristic:** Start with pre-flight. If the check happens after work is produced, it is a revision gate. If the revision loop cannot resolve the issue, escalate. If continuing is dangerous, abort.

package/gsd-core/references/git-integration.md

@@ -0,0 +1,298 @@
+<overview>
+Git integration for GSD framework.
+</overview>
+
+<core_principle>
+
+**Commit outcomes, not process.**
+
+The git log should read like a changelog of what shipped, not a diary of planning activity.
+</core_principle>
+
+<commit_points>
+
+| Event                   | Commit? | Why                                              |
+| ----------------------- | ------- | ------------------------------------------------ |
+| BRIEF + ROADMAP created | YES     | Project initialization                           |
+| PLAN.md created         | NO      | Intermediate - commit with plan completion       |
+| RESEARCH.md created     | NO      | Intermediate                                     |
+| DISCOVERY.md created    | NO      | Intermediate                                     |
+| **Task completed**      | YES     | Atomic unit of work (1 commit per task)         |
+| **Plan completed**      | YES     | Metadata commit (SUMMARY + STATE + ROADMAP)     |
+| Handoff created         | YES     | WIP state preserved                              |
+
+</commit_points>
+
+<git_check>
+
+```bash
+[ -d .git ] && echo "GIT_EXISTS" || echo "NO_GIT"
+```
+
+If NO_GIT: Run `git init` silently. GSD projects always get their own repo.
+</git_check>
+
+<commit_formats>
+
+<format name="initialization">
+## Project Initialization (brief + roadmap together)
+
+```
+docs: initialize [project-name] ([N] phases)
+
+[One-liner from PROJECT.md]
+
+Phases:
+1. [phase-name]: [goal]
+2. [phase-name]: [goal]
+3. [phase-name]: [goal]
+```
+
+What to commit:
+
+```bash
+gsd-tools query commit "docs: initialize [project-name] ([N] phases)" --files .planning/
+```
+
+</format>
+
+<format name="task-completion">
+## Task Completion (During Plan Execution)
+
+Each task gets its own commit immediately after completion.
+
+> **Parallel agents:** When running as a parallel executor (spawned by execute-phase),
+> run commits normally — let pre-commit hooks run. Do NOT pass `--no-verify` by default
+> (#2924). Hooks should fire on the introducing commit; silent bypass violates project
+> CLAUDE.md guidance. If a project explicitly opts out via
+> `workflow.worktree_skip_hooks=true`, the orchestrator surfaces that flag in the
+> executor prompt; absent that signal, hooks run normally.
+
+```
+{type}({phase}-{plan}): {task-name}
+
+- [Key change 1]
+- [Key change 2]
+- [Key change 3]
+```
+
+**Commit types:**
+- `feat` - New feature/functionality
+- `fix` - Bug fix
+- `test` - Test-only (TDD RED phase)
+- `refactor` - Code cleanup (TDD REFACTOR phase)
+- `perf` - Performance improvement
+- `chore` - Dependencies, config, tooling
+
+**Examples:**
+
+```bash
+# Standard task
+git add src/api/auth.ts src/types/user.ts
+git commit -m "feat(08-02): create user registration endpoint
+
+- POST /auth/register validates email and password
+- Checks for duplicate users
+- Returns JWT token on success
+"
+
+# TDD task - RED phase
+git add src/__tests__/jwt.test.ts
+git commit -m "test(07-02): add failing test for JWT generation
+
+- Tests token contains user ID claim
+- Tests token expires in 1 hour
+- Tests signature verification
+"
+
+# TDD task - GREEN phase
+git add src/utils/jwt.ts
+git commit -m "feat(07-02): implement JWT generation
+
+- Uses jose library for signing
+- Includes user ID and expiry claims
+- Signs with HS256 algorithm
+"
+```
+
+</format>
+
+<format name="plan-completion">
+## Plan Completion (After All Tasks Done)
+
+After all tasks committed, one final metadata commit captures plan completion.
+
+```
+docs({phase}-{plan}): complete [plan-name] plan
+
+Tasks completed: [N]/[N]
+- [Task 1 name]
+- [Task 2 name]
+- [Task 3 name]
+
+SUMMARY: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md
+```
+
+What to commit:
+
+```bash
+gsd-tools query commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md
+```
+
+**Note:** Code files NOT included - already committed per-task.
+
+</format>
+
+<format name="handoff">
+## Handoff (WIP)
+
+```
+wip: [phase-name] paused at task [X]/[Y]
+
+Current: [task name]
+[If blocked:] Blocked: [reason]
+```
+
+What to commit:
+
+```bash
+gsd-tools query commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/
+```
+
+</format>
+</commit_formats>
+
+<example_log>
+
+**Old approach (per-plan commits):**
+```
+a7f2d1 feat(checkout): Stripe payments with webhook verification
+3e9c4b feat(products): catalog with search, filters, and pagination
+8a1b2c feat(auth): JWT with refresh rotation using jose
+5c3d7e feat(foundation): Next.js 15 + Prisma + Tailwind scaffold
+2f4a8d docs: initialize ecommerce-app (5 phases)
+```
+
+**New approach (per-task commits):**
+```
+# Phase 04 - Checkout
+1a2b3c docs(04-01): complete checkout flow plan
+4d5e6f feat(04-01): add webhook signature verification
+7g8h9i feat(04-01): implement payment session creation
+0j1k2l feat(04-01): create checkout page component
+
+# Phase 03 - Products
+3m4n5o docs(03-02): complete product listing plan
+6p7q8r feat(03-02): add pagination controls
+9s0t1u feat(03-02): implement search and filters
+2v3w4x feat(03-01): create product catalog schema
+
+# Phase 02 - Auth
+5y6z7a docs(02-02): complete token refresh plan
+8b9c0d feat(02-02): implement refresh token rotation
+1e2f3g test(02-02): add failing test for token refresh
+4h5i6j docs(02-01): complete JWT setup plan
+7k8l9m feat(02-01): add JWT generation and validation
+0n1o2p chore(02-01): install jose library
+
+# Phase 01 - Foundation
+3q4r5s docs(01-01): complete scaffold plan
+6t7u8v feat(01-01): configure Tailwind and globals
+9w0x1y feat(01-01): set up Prisma with database
+2z3a4b feat(01-01): create Next.js 15 project
+
+# Initialization
+5c6d7e docs: initialize ecommerce-app (5 phases)
+```
+
+Each plan produces 2-4 commits (tasks + metadata). Clear, granular, bisectable.
+
+</example_log>
+
+<anti_patterns>
+
+**Still don't commit (intermediate artifacts):**
+- PLAN.md creation (commit with plan completion)
+- RESEARCH.md (intermediate)
+- DISCOVERY.md (intermediate)
+- Minor planning tweaks
+- "Fixed typo in roadmap"
+
+**Do commit (outcomes):**
+- Each task completion (feat/fix/test/refactor)
+- Plan completion metadata (docs)
+- Project initialization (docs)
+
+**Key principle:** Commit working code and shipped outcomes, not planning process.
+
+</anti_patterns>
+
+<commit_strategy_rationale>
+
+## Why Per-Task Commits?
+
+**Context engineering for AI:**
+- Git history becomes primary context source for future Claude sessions
+- `git log --grep="{phase}-{plan}"` shows all work for a plan
+- `git diff <hash>^..<hash>` shows exact changes per task
+- Less reliance on parsing SUMMARY.md = more context for actual work
+
+**Failure recovery:**
+- Task 1 committed ✅, Task 2 failed ❌
+- Claude in next session: sees task 1 complete, can retry task 2
+- Can `git reset --hard` to last successful task
+
+**Debugging:**
+- `git bisect` finds exact failing task, not just failing plan
+- `git blame` traces line to specific task context
+- Each commit is independently revertable
+
+**Observability:**
+- Solo developer + Claude workflow benefits from granular attribution
+- Atomic commits are git best practice
+- "Commit noise" irrelevant when consumer is Claude, not humans
+
+</commit_strategy_rationale>
+
+<sub_repos_support>
+
+## Multi-Repo Workspace Support (sub_repos)
+
+For workspaces with separate git repos (e.g., `backend/`, `frontend/`, `shared/`), GSD routes commits to each repo independently.
+
+### Configuration
+
+In `.planning/config.json`, list sub-repo directories under `planning.sub_repos`:
+
+```json
+{
+  "planning": {
+    "commit_docs": false,
+    "sub_repos": ["backend", "frontend", "shared"]
+  }
+}
+```
+
+Set `commit_docs: false` so planning docs stay local and are not committed to any sub-repo.
+
+### How It Works
+
+1. **Auto-detection:** During `/gsd:new-project`, directories with their own `.git` folder are detected and offered for selection as sub-repos. On subsequent runs, `loadConfig` auto-syncs the `sub_repos` list with the filesystem — adding newly created repos and removing deleted ones. This means `config.json` may be rewritten automatically when repos change on disk.
+2. **File grouping:** Code files are grouped by their sub-repo prefix (e.g., `backend/src/api/users.ts` belongs to the `backend/` repo).
+3. **Independent commits:** Each sub-repo receives its own atomic commit via `gsd-tools.cjs commit-to-subrepo`. File paths are made relative to the sub-repo root before staging.
+4. **Planning stays local:** The `.planning/` directory is not committed; it acts as cross-repo coordination.
+
+### Commit Routing
+
+Instead of the standard `commit` command, use `commit-to-subrepo` when `sub_repos` is configured:
+
+```bash
+gsd-tools query commit-to-subrepo "feat(02-01): add user API" \
+  --files backend/src/api/users.ts backend/src/types/user.ts frontend/src/components/UserForm.tsx
+```
+
+This stages `src/api/users.ts` and `src/types/user.ts` in the `backend/` repo, and `src/components/UserForm.tsx` in the `frontend/` repo, then commits each independently with the same message.
+
+Files that don't match any configured sub-repo are reported as unmatched.
+
+</sub_repos_support>

package/gsd-core/references/git-planning-commit.md

@@ -0,0 +1,40 @@
+# Git Planning Commit
+
+Commit planning artifacts via `gsd-tools query commit`, which checks `commit_docs` config and gitignore status (same behavior as legacy `gsd-tools.cjs commit`).
+
+## Commit via CLI
+
+Pass the message first, then file paths via `--files`. Both `commit` and `commit-to-subrepo` use `--files` to declare the paths to commit.
+
+Always use this for `.planning/` files — it handles `commit_docs` and gitignore checks automatically:
+
+```bash
+gsd-tools query commit "docs({scope}): {description}" --files .planning/STATE.md .planning/ROADMAP.md
+```
+
+The CLI will return `skipped` (with reason) if `commit_docs` is `false` or `.planning/` is gitignored. No manual conditional checks needed.
+
+## Amend previous commit
+
+To fold `.planning/` file changes into the previous commit:
+
+```bash
+gsd-tools query commit "" --files .planning/codebase/*.md --amend
+```
+
+## Commit Message Patterns
+
+| Command | Scope | Example |
+|---------|-------|---------|
+| plan-phase | phase | `docs(phase-03): create authentication plans` |
+| execute-phase | phase | `docs(phase-03): complete authentication phase` |
+| new-milestone | milestone | `docs: start milestone v1.1` |
+| remove-phase | chore | `chore: remove phase 17 (dashboard)` |
+| insert-phase | phase | `docs: insert phase 16.1 (critical fix)` |
+| add-phase | phase | `docs: add phase 07 (settings page)` |
+
+## When to Skip
+
+- `commit_docs: false` in config
+- `.planning/` is gitignored
+- No changes to commit (check with `git status --porcelain .planning/`)