@ktpartners/dgs-platform 3.4.2 → 3.5.0

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.0",
   "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"
   }
 }