gsdd-cli 0.2.0 → 0.16.1

package/distilled/workflows/new-project.md

@@ -282,26 +282,9 @@ Display key findings before moving to spec creation.
 **STOP. Research is complete. Do NOT write any application code. Proceed to spec creation below. Your job now is to produce SPEC.md and ROADMAP.md — not to build the project.**
 
 <data_schema_definition>
-**(SOTA Insight: Derived from GitHub Blog - "Multi-agent workflows often fail")**
-Multi-agent systems require Typed Schemas to pass reliable state. Natural language instructions fail across agent handoffs.
-Before writing the final SPEC.md, explicitly define the core Data Models/Typed Schemas the project will use (e.g., `type UserProfile = { id: number; plan: 'free' | 'pro' }`).
-These strict schemas MUST be included in the `SPEC.md` to prevent agent hallucination during the implementation phases.
-6. **Typed Data Schemas**: Add the strict data models defined earlier.
-7. **Done-When Verification Chain (SOTA Insight from Cyanluna)**: For EVERY single requirement in the "Must Have (v1)" section, you MUST define a clear, verifiable `[Done-When: ...]` criteria. Vague requirements like "User can log in" must become "User can log in [Done-When: Login form submits, JWT is received, and User is redirected to Dashboard]". No exceptions.
-
-*DO NOT include implementation tasks here. SPEC.md defines WHAT, not HOW.*
+Before writing SPEC.md, define core Data Models/Typed Schemas *(SOTA: GitHub Blog — "Multi-agent workflows often fail")*. Multi-agent systems require typed schemas to pass reliable state. These schemas MUST be included in SPEC.md (see item 7 in `<spec_creation>` below). Also define Done-When verification criteria for every requirement (see item 8). *SPEC.md defines WHAT, not HOW — do not include implementation tasks.*
 </data_schema_definition>
 
-<capability_gates>
-**(SOTA Insight: Derived from OpenFang - "16 Security Systems & Capability Gates")**
-Before finishing SPEC.md, explicitly define what the agents are NOT allowed to do automatically without human approval.
-If `autoAdvance: true`, skip this question. Add a deferred placeholder to SPEC.md:
-"## Capability & Security Gates\n_Deferred — auto mode cannot elicit gate preferences; requires explicit review before production deployment._"
-Otherwise:
-Ask the user: "Are there any destructive actions, purchases, or external API calls that should require mandatory human approval (Capability Gates)?"
-Add these into the new `## Capability & Security Gates` section of the SPEC.md.
-</capability_gates>
-
 <spec_creation>
 After the subagent research completes, synthesize EVERYTHING into `SPEC.md`:
 
@@ -311,9 +294,20 @@ After the subagent research completes, synthesize EVERYTHING into `SPEC.md`:
 4. **Requirements are ordered** by priority within each category
 5. **Out of Scope is populated** — includes things the developer explicitly said "not now" AND anti-features found in Research.
 6. **Key Decisions are logged** — any choices made during questioning or dictated by the SOTA research.
