gsdd-cli 0.27.0 → 0.28.0

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

@@ -1,204 +0,0 @@
-<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>
-
-<repo_root_helper_contract>
-All `node .planning/bin/gsdd.mjs ...` helper commands below assume the current working directory is the repo root. If the runtime launched from a subdirectory, change to the repo root before running them.
-</repo_root_helper_contract>
-
-<lifecycle_preflight>
-Before writing ROADMAP gap-closure phases or phase directories, run:
-
-- `node .planning/bin/gsdd.mjs lifecycle-preflight plan-milestone-gaps`
-
-If the preflight result is `blocked`, STOP and report the blocker. This workflow intentionally mutates planning truth, so it must not proceed through pre-existing planning-state drift.
-</lifecycle_preflight>
-
-<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.
-
-## 8. Rebaseline Planning Fingerprint
-
-After confirming the ROADMAP update and phase directories exist, run:
-
-- `node .planning/bin/gsdd.mjs session-fingerprint write --allow-changed ROADMAP.md`
-
-This records the user-confirmed ROADMAP mutation so the recommended `/gsdd-plan [N]` handoff does not immediately block on expected `planning_state_drift`. The `--allow-changed ROADMAP.md` guard must fail if `SPEC.md` or `config.json` also drifted after preflight; stop and reconcile that unexpected drift instead of rebaselining it. Do not run this if the ROADMAP write failed or the phase directories are missing.
-
-</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
-- [ ] `session-fingerprint write` ran after the reviewed ROADMAP update so `/gsdd-plan [N]` is not stranded by expected planning drift
-</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>