@therocketcode/gsd-core 1.4.0

package/gsd-core/references/doc-conflict-engine.md

@@ -0,0 +1,91 @@
+# Doc Conflict Engine
+
+Shared conflict-detection contract for workflows that ingest external content into `.planning/` (e.g., `/gsd:import`, `/gsd:ingest-docs`). Defines the report format, severity semantics, and safety-gate behavior. The specific checks that populate each severity bucket are workflow-specific and defined by the calling workflow.
+
+---
+
+## Severity Semantics
+
+- **[BLOCKER]** — Unsafe to proceed. The workflow MUST exit without writing any destination files. Used for contradictions of locked decisions, missing prerequisites, and impossible targets.
+- **[WARNING]** — Ambiguous or partially overlapping. The workflow MUST surface the warning and obtain explicit user approval before writing. Never auto-approve.
+- **[INFO]** — Informational only. No gate; no user prompt required. Included in the report for transparency.
+
+---
+
+## Report Format
+
+Plain-text, never markdown tables (no `|---|`). The report is rendered to the user verbatim.
+
+```
+## Conflict Detection Report
+
+### BLOCKERS ({N})
+
+[BLOCKER] {Short title}
+  Found: {what the incoming content says}
+  Expected: {what existing project context requires}
+  → {Specific action to resolve}
+
+### WARNINGS ({N})
+
+[WARNING] {Short title}
+  Found: {what was detected}
+  Impact: {what could go wrong}
+  → {Suggested action}
+
+### INFO ({N})
+
+[INFO] {Short title}
+  Note: {relevant information}
+```
+
+Every entry requires `Found:` plus one of `Expected:`/`Impact:`/`Note:` plus (for BLOCKER/WARNING) a `→` remediation line.
+
+---
+
+## Safety Gate
+
+**If any [BLOCKER] exists:**
+
+Display:
+```
+GSD > BLOCKED: {N} blockers must be resolved before {operation} can proceed.
+```
+
+Exit WITHOUT writing any destination files. The gate must hold regardless of WARNING/INFO counts.
+
+**If only WARNINGS and/or INFO (no blockers):**
+
+Render the full report, then prompt for approval via the `approve-revise-abort` or `yes-no` pattern from `references/gate-prompts.md`. Respect text mode (see the workflow's own text-mode handling). If the user aborts, exit cleanly with a cancellation message.
+
+**If the report is empty (no entries in any bucket):**
+
+Proceed silently or display `GSD > No conflicts detected.` Either is acceptable; workflows choose based on verbosity context.
+
+---
+
+## Workflow Responsibilities
+
+Each workflow that consumes this contract must define:
+
+1. **Its own check list per bucket** — which conditions are BLOCKER vs WARNING vs INFO. These are domain-specific (plan ingestion checks are not doc ingestion checks).
+2. **The loaded context** — what it reads (ROADMAP.md, PROJECT.md, REQUIREMENTS.md, CONTEXT.md, intel files) before running checks.
+3. **The operation noun** — substituted into the BLOCKED banner (`import`, `ingest`, etc.).
+
+The workflow MUST NOT:
+
+- Introduce new severity levels beyond BLOCKER/WARNING/INFO
+- Render the report as a markdown table
+- Write any destination file when BLOCKERs exist
+- Auto-approve past WARNINGs without user input
+
+---
+
+## Anti-Patterns
+
+Do NOT:
+
+- Use markdown tables (`|---|`) in the conflict report — use plain-text labels as shown above
+- Bypass the safety gate when BLOCKERs exist — no exceptions for "minor" blockers
+- Fold WARNINGs into INFO to skip the approval prompt — if user input is needed, it is a WARNING
+- Re-invent severity labels per workflow — the three-level taxonomy is fixed

package/gsd-core/references/domain-modeling.md

@@ -0,0 +1,80 @@
+# Domain Modeling — Lightweight DDD for Greenfield
+
+Reference for the `/gsd:model-domain` workflow. This skill does **strategic** Domain-Driven Design only: shared language + subdomain distillation (+ optional bounded contexts). It deliberately does **not** prescribe architecture — that is `/gsd:recommend-architecture`'s job, which consumes this model.
+
+## Core principle: separate strategic from tactical DDD
+
+DDD splits into two halves that are **not equally worth it**:
+
+- **Strategic DDD** — ubiquitous language, subdomain distillation (core/supporting/generic), bounded contexts. **Cheap and broadly valuable**, even for simple apps. This is what `model-domain` captures.
+- **Tactical DDD** — aggregates, value objects, domain events, rich domain model, hexagonal layering. **Conditional**: only worth it inside a core domain that is genuinely complex. Deciding this belongs to `recommend-architecture`, not here.
+
+> The most common real-world failure is "tactical patterns without strategy" (DDD-Lite): copying aggregates/repositories everywhere while skipping the language and distillation work that actually creates value. `model-domain` exists to do the strategic half well so tactical effort later lands only where it pays.
+
+## 1. Ubiquitous language
+
+A shared glossary the whole team (business, product, engineering) uses consistently. Misaligned vocabulary is a compounding source of rework.
+
+**How to elicit:**
+- Listen for repeated nouns/verbs in PROJECT.md and REQUIREMENTS.md; reflect them back.
+- Ask "What would you *call* this?" — capture the team's word, not the textbook word.
+- Surface conflicts: "When you say *X*, do you mean A or B?" Polysemes (one word, two meanings) are a signal of a bounded-context boundary.
+- Iterate to ~8–15 core terms, each with a one-line definition + usage context.
+
+Ubiquitous language is cheap enough to keep even in simple apps. The *modeling depth* beyond it should scale with whether the app actually has domain logic.
+
+## 2. Subdomain distillation (the pivotal step)
+
+Classify each area of the system. This is the single highest-leverage output — it tells you where to invest.
+
+| Type | Definition | What to do | Examples |
+|---|---|---|---|
+| **Core** | Differentiating **and** complex enough to be worth owning. Your competitive advantage. | Build in-house, best people, invest. Candidate for tactical DDD later. | Search ranking (a search engine), fraud detection (a payments product), matching (a marketplace) |
+| **Supporting** | Necessary, not differentiating. Tightly coupled to the core. | "Good enough," build simply or buy-and-extend. | Onboarding flows, internal admin, notifications |
+| **Generic** | Commodity every business needs; no edge. | Buy / off-the-shelf / library. | Auth, billing, email, logging, tax calculation |
+
+### Three nuances that prevent misclassification
+
+1. **Core = differentiating AND complex — not just complex (and not merely *critical* or *regulated*).** A complex-, critical-, or regulated-but-*generic* subdomain (tax, identity/auth, encryption, compliance) is a **buy**, not a build. Difficulty, security-criticality, and regulatory burden do not make something core — only competitive differentiation does. Don't invest core-grade effort there.
+2. **Generic ≠ low quality.** "Generic" means *not differentiating*, not *low effort*. A battle-tested auth library is high-quality and generic.
+3. **Watch for CRUD that will grow business rules.** The dangerous case is an app that "starts as a UI over the database, then evolves into real domain logic." Before classifying something Generic/CRUD, probe future features: *will this accumulate invariants and rules?* If yes, treat it as (emerging) core/supporting, not generic.
+
+### Anti-sprawl rule
+
+Start with **one** core domain and **one** bounded context. Additional contexts reveal themselves if they exist. Don't hunt for subdomains for the sake of it.
+
+## 3. Bounded contexts (optional — via lightweight event storming)
+
+Only when the domain is non-trivial. A **Big-Picture event storming** pass surfaces candidate context boundaries cheaply:
+
+1. List the major **domain events** ("Order Placed", "Payment Captured", "Shipment Dispatched") on a timeline.
+2. For each: *who triggers it? who reacts? what decision follows?*
+3. Group events by actor/responsibility → each cluster is a candidate **bounded context**.
+
+Boundaries often fall where the **language changes** (the same word means different things) or where the **rate of change** differs. If boundaries are unclear, **defer** them — say so explicitly and let planning refine them. Do not run design-level (aggregate-level) event storming here; that is tactical and belongs to a core subdomain you've already identified.
+
+## What this skill does NOT do
+
+- **No architecture prescription.** Whether the project needs hexagonal, CQRS, a modular monolith, etc. is decided by `/gsd:recommend-architecture`, which reads `DOMAIN-MODEL.md`. Keep this artifact about the *problem*, not the *solution*.
+- **No tactical modeling.** No aggregates, no class design. Strategic only.
+
+## Handoff (why this artifact matters downstream)
+
+`DOMAIN-MODEL.md` is the single complexity assessment that parameterizes the rest of the project:
+
+- → **`recommend-architecture`**: subdomain complexity drives the domain-logic axis (Transaction Script ↔ Domain Model ↔ Hexagonal). Core+complex ⇒ richer; supporting/generic ⇒ simple.
+- → **`testing-strategy`**: where the behavior lives drives test shape — a rich core wants more unit tests; CRUD-over-DB edges want integration tests.
+
+## When to run / when to skip
+
+**Run** after `/gsd:new-project`, before planning, when: the domain has real business rules, multiple stakeholder vocabularies, distinct business areas, or a genuine competitive core.
+
+**Skip / keep minimal** for: a truly simple CRUD app over a stable, obvious domain; a throwaway prototype (formalize after the MVP validates direction). Even then, capturing the ubiquitous language is cheap and usually worth it.
+
+## Anti-patterns
+
+- **Tactical without strategy (DDD-Lite):** aggregates everywhere, no distillation. The thing this skill prevents.
+- **Subdomain sprawl:** inventing contexts that don't exist. Start with one.
+- **Treating language as optional:** inconsistent terms → compounding ambiguity.
+- **Confusing complex with core:** a hard-but-commodity area is a buy, not your advantage.
+- **Prescribing architecture here:** keep it about the domain; hand the decision to `recommend-architecture`.

package/gsd-core/references/domain-probes.md

@@ -0,0 +1,125 @@
+# Domain-Aware Probing Patterns
+
+Shared reference for `/gsd-begin`, `/gsd:discuss-phase`, and domain exploration workflows.
+
+When the user mentions a technology area, use these probes to ask insightful follow-up questions. Don't run through them as a checklist -- pick the 2-3 most relevant based on context. The goal is to surface hidden assumptions and trade-offs the user may not have considered yet.
+
+---
+
+## Authentication
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "login" or "auth" | OAuth (which providers?), JWT, or session-based? Do you need social login or just email/password? |
+| "users" or "accounts" | MFA required? Password reset flow? Email verification? |
+| "sessions" | Session duration and refresh strategy? Server-side sessions or stateless tokens? |
+| "roles" or "permissions" | RBAC, ABAC, or simple role checks? How many distinct roles? |
+| "API keys" | Key rotation strategy? Scoped permissions per key? Rate limiting per key? |
+
+---
+
+## Real-Time Updates
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "real-time" or "live updates" | WebSockets, SSE, or polling? What specifically needs to be real-time vs. eventual? |
+| "notifications" | Push notifications (browser/mobile), in-app only, or both? Persistence and read receipts? |
+| "collaboration" or "multiplayer" | Conflict resolution strategy? Operational transforms or CRDTs? Expected concurrent users? |
+| "chat" or "messaging" | Message history and search? Typing indicators? Read receipts? |
+| "streaming" | Reconnection strategy? What happens when the connection drops -- queue or discard? |
+
+---
+
+## Dashboard
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "dashboard" | What data sources feed it? How many distinct views? |
+| "charts" or "graphs" | Interactive or static? Drill-down capability? Export to CSV/PDF? |
+| "metrics" or "KPIs" | Refresh strategy -- real-time, periodic polling, or on-demand? Acceptable staleness? |
+| "admin panel" | Role-based visibility? Which actions beyond viewing (edit, delete, approve)? |
+| "mobile" or "responsive" | Simplified mobile view or full parity? Touch interactions for charts? |
+
+---
+
+## API Design
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "API" | REST, GraphQL, or RPC-style? Internal only or public-facing? |
+| "endpoints" or "routes" | Versioning strategy (URL path, header, query param)? Breaking change policy? |
+| "pagination" | Cursor-based or offset? Expected result set sizes? Stable ordering guarantee? |
+| "rate limiting" | Per-user, per-IP, or per-API-key? Burst allowance? How to communicate limits to clients? |
+| "errors" | Structured error format? Error codes vs. messages? How much detail in production errors? |
+
+---
+
+## Database
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "database" or "storage" | SQL or NoSQL? What drives the choice -- relational integrity, flexibility, scale? |
+| "ORM" or "queries" | ORM (which one?) or raw queries? Query builder as middle ground? |
+| "migrations" | Migration tool? Rollback strategy? How do you handle data migrations vs. schema migrations? |
+| "seeding" or "test data" | Seed data for development? Realistic fake data or minimal fixtures? |
+| "scale" or "performance" | Read/write ratio? Read replicas? Connection pooling strategy? |
+
+---
+
+## Search
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "search" | Full-text or exact match? Dedicated search engine (Elasticsearch, Meilisearch) or database-level? |
+| "filtering" or "facets" | Faceted filtering? How many filter dimensions? Combined filters (AND/OR)? |
+| "autocomplete" or "typeahead" | Debounce strategy? Minimum character threshold? Result ranking? |
+| "indexing" | Index size and update frequency? Real-time indexing or batch? Acceptable index lag? |
+| "fuzzy" or "typo tolerance" | Fuzzy matching? Synonym support? Language-specific stemming? |
+
+---
+
+## File Upload/Storage
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "upload" or "file upload" | Local filesystem or cloud (S3, GCS, Azure Blob)? Direct upload or through server? |
+| "images" or "media" | Processing pipeline -- resize, compress, thumbnail generation? Format conversion? |
+| "size limits" | Max file size? Max total storage per user? What happens when limits are hit? |
+| "CDN" | CDN for delivery? Cache invalidation for updated files? Signed URLs for access control? |
+| "documents" or "attachments" | Virus scanning? Preview generation? Versioning of uploaded files? |
+
+---
+
+## Caching
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "caching" or "performance" | Where to cache -- browser, CDN, application layer, database query cache? |
+| "invalidation" | Invalidation strategy -- TTL, event-driven, or manual? Cache-aside vs. write-through? |
+| "stale data" | Acceptable staleness window? Stale-while-revalidate pattern? |
+| "Redis" or "Memcached" | Cache topology -- single node or clustered? Persistence needed or pure cache? |
+| "CDN" or "edge" | Edge caching for static assets? Dynamic content at the edge? Cache key strategy? |
+
+---
+
+## Testing
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "testing" or "tests" | Unit, integration, and E2E balance? Where do you invest most testing effort? |
+| "mocking" or "stubs" | Mock external services or use test containers? Database mocking strategy? |
+| "CI" or "pipeline" | Tests in CI? Parallel test execution? Test-on-PR or test-on-push? |
+| "coverage" | Coverage targets? Coverage as gate or advisory? Which metrics (line, branch, function)? |
+| "E2E" or "browser testing" | Playwright, Cypress, or other? Headed vs. headless? Visual regression testing? |
+
+---
+
+## Deployment
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "deploy" or "hosting" | Container, serverless, or traditional VM/VPS? Managed platform (Vercel, Railway) or self-hosted? |
+| "CI/CD" or "pipeline" | GitHub Actions, GitLab CI, or other? Deploy on merge to main or manual trigger? |
+| "environments" | How many environments (dev, staging, prod)? Environment parity strategy? |
+| "rollback" | Rollback strategy? Blue-green, canary, or instant rollback? Database rollback considerations? |
+| "secrets" or "config" | Secret management -- env vars, vault, or platform-native? Per-environment config strategy? |

package/gsd-core/references/e2e-tiering.md

@@ -0,0 +1,35 @@
+# E2E Test Tiering — Persistent Smoke vs Transient
+
+How-to reference for structuring end-to-end tests so CI stays fast and the suite stays maintainable. Read when adding e2e tests. Pairs with `test-strategy.md`.
+
+## The tiers
+
+- **Persistent (in CI, every PR):** a small **smoke / critical-user-journey** suite — auth, payment, core nav. <5 min feedback. An "ultra-priority" set checking only vital flows validates build stability.
+- **Deeper regression:** business-critical flows on staging / release candidates / scheduled runs — *not* every PR.
+- **Transient:** throwaway e2e to validate a freshly-built flow during the dev loop; **not** kept in CI; demote to integration once the behavior is covered more cheaply.
+
+## Keep e2e lean
+
+- E2E is the most expensive layer to run and maintain. A portfolio of **50–200 well-chosen** e2e tests covering critical workflows beats 1,000 redundant ones.
+- Push edge cases **down** to unit/integration (test each behavior once, at the cheapest level — see `test-strategy.md`). E2E covers true end-to-end critical journeys only.
+- The **ice-cream cone** (mostly e2e) is the anti-pattern.
+
+## Ephemeral environments
+
+Spin up a per-PR environment, run the suite, tear it down on merge (standard CI/CD). Add an `if: always()` cleanup so resources are freed even on failure.
+
+## CI structure
+
+```
+on PR:       smoke suite          (persistent, <5 min, every PR)
+on staging:  business-critical regression
+on release:  broad coverage / scheduled
+```
+
+## Anti-patterns
+
+- E2E for every feature/edge case (ice-cream cone; slow, flaky, costly).
+- A fat e2e suite as the primary safety net instead of integration/unit.
+- Keeping throwaway dev-loop e2e in CI.
+
+*Sources: Ranger E2E-in-CI/CD guide; Google Testing Blog; "Software Engineering at Google" (testing).*

package/gsd-core/references/execute-mvp-tdd.md

@@ -0,0 +1,81 @@
+# Execute-Phase — MVP+TDD Gate (Runtime Enforcement)
+
+> Loaded by `execute-phase` workflow and `gsd-executor` agent only when **both** `MVP_MODE=true` AND `TDD_MODE=true` for the phase. Defines the runtime gate that blocks behavior-adding tasks until a failing-test commit exists.
+
+## When this gate fires
+
+- `MVP_MODE` is `true` (resolved from CLI flag → ROADMAP `**Mode:**` field → config; see `references/planner-mvp-mode.md`).
+- `TDD_MODE` is `true` (resolved from `--tdd` flag → `workflow.tdd_mode` config).
+- The current task being executed has `tdd="true"` in its `<task>` frontmatter (set by the planner per Phase 1).
+- The task's `<behavior>` block lists at least one expected behavior.
+
+If any of these is false, the gate is inactive — execution proceeds normally.
+
+## What the gate checks
+
+For each task gated by MVP+TDD, the executor MUST verify (before running the implementation step):
+
+1. **A failing-test commit exists.** Search git log on the current branch for a commit matching `test({phase}-{plan})` whose subject mentions the same plan as the current task. The commit must touch a test file (`*.test.*`, `*.spec.*`, `tests/**`).
+2. **The test was actually red.** The commit message body or the executor's recent shell history must show the test failed when first run. Acceptable evidence:
+   - Commit message contains `RED:` prefix or `(RED)` tag
+   - Recent terminal output shows `FAIL` or non-zero exit on the new test before any implementation commit
+3. **No implementation commit yet.** No `feat({phase}-{plan})` commit may exist for the same plan ID before the failing-test commit.
+
+If any check fails, the gate trips.
+
+## What "behavior-adding task" means
+
+A task is behavior-adding when:
+- Its frontmatter has `tdd="true"` AND
+- Its `<behavior>` block names at least one user-visible outcome (not a config-only or doc-only task) AND
+- Its `<files>` list includes at least one source file (not exclusively docs/tests/config files such as `*.md`, `*.json`, `*.test.*`, `*.spec.*`, `*.yml`, `*.yaml`, `*.toml`, `*.ini`, `.env*`)
+
+Pure documentation, configuration, or test-only tasks are skipped by this gate even when both modes are active.
+
+## What happens when the gate trips
+
+The executor MUST:
+
+1. Halt before running the task's implementation step.
+2. Emit a structured halt report:
+
+   ```
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    MVP+TDD GATE TRIPPED — Plan {plan_id}, Task {task_id}
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   Reason: {missing_red_commit | red_commit_not_failing | feat_before_test}
+
+   Behavior expected to be tested:
+   - {first behavior bullet}
+
+   Required next step:
+   1. Write a failing test for the behavior above.
+   2. Commit it as: test({phase}-{plan}): {short description}
+   3. Re-run /gsd execute-phase
+   ```
+
+3. Exit the current execution wave cleanly. Do NOT roll back any prior commits in the same wave.
+4. Update `STATE.md` with `last_gate_trip: {plan_id}/{task_id}` so the user can resume after writing the test.
+
+## Escalation: end-of-phase TDD review under MVP+TDD
+
+The existing end-of-phase TDD review (in `workflows/execute-phase.md`'s `tdd_review_checkpoint` step) is normally **advisory** — it surfaces gate violations but does not block phase completion.
+
+Under MVP+TDD, escalate this to **blocking**:
+- If any TDD plan is missing a RED or GREEN commit, the executor MUST refuse to mark the phase complete.
+- The user is shown the same review table, but the verdict line reads:
+  > "Phase blocked: {N} TDD plan(s) violate the RED→GREEN gate sequence under MVP+TDD. Resolve and re-run /gsd execute-phase, or override with `/gsd execute-phase {phase} --force-mvp-gate` to ship anyway."
+
+The `--force-mvp-gate` flag is documented but not introduced by this plan — it is the escape hatch the spec mentions; if the user later builds it, the workflow already references the contract.
+
+## What this gate does NOT do
+
+- It does not enforce REFACTOR commits. REFACTOR remains optional (per `references/tdd.md`).
+- It does not check test quality (the test could be trivially passing). That's the planner's job.
+- It does not run tests. The executor only inspects git log + file system. Running tests is the implementation step's job.
+- It does not gate config-only or doc-only tasks (see "behavior-adding task" definition).
+
+## Compatibility with existing TDD discipline
+
+This gate is additive to `references/tdd.md`. Tasks not under MVP+TDD continue to use the existing advisory TDD discipline (RED/GREEN/REFACTOR commits with end-of-phase review checkpoint). Only the runtime gate and the blocking escalation are new.

package/gsd-core/references/executor-examples.md

@@ -0,0 +1,110 @@
+# Executor Extended Examples
+
+> Reference file for gsd-executor agent. Loaded on-demand via `@` reference.
+> For sub-200K context windows, this content is stripped from the agent prompt and available here for on-demand loading.
+
+## Deviation Rule Examples
+
+### Rule 1 — Auto-fix bugs
+
+**Examples of Rule 1 triggers:**
+- Wrong queries returning incorrect data
+- Logic errors in conditionals
+- Type errors and type mismatches
+- Null pointer exceptions / undefined access
+- Broken validation (accepts invalid input)
+- Security vulnerabilities (XSS, SQL injection)
+- Race conditions in async code
+- Memory leaks from uncleaned resources
+
+### Rule 2 — Auto-add missing critical functionality
+
+**Examples of Rule 2 triggers:**
+- Missing error handling (unhandled promise rejections, no try/catch on I/O)
+- No input validation on user-facing endpoints
+- Missing null checks before property access
+- No auth on protected routes
+- Missing authorization checks (user can access other users' data)
+- No CSRF/CORS configuration
+- No rate limiting on public endpoints
+- Missing DB indexes on frequently queried columns
+- No error logging (failures silently swallowed)
+
+### Rule 3 — Auto-fix blocking issues
+
+**Examples of Rule 3 triggers:**
+- Missing dependency not in package.json
+- Wrong types preventing compilation
+- Broken imports (wrong path, wrong export name)
+- Missing env var required at runtime
+- DB connection error (wrong URL, missing credentials)
+- Build config error (wrong entry point, missing loader)
+- Missing referenced file (import points to non-existent module)
+- Circular dependency preventing module load
+
+### Rule 4 — Ask about architectural changes
+
+**Examples of Rule 4 triggers:**
+- New DB table (not just adding a column)
+- Major schema changes (renaming tables, changing relationships)
+- New service layer (adding a queue, cache, or message bus)
+- Switching libraries/frameworks (e.g., replacing Express with Fastify)
+- Changing auth approach (switching from session to JWT)
+- New infrastructure (adding Redis, S3, etc.)
+- Breaking API changes (removing or renaming endpoints)
+
+## Edge Case Decision Guide
+
+| Scenario | Rule | Rationale |
+|----------|------|-----------|
+| Missing validation on input | Rule 2 | Security requirement |
+| Crashes on null input | Rule 1 | Bug — incorrect behavior |
+| Need new database table | Rule 4 | Architectural decision |
+| Need new column on existing table | Rule 1 or 2 | Depends on context |
+| Pre-existing linting warnings | Out of scope | Not caused by current task |
+| Unrelated test failures | Out of scope | Not caused by current task |
+
+**Decision heuristic:** "Does this affect correctness, security, or ability to complete the current task?"
+- YES → Rules 1-3 (fix automatically)
+- MAYBE → Rule 4 (ask the user)
+- NO → Out of scope (log to deferred-items.md)
+
+## Checkpoint Examples
+
+### Good checkpoint placement
+
+```xml
+<!-- Automate everything, then verify at the end -->
+<task type="auto">Create database schema</task>
+<task type="auto">Create API endpoints</task>
+<task type="auto">Create UI components</task>
+<task type="checkpoint:human-verify">
+  <what-built>Complete auth flow (schema + API + UI)</what-built>
+  <how-to-verify>
+    1. Visit http://localhost:3000/register
+    2. Create account with test@example.com
+    3. Log in with those credentials
+    4. Verify dashboard loads with user name
+  </how-to-verify>
+</task>
+```
+
+### Bad checkpoint placement
+
+```xml
+<!-- Too many checkpoints — causes verification fatigue -->
+<task type="auto">Create schema</task>
+<task type="checkpoint:human-verify">Check schema</task>
+<task type="auto">Create API</task>
+<task type="checkpoint:human-verify">Check API</task>
+<task type="auto">Create UI</task>
+<task type="checkpoint:human-verify">Check UI</task>
+```
+
+### Auth gate handling
+
+When an auth error occurs during `type="auto"` execution:
+1. Recognize it as an auth gate (not a bug) — indicators: "Not authenticated", "401", "403", "Please run X login"
+2. STOP the current task
+3. Return a `checkpoint:human-action` with exact auth steps
+4. In SUMMARY.md, document auth gates as normal flow, not deviations

package/gsd-core/references/few-shot-examples/plan-checker.md

@@ -0,0 +1,73 @@
+---
+component: plan-checker
+version: 1
+last_calibrated: 2026-03-24
+---
+
+# Plan-Checker Few-Shot Examples
+
+## Positive Examples
+
+### Example 1: BLOCKER flagged for vague task action missing file and function names
+
+**Input:** Plan task with action: "Implement the authentication feature for the API routes."
+
+**Output:**
+
+> ```yaml
+> issues:
+>   - dimension: task_completeness
+>     severity: BLOCKER
+>     finding: "Task T1 action says 'implement the authentication feature' without naming target files, functions to create, or middleware to apply. Executor cannot determine what to build."
+>     affected_field: "<action>"
+>     suggested_fix: "Specify: create authMiddleware in src/middleware/auth.js, apply to routes in src/routes/api.js lines 12-45, verify with integration test"
+> ```
+
+**Why this is good:** The checker cited the specific dimension (task_completeness), quoted the problematic text, explained why it is a blocker (executor cannot determine what to build), and gave a concrete fix with file paths and function names. The finding is actionable -- the planner knows exactly what to add.
+
+### Example 2: BLOCKER for same-wave file conflict between two plans
+
+**Input:** Two plans in wave 1 -- Plan 01 modifies `gsd-core/workflows/execute-phase.md`, Plan 02 also modifies `gsd-core/workflows/execute-phase.md`. No `depends_on` declared.
+
+**Output:**
+
+> ```yaml
+> issues:
+>   - dimension: dependency_correctness
+>     severity: BLOCKER
+>     finding: "Plans 01 and 02 both modify gsd-core/workflows/execute-phase.md in wave 1 with no depends_on relationship. Concurrent execution will cause merge conflicts or lost changes."
+>     affected_field: "files_modified"
+>     suggested_fix: "Either move Plan 02 to wave 2 with depends_on: ['01'] or consolidate the file changes into a single plan"
+> ```
+
+**Why this is good:** The checker identified a real structural problem -- two plans modifying the same file in the same wave without a dependency relationship. It cited dependency_correctness, named both plans, the conflicting file, and provided two alternative fixes.
+
+## Negative Examples
+
+### Example 1: All dimensions pass when verify commands are missing
+
+**Input:** Plan with 3 tasks. Task T2 has `<verify></verify>` (empty). Task T3 has `<verify>echo "done"</verify>` (trivial, cannot distinguish pass from fail).
+
+**Output:**
+
+> ## CHECK PASSED
+> Plans: 1 | Tasks: 3 | Dimensions: 10 | Issues: 0
+
+**Why this is bad:** The checker missed two violations. verification_derivation requires verify commands to be runnable and test actual output -- an empty verify block is a BLOCKER. Verify commands must distinguish pass from fail -- `echo "done"` always returns 0 regardless of implementation state. Both should have been flagged.
+
+### Example 2: False positive INFO for a correctly-sized plan
+
+**Input:** Plan with 3 tasks, 6 unique files, 1 dependency. All within limits.
+
+**Output:**
+
+> ```yaml
+> issues:
+>   - dimension: scope_sanity
+>     severity: INFO
+>     finding: "Plan has 3 tasks -- consider splitting into smaller plans for faster iteration"
+>     affected_field: "task count"
+>     suggested_fix: "Split tasks into separate plans"
+> ```
+
+**Why this is bad:** The checker flagged a non-issue. scope_sanity allows 2-3 tasks per plan -- 3 tasks is within limits. The checker applied a personal preference ("smaller is better") rather than the documented threshold. This wastes planner time on false positives and erodes trust in the checker's judgment. A correct check would produce no issue for this plan.