@ktpartners/dgs-platform 3.0.4 → 3.3.0

package/deliver-great-systems/workflows/init-product.md

@@ -88,51 +88,15 @@ Created:
   - .gitignore
 ```
 
-**b2. Configure Base Branch:**
+**b2. Configure Workflow Discipline (non-interactive):**
 
-Prompt the user for their code repo base branch:
-
-```
-AskUserQuestion([{
-  question: "What is the base branch for your code repos? (e.g., main, develop, dev)",
-  header: "Git Configuration",
-  multiSelect: false,
-  freeform: true,
-  placeholder: ""
-}])
-```
-
-Always ask — no auto-detection, no default pre-fill. The user types the branch name explicitly.
-
-After receiving the answer, write to config:
-```bash
-node /Users/adrian/.claude/deliver-great-systems/bin/dgs-tools.cjs config-set git.base_branch "$USER_ANSWER"
-```
-
-If the user provides an empty answer or skips, do NOT write anything — the default `main` from config-ensure-section already provides the fallback.
-
-**b3. Configure Workflow Discipline:**
+Workflow discipline is always enabled by default — it adds a CLAUDE.md file that routes code changes through `/dgs:*` commands for traceability and atomic commits. Read-only operations (searching, tests, git log) stay unrestricted. Users can disable later via `/dgs:settings`.
 
 Read the CLAUDE.md template:
 ```bash
 CLAUDE_TEMPLATE=$(cat /Users/adrian/.claude/deliver-great-systems/templates/claude-md.md)
 ```
 
-Use AskUserQuestion:
-```
-AskUserQuestion([{
-  question: "Enable workflow discipline? This adds a CLAUDE.md file that routes code changes through /dgs:* commands for traceability and atomic commits. Read-only operations (searching, tests, git log) stay unrestricted.",
-  header: "Workflow Discipline",
-  multiSelect: false,
-  options: [
-    { label: "Yes (Recommended)", description: "Creates CLAUDE.md with DGS command routing rules" },
-    { label: "No", description: "Skip — no CLAUDE.md created" }
-  ]
-}])
-```
-
-**If "Yes":**
-
 Check if `./CLAUDE.md` already exists in the project root (cwd):
 
 - **If CLAUDE.md does NOT exist:** Create `./CLAUDE.md` with DGS section delimiters wrapping the template content:
@@ -162,142 +126,72 @@ node /Users/adrian/.claude/deliver-great-systems/bin/dgs-tools.cjs config-set wo
 
 Display: `Workflow discipline enabled — CLAUDE.md added.`
 
-Add `CLAUDE.md` to the commit file list for the init commit that follows (the `dgs-tools.cjs commit` call at the end of the flow).
+CLAUDE.md is always included in the init commit file list (b4 below).
 
-**If "No":**
+**b3. Apply Recommended Defaults (non-interactive):**
+
+All other recommended defaults (`model_profile=balanced`, `commit_docs=true`, `workflow.research=true`, `workflow.plan_check=true`, `workflow.verifier=true`, `git.base_branch=main`) are already applied by `repos init-product` in step 2 — they live in `config.cjs`'s hardcoded defaults and are merged with any per-user overrides from `~/.dgs/defaults.json` (saved via `/dgs:settings save-as-defaults`). The three keys below are the only ones the underlying init does not pre-populate, so they are set explicitly here:
 
-Set config:
 ```bash
