gsdd-cli 0.3.1 → 0.16.1

package/distilled/workflows/execute.md

@@ -11,10 +11,70 @@ CRITICAL: Read every file below before performing any other actions. This is you
 1. `.planning/phases/{plan_id}-PLAN.md` or the target plan file provided by the orchestrator
 2. `.planning/SPEC.md` - requirements, constraints, and current state
 3. `.planning/ROADMAP.md` - phase goal and success criteria
-4. Previous phase summaries if they are genuinely relevant
+4. Previous phase summaries beyond the immediately prior completed phase, if they are genuinely relevant
 5. Relevant source files listed in the plan's `<files>` sections
+6. `.planning/phases/*-SUMMARY.md` for the immediately prior completed phase - if a `<judgment>` section is present, read all four sub-sections. Honor `<anti_regression>` rules as execution constraints. Use `<active_constraints>` and `<decision_posture>` to calibrate deviation decisions.
+7. **Session-boundary fallback:** If no prior completed phase SUMMARY.md with a `<judgment>` section was found in step 6, check whether `.planning/.continue-here.bak` exists. If it does, read its `<judgment>` section. Honor `<anti_regression>` rules as execution constraints and use `<active_constraints>` and `<decision_posture>` to calibrate deviation decisions. After reading, run `gsdd file-op delete .planning/.continue-here.bak --missing ok` (auto-clean).
 </load_context>
 
+<runtime_contract>
+Execution uses the same `Runtime` and `Assurance` types as planning and verification.
+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>
+Before executing tasks, read the plan artifact's `runtime`, `assurance`, and structured `<plan_check>` result.
+Use `unreviewed` before any executor check, `self_checked` for self/same-runtime checking, and `cross_runtime_checked` only for a different runtime/vendor checker.
+If execution begins from a stronger plan artifact into a weaker execution context, emit a structured `<assurance_check>` with `source_artifact`, `source_runtime`, `source_assurance`, `current_runtime`, `current_assurance`, `status`, and `warning`.
+If plan runtime/assurance is missing, use `status: unknown`.
+</assurance_check>
+
+<multi_plan_orchestration>
+A phase often contains multiple plans. When invoked at the phase level (no specific plan provided), run this orchestration step first.
+
+### Discover Plans and Group by Wave
+
+1. Scan `.planning/phases/{phase_dir}/` for all `*-PLAN.md` files.
+2. For each plan, read its frontmatter `wave` field (default: `wave: 1` if absent).
+3. Group plans by wave number. Collect the set of distinct wave numbers and sort them ascending.
+4. Check for `*-SUMMARY.md` files — plans that already have a matching SUMMARY are complete; skip them.
+
+Present to the user:
+```
+Phase {N} — {Name}
+Plans to execute:
+  Wave 1: {plan-01-NAME.md}, {plan-02-NAME.md}
+  Wave 2: {plan-03-NAME.md}
+Plans already complete (have SUMMARY): {list}
+```
+
+Confirm with the user before proceeding if any existing SUMMARYs look stale or incomplete.
+
+### Execute Wave by Wave
+
+For each wave in ascending order:
+1. Execute each plan in the wave **sequentially** using the `<execution_loop>` below.
+2. After each plan: verify `{plan_id}-SUMMARY.md` exists on disk.
+3. If a plan produces a SUMMARY, log: `Wave {W} / Plan {NN}: ✓ complete`.
+4. If a plan fails verification 3 times: STOP, report which plan failed, do not continue to the next wave.
+5. After all plans in a wave are complete, advance to the next wave.
+
+### Aggregate Summary
+
+After all waves complete, produce a brief aggregate report:
+```
+Phase {N} complete.
+Plans executed: {count}
+Waves: {W} total
+Key deliverables: [bullet list of what was built, one line per plan]
+Next step: /gsdd-verify {N} — verify the phase goal was achieved
+```
+
+If only a single plan was provided (the common case), skip this section entirely and go straight to the `<execution_loop>`.
+</multi_plan_orchestration>
+
 <execution_loop>
 For each task in the plan, follow this loop:
 
@@ -28,8 +88,8 @@ For each task in the plan, follow this loop:
 
 ### Frontmatter And Task Semantics
 
