@ktpartners/dgs-platform 3.4.1 → 3.5.0

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

@@ -5,7 +5,8 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
-const { escapeRegex, getMilestonePhaseFilter, getProjectRoot, output, error, loadConfig } = require('./core.cjs');
+const { escapeRegex, getMilestonePhaseFilter, getProjectRoot, output, error, loadConfig, phasesDir, resolveMilestoneVersion, resolveProjectPath } = require('./core.cjs');
+const { phaseInitVersionedDirInternal } = require('./phase.cjs');
 const { extractFrontmatter, spliceFrontmatter } = require('./frontmatter.cjs');
 const { getPlanningRoot } = require('./paths.cjs');
 const { writeStateMd, stateReadAdhoc } = require('./state.cjs');
@@ -118,7 +119,9 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
   const statePath = path.join(projectRoot, 'STATE.md');
   const milestonesPath = path.join(planRoot, 'MILESTONES.md');
   const archiveDir = path.join(planRoot, 'milestones');
-  const phasesDir = path.join(projectRoot, 'phases');
+  const phasesAbs = path.join(cwd, phasesDir(cwd));
+  // Versioned layout → phases/<version>/ is milestone-scoped; flat → shared phases/ needs number-set filtering.
+  const versionedLayout = /^v\d+\.\d+$/.test(path.basename(phasesDir(cwd)));
   const today = new Date().toISOString().split('T')[0];
   const milestoneName = options.name || version;
 
@@ -128,6 +131,8 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
   // Scope stats and accomplishments to only the phases belonging to the
   // current milestone's ROADMAP.  Uses the shared filter from core.cjs
   // (same logic used by cmdPhasesList and other callers).
+  // Version-aware as of NUM-04: returns a pass-all predicate under versioned
+  // layout, so the stats loop counts every entry in phases/<version>/.
   const isDirInMilestone = getMilestonePhaseFilter(cwd);
 
   // Gather stats from phases (scoped to current milestone only)