-node /Users/adrian/.claude/deliver-great-systems/bin/dgs-tools.cjs config-set workflow.discipline false
+node /Users/adrian/.claude/deliver-great-systems/bin/dgs-tools.cjs config-set mode yolo
+node /Users/adrian/.claude/deliver-great-systems/bin/dgs-tools.cjs config-set granularity standard
+node /Users/adrian/.claude/deliver-great-systems/bin/dgs-tools.cjs config-set workflow.codereview true
 ```
 
-Display: `Skipped.`
+Commit the applied defaults:
+```bash
+node /Users/adrian/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "chore: apply recommended defaults" --files ${config_path}
+```
 
-Do NOT create or modify CLAUDE.md. Do NOT add CLAUDE.md to any commit.
+**b4. Commit initialized files:**
 
-**b4. Configure Workflow Preferences (Round 1 — Core settings):**
+Extract the `scaffolded_files` array from the init response (`RESULT` captured in step 2) and pass those paths to the commit step alongside the explicitly-named files. The `scaffolded_files` array is the AGENT-13 contract field — it lists every path `cmdReposInitProduct` guaranteed on disk that the caller MUST commit (today the array contains the per-directory keep-files written under `specs/`, `docs/product/`, and `quick/`; future scaffold additions automatically flow through without workflow edits):
 
-```
-AskUserQuestion([
-  {
-    header: "Mode",
-    question: "How do you want to work?",
-    multiSelect: false,
-    options: [
-      { label: "YOLO (Recommended)", description: "Auto-approve, just execute" },
-      { label: "Interactive", description: "Confirm at each step" }
-    ]
-  },
-  {
-    header: "Depth",
-    question: "How thorough should planning be?",
-    multiSelect: false,
-    options: [
-      { label: "Quick", description: "Ship fast (3-5 phases, 1-3 plans each)" },
-      { label: "Standard", description: "Balanced scope and speed (5-8 phases, 3-5 plans each)" },
-      { label: "Comprehensive", description: "Thorough coverage (8-12 phases, 5-10 plans each)" }
-    ]
-  },
-  {
-    header: "Git Tracking",
-    question: "Commit planning docs to git?",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Planning docs tracked in version control" },
-      { label: "No", description: "Keep planning docs local-only (add to .gitignore)" }
-    ]
-  }
-])
+```bash
+# AGENT-13: consume scaffolded_files from cmdReposInitProduct (per references/workflow-conventions.md)
+SCAFFOLDED=$(printf '%s' "$RESULT" | jq -r '.scaffolded_files[]?' | tr '\n' ' ')
+node /Users/adrian/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: initialize product ${product_name}" --files REPOS.md PROJECTS.md config.json .gitignore CLAUDE.md ${SCAFFOLDED}
 ```
 
-**b5. Configure Workflow Preferences (Round 2 — Agents):**
+CLAUDE.md is always included (workflow discipline is now always enabled by default — see b2). The `${SCAFFOLDED}` token is unquoted intentionally so word-splitting expands the multiple paths into separate `--files` arguments.
 
-```
-AskUserQuestion([
-  {
-    header: "AI Models",
-    question: "Which AI models for planning agents?",
-    multiSelect: false,
-    options: [
-      { label: "Balanced (Recommended)", description: "Sonnet for most agents — good quality/cost ratio" },
-      { label: "Quality", description: "Opus for research/roadmap — higher cost, deeper analysis" },
-      { label: "Budget", description: "Haiku where possible — fastest, lowest cost" }
-    ]
-  },
-  {
-    header: "Research",
-    question: "Research before planning each phase? (adds tokens/time)",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Investigate domain, find patterns, surface gotchas" },
-      { label: "No", description: "Plan directly from requirements" }
-    ]
-  },
-  {
-    header: "Plan Check",
-    question: "Verify plans will achieve their goals? (adds tokens/time)",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Catch gaps before execution starts" },
-      { label: "No", description: "Execute plans without verification" }
-    ]
-  },
-  {
-    header: "Verifier",
-    question: "Verify work satisfies requirements after each phase? (adds tokens/time)",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Confirm deliverables match phase goals" },
-      { label: "No", description: "Trust execution, skip verification" }
-    ]
-  }
-])
-```
+**b5. Display Defaults Summary:**
+
+After commits land, print a summary block listing every applied setting and the recommended next step:
 