-The executor consumes the plan schema defined by `/gsdd:plan`:
-- frontmatter keys: `phase`, `plan`, `type`, `wave`, `depends_on`, `files-modified`, `autonomous`, `requirements`, `must_haves`
+The executor consumes the plan schema defined by `/gsdd-plan`:
+- frontmatter keys: `phase`, `plan`, `type`, `wave`, `depends_on`, `files-modified`, `autonomous`, `requirements`, `must_haves`, `tdd`
 - task types:
   - `type="auto"` - proceed without pausing
   - `type="checkpoint:user"` - stop for a required user decision or human-only step
@@ -61,6 +121,27 @@ Before modifying any existing behavior, run a ripple check:
    When removing an import, function, or variable, grep for all usages before deleting it.
    This catches dead references before they turn into broken execution paths.
 
+### TDD Execution
+
+If a task frontmatter includes `tdd: true`, switch to RED-GREEN-REFACTOR cycle for that task:
+
+**RED — Write the failing test first**
+1. Write the test that describes the intended behavior.
+2. Run the test. Confirm it **fails** with the right failure (not a syntax error — an assertion failure that reflects what is missing).
+3. Do not proceed until you see the expected red failure.
+
+**GREEN — Minimal implementation**
+1. Write the smallest amount of code that makes the test pass.
+2. Run the test. Confirm it passes.
+3. Do not over-engineer at this stage — add only what the test requires.
+
+**REFACTOR — Clean up**
+1. Improve structure, naming, and clarity without changing behavior.
+2. Run the tests again. Confirm they still pass.
+3. Log the RED→GREEN→REFACTOR cycle in SUMMARY.md under the task entry.
+
+Non-TDD tasks skip this protocol and proceed with the standard verification flow.
+
 ### Local Verification
 Before reporting a task complete:
 - run the task's `<verify>` checks
@@ -72,23 +153,56 @@ Before reporting a task complete:
 ### Git Guidance
 
 ```bash
-# Stage only the files you intend to include.
+# Stage individual files — never "git add ." or "git add -A"
 git add src/routes/users.ts src/app/users/page.tsx tests/users.route.test.ts
 
-# Commit only when it matches the repo or user workflow.
+# Commit message — conventional type prefix
 git commit -m "feat: wire users page to real route"
 ```
 
+**Conventional commit type reference** (advisory — repo/user conventions override):
+
+| Type | Use when |
+|------|----------|
+| `feat` | New user-facing feature |
+| `fix` | Bug fix |
+| `test` | Adding or updating tests only |
+| `refactor` | Code restructure with no behavior change |
+| `perf` | Performance improvement |
+| `docs` | Documentation only |
+| `style` | Formatting, whitespace, no logic change |
+| `chore` | Build, tooling, dependencies |
+
 Git rules:
-- Repo and user conventions win first.
+- **Repo and user conventions win first.** This table is a reference, not a mandate.
 - `.planning/config.json -> gitProtocol` is advisory only.
-- Do not mention phase, plan, or task IDs in commit or PR names unless explicitly requested.
+- **Stage only files listed in the plan's `files-modified` frontmatter.** Never use `git add .` or `git add -A`. If you need to stage a file not in `files-modified`, record it as a deviation.
+- **Wrong-branch check:** Before significant implementation begins, verify HEAD is not `main` or `master` if repo convention expects a feature branch; if it is, STOP and hard-warn the user before proceeding.
+- **Transition-safety warning pass:** Before significant implementation begins, inspect staged, unstaged, untracked, unpushed, PR-less, stale/spent, and mixed-scope branch signals. Warn on these conditions explicitly; ordinary delivery risk remains warning-level unless the current branch is clearly the wrong integration surface for the planned work.
+- Do not mention phase, plan, task, or requirement IDs, or internal milestone labels, in commit messages, PR titles, or PR bodies unless explicitly requested.
 - Do not force one commit per task unless the repo or user asked for that.
+- **PR creation:** After committing work on a feature branch, create a PR before reporting completion unless the user or plan explicitly says otherwise.
 </execution_loop>
 
 <deviation_rules>
 Reality rarely matches the plan perfectly. Handle deviations with these rules in priority order:
 
+### Structured mismatch taxonomy
+
+All execution-time deltas must be classified as one of:
+- `factual_discovery` - the repo/runtime reality differs from the plan in a concrete, local way (wrong path, stale API shape, moved module, outdated dependency assumption)
+- `intent_scope_change` - the requested outcome or scope needs to change
+- `architecture_risk_conflict` - the planned approach creates a structural or risk problem that needs a different design
+
+Treat only hard mismatches as blocking by default:
+- malformed or missing contract sections in the input artifact
+- unresolved blocking checker findings
+- any `intent_scope_change`
+- any `architecture_risk_conflict`
+- a `factual_discovery` that is not deterministically recoverable
+
+If a `factual_discovery` is local, deterministic, and recoverable, proceed with a recorded delta instead of bouncing immediately back to planning. That delta must be surfaced later in SUMMARY.md for downstream review and milestone audit.
+
 ### Rule 1: Auto-Fix Bugs
 
 **Trigger:** Code doesn't work as intended (broken behavior, errors, incorrect output)
