@ktpartners/dgs-platform 3.3.0 → 3.4.1

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

@@ -201,3 +201,656 @@ describe('cmdMilestoneComplete quick dir archival', () => {
     assert.equal(typeof result.archived.quick, 'boolean', 'archived.quick should be boolean');
   });
 });
+
+// ─── milestone abandon (Phase 160, ADH-07/08/09/12/20) ───────────────────────
+//
+// These tests drive the `milestone abandon` CLI verb through a subprocess
+// (the verb calls output()/error() which exit the process), mirroring the
+// canonical harness in worktrees.test.cjs. Each test stands up a real planning
+// git repo + one registered code repo, creates an ad-hoc milestone via
+// `milestone create-adhoc`, then exercises abandon.
+
+const { execSync: _execSync } = require('child_process');
+const _os = require('os');
+const { resetPaths: _resetPaths, initPaths: _initPaths } = require('./paths.cjs');
+
+const _DGS_TOOLS = path.resolve(__dirname, '..', 'dgs-tools.cjs');
+
+// Deterministic git identity for attributed-commit assertions (ADH-20).
+const ABANDON_GIT_ENV = {
+  GIT_AUTHOR_NAME: 'Abandon Tester',
+  GIT_AUTHOR_EMAIL: 'abandon@test.com',
+  GIT_COMMITTER_NAME: 'Abandon Tester',
+  GIT_COMMITTER_EMAIL: 'abandon@test.com',
+};
+
+/**
+ * Stand up a planning repo + one registered code repo, both real git repos.
+ * Layout:
+ *   {tmpDir}/planning/    <- DGS planning root (git)
+ *     config.json, config.local.json, REPOS.md, PROJECTS.md
+ *     projects/tp/{PROJECT,STATE,ROADMAP,REQUIREMENTS}.md
+ *   {tmpDir}/code-repo/   <- registered code repo (git, on main)
+ */
+function createAbandonEnv() {
+  const tmpDir = fs.realpathSync(fs.mkdtempSync(path.join(_os.tmpdir(), 'dgs-ab-')));
+  const planDir = path.join(tmpDir, 'planning');
+  const codeDir = path.join(tmpDir, 'code-repo');
+  const fullEnv = { ...process.env, ...ABANDON_GIT_ENV };
+
+  // Planning repo
+  fs.mkdirSync(planDir, { recursive: true });
+  _execSync('git init -b main', { cwd: planDir, stdio: 'pipe', env: fullEnv });
+  _execSync('git config user.email "abandon@test.com"', { cwd: planDir, stdio: 'pipe' });
+  _execSync('git config user.name "Abandon Tester"', { cwd: planDir, stdio: 'pipe' });
+
+  // Code repo
+  fs.mkdirSync(codeDir, { recursive: true });
+  _execSync('git init -b main', { cwd: codeDir, stdio: 'pipe', env: fullEnv });
+  _execSync('git config user.email "abandon@test.com"', { cwd: codeDir, stdio: 'pipe' });
+  _execSync('git config user.name "Abandon Tester"', { cwd: codeDir, stdio: 'pipe' });
+  fs.writeFileSync(path.join(codeDir, '.gitkeep'), '');
+  _execSync('git add .', { cwd: codeDir, stdio: 'pipe' });
+  _execSync('git commit -m "initial"', { cwd: codeDir, stdio: 'pipe', env: fullEnv });
+
+  // DGS config
+  fs.writeFileSync(path.join(planDir, 'config.json'), JSON.stringify({ git: { base_branch: 'main' } }, null, 2));
+  fs.writeFileSync(path.join(planDir, 'config.local.json'), JSON.stringify({ current_project: 'tp' }, null, 2));
+  fs.writeFileSync(path.join(planDir, 'PROJECTS.md'), '# Projects\n');
+  fs.writeFileSync(path.join(planDir, 'REPOS.md'),
+    '# Repos\n\n' +
+    '| Name | Path | GitHub URL | Description |\n' +
+    '|------|------|------------|-------------|\n' +
+    '| code-repo | ' + path.relative(planDir, codeDir) + ' |  | Test repo |\n'
+  );
+
+  // Full project doc set so the path-scoped restore has all 5 docs present at base.
+  fs.mkdirSync(path.join(planDir, 'projects', 'tp'), { recursive: true });
+  fs.writeFileSync(path.join(planDir, 'projects', 'tp', 'PROJECT.md'), '# Project tp\n\nPre-milestone project doc.\n');
+  fs.writeFileSync(path.join(planDir, 'projects', 'tp', 'STATE.md'), '# State\nStatus: planning\nPre-milestone state.\n');
+  fs.writeFileSync(path.join(planDir, 'projects', 'tp', 'ROADMAP.md'), '# Roadmap\n\nPre-milestone roadmap.\n');
+  fs.writeFileSync(path.join(planDir, 'projects', 'tp', 'REQUIREMENTS.md'), '# Requirements\n\nPre-milestone requirements.\n');
+
+  _execSync('git add .', { cwd: planDir, stdio: 'pipe' });
+  _execSync('git commit -m "setup"', { cwd: planDir, stdio: 'pipe', env: fullEnv });
+
+  _initPaths(planDir);
+
+  return {
+    tmpDir, planDir, codeDir, fullEnv,
+    cleanup: function () {
+      _resetPaths();
+      try {
+        const parent = path.dirname(codeDir);
+        for (const e of fs.readdirSync(parent)) {
+          if (e.startsWith('code-repo--')) {
+            fs.rmSync(path.join(parent, e), { recursive: true, force: true });
+          }
+        }
+      } catch { /* ignore */ }
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    },
+  };
+}
+
+/** Run a dgs-tools command from the planning dir; returns parsed JSON. */
+function abandonRun(planDir, args, env) {
+  const out = _execSync(
+    'node ' + JSON.stringify(_DGS_TOOLS) + ' ' + args,
+    { cwd: planDir, stdio: ['pipe', 'pipe', 'pipe'], encoding: 'utf-8', env: { ...process.env, ...ABANDON_GIT_ENV, ...(env || {}) } }
+  );
+  return JSON.parse(out.trim());
+}
+
+/** Run a dgs-tools command expecting a non-zero exit; returns combined stdout+stderr. */
+function abandonRunFail(planDir, args, env) {
+  try {
+    _execSync(
+      'node ' + JSON.stringify(_DGS_TOOLS) + ' ' + args,
+      { cwd: planDir, stdio: ['pipe', 'pipe', 'pipe'], encoding: 'utf-8', env: { ...process.env, ...ABANDON_GIT_ENV, ...(env || {}) } }
+    );
+    return null; // unexpected success
+  } catch (err) {
+    return (err.stdout || '').toString() + (err.stderr || err.message || '').toString();
+  }
+}
+
+/** Create an ad-hoc milestone named 'abandon target'; returns { slug, baseRef }. */
+function setupAdhoc(planDir) {
+  const res = abandonRun(planDir, 'milestone create-adhoc ' + JSON.stringify('abandon target') + ' --version v0.1');
+  return { slug: res.slug, baseRef: res.base_ref || ('refs/dgs/adhoc/' + res.slug + '/base') };
+}
+
+function readLocal(planDir) {
+  return JSON.parse(fs.readFileSync(path.join(planDir, 'config.local.json'), 'utf-8'));
+}
+
+/** True if a git ref resolves in the given repo. */
+function refResolves(repoDir, ref) {
+  try {
+    _execSync('git show-ref --verify --quiet ' + JSON.stringify(ref), { cwd: repoDir, stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** True if `doc` (relative to planDir) differs from its content at `ref`. */
+function docDiffersFromRef(planDir, ref, doc) {
+  try {
+    _execSync('git diff --quiet ' + JSON.stringify(ref) + ' -- ' + JSON.stringify(doc), { cwd: planDir, stdio: 'pipe' });
+    return false; // no diff
+  } catch {
+    return true; // diff present (or pathspec issue)
+  }
+}
+
+describe('milestone abandon', () => {
+  let env;
+  beforeEach(() => { env = createAbandonEnv(); });
+  afterEach(() => { if (env) env.cleanup(); });
+
+  it('ad-hoc create composes a version-prefixed structural slug (not the bare name)', () => {
+    const res = abandonRun(env.planDir, 'milestone create-adhoc ' + JSON.stringify('My Adhoc Thing') + ' --version v3.4');
+    assert.ok(res.created && res.slug, 'should create with a slug');
+    // Structural composition: [<version>-]<name-slug>; v3.4 -> v3-4.
+    assert.ok(res.slug.startsWith('v3-4-'), 'slug should embed the version segment: ' + res.slug);
+    assert.ok(res.slug.includes('my-adhoc-thing'), 'slug should include the name: ' + res.slug);
+    assert.notEqual(res.slug, 'my-adhoc-thing', 'slug must NOT be the bare name');
+    // The code-repo milestone branch follows the composed slug.
+    const branches = _execSync('git branch', { cwd: env.codeDir, encoding: 'utf-8', stdio: 'pipe' });
+    assert.ok(branches.includes('milestone/' + res.slug), 'milestone branch should use the composed slug');
+    // create + abandon still complete end-to-end.
+    const ab = abandonRun(env.planDir, 'milestone abandon --confirmed');
+    assert.equal(ab.abandoned, true, 'abandon should still complete with the new slug');
+  });
+
+  it('ADH-07 happy path: restores docs to base ref, removes worktrees/branches, clears context, commits reversion', () => {
+    const { slug, baseRef } = setupAdhoc(env.planDir);
+
+    // Mutate a restored doc on base_branch during the milestone window, then commit it.
+    const statePath = path.join(env.planDir, 'projects', 'tp', 'STATE.md');
+    fs.writeFileSync(statePath, fs.readFileSync(statePath, 'utf-8') + '\nMilestone-window edit row.\n');
+    _execSync('git add . && git commit -m "milestone-window STATE edit"', { cwd: env.planDir, stdio: 'pipe', env: env.fullEnv });
+
+    // Sanity: STATE.md currently differs from base ref.
+    assert.ok(docDiffersFromRef(env.planDir, baseRef, 'projects/tp/STATE.md'), 'precondition: STATE.md differs from base');
+
+    // ADH-21: abandon DELETES the base ref as part of lifecycle cleanup, so resolve
+    // it to an immutable commit SHA now to diff against after abandon.
+    const baseSha = _execSync('git rev-parse ' + JSON.stringify(baseRef), { cwd: env.planDir, encoding: 'utf-8', stdio: 'pipe' }).trim();
+
+    const result = abandonRun(env.planDir, 'milestone abandon --confirmed');
+    assert.equal(result.abandoned, true, 'should report abandoned:true');
+    assert.equal(result.slug, slug);
+
+    // STATE.md restored to base-ref content (no diff vs the captured base SHA).
+    assert.ok(!docDiffersFromRef(env.planDir, baseSha, 'projects/tp/STATE.md'), 'STATE.md should match base ref after abandon');
+
+    // Code repo milestone branch + worktree removed.
+    const branches = _execSync('git branch', { cwd: env.codeDir, encoding: 'utf-8', stdio: 'pipe' });
+    assert.ok(!branches.includes('milestone/' + slug), 'milestone/{slug} branch should be removed');
+
+    // active_context cleared.
+    const cfg = readLocal(env.planDir);
+    assert.ok(!cfg.execution || cfg.execution.active_context === null, 'active_context should be null after abandon');
+
+    // A reversion commit exists on base_branch HEAD.
+    const head = _execSync('git log -1 --format=%s', { cwd: env.planDir, encoding: 'utf-8', stdio: 'pipe' }).trim();
+    assert.match(head, /revert|abandon/i, 'HEAD commit should be the reversion: ' + head);
+  });
+
+  it('ADH-08 guard: non-ad-hoc milestone is refused with guidance and makes no changes', () => {
+    // No create-adhoc — drive abandon on a plain (non-ad-hoc) planning repo.
+    // Set an active_context that is NOT an ad-hoc milestone entry.
+    const cfg = readLocal(env.planDir);
+    cfg.projects = { tp: { worktrees: { 'plain-ms': { type: 'milestone' } } } };
+    cfg.execution = { active_context: 'plain-ms' };
+    fs.writeFileSync(path.join(env.planDir, 'config.local.json'), JSON.stringify(cfg, null, 2) + '\n');
+
+    const headBefore = _execSync('git rev-parse HEAD', { cwd: env.planDir, encoding: 'utf-8', stdio: 'pipe' }).trim();
+
+    const out = abandonRunFail(env.planDir, 'milestone abandon --confirmed');
+    assert.ok(out, 'abandon should fail (non-zero) on a non-ad-hoc milestone');
+    assert.match(out, /ad-hoc|complete-milestone/i, 'should surface ad-hoc-only guidance: ' + out);
+
+    // NO changes: worktree entry still present, active_context unchanged, no new commit.
+    const after = readLocal(env.planDir);
+    assert.ok(after.projects.tp.worktrees['plain-ms'], 'worktree entry must remain');
+    assert.equal(after.execution.active_context, 'plain-ms', 'active_context unchanged');
+    const headAfter = _execSync('git rev-parse HEAD', { cwd: env.planDir, encoding: 'utf-8', stdio: 'pipe' }).trim();
+    assert.equal(headAfter, headBefore, 'no new commit on refusal');
+  });
+
+  it('ADH-09 restore scope: only the named docs change; a sentinel outside the set is untouched (never whole-tree)', () => {
+    const { slug, baseRef } = setupAdhoc(env.planDir);
+
+    // Add a sentinel tracked file AFTER the base ref was captured (proves path-scoped).
+    const sentinelRel = 'projects/tp/SENTINEL.txt';
+    const sentinelPath = path.join(env.planDir, sentinelRel);
+    fs.writeFileSync(sentinelPath, 'sentinel content added during milestone window\n');
+    // Also edit STATE.md in the window.
+    const statePath = path.join(env.planDir, 'projects', 'tp', 'STATE.md');
+    fs.writeFileSync(statePath, fs.readFileSync(statePath, 'utf-8') + '\nwindow edit\n');
+    _execSync('git add . && git commit -m "window: sentinel + state edit"', { cwd: env.planDir, stdio: 'pipe', env: env.fullEnv });
+
+    // ADH-21: abandon deletes the base ref — capture its commit SHA first.
+    const baseSha = _execSync('git rev-parse ' + JSON.stringify(baseRef), { cwd: env.planDir, encoding: 'utf-8', stdio: 'pipe' }).trim();
+
+    abandonRun(env.planDir, 'milestone abandon --confirmed');
+
+    // Sentinel must be UNCHANGED (a whole-tree reset to base would have deleted it).
+    assert.ok(fs.existsSync(sentinelPath), 'sentinel file must survive a path-scoped restore');
+    assert.equal(fs.readFileSync(sentinelPath, 'utf-8'), 'sentinel content added during milestone window\n', 'sentinel content unchanged');
+
+    // STATE.md was restored to base (compare against the captured base SHA).
+    assert.ok(!docDiffersFromRef(env.planDir, baseSha, 'projects/tp/STATE.md'), 'STATE.md restored to base');
+    void slug;
+  });
+
+  it('ADH-12 confirmation: without --confirmed, abandon refuses with the loss message and makes no changes', () => {
+    const { slug } = setupAdhoc(env.planDir);
+    const headBefore = _execSync('git rev-parse HEAD', { cwd: env.planDir, encoding: 'utf-8', stdio: 'pipe' }).trim();
+
+    const out = abandonRunFail(env.planDir, 'milestone abandon');
+    assert.ok(out, 'abandon without --confirmed should fail');
+    assert.match(out, /all uncommitted and committed milestone changes will be lost/i, 'loss message required: ' + out);
+
+    // NO changes — context still active, branch still present, no new commit.
+    const cfg = readLocal(env.planDir);
+    assert.equal(cfg.execution.active_context, slug, 'active_context unchanged without --confirmed');
+    const branches = _execSync('git branch', { cwd: env.codeDir, encoding: 'utf-8', stdio: 'pipe' });
+    assert.ok(branches.includes('milestone/' + slug), 'milestone branch still present');
+    const headAfter = _execSync('git rev-parse HEAD', { cwd: env.planDir, encoding: 'utf-8', stdio: 'pipe' }).trim();
+    assert.equal(headAfter, headBefore, 'no new commit without --confirmed');
+  });
+
+  it('ADH-20a precondition: a staged/uncommitted edit to a restored doc blocks abandon with remediation, no mutation', () => {
+    const { slug } = setupAdhoc(env.planDir);
+
+    // Dirty a restored doc without committing.
+    const statePath = path.join(env.planDir, 'projects', 'tp', 'STATE.md');
+    fs.writeFileSync(statePath, fs.readFileSync(statePath, 'utf-8') + '\nuncommitted dirty edit\n');
+
+    const headBefore = _execSync('git rev-parse HEAD', { cwd: env.planDir, encoding: 'utf-8', stdio: 'pipe' }).trim();
+
+    const out = abandonRunFail(env.planDir, 'milestone abandon --confirmed');
+    assert.ok(out, 'abandon should refuse on a dirty restored-doc tree');
+    assert.match(out, /commit|discard|uncommitted|staged/i, 'should give remediation: ' + out);
+
+    // NO mutation: context still active, branch present, no new commit, dirty edit preserved.
+    const cfg = readLocal(env.planDir);
+    assert.equal(cfg.execution.active_context, slug, 'active_context unchanged');
+    const branches = _execSync('git branch', { cwd: env.codeDir, encoding: 'utf-8', stdio: 'pipe' });
+    assert.ok(branches.includes('milestone/' + slug), 'milestone branch still present');
+    const headAfter = _execSync('git rev-parse HEAD', { cwd: env.planDir, encoding: 'utf-8', stdio: 'pipe' }).trim();
+    assert.equal(headAfter, headBefore, 'no new commit on refusal');
+    assert.match(fs.readFileSync(statePath, 'utf-8'), /uncommitted dirty edit/, 'dirty edit preserved');
+  });
+
+  it('ADH-20 attributed commit: the reversion commit is authored by the configured git identity', () => {
+    const { baseRef } = setupAdhoc(env.planDir);
+
+    // Make a committed window edit so the restore produces a real reversion commit.
+    const statePath = path.join(env.planDir, 'projects', 'tp', 'STATE.md');
+    fs.writeFileSync(statePath, fs.readFileSync(statePath, 'utf-8') + '\nwindow edit for attribution\n');
+    _execSync('git add . && git commit -m "window edit"', { cwd: env.planDir, stdio: 'pipe', env: env.fullEnv });
+
+    abandonRun(env.planDir, 'milestone abandon --confirmed');
+
+    const author = _execSync('git log -1 "--format=%an|%ae"', { cwd: env.planDir, encoding: 'utf-8', stdio: 'pipe' }).trim();
+    assert.equal(author, 'Abandon Tester|abandon@test.com', 'reversion commit must be attributed to the invoking identity: ' + author);
+    void baseRef;
+  });
+
+  it('ADH-20 pushed-branch teardown: pushed milestone branch → local removal + owned remote branch deleted', () => {
+    const { slug } = setupAdhoc(env.planDir);
+
+    // Stand up a bare remote for the code repo and push the milestone branch to it.
+    const remoteDir = path.join(env.tmpDir, 'code-remote.git');
+    _execSync('git init --bare ' + JSON.stringify(remoteDir), { cwd: env.tmpDir, stdio: 'pipe', env: env.fullEnv });
+    _execSync('git remote add origin ' + JSON.stringify(remoteDir), { cwd: env.codeDir, stdio: 'pipe' });
+    _execSync('git push origin ' + JSON.stringify('milestone/' + slug), { cwd: env.codeDir, stdio: 'pipe', env: env.fullEnv });
+    // Refresh remote-tracking refs in the main checkout.
+    _execSync('git fetch origin', { cwd: env.codeDir, stdio: 'pipe', env: env.fullEnv });
+
+    assert.ok(refResolves(env.codeDir, 'refs/remotes/origin/milestone/' + slug), 'precondition: remote ref exists');
+    assert.ok(refResolves(remoteDir, 'refs/heads/milestone/' + slug), 'precondition: remote branch exists');
+
+    const out = _execSync(
+      'node ' + JSON.stringify(_DGS_TOOLS) + ' milestone abandon --confirmed 2>&1',
+      { cwd: env.planDir, stdio: ['pipe', 'pipe', 'pipe'], encoding: 'utf-8', env: { ...process.env, ...ABANDON_GIT_ENV } }
+    );
+
+    // Local branch removed; owned remote branch DELETED during teardown.
+    const branches = _execSync('git branch', { cwd: env.codeDir, encoding: 'utf-8', stdio: 'pipe' });
+    assert.ok(!branches.includes('milestone/' + slug), 'local milestone branch removed');
+    assert.ok(!refResolves(remoteDir, 'refs/heads/milestone/' + slug), 'owned remote milestone branch should be deleted');
+  });
+
+  it('ADH-20 remote-delete failure is non-fatal: abandon still reports abandoned:true', () => {
+    const { slug } = setupAdhoc(env.planDir);
+
+    // Add an origin remote that points at a non-existent / unreachable path so a
+    // delete push fails, but the milestone branch ref is locally present.
+    const deadRemote = path.join(env.tmpDir, 'does-not-exist.git');
+    _execSync('git remote add origin ' + JSON.stringify(deadRemote), { cwd: env.codeDir, stdio: 'pipe' });
+    // Fabricate a remote-tracking ref so the teardown attempts a delete.
+    const sha = _execSync('git rev-parse ' + JSON.stringify('milestone/' + slug), { cwd: env.codeDir, encoding: 'utf-8', stdio: 'pipe' }).trim();
+    _execSync('git update-ref ' + JSON.stringify('refs/remotes/origin/milestone/' + slug) + ' ' + sha, { cwd: env.codeDir, stdio: 'pipe' });
+    assert.ok(refResolves(env.codeDir, 'refs/remotes/origin/milestone/' + slug), 'precondition: remote-tracking ref exists');
+
+    const result = abandonRun(env.planDir, 'milestone abandon --confirmed');
+    assert.equal(result.abandoned, true, 'a failed remote delete must NOT fail the abandon');
+  });
+});
+
+// ─── state adhoc-readiness (Phase 161, ADH-10/11/13) ─────────────────────────
+//
+// Drives the `state adhoc-readiness --raw` predicate (Plan 02) through the same
+// subprocess harness as the abandon suite. The predicate gates the relaxed
+// completion path in complete-milestone.md (Plan 03): an ad-hoc milestone with
+// at least one merged unit of work (a completed quick row OR a completed phase)
+// is "ready"; with zero merged work it is refused (ADH-13). A non-ad-hoc
+// milestone always reports adhoc:false so the strict gate governs (ADH-11).
+
+const _STATE_PATH_REL = path.join('projects', 'tp', 'STATE.md');
+const _ROADMAP_PATH_REL = path.join('projects', 'tp', 'ROADMAP.md');
+
+// Path to the workflow file whose exact ADH-13 refusal string Test 5 pins.
+// Resolved relative to THIS repo root (NOT the temp planDir).
+const _COMPLETE_MILESTONE_WF = path.resolve(
+  __dirname, '..', '..', 'workflows', 'complete-milestone.md'
+);
+
+// The exact ADH-13 refusal string — byte-for-byte (em-dash + backticks).
+const ADH13_REFUSAL =
+  'Nothing to ship — run a quick/fast or execute a phase first, or `/dgs:abandon-milestone`';
+
+/** Commit everything in planDir with the deterministic abandon identity. */
+function _commitFixture(planDir, msg) {
+  _execSync('git add -A && git commit -m ' + JSON.stringify(msg), {
+    cwd: planDir, stdio: 'pipe', env: { ...process.env, ...ABANDON_GIT_ENV },
+  });
+}
+
+/**
+ * Append a well-formed "Quick Tasks Completed" data row to the active STATE.md.
+ * full=true → 6-col layout (with Status); full=false → 5-col layout (no Status).
+ * Inserts the section header + column header + separator when absent.
+ */
+function addQuickRow(planDir, { id, commit, full }) {
+  const statePath = path.join(planDir, _STATE_PATH_REL);
+  let content = fs.existsSync(statePath) ? fs.readFileSync(statePath, 'utf-8') : '';
+  if (!/###\s*Quick Tasks Completed/i.test(content)) {
+    const header = full
+      ? '| # | Description | Date | Commit | Status | Directory |'
+      : '| # | Description | Date | Commit | Directory |';
+    const sep = full
+      ? '|---|---|---|---|---|---|'
+      : '|---|---|---|---|---|';
+    content += '\n### Quick Tasks Completed\n\n' + header + '\n' + sep + '\n';
+  }
+  const row = full
+    ? `| ${id} | desc | 2026-06-09 | ${commit} | Verified | dir |`
+    : `| ${id} | desc | 2026-06-09 | ${commit} | dir |`;
+  content += row + '\n';
+  fs.writeFileSync(statePath, content, 'utf-8');
+  _commitFixture(planDir, 'fixture: quick row');
+}
+
+/**
+ * Append a malformed/partial "Quick Tasks Completed" row (empty id AND empty
+ * commit) — must be skipped by the row counter.
+ */
+function addMalformedQuickRow(planDir) {
+  const statePath = path.join(planDir, _STATE_PATH_REL);
+  let content = fs.existsSync(statePath) ? fs.readFileSync(statePath, 'utf-8') : '';
+  if (!/###\s*Quick Tasks Completed/i.test(content)) {
+    content += '\n### Quick Tasks Completed\n\n' +
+      '| # | Description | Date | Commit | Directory |\n' +
+      '|---|---|---|---|---|\n';
+  }
+  content += '|  | broken | 2026-06-09 |  | dir |\n';
+  fs.writeFileSync(statePath, content, 'utf-8');
+  _commitFixture(planDir, 'fixture: malformed quick row');
+}
+
+/**
+ * Create a phase dir under projects/tp/phases/ and list it in ROADMAP.md so
+ * `roadmap analyze` enumerates it. complete=true → also write a SUMMARY.md so
+ * 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');
+  fs.mkdirSync(phaseDir, { recursive: true });
+  fs.writeFileSync(path.join(phaseDir, '01-01-PLAN.md'), '# Plan\n');
+  if (complete) {
+    fs.writeFileSync(path.join(phaseDir, '01-01-SUMMARY.md'), '# Summary\n');
+  }
+  const roadmapPath = path.join(planDir, _ROADMAP_PATH_REL);
+  fs.writeFileSync(
+    roadmapPath,
+    '# Roadmap\n\n## v0.1\n\n- [ ] **Phase 1: Foo**\n\n## Phase 1: Foo\n\n**Goal:** test phase\n'
+  );
+  _commitFixture(planDir, 'fixture: phase');
+}
+
+/**
+ * Test 6/7 fixture: a NON-ad-hoc milestone. STATE.md has NO `adhoc` key (so
+ * stateReadAdhoc → false). ROADMAP lists 2 phases, only 1 with a SUMMARY (<100%).
+ * Does NOT call create-adhoc.
+ */
+function addNonAdhocMilestone(planDir) {
+  const statePath = path.join(planDir, _STATE_PATH_REL);
+  fs.writeFileSync(statePath, '# State\nStatus: in_progress\nNon-adhoc milestone.\n');
+  // Phase 1 complete, Phase 2 planned only → <100%.
+  const p1 = path.join(planDir, 'projects', 'tp', 'phases', '01-alpha');
+  const p2 = path.join(planDir, 'projects', 'tp', 'phases', '02-beta');
+  fs.mkdirSync(p1, { recursive: true });
+  fs.mkdirSync(p2, { recursive: true });
+  fs.writeFileSync(path.join(p1, '01-01-PLAN.md'), '# Plan\n');
+  fs.writeFileSync(path.join(p1, '01-01-SUMMARY.md'), '# Summary\n');
+  fs.writeFileSync(path.join(p2, '02-01-PLAN.md'), '# Plan\n');
+  const roadmapPath = path.join(planDir, _ROADMAP_PATH_REL);
+  fs.writeFileSync(
+    roadmapPath,
+    '# Roadmap\n\n## v0.1\n\n- [x] **Phase 1: Alpha**\n- [ ] **Phase 2: Beta**\n\n' +
+    '## Phase 1: Alpha\n\n**Goal:** a\n\n## Phase 2: Beta\n\n**Goal:** b\n'
+  );
+  _commitFixture(planDir, 'fixture: non-adhoc milestone');
+}
+
+describe('state adhoc-readiness', () => {
+  let env;
+  beforeEach(() => { env = createAbandonEnv(); });
+  afterEach(() => { if (env) env.cleanup(); });
+
+  it('Test 1 (ADH-10 happy path, quicks-only): one well-formed quick row → ready', () => {
+    setupAdhoc(env.planDir);
+    addQuickRow(env.planDir, { id: '1', commit: 'abc1234', full: false });
+
+    const r = abandonRun(env.planDir, 'state adhoc-readiness --raw');
+    assert.deepEqual(r, {
+      adhoc: true, completedQuickRows: 1, completedPhases: 0, ready: true, reason: 'ok',
+    });
+  });
+
+  it('Test 2 (ADH-10 completed-phase path): one completed phase → ready', () => {
+    setupAdhoc(env.planDir);
+    addCompletedPhase(env.planDir, { complete: true });
+
+    const r = abandonRun(env.planDir, 'state adhoc-readiness --raw');
+    assert.equal(r.adhoc, true);
+    assert.equal(r.completedQuickRows, 0);
+    assert.equal(r.completedPhases, 1);
+    assert.equal(r.ready, true);
+  });
+
+  it('Test 3 (ADH-10 edge): a planned-but-incomplete phase does NOT count', () => {
+    setupAdhoc(env.planDir);
+    addCompletedPhase(env.planDir, { complete: false });
+
+    const r = abandonRun(env.planDir, 'state adhoc-readiness --raw');
+    assert.equal(r.completedPhases, 0, 'planned-incomplete phase must not be counted');
+    assert.equal(r.ready, false);
+  });
+
+  it('Test 4 (ADH-10 edge): a malformed quick row is ignored', () => {
+    setupAdhoc(env.planDir);
+    addMalformedQuickRow(env.planDir);
+
+    const r = abandonRun(env.planDir, 'state adhoc-readiness --raw');
+    assert.equal(r.completedQuickRows, 0, 'malformed quick row must be skipped');
+    assert.equal(r.ready, false);
+  });
+
+  it('Test 5 (ADH-13 zero-work refusal): no quicks, no phases → not ready + exact string pinned', () => {
+    setupAdhoc(env.planDir);
+
+    const r = abandonRun(env.planDir, 'state adhoc-readiness --raw');
+    assert.equal(r.adhoc, true);
+    assert.equal(r.ready, false);
+    assert.equal(r.reason, 'no_merged_work');
+
+    // The exact ADH-13 refusal string must live in the workflow (Plan 03 surface).
+    const wf = fs.readFileSync(_COMPLETE_MILESTONE_WF, 'utf-8');
+    assert.ok(
+      wf.includes(ADH13_REFUSAL),
+      'complete-milestone.md must contain the exact ADH-13 refusal string'
+    );
+  });
+
+  it('Test 6 (ADH-11 regression): non-ad-hoc milestone → adhoc:false', () => {
+    addNonAdhocMilestone(env.planDir);
+
+    const r = abandonRun(env.planDir, 'state adhoc-readiness --raw');
+    assert.equal(r.adhoc, false, 'non-ad-hoc milestone must report adhoc:false');
+  });
+
+  it('Test 7 (ADH-11 regression): strict gate untouched for a normal milestone', () => {
+    // For the non-ad-hoc fixture the predicate relaxes nothing: adhoc:false, so
+    // the workflow takes the unchanged strict 100%-phase gate (verified manually
+    // in Plan 03). The `ready` field is irrelevant in this branch.
+    addNonAdhocMilestone(env.planDir);
+
+    const r = abandonRun(env.planDir, 'state adhoc-readiness --raw');
+    assert.equal(r.adhoc, false);
+  });
+});
+
+// ─── milestone cleanup-adhoc / lifecycle cleanup (Phase 162, ADH-21/14/15) ───
+//
+// ADH-21: BOTH complete-milestone and abandon-milestone must leave no residual
+// ad-hoc bookkeeping. The only real residue today is the snapshot base ref
+// refs/dgs/adhoc/{slug}/base (created at milestone.cjs create-adhoc, never
+// deleted by either exit). Plan 02 adds an idempotent `milestone cleanup-adhoc`
+// verb + wires it into both lifecycle exits. Tests 1-5 drive that contract
+// through the existing subprocess harness. Tests 6-7 (ADH-14) and 8-11
+// (ADH-15) pin the status-surface and docs literals against the repo-root
+// workflow/doc files so the Plan 03/04 prose cannot silently drift.
+
+// Repo root, resolved from THIS file at deliver-great-systems/bin/lib/.
+const _REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+
+/** Run a git command in `dir`; returns trimmed stdout. */
+function gitOut(dir, gitArgs) {
+  return _execSync('git ' + gitArgs.join(' '), { cwd: dir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+}
+
+/** Parse config.local.json from a planning dir; {} if absent. */
+function readLocalCfg(planDir) {
+  const p = path.join(planDir, 'config.local.json');
+  if (!fs.existsSync(p)) return {};
+  try { return JSON.parse(fs.readFileSync(p, 'utf-8')); } catch { return {}; }
+}
+
+describe('milestone cleanup-adhoc / lifecycle cleanup', () => {
+  let env;
+  beforeEach(() => { env = createAbandonEnv(); });
+  afterEach(() => { if (env) env.cleanup(); });
+
+  // ── ADH-21: cleanup verb + abandon post-state ──
+
+  it('Test 1 (fixture sanity): base ref exists after create-adhoc', () => {
+    const { slug } = setupAdhoc(env.planDir);
+    const refs = gitOut(env.planDir, ['for-each-ref', 'refs/dgs/adhoc/' + slug]);
+    assert.notEqual(refs, '', 'create-adhoc must leave a base ref for cleanup to remove');
+  });
+
+  it('Test 2 (ADH-21): cleanup-adhoc removes the base ref', () => {
+    const { slug } = setupAdhoc(env.planDir);
+    const r = abandonRun(env.planDir, 'milestone cleanup-adhoc ' + JSON.stringify(slug) + ' --raw');
+    assert.equal(r.slug, slug);
+    assert.equal(r.ref_deleted, true, 'first cleanup must delete the base ref');
+    assert.equal(gitOut(env.planDir, ['for-each-ref', 'refs/dgs/adhoc/' + slug]), '', 'no residual ref after cleanup');
+  });
+
+  it('Test 3 (ADH-21): cleanup-adhoc is idempotent', () => {
+    const { slug } = setupAdhoc(env.planDir);
+    abandonRun(env.planDir, 'milestone cleanup-adhoc ' + JSON.stringify(slug) + ' --raw');
+    const r2 = abandonRun(env.planDir, 'milestone cleanup-adhoc ' + JSON.stringify(slug) + ' --raw');
+    assert.equal(r2.ref_deleted, false, 'second run is a no-op for the ref');
+    assert.equal(gitOut(env.planDir, ['for-each-ref', 'refs/dgs/adhoc/' + slug]), '', 'ref still empty');
+  });
+
+  it('Test 4 (ADH-21): cleanup-adhoc is a safe no-op for a non-ad-hoc slug', () => {
+    const r = abandonRun(env.planDir, 'milestone cleanup-adhoc ' + JSON.stringify('does-not-exist') + ' --raw');
+    assert.equal(r.ref_deleted, false);
+    assert.equal(r.entry_removed, false);
+  });
+
+  it('Test 5 (ADH-21 acceptance): after abandon, no residual ref AND no worktree entry', () => {
+    const { slug } = setupAdhoc(env.planDir);
+    abandonRun(env.planDir, 'milestone abandon --confirmed --raw');
+
+    // (a) no residual base ref
+    assert.equal(gitOut(env.planDir, ['for-each-ref', 'refs/dgs/adhoc/' + slug]), '', 'abandon must leave no residual base ref');
+
+    // (b) no residual worktree entry / adhoc keys
+    const cfg = readLocalCfg(env.planDir);
+    const wt = cfg.projects && cfg.projects.tp && cfg.projects.tp.worktrees;
+    assert.ok(!wt || wt[slug] === undefined, 'abandon must leave no residual worktrees[slug] entry');
+  });
+
+  // ── ADH-14: status surfaces (grep assertions at repo root) ──
+
+  it('Test 6 (ADH-14): progress.md reads the marker + renders the ad-hoc container line', () => {
+    // Live render is Manual-Only; this pins the literal so Plan 03 cannot drift.
+    const wf = fs.readFileSync(path.join(_REPO_ROOT, 'deliver-great-systems', 'workflows', 'progress.md'), 'utf-8');
+    assert.ok(wf.includes('state read-adhoc'), 'progress.md must read the ad-hoc marker');
+    assert.ok(/[Aa]d-hoc container/.test(wf), 'progress.md must render an ad-hoc container line');
+  });
+
+  it('Test 7 (ADH-14): complete-milestone.md preamble references the ad-hoc marker', () => {
+    const wf = fs.readFileSync(path.join(_REPO_ROOT, 'deliver-great-systems', 'workflows', 'complete-milestone.md'), 'utf-8');
+    assert.ok(wf.includes('state read-adhoc'), 'complete-milestone.md must read the ad-hoc marker');
+    assert.ok(/[Aa]d-hoc/.test(wf), 'complete-milestone.md must mention the ad-hoc marker');
+  });
+
+  // ── ADH-15: docs (grep assertions at repo root) ──
+
+  it('Test 8 (ADH-15): state.md documents the optional adhoc frontmatter field', () => {
+    const doc = fs.readFileSync(path.join(_REPO_ROOT, 'deliver-great-systems', 'templates', 'state.md'), 'utf-8');
+    assert.ok(/adhoc/.test(doc), 'state.md must mention the adhoc field');
+    assert.ok(/frontmatter/i.test(doc), 'state.md must describe it as frontmatter');
+  });
+
+  it('Test 9 (ADH-15): help.md documents --adhoc and abandon-milestone', () => {
+    const doc = fs.readFileSync(path.join(_REPO_ROOT, 'deliver-great-systems', 'workflows', 'help.md'), 'utf-8');
+    assert.ok(doc.includes('--adhoc'), 'help.md must mention --adhoc');
+    assert.ok(doc.includes('abandon-milestone'), 'help.md must mention abandon-milestone');
+  });
+
+  it('Test 10 (ADH-15): COMMAND-REFERENCE.md documents --adhoc and abandon-milestone', () => {
+    const doc = fs.readFileSync(path.join(_REPO_ROOT, 'docs', 'COMMAND-REFERENCE.md'), 'utf-8');
+    assert.ok(doc.includes('--adhoc'), 'COMMAND-REFERENCE.md must mention --adhoc');
+    assert.ok(doc.includes('abandon-milestone'), 'COMMAND-REFERENCE.md must mention abandon-milestone');
+  });
+
+  it('Test 11 (ADH-15): claude-md.md routing note mentions the ad-hoc container + abandon-milestone', () => {
+    const doc = fs.readFileSync(path.join(_REPO_ROOT, 'deliver-great-systems', 'templates', 'claude-md.md'), 'utf-8');
+    assert.ok(/ad-hoc/i.test(doc), 'claude-md.md must mention the ad-hoc container');
+    assert.ok(/abandon-milestone/.test(doc), 'claude-md.md must mention abandon-milestone');
+  });
+});