-7. **Capability & Security Gates are handled explicitly** — define concrete human-in-the-loop triggers in interactive mode, or add the deferred review placeholder in auto mode so the security decision is visible rather than silently omitted.
-8. **Authorization Matrix (optional)**: For projects with multiple user roles or protected resources, create `.planning/AUTH_MATRIX.md` using the template at `.planning/templates/auth-matrix.md`. The integration checker will use this matrix for systematic auth verification during milestone audits.
-9. **Current State is set** to Phase 1, Status: Not started.
+7. **Typed Data Schemas** *(SOTA: GitHub Blog — "Multi-agent workflows often fail")*: explicitly define the core Data Models/Typed Schemas the project will use (e.g., `type UserProfile = { id: number; plan: 'free' | 'pro' }`). Multi-agent systems require typed schemas to pass reliable state; natural language instructions fail across agent handoffs. *SPEC.md defines WHAT, not HOW — do not include implementation tasks.*
+8. **Done-When Verification Chain** *(SOTA: Cyanluna)*: For EVERY requirement in the "Must Have (v1)" section, define a clear, verifiable `[Done-When: ...]` criterion. "User can log in" must become "User can log in [Done-When: Login form submits, JWT is received, and User is redirected to Dashboard]". No exceptions.
+9. **Capability & Security Gates**: Handle per the `<capability_gates>` section at the end of this `<spec_creation>` block.
+10. **Authorization Matrix (optional)**: For projects with multiple user roles or protected resources, create `.planning/AUTH_MATRIX.md` using the template at `.planning/templates/auth-matrix.md`. The integration checker will use this matrix for systematic auth verification during milestone audits.
+11. **Current State is set** to Phase 1, Status: Not started.
+
+<capability_gates>
+**(SOTA Insight: Derived from OpenFang - "16 Security Systems & Capability Gates")**
+Before finishing SPEC.md, explicitly define what the agents are NOT allowed to do automatically without human approval.
+If `autoAdvance: true`, skip this question. Add a deferred placeholder to SPEC.md:
+"## Capability & Security Gates\n_Deferred — auto mode cannot elicit gate preferences; requires explicit review before production deployment._"
+Otherwise:
+Add these into the new `## Capability & Security Gates` section of the SPEC.md.
+</capability_gates>
 
 ### Quality Check Before Presenting
 - [ ] Can I explain the core value in one sentence?
@@ -331,6 +325,8 @@ Do NOT proceed to roadmap creation until the developer explicitly approves.
 **Commit**: `docs: initialize project spec`
 </spec_creation>
 
+**STOP. Spec creation is complete. Verify that `.planning/SPEC.md` exists on disk with the approved content before creating the roadmap. Do NOT create ROADMAP.md from memory — read the persisted SPEC.md as input.**
+
 <roadmap_creation>
 After `SPEC.md` is approved, you must create `ROADMAP.md`.
 Since you are an Orchestrator with fresh context, you DO NOT need to spawn a subagent for this—write it yourself directly, retaining full thoroughness.
@@ -382,6 +378,14 @@ Do NOT proceed to planning until the developer explicitly approves.
 **Commit**: `docs: create project roadmap`
 </roadmap_creation>
 
+<persistence>
+MANDATORY: Both `.planning/SPEC.md` and `.planning/ROADMAP.md` must exist on disk before reporting completion.
+
+If either file was not written (permissions issue, path problem), STOP and report the blocker to the user. Do NOT report success without persisted artifacts.
+
+These files are consumed by every downstream workflow. Artifacts that exist only in chat context will be lost on context compression, leaving the project in an unrecoverable state.
+</persistence>
+
 <success_criteria>
 Init is DONE when ALL of these are true:
 
@@ -407,11 +411,11 @@ Report to the user what was accomplished, then present the next step:
 - `.planning/SPEC.md` — living specification (requirements, constraints, decisions)
 - `.planning/ROADMAP.md` — phased execution plan with success criteria
 
-**Next step:** `/gsdd:plan` — create a detailed plan for Phase 1
+**Next step:** `/gsdd-plan` — create a detailed plan for Phase 1
 
 Also available:
-- `/gsdd:progress` — check overall project status
-- `/gsdd:map-codebase` — map existing codebase (if not already done)
+- `/gsdd-progress` — check overall project status
+- `/gsdd-map-codebase` — map existing codebase (if not already done)
 
 Consider clearing context before starting the next workflow for best results.
 ---

package/distilled/workflows/pause.md

@@ -12,6 +12,12 @@ Scope boundary: you write a checkpoint file. You do not route, present status, o
 If `.planning/` does not exist, stop and tell the user to run `gsdd init` first.
 </prerequisites>
 
+<runtime_contract>
+Use the `Runtime` type from `.planning/SPEC.md`.
+Infer runtime from the launching surface when obvious: `.claude/` -> `claude-code`, `.codex/` or Codex portable skill -> `codex-cli`, `.opencode/` -> `opencode`, otherwise `other`.
+Checkpoints record `runtime` only — assurance does not apply to state snapshots.
+</runtime_contract>
+
 <process>
 
 <detect_work>
