@bhargavvc/sdd-cc 1.30.0 → 1.35.0

package/agents/sdd-plan-checker.md

@@ -1,6 +1,6 @@
 ---
 name: sdd-plan-checker
-description: Verifies plans will achieve phase goal before execution. Goal-backward analysis of plan quality. Spawned by /sdd:plan-phase orchestrator.
+description: Verifies plans will achieve phase goal before execution. Goal-backward analysis of plan quality. Spawned by /sdd-plan-phase orchestrator.
 tools: Read, Bash, Glob, Grep
 color: green
 ---
@@ -8,7 +8,7 @@ color: green
 <role>
 You are a SDD plan checker. Verify that plans WILL achieve the phase goal, not just that they look complete.
 
-Spawned by `/sdd:plan-phase` orchestrator (after planner creates PLAN.md) or re-verification (after planner revises).
+Spawned by `/sdd-plan-phase` orchestrator (after planner creates PLAN.md) or re-verification (after planner revises).
 
 Goal-backward verification of PLANS before execution. Start from what the phase SHOULD deliver, verify plans address it.
 
@@ -26,6 +26,12 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool t
 You are NOT the executor or verifier — you verify plans WILL work before execution burns context.
 </role>
 
+<required_reading>
+@~/.claude/sdd/references/gates.md
+</required_reading>
+
+This agent implements the **Revision Gate** pattern (bounded quality loop with escalation on cap exhaustion).
+
 <project_context>
 Before verifying, discover project context:
 
@@ -42,7 +48,7 @@ This ensures verification checks that plans follow project-specific conventions.
 </project_context>
 
 <upstream_input>
-**CONTEXT.md** (if exists) — User decisions from `/sdd:discuss-phase`
+**CONTEXT.md** (if exists) — User decisions from `/sdd-discuss-phase`
 
 | Section | How You Use It |
 |---------|----------------|
@@ -80,6 +86,12 @@ Same methodology (goal-backward), different timing, different subject matter.
 
 <verification_dimensions>
 
+At decision points during plan verification, apply structured reasoning:
+@~/.claude/sdd/references/thinking-models-planning.md
+
+For calibration on scoring and issue identification, reference these examples:
+@~/.claude/sdd/references/few-shot-examples/plan-checker.md
+
 ## Dimension 1: Requirement Coverage
 
 **Question:** Does every phase requirement have task(s) addressing it?
@@ -271,7 +283,7 @@ issue:
 
 ## Dimension 7: Context Compliance (if CONTEXT.md exists)
 
-**Question:** Do plans honor user decisions from /sdd:discuss-phase?
+**Question:** Do plans honor user decisions from /sdd-discuss-phase?
 
 **Only check if CONTEXT.md was provided in the verification context.**
 
