@ktpartners/dgs-platform 3.4.2 → 3.5.1

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

@@ -0,0 +1,186 @@
+/**
+ * Tests for cmdMilestoneComplete — structural phase archival (Phase 167, NUM-03/NUM-04)
+ *
+ * Covers the versioned single-move archival path, the collision-abort guard,
+ * mixed-layout correctness, and flat-mode preservation.
+ *
+ * Uses Node.js built-in test runner (node:test) and assert (node:assert/strict).
+ * Each test creates an isolated temp directory fixture and cleans up after.
+ */
+
+const { describe, it, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+
+const { createFixture } = require('./test-helpers.cjs');
+const { cmdMilestoneComplete } = require('./milestone.cjs');
+
+// Helper: capture stdout from cmdMilestoneComplete (which calls output()).
+// Also stubs process.exit so error()-guarded paths return instead of exiting.
+function captureResult(fn) {
+  const chunks = [];
+  const origWrite = process.stdout.write;
+  process.stdout.write = function (chunk) {
+    chunks.push(String(chunk));
+  };
+  const origStderrWrite = process.stderr.write;
+  process.stderr.write = function () {};
+  const origExit = process.exit;
+  process.exit = function () {};
+  try {
+    fn();
+  } finally {
+    process.stdout.write = origWrite;
+    process.stderr.write = origStderrWrite;
+    process.exit = origExit;
+  }
+  const raw = chunks.join('');
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Creates a root-layout fixture suitable for cmdMilestoneComplete.
+ * Pass `extras` to add/override structure entries (e.g. a versioned STATE.md
+ * with current_milestone frontmatter and phases/v26.0/ dirs).
+ */
+function createMilestoneFixture(extras) {
+  const base = {
+    'config.json': JSON.stringify({}),
+    'config.local.json': JSON.stringify({ planningRoot: '.' }),
+    'STATE.md': '# Project State\n\nPhase: 1\nStatus: Ready\nProgress: [----------] 0%\n',
+    'ROADMAP.md': '# Roadmap\n\n## Phase 1: Test\n',
+    'phases/': null,
+  };
+  if (extras) {
+    Object.assign(base, extras);
+  }
+  return createFixture(base);
+}
+
+// Versioned STATE.md with current_milestone frontmatter so resolveMilestoneVersion → v26.0.
+const VERSIONED_STATE =
+  '---\ncurrent_milestone: v26.0\nmilestone: v26.0\n---\n\n# Project State\n\nPhase: 1\nStatus: Ready\n';
+
+describe('cmdMilestoneComplete versioned structural archival', () => {
+  let fixture;
+
+  afterEach(() => {
+    if (fixture) fixture.cleanup();
+    fixture = undefined;
+  });
+
+  it('versioned single-move: archives phases/v26.0 to milestones/v26.0-phases via one rename', () => {
+    fixture = createMilestoneFixture({
+      'STATE.md': VERSIONED_STATE,
+      'phases/v26.0/01-foo/01-foo-SUMMARY.md': '---\none-liner: foo\n---\n## Task 1\n',
+      'phases/v26.0/02-bar/02-bar-SUMMARY.md': '---\none-liner: bar\n---\n## Task 1\n',
+    });
+    const cwd = fixture.cwd;
+
+    const result = captureResult(() => {
+      cmdMilestoneComplete(cwd, 'v26.0', { archivePhases: true }, false);
+    });
+
+    assert.ok(
+      fs.existsSync(path.join(cwd, 'milestones', 'v26.0-phases', '01-foo')),
+      '01-foo should be archived under milestones/v26.0-phases/'
+    );
+    assert.ok(
+      fs.existsSync(path.join(cwd, 'milestones', 'v26.0-phases', '02-bar')),
+      '02-bar should be archived under milestones/v26.0-phases/'
+    );
+    assert.ok(
+      !fs.existsSync(path.join(cwd, 'phases', 'v26.0')),
+      'phases/v26.0 should be MOVED (not copied) — source must no longer exist'
+    );
+    assert.ok(result, 'Should return result JSON');
+    assert.equal(result.archived.phases, true, 'archived.phases should be true');
+  });
+
+  it('versioned collision abort: aborts when milestones/v26.0-phases already exists, leaves source intact', () => {
+    fixture = createMilestoneFixture({
+      'STATE.md': VERSIONED_STATE,
+      'phases/v26.0/01-foo/01-foo-SUMMARY.md': '---\none-liner: foo\n---\n## Task 1\n',
+      'milestones/v26.0-phases/old/keep.md': 'PRESERVE ME',
+    });
+    const cwd = fixture.cwd;
+
+    captureResult(() => {
+      cmdMilestoneComplete(cwd, 'v26.0', { archivePhases: true }, false);
+    });
+
+    // Source NOT moved on collision.
+    assert.ok(
+      fs.existsSync(path.join(cwd, 'phases', 'v26.0', '01-foo')),
+      'source phases/v26.0/01-foo should still exist after collision abort'
+    );
+    // Pre-existing archive untouched — no overwrite, no merge.
+    const keepPath = path.join(cwd, 'milestones', 'v26.0-phases', 'old', 'keep.md');
+    assert.ok(fs.existsSync(keepPath), 'pre-existing archive entry should be untouched');
+    assert.equal(
+      fs.readFileSync(keepPath, 'utf-8'),
+      'PRESERVE ME',
+      'pre-existing archive content should not be overwritten'
+    );
+    // No source dir merged into the existing archive.
+    assert.ok(
+      !fs.existsSync(path.join(cwd, 'milestones', 'v26.0-phases', '01-foo')),
+      'source dir should NOT be merged into the existing archive'
+    );
+  });
+
+  it('mixed-layout: archives only phases/v26.0, leaves sibling flat phases/NN-slug dirs untouched', () => {
+    fixture = createMilestoneFixture({
+      'STATE.md': VERSIONED_STATE,
+      'phases/v26.0/01-foo/01-foo-SUMMARY.md': '---\none-liner: foo\n---\n## Task 1\n',
+      'phases/90-legacy/PLAN.md': '# Legacy flat phase',
+    });
+    const cwd = fixture.cwd;
+
+    captureResult(() => {
+      cmdMilestoneComplete(cwd, 'v26.0', { archivePhases: true }, false);
+    });
+
+    assert.ok(
+      fs.existsSync(path.join(cwd, 'milestones', 'v26.0-phases', '01-foo')),
+      'versioned phase 01-foo should be archived'
+    );
+    assert.ok(
+      fs.existsSync(path.join(cwd, 'phases', '90-legacy', 'PLAN.md')),
+      'unrelated sibling flat phase phases/90-legacy/ must NOT be disturbed'
+    );
+    assert.ok(
+      !fs.existsSync(path.join(cwd, 'phases', 'v26.0')),
+      'versioned subtree should be moved away'
+    );
+  });
+
+  it('flat mode preserved: per-directory filtered move still works (no frontmatter version)', () => {
+    fixture = createMilestoneFixture({
+      'ROADMAP.md': '# Roadmap\n\n## Phase 1: Test\n',
+      'phases/01-foo/01-foo-SUMMARY.md': '---\none-liner: foo\n---\n## Task 1\n',
+    });
+    const cwd = fixture.cwd;
+
+    const result = captureResult(() => {
+      cmdMilestoneComplete(cwd, 'v1.0', { archivePhases: true }, false);
+    });
+
+    assert.ok(
+      fs.existsSync(path.join(cwd, 'milestones', 'v1.0-phases', '01-foo')),
+      'flat per-dir move should archive 01-foo to milestones/v1.0-phases/'
+    );
+    // Flat phases/ is mkdir-archived FROM, not moved wholesale → it still exists as a dir.
+    assert.ok(
+      fs.existsSync(path.join(cwd, 'phases')),
+      'flat phases/ directory should still exist (archived from, not moved wholesale)'
+    );
+    assert.ok(result, 'Should return result JSON');
+    assert.equal(result.archived.phases, true, 'archived.phases should be true in flat mode');
+  });
+});

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');
+  });
+});