-**b6. Write config.json** with all values collected above:
-
-```json
-{
-  "mode": "yolo|interactive",
-  "depth": "quick|standard|comprehensive",
-  "parallelization": true,
-  "commit_docs": true|false,
-  "model_profile": "quality|balanced|budget",
-  "workflow": {
-    "research": true|false,
-    "plan_check": true|false,
-    "verifier": true|false,
-    "nyquist_validation": true,
-    "auto_advance": false,
-    "discipline": true|false
-  },
-  "git": {
-    "base_branch": "[from earlier question]",
-    "sync_push": "auto",
-    "sync_pull": "auto"
-  }
-}
 ```
+───────────────────────────────────────────────────────────────
 
-Smart defaults (not asked): `parallelization: true`, `auto_advance: false`, `nyquist_validation: true`.
+## ✓ Defaults Applied
 
-**If commit_docs = No:** Add the planning root directory to `.gitignore`.
+The following recommended settings were applied automatically:
 
-**Commit config:**
+| Setting                    | Value      |
+|----------------------------|------------|
+| mode                       | yolo       |
+| granularity                | standard   |
+| commit_docs                | true       |
+| model_profile              | balanced   |
+| workflow.research          | true       |
+| workflow.plan_check        | true       |
+| workflow.verifier          | true       |
+| workflow.codereview        | true       |
+| workflow.discipline        | true       |
+| git.base_branch            | main       |
 
-```bash
-node /Users/adrian/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "chore: add product config" --files ${config_path}
-```
+Change any of them with `/dgs:settings`.
 
-**b7. Commit initialized files:**
+## ▶ Recommended Next Step — Upload Product-Context Docs
 
-Use the `files_created` array from the init response to build the commit file list:
+`/dgs:add-doc PRODUCT-SUMMARY.md`   *what the product is, who it serves, key constraints*
+`/dgs:add-doc ARCHITECTURE.md`      *module boundaries, data flow, tech choices, security model*
 
-```bash
-node /Users/adrian/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: initialize product ${product_name}" --files REPOS.md PROJECTS.md config.json .gitignore CLAUDE.md
+Drop the file path, or paste/attach the file when prompted. These give every downstream workflow (research, planning, review) the context to do its job.
+
+Don't have these docs yet? Skip for now — you can run `/dgs:add-doc` anytime later. (A guided "answer questions to generate" path is on the roadmap.)
 ```
 
-Only include CLAUDE.md in the --files list if workflow discipline was enabled (user answered Yes).
+The summary is informational only — no commits, no config writes.
 
 **c. Route to next step:**
 

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

@@ -50,7 +50,7 @@ The spec must have status: final.
 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`, `current_project`, `project_root`.
+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:
 
@@ -63,7 +63,8 @@ All subsequent steps use these resolved paths. Never reference PROJECT.md, STATE
 ## 1. Load Context
 
 - Read `${project_path}` (existing project, validated requirements, decisions)
-- Read `${project_root}/MILESTONES.md` (what shipped previously) — if file does not exist, this is the first milestone; skip and use defaults
+- 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)
 
@@ -83,7 +84,37 @@ Read the spec file and extract:
 
 ### Determine Milestone Version
 
-Parse `${project_root}/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)
 
@@ -109,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.
@@ -180,6 +219,40 @@ Skip Steps 2-6 (questioning, version determination, update, cleanup) — they're
 - 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 `${project_root}/MILESTONE-CONTEXT.md` exists:**
@@ -193,10 +266,37 @@ Skip Steps 2-6 (questioning, version determination, update, cleanup) — they're
 
 ## 3. Determine Milestone Version
 
-- Parse last version from `${project_root}/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
 
@@ -422,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
@@ -435,7 +535,7 @@ node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: define mile
 ◆ Spawning roadmapper...
 ```
 
-**Starting phase number:** Read `${project_root}/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="
@@ -445,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>
@@ -585,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>