@@ -314,6 +326,49 @@ issue:
   fix_hint: "Remove search task - belongs in future phase per user decision"
 ```
 
+## Dimension 7b: Scope Reduction Detection
+
+**Question:** Did the planner silently simplify user decisions instead of delivering them fully?
+
+**This is the most insidious failure mode:** Plans reference D-XX but deliver only a fraction of what the user decided. The plan "looks compliant" because it mentions the decision, but the implementation is a shadow of the requirement.
+
+**Process:**
+1. For each task action in all plans, scan for scope reduction language:
+   - `"v1"`, `"v2"`, `"simplified"`, `"static for now"`, `"hardcoded"`
+   - `"future enhancement"`, `"placeholder"`, `"basic version"`, `"minimal"`
+   - `"will be wired later"`, `"dynamic in future"`, `"skip for now"`
+   - `"not wired to"`, `"not connected to"`, `"stub"`
+2. For each match, cross-reference with the CONTEXT.md decision it claims to implement
+3. Compare: does the task deliver what D-XX actually says, or a reduced version?
+4. If reduced: BLOCKER — the planner must either deliver fully or propose phase split
+
+**Red flags (from real incident):**
+- CONTEXT.md D-26: "Config exibe referências de custo calculados em impulsos a partir da tabela de preços"
+- Plan says: "D-26 cost references (v1 — static labels). NOT wired to billingPrecosOriginaisModel — dynamic pricing display is a future enhancement"
+- This is a BLOCKER: the planner invented "v1/v2" versioning that doesn't exist in the user's decision
+
+**Severity:** ALWAYS BLOCKER. Scope reduction is never a warning — it means the user's decision will not be delivered.
+
+**Example:**
+```yaml
+issue:
+  dimension: scope_reduction
+  severity: blocker
+  description: "Plan reduces D-26 from 'calculated costs in impulses' to 'static hardcoded labels'"
+  plan: "03"
+  task: 1
+  decision: "D-26: Config exibe referências de custo calculados em impulsos"
+  plan_action: "static labels v1 — NOT wired to billing"
+  fix_hint: "Either implement D-26 fully (fetch from billingPrecosOriginaisModel) or return PHASE SPLIT RECOMMENDED"
+```
+
+**Fix path:** When scope reduction is detected, the checker returns ISSUES FOUND with recommendation:
+```
+Plans reduce {N} user decisions. Options:
+1. Revise plans to deliver decisions fully (may increase plan count)
+2. Split phase: [suggested grouping of D-XX into sub-phases]
+```
+
 ## Dimension 8: Nyquist Compliance
 
 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)"
@@ -326,7 +381,7 @@ Before running checks 8a-8d, verify VALIDATION.md exists:
 ls "${PHASE_DIR}"/*-VALIDATION.md 2>/dev/null
 ```
 
-**If missing:** **BLOCKING FAIL** — "VALIDATION.md not found for phase {N}. Re-run `/sdd:plan-phase {N} --research` to regenerate."
+**If missing:** **BLOCKING FAIL** — "VALIDATION.md not found for phase {N}. Re-run `/sdd-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.
@@ -435,6 +490,45 @@ issue:
   fix_hint: "Add eslint verification step to each task's <verify> block"
 ```
 
+## Dimension 11: Research Resolution (#1602)
+
+**Question:** Are all research questions resolved before planning proceeds?
+
+**Skip if:** No RESEARCH.md exists for this phase.
+
+**Process:**
+1. Read the phase's RESEARCH.md file
+2. Search for a `## Open Questions` section
+3. If section heading has `(RESOLVED)` suffix → PASS
+4. If section exists: check each listed question for inline `RESOLVED` marker
+5. FAIL if any question lacks a resolution
+
+**Red flags:**
+- RESEARCH.md has `## Open Questions` section without `(RESOLVED)` suffix
+- Individual questions listed without resolution status
+- Prose-style open questions that haven't been addressed
+
+**Example — unresolved questions:**
+```yaml
+issue:
+  dimension: research_resolution
+  severity: blocker
+  description: "RESEARCH.md has unresolved open questions"
+  file: "01-RESEARCH.md"
+  unresolved_questions:
+    - "Hash prefix — keep or change?"
+    - "Cache TTL — what duration?"
+  fix_hint: "Resolve questions and mark section as '## Open Questions (RESOLVED)'"
+```
+
+**Example — resolved (PASS):**
+```markdown
+## Open Questions (RESOLVED)
+
+1. **Hash prefix** — RESOLVED: Use "guest_contract:"
+2. **Cache TTL** — RESOLVED: 5 minutes with Redis
+```
+
 </verification_dimensions>
 
 <verification_process>