@@ -157,18 +271,24 @@ Keep the update factual and compact:
 ```
 
 ### 2. Update ROADMAP.md Phase Status
-Use the roadmap template's status grammar:
+Do not hand-edit the ROADMAP checkbox line. Use the status-aware helper instead:
 
-```markdown
-- [x] **Phase {N}: {Name}** - {Goal}
-```
+- Run `gsdd phase-status {N} done` when this plan completes the phase.
+- Run `gsdd phase-status {N} in_progress` when this plan completes but more plans remain in the phase.
 
-If the phase is partially complete and more plans remain, use `[-]` instead of `[x]`.
+The helper owns the `[ ]` / `[-]` / `[x]` mutation for `.planning/ROADMAP.md`.
 
 ### 3. Write Phase Summary
 Create `.planning/phases/{phase_dir}/{plan_id}-SUMMARY.md` with:
 
 ```markdown
+---
+phase: 01-foundation
+plan: 01
+runtime: codex-cli
+assurance: self_checked
+---
+
 # Phase {N}: {Name} - Plan {NN} Summary
 
 **Completed**: {date}
@@ -178,10 +298,58 @@ Create `.planning/phases/{phase_dir}/{plan_id}-SUMMARY.md` with:
 **Decisions Made**: {new decisions, if any}
 **Notes for Verification**: {anything the verifier should know}
 **Notes for Next Work**: {anything the next planner should know}
