@ktpartners/dgs-platform 2.9.0 → 3.3.0

package/deliver-great-systems/workflows/new-milestone.md

@@ -44,12 +44,29 @@ The spec must have status: final.
 
 <process>
 
+## 0. Resolve Paths and Models
+
+```bash
+INIT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs init new-milestone)
+```
+
+Extract from init JSON: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `research_enabled`, `current_milestone`, `current_milestone_name`, `project_exists`, `roadmap_exists`, `state_exists`, `project_path`, `roadmap_path`, `state_path`, `product_milestones_path`, `product_milestones_exists`, `current_project`, `project_root`.
+
+Load planning-tier context files:
+
+```bash
+TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" context load-tier planning --raw 2>/dev/null)
+```
+
+All subsequent steps use these resolved paths. Never reference PROJECT.md, STATE.md, etc. by bare name — always use `${project_path}`, `${state_path}`, `${project_root}`, etc.
+
 ## 1. Load Context
 
-- Read PROJECT.md (existing project, validated requirements, decisions)
-- Read MILESTONES.md (what shipped previously) — if file does not exist, this is the first milestone; skip and use defaults
-- Read STATE.md (pending todos, blockers) — if file does not exist, will be created in Step 5
-- Check for MILESTONE-CONTEXT.md (from /dgs:discuss-milestone)
+- Read `${project_path}` (existing project, validated requirements, decisions)
+- Read `${product_milestones_path}` (product-level MILESTONES.md — authoritative record of what shipped across ALL projects in this product; used here for global version and phase continuity) — if `${product_milestones_exists}` is false, this is the first milestone in the product; skip and use defaults
+- Optionally read `${project_root}/MILESTONES.md` (per-project shipped record) for project-specific context if it exists — do NOT use it for version or phase numbering, which are global across the product
+- Read `${state_path}` (pending todos, blockers) — if file does not exist, will be created in Step 5
+- Check for `${project_root}/MILESTONE-CONTEXT.md` (from /dgs:discuss-milestone)
 
 ## 1b. Spec-Driven Milestone (auto mode only)
 
@@ -67,7 +84,37 @@ Read the spec file and extract:
 
 ### Determine Milestone Version
 
-Parse MILESTONES.md for last version. If no MILESTONES.md exists (first milestone): default to v1.0 (auto mode: use v1.0 without asking). Suggest next version automatically (e.g., v1.0 → v1.1, or v2.0 for major). In auto mode, use the minor bump without asking.
+Parse `${product_milestones_path}` for last version (versions are global across the product — a new milestone in project A continues the sequence from milestones shipped in any sibling project).
+
+**Compute candidates:**
+- If `${product_milestones_exists}` is false (first milestone in the product): the version is fixed at `v1.0` — skip the question below.
+- Otherwise, last version is `vX.Y`:
+  - Minor candidate: `v[X].[Y+1]` (e.g. v1.3 → v1.4)
+  - Major candidate: `v[X+1].0` (e.g. v1.3 → v2.0)
+
+**Derive recommendation from the spec's Problem and Goals sections:**
+- Recommend **major** if content signals a breaking change, rewrite, replacement, migration, deprecation, or removal of a major capability.
+- Otherwise recommend **minor**.
+
+Compose a one-sentence reason for the recommendation (e.g. "Adds notification features without changing existing contracts" or "Replaces legacy auth with OIDC, deprecating session-token storage").
+
+**Confirm with the user** via AskUserQuestion (auto mode no longer hardcodes minor — version is the one gate auto mode still surfaces, because a wrong major/minor call is hard to undo and the spec content alone is insufficient signal):
+
+```
+AskUserQuestion(
+  header: "Version",
+  question: "Which version for this milestone? Recommendation: v[recommended] (${recommended_kind}) — ${reason}.",
+  options: [
+    { label: "v[recommended] — ${recommended_kind} (recommended)", description: "${reason}" },
+    { label: "v[other] — ${other_kind}", description: "${other_kind_brief_description}" },
+    { label: "Custom", description: "Enter a version manually" }
+  ]
+)
+```
+
+If the user selects "Custom", prompt for manual entry and validate it parses as `vX.Y`.
+
+The chosen `vX.Y` is used for PROJECT.md, STATE.md, and commit messages throughout the rest of the auto-mode flow.
 
 ### Repo Cross-Check (v2 only)
 