@@ -27,6 +33,8 @@ Store the detected work type as `$WORK_TYPE` (one of: `phase`, `quick`, `generic
 </detect_work>
 
 <gather_state>
+Build a draft checkpoint from artifact truth before asking the user to restate work. The user should correct the draft, not rewrite obvious repo state from scratch.
+
 Ask the user conversationally to fill in the gaps the artifacts cannot answer:
 
 1. **What was completed** this session
@@ -35,14 +43,24 @@ Ask the user conversationally to fill in the gaps the artifacts cannot answer:
 4. **Key decisions** — any decisions made and their rationale
 5. **Blockers** — anything stuck or waiting on external input
 6. **What to do first** when resuming
+7. **Judgment context** — active constraints currently governing the work, any unresolved uncertainty or open questions, the current decision posture (what approach was chosen and why), and anti-regression rules (invariants that must not break). Pre-fill from SPEC.md constraints and APPROACH.md decisions where applicable; ask the user for what is session-specific or undocumented.
 
-Read the relevant artifacts to pre-fill what you can:
+Read the relevant artifacts and current integration surface to pre-fill what you can:
 - For phase work: read the PLAN file and any partial SUMMARY — use these to pre-fill remaining_work and decisions where possible; only ask the user for gaps
 - For quick tasks: read the quick task PLAN and LOG.md entry — same pre-fill approach
-- For generic work: all six points must come from the user (no artifacts to derive from); ask all six explicitly
+- For generic work: derive everything you can from repo state first, then ask only for what remains unknown
+
+Question budget:
+- Ask at most 3 high-signal questions total
+- Prefer confirmation/correction prompts over open-ended recap prompts
+- If repo/artifact truth already answers a point, do not ask the user to repeat it
 </gather_state>
 
 <write_checkpoint>
+Before writing the new checkpoint, run `gsdd file-op delete .planning/.continue-here.bak --missing ok` to clear the prior session backup. This is cleanup-only and should no-op safely if the backup is absent.
+
+When the current branch/worktree is known to be evidence-only, stale/spent, or otherwise not the next intended execution surface, say that explicitly in `<current_state>`, `<remaining_work>`, and `<anti_regression>`. Do not flatten evidence-only local state into the same continuity story as the next execution surface.
+
 Write `.planning/.continue-here.md` with the following structure:
 
 ```markdown
@@ -50,6 +68,7 @@ Write `.planning/.continue-here.md` with the following structure:
 workflow: $WORK_TYPE
 phase: $PHASE_NAME_OR_NULL
 timestamp: $ISO_8601_TIMESTAMP
+runtime: $INFERRED_RUNTIME
 ---
 
 <current_state>
@@ -75,11 +94,28 @@ timestamp: $ISO_8601_TIMESTAMP
 <next_action>
 [The specific first thing to do when resuming — concrete enough for a fresh session to act on immediately]
 </next_action>
+
+<judgment>
+<active_constraints>
+[Constraints currently governing the work — from SPEC.md, APPROACH.md, or discovered during execution. Include constraint source.]
+</active_constraints>
+<unresolved_uncertainty>
+[Open questions, unvalidated assumptions, areas where the approach may need revision. Include why each matters.]
+</unresolved_uncertainty>
+<decision_posture>
+[Current strategic direction — what approach was chosen, what alternatives were rejected, what the governing trade-off is.]
+</decision_posture>
+<anti_regression>
+[Rules that must hold — invariants, previously-verified behaviors that must not break, scope boundaries that must not expand.]
+</anti_regression>
+</judgment>
 ```
 
 The checkpoint is project-scoped (lives at `.planning/.continue-here.md`, not inside a phase directory) so resume always knows where to look.
 </write_checkpoint>
 
+**MANDATORY: `.planning/.continue-here.md` must exist on disk after writing. If the file was not created, STOP and report the failure. The entire purpose of this workflow is to persist context — a failed write means the pause did nothing.**
+
 <advisory_git>
 Read `.planning/config.json` for the `gitProtocol` section. If config.json cannot be read, skip git advice.
 
@@ -92,7 +128,7 @@ Example suggestion: "You may want to commit your current changes as a WIP before
 Report to the user:
 - Checkpoint location: `.planning/.continue-here.md`
 - Work type captured (phase/quick/generic)
-- How to resume: run the `/gsdd:resume` workflow in the next session
+- How to resume: run the `/gsdd-resume` workflow in the next session
 </confirm>
 
 </process>
@@ -100,7 +136,7 @@ Report to the user:
 <success_criteria>
 - [ ] Active work context detected (phase, quick, or generic)
 - [ ] User provided missing context via conversation
-- [ ] `.planning/.continue-here.md` created with frontmatter and all 6 sections
+- [ ] `.planning/.continue-here.md` created with frontmatter, all 6 sections, and <judgment> block
 - [ ] Advisory git suggestion presented (not mandated)
 - [ ] User informed of checkpoint location and resume instructions
 </success_criteria>
@@ -111,10 +147,10 @@ Report to the user what was accomplished, then present the next step:
 ---
 **Completed:** Session paused — created `.planning/.continue-here.md` (checkpoint file).
 
-**Next step (next session):** `/gsdd:resume` — restore context and continue where you left off
+**Next step (next session):** `/gsdd-resume` — restore context and continue where you left off
 
 Also available:
-- `/gsdd:progress` — check project status without restoring checkpoint context
+- `/gsdd-progress` — check project status without restoring checkpoint context
 
 Consider clearing context before starting the next workflow for best results.
 ---

package/distilled/workflows/plan-milestone-gaps.md

@@ -0,0 +1,183 @@
+<role>
+You are the GAP CLOSURE PLANNER. Your job is to read the audit results from a completed milestone audit and create focused phases in ROADMAP.md that will close the identified gaps, so the milestone can be re-audited and eventually completed.
+
+Core mindset: gaps are specific and concrete — name them, group them logically, and create phases that close them. Do not create vague "cleanup" phases.
+
+Scope boundary: you create gap closure phases in ROADMAP.md. You do not plan the phases — that is `/gsdd-plan` territory. You do not close the gaps yourself.
+</role>
+
+<prerequisites>
+`.planning/ROADMAP.md` must exist.
+`.planning/SPEC.md` must exist.
+A `.planning/v*-MILESTONE-AUDIT.md` file must exist with `status: gaps_found`.
+
+If no audit file exists: stop and direct the user to run `/gsdd-audit-milestone` first.
+If audit status is `passed`: stop and direct the user to run `/gsdd-complete-milestone` instead.
+</prerequisites>
+
+<load_context>
+Before starting, read these files:
+
+1. `.planning/v*-MILESTONE-AUDIT.md` (most recent) — gap details, requirement failures, integration issues, broken flows
+2. `.planning/SPEC.md` — requirement priorities (v1/v2), requirement descriptions
+3. `.planning/ROADMAP.md` — existing phases (to determine phase numbering continuation)
+</load_context>
+
+<process>
+
+## 1. Load Audit Gaps
+
+Parse the MILESTONE-AUDIT.md. Extract all gap objects:
+- **Requirement gaps** — requirements marked unsatisfied with reason and missing evidence
+- **Integration gaps** — cross-phase wiring failures (e.g., module A exports not consumed by module B)
+- **Flow gaps** — E2E user flows broken at specific steps
+
+For each gap, note:
+- Gap type (requirement / integration / flow)
+- Priority: derive from SPEC.md (`v1` requirement = must close, `v2` = optional)
+- What is missing or broken
+
+If no gaps are found after parsing, stop and direct the user to `/gsdd-complete-milestone`.
+
+## 2. Prioritize Gaps
+
+Sort gaps into two buckets:
+
+**Must close** (v1 requirements, or integration/flow gaps affecting v1 requirements):
+- These must become phases. The milestone cannot complete until they are resolved.
+
+**Optional** (v2 requirements, low-severity integration gaps):
+- Present to user: include in this milestone or defer?
+
+Present the gap summary:
+
+```
+## Gap Analysis
+
+Must close ([N] gaps):
+- [REQ-ID]: [description] — [reason it failed]
+- Integration [Phase X → Phase Y]: [what is missing]
+- Flow "[flow name]": broken at [step]
+
+Optional ([M] gaps):
+- [REQ-ID]: [description] (v2 priority)
+```
+
+**STOP. Ask the user which optional gaps to include.**
+
+Exception: if `config.json -> mode` is `yolo`, include all must-close gaps and skip optional gaps.
+
+## 3. Group Gaps into Phases
+
+Cluster the selected gaps into logical phases using these rules:
+- Same affected phase or subsystem → combine into one gap closure phase
+- Dependency order: fix broken foundations before wiring dependents
+- Keep phases focused: 2-4 tasks each
+- Name phases after what they fix, not just "Gap Closure"
+
+**Example grouping:**
+
+```
+Gaps:
+- AUTH-03 unsatisfied (password reset flow missing)
+- Integration: Session → Dashboard (auth header not passed)
+- Flow "Reset password" broken at email dispatch
+
+→ Phase N: "Auth Reset Flow"
+  - Implement password reset email dispatch
+  - Wire session auth header to dashboard API calls
+  - Test reset flow end-to-end
+```
+
+## 4. Determine Phase Numbers
+
+Find the highest existing phase number in ROADMAP.md. New gap closure phases continue from there.
+
+Example: if ROADMAP.md has Phases 1–5, gap closure phases start at Phase 6.
+
+## 5. Present Gap Closure Plan
+
+Present the proposed gap closure phases for confirmation:
+
+```
+## Gap Closure Plan
+
+Milestone: v[X.Y]
+Gaps to close: [N] requirement, [M] integration, [K] flow
+
+**Phase [N]: [Name]**
+Closes:
+- [REQ-ID]: [description]
+- Integration: [from] → [to]
+Estimated tasks: [2-4]
+
+**Phase [N+1]: [Name]**
+Closes:
+- [REQ-ID]: [description]
+Estimated tasks: [2-4]
+```
+
+**STOP. Wait for user confirmation before writing to ROADMAP.md.**
+
+If the user requests adjustments, revise and re-present.
+
+## 6. Add Phases to ROADMAP.md
+
+Once confirmed, append the gap closure phases below the existing phases in ROADMAP.md:
+
+```markdown
+### v[X.Y] Gap Closure
+
+- [ ] **Phase [N]: [Name]** — [goal]
+- [ ] **Phase [N+1]: [Name]** — [goal]
+```
+
+If the current ROADMAP.md already has a milestone section for this version, add the phases under it.
+
+## 7. Create Phase Directories
+
+Create a directory for each gap closure phase:
+
+```
+.planning/phases/[NN]-[phase-name-kebab]/
+```
+
+No files inside — `/gsdd-plan` populates them.
+
+</process>
+
+<success_criteria>
+- [ ] MILESTONE-AUDIT.md loaded and all gaps parsed
+- [ ] Gaps categorized by type (requirement / integration / flow) and priority (must / optional)
+- [ ] User confirmed which optional gaps to include
+- [ ] Gaps grouped into logical phases with clear goals
+- [ ] Phase numbering continues from highest existing phase
+- [ ] User confirmed gap closure plan before ROADMAP.md was updated
+- [ ] ROADMAP.md updated with new gap closure phases
+- [ ] Phase directories created
+</success_criteria>
+
+**MANDATORY: `.planning/ROADMAP.md` must be updated on disk before this workflow is complete. If the write fails, STOP and report the failure. Without the updated ROADMAP, the phase cycle cannot begin.**
+
+<completion>
+Report to the user what was created, then present the next step:
+
+---
+**Completed:** Gap closure plan created.
+
+Created:
+- [N] gap closure phases in `ROADMAP.md` (Phases [start]–[end])
+- Phase directories in `.planning/phases/`
+
+Gaps addressed:
+- [brief summary of what the phases close]
+
+**Next step:** `/gsdd-plan [N]` — plan Phase [N]: [phase name]
+
+After all gap closure phases complete:
+- `/gsdd-audit-milestone` — re-audit to verify gaps are closed
+- `/gsdd-complete-milestone` — archive when audit passes
+
+Consider clearing context before starting the next workflow for best results.
+---
+</completion>

package/distilled/workflows/plan.md

@@ -13,17 +13,42 @@ Before starting, read these files:
 4. `.planning/phases/*-APPROACH.md` - approach decisions from user discussion (if exists)
 5. `.planning/phases/*-PLAN.md` - any previous plans that affect this phase
 6. Relevant source code - if this phase builds on existing code, read the key files
-
+7. `.planning/phases/*-SUMMARY.md` for the prior completed phase - if a `<judgment>` section is present, read all four sub-sections. The `<judgment>` carries forward active constraints, unresolved uncertainty, decision posture, and anti-regression rules from the prior phase. Honor these as input context alongside SPEC.md decisions and APPROACH.md choices.
+8. **Session-boundary fallback:** If no prior completed phase SUMMARY.md with a `<judgment>` section was found in step 7, check whether `.planning/.continue-here.bak` exists. If it does, read its `<judgment>` section and honor the same four sub-sections as input context. After reading, run `gsdd file-op delete .planning/.continue-here.bak --missing ok` (auto-clean: the judgment has been absorbed into this session's context).
 Identify the target phase: the first phase with status `[ ]` or `[-]` in `ROADMAP.md`.
 </load_context>
 
+<integration_surface_check>
+Before planning roadmap work, inspect the live integration surface separately from checkpoint or planning artifacts:
+- current branch name
+- divergence from `main` when available
+- staged, unstaged, and untracked local truth
+- whether the current branch appears stale/spent or mixed-scope
+
+If the planning truth says "next phase is X" but the git/worktree truth says the current branch is a stale or mixed execution surface, warn explicitly and treat the dirty branch as evidence only. Do not silently assume the checked-out branch is the right planning surface just because it exists.
+</integration_surface_check>
+
+<runtime_contract>
+Use the `Runtime` and `Assurance` types from `.planning/SPEC.md`.
+Infer runtime from the launching surface when obvious: `.claude/` -> `claude-code`, `.codex/` or Codex portable skill -> `codex-cli`, `.opencode/` -> `opencode`, otherwise `other`.
+Assurance is ordered: `unreviewed` -> `self_checked` -> `cross_runtime_checked`.
+Same-runtime helpers never count as cross-runtime evidence.
+</runtime_contract>
+
+<assurance_check>
+After `<load_context>`, compare the current planning pass against the strongest upstream artifact available: same-phase prior plan first, otherwise prior completed phase SUMMARY or VERIFICATION.
+Use `unreviewed` before any checker result, `self_checked` for planner self-check or same-runtime checker, and `cross_runtime_checked` only for a different runtime/vendor checker.
+If current assurance is lower, write a structured `<assurance_check>` near the top of the plan body with `source_artifact`, `source_runtime`, `source_assurance`, `current_runtime`, `current_assurance`, `status`, and `warning`.
+If upstream runtime/assurance is missing, use `status: unknown`.
+</assurance_check>
+
 <context_fidelity>
 Before planning, acknowledge what is locked:
-
 - Decisions in `.planning/SPEC.md` "Key Decisions" - do not revisit them.
 - Decisions in APPROACH.md "Implementation Decisions" - these are user-validated choices. Implement the chosen approaches, not alternatives. "Agent's Discretion" items give you flexibility.
 - Patterns from previous phases - match existing conventions. Do not introduce new patterns without cause.
 - Deferred items - items marked v2, nice-to-have, or out of scope in SPEC.md or APPROACH.md. Do not plan for them.
+- Cross-check: if SPEC.md and APPROACH.md disagree on whether an item is must-have or deferred, stop and ask the user before planning. Do not silently adopt one classification over the other.
 
 If you need to challenge a locked decision: stop, ask the developer, and document the new decision explicitly.
 </context_fidelity>
@@ -58,9 +83,30 @@ Write to `.planning/research/{phase_number}-RESEARCH.md` with sections:
 - Research for this phase already exists and is still fresh
 - The phase uses only technologies already established in previous phases
 
-Quality gate: do not proceed to goal-backward planning if you have unresolved uncertainties about the implementation approach.
+Quality gate: do not proceed to goal-backward planning if you have unresolved uncertainties about the implementation approach. If research was skipped (skip conditions above apply), document the skip reason in the plan Notes section so the plan checker can verify the skip was justified.
 </research_check>
 
+<spec_quality_check>
+### When This Runs
+After research_check, before goal_backward_planning.
+
+### Classify Each Phase Requirement and Success Criterion
+For each requirement and success criterion in this phase, assign one of:
+- **Resolved**: the behavior is testable, the Done-When is unambiguous, and the decision is locked (codebase fact or explicit SPEC.md/APPROACH.md decision). Proceed.
+- **Open**: the requirement depends on a product or UX decision that has not been made. Cannot proceed.
+- **Ambiguous**: there are two or more reasonable interpretations of what "done" means. Cannot proceed.
+
+Trigger questions per item:
+- Is the Done-When criterion specific enough to write a verify command for?
+- Does this require a product or UX decision that is absent from SPEC.md, APPROACH.md, or ROADMAP.md?
+- Would two different developers reasonably implement this differently based only on the requirement text?
+
+### Quality Gate
+- If all items are **Resolved**: proceed to goal_backward_planning.
+- If any item is **Open** or **Ambiguous**: STOP. Report each item with the specific question that would resolve it. Do not produce an execution-ready plan until the user resolves these items.
+- Exception — **minor technical ambiguity** (e.g., exact error message wording, logging format) that does not change user-facing behavior: note it as a warning in the plan Notes section and proceed. Do not use this exception for behavioral or acceptance-criteria ambiguity.
+</spec_quality_check>
+
 <goal_backward_planning>
 Plan backward from success criteria.
 
@@ -96,6 +142,8 @@ phase: 01-foundation
 plan: 01
 type: execute
 wave: 1
+runtime: claude-code
+assurance: self_checked
 depends_on: []
 files-modified:
   - src/lib/auth.ts
@@ -196,6 +244,8 @@ phase: 01-foundation
 plan: 01
 type: execute
 wave: 1
+runtime: claude-code
+assurance: self_checked
 depends_on: []
 files-modified:
   - src/routes/users.ts
@@ -231,6 +281,16 @@ must_haves:
 1. [Observable truth from ROADMAP.md]
 2. [Observable truth from ROADMAP.md]
 
+<checks>
+<plan_check>
+checker: self | cross_runtime
+checker_runtime: claude-code
+status: passed | issues_found | skipped
+blocking: false
+notes: [What the checker actually validated or why it was skipped]
+</plan_check>
+</checks>
+
 ## Tasks
 
 <task id="01-01" type="auto">
@@ -250,6 +310,8 @@ must_haves:
 ## Notes
 [Gotchas, implementation notes, or explicit assumptions]
 ```
+
+**MANDATORY: You MUST write PLAN.md to disk at `.planning/phases/{phase_dir}/{plan_id}-PLAN.md`. Output to conversation alone is NOT sufficient. If this file is not written to disk, planning is NOT complete.**
 </plan_structure>
 
 <approach_exploration>
@@ -340,10 +402,9 @@ After the planner produces a draft plan, an independent checker reviews it in fr
 5. `scope_sanity` - plans are sized so an executor can complete them without context collapse
 6. `must_have_quality` - success criteria are specific, observable, and reflected in tasks
 7. `context_compliance` - locked decisions are honored and deferred ideas stay out of scope
-8. `approach_alignment` - when APPROACH.md exists, plans implement the chosen approaches, not alternatives. Blocker if plan contradicts an explicit user choice. Warning if plan drifts from recommendation without justification. Skipped when no APPROACH.md is provided.
-
+8. `goal_achievement` - the plan, if executed perfectly, actually achieves the stated phase goal: goal addressed (tasks deliver the goal), success criteria reachable (each criterion traceable to a task verify output), and outcome observable (a human or automated check can confirm the goal was met)
+9. `approach_alignment` - when APPROACH.md exists, plans implement the chosen approaches, not alternatives. Blocker if plan contradicts an explicit user choice. Warning if plan drifts from recommendation without justification. Skipped when no APPROACH.md is provided.
 ### Invoking the Checker
-
 1. If `.planning/config.json` has `workflow.planCheck: false`, skip the independent checker. Perform the planner self-check below and report `reduced_assurance`.
 2. If plan checking is enabled, check if your runtime provides a `gsdd-plan-checker` agent.
 3. If a native checker agent is available, invoke it in a fresh context with only these explicit inputs:
@@ -359,7 +420,7 @@ After the planner produces a draft plan, an independent checker reviews it in fr
      "summary": "One sentence overall assessment",
      "issues": [
        {
-         "dimension": "requirement_coverage | task_completeness | dependency_correctness | key_link_completeness | scope_sanity | must_have_quality | context_compliance | approach_alignment",
+         "dimension": "requirement_coverage | task_completeness | dependency_correctness | key_link_completeness | scope_sanity | must_have_quality | context_compliance | goal_achievement | approach_alignment",
          "severity": "blocker | warning",
          "description": "What is wrong",
          "plan": "01-PLAN",
@@ -374,9 +435,12 @@ After the planner produces a draft plan, an independent checker reviews it in fr
 6. If the checker returns `issues_found`, revise the existing plan files only where needed, then invoke the checker again.
 7. Maximum 3 checker cycles total. If blockers remain after cycle 3, stop and escalate to the user instead of pretending the plan is ready.
 8. If no native checker agent is available in your runtime, perform the planner self-check below and explicitly report `reduced_assurance` rather than claiming an independent checker ran.
-
+When the checker outcome is finalized, write the result into the plan artifact:
+- checker ran in same runtime or planner self-check only -> set frontmatter `assurance: self_checked`
+- checker ran in a different runtime/vendor and passed -> set frontmatter `assurance: cross_runtime_checked`
+- draft exists before any checker result is recorded -> keep `assurance: unreviewed`
+- record the structured outcome in the plan's `<checks>` block; do not leave the checker result only in chat context
 ### Orchestration Summary
-
 After plan checking completes, report:
 - target phase
 - whether independent plan checking ran
@@ -400,7 +464,6 @@ For every success criterion from `ROADMAP.md`:
 - [ ] At least one task produces an artifact that satisfies it
 - [ ] The task's `<verify>` section checks it specifically
 - [ ] The criterion is covered explicitly, not only implied
-
 ### Check Task Completeness
 For each task:
 - [ ] The `<files>` section lists every file to create or modify
@@ -429,6 +492,8 @@ Planning is done when all of these are true:
 - [ ] Success criteria from `ROADMAP.md` are represented as must-haves
 - [ ] Goal-backward derivation from criteria to artifacts to key links to tasks is explicit
 - [ ] Every plan has frontmatter with `phase`, `plan`, `type`, `wave`, `depends_on`, `files-modified`, `autonomous`, `requirements`, and `must_haves`
+- [ ] Every plan frontmatter records `runtime` and `assurance`
+- [ ] Every plan records checker outcome in a structured `<checks>` block
 - [ ] Every task has XML structure with `id`, `type`, `files`, `action`, `verify`, and `done`
 - [ ] Every task has at least one runnable verify command
 - [ ] Plan sizing stays within 2-5 tasks, preferring 2-3
@@ -442,11 +507,11 @@ Report to the user what was accomplished, then present the next step:
 ---
 **Completed:** Phase planning — created `.planning/phases/{phase_dir}/{plan_id}-PLAN.md`.
 
-**Next step:** `/gsdd:execute` — execute the plan
+**Next step:** `/gsdd-execute` — execute the plan
 
 Also available:
-- `/gsdd:plan` — create additional plans for the same phase (if multi-wave)
-- `/gsdd:progress` — check overall project status
+- `/gsdd-plan` — create additional plans for the same phase (if multi-wave)
+- `/gsdd-progress` — check overall project status
 
 Consider clearing context before starting the next workflow for best results.
 ---