+
+<checks>
+<executor_check>
+checker: self | cross_runtime
+checker_runtime: codex-cli
+status: passed | issues_found | skipped
+blocking: false
+notes: [What the executor checker validated or why it was skipped]
+</executor_check>
+</checks>
+
+<handoff>
+plan_runtime: claude-code
+plan_assurance: cross_runtime_checked
+plan_check_status: passed
+execution_runtime: codex-cli
+execution_assurance: self_checked
+executor_check_status: passed
+hard_mismatches_open: false
+</handoff>
+
+<deltas>
+- class: factual_discovery | intent_scope_change | architecture_risk_conflict
+  impact: recoverable | blocking
+  disposition: proceeded | escalated
+  summary: [What changed and why]
+</deltas>
+
+<judgment>
+<active_constraints>
+[Constraints that governed this phase and carry forward to future work]
+</active_constraints>
+<unresolved_uncertainty>
+[Open questions or unvalidated assumptions the next phase should be aware of]
+</unresolved_uncertainty>
+<decision_posture>
+[The strategic direction and key trade-offs - what was chosen, what was deferred, what the governing approach is]
+</decision_posture>
+<anti_regression>
+[Invariants established by this phase that must not be broken by future work]
+</anti_regression>
+</judgment>
 ```
 
 **Summary quality gate:** One-liner must be substantive (e.g., "JWT auth with refresh rotation using jose library" not "Authentication implemented"). If the summary one-liner reads like a placeholder, rewrite it before finalizing.
 
+Write the structured sections honestly:
+- `assurance: self_checked` if execution only received self-check or same-runtime checking
+- `assurance: cross_runtime_checked` only when a different runtime/vendor validated the execution artifact
+- include every execution delta in `<deltas>`; do not hide recoverable drift in prose-only notes
+- if a hard mismatch remains open, set `<handoff>.hard_mismatches_open: true` and stop rather than presenting the summary as clean handoff state
+
 Do not invent an inline PLAN task-state mutation scheme if the plan does not define one.
 Summary-driven progress tracking avoids silent drift between the plan contract and what execution actually completed.
 
@@ -245,6 +413,8 @@ Execution is done when all of these are true:
 - [ ] `.planning/SPEC.md` current state is updated accurately
 - [ ] `ROADMAP.md` uses `[ ]`, `[-]`, `[x]` consistently
 - [ ] `SUMMARY.md` is written
+- [ ] `SUMMARY.md` frontmatter records `runtime` and `assurance`
+- [ ] `SUMMARY.md` includes structured `<checks>`, `<handoff>`, and `<deltas>` sections
 - [ ] Self-check passed
 - [ ] Any git actions honor repo or user conventions and `.planning/config.json`
 </success_criteria>
@@ -255,15 +425,14 @@ Report to the user what was accomplished, then present the next step:
 ---
 **Completed:** Plan execution — created `.planning/phases/{phase_dir}/{plan_id}-SUMMARY.md`.
 
-**Next step:** `/gsdd:verify` — verify that the phase goal was achieved (if `workflow.verifier` is enabled in config.json)
-
-If verifier is disabled or verification already passed:
-**Next step:** `/gsdd:progress` — check status and route to the next phase
+**Next step:** Check `.planning/config.json` → `workflow.verifier`:
+- If `true`: run `/gsdd-verify` — verify that the phase goal was achieved
+- If `false` (or key missing): run `/gsdd-progress` — check status and route to the next phase
 
 Also available:
-- `/gsdd:plan` — plan the next wave (if more plans remain in this phase)
-- `/gsdd:quick` — handle a sub-hour task outside the phase cycle
-- `/gsdd:pause` — save context for later if stopping work
+- `/gsdd-plan` — plan the next wave (if more plans remain in this phase)
+- `/gsdd-quick` — handle a sub-hour task outside the phase cycle
+- `/gsdd-pause` — save context for later if stopping work
 
 Consider clearing context before starting the next workflow for best results.
 ---

package/distilled/workflows/map-codebase.md

@@ -142,7 +142,7 @@ These 4 documents are consumed by downstream GSDD workflows:
 
 | Workflow | Documents Used |
 |----------|---------------|
-| `/gsdd:new-project` | All 4 -- infers Validated requirements from existing capabilities |
+| `/gsdd-new-project` | All 4 -- infers Validated requirements from existing capabilities |
 | `plan` (future) | ARCHITECTURE + CONVENTIONS for implementation planning |
 | `execute` (future) | CONVENTIONS for code style, ARCHITECTURE for file placement |
 | `verify` (future) | CONCERNS for regression awareness |
@@ -230,10 +230,12 @@ Report to the user what was accomplished, then present the next step:
 ---
 **Completed:** Codebase mapping — 4 documents written to `.planning/codebase/` (STACK.md, ARCHITECTURE.md, CONVENTIONS.md, CONCERNS.md).
 
-**Next step:** `/gsdd:new-project` — initialize the project with spec and roadmap
+**Next step:** Choose based on what you need:
+- `/gsdd-new-project` — full project initialization (spec, roadmap, phased delivery)
+- `/gsdd-quick` — brownfield feature work without full ceremony (bug fixes, small features, one-off tasks)
 
 Also available:
-- `/gsdd:map-codebase` — re-map if results need refinement
+- `/gsdd-map-codebase` — re-map if results need refinement
 - Review specific file: read `.planning/codebase/STACK.md`
 
 Consider clearing context before starting the next workflow for best results.

package/distilled/workflows/new-milestone.md

@@ -0,0 +1,249 @@
+<role>
+You are the MILESTONE INITIATOR. Your job is to start a new milestone cycle for an existing project — gather what to build next, define scoped requirements in SPEC.md, and create roadmap phases in ROADMAP.md so the phase lifecycle can begin.
+
+Core mindset: this is a brownfield continuation, not a fresh start. You build on what shipped. Do not re-research capabilities that already exist in the Validated section of SPEC.md.
+
+Scope boundary: you produce updated SPEC.md requirements and a new set of phases in ROADMAP.md. You do not plan phases — that is `/gsdd-plan` territory.
+</role>
+
+<prerequisites>
+`.planning/SPEC.md` must exist (project has been initialized and at least one milestone shipped).
+`.planning/MILESTONES.md` must exist (at least one milestone was completed and archived).
+
+If SPEC.md is missing, the project has not been initialized — run `/gsdd-new-project` instead.
+If MILESTONES.md is missing, no milestone has been completed — complete the current milestone first with `/gsdd-complete-milestone`.
+</prerequisites>
+
+<load_context>
+Before starting, read these files:
+
+1. `.planning/SPEC.md` — project identity, core value, validated requirements, constraints, decisions
+2. `.planning/MILESTONES.md` — what shipped previously, last milestone version and date
+3. `.planning/ROADMAP.md` — collapsed milestone phases, current phase numbering (to determine where to continue)
+4. `.planning/config.json` — `workflow.research`, `researchDepth`, `gitProtocol`
+</load_context>
+
+<integration_surface_check>
+Before mutating milestone truth, inspect the current branch/worktree as a separate provenance surface:
+- current branch
+- divergence from `main`
+- staged / unstaged / untracked local truth
+- whether the branch appears stale/spent or mixed-scope
+
+If milestone truth on disk is local-only or AI-generated draft truth, or if the checked-out branch is clearly not the intended integration surface, say so explicitly before continuing. Do not flatten local draft planning truth into committed repo truth.
+</integration_surface_check>
+
+<process>
+
+## 1. Present What Shipped Last
+
+Read `.planning/MILESTONES.md`. Find the most recent milestone entry. Present it to the user:
+
+```
+Last milestone: v[X.Y] — [Name] (shipped [date])
+
+Delivered:
+- [Accomplishment 1]
+- [Accomplishment 2]
+- [Accomplishment 3]
+```
+
+## 2. Gather What to Build Next
+
+Ask the user what the next milestone should focus on. Explore:
+- What problem does this milestone solve?
+- Who benefits?
+- What is explicitly out of scope for this milestone?
+- Any constraints (deadline, team size, dependencies)?
+
+If a `.planning/MILESTONE-BRIEF.md` exists, use it as the input instead of asking. Note any assumptions inferred from the brief.
+(MILESTONE-BRIEF.md is an optional pre-written document with goals and scope for the next milestone — useful when the user wants to skip the interactive questioning. Create it manually in `.planning/` before running this workflow.)
+
+## 3. Determine Version
+
+Parse the last version from MILESTONES.md (e.g., `v0.5.0`). Suggest the next version:
+- Minor increment for additive work (v0.5.0 → v0.6.0)
+- Major increment for breaking changes or new direction (v0.x.y → v1.0.0)
+
+Confirm version with the user.
+
+## 4. Research Decision
+
+Check `config.json -> workflow.research`. If `true`, ask the user:
+
+> "Research the domain ecosystem for new features before defining requirements?"
+>
+> - "Yes — research first" (recommended for new capability areas)
+> - "No — skip research"
+
+If `workflow.research` is `false` in config, skip to Step 5.
+
+**If research is selected:**
+
+Check `researchDepth` in config (`fast` | `balanced` | `deep`).
+
+Use `<delegate>` blocks to spawn researchers. Pass milestone context to each:
+- What existing capabilities are already validated (from SPEC.md Validated section) — do NOT re-research these
+- What NEW capabilities this milestone is adding
+- Focus on: what's needed for the NEW features only
+
+```
+<delegate>
+**Identity:** Researcher — Stack
+**Instruction:** Read `.planning/templates/roles/researcher.md`, then research what stack additions are needed for the new milestone capabilities.
+
+**Milestone context:** [existing validated capabilities, new capabilities being added]
+**Question:** What library/framework additions are needed? What should NOT be added?
+**Output:** Write findings to `.planning/research/STACK.md`
+**Return:** 2-3 sentence summary of key findings
+</delegate>
+```
+
+Spawn 2-4 researchers in parallel based on researchDepth:
+- `fast`: 1 researcher (features/pitfalls combined)
+- `balanced`: 2 researchers (features, pitfalls)
+- `deep`: 4 researchers (stack, features, architecture, pitfalls)
+
+After researchers complete, synthesize findings inline (no synthesizer delegate needed unless `deep` mode — then spawn the synthesizer delegate).
+
+Present key findings before moving to requirements.
+
+## 5. Define Requirements
+
+Read SPEC.md Must Have section. Identify the requirement ID pattern in use (e.g., `[FLOW-01]`, `[PLAN-01]`).
+
+Based on milestone goals and research findings (if any), define the new Must Have requirements for this milestone:
+
+- Each requirement must be user-centric: "User can X"
+- Each must have a `[Done-When:]` completion criterion
+- IDs follow the existing category pattern or introduce a new category for new capability areas
+- Do NOT duplicate or restate requirements already in the Validated section
+
+Present the full proposed requirements list:
+
+```
+## Proposed Requirements for v[X.Y]
+
+- [ ] **[CAT-01]**: User can X. [Done-When: ...]
+- [ ] **[CAT-02]**: User can Y. [Done-When: ...]
+```
+
+**STOP. Wait for user confirmation before writing to SPEC.md.**
+
+If the user requests changes, revise and re-present.
+
+Once confirmed, add the requirements to SPEC.md's Must Have section.
+
+## 6. Create Roadmap Phases
+
+Determine the starting phase number:
+- Check ROADMAP.md for the highest existing phase number (in collapsed `<details>` blocks or active entries)
+- Check MILESTONES.md for the last phase range (e.g., "Phases 1–5")
+- New phases start from max + 1
+
+Design 2-5 phases that cover all new requirements:
+- Each phase has a goal (one sentence), requirement assignments, and 2-4 success criteria
+- All requirements must be assigned to exactly one phase
+- Verify 100% coverage before writing
+
+Present the proposed roadmap:
+
+```
+## Proposed Phases for v[X.Y]
+
+**Phase [N]: [Name]**
+Goal: [one sentence]
+Requirements: [REQ-IDs]
+Success criteria:
+1. [observable outcome]
+2. [observable outcome]
+
+**Phase [N+1]: [Name]**
+...
+```
+
+**STOP. Wait for user confirmation before writing to ROADMAP.md.**
+
+If the user requests adjustments, revise and re-present.
+
+Once confirmed, add the phases to ROADMAP.md below the collapsed milestone `<details>` block(s):
+
+```markdown
+### [Milestone Name]
+
+- [ ] **Phase [N]: [Name]** — [goal]
+- [ ] **Phase [N+1]: [Name]** — [goal]
+```
+
+Also update the Milestones list at the top of ROADMAP.md:
+
+```markdown
+- 🚧 **v[X.Y] [Name]** — Phases [N]–[M] (in progress)
+```
+
+## 7. Create Phase Directories
+
+Create placeholder directories for each new phase:
+
+```
+.planning/phases/[NN]-[phase-name-kebab]/
+```
+
+No files inside — the `/gsdd-plan` workflow populates them.
+
+## 8. Update SPEC.md Current State
+
+Update the `## Current State` section in SPEC.md:
+
+```markdown
+## Current State
+
+- **Milestone:** v[X.Y] [Name] — IN PROGRESS
+- **Phases:** [N]–[M] (0 of [total] complete)
+- **Blockers:** None
+- **Next:** `/gsdd-plan [N]` to begin Phase [N]
+
+---
+*Last updated: [today] — v[X.Y] milestone started*
+```
+
+</process>
+
+<success_criteria>
+- [ ] MILESTONES.md read and last milestone presented
+- [ ] Milestone goals gathered from user (or MILESTONE-BRIEF.md consumed)
+- [ ] Version confirmed
+- [ ] Research completed if requested (or skipped per config/user)
+- [ ] Requirements defined, user-centric, with Done-When criteria
+- [ ] User confirmed requirements before SPEC.md was updated
+- [ ] All new requirements added to SPEC.md Must Have section
+- [ ] Phase numbering continues from previous milestone
+- [ ] All requirements assigned to phases (100% coverage)
+- [ ] User confirmed roadmap before ROADMAP.md was updated
+- [ ] ROADMAP.md updated with new phases and milestone header
+- [ ] SPEC.md Current State updated
+- [ ] Phase directories created
+</success_criteria>
+
+**MANDATORY: `.planning/SPEC.md` and `.planning/ROADMAP.md` must be updated on disk before this workflow is complete. If either write fails, STOP and report the failure. These are the handoff artifacts — without them, the next session cannot proceed.**
+
+<completion>
+Report to the user what was created, then present the next step:
+
+---
+**Completed:** Milestone v[X.Y] initialized.
+
+Created:
+- [N] new requirements in `SPEC.md` Must Have section
+- [M] new phases in `ROADMAP.md` (Phases [start]–[end])
+- Phase directories in `.planning/phases/`
+
+**Next step:** `/gsdd-plan [N]` — plan Phase [N]: [phase name]
+
+Also available:
+- `/gsdd-progress` — check overall project status
+- `/gsdd-map-codebase` — refresh codebase maps before planning (recommended for large codebases)
+
+Consider clearing context before starting the next workflow for best results.
+---
+</completion>

package/distilled/workflows/new-project.md

@@ -296,7 +296,7 @@ After the subagent research completes, synthesize EVERYTHING into `SPEC.md`:
 6. **Key Decisions are logged** — any choices made during questioning or dictated by the SOTA research.
 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 below.
+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.
 
@@ -306,8 +306,7 @@ Before finishing SPEC.md, explicitly define what the agents are NOT allowed to d
 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 `## Capability & Security Gates` section of the SPEC.md.
+Add these into the new `## Capability & Security Gates` section of the SPEC.md.
 </capability_gates>
 
 ### Quality Check Before Presenting
@@ -412,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.
 ---