@@ -93,10 +140,18 @@ AskUserQuestion([{
 }])
 ```
 
-Handle each choice identically to new-project's repo cross-check:
-- **Continue:** Skip, proceed
-- **Register existing:** Ask path, run `repos add`
-- **Create + Register:** `mkdir -p`, `git init`, `repos add`
+For each unregistered repo, handle the user's choice:
+- **Continue:** Skip this repo, proceed to next
+- **Register existing:** Ask for path (suggest `../{repo_name}`), then run:
+  ```bash
+  node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs repos add "{path}" --name "{repo_name}"
+  ```
+- **Create + Register:**
+  ```bash
+  mkdir -p ../{repo_name}
+  cd ../{repo_name} && git init
+  node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs repos add "../{repo_name}" --name "{repo_name}"
+  ```
 - **Cancel:** Stop with message: "Milestone creation cancelled. Resolve repo registration and try again."
 
 If no unregistered repos OR not v2: skip silently.
@@ -148,7 +203,7 @@ node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: link $SPEC
 
 ### Continue to Step 7
 
-Skip Steps 2-6 (questioning, version determination, update, cleanup, context loading) — they're replaced by spec-driven derivation. Proceed to Step 7 (Load Context and Resolve Models), then:
+Skip Steps 2-6 (questioning, version determination, update, cleanup) — they're replaced by spec-driven derivation. Proceed to Step 8 (Research Decision), then:
 
 - Step 8 (Research Decision): Default to "Research first" in auto mode
 - Step 9 (Define Requirements): Generate from spec instead of interactive scoping:
@@ -164,9 +219,43 @@ Skip Steps 2-6 (questioning, version determination, update, cleanup, context loa
 - Step 10.5 (Overlap Check): Run as usual
 - Step 11 (Done): Show source spec in completion output
 
+## 1c. Migrate Historical Quick Directories
+
+One-time migration for projects with quick dirs accumulated from before per-milestone archival.
+
+Check if `${project_root}/quick/` exists and contains any directories (beyond HISTORY.md):
+
+```bash
+QUICK_DIR="${project_root}/quick"
+if [ -d "$QUICK_DIR" ]; then
+  QUICK_DIRS=$(ls -d "$QUICK_DIR"/*/ 2>/dev/null | wc -l)
+fi
+```
+
+If directories exist (count > 0):
+
+1. Create `milestones/historical-quick/` in the planning root
+2. Move ALL directories from `${project_root}/quick/` into `milestones/historical-quick/`
+3. Do NOT move HISTORY.md (it is a file, not a directory -- the glob naturally skips it)
+4. Do NOT move other plain files in quick/
+5. Log: `Migrated {N} historical quick directories to milestones/historical-quick/`
+
+```bash
+PLAN_ROOT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs paths planning-root --raw)
+HIST_DIR="$PLAN_ROOT/milestones/historical-quick"
+mkdir -p "$HIST_DIR"
+for d in "$QUICK_DIR"/*/; do
+  [ -d "$d" ] && mv "$d" "$HIST_DIR/"
+done
+```
+
+If no directories exist: skip silently (no output needed).
+
+This is idempotent -- once dirs are moved, subsequent runs find nothing to migrate.
+
 ## 2. Gather Milestone Goals
 
-**If MILESTONE-CONTEXT.md exists:**
+**If `${project_root}/MILESTONE-CONTEXT.md` exists:**
 - Use features and scope from discuss-milestone
 - Present summary for confirmation
 
@@ -177,10 +266,37 @@ Skip Steps 2-6 (questioning, version determination, update, cleanup, context loa
 
 ## 3. Determine Milestone Version
 
-- Parse last version from MILESTONES.md
-- If no MILESTONES.md exists (first milestone): default to v1.0 and suggest it to user
-- Suggest next version (v1.0 → v1.1, or v2.0 for major)
-- Confirm with user
+Parse last version from `${product_milestones_path}` (product-level — versions are global across all projects in the product).
+
+**Compute candidates:**
+- If `${product_milestones_exists}` is false (first milestone in the product): the version is fixed at `v1.0` — skip the question below.
+- Otherwise, last version is `vX.Y`:
+  - Minor candidate: `v[X].[Y+1]` (e.g. v1.3 → v1.4)
+  - Major candidate: `v[X+1].0` (e.g. v1.3 → v2.0)
+
+**Derive recommendation from the milestone goals gathered in Step 2:**
+- Recommend **major** if the goals signal a breaking change, rewrite, replacement, migration, deprecation, or removal of a major capability.
+- Otherwise recommend **minor**.
+
+Compose a one-sentence reason for the recommendation (e.g. "Adds notification features without changing existing contracts" or "Replaces legacy auth with OIDC, deprecating session-token storage").
+
+**Confirm with the user** via AskUserQuestion:
+
+```
+AskUserQuestion(
+  header: "Version",
+  question: "Which version for this milestone? Recommendation: v[recommended] (${recommended_kind}) — ${reason}.",
+  options: [
+    { label: "v[recommended] — ${recommended_kind} (recommended)", description: "${reason}" },
+    { label: "v[other] — ${other_kind}", description: "${other_kind_brief_description}" },
+    { label: "Custom", description: "Enter a version manually" }
+  ]
+)
+```
+
+If the user selects "Custom", prompt for manual entry and validate it parses as `vX.Y`.
+
+The chosen `vX.Y` is used for PROJECT.md, STATE.md, and commit messages throughout the rest of the workflow.
 
 ## 4. Update PROJECT.md
 
@@ -201,8 +317,8 @@ Update Active requirements section and "Last updated" footer.
 
 ## 5. Update STATE.md
 
-**If STATE.md does not exist (first milestone):** Create it with the structure below.
-**If STATE.md exists:** Update the Current Position section.
+**If `${state_path}` does not exist (first milestone):** Create it with the structure below.
+**If it exists:** Update the Current Position section.
 
 ```markdown
 ## Current Position
@@ -217,25 +333,15 @@ Keep Accumulated Context section from previous milestone.
 
 ## 6. Cleanup and Commit
 
-Delete MILESTONE-CONTEXT.md if exists (consumed).
+Delete `${project_root}/MILESTONE-CONTEXT.md` if exists (consumed).
 
 ```bash
 node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: start milestone v[X.Y] [Name]" --push --files ${project_path} ${state_path}
 ```
 
-## 7. Load Context and Resolve Models
-
-```bash
-INIT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs init new-milestone)
-```
-
-Extract from init JSON: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `research_enabled`, `current_milestone`, `project_exists`, `roadmap_exists`.
-
-Load planning-tier context files:
+## 7. Research Decision Gate
 
-```bash
-TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" context load-tier planning --raw 2>/dev/null)
-```
+Paths and models already resolved in Step 0.
 
 ## 8. Research Decision
 
@@ -416,7 +522,7 @@ If "adjust": Return to scoping.
 
 **Commit requirements:**
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: define milestone v[X.Y] requirements" --push --files ${project_root}/REQUIREMENTS.md
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: define milestone v[X.Y] requirements" --push --files ${project_root}/REQUIREMENTS.md config.json
 ```
 
 ## 10. Create Roadmap
@@ -429,7 +535,7 @@ node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: define mile
 ◆ Spawning roadmapper...
 ```
 
-**Starting phase number:** Read MILESTONES.md for last phase number. Continue from there (v1.0 ended at phase 5 → v1.1 starts at phase 6). If no MILESTONES.md exists (first milestone): start phase numbering at 1.
+**Starting phase number:** Read `${product_milestones_path}` for last phase number (phase numbers are global across the product — the next phase continues the sequence from the most recent milestone shipped in any project). Continue from there (e.g., v23.0 ended at phase 148 → v23.1 starts at phase 149). If `${product_milestones_exists}` is false (first milestone in the product): start phase numbering at 1.
 
 ```
 Task(prompt="
@@ -439,7 +545,7 @@ Task(prompt="
 - ${project_root}/REQUIREMENTS.md
 - ${project_root}/research/SUMMARY.md (if exists)
 - ${config_path}
-- ${project_root}/MILESTONES.md
+- ${product_milestones_path}
 - ${project_root}/docs/product/ARCHITECTURE.md (Target architecture, if exists)
 - ${project_root}/docs/product/PRODUCT-SUMMARY.md (Product summary, if exists)
 </files_to_read>
@@ -579,6 +685,7 @@ Also: `/dgs:plan-phase [N]` — skip discussion, plan directly
 - [ ] Auto mode: repo cross-check completed (if v2)
 - [ ] Auto mode: one milestone per spec enforced
 - [ ] Auto mode: spec milestones field updated with link-milestone call
+- [ ] Both modes: version selection presented as AskUserQuestion with minor/major candidates and a recommendation derived from spec/goals content (auto mode included — version is the one gate auto mode still surfaces)
 
 **Atomic commits:** Each phase commits its artifacts immediately.
 </success_criteria>