get-shit-done-ios 0.11.0 → 1.1.0

package/README.md

@@ -9,7 +9,7 @@
 **Solves context rot — the quality degradation that happens as Claude fills its context window.**
 
 [![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
-[![Based on GSD](https://img.shields.io/badge/Based_on-GSD_1.21.0-orange?style=for-the-badge)](https://github.com/glittercowboy/get-shit-done)
+[![Based on GSD](https://img.shields.io/badge/Based_on-GSD_1.22.4-orange?style=for-the-badge)](https://github.com/glittercowboy/get-shit-done)
 
 ```bash
 npx get-shit-done-ios@latest
@@ -515,7 +515,7 @@ You're never locked in. The system adapts.
 | `/gsd:add-todo [desc]` | Capture idea for later |
 | `/gsd:check-todos` | List pending todos |
 | `/gsd:debug [desc]` | Systematic debugging with persistent state |
-| `/gsd:quick [--full]` | Execute ad-hoc task with GSD guarantees (`--full` adds plan-checking and verification) |
+| `/gsd:quick [--discuss] [--full]` | Execute ad-hoc task with GSD guarantees (`--discuss` for pre-planning context, `--full` adds plan-checking and verification) |
 | `/gsd:health [--repair]` | Validate `.planning/` directory integrity, auto-repair with `--repair` |
 
 <sup>¹ Contributed by reddit user OracleGreyBeard</sup>
@@ -531,7 +531,7 @@ GSD stores project settings in `.planning/config.json`. Configure during `/gsd:n
 | Setting | Options | Default | What it controls |
 |---------|---------|---------|------------------|
 | `mode` | `yolo`, `interactive` | `interactive` | Auto-approve vs confirm at each step |
-| `depth` | `quick`, `standard`, `comprehensive` | `standard` | Planning thoroughness (phases × plans) |
+| `granularity` | `coarse`, `standard`, `fine` | `standard` | Planning thoroughness (phases × plans) |
 
 ### Model Profiles
 

package/agents/gsd-codebase-mapper.md

@@ -3,6 +3,14 @@ name: gsd-codebase-mapper
 description: Explores codebase and writes structured analysis documents. Spawned by map-codebase with a focus area (tech, arch, quality, concerns). Writes documents directly to reduce orchestrator context load.
 tools: Read, Bash, Grep, Glob, Write
 color: cyan
+skills:
+  - gsd-mapper-workflow
+# hooks:
+#   PostToolUse:
+#     - matcher: "Write|Edit"
+#       hooks:
+#         - type: command
+#           command: "npx eslint --fix $FILE 2>/dev/null || true"
 ---
 
 <role>
@@ -167,7 +175,7 @@ Write document(s) to `.planning/codebase/` using the templates below.
 3. If something is not found, use "Not detected" or "Not applicable"
 4. Always include file paths with backticks
 
-Use the Write tool to create each document.
+**ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
 </step>
 
 <step name="return_confirmation">

package/agents/gsd-debugger.md

@@ -3,6 +3,14 @@ name: gsd-debugger
 description: Investigates iOS/Swift/SwiftUI bugs using scientific method, manages debug sessions, handles checkpoints. Spawned by /gsd:debug orchestrator.
 tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch
 color: orange
+skills:
+  - gsd-debugger-workflow
+# hooks:
+#   PostToolUse:
+#     - matcher: "Write|Edit"
+#       hooks:
+#         - type: command
+#           command: "npx eslint --fix $FILE 2>/dev/null || true"
 ---
 
 <role>
@@ -472,6 +480,28 @@ signposter.endInterval("DatabaseQuery", state)
 - Zombie Objects — Detect messages sent to deallocated objects
 - Malloc Stack Logging — Track allocation origins
 
+### iOS Debugging Tools
+
+**Diagnostics (cheapest first):**
+- `mcp__xcode__XcodeRefreshCodeIssuesInFile` — Fast per-file compiler diagnostics (Xcode open)
+- `swift-lsp` — Type checking, find references, go-to-definition
+- `mcp__XcodeBuildMCP__build_sim` — Full build to reproduce compilation errors
+
+**Runtime debugging:**
+- `mcp__XcodeBuildMCP__launch_app_logs_sim` — Launch app with log capture
+- `mcp__XcodeBuildMCP__start_sim_log_cap` + `stop_sim_log_cap` — Runtime logs
+- `mcp__xcode__ExecuteSnippet` — Run Swift code in project context (Xcode open)
+
+**UI debugging:**
+- `mcp__XcodeBuildMCP__describe_ui` — Inspect live UI hierarchy
+- `mcp__XcodeBuildMCP__screenshot` — Capture visual state at moment of bug
+- `mcp__xcode__RenderPreview` — Check SwiftUI preview for rendering issues (Xcode open)
+
+**Code understanding:**
+- `swift-lsp` find references — Trace all usages of a type/function
+- `context7` — Latest API documentation for debugging API misuse
+- `mcp__xcode__DocumentationSearch` — Apple docs + WWDC transcripts (Xcode open)
+
 ## Comment Out Everything
 
 **When:** Many possible interactions, unclear which code causes issue.
@@ -979,6 +1009,8 @@ ls .planning/debug/*.md 2>/dev/null | grep -v resolved
 <step name="create_debug_file">
 **Create debug file IMMEDIATELY.**
 
+**ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
+
 1. Generate slug from user input (lowercase, hyphens, max 30 chars)
 2. `mkdir -p .planning/debug`
 3. Create file with initial state:
@@ -1158,6 +1190,7 @@ mv .planning/debug/{slug}.md .planning/debug/resolved/
 
 ```bash
 INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state load)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 # commit_docs is in the JSON output
 ```
 

package/agents/gsd-executor.md

@@ -3,6 +3,14 @@ name: gsd-executor
 description: Executes GSD plans with atomic commits, deviation handling, checkpoint protocols, and state management. Spawned by execute-phase orchestrator or execute-plan command.
 tools: Read, Write, Edit, Bash, Grep, Glob
 color: yellow
+skills:
+  - gsd-executor-workflow
+# hooks:
+#   PostToolUse:
+#     - matcher: "Write|Edit"
+#       hooks:
+#         - type: command
+#           command: "npx eslint --fix $FILE 2>/dev/null || true"
 ---
 
 **iOS References:**
@@ -38,6 +46,85 @@ Before executing, discover project context:
 This ensures project-specific patterns, conventions, and best practices are applied during execution.
 </project_context>
 
+## iOS Validation Ladder
+
+After implementing each change, validate using the cheapest tool first:
+
+1. **Per-file check** (after every file edit):
+   - Xcode open: `mcp__xcode__XcodeRefreshCodeIssuesInFile` — compiler errors in <2 seconds
+   - Xcode closed: `swift-lsp` diagnostics — type checking and import validation
+   - Fix ALL errors before editing the next file.
+
+2. **Full build** (after completing all edits for a plan step):
+   - `mcp__XcodeBuildMCP__build_sim` — full compilation check
+   - If Xcode open, `mcp__xcode__BuildProject` uses Xcode's build system directly
+   - Fix build errors before proceeding to next plan step.
+
+3. **Test suite** (after completing all plan steps):
+   - `mcp__XcodeBuildMCP__test_sim` — run all tests. Final gate.
+   - If Xcode open, `mcp__xcode__RunAllTests` or `RunSomeTests` for targeted testing.
+
+4. **Visual verification** (MANDATORY for any plan step that modifies SwiftUI views):
+   - Xcode open: `mcp__xcode__RenderPreview` — actual SwiftUI preview screenshot
+   - Xcode closed: `mcp__XcodeBuildMCP__build_run_sim` + `mcp__XcodeBuildMCP__screenshot`
+   - `mcp__XcodeBuildMCP__describe_ui` — verify accessibility tree contains expected elements
+   - Present screenshot to user at checkpoints for UI plans.
+
+Do NOT skip straight to full build for every edit — it's expensive. Use per-file checks first.
+Do NOT skip visual verification for UI changes — build + tests passing ≠ correct UI.
+Do NOT batch all UI fixes — implement one fix, verify visually, then proceed to the next.
+
+## API Verification Before Implementation
+
+Before writing code that uses Apple framework APIs:
+1. If the API is unfamiliar, new, or you're not 100% certain of the signature:
+   - Xcode open: `mcp__xcode__DocumentationSearch` — Apple's full docs + WWDC transcripts
+   - Xcode closed: **context7** (`resolve-library-id` → `get-library-docs`)
+2. If neither returns results, use **swift-lsp** to check if the API exists in the project's SDK.
+3. NEVER guess at API names, parameter labels, or return types.
+
+Key areas where hallucination is common:
+- SwiftUI view modifiers (names change between iOS versions)
+- SwiftData relationship macros and query predicates
+- Swift Testing macro syntax (`#expect`, `#require`, `@Test`, `@Suite`)
+- Concurrency annotations (`@MainActor`, `nonisolated`, `@Sendable`)
+- New frameworks and APIs (Liquid Glass, FoundationModels, RecognizeDocumentsRequest) — ALWAYS search before using
+
+## Scope Discipline
+
+- Limit changes to exactly what the current plan step requires. Do not refactor adjacent code, rename unrelated symbols, or "improve" code that isn't part of the task.
+- If you notice issues outside the current scope, note them in the SUMMARY.md under "Observations" — do not fix them inline.
+- Exception: If a change is required to make the plan step work, that is in scope. Document why.
+
+## SwiftUI View Requirements
+
+When creating or modifying SwiftUI views:
+- Always include a `#Preview` block at the bottom of the file (use the macro, NOT `PreviewProvider`)
+- Provide meaningful sample data in previews — not empty views
+- If the view requires a `ModelContainer`, configure one in the preview
+- When Xcode is open, use `mcp__xcode__RenderPreview` to verify the preview renders correctly
+
+**Anti-patterns to flag:** Use of `Combine` (`import Combine`, `PassthroughSubject`, `@Published` with `sink`) when Swift Concurrency alternatives exist. Prefer `AsyncSequence`, `AsyncStream`, `@Observable`, `Task`, `async/await`. Exception: extending existing Combine-based code.
+
+### UI Checkpoint Protocol
+
+When a plan with `autonomous: false` (checkpoints) involves UI modifications:
+1. Before presenting the checkpoint to the user, ALWAYS:
+   - `mcp__XcodeBuildMCP__build_run_sim` — build and launch the app
+   - `mcp__XcodeBuildMCP__screenshot` — capture the current UI state
+   - Present the screenshot alongside the checkpoint question
+2. This allows the user to verify visually without opening the Simulator themselves
+3. If Xcode is open, also use `mcp__xcode__RenderPreview` for individual view previews
+
+### UI Fix Discipline
+
+When implementing fixes from human feedback on UI issues:
+1. Implement ONE fix at a time
+2. Build + run + screenshot after each fix
+3. Present the result to the user before proceeding to the next fix
+4. Do NOT batch multiple UI fixes — compounding errors makes root cause identification harder
+5. If multiple handoff documents exist about the same issue, use ONLY the most recent one
+
 <execution_flow>
 
 <step name="load_project_state" priority="first">
@@ -45,6 +132,7 @@ Load execution context:
 
 ```bash
 INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init execute-phase "${PHASE}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
 Extract from init JSON: `executor_model`, `commit_docs`, `phase_dir`, `plans`, `incomplete_plans`.
@@ -219,13 +307,14 @@ Do NOT continue reading. Analysis without action is a stuck signal.
 </authentication_gates>
 
 <auto_mode_detection>
-Check if auto mode is active at executor start:
+Check if auto mode is active at executor start (chain flag or user preference):
 
 ```bash
+AUTO_CHAIN=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" config-get workflow._auto_chain_active 2>/dev/null || echo "false")
 AUTO_CFG=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" config-get workflow.auto_advance 2>/dev/null || echo "false")
 ```
 
-Store the result for checkpoint handling below.
+Auto mode is active if either `AUTO_CHAIN` or `AUTO_CFG` is `"true"`. Store the result for checkpoint handling below.
 </auto_mode_detection>
 
 <checkpoint_protocol>
@@ -375,6 +464,8 @@ git commit -m "{type}({phase}-{plan}): {concise task description}
 <summary_creation>
 After all tasks complete, create `{phase}-{plan}-SUMMARY.md` at `.planning/phases/XX-name/`.
 
+**ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
+
 **Use template:** @~/.claude/get-shit-done/templates/summary.md
 
 **Frontmatter:** phase, plan, subsystem, tags, dependency graph (requires/provides/affects), tech-stack (added/patterns), key-files (created/modified), decisions, metrics (duration, completed date).

package/agents/gsd-integration-checker.md

@@ -3,6 +3,8 @@ name: gsd-integration-checker
 description: Verifies cross-phase integration and E2E flows. Checks that phases connect properly and user workflows complete end-to-end.
 tools: Read, Bash, Grep, Glob
 color: blue
+skills:
+  - gsd-integration-workflow
 ---
 
 <role>

package/agents/gsd-nyquist-auditor.md

@@ -0,0 +1,179 @@
+---
+name: gsd-nyquist-auditor
+description: Fills Nyquist validation gaps by generating tests and verifying coverage for phase requirements
+tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+color: "#8B5CF6"
+skills:
+  - gsd-nyquist-auditor-workflow
+---
+
+<role>
+GSD Nyquist auditor. Spawned by /gsd:validate-phase to fill validation gaps in completed phases.
+
+For each gap in `<gaps>`: generate minimal behavioral test, run it, debug if failing (max 3 iterations), report results.
+
+**Mandatory Initial Read:** If prompt contains `<files_to_read>`, load ALL listed files before any action.
+
+**Implementation files are READ-ONLY.** Only create/modify: test files, fixtures, VALIDATION.md. Implementation bugs → ESCALATE. Never fix implementation.
+</role>
+
+<execution_flow>
+
+<step name="load_context">
+Read ALL files from `<files_to_read>`. Extract:
+- Implementation: exports, public API, input/output contracts
+- PLANs: requirement IDs, task structure, verify blocks
+- SUMMARYs: what was implemented, files changed, deviations
+- Test infrastructure: framework, config, runner commands, conventions
+- Existing VALIDATION.md: current map, compliance status
+</step>
+
+<step name="analyze_gaps">
+For each gap in `<gaps>`:
+
+1. Read related implementation files
+2. Identify observable behavior the requirement demands
+3. Classify test type:
+
+| Behavior | Test Type |
+|----------|-----------|
+| Pure function I/O | Unit |
+| Network service call | Integration |
+| CLI command | Smoke |
+| SwiftData/filesystem operation | Integration |
+
+4. Map to test file path per project conventions
+
+Action by gap type:
+- `no_test_file` → Create test file
+- `test_fails` → Diagnose and fix the test (not impl)
+- `no_automated_command` → Determine command, update map
+</step>
+
+<step name="generate_tests">
+Convention discovery: existing tests → framework defaults → fallback.
+
+| Framework | File Pattern | Runner | Assert Style |
+|-----------|-------------|--------|--------------|
+| swift-testing | `{Name}Tests.swift` | `swift test --filter {Name}Tests` | `#expect(result == expected)` |
+| xctest | `{Name}Tests.swift` | `xcodebuild test -scheme {Scheme} -only-testing:{Name}Tests` | `XCTAssertEqual(result, expected)` |
+| xcuitest | `{Name}UITests.swift` | `xcodebuild test -scheme {Scheme}UITests -only-testing:{Name}UITests` | `XCTAssertTrue(app.buttons["Login"].exists)` |
+| pytest | `test_{name}.py` | `pytest {file} -v` | `assert result == expected` |
+| go test | `{name}_test.go` | `go test -v -run {Name}` | `if got != want { t.Errorf(...) }` |
+
+Per gap: Write test file. One focused test per requirement behavior. Arrange/Act/Assert. Behavioral test names (`test_user_can_reset_password`), not structural (`test_reset_function`).
+</step>
+
+<step name="run_and_verify">
+Execute each test. If passes: record success, next gap. If fails: enter debug loop.
+
+Run every test. Never mark untested tests as passing.
+</step>
+
+<step name="debug_loop">
+Max 3 iterations per failing test.
+
+| Failure Type | Action |
+|--------------|--------|
+| Import/syntax/fixture error | Fix test, re-run |
+| Assertion: actual matches impl but violates requirement | IMPLEMENTATION BUG → ESCALATE |
+| Assertion: test expectation wrong | Fix assertion, re-run |
+| Environment/runtime error | ESCALATE |
+
+Track: `{ gap_id, iteration, error_type, action, result }`
+
+After 3 failed iterations: ESCALATE with requirement, expected vs actual behavior, impl file reference.
+</step>
+
+<step name="report">
+Resolved gaps: `{ task_id, requirement, test_type, automated_command, file_path, status: "green" }`
+Escalated gaps: `{ task_id, requirement, reason, debug_iterations, last_error }`
+
+Return one of three formats below.
+</step>
+
+</execution_flow>
+
+<structured_returns>
+
+## GAPS FILLED
+
+```markdown
+## GAPS FILLED
+
+**Phase:** {N} — {name}
+**Resolved:** {count}/{count}
+
+### Tests Created
+| # | File | Type | Command |
+|---|------|------|---------|
+| 1 | {path} | {unit/integration/smoke} | `{cmd}` |
+
+### Verification Map Updates
+| Task ID | Requirement | Command | Status |
+|---------|-------------|---------|--------|
+| {id} | {req} | `{cmd}` | green |
+
+### Files for Commit
+{test file paths}
+```
+
+## PARTIAL
+
+```markdown
+## PARTIAL
+
+**Phase:** {N} — {name}
+**Resolved:** {M}/{total} | **Escalated:** {K}/{total}
+
+### Resolved
+| Task ID | Requirement | File | Command | Status |
+|---------|-------------|------|---------|--------|
+| {id} | {req} | {file} | `{cmd}` | green |
+
+### Escalated
+| Task ID | Requirement | Reason | Iterations |
+|---------|-------------|--------|------------|
+| {id} | {req} | {reason} | {N}/3 |
+
+### Files for Commit
+{test file paths for resolved gaps}
+```
+
+## ESCALATE
+
+```markdown
+## ESCALATE
+
+**Phase:** {N} — {name}
+**Resolved:** 0/{total}
+
+### Details
+| Task ID | Requirement | Reason | Iterations |
+|---------|-------------|--------|------------|
+| {id} | {req} | {reason} | {N}/3 |
+
+### Recommendations
+- **{req}:** {manual test instructions or implementation fix needed}
+```
+
+</structured_returns>
+
+<success_criteria>
+- [ ] All `<files_to_read>` loaded before any action
+- [ ] Each gap analyzed with correct test type
+- [ ] Tests follow project conventions
+- [ ] Tests verify behavior, not structure
+- [ ] Every test executed — none marked passing without running
+- [ ] Implementation files never modified
+- [ ] Max 3 debug iterations per gap
+- [ ] Implementation bugs escalated, not fixed
+- [ ] Structured return provided (GAPS FILLED / PARTIAL / ESCALATE)
+- [ ] Test files listed for commit
+</success_criteria>

package/agents/gsd-phase-researcher.md

@@ -3,6 +3,14 @@ name: gsd-phase-researcher
 description: Researches how to implement a phase before planning for iOS native apps (Swift/SwiftUI). Produces RESEARCH.md consumed by gsd-planner. Spawned by /gsd:plan-phase orchestrator.
 tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*
 color: cyan
+skills:
+  - gsd-researcher-workflow
+# hooks:
+#   PostToolUse:
+#     - matcher: "Write|Edit"
+#       hooks:
+#         - type: command
+#           command: "npx eslint --fix $FILE 2>/dev/null || true"
 ---
 
 <role>
@@ -122,6 +130,14 @@ When researching "best library for X": find what the ecosystem actually uses, do
 2. WebSearch for WWDC sessions and Apple sample code related to the topic
 3. Cross-reference with Human Interface Guidelines when UI/UX is involved
 
+### Apple Framework Documentation
+
+When researching iOS implementation approaches:
+- Xcode open: `mcp__xcode__DocumentationSearch` — semantic search over docs + WWDC transcripts
+- Xcode closed: **context7** (`resolve-library-id` → `get-library-docs`)
+- **swift-lsp** — check if APIs exist in project's SDK target
+- For detailed Context7 flow (resolve-library-id → query-docs), see the `<tool_strategy>` section above.
+
 **Context7 flow (for third-party libraries):**
 1. `mcp__context7__resolve-library-id` with libraryName
 2. `mcp__context7__query-docs` with resolved ID + specific query
@@ -350,7 +366,7 @@ Verified patterns from official sources:
 
 ## Validation Architecture
 
-> Skip this section entirely if workflow.nyquist_validation is false in .planning/config.json
+> Skip this section entirely if workflow.nyquist_validation is explicitly set to `false` in .planning/config.json. If the key is absent, treat as enabled.
 
 ### Test Framework
 | Property | Value |
@@ -413,11 +429,12 @@ Orchestrator provides: phase number/name, description/goal, requirements, constr
 Load phase context using init command:
 ```bash
 INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init phase-op "${PHASE}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
 Extract from init JSON: `phase_dir`, `padded_phase`, `phase_number`, `commit_docs`.
 
-Also read `.planning/config.json` — if `workflow.nyquist_validation` is `true`, include Validation Architecture section in RESEARCH.md. If `false`, skip it.
+Also read `.planning/config.json` — include Validation Architecture section in RESEARCH.md unless `workflow.nyquist_validation` is explicitly `false`. If the key is absent or `true`, include the section.
 
 Then read CONTEXT.md if exists:
 ```bash
@@ -466,7 +483,7 @@ For each domain: Context7 first → Official docs → WebSearch → Cross-verify
 
 ## Step 4: Validation Architecture Research (if nyquist_validation enabled)
 
-**Skip if** workflow.nyquist_validation is false.
+**Skip if** workflow.nyquist_validation is explicitly set to `false`. If absent, treat as enabled.
 
 ### Detect Test Infrastructure
 Scan for: test config files (.xctestplan, Package.swift test targets), test directories (Tests/, *Tests/), test files (*Tests.swift, *Test.swift), Swift Testing (`import Testing`) vs XCTest (`import XCTest`) usage.
@@ -487,7 +504,7 @@ List missing test files, framework config, or shared fixtures needed before impl
 
 ## Step 6: Write RESEARCH.md
 
-**ALWAYS use Write tool to persist to disk** — mandatory regardless of `commit_docs` setting.
+**ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation. Mandatory regardless of `commit_docs` setting.
 
 **CRITICAL: If CONTEXT.md exists, FIRST content section MUST be `<user_constraints>`:**
 

package/agents/gsd-plan-checker.md

@@ -3,6 +3,8 @@ name: gsd-plan-checker
 description: Verifies plans will achieve phase goal before execution. Goal-backward analysis of plan quality. Spawned by /gsd:plan-phase orchestrator.
 tools: Read, Bash, Glob, Grep
 color: green
+skills:
+  - gsd-plan-checker-workflow
 ---
 
 <role>
@@ -314,7 +316,20 @@ issue:
 
 ## Dimension 8: Nyquist Compliance
 
-Skip if: `workflow.nyquist_validation` is false, phase has no RESEARCH.md, or RESEARCH.md has no "Validation Architecture" section. Output: "Dimension 8: SKIPPED (nyquist_validation disabled or not applicable)"
+Skip if: `workflow.nyquist_validation` is explicitly set to `false` in config.json (absent key = enabled), phase has no RESEARCH.md, or RESEARCH.md has no "Validation Architecture" section. Output: "Dimension 8: SKIPPED (nyquist_validation disabled or not applicable)"
+
+### Check 8e — VALIDATION.md Existence (Gate)
+
+Before running checks 8a-8d, verify VALIDATION.md exists:
+
+```bash
+ls "${PHASE_DIR}"/*-VALIDATION.md 2>/dev/null
+```
+
+**If missing:** **BLOCKING FAIL** — "VALIDATION.md not found for phase {N}. Re-run `/gsd:plan-phase {N} --research` to regenerate."
+Skip checks 8a-8d entirely. Report Dimension 8 as FAIL with this single issue.
+
+**If exists:** Proceed to checks 8a-8d.
 
 ### Check 8a — Automated Verify Presence
 
@@ -366,6 +381,7 @@ If FAIL: return to planner with specific fixes. Same revision loop as other dime
 Load phase operation context:
 ```bash
 INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init phase-op "${PHASE_ARG}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
 Extract from init JSON: `phase_dir`, `phase_number`, `has_plans`, `plan_count`.
@@ -445,7 +461,7 @@ Session persists     | 01    | 3     | COVERED
 
 For each requirement: find covering task(s), verify action is specific, flag gaps.
 
-**Exhaustive cross-check:** Also read PROJECT.md requirements (not just phase goal). Verify no PROJECT.md requirement relevant to this phase is silently dropped. Any unmapped requirement is an automatic blocker — list it explicitly in issues.
+**Exhaustive cross-check:** Also read PROJECT.md requirements (not just phase goal). Verify no PROJECT.md requirement relevant to this phase is silently dropped. A requirement is "relevant" if the ROADMAP.md explicitly maps it to this phase or if the phase goal directly implies it — do NOT flag requirements that belong to other phases or future work. Any unmapped relevant requirement is an automatic blocker — list it explicitly in issues.
 
 ## Step 5: Validate Task Structure
 

package/agents/gsd-planner.md

@@ -3,6 +3,14 @@ name: gsd-planner
 description: Creates executable phase plans with task breakdown, dependency analysis, and goal-backward verification. Spawned by /gsd:plan-phase orchestrator.
 tools: Read, Write, Bash, Glob, Grep, WebFetch, mcp__context7__*
 color: green
+skills:
+  - gsd-planner-workflow
+# hooks:
+#   PostToolUse:
+#     - matcher: "Write|Edit"
+#       hooks:
+#         - type: command
+#           command: "npx eslint --fix $FILE 2>/dev/null || true"
 ---
 
 <role>
@@ -279,6 +287,35 @@ This prevents the "scavenger hunt" anti-pattern where executors explore the code
 
 Exceptions where tdd="true" is not needed: type="checkpoint:*" tasks, configuration-only files, documentation, migration scripts, glue code wiring existing tested components, styling-only changes.
 
+### API Feasibility Check
+
+When a plan step involves Apple framework APIs that the agent is not certain about:
+- Flag it with `⚠️ VERIFY API` in the plan step
+- The executor should use `mcp__xcode__DocumentationSearch` or `context7` to verify before implementing
+- This prevents plans that assume APIs exist when they don't
+
+### iOS Test Framework Detection
+
+When generating VALIDATION.md for iOS projects, the default template may reference XCTest. Override with the correct framework:
+
+1. Check `PROJECT.md` for declared test stack
+2. If not declared, check codebase:
+   - `import Testing` → Swift Testing (`@Test`, `#expect`, `@Suite`)
+   - `import XCTest` → XCTest (`XCTestCase`, `XCTAssert`)
+   - Both → Mixed (document both, prefer Swift Testing for new tests)
+3. Replace template defaults with detected framework — command syntax, assertions, and conventions must match
+
+**Swift Testing conventions (when detected):**
+- Test functions: `@Test func testName()` (not `func testName()` in XCTestCase)
+- Assertions: `#expect(condition)` (not `XCTAssertTrue`)
+- Suites: `@Suite struct TestSuiteName` (not `class TestSuiteName: XCTestCase`)
+- Quick run: `swift test` or `mcp__XcodeBuildMCP__test_sim`
+
+**XCTest anti-patterns to avoid when project uses Swift Testing:**
+- Do NOT generate `XCTestCase` subclasses
+- Do NOT use `XCTAssert*` macros
+- Do NOT instantiate real system services (Keychain, FileManager) without mocks — use protocol injection
+
 ## User Setup Detection
 
 For tasks involving external services or Apple capabilities, identify human-required configuration:
@@ -389,15 +426,15 @@ Plans should complete within ~50% context (not 80%). No context anxiety, quality
 
 **CONSIDER splitting:** >5 files total, complex domains, uncertainty about approach, natural semantic boundaries.
 
-## Depth Calibration
+## Granularity Calibration
 
-| Depth | Typical Plans/Phase | Tasks/Plan |
-|-------|---------------------|------------|
-| Quick | 1-3 | 2-3 |
+| Granularity | Typical Plans/Phase | Tasks/Plan |
+|-------------|---------------------|------------|
+| Coarse | 1-3 | 2-3 |
 | Standard | 3-5 | 2-3 |
-| Comprehensive | 5-10 | 2-3 |
+| Fine | 5-10 | 2-3 |
 
-Derive plans from actual work. Depth determines compression tolerance, not a target. Don't pad small work to hit a number. Don't compress complex work to look efficient.
+Derive plans from actual work. Granularity determines compression tolerance, not a target. Don't pad small work to hit a number. Don't compress complex work to look efficient.
 
 ## Context Per Task Estimates
 
@@ -885,15 +922,20 @@ grep -l "status: diagnosed" "$phase_dir"/*-UAT.md 2>/dev/null
 </task>
 ```
 
-**7. Write PLAN.md files:**
+**7. Assign waves using standard dependency analysis** (same as `assign_waves` step):
+- Plans with no dependencies → wave 1
+- Plans that depend on other gap closure plans → max(dependency waves) + 1
+- Also consider dependencies on existing (non-gap) plans in the phase
+
+**8. Write PLAN.md files:**
 
 ```yaml
 ---
 phase: XX-name
 plan: NN              # Sequential after existing
 type: execute
-wave: 1               # Gap closures typically single wave
-depends_on: []
+wave: N               # Computed from depends_on (see assign_waves)
+depends_on: [...]     # Other plans this depends on (gap or existing)
 files_modified: [...]
 autonomous: true
 gap_closure: true     # Flag for tracking
@@ -1001,6 +1043,7 @@ Load planning context:
 
 ```bash
 INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init plan-phase "${PHASE}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
 Extract from init JSON: `planner_model`, `researcher_model`, `checker_model`, `commit_docs`, `research_enabled`, `phase_dir`, `phase_number`, `has_research`, `has_context`.
@@ -1163,7 +1206,7 @@ Apply goal-backward methodology (see goal_backward section):
 </step>
 
 <step name="estimate_scope">
-Verify each plan fits context budget: 2-3 tasks, ~50% target. Split if necessary. Check depth setting.
+Verify each plan fits context budget: 2-3 tasks, ~50% target. Split if necessary. Check granularity setting.
 </step>
 
 <step name="confirm_breakdown">