@@ -137,14 +142,14 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
   const accomplishments = [];
 
   try {
-    const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+    const entries = fs.readdirSync(phasesAbs, { withFileTypes: true });
     const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort();
 
     for (const dir of dirs) {
       if (!isDirInMilestone(dir)) continue;
 
       phaseCount++;
-      const phaseFiles = fs.readdirSync(path.join(phasesDir, dir));
+      const phaseFiles = fs.readdirSync(path.join(phasesAbs, dir));
       const plans = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md');
       const summaries = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
       totalPlans += plans.length;
@@ -152,7 +157,7 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
       // Extract one-liners from summaries
       for (const s of summaries) {
         try {
-          const content = fs.readFileSync(path.join(phasesDir, dir, s), 'utf-8');
+          const content = fs.readFileSync(path.join(phasesAbs, dir, s), 'utf-8');
           const fm = extractFrontmatter(content);
           if (fm['one-liner']) {
             accomplishments.push(fm['one-liner']);
@@ -302,17 +307,29 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
   if (options.archivePhases) {
     try {
       const phaseArchiveDir = path.join(archiveDir, `${version}-phases`);
-      fs.mkdirSync(phaseArchiveDir, { recursive: true });
-
-      const phaseEntries = fs.readdirSync(phasesDir, { withFileTypes: true });
-      const phaseDirNames = phaseEntries.filter(e => e.isDirectory()).map(e => e.name);
-      let archivedCount = 0;
-      for (const dir of phaseDirNames) {
-        if (!isDirInMilestone(dir)) continue;
-        fs.renameSync(path.join(phasesDir, dir), path.join(phaseArchiveDir, dir));
-        archivedCount++;
+      if (versionedLayout) {
+        // NUM-03: phases/<version>/ is the whole milestone → archive in ONE move.
+        // Collision guard: never overwrite/merge an existing archive (no mkdir of dest —
+        // renameSync of a dir requires the destination to NOT exist).
+        if (fs.existsSync(phaseArchiveDir)) {
+          error(`Cannot archive phases: ${phaseArchiveDir} already exists. Move or remove it, then re-run milestone complete --archive-phases.`);
+          return;
+        }
+        fs.renameSync(phasesAbs, phaseArchiveDir);
+        phasesArchived = true;
+      } else {
+        // Flat mode: shared phases/ — preserve the per-directory filtered move byte-for-byte.
+        fs.mkdirSync(phaseArchiveDir, { recursive: true });
+        const phaseEntries = fs.readdirSync(phasesAbs, { withFileTypes: true });
+        const phaseDirNames = phaseEntries.filter(e => e.isDirectory()).map(e => e.name);
+        let archivedCount = 0;
+        for (const dir of phaseDirNames) {
+          if (!isDirInMilestone(dir)) continue;
+          fs.renameSync(path.join(phasesAbs, dir), path.join(phaseArchiveDir, dir));
+          archivedCount++;
+        }
+        phasesArchived = archivedCount > 0;
       }
-      phasesArchived = archivedCount > 0;
     } catch {}
   }
 
@@ -431,6 +448,46 @@ function _adhocTools(cwd, argStr) {
   }
 }
 
+/**
+ * Seed an `## Active Milestone: <version>` section into ROADMAP.md (Decision A).
+ *
+ * Idempotent: if a `## Active Milestone: <version>` heading already exists, it
+ * returns false without writing. Otherwise it strips a placeholder
+ * `### 📋 Next Milestone — TBD` block (if present) and APPENDS the active section
+ * terminated by `\n---\n`, so the section's trailing separator becomes the file's
+ * LAST `\n---` — exactly the anchor cmdPhaseAdd inserts `### Phase N:` entries
+ * before. With zero `### Phase` headings present, the first add-phase computes
+ * maxPhase=0 → Phase 1 / 01-<slug> under phases/<version>/.
+ *
+ * Guard: if the roadmap file does not exist, returns false (create-adhoc's STATE
+ * existence check is the authoritative precondition; we never crash here).
+ *
+ * @returns {boolean} true if it wrote the section, false on no-op.
+ */
+function seedAdhocRoadmapSection(roadmapPath, version, name) {
+  if (!fs.existsSync(roadmapPath)) return false;
+  let content = fs.readFileSync(roadmapPath, 'utf-8');
+  // Idempotent: already seeded for this version → no-op.
+  if (new RegExp('^##\\s+Active Milestone:\\s*' + escapeRegex(version) + '\\b', 'm').test(content)) {
+    return false;
+  }
+  // Strip a placeholder "### 📋 Next Milestone — TBD" heading-and-body block if
+  // present (consume up to the next heading / separator / EOF).
+  content = content.replace(
+    /\n?#{2,3}\s*(?:📋\s*)?Next Milestone\s*[—-]\s*TBD[\s\S]*?(?=\n#{1,3}\s|\n---|$)/,
+    ''
+  );
+  // Normalize trailing whitespace to a single newline, then append the section.
+  content = content.replace(/\s*$/, '\n');
+  const section =
+    '\n## Active Milestone: ' + version + ' ' + name + '\n\n' +
+    '**Goal:** ' + name + '\n' +
+    '**Status:** In progress (ad-hoc container — phases added on demand via /dgs:add-phase)\n\n' +
+    'Phases:\n\n---\n';
+  fs.writeFileSync(roadmapPath, content + section, 'utf-8');
+  return true;
+}
+
 /**
  * Create an ad-hoc milestone container atomically (Phase 159).
  *
@@ -508,13 +565,34 @@ function cmdMilestoneCreateAdhoc(cwd, args, raw) {
   let refCreated = false;
   let worktreesCreated = false;
   let stateCommitHash = null;
-  const statePath = path.join(planningRoot, getProjectRoot(cwd), 'STATE.md');
+  // Decision D — seeded-scaffolding rollback bookkeeping. The versioned dir is
+  // untracked (empty at creation) so a commit-reset never removes it; rollback
+  // drops it explicitly.
+  let versionedDirCreated = false;
+  let versionedDirAbs = null;
+  const projRootRel = getProjectRoot(cwd);
+  const statePath = path.join(planningRoot, projRootRel, 'STATE.md');
+  const roadmapPath = path.join(planningRoot, projRootRel, 'ROADMAP.md');
 
   const rollback = (reasonMsg) => {
     // Reverse order. active_context is set LAST so a pre-step-6 failure never set it.
+    // (i) Drop the seeded versioned dir first — it is untracked, so neither the
+    //     commit-reset nor a doc restore would remove it.
+    if (versionedDirCreated && versionedDirAbs) {
+      try { fs.rmSync(versionedDirAbs, { recursive: true, force: true }); } catch {}
+    }
     if (stateCommitHash) {
-      // Reset the just-made STATE commit (not yet pushed at this point).
+      // Post-commit failure: the reset reverts BOTH staged docs (STATE + ROADMAP).
       _adhocGit(planningRoot, ['reset', '--hard', stateCommitHash + '^']);
+    } else {
+      // Pre-commit failure (5c versioned-dir / 5d add-or-commit): the on-disk
+      // current_milestone + Active Milestone section were written but never
+      // committed. Restore both docs from HEAD so NO residue survives — this
+      // makes the "no residue on any step-5 failure" guarantee hold literally
+      // regardless of which window the failure hits (plan-check advisory).
+      _adhocGit(planningRoot, ['checkout', 'HEAD', '--',
+        path.relative(planningRoot, statePath),
+        path.relative(planningRoot, roadmapPath)]);
     }
     if (worktreesCreated) {
       _adhocTools(cwd, 'worktrees remove ' + JSON.stringify(slug) + ' --force');
@@ -522,7 +600,7 @@ function cmdMilestoneCreateAdhoc(cwd, args, raw) {
     if (refCreated) {
       _adhocGit(planningRoot, ['update-ref', '-d', baseRef]);
     }
-    error(reasonMsg + ' — rolled back (no worktree, no base ref, no STATE marker, active_context unset).');
+    error(reasonMsg + ' — rolled back (no versioned dir, no roadmap section, no current_milestone, no worktree, no base ref, no STATE marker, active_context unset).');
   };
 
   // ── Step 2 — capture planning base ref (ADH-06). ──
@@ -549,7 +627,10 @@ function cmdMilestoneCreateAdhoc(cwd, args, raw) {
   } catch { entryOk = false; }
   if (!entryOk) rollback('Worktree entry missing adhoc marker / base-ref');
 
-  // ── Step 5 — commit STATE.md with adhoc:true + milestone vX.Y (ADH-04 primary). ──
+  // ── Step 5 — seed planning scaffolding + commit STATE.md & ROADMAP.md atomically
+  //    (ADH-04 primary + Decision D). Folds current_milestone (5a), the Active
+  //    Milestone ROADMAP section (5b), and the versioned phases dir (5c) into ONE
+  //    commit (5d), all undone in reverse by rollback(). ──
   if (!fs.existsSync(statePath)) rollback('STATE.md not found at ' + statePath);
   try {
     const content = fs.readFileSync(statePath, 'utf-8');
@@ -558,17 +639,37 @@ function cmdMilestoneCreateAdhoc(cwd, args, raw) {
     fm.milestone_name = name;
     fm.status = 'executing';
     fm.adhoc = true;
+    // 5a — the authoritative version signal. The verb already validated/normalized
+    // `version` to a grammar-valid vX.Y, so create-adhoc is a SOLE setter of it.
+    fm.current_milestone = version;
     const newContent = spliceFrontmatter(content, fm);
     fs.writeFileSync(statePath, newContent, 'utf-8');
   } catch (e) {
     rollback('Failed to write STATE.md adhoc marker: ' + e.message);
   }
+
+  // 5b — seed the ROADMAP active-milestone section (idempotent, guarded).
+  seedAdhocRoadmapSection(roadmapPath, version, name);
+
+  // 5c — create phases/<version>/ via the SHARED versioned-dir creator. Track
+  //      whether THIS call materialized it so rollback can drop the untracked dir.
+  try {
+    const r = phaseInitVersionedDirInternal(cwd);
+    versionedDirAbs = path.join(cwd, r.directory);
+    versionedDirCreated = r.created;
+  } catch (e) {
+    rollback('Failed to create versioned phases dir: ' + e.message);
+  }
+
+  // 5d — stage BOTH docs (STATE.md + ROADMAP.md if present) and commit atomically.
   const stateRel = path.relative(planningRoot, statePath);
-  const addRes = _adhocGit(planningRoot, ['add', stateRel]);
-  if (!addRes.ok) rollback('Failed to stage STATE.md: ' + addRes.stderr);
+  const stagePaths = [stateRel];
+  if (fs.existsSync(roadmapPath)) stagePaths.push(path.relative(planningRoot, roadmapPath));
+  const addRes = _adhocGit(planningRoot, ['add'].concat(stagePaths));
+  if (!addRes.ok) rollback('Failed to stage planning docs: ' + addRes.stderr);
   const commitRes = _adhocGit(planningRoot, ['commit', '-m',
     'feat(milestone): establish ad-hoc container ' + slug + ' (' + version + ')']);
-  if (!commitRes.ok) rollback('Failed to commit STATE.md: ' + commitRes.stderr);
+  if (!commitRes.ok) rollback('Failed to commit planning docs: ' + commitRes.stderr);
   const hashRes = _adhocGit(planningRoot, ['rev-parse', 'HEAD']);
   stateCommitHash = hashRes.ok ? hashRes.stdout : null;
 
@@ -671,6 +772,20 @@ function cmdAbandonMilestone(cwd, args, raw) {
     error('Planning docs have uncommitted/staged edits (' + dirty.stdout.trim() + '). Commit or discard them first, then retry /dgs:abandon-milestone. No changes made.');
   }
 
+  // ── Decision E — resolve the seeded versioned phases dir (phases/<version>/) EARLY,
+  //    from the still-present current_milestone (the 6b restore wipes it). It is removed
+  //    in teardown so abandon leaves no versioned residue. Guarded/non-fatal: a no-op when
+  //    the version is undeterminable or the dir is absent. ──
+  let versionedAbs = null, relVersioned = null;
+  try {
+    const v = resolveMilestoneVersion(cwd);
+    if (v) {
+      const base = resolveProjectPath(cwd, 'phases');
+      const abs = path.join(planningRoot, base, v);
+      if (fs.existsSync(abs)) { versionedAbs = abs; relVersioned = path.relative(planningRoot, abs); }
+    }
+  } catch { /* undeterminable version — leave versionedAbs null (no-op) */ }
+
   // ── Step 5 — delete the OWNED pushed milestone branch on origin (ADH-20).
   //    For each repo whose remote-tracking ref exists, run a NON-FATAL
   //    `git push origin --delete milestone/<slug>` so the milestone name is
@@ -706,6 +821,20 @@ function cmdAbandonMilestone(cwd, args, raw) {
       'Re-run /dgs:abandon-milestone after resolving, or remove the worktree manually.');
   }
 
+  // Decision E — remove the seeded versioned phases dir (phases/<version>/) so abandon
+  // leaves no versioned residue. Stage any TRACKED phase files for deletion so they land
+  // in the 6c attributed reversion commit. Non-fatal/guarded: abandon still reports
+  // abandoned:true when the dir was already absent (the seeded dir is normally empty +
+  // untracked, so this is a pure on-disk cleanup unless real phases were added/committed).
+  let phasesDirRemoved = null;
+  if (versionedAbs) {
+    try { fs.rmSync(versionedAbs, { recursive: true, force: true }); } catch {}
+    if (relVersioned) {
+      _adhocGit(planningRoot, ['add', '-A', '--', relVersioned]);
+      phasesDirRemoved = relVersioned;
+    }
+  }
+
   // 6b. Path-scoped restore of exactly the present docs (ADH-09). NEVER a
   //     whole-tree reset / checkout <ref> .
   if (present.length > 0) {
@@ -720,29 +849,30 @@ function cmdAbandonMilestone(cwd, args, raw) {
     reverted.docs = true; // nothing to restore
   }
 
-  // 6c. Attributed reversion commit (ADH-20). Skip gracefully if the restore
-  //     produced no staged change (base === current for these docs).
+  // 6c. Attributed reversion commit (ADH-20). The commit guard is the STAGED state,
+  //     not present.length, so it also fires when the ONLY change is the versioned-dir
+  //     deletion staged above. Skips gracefully if nothing is staged (base === current
+  //     for the docs AND no tracked versioned files existed).
   if (present.length > 0) {
     const addRes = _adhocGit(planningRoot, ['add', '--'].concat(present));
     if (!addRes.ok) {
       error('Docs restored but failed to stage them: ' + addRes.stderr +
         '. Reverted so far: ' + JSON.stringify(reverted) + '. Recoverable — stage and commit the restored docs manually.');
     }
-    const hasStaged = !_adhocGit(planningRoot, ['diff', '--cached', '--quiet']).ok;
-    if (hasStaged) {
-      const author = formatAuthorString(requireGitIdentity(cwd));
-      const commitRes = _adhocGit(planningRoot, ['commit', '--author', author, '-m',
-        'revert(milestone): abandon ad-hoc ' + slug + ' — restore project docs to pre-milestone state']);
-      reverted.committed = commitRes.ok;
-      if (!commitRes.ok) {
-        error('Docs restored + staged but commit failed: ' + commitRes.stderr +
-          '. Reverted so far: ' + JSON.stringify(reverted) + '. Recoverable — commit the staged docs manually.');
-      }
-    } else {
-      // No diff to commit — restore was a no-op (base == current). Treated as success.
-      reverted.committed = true;
+  }
+  const hasStaged = !_adhocGit(planningRoot, ['diff', '--cached', '--quiet']).ok;
+  if (hasStaged) {
+    const author = formatAuthorString(requireGitIdentity(cwd));
+    const commitRes = _adhocGit(planningRoot, ['commit', '--author', author, '-m',
+      'revert(milestone): abandon ad-hoc ' + slug + ' — restore project docs to pre-milestone state']);
+    reverted.committed = commitRes.ok;
+    if (!commitRes.ok) {
+      error('Docs restored + staged but commit failed: ' + commitRes.stderr +
+        '. Reverted so far: ' + JSON.stringify(reverted) + '. Recoverable — commit the staged docs manually.');
     }
   } else {
+    // Nothing staged — restore was a no-op (base == current) and no tracked versioned
+    // files existed. Treated as success.
     reverted.committed = true;
   }
 
@@ -761,6 +891,7 @@ function cmdAbandonMilestone(cwd, args, raw) {
     base_ref: baseRef,
     restored: present,
     reverted,
+    phases_dir_removed: phasesDirRemoved,
     base_ref_deleted: cleanup.ref_deleted,
     warnings,
   }, raw);

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

@@ -622,7 +622,10 @@ function addMalformedQuickRow(planDir) {
  * disk_status==='complete'; complete=false → PLAN.md only (planned, not counted).
  */
 function addCompletedPhase(planDir, { complete }) {
-  const phaseDir = path.join(planDir, 'projects', 'tp', 'phases', '01-foo');
+  // setupAdhoc seeds phases/v0.1/ and current_milestone:v0.1, so the version-aware
+  // resolver now routes phase lookups into phases/v0.1/ — write the fixture phase
+  // there (not the flat phases/) so adhoc-readiness enumerates it.
+  const phaseDir = path.join(planDir, 'projects', 'tp', 'phases', 'v0.1', '01-foo');
   fs.mkdirSync(phaseDir, { recursive: true });
   fs.writeFileSync(path.join(phaseDir, '01-01-PLAN.md'), '# Plan\n');
   if (complete) {
@@ -854,3 +857,112 @@ describe('milestone cleanup-adhoc / lifecycle cleanup', () => {
     assert.ok(/abandon-milestone/.test(doc), 'claude-md.md must mention abandon-milestone');
   });
 });
+
+// ─── ad-hoc full lifecycle seeding (quick-260627-mv4) ────────────────────────
+//
+// Proves create-adhoc seeds the planning scaffolding that lets a hand-added
+// phase flow through discuss/plan/execute-phase: current_milestone + the
+// versioned phases dir + an Active Milestone ROADMAP section, all atomic and
+// rolled back together; that the first add-phase lands 01-<slug> UNDER
+// phases/<version>/ (restart-at-1); that the roadmap seed is idempotent; that
+// abandon removes the versioned dir + restores the docs; and that a precondition
+// failure leaves the first milestone's seed intact with no new residue.
+
+describe('ad-hoc full lifecycle seeding', () => {
+  let env;
+  beforeEach(() => { env = createAbandonEnv(); });
+  afterEach(() => { if (env) env.cleanup(); });
+
+  it('SEED: create-adhoc writes current_milestone + phases/<version>/ + Active Milestone section', () => {
+    setupAdhoc(env.planDir);
+
+    // (a) STATE.md frontmatter carries the authoritative current_milestone signal.
+    const stateContent = fs.readFileSync(path.join(env.planDir, _STATE_PATH_REL), 'utf-8');
+    assert.match(stateContent, /current_milestone:\s*v0\.1\b/, 'STATE.md must carry current_milestone: v0.1');
+
+    // (b) the versioned phases dir exists on disk.
+    assert.ok(
+      fs.existsSync(path.join(env.planDir, 'projects', 'tp', 'phases', 'v0.1')),
+      'projects/tp/phases/v0.1/ must exist after create-adhoc'
+    );
+
+    // (c) ROADMAP.md has the Active Milestone section terminated by a --- anchor.
+    const roadmap = fs.readFileSync(path.join(env.planDir, _ROADMAP_PATH_REL), 'utf-8');
+    assert.match(roadmap, /^##\s+Active Milestone:\s*v0\.1\b/m, 'ROADMAP must have ## Active Milestone: v0.1');
+    assert.ok(roadmap.trimEnd().endsWith('---'), 'ROADMAP must end with a --- anchor for add-phase');
+  });
+
+  it('RESTART-AT-1: first add-phase lands 01-<slug> UNDER phases/v0.1/ (milestone-local)', () => {
+    setupAdhoc(env.planDir);
+
+    const res = abandonRun(env.planDir, 'phase add ' + JSON.stringify('do a thing'));
+    assert.equal(res.padded, '01', 'first add-phase under an empty milestone restarts at 01');
+    const dirPosix = res.directory.split(path.sep).join('/');
+    assert.ok(
+      dirPosix.includes('phases/v0.1/01-'),
+      'add-phase directory must be under phases/v0.1/ : ' + res.directory
+    );
+    assert.ok(fs.existsSync(path.join(env.planDir, res.directory)), 'the 01- phase dir must exist on disk');
+  });
+
+  it('IDEMPOTENT ROADMAP SEED: exactly one ## Active Milestone: v0.1 after create', () => {
+    setupAdhoc(env.planDir);
+    const roadmap = fs.readFileSync(path.join(env.planDir, _ROADMAP_PATH_REL), 'utf-8');
+    const occurrences = (roadmap.match(/^##\s+Active Milestone:\s*v0\.1\b/gm) || []).length;
+    assert.equal(occurrences, 1, 'the Active Milestone section must not be duplicated');
+  });
+
+  it('ABANDON REMOVES VERSIONED DIR: phases/v0.1/ gone + docs restored to pre-milestone', () => {
+    setupAdhoc(env.planDir);
+    const result = abandonRun(env.planDir, 'milestone abandon --confirmed');
+    assert.equal(result.abandoned, true);
+    // The removed versioned dir is reported.
+    assert.match(String(result.phases_dir_removed || ''), /phases[\\/]v0\.1$/, 'phases_dir_removed should name the versioned dir');
+
+    // Versioned dir is gone from disk.
+    assert.ok(
+      !fs.existsSync(path.join(env.planDir, 'projects', 'tp', 'phases', 'v0.1')),
+      'phases/v0.1/ must be removed by abandon'
+    );
+    // ROADMAP restored: no Active Milestone section.
+    const roadmap = fs.readFileSync(path.join(env.planDir, _ROADMAP_PATH_REL), 'utf-8');
+    assert.ok(!/##\s+Active Milestone/.test(roadmap), 'ROADMAP must no longer contain an Active Milestone section');
+    // STATE restored: no current_milestone.
+    const stateContent = fs.readFileSync(path.join(env.planDir, _STATE_PATH_REL), 'utf-8');
+    assert.ok(!/current_milestone:/.test(stateContent), 'STATE.md must no longer carry current_milestone');
+  });
+
+  it('ROLLBACK-NO-RESIDUE: a precondition failure leaves the first seed intact and adds nothing', () => {
+    const { slug } = setupAdhoc(env.planDir);
+
+    // A second create-adhoc while a context is active fails at the precondition
+    // guard (before any mutation). The first milestone's seed must be untouched
+    // and NO second versioned dir / dirty doc residue may appear.
+    const out = abandonRunFail(env.planDir, 'milestone create-adhoc ' + JSON.stringify('second one') + ' --version v0.2');
+    assert.ok(out, 'second create-adhoc must fail while a context is active');
+
+    // First seed intact.
+    const stateContent = fs.readFileSync(path.join(env.planDir, _STATE_PATH_REL), 'utf-8');
+    assert.match(stateContent, /current_milestone:\s*v0\.1\b/, 'first current_milestone must survive');
+    assert.ok(fs.existsSync(path.join(env.planDir, 'projects', 'tp', 'phases', 'v0.1')), 'first phases/v0.1/ must survive');
+
+    // No residue from the failed attempt.
+    assert.ok(!fs.existsSync(path.join(env.planDir, 'projects', 'tp', 'phases', 'v0.2')), 'no phases/v0.2/ residue');
+    const roadmap = fs.readFileSync(path.join(env.planDir, _ROADMAP_PATH_REL), 'utf-8');
+    assert.equal(
+      (roadmap.match(/^##\s+Active Milestone:/gm) || []).length, 1,
+      'no duplicate / second Active Milestone section from the failed attempt'
+    );
+
+    // active_context unchanged.
+    const cfg = readLocal(env.planDir);
+    assert.equal(cfg.execution.active_context, slug, 'active_context must be unchanged after a failed create');
+
+    // Planning tree carries no dirty STATE.md/ROADMAP.md residue (rollback no-residue guarantee).
+    const porcelain = _execSync(
+      'git status --porcelain -- ' + JSON.stringify(_STATE_PATH_REL) + ' ' + JSON.stringify(_ROADMAP_PATH_REL),
+      { cwd: env.planDir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
+    ).trim();
+    assert.equal(porcelain, '', 'STATE.md/ROADMAP.md must not be left dirty after a failed create-adhoc');
+  });
+});

package/deliver-great-systems/bin/lib/path-audit.test.cjs

@@ -272,6 +272,134 @@ describe('path audit: comprehensive .planning/ reference scanning', () => {
     }
   });
 
+  // ─── Phases-Path Seam Gate (RSLV-03) ────────────────────────────────────
+  // Enforces the one-seam invariant from Phase 164: all active-project phases-path
+  // resolution routes through core.cjs phasesDir(cwd). Any NEW ad-hoc
+  // path.join(..., 'phases') active-project construction in a non-test lib module
+  // is a regression (re-introduces the split-brain that Phase 164 consolidated).
+  //
+  // The empirically-derived exclusion model (validated against the real
+  // post-164-04 tree, NOT the plan's pre-migration model — the tree drifted):
+  //
+  //  COMMENT-STRIP — trailing // line-comments are stripped before matching, and
+  //    lines that are pure // or * (JSDoc) comments are skipped. This clears
+  //    core.cjs:297 / phase.cjs:21 (`phasesRel = 'phases';   // ... path.join('.','phases')`)
+  //    and the core.cjs:776 / phase.cjs:13 JSDoc mentions WITHOUT allowlisting those
+  //    files (their canonical-resolver code carries no gate-matching construction).
+  //
+  //  (1) PER-LINE FALLBACK_SKIPS — retained catch-branch fallbacks that migrated
+  //      files legitimately keep (the IN-SCOPE try branch routes through
+  //      phasesDir(cwd), which carries no 'phases' literal, so the file stays gated):
+  //        - getPlanningRoot(cwd),'phases'  → commands.cjs:153, state.cjs:646
+  //        - path.join(planRootRel,'phases') → init.cjs:865/1065/1262 (whole ctx.root ternary line), commands.cjs:1098
+  //        - path.join(planRoot,'phases')    → commands.cjs:872
+  //        - = path.join(projectRoot,'phases') → state.cjs:300 (phasesRel) AND jobs.cjs:1133/1715/1930 (phasesAbs).
+  //              Anchored on the `= path.join(projectRoot,` assignment so it matches BOTH
+  //              variable names introduced across plans 03/04 (state.cjs uses phasesRel;
+  //              jobs.cjs's three soft-fallback catches use phasesAbs) — the plan's model
+  //              only anticipated the phasesRel form; 164-04 added the phasesAbs sites.
+  //        - path.relative(cwd, planningRoot)..,'phases' → context.cjs:534 planning-root catch
+  //              (retained fallback NOT in the plan's model; surfaced empirically).
+  //
+  //  (2) PER-FILE ALLOWLIST — wholly-different-semantics sites with NO in-scope
+  //      active-project resolution to guard (applied as a PRE-FILTER before scanning):
+  //        overlap.cjs / projects.cjs (by-slug, not current project),
+  //        review.cjs (caller-supplied projectRoot param),
+  //        package-scan-report.cjs (cross-project scan),
+  //        verify.cjs (planning-root health check via planRoot/planningDir variables).
+  //      core.cjs is intentionally NOT allowlisted: Plan 01 migrated findPhaseInternal's
+  //      path.join(projectRoot,'phases') to phasesDir(cwd), so post-migration it carries
+  //      no gate-matching code line (only the comment the strip removes).
+  //
+  // Durable-guard proof recorded in 164-05-SUMMARY.md: with the allowlist filter and
+  // the projectRoot skip disabled, this gate fires on exactly 11 lines across 7 files
+  // {jobs, overlap, package-scan-report, projects, review, state, verify} — proving the
+  // nested-paren regex is not inert and core.cjs/phase.cjs carry no matching code line.
+  it('GATE: zero ad-hoc active-project path.join(..., "phases") in library source (RSLV-03)', () => {
+    const libDir = path.join(DGS_ROOT, 'bin', 'lib');
+
+    // (2) Per-FILE allowlist: { file: 'reason' }. EMPIRICALLY VERIFIED — these are
+    // the only non-fallback files matching the gate regex post-migration AND having
+    // no in-scope active-project site to guard.
+    const ALLOWLIST = {
+      'overlap.cjs': 'by-slug project: path.join(getProjectDir(cwd, slug), "phases") — not current-project',
+      'projects.cjs': 'by-slug project: path.join(getProjectDir(cwd, slug), "phases") — not current-project',
+      'review.cjs': 'caller-supplied projectRoot param: path.join(planningRoot, projectRoot, "phases") — not resolved here',
+      'package-scan-report.cjs': 'cross-project scan: path.join(projectsDir, pEnt.name, "phases") over all projects',
+      'verify.cjs': 'planning-root health check: path.join(planRoot|planningDir, "phases") where the root is getPlanningRoot(cwd) via a variable the generic getPlanningRoot skip does not catch',
+    };
+
+    const files = fs.readdirSync(libDir)
+      .filter(f => f.endsWith('.cjs'))
+      .filter(f => !f.endsWith('.test.cjs'))
+      .filter(f => f !== 'test-helpers.cjs')
+      .filter(f => f !== 'migration.cjs')
+      .filter(f => !(f in ALLOWLIST));   // PRE-FILTER: allowlisted files never line-scanned
+
+    // NESTED-paren tolerant: matches path.join(<x | f(...)>, 'phases'[,)] — one level of
+    // nested parens allowed so getProjectDir(...)/getPlanningRoot(...) forms match (a plain
+    // [^)]* body could not, making nested-call regressions invisible).
+    const PHASES_JOIN_PATTERN = /path\.join\((?:[^()]|\([^()]*\))*,\s*['"]phases['"]\s*[,)]/;
+
+    // (1) Per-LINE generic skips for legitimately-retained fallback branches.
+    const FALLBACK_SKIPS = [
+      /getPlanningRoot\([^)]*\),\s*['"]phases['"]/,                  // path.join(getPlanningRoot(cwd), 'phases')
+      /path\.join\(planRootRel,\s*['"]phases['"]/,                   // init.cjs x3 + commands.cjs:1098 planning-root fallbacks
+      /path\.join\(planRoot,\s*['"]phases['"]/,                      // commands.cjs:872 planRoot fallback
+      /=\s*path\.join\(projectRoot,\s*['"]phases['"]/,               // state.cjs:300 (phasesRel) + jobs.cjs x3 (phasesAbs) projectRoot catches
+      /path\.relative\(cwd,\s*planningRoot\)[^,]*,\s*['"]phases['"]/, // context.cjs:534 planning-root catch
+    ];
+
+    const violations = [];
+    for (const f of files) {
+      const filePath = path.join(libDir, f);
+      const lines = fs.readFileSync(filePath, 'utf-8').split('\n');
+      for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i];
+        if (raw.trimStart().startsWith('//')) continue;
+        if (raw.trimStart().startsWith('*')) continue;
+        const line = raw.replace(/\/\/.*$/, '');   // strip trailing line-comment before matching
+        if (!PHASES_JOIN_PATTERN.test(line)) continue;
+        if (FALLBACK_SKIPS.some(re => re.test(line))) continue;  // retained fallback branch
+        violations.push(`${f}:${i + 1}: ${raw.trim()}`);
+      }
+    }
+
+    if (violations.length > 0) {
+      assert.fail(
+        `Found ${violations.length} ad-hoc path.join(..., 'phases') site(s) outside the canonical resolver:\n` +
+        violations.join('\n') +
+        `\n\nRoute active-project phases-path resolution through core.cjs phasesDir(cwd). ` +
+        `If this is a genuinely different semantic (by-slug / planning-root / cross-project / param), add it to ALLOWLIST with a reason.`
+      );
+    }
+  });
+
+  // Anti-regression: prove the gate WOULD catch a fresh ad-hoc projectRoot+'phases'
+  // construction in a non-fallback, non-comment, non-allowlisted context. Runs the
+  // same regex+skip logic over a synthetic line; the line must be flagged.
+  it('GATE self-test: a fresh ad-hoc path.join(projectRoot, "phases") IS caught (RSLV-03)', () => {
+    const PHASES_JOIN_PATTERN = /path\.join\((?:[^()]|\([^()]*\))*,\s*['"]phases['"]\s*[,)]/;
+    const FALLBACK_SKIPS = [
+      /getPlanningRoot\([^)]*\),\s*['"]phases['"]/,
+      /path\.join\(planRootRel,\s*['"]phases['"]/,
+      /path\.join\(planRoot,\s*['"]phases['"]/,
+      /=\s*path\.join\(projectRoot,\s*['"]phases['"]/,
+      /path\.relative\(cwd,\s*planningRoot\)[^,]*,\s*['"]phases['"]/,
+    ];
+    // A NEW ad-hoc site: not an assignment-form catch (no leading `= `), not a comment,
+    // not a known fallback shape — e.g. used directly as a call argument.
+    const adHoc = `      const dir = path.join(projectRoot, 'phases');`;
+    const stripped = adHoc.replace(/\/\/.*$/, '');
+    assert.ok(PHASES_JOIN_PATTERN.test(stripped), 'regex must match a fresh projectRoot+phases join');
+    // The skip anchored on `= path.join(projectRoot,` does NOT match `= path.join(projectRoot,` here?
+    // It DOES (this is a const assignment). Use a true non-fallback shape: a bare call argument.
+    const adHocArg = `      doThing(path.join(projectRoot, 'phases'));`;
+    const strippedArg = adHocArg.replace(/\/\/.*$/, '');
+    assert.ok(PHASES_JOIN_PATTERN.test(strippedArg), 'regex must match a bare-argument projectRoot+phases join');
+    assert.ok(!FALLBACK_SKIPS.some(re => re.test(strippedArg)), 'a bare-argument ad-hoc site must NOT be covered by any fallback skip — it would be flagged as a violation');
+  });
+
   // ─── Allowlist Verification ─────────────────────────────────────────────
 
   it('allowlisted workflow files exist and are minimal', () => {

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

@@ -93,7 +93,7 @@ function isV2Install(cwd) {
  * Results are cached per resolved absolute cwd.
  *
  * @param {string} [cwd] - Working directory (defaults to process.cwd())
- * @returns {Readonly<Object>} Frozen PATHS object with ROOT, PHASES, IDEAS, etc.
+ * @returns {Readonly<Object>} Frozen PATHS object with ROOT, IDEAS, etc.
  */
 function getPaths(cwd) {
   const resolved = path.resolve(cwd || process.cwd());
@@ -103,7 +103,6 @@ function getPaths(cwd) {
 
   const paths = Object.freeze({
     ROOT: root,
-    PHASES: path.join(root, 'phases'),
     IDEAS: path.join(root, 'ideas'),
     SPECS: path.join(root, 'specs'),
     JOBS: path.join(root, 'jobs'),

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

@@ -244,12 +244,12 @@ describe('PATHS object shape', () => {
   });
 
   const EXPECTED_KEYS = [
-    'ROOT', 'PHASES', 'IDEAS', 'SPECS', 'JOBS', 'DOCS',
+    'ROOT', 'IDEAS', 'SPECS', 'JOBS', 'DOCS',
     'CODEBASE', 'MILESTONES', 'CONFIG', 'CONFIG_LOCAL',
     'QUICK', 'TODOS', 'RESEARCH', 'DEBUG', 'ARCHIVE', 'PROJECTS',
   ];
 
-  it('returns object with all 16 expected keys', () => {
+  it('returns object with all 15 expected keys', () => {
     cwd = makeGitTempDir();
     const paths = getPaths(cwd);
     assert.deepEqual(Object.keys(paths).sort(), EXPECTED_KEYS.slice().sort());
@@ -287,7 +287,7 @@ describe('PATHS object shape', () => {
   it('subdirectory paths are derived from ROOT', () => {
     cwd = makeGitTempDir();
     const paths = getPaths(cwd);
-    assert.equal(paths.PHASES, path.join(paths.ROOT, 'phases'));
+    assert.equal(paths.PHASES, undefined, 'PHASES key removed — phases path resolves via core.cjs phasesDir, not the project-unaware PATHS constant');
     assert.equal(paths.IDEAS, path.join(paths.ROOT, 'ideas'));
     assert.equal(paths.SPECS, path.join(paths.ROOT, 'specs'));
     assert.equal(paths.JOBS, path.join(paths.ROOT, 'jobs'));
@@ -443,7 +443,6 @@ describe('edge cases', () => {
     cwd = makeGitTempDir();
     const paths = getPaths(cwd);
     // Should return all paths even though none of these directories exist
-    assert.ok(paths.PHASES);
     assert.ok(paths.IDEAS);
     assert.ok(paths.SPECS);
     assert.ok(paths.ROOT);