@ktpartners/dgs-platform 2.7.2 → 2.7.4

package/agents/dgs-roadmapper.md

@@ -92,6 +92,32 @@ If a requirement fits multiple phases → assign to ONE (usually the first that
 
 </philosophy>
 
+<milestone_handling>
+
+## Milestone Version
+
+The orchestrator passes a `<milestone>` block in the planning context with `version` and `name`.
+
+**Reading:** Extract `version` (e.g., "v17.0") and `name` (e.g., "Git Push and Pull Integration") from the `<milestone>` tag in the prompt.
+
+**If no `<milestone>` block provided:** Default to `v1.0` / `milestone` (greenfield).
+
+**Usage:**
+
+When writing **STATE.md frontmatter**, use the provided version:
+```yaml
+---
+dgs_state_version: 1.0
+milestone: {version}       # e.g., v17.0, NOT hardcoded v1.0
+milestone_name: {name}
+status: planning
+---
+```
+
+When writing **ROADMAP.md**, use the version in milestone headings and references instead of assuming v1.0.
+
+</milestone_handling>
+
 <goal_backward_phases>
 
 ## Deriving Phase Success Criteria
@@ -402,6 +428,7 @@ Orchestrator provides:
 - REQUIREMENTS.md content (v1 requirements with REQ-IDs)
 - research/SUMMARY.md content (if exists - phase suggestions)
 - config.json (granularity setting)
+- Milestone version and name (from `<milestone>` block -- use when writing STATE.md/ROADMAP.md)
 
 Parse and confirm understanding before proceeding.
 
@@ -462,8 +489,10 @@ If gaps found, include in draft for user decision.
 Write files first, then return. This ensures artifacts persist even if context is lost.
 
 1. **Write ROADMAP.md** using output format
+   Use milestone version from `<milestone>` block for headings (e.g., "v17.0 [Name]" not "v1.0 MVP").
 
 2. **Write STATE.md** using output format
+   Use milestone version from `<milestone>` block in frontmatter (`milestone: {version}`, `milestone_name: {name}`).
 
 3. **Update REQUIREMENTS.md traceability section**
 

package/commands/dgs/capture-principle.md

@@ -124,7 +124,7 @@ Use today's date for the `Added` field.
 
 If `commit_docs` is true:
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: capture design principle - {title}" --files .planning/docs/product/DESIGN-PRINCIPLES.md
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: capture design principle - {title}" --push --files .planning/docs/product/DESIGN-PRINCIPLES.md
 ```
 
 If `commit_docs` is false, just save the file without committing.

package/deliver-great-systems/bin/lib/init.cjs

@@ -397,6 +397,7 @@ function cmdInitNewProject(cwd, raw) {
   const config = loadConfig(cwd);
   const ctx = resolveProjectContext(cwd);
   const planRootRel = path.relative(cwd, getPlanningRoot(cwd)) || '.';
+  const milestone = getMilestoneInfo(cwd);
 
   // Detect Brave Search API key availability
   const homedir = require('os').homedir();
@@ -461,6 +462,10 @@ function cmdInitNewProject(cwd, raw) {
     requirements_path: ctx.root ? path.join(ctx.root, 'REQUIREMENTS.md') : path.join(planRootRel, 'REQUIREMENTS.md'),
     research_dir: ctx.root ? path.join(ctx.root, 'research') : path.join(planRootRel, 'research'),
 
+    // Milestone info (product-level, shared across projects)
+    milestone_version: milestone.version,
+    milestone_name: milestone.name,
+
     // v2 context
     dgs_mode: ctx.dgs_mode,
     current_project: ctx.current_project,

package/deliver-great-systems/bin/lib/init.test.cjs

@@ -227,6 +227,14 @@ describe('v1 mode: init new-project', () => {
   it('returns dgs_mode v1', () => {
     assert.equal(result.dgs_mode, 'v1');
   });
+
+  it('returns milestone_version defaulting to v1.0 when no milestones exist', () => {
+    assert.equal(result.milestone_version, 'v1.0');
+  });
+
+  it('returns milestone_name defaulting to milestone', () => {
+    assert.equal(result.milestone_name, 'milestone');
+  });
 });
 
 // ─── v1 Mode: other init commands ────────────────────────────────────────────
@@ -462,6 +470,10 @@ describe('v2 mode with project: init new-project', () => {
   it('returns dgs_mode v2', () => {
     assert.equal(result.dgs_mode, 'v2');
   });
+
+  it('returns milestone_version defaulting to v1.0 when no milestones exist', () => {
+    assert.equal(result.milestone_version, 'v1.0');
+  });
 });
 
 describe('v2 mode with project: init progress', () => {

package/deliver-great-systems/workflows/add-idea.md

@@ -72,7 +72,7 @@ Parse the JSON result to get `id`, `filename`, `path`.
 
 <step name="git_commit">
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "ideas: add #${id} - ${title}" --files ${project_root}/ideas/pending/${filename} ${project_root}/ideas/manifest.json
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "ideas: add #${id} - ${title}" --push --files ${project_root}/ideas/pending/${filename} ${project_root}/ideas/manifest.json
 ```
 </step>
 

package/deliver-great-systems/workflows/add-todo.md

@@ -123,7 +123,7 @@ If STATE.md exists (use `state_path` from init):
 Commit the todo and any updated state:
 
 ```bash
-node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs: capture todo - [title]" --files ${pending_dir}/[filename] ${state_path}
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs: capture todo - [title]" --push --files ${pending_dir}/[filename] ${state_path}
 ```
 
 Tool respects `commit_docs` config and gitignore automatically.

package/deliver-great-systems/workflows/approve-spec.md

@@ -162,7 +162,7 @@ Perform the approval state transition and audit trail update.
 
 4. Commit the changes:
    ```bash
-   node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: approve $SPEC_ID v$VERSION" --files "$SPEC_FILE_PATH"
+   node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: approve $SPEC_ID v$VERSION" --push --files "$SPEC_FILE_PATH"
    ```
 </step>
 

package/deliver-great-systems/workflows/audit-phase.md

@@ -278,7 +278,7 @@ When `RERUN_FAILED_MODE` is true, the structural verifier also reruns, but only
 **Commit the UAT file:**
 
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "[AUDIT] audit(${PHASE_ARG}): ${test_failures} test failures, ${structural_gaps} structural gaps" --files "${uat_path}" "${log_path}"
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "[AUDIT] audit(${PHASE_ARG}): ${test_failures} test failures, ${structural_gaps} structural gaps" --push --files "${uat_path}" "${log_path}"
 ```
 </step>
 

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

@@ -1211,7 +1211,7 @@ git push origin v[X.Y]
 Commit milestone completion.
 
 ```bash
-node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "chore: complete v[X.Y] milestone" --files ${project_root}/milestones/v[X.Y]-ROADMAP.md ${project_root}/milestones/v[X.Y]-REQUIREMENTS.md ${project_root}/v[X.Y]-MILESTONE-AUDIT.md ${project_root}/MILESTONES.md ${project_path} ${state_path}
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "chore: complete v[X.Y] milestone" --push --files ${project_root}/milestones/v[X.Y]-ROADMAP.md ${project_root}/milestones/v[X.Y]-REQUIREMENTS.md ${project_root}/v[X.Y]-MILESTONE-AUDIT.md ${project_root}/MILESTONES.md ${project_path} ${state_path}
 ```
 ```
 

package/deliver-great-systems/workflows/import-spec.md

@@ -264,7 +264,7 @@ Original: will be saved to ${project_root}/{attachment_path}
 
    **Execute the commit:**
    ```bash
-   node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: import {id} - {title} (from {original-filename})" --files ${project_root}/specs/spec-{slug}.md ${project_root}/{attachment_path} ${project_root}/specs/spec-{slug}/docs/INDEX.md ${project_root}/specs/spec-{slug}/docs/.names.json
+   node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: import {id} - {title} (from {original-filename})" --push --files ${project_root}/specs/spec-{slug}.md ${project_root}/{attachment_path} ${project_root}/specs/spec-{slug}/docs/INDEX.md ${project_root}/specs/spec-{slug}/docs/.names.json
    ```
    The `dgs-tools.cjs commit` helper with `--files` stages only the specified files and commits them. This ensures other unstaged/uncommitted changes in the working tree are not included. The `.names.json` file is included because `docs add` creates it as internal metadata for INDEX rebuilds.
 

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

@@ -129,7 +129,7 @@ Last activity: [today] — Milestone v[X.Y] started (from spec [spec-id])
 ### Commit
 
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: start milestone v[X.Y] [Name] (from spec)" --files ${project_path} ${state_path}
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: start milestone v[X.Y] [Name] (from spec)" --push --files ${project_path} ${state_path}
 ```
 
 ### Link Spec to Milestone
@@ -143,7 +143,7 @@ node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs specs link-milestone --id
 Include the updated spec file in a commit:
 
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: link $SPEC_ID to v$VERSION" --files ${project_root}/specs/$SPEC_FILENAME
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: link $SPEC_ID to v$VERSION" --push --files ${project_root}/specs/$SPEC_FILENAME
 ```
 
 ### Continue to Step 7
@@ -216,7 +216,7 @@ Keep Accumulated Context section from previous milestone.
 Delete MILESTONE-CONTEXT.md if exists (consumed).
 
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: start milestone v[X.Y] [Name]" --files ${project_path} ${state_path}
+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
@@ -406,7 +406,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" --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
 ```
 
 ## 10. Create Roadmap
@@ -485,7 +485,7 @@ Success criteria:
 
 **Commit roadmap** (after approval):
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: create milestone v[X.Y] roadmap ([N] phases)" --files ${roadmap_path} ${state_path} ${project_root}/REQUIREMENTS.md
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: create milestone v[X.Y] roadmap ([N] phases)" --push --files ${roadmap_path} ${state_path} ${project_root}/REQUIREMENTS.md
 ```
 
 ## 10.5. Overlap Check (v2 only)

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

@@ -64,7 +64,7 @@ If the `--auto` argument references a spec file path or spec ID:
 INIT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs init new-project)
 ```
 
-Parse JSON for: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `project_exists`, `has_codebase_map`, `planning_exists`, `has_existing_code`, `has_package_file`, `is_brownfield`, `needs_codebase_map`, `has_git`, `project_path`, `state_path`, `roadmap_path`, `requirements_path`, `research_dir`.
+Parse JSON for: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `project_exists`, `has_codebase_map`, `planning_exists`, `has_existing_code`, `has_package_file`, `is_brownfield`, `needs_codebase_map`, `has_git`, `project_path`, `state_path`, `roadmap_path`, `requirements_path`, `research_dir`, `milestone_version`, `milestone_name`.
 
 Load planning-tier context files:
 
@@ -420,7 +420,7 @@ Do not compress. Capture everything gathered.
 
 ```bash
 mkdir -p .planning
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: initialize project" --files ${project_path}
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: initialize project" --push --files ${project_path}
 ```
 
 ## 5. Resolve Model Profile
@@ -829,7 +829,7 @@ If "adjust": Return to scoping.
 **Commit requirements:**
 
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: define v1 requirements" --files ${requirements_path}
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: define v1 requirements" --push --files ${requirements_path}
 ```
 
 ## 8. Create Roadmap
@@ -857,6 +857,11 @@ Task(prompt="
 ${product_doc_files}
 </files_to_read>
 
+<milestone>
+version: ${milestone_version}
+name: ${milestone_name}
+</milestone>
+
 </planning_context>
 
 <instructions>
@@ -864,6 +869,7 @@ Create roadmap:
 1. Derive phases from requirements (don't impose structure)
 2. Map every v1 requirement to exactly one phase
 3. Derive 2-5 success criteria per phase (observable user behaviors)
+Use the milestone version from <milestone> when writing STATE.md frontmatter and ROADMAP.md headings.
 4. Validate 100% coverage
 5. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
 6. Return ROADMAP CREATED with summary
@@ -960,7 +966,7 @@ Use AskUserQuestion:
 **Commit roadmap (after approval or auto mode):**
 
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: create roadmap ([N] phases)" --files ${roadmap_path} ${state_path} ${requirements_path}
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: create roadmap ([N] phases)" --push --files ${roadmap_path} ${state_path} ${requirements_path}
 ```
 
 ### Link Spec to Milestone (spec-driven mode only)
@@ -974,7 +980,7 @@ node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs specs link-milestone --id
 Include the updated spec file in a commit:
 
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: link $SPEC_ID to v1.0" --files $SPEC_PATH
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: link $SPEC_ID to v1.0" --push --files $SPEC_PATH
 ```
 
 ## 8.5. Overlap Check (v2 only)

package/deliver-great-systems/workflows/plan-phase.md

@@ -163,7 +163,7 @@ Use full relative paths. Group by topic area.]
 
 5. Commit:
 ```bash
-node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs(${padded_phase}): generate context from PRD" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs(${padded_phase}): generate context from PRD" --push --files "${phase_dir}/${padded_phase}-CONTEXT.md"
 ```
 
 6. Set `context_content` to the generated CONTEXT.md content and continue to step 5 (Handle Research).

package/deliver-great-systems/workflows/quick.md

@@ -776,7 +776,7 @@ Build file list:
 - If `$FULL_MODE` and verification file exists: `${QUICK_DIR}/${quick_id}-VERIFICATION.md`
 
 ```bash
-node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs(quick-${quick_id}): ${DESCRIPTION}" --files ${file_list}
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs(quick-${quick_id}): ${DESCRIPTION}" --push --files ${file_list}
 ```
 
 Get final commit hash:

package/deliver-great-systems/workflows/refine-spec.md

@@ -239,7 +239,7 @@ All writes happen here, atomically at the end of the session. No file changes oc
 
 10. **Commit the changes:**
     ```bash
-    node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "refine(spec): $SPEC_SLUG v$NEW_VERSION -- $SUMMARY" --files "$SPEC_FILE_PATH"
+    node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "refine(spec): $SPEC_SLUG v$NEW_VERSION -- $SUMMARY" --push --files "$SPEC_FILE_PATH"
     ```
 </step>
 

package/deliver-great-systems/workflows/update-idea.md

@@ -124,12 +124,12 @@ LIST=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs ideas list --raw)
 Parse to find the idea's state and filename, then commit:
 
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "ideas: update #${id} - ${field}" --files ${path}
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "ideas: update #${id} - ${field}" --push --files ${path}
 ```
 
 For note appends, use:
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "ideas: add note to #${id}" --files ${path}
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "ideas: add note to #${id}" --push --files ${path}
 ```
 </step>
 

package/deliver-great-systems/workflows/update.md

@@ -121,7 +121,7 @@ Exit.
 <step name="show_changes_and_confirm">
 **If update available**, fetch and show what's new BEFORE updating:
 
-1. Fetch changelog from GitHub raw URL
+1. Read changelog from installed package (CHANGELOG.md in the DGS install directory)
 2. Extract entries between installed and latest versions
 3. Display preview and ask for confirmation:
 
@@ -209,7 +209,7 @@ Format completion message (changelog was already shown in confirmation step):
 
 ⚠️  Restart Claude Code to pick up the new commands.
 
-[View full changelog](https://github.com/glittercowboy/deliver-great-systems/blob/main/CHANGELOG.md)
+[View full changelog](https://github.com/KT-Partners-Ltd/deliver-great-systems/blob/main/CHANGELOG.md)
 ```
 </step>
 

package/deliver-great-systems/workflows/verify-work.md

@@ -373,14 +373,14 @@ Clear Current Test section:
 [testing complete]
 ```
 
-Commit the UAT file:
+Commit the UAT file and VERIFICATION.md:
 ```bash
-node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "test({phase_num}): complete UAT - {passed} passed, {issues} issues" --files "${phase_dir}/{phase_num}-UAT.md"
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "test({phase_num}): complete UAT - {passed} passed, {issues} issues" --push --files "${phase_dir}/{phase_num}-UAT.md" "${phase_dir}/{phase_num}-VERIFICATION.md"
 ```
 
 If `AUTO_MODE` is true, prefix the commit message with `[AUTO] `:
 ```bash
-node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "[AUTO] test({phase_num}): complete UAT - {passed} passed, {issues} issues" --files "${phase_dir}/{phase_num}-UAT.md"
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "[AUTO] test({phase_num}): complete UAT - {passed} passed, {issues} issues" --push --files "${phase_dir}/{phase_num}-UAT.md" "${phase_dir}/{phase_num}-VERIFICATION.md"
 ```
 
 Present summary:

package/deliver-great-systems/workflows/write-spec.md

@@ -222,7 +222,7 @@ node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs specs add-log-entry --id
 
 Commit the draft:
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: draft $id from ideas $idea_ids" --files ${project_root}/specs/$filename
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: draft $id from ideas $idea_ids" --push --files ${project_root}/specs/$filename
 ```
 
 Store `SPEC_ID` and `FILENAME` for subsequent steps.
@@ -289,7 +289,7 @@ Use AskUserQuestion: "Review the draft spec above. Type **approve** to send to r
 
 After approval, commit any changes:
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: revise draft $SPEC_ID" --files ${project_root}/specs/$FILENAME
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: revise draft $SPEC_ID" --push --files ${project_root}/specs/$FILENAME
 ```
 </step>
 
@@ -350,7 +350,7 @@ Estimated cost: ~$X.XX
 **6. Commit updated spec:**
 
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: review $SPEC_ID (N rounds)" --files ${project_root}/specs/$FILENAME
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: review $SPEC_ID (N rounds)" --push --files ${project_root}/specs/$FILENAME
 ```
 </step>
 

package/package.json

@@ -4,7 +4,7 @@
   "bugs": {
     "url": "https://github.com/KT-Partners-Ltd/dgs-platform-docs/issues"
   },
-  "version": "2.7.2",
+  "version": "2.7.4",
   "description": "Deliver Great Systems Platform — A meta-prompting, context engineering and spec-driven development system for Claude Code and Gemini by KT Partners.",
   "bin": {
     "dgs": "bin/install.js"
@@ -18,7 +18,8 @@
     "agents",
     "hooks/dist",
     "scripts",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "keywords": [
     "claude",