@opengsd/gsd-core 1.2.0-rc.1

package/get-shit-done/references/planner-human-verify-mode.md

@@ -0,0 +1,57 @@
+# Planner — Human Verification Mode
+
+> Loaded by `gsd-planner` when deciding whether to emit `<task type="checkpoint:human-verify">` tasks. Read `workflow.human_verify_mode` from `.planning/config.json` (default `end-of-phase` since #3309).
+
+## The two modes
+
+### `end-of-phase` (default — issue #3309)
+
+Do **not** emit any `<task type="checkpoint:human-verify">` tasks. Every mid-flight halt costs a full executor cold-start (CLAUDE.md, MEMORY.md, STATE.md, plan re-read on respawn) because subagent context is discarded across the pause; a plan with N human-verify checkpoints pays the cold-start cost N+1 times — measured at "tens of thousands of tokens" per round-trip on real projects. This is the default for that reason.
+
+Instead, fold each would-be verification step into the relevant `auto` task using a `<verify><human-check>` sub-block:
+
+```xml
+<task type="auto">
+  <name>Wire dashboard route</name>
+  <files>app/dashboard/page.tsx, app/api/dashboard/route.ts</files>
+  <action>...</action>
+  <verify>
+    <automated>npm test -- --filter=dashboard</automated>
+    <human-check>
+      <test>Visit http://localhost:3000/dashboard</test>
+      <expected>Sidebar left, content right on desktop &gt;1024px; collapses to hamburger at 768px</expected>
+      <why_human>Visual layout — grep cannot verify breakpoint behavior</why_human>
+    </human-check>
+  </verify>
+  <done>Layout renders correctly across breakpoints</done>
+</task>
+```
+
+The verifier (Step 8) harvests every `<verify><human-check>` block at end-of-phase and consolidates them into the existing `human_needed` → HUMAN-UAT.md path in `workflows/execute-phase.md`. The user reviews everything in one batch instead of paying a cold-start cost per item.
+
+### `mid-flight` (opt-back-in — pre-#3309 behavior)
+
+Set `gsd config-set workflow.human_verify_mode mid-flight` to restore the canonical mid-flight pattern: emit `<task type="checkpoint:human-verify">` tasks at the points where human confirmation is required, and the executor halts at each one to ask the user.
+
+```xml
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>Dev server running at http://localhost:3000</what-built>
+  <how-to-verify>
+    1. Visit /dashboard
+    2. Sidebar collapses at 768px
+  </how-to-verify>
+  <resume-signal>"approved" or describe issues</resume-signal>
+</task>
+```
+
+Choose `mid-flight` when you genuinely need the work to stop before any subsequent task runs (e.g., the next task depends on visual confirmation of the previous one), and you accept the cold-start cost as the price of that hard barrier.
+
+## What is *not* affected
+
+`checkpoint:decision` and `checkpoint:human-action` tasks are still emitted in `end-of-phase` mode. Those gate the work itself (a choice the executor needs from the user, or an auth step only the user can perform), not post-hoc verification of completed work. Only `checkpoint:human-verify` is suppressed.
+
+## Compatibility with other modes
+
+- **`workflow.tdd_mode`**: orthogonal. TDD tasks still emit `tdd="true"` and `<behavior>`; the `<verify>` block carries the human-check sub-element when `human_verify_mode = end-of-phase`.
+- **`MVP_MODE`**: orthogonal. Vertical-slice ordering is unchanged. The first task remains a failing end-to-end test; later auto tasks may carry `<verify><human-check>` instead of standalone checkpoint tasks.
+- **`workflow.auto_advance` / `_auto_chain_active`**: in mid-flight mode these auto-approve checkpoint:human-verify halts. In end-of-phase mode there are no halts to auto-approve, so the flags have no effect on this code path.

package/get-shit-done/references/planner-interface-context.md

@@ -0,0 +1,62 @@
+# Interface Context for Executors
+
+**Key insight:** "The difference between handing a contractor blueprints versus telling them 'build me a house.'"
+
+When creating plans that depend on existing code or create new interfaces consumed by other plans:
+
+## For plans that USE existing code:
+After determining `files_modified`, extract the key interfaces/types/exports from the codebase that executors will need:
+
+```bash
+# Extract type definitions, interfaces, and exports from relevant files
+grep -n "export\\|interface\\|type\\|class\\|function" {relevant_source_files} 2>/dev/null | head -50
+```
+
+Embed these in the plan's `<context>` section as an `<interfaces>` block:
+
+```xml
+<interfaces>
+<!-- Key types and contracts the executor needs. Extracted from codebase. -->
+<!-- Executor should use these directly — no codebase exploration needed. -->
+
+From src/types/user.ts:
+```typescript
+export interface User {
+  id: string;
+  email: string;
+  name: string;
+  createdAt: Date;
+}
+```
+
+From src/api/auth.ts:
+```typescript
+export function validateToken(token: string): Promise<User | null>;
+export function createSession(user: User): Promise<SessionToken>;
+```
+</interfaces>
+```
+
+## For plans that CREATE new interfaces:
+If this plan creates types/interfaces that later plans depend on, include a "Wave 0" skeleton step:
+
+```xml
+<task type="auto">
+  <name>Task 0: Write interface contracts</name>
+  <files>src/types/newFeature.ts</files>
+  <action>Create type definitions that downstream plans will implement against. These are the contracts — implementation comes in later tasks.</action>
+  <verify>File exists with exported types, no implementation</verify>
+  <done>Interface file committed, types exported</done>
+</task>
+```
+
+## When to include interfaces:
+- Plan touches files that import from other modules → extract those module's exports
+- Plan creates a new API endpoint → extract the request/response types
+- Plan modifies a component → extract its props interface
+- Plan depends on a previous plan's output → extract the types from that plan's files_modified
+
+## When to skip:
+- Plan is self-contained (creates everything from scratch, no imports)
+- Plan is pure configuration (no code interfaces involved)
+- Level 0 discovery (all patterns already established)

package/get-shit-done/references/planner-mvp-mode.md

@@ -0,0 +1,53 @@
+# Planner — MVP Mode (Vertical Slice Strategy)
+
+> Loaded by `gsd-planner` only when `MVP_MODE=true`. Standard horizontal-layer planning rules continue to apply for all other phases.
+
+## Core Rule
+
+**Decompose by feature slice, not by technical layer.** Every task must move the user-facing capability forward. After each task, a real user can click through more of the feature than they could before.
+
+**Forbidden** in MVP mode:
+- "Create the database schema" as a standalone task
+- "Build the API layer" as a standalone task
+- "Wire up the UI" as a final integration task
+
+**Required** in MVP mode:
+- The first non-test task produces a working end-to-end path. Stubs are allowed for non-critical branches; the happy path must be real.
+- Each subsequent task either adds a new slice OR refines an existing slice (validation, error states, edge cases).
+- The phase goal is framed as a user story: "**As a** [user], **I want to** [do X], **so that** [Y]."
+
+## Task Order Pattern
+
+For a feature `F`:
+
+1. **Failing end-to-end test** for the happy path of `F`.
+2. **Thinnest viable slice** — UI form → API endpoint → DB read/write — that makes the test pass. Hard-coded values, missing validation, no error states are fine here.
+3. **Real data layer** — replace any stubs from Task 2 with real queries.
+4. **Validation + error states** — invalid input, network failure, empty states.
+5. **Production polish** — loading indicators, edge cases, accessibility checks.
+
+Tasks 3-5 are not always all needed; gate by the phase's acceptance criteria.
+
+## Walking Skeleton Mode (`WALKING_SKELETON=true`)
+
+When the orchestrator sets `WALKING_SKELETON=true` (Phase 1 of a new project under `--mvp`), the plan changes shape:
+
+- The "feature" is the application itself. Pick the smallest meaningful capability that proves the full stack works (e.g., "user can sign up and see their name on a dashboard").
+- The plan **must include**:
+  - Project scaffold (framework init, routing, build, lint)
+  - One real DB read/write
+  - One real UI interaction wired to the API
+  - Deployment to a dev environment (or a documented local-run command that exercises the full stack)
+- The plan **must produce** `SKELETON.md` in the phase directory alongside `PLAN.md`. Use the template at `@~/.claude/get-shit-done/references/skeleton-template.md`. `SKELETON.md` records the architectural decisions that subsequent phases will build on (chosen framework, DB, deployment target, auth approach, directory layout).
+
+`SKELETON.md` is the architectural backbone for every later vertical slice; treat it as a contract, not a scratchpad.
+
+## Anti-Patterns to Reject
+
+- **Layer cake disguised as slices.** Three "vertical" tasks where Task 1 is "all the schemas", Task 2 is "all the endpoints", Task 3 is "all the UI" — that is horizontal planning with new labels. Reject.
+- **Skeleton bloat.** Walking Skeleton is the *thinnest* working stack, not "Phase 1 of a normal app." If Skeleton has more than ~5 tasks, you are not skeletonizing.
+- **Premature SPIDR splitting.** SPIDR splitting is the `mvp-phase` command's job (Phase 2 of the PRD), not the planner's. If the phase scope feels too large, surface it via the verification loop, do not split silently.
+
+## Acceptance Test for Your Plan
+
+Before emitting the plan, ask: **after Task N completes, can a real user *do* something they could not do after Task N-1?** If the answer is "no, but the foundation is laid", you have a horizontal task disguised as a slice. Restructure.

package/get-shit-done/references/planner-reviews.md

@@ -0,0 +1,39 @@
+# Reviews Mode — Planner Reference
+
+Triggered when orchestrator sets Mode to `reviews`. Replanning from scratch with REVIEWS.md feedback as additional context.
+
+**Mindset:** Fresh planner with review insights — not a surgeon making patches, but an architect who has read peer critiques.
+
+### Step 1: Load REVIEWS.md
+Read the reviews file from `<files_to_read>`. Parse:
+- Per-reviewer feedback (strengths, concerns, suggestions)
+- Consensus Summary (agreed concerns = highest priority to address)
+- Divergent Views (investigate, make a judgment call)
+
+### Step 2: Categorize Feedback
+Group review feedback into:
+- **Must address**: HIGH severity consensus concerns
+- **Should address**: MEDIUM severity concerns from 2+ reviewers
+- **Consider**: Individual reviewer suggestions, LOW severity items
+
+### Step 3: Plan Fresh with Review Context
+Create new plans following the standard planning process, but with review feedback as additional constraints:
+- Each HIGH severity consensus concern MUST have a task that addresses it
+- MEDIUM concerns should be addressed where feasible without over-engineering
+- Note in task actions: "Addresses review concern: {concern}" for traceability
+
+### Step 4: Return
+Use standard PLANNING COMPLETE return format, adding a reviews section:
+
+```markdown
+### Review Feedback Addressed
+
+| Concern | Severity | How Addressed |
+|---------|----------|---------------|
+| {concern} | HIGH | Plan {N}, Task {M}: {how} |
+
+### Review Feedback Deferred
+| Concern | Reason |
+|---------|--------|
+| {concern} | {why — out of scope, disagree, etc.} |
+```

package/get-shit-done/references/planner-revision.md

@@ -0,0 +1,87 @@
+# Revision Mode — Planner Reference
+
+Triggered when orchestrator provides `<revision_context>` with checker issues. NOT starting fresh — making targeted updates to existing plans.
+
+**Mindset:** Surgeon, not architect. Minimal changes for specific issues.
+
+### Step 1: Load Existing Plans
+
+```bash
+cat .planning/phases/$PHASE-*/$PHASE-*-PLAN.md
+```
+
+Build mental model of current plan structure, existing tasks, must_haves.
+
+### Step 2: Parse Checker Issues
+
+Issues come in structured format:
+
+```yaml
+issues:
+  - plan: "16-01"
+    dimension: "task_completeness"
+    severity: "blocker"
+    description: "Task 2 missing <verify> element"
+    fix_hint: "Add verification command for build output"
+```
+
+Group by plan, dimension, severity.
+
+### Step 3: Revision Strategy
+
+| Dimension | Strategy |
+|-----------|----------|
+| requirement_coverage | Add task(s) for missing requirement |
+| task_completeness | Add missing elements to existing task |
+| dependency_correctness | Fix depends_on, recompute waves |
+| key_links_planned | Add wiring task or update action |
+| scope_sanity | Split into multiple plans |
+| must_haves_derivation | Derive and add must_haves to frontmatter |
+
+### Step 4: Make Targeted Updates
+
+**DO:** Edit specific flagged sections, preserve working parts, update waves if dependencies change.
+
+**DO NOT:** Rewrite entire plans for minor issues, add unnecessary tasks, break existing working plans.
+
+### Step 5: Validate Changes
+
+- [ ] All flagged issues addressed
+- [ ] No new issues introduced
+- [ ] Wave numbers still valid
+- [ ] Dependencies still correct
+- [ ] Files on disk updated
+
+### Step 6: Commit
+
+```bash
+gsd-tools query commit "fix($PHASE): revise plans based on checker feedback" --files .planning/phases/$PHASE-*/$PHASE-*-PLAN.md
+```
+
+### Step 7: Return Revision Summary
+
+```markdown
+## REVISION COMPLETE
+
+**Issues addressed:** {N}/{M}
+
+### Changes Made
+
+| Plan | Change | Issue Addressed |
+|------|--------|-----------------|
+| 16-01 | Added <verify> to Task 2 | task_completeness |
+| 16-02 | Added logout task | requirement_coverage (AUTH-02) |
+
+### Files Updated
+
+- .planning/phases/16-xxx/16-01-PLAN.md
+- .planning/phases/16-xxx/16-02-PLAN.md
+
+{If any issues NOT addressed:}
+
+### Unaddressed Issues
+
+| Issue | Reason |
+|-------|--------|
+| {issue} | {why - needs user input, architectural change, etc.} |
+```

package/get-shit-done/references/planner-source-audit.md

@@ -0,0 +1,73 @@
+# Planner Source Audit & Authority Limits
+
+Reference for `agents/gsd-planner.md` — extended rules for multi-source coverage audits and planner authority constraints.
+
+## Multi-Source Coverage Audit Format
+
+Before finalizing plans, produce a **source audit** covering ALL four artifact types:
+
+```
+SOURCE    | ID      | Feature/Requirement          | Plan  | Status    | Notes
+--------- | ------- | ---------------------------- | ----- | --------- | ------
+GOAL      | —       | {phase goal from ROADMAP.md}  | 01-03 | COVERED   |
+REQ       | REQ-14  | OAuth login with Google + GH | 02    | COVERED   |
+REQ       | REQ-22  | Email verification flow      | 03    | COVERED   |
+RESEARCH  | —       | Rate limiting on auth routes | 01    | COVERED   |
+RESEARCH  | —       | Refresh token rotation       | NONE  | ⚠ MISSING | No plan covers this
+CONTEXT   | D-01    | Use jose library for JWT     | 02    | COVERED   |
+CONTEXT   | D-04    | 15min access / 7day refresh  | 02    | COVERED   |
+```
+
+### Four Source Types
+
+1. **GOAL** — The `goal:` field from ROADMAP.md for this phase. The primary success condition.
+2. **REQ** — Every REQ-ID in `phase_req_ids`. Cross-reference REQUIREMENTS.md for descriptions.
+3. **RESEARCH** — Technical approaches, discovered constraints, and features identified in RESEARCH.md. Exclude items explicitly marked "out of scope" or "future work" by the researcher.
+4. **CONTEXT** — Every D-XX decision from CONTEXT.md `<decisions>` section.
+
+### What is NOT a Gap
+
+Do not flag these as MISSING:
+- Items in `## Deferred Ideas` in CONTEXT.md — developer chose to defer these
+- Items scoped to a different phase via `phase_req_ids` — not assigned to this phase
+- Items in RESEARCH.md explicitly marked "out of scope" or "future work" by the researcher
+
+### Handling MISSING Items
+
+If ANY row is `⚠ MISSING`, do NOT finalize the plan set silently. Return to the orchestrator:
+
+```
+## ⚠ Source Audit: Unplanned Items Found
+
+The following items from source artifacts have no corresponding plan:
+
+1. **{SOURCE}: {item description}** (from {artifact file}, section "{section}")
+   - {why this was identified as required}
+
+   Options:
+   A) Add a plan to cover this item
+   B) Split phase: move to a sub-phase
+   C) Defer explicitly: add to backlog with developer confirmation
+
+   → Awaiting developer decision before finalizing plan set.
+```
+
+If ALL rows are COVERED → return `## PLANNING COMPLETE` as normal.
+
+---
+
+## Authority Limits — Constraint Examples
+
+The planner's only legitimate reasons to split or flag a feature are **constraints**, not judgments about difficulty:
+
+**Valid (constraints):**
+- ✓ "This task touches 9 files and would consume ~45% context — split into two tasks"
+- ✓ "No API key or endpoint is defined in any source artifact — need developer input"
+- ✓ "This feature depends on the auth system built in Phase 03, which is not yet complete"
+
+**Invalid (difficulty judgments):**
+- ✗ "This is complex and would be difficult to implement correctly"
+- ✗ "Integrating with an external service could take a long time"
+- ✗ "This is a challenging feature that might be better left to a future phase"
+
+If a feature has none of the three legitimate constraints (context cost, missing information, dependency conflict), it gets planned. Period.