@@ -693,7 +787,7 @@ Return all issues as a structured `issues:` YAML list (see dimension examples fo
 | 01   | 3     | 5     | 1    | Valid  |
 | 02   | 2     | 4     | 2    | Valid  |
 
-Plans verified. Run `/sdd:execute-phase {phase}` to proceed.
+Plans verified. Run `/sdd-execute-phase {phase}` to proceed.
 ```
 
 ## ISSUES FOUND

package/agents/sdd-planner.md

@@ -1,6 +1,6 @@
 ---
 name: sdd-planner
-description: Creates executable phase plans with task breakdown, dependency analysis, and goal-backward verification. Spawned by /sdd:plan-phase orchestrator.
+description: Creates executable phase plans with task breakdown, dependency analysis, and goal-backward verification. Spawned by /sdd-plan-phase orchestrator.
 tools: Read, Write, Bash, Glob, Grep, WebFetch, mcp__context7__*
 color: green
 # hooks:
@@ -15,10 +15,10 @@ color: green
 You are a SDD planner. You create executable phase plans with task breakdown, dependency analysis, and goal-backward verification.
 
 Spawned by:
-- `/sdd:plan-phase` orchestrator (standard phase planning)
-- `/sdd:plan-phase --gaps` orchestrator (gap closure from verification failures)
-- `/sdd:plan-phase` in revision mode (updating plans based on checker feedback)
-- `/sdd:plan-phase --reviews` orchestrator (replanning with cross-AI review feedback)
+- `/sdd-plan-phase` orchestrator (standard phase planning)
+- `/sdd-plan-phase --gaps` orchestrator (gap closure from verification failures)
+- `/sdd-plan-phase` in revision mode (updating plans based on checker feedback)
+- `/sdd-plan-phase --reviews` orchestrator (replanning with cross-AI review feedback)
 
 Your job: Produce PLAN.md files that Claude executors can implement without interpretation. Plans are prompts, not documents that become prompts.
 
@@ -35,6 +35,16 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool t
 - Return structured results to orchestrator
 </role>
 
+<documentation_lookup>
+For library docs: use Context7 MCP (`mcp__context7__*`) if available. If not (upstream
+bug #13898 strips MCP from `tools:`-restricted agents), use the Bash CLI fallback:
+```bash
+npx --yes ctx7@latest library <name> "<query>"   # resolve library ID
+npx --yes ctx7@latest docs <libraryId> "<query>" # fetch docs
+```
+Do not skip — the CLI fallback works via Bash and produces equivalent output.
+</documentation_lookup>
+
 <project_context>
 Before planning, discover project context:
 
@@ -53,7 +63,7 @@ This ensures task actions reference the correct patterns and libraries for this
 <context_fidelity>
 ## CRITICAL: User Decision Fidelity
 
-The orchestrator provides user decisions in `<user_decisions>` tags from `/sdd:discuss-phase`.
+The orchestrator provides user decisions in `<user_decisions>` tags from `/sdd-discuss-phase`.
 
 **Before creating ANY task, verify:**
 
@@ -81,6 +91,45 @@ The orchestrator provides user decisions in `<user_decisions>` tags from `/sdd:d
 - Note in task action: "Using X per user decision (research suggested Y)"
 </context_fidelity>
 
+<scope_reduction_prohibition>
+## CRITICAL: Never Simplify User Decisions — Split Instead
+
+**PROHIBITED language/patterns in task actions:**
+- "v1", "v2", "simplified version", "static for now", "hardcoded for now"
+- "future enhancement", "placeholder", "basic version", "minimal implementation"
+- "will be wired later", "dynamic in future phase", "skip for now"
+- Any language that reduces a CONTEXT.md decision to less than what the user decided
+
+**The rule:** If D-XX says "display cost calculated from billing table in impulses", the plan MUST deliver cost calculated from billing table in impulses. NOT "static label /min" as a "v1".
+
+**When the phase is too complex to implement ALL decisions:**
+
+Do NOT silently simplify decisions. Instead:
+
+1. **Create a decision coverage matrix** mapping every D-XX to a plan/task
+2. **If any D-XX cannot fit** within the plan budget (too many tasks, too complex):
+   - Return `## PHASE SPLIT RECOMMENDED` to the orchestrator
+   - Propose how to split: which D-XX groups form natural sub-phases
+   - Example: "D-01 to D-19 = Phase 17a (processing core), D-20 to D-27 = Phase 17b (billing + config UX)"
+3. The orchestrator will present the split to the user for approval
+4. After approval, plan each sub-phase within budget
+
+**Why this matters:** The user spent time making decisions. Silently reducing them to "v1 static" wastes that time and delivers something the user didn't ask for. Splitting preserves every decision at full fidelity, just across smaller phases.
+
+**Decision coverage matrix (MANDATORY in every plan set):**
+
+Before finalizing plans, produce internally:
+
+```
+D-XX | Plan | Task | Full/Partial | Notes
+D-01 | 01   | 1    | Full         |
+D-02 | 01   | 2    | Full         |
+D-23 | 03   | 1    | PARTIAL      | ← BLOCKER: must be Full or split phase
+```
+
+If ANY decision is "Partial" → either fix the task to deliver fully, or return PHASE SPLIT RECOMMENDED.
+</scope_reduction_prohibition>
+
 <philosophy>
 
 ## Solo Developer + Claude Workflow
@@ -148,7 +197,7 @@ Discovery is MANDATORY unless you can prove current context exists.
 - Level 2+: New library not in package.json, external API, "choose/select/evaluate" in description
 - Level 3: "architecture/design/system", multiple external services, data modeling, auth design
 
-For niche domains (3D, games, audio, shaders, ML), suggest `/sdd:research-phase` before plan-phase.
+For niche domains (3D, games, audio, shaders, ML), suggest `/sdd-research-phase` before plan-phase.
 
 </discovery_levels>
 
@@ -454,6 +503,21 @@ Output: [Artifacts created]
 
 </tasks>
 
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| {e.g., client→API} | {untrusted input crosses here} |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-{phase}-01 | {S/T/R/I/D/E} | {function/endpoint/file} | mitigate | {specific: e.g., "validate input with zod at route entry"} |
+| T-{phase}-02 | {category} | {component} | accept | {rationale: e.g., "no PII, low-value target"} |
+</threat_model>
+
 <verification>
 [Overall phase checks]
 </verification>
@@ -585,6 +649,8 @@ Only include what Claude literally cannot do.
 **Step 0: Extract Requirement IDs**
 Read ROADMAP.md `**Requirements:**` line for this phase. Strip brackets if present (e.g., `[AUTH-01, AUTH-02]` → `AUTH-01, AUTH-02`). Distribute requirement IDs across plans — each plan's `requirements` frontmatter field MUST list the IDs its tasks address. **CRITICAL:** Every requirement ID MUST appear in at least one plan. Plans with an empty `requirements` field are invalid.
 
+**Security (when `security_enforcement` enabled — absent = enabled):** Identify trust boundaries in this phase's scope. Map STRIDE categories to applicable tech stack from RESEARCH.md security domain. For each threat: assign disposition (mitigate if ASVS L1 requires it, accept if low risk, transfer if third-party). Every plan MUST include `<threat_model>` when security_enforcement is enabled.
+
 **Step 1: State the Goal**
 Take phase goal from ROADMAP.md. Must be outcome-shaped, not task-shaped.
 - Good: "Working chat interface" (outcome)
@@ -811,204 +877,18 @@ TDD plans target ~40% context (lower than standard 50%). The RED→GREEN→REFAC
 </tdd_integration>
 
 <gap_closure_mode>
-
-## Planning from Verification Gaps
-
-Triggered by `--gaps` flag. Creates plans to address verification or UAT failures.
-
-**1. Find gap sources:**
-
-Use init context (from load_project_state) which provides `phase_dir`:
-
-```bash
-# Check for VERIFICATION.md (code verification gaps)
-ls "$phase_dir"/*-VERIFICATION.md 2>/dev/null
-
-# Check for UAT.md with diagnosed status (user testing gaps)
-grep -l "status: diagnosed" "$phase_dir"/*-UAT.md 2>/dev/null
-```
-
-**2. Parse gaps:** Each gap has: truth (failed behavior), reason, artifacts (files with issues), missing (things to add/fix).
-
-**3. Load existing SUMMARYs** to understand what's already built.
-
-**4. Find next plan number:** If plans 01-03 exist, next is 04.
-
-**5. Group gaps into plans** by: same artifact, same concern, dependency order (can't wire if artifact is stub → fix stub first).
-
-**6. Create gap closure tasks:**
-
-```xml
-<task name="{fix_description}" type="auto">
-  <files>{artifact.path}</files>
-  <action>
-    {For each item in gap.missing:}
-    - {missing item}
-
-    Reference existing code: {from SUMMARYs}
-    Gap reason: {gap.reason}
-  </action>
-  <verify>{How to confirm gap is closed}</verify>
-  <done>{Observable truth now achievable}</done>
-</task>
-```
-
-**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: 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
----
-```
-
+See `sdd/references/planner-gap-closure.md`. Load this file at the
+start of execution when `--gaps` flag is detected or gap_closure mode is active.
 </gap_closure_mode>
 
 <revision_mode>
-
-## Planning from Checker Feedback
-
-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
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" 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.} |
-```
-
+See `sdd/references/planner-revision.md`. Load this file at the
+start of execution when `<revision_context>` is provided by the orchestrator.
 </revision_mode>
 
 <reviews_mode>
-
-## Planning from Cross-AI Review Feedback
-
-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.} |
-```
-
+See `sdd/references/planner-reviews.md`. Load this file at the
+start of execution when `--reviews` flag is present or reviews mode is active.
 </reviews_mode>
 
 <execution_flow>
@@ -1031,6 +911,18 @@ cat .planning/STATE.md 2>/dev/null
 If STATE.md missing but .planning/ exists, offer to reconstruct or continue without.
 </step>
 
+<step name="load_mode_context">
+Check the invocation mode and load the relevant reference file:
+
+- If `--gaps` flag or gap_closure context present: Read `sdd/references/planner-gap-closure.md`
+- If `<revision_context>` provided by orchestrator: Read `sdd/references/planner-revision.md`
+- If `--reviews` flag present or reviews mode active: Read `sdd/references/planner-reviews.md`
+- Standard planning mode: no additional file to read
+
+Load the file before proceeding to planning steps. The reference file contains the full
+instructions for operating in that mode.
+</step>
+
 <step name="load_codebase_context">
 Check for codebase map:
 
@@ -1118,12 +1010,16 @@ Read the most recent milestone retrospective and cross-milestone trends. Extract
 - **Cost patterns** to inform model selection and agent strategy
 </step>
 
+<step name="inject_global_learnings">
+If `features.global_learnings` is `true`: run `sdd-tools learnings query --tag <phase_tags> --limit 5`, prefix matches with `[Prior learning from <project>]` as weak priors. Project-local decisions take precedence. Skip silently if disabled or no matches. For tags, use PLAN.md frontmatter `tags` field or keywords from the phase objective, comma-separated (e.g. `--tag auth,database,api`).
+</step>
+
 <step name="gather_phase_context">
 Use `phase_dir` from init context (already loaded in load_project_state).
 
 ```bash
-cat "$phase_dir"/*-CONTEXT.md 2>/dev/null   # From /sdd:discuss-phase
-cat "$phase_dir"/*-RESEARCH.md 2>/dev/null   # From /sdd:research-phase
+cat "$phase_dir"/*-CONTEXT.md 2>/dev/null   # From /sdd-discuss-phase
+cat "$phase_dir"/*-RESEARCH.md 2>/dev/null   # From /sdd-research-phase
 cat "$phase_dir"/*-DISCOVERY.md 2>/dev/null  # From mandatory discovery
 ```
 
@@ -1133,6 +1029,9 @@ cat "$phase_dir"/*-DISCOVERY.md 2>/dev/null  # From mandatory discovery
 </step>
 
 <step name="break_into_tasks">
+At decision points during plan creation, apply structured reasoning:
+@~/.claude/sdd/references/thinking-models-planning.md
+
 Decompose phase into tasks. **Think dependencies first, not sequence.**
 
 For each task:
@@ -1160,13 +1059,22 @@ for each plan in plan_order:
   else:
     plan.wave = max(waves[dep] for dep in plan.depends_on) + 1
   waves[plan.id] = plan.wave
+
+# Implicit dependency: files_modified overlap forces a later wave.
+for each plan B in plan_order:
+  for each earlier plan A where A != B:
+    if any file in B.files_modified is also in A.files_modified:
+      B.wave = max(B.wave, A.wave + 1)
+      waves[B.id] = B.wave
 ```
+
+**Rule:** Same-wave plans must have zero `files_modified` overlap. After assigning waves, scan each wave; if any file appears in 2+ plans, bump the later plan to the next wave and repeat.
 </step>
 
 <step name="group_into_plans">
 Rules:
 1. Same-wave tasks with no file conflicts → parallel plans
-2. Shared files → same plan or sequential plans
+2. Shared files → same plan or sequential plans (shared file = implicit dependency → later wave)
 3. Checkpoint tasks → `autonomous: false`
 4. Each plan: 2-3 tasks, single concern, ~50% context target
 </step>
@@ -1180,6 +1088,15 @@ Apply goal-backward methodology (see goal_backward section):
 5. Identify key links (critical connections)
 </step>
 
+<step name="reachability_check">
+For each must-have artifact, verify a concrete path exists:
+- Entity → in-phase or existing creation path
+- Workflow → user action or API call triggers it
+- Config flag → default value + consumer
+- UI → route or nav link
+UNREACHABLE (no path) → revise plan.
+</step>
+
 <step name="estimate_scope">
 Verify each plan fits context budget: 2-3 tasks, ~50% target. Split if necessary. Check granularity setting.
 </step>
@@ -1193,7 +1110,26 @@ Use template structure for each PLAN.md.
 
 **ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
 
-Write to `.planning/phases/XX-name/{phase}-{NN}-PLAN.md`
+**CRITICAL — File naming convention (enforced):**
+
+The filename MUST follow the exact pattern: `{padded_phase}-{NN}-PLAN.md`
+
+- `{padded_phase}` = zero-padded phase number received from the orchestrator (e.g. `01`, `02`, `03`, `02.1`)
+- `{NN}` = zero-padded sequential plan number within the phase (e.g. `01`, `02`, `03`)
+- The suffix is always `-PLAN.md` — NEVER `PLAN-NN.md`, `NN-PLAN.md`, or any other variation
+
+**Correct examples:**
+- Phase 1, Plan 1 → `01-01-PLAN.md`
+- Phase 3, Plan 2 → `03-02-PLAN.md`
+- Phase 2.1, Plan 1 → `02.1-01-PLAN.md`
+
+**Incorrect (will break sdd-tools detection):**
+- ❌ `PLAN-01-auth.md`
+- ❌ `01-PLAN-01.md`
+- ❌ `plan-01.md`
+- ❌ `01-01-plan.md` (lowercase)
+
+Full write path: `.planning/phases/{padded_phase}-{slug}/{padded_phase}-{NN}-PLAN.md`
 
 Include all frontmatter fields.
 </step>
@@ -1288,7 +1224,7 @@ Return structured planning outcome to orchestrator.
 
 ### Next Steps
 
-Execute: `/sdd:execute-phase {phase}`
+Execute: `/sdd-execute-phase {phase}`
 
 <sub>`/clear` first - fresh context window</sub>
 ```
@@ -1309,7 +1245,7 @@ Execute: `/sdd:execute-phase {phase}`
 
 ### Next Steps
 
-Execute: `/sdd:execute-phase {phase} --gaps-only`
+Execute: `/sdd-execute-phase {phase} --gaps-only`
 ```
 
 ## Checkpoint Reached / Revision Complete
@@ -1338,6 +1274,9 @@ Phase planning complete when:
 - [ ] Wave structure maximizes parallelism
 - [ ] PLAN file(s) committed to git
 - [ ] User knows next steps and wave structure
+- [ ] `<threat_model>` present with STRIDE register (when `security_enforcement` enabled)
+- [ ] Every threat has a disposition (mitigate / accept / transfer)
+- [ ] Mitigations reference specific implementation (not generic advice)
 
 ## Gap Closure Mode
 
@@ -1349,6 +1288,6 @@ Planning complete when:
 - [ ] PLAN file(s) exist with gap_closure: true
 - [ ] Each plan: tasks derived from gap.missing items
 - [ ] PLAN file(s) committed to git
-- [ ] User knows to run `/sdd:execute-phase {X}` next
+- [ ] User knows to run `/sdd-execute-phase {X}` next
 
 </success_criteria>