@ktpartners/dgs-platform 3.4.2 → 3.5.1

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

@@ -85,7 +85,13 @@ EXIT_CODE=$?
 **Step 4: Display result**
 
 **If exit code is 0 (success):**
-Parse the restored-docs list and any warnings from RESULT (JSON: `{ abandoned, slug, base_ref, restored, reverted, warnings }`).
+Parse the restored-docs list and any warnings from RESULT (JSON: `{ abandoned, slug, base_ref, restored, reverted, phases_dir_removed, warnings }`).
+
+Abandon also removes the seeded versioned phases directory `phases/<version>/`
+that `create-adhoc` created, so no versioned phases residue remains after the
+planning docs are restored. Any tracked phase files under it are staged for
+deletion in the same attributed reversion commit. The removed path is reported as
+`phases_dir_removed` (null when there was nothing to remove).
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  DGS ► MILESTONE ABANDONED ✓
@@ -116,5 +122,6 @@ Display the error / reverted-vs-not report from RESULT verbatim (ADH-20 — it s
 - [ ] The 5 project docs path-scoped-restored to the base ref (never a whole-tree reset) (ADH-09)
 - [ ] Attributed reversion commit recorded (ADH-20)
 - [ ] active_context cleared
+- [ ] Seeded versioned phases dir `phases/<version>/` removed; no versioned residue (reported as `phases_dir_removed`)
 - [ ] Owned remote milestone branch deleted during teardown (non-fatal on failure); failures surfaced as warnings (ADH-20)
 </success_criteria>

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

@@ -13,7 +13,7 @@ Requires explicit confirmation before proceeding. This is destructive and cannot
 Check for active product-level quick:
 ```bash
 ACTIVE=$(node -e "
-  const q = require('$HOME/.claude/deliver-great-systems/bin/lib/quick.cjs');
+  const q = require(process.env.HOME + '/.claude/deliver-great-systems/bin/lib/quick.cjs');
   const a = q.getActiveQuick(process.cwd());
   process.stdout.write(JSON.stringify(a || { none: true }));
 ")

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

@@ -21,7 +21,7 @@ Multi-agent code review that runs 3 passes of 3 parallel agents each (9 total re
 Compute the diff from the plan's task commits.
 
 ```bash
-FIRST_TASK_COMMIT=$(git -C "${CODE_REPO_PATH}" log --oneline --grep="feat(${PHASE}-${PLAN}):" --grep="fix(${PHASE}-${PLAN}):" --grep="test(${PHASE}-${PLAN}):" --grep="refactor(${PHASE}-${PLAN}):" --reverse | head -1 | cut -d' ' -f1)
+FIRST_TASK_COMMIT=$(git -C "${CODE_REPO_PATH}" log $(git -C "${CODE_REPO_PATH}" merge-base main HEAD)..HEAD --oneline --grep="feat(${PHASE}-${PLAN}):" --grep="fix(${PHASE}-${PLAN}):" --grep="test(${PHASE}-${PLAN}):" --grep="refactor(${PHASE}-${PLAN}):" --reverse | head -1 | cut -d' ' -f1)
 ```
 
 If FIRST_TASK_COMMIT is empty, exit with message: "No task commits found for ${PHASE}-${PLAN}, skipping code review."

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

@@ -433,7 +433,7 @@ If mark-milestone-complete fails, log a warning but continue to gather_stats (no
 Calculate milestone statistics:
 
 ```bash
-git log --oneline --grep="feat(" | head -20
+git log --oneline FIRST_COMMIT..LAST_COMMIT --grep="feat(" | head -20
 git diff --stat FIRST_COMMIT..LAST_COMMIT | tail -1
 find . -name "*.swift" -o -name "*.ts" -o -name "*.py" | xargs wc -l 2>/dev/null
 git log --format="%ai" FIRST_COMMIT | tail -1

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

@@ -377,7 +377,7 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
 
    For each SUMMARY.md:
    - Verify first 2 files from `key-files.created` exist on disk
-   - Check `git log --oneline --all --grep="{phase}-{plan}"` returns ≥1 commit
+   - Check `git log --oneline $(git merge-base main HEAD)..HEAD --grep="{phase}-{plan}"` returns ≥1 commit
    - Check for `## Self-Check: FAILED` marker
 
    If ANY spot-check fails: report which plan failed, route to failure handler.
@@ -450,7 +450,7 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
 
    Compute diff reference for the plan's task commits:
    ```bash
-   FIRST_TASK_COMMIT=$(git -C "${CODE_REPO_PATH}" log --oneline --grep="feat(${PHASE}-${PLAN}):" --grep="fix(${PHASE}-${PLAN}):" --grep="test(${PHASE}-${PLAN}):" --grep="refactor(${PHASE}-${PLAN}):" --reverse | head -1 | cut -d' ' -f1)
+   FIRST_TASK_COMMIT=$(git -C "${CODE_REPO_PATH}" log $(git -C "${CODE_REPO_PATH}" merge-base main HEAD)..HEAD --oneline --grep="feat(${PHASE}-${PLAN}):" --grep="fix(${PHASE}-${PLAN}):" --grep="test(${PHASE}-${PLAN}):" --grep="refactor(${PHASE}-${PLAN}):" --reverse | head -1 | cut -d' ' -f1)
    ```
 
    If FIRST_TASK_COMMIT is empty (no task commits found), skip codereview for this plan with message: "No task commits found for {phase}-{plan}, skipping code review."

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

@@ -114,7 +114,7 @@ Pattern B only (verify-only checkpoints). Skip for A/C.
    - Main route: execute tasks using standard flow (step name="execute")
 3. After ALL segments: aggregate files/deviations/decisions → create SUMMARY.md → commit → self-check:
    - Verify key-files.created exist on disk with `[ -f ]`
-   - Check `git log --oneline --all --grep="{phase}-{plan}"` returns ≥1 commit
+   - Check `git log --oneline $(git merge-base main HEAD)..HEAD --grep="{phase}-{plan}"` returns ≥1 commit
    - Append `## Self-Check: PASSED` or `## Self-Check: FAILED` to SUMMARY
 
    **Known Claude Code bug (classifyHandoffIfNeeded):** If any segment agent reports "failed" with `classifyHandoffIfNeeded is not defined`, this is a Claude Code runtime bug — not a real failure. Run spot-checks; if they pass, treat as successful.
@@ -490,7 +490,7 @@ The plan name is auto-extracted from the PLAN.md `plan_name` frontmatter field (
 If ${project_root}/codebase/ doesn't exist: skip.
 
 ```bash
-FIRST_TASK=$(git log --oneline --grep="feat({phase}-{plan}):" --grep="fix({phase}-{plan}):" --grep="test({phase}-{plan}):" --reverse | head -1 | cut -d' ' -f1)
+FIRST_TASK=$(git log $(git merge-base main HEAD)..HEAD --oneline --grep="feat({phase}-{plan}):" --grep="fix({phase}-{plan}):" --grep="test({phase}-{plan}):" --reverse | head -1 | cut -d' ' -f1)
 git diff --name-only ${FIRST_TASK}^..HEAD 2>/dev/null
 ```
 

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

@@ -63,7 +63,7 @@ All subsequent steps use these resolved paths. Never reference PROJECT.md, STATE
 ## 1. Load Context
 
 - 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
+- Read `${product_milestones_path}` (product-level MILESTONES.md — authoritative record of what shipped across ALL projects in this product; used here for the global version sequence — phase numbering is NOT global, it restarts per milestone (see Step 10)) — 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)
@@ -112,9 +112,19 @@ The verb implements, in this exact canonical order:
    `adhoc_base_ref`. Any repo failure → ROLLBACK.
 4. **Confirm marker on the worktree entry (ADH-04 mirror).** Verify the entry
    now carries `adhoc:true` and `adhoc_base_ref`. If absent → ROLLBACK.
-5. **Commit STATE.md with `adhoc:true` (ADH-04 primary).** Write the milestone
-   fields (name, `vX.Y`, status) PLUS `adhoc: true` to STATE.md frontmatter (the
-   `state set-adhoc` helper) and commit it. Commit failure → ROLLBACK.
+5. **Seed planning scaffolding + commit STATE.md & ROADMAP.md (ADH-04 primary).**
+   In ONE atomic commit the verb now also folds in the planning scaffolding that
+   lets a hand-added phase flow through discuss/plan/execute-phase:
+   - (5a) Write the milestone fields (name, `vX.Y`, status) PLUS `adhoc: true` AND
+     `current_milestone: vX.Y` (the authoritative version signal — see the
+     Sole setters note) to STATE.md frontmatter.
+   - (5b) Seed an `## Active Milestone: vX.Y` section into ROADMAP.md (idempotent)
+     terminated by a `---` anchor so `/dgs:add-phase` can extend it.
+   - (5c) Create the versioned phases directory `phases/<version>/` so the
+     version-aware resolver routes the first `add-phase` into it (restart-at-1
+     `01-<slug>`), with no requirements/roadmapper ceremony.
+   - (5d) Stage STATE.md AND ROADMAP.md and commit. Commit failure → ROLLBACK
+     (the three artifacts are rolled back together).
 6. **Set `execution.active_context` LAST (ADH-03).**
    `config-local-set execution.active_context {slug}` — set ONLY after steps 2–5
    succeed, so `detectQuickMode` never observes a half-created milestone (no leak
@@ -122,12 +132,18 @@ The verb implements, in this exact canonical order:
 
 **ROLLBACK (ADH-18) — undo in reverse, only this invocation's artifacts:**
 1. `active_context` is set last, so a pre-step-6 failure never set it.
-2. Reset the just-made STATE.md commit if step 5 committed.
-3. Remove created worktrees: `worktrees remove {slug} --force` (also nulls
+2. Drop the seeded versioned dir `phases/<version>/` (it is untracked, so a
+   commit-reset alone never removes it).
+3. If step 5 committed: reset the just-made STATE.md + ROADMAP.md commit (reverts
+   both `current_milestone` and the Active Milestone section). If the failure hit
+   the PRE-commit window (5c/5d): restore STATE.md + ROADMAP.md from HEAD so the
+   on-disk `current_milestone` + roadmap section never survive.
+4. Remove created worktrees: `worktrees remove {slug} --force` (also nulls
    `active_context`).
-4. Delete the base ref: `git -C <planning_root> update-ref -d refs/dgs/adhoc/{slug}/base`.
-5. Print an actionable error naming what was rolled back; exit non-zero.
-Leave NO residue — no ref, no worktree entry, no marker, `active_context` unset.
+5. Delete the base ref: `git -C <planning_root> update-ref -d refs/dgs/adhoc/{slug}/base`.
+6. Print an actionable error naming what was rolled back; exit non-zero.
+Leave NO residue — no versioned dir, no roadmap section, no `current_milestone`,
+no ref, no worktree entry, no marker, `active_context` unset.
 
 **On success — ADH-22 advisory.** The verb prints:
 "Advisory: while this ad-hoc milestone is active, any product-level (`--main`)
@@ -250,6 +266,10 @@ Status: Defining requirements
 Last activity: [today] — Milestone v[X.Y] started (from spec [spec-id])
 ```
 
+Also write the structured frontmatter field `current_milestone: v[X.Y]` into STATE.md frontmatter (the chosen version, validated against `^v\d+\.\d+$` — e.g. `current_milestone: v25.0`). This is the authoritative structured version signal that resolveMilestoneVersion reads.
+
+> **Sole setters:** `current_milestone` is the authoritative structured version signal. The new-milestone flow, `init.cjs`, AND `milestone create-adhoc` are the SOLE setters of this field — no other command sets or clears it. Only ever write a grammar-valid `v[X.Y]` value; never write an out-of-grammar value.
+
 ### Commit
 
 ```bash
@@ -398,6 +418,10 @@ Status: Defining requirements
 Last activity: [today] — Milestone v[X.Y] started
 ```
 
+Also write the structured frontmatter field `current_milestone: v[X.Y]` into STATE.md frontmatter (the chosen version, validated against `^v\d+\.\d+$` — e.g. `current_milestone: v25.0`). This is the authoritative structured version signal that resolveMilestoneVersion reads.
+
+> **Sole setters:** `current_milestone` is the authoritative structured version signal. The new-milestone flow, `init.cjs`, AND `milestone create-adhoc` are the SOLE setters of this field — no other command sets or clears it. Only ever write a grammar-valid `v[X.Y]` value; never write an out-of-grammar value.
+
 Keep Accumulated Context section from previous milestone.
 
 ## 6. Cleanup and Commit
@@ -604,7 +628,7 @@ node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: define mile
 ◆ Spawning roadmapper...
 ```
 
-**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.
+**Starting phase number:** Phase numbering restarts at 1 for every milestone (written zero-padded as `01`). The new milestone's phases live in its own `phases/<version>/` directory, so numbers are scoped to this milestone — do NOT read MILESTONES.md for phase continuity (versions stay global; phase numbers do not).
 
 ```
 Task(prompt="
@@ -622,7 +646,7 @@ Task(prompt="
 
 <instructions>
 Create roadmap for milestone v[X.Y]:
-1. Start phase numbering from [N]
+1. Start phase numbering at 1 (zero-padded `01`)
 2. Derive phases from THIS MILESTONE's requirements only
 3. Map every requirement to exactly one phase
 4. Derive 2-5 success criteria per phase (observable user behaviors)
@@ -673,6 +697,16 @@ Success criteria:
 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
 ```
 
+### Create the versioned phases directory
+
+Materialise the milestone's own active-phases directory so the version-aware resolver and add-phase land in it (only the new-milestone flow creates a versioned directory):
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs phase init-versioned-dir --raw
+```
+
+This fails loud (non-zero, remediation message) if `current_milestone` is undeterminable — it never writes `phases/v1.0/`. It is idempotent (re-running is a safe no-op).
+
 ## 10.5. Overlap Check (v2 only)
 
 If v2 install (PROJECTS.md or REPOS.md exists in the planning root):
@@ -745,7 +779,7 @@ Also: `/dgs:plan-phase [N]` — skip discussion, plan directly
 - [ ] dgs-roadmapper spawned with phase numbering context
 - [ ] Roadmap files written immediately (not draft)
 - [ ] User feedback incorporated (if any)
-- [ ] ROADMAP.md phases continue from previous milestone
+- [ ] ROADMAP.md phase numbering restarts at 01 for this milestone
 - [ ] All commits made (if planning docs committed)
 - [ ] User knows next step: `/dgs:discuss-phase [N]`
 - [ ] Auto mode: spec parsed and validated (status: final)

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

@@ -13,7 +13,7 @@ Requires explicit confirmation before proceeding. This is destructive and cannot
 Check for active product-level quick:
 ```bash
 ACTIVE=$(node -e "
-  const q = require('$HOME/.claude/deliver-great-systems/bin/lib/quick.cjs');
+  const q = require(process.env.HOME + '/.claude/deliver-great-systems/bin/lib/quick.cjs');
   const a = q.getActiveQuick(process.cwd());
   process.stdout.write(JSON.stringify(a || { none: true }));
 ")

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

@@ -97,7 +97,7 @@ Detect whether this is a product-level or milestone-context quick:
 
 ```bash
 QUICK_DETECT=$(node -e "
-  const q = require('$HOME/.claude/deliver-great-systems/bin/lib/quick.cjs');
+  const q = require(process.env.HOME + '/.claude/deliver-great-systems/bin/lib/quick.cjs');
   const r = q.detectQuickMode(process.cwd(), ${FORCE_MAIN:-false});
   process.stdout.write(JSON.stringify(r));
 ")
@@ -113,7 +113,7 @@ Check the one-active-quick guard and create worktree:
 
 ```bash
 QUICK_START=$(node -e "
-  const q = require('$HOME/.claude/deliver-great-systems/bin/lib/quick.cjs');
+  const q = require(process.env.HOME + '/.claude/deliver-great-systems/bin/lib/quick.cjs');
   const r = q.startProductQuick(process.cwd(), '${DESCRIPTION}', ${QUICK_MODE_FLAG ? \"'\" + QUICK_MODE_FLAG + \"'\" : 'null'});
   process.stdout.write(JSON.stringify(r));
 ")
@@ -158,7 +158,7 @@ QUICK_REPO_CWD=$(node -e "
   const path = require('path');
   const localPath = path.join(process.cwd(), 'config.local.json');
   const local = JSON.parse(fs.readFileSync(localPath, 'utf-8'));
-  const { loadConfig } = require('$HOME/.claude/deliver-great-systems/bin/lib/core.cjs');
+  const { loadConfig } = require(process.env.HOME + '/.claude/deliver-great-systems/bin/lib/core.cjs');
   const cfg = loadConfig(process.cwd());
   const proj = cfg.current_project;
   const wt = (local.projects && local.projects[proj] && local.projects[proj].worktrees && local.projects[proj].worktrees['${MILESTONE_SLUG}']) || {};

package/package.json

@@ -8,7 +8,7 @@
   "bugs": {
     "url": "https://github.com/KT-Partners-Ltd/dgs-platform-docs/issues"
   },
-  "version": "3.4.2",
+  "version": "3.5.1",
   "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"
@@ -57,6 +57,7 @@
   "scripts": {
     "build:hooks": "node scripts/build-hooks.js",
     "prepublishOnly": "npm run build:hooks",
-    "test": "node --test tests/*.test.cjs"
+    "test": "node --test tests/*.test.cjs deliver-great-systems/bin/lib/*.test.cjs",
+    "test:lib": "node --test deliver-great-systems/bin/lib/*.test.cjs"
   }
 }