@ktpartners/dgs-platform 3.3.0 → 3.4.1

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

@@ -154,6 +154,125 @@ function writeLocalConfig(planDir, data) {
   fs.writeFileSync(path.join(planDir, 'config.local.json'), JSON.stringify(data, null, 2) + '\n');
 }
 
+// ─── composeMilestoneSlug (pure helper) ──────────────────────────────────────
+
+describe('composeMilestoneSlug', () => {
+  const { composeMilestoneSlug } = require('./worktrees.cjs');
+
+  it('version + name -> version dots dashed, sanitized, joined', () => {
+    assert.equal(
+      composeMilestoneSlug({ version: 'v25.0', name: 'Ad-hoc Container' }),
+      'v25-0-ad-hoc-container'
+    );
+  });
+
+  it('blank name -> version alone (NO milestone collapse)', () => {
+    assert.equal(composeMilestoneSlug({ version: 'v25.0', name: '' }), 'v25-0');
+  });
+
+  it("placeholder name 'milestone' -> v25-0-milestone (no bare collapse)", () => {
+    assert.equal(
+      composeMilestoneSlug({ version: 'v25.0', name: 'milestone' }),
+      'v25-0-milestone'
+    );
+  });
+
+  it('project prefix when multiProject', () => {
+    assert.equal(
+      composeMilestoneSlug({ version: 'v25.0', name: 'X', project: 'tp', multiProject: true }),
+      'tp-v25-0-x'
+    );
+  });
+
+  it('no project prefix when single-project', () => {
+    assert.equal(
+      composeMilestoneSlug({ version: 'v25.0', name: 'X', project: 'tp', multiProject: false }),
+      'v25-0-x'
+    );
+  });
+
+  it('both version AND name empty -> deterministic non-empty "milestone" last-resort', () => {
+    const a = composeMilestoneSlug({ version: '', name: '' });
+    const b = composeMilestoneSlug({ version: '', name: '' });
+    assert.ok(a && a.length > 0, 'should be non-empty');
+    assert.equal(a, 'milestone', 'last-resort should be the deterministic bare milestone');
+    assert.equal(a, b, 'should be stable across calls');
+  });
+
+  it('result always passes through slug sanitization (lowercase, [a-z0-9-], <=50)', () => {
+    const out = composeMilestoneSlug({ version: 'v1.0', name: 'A Very Long !!! Name $$$ With Symbols & Spaces Everywhere Indeed Truly' });
+    assert.ok(/^[a-z0-9-]+$/.test(out), 'only lowercase alnum and dashes: ' + out);
+    assert.ok(out.length <= 50, 'slug should be <=50 chars: ' + out);
+    assert.ok(!/--/.test(out), 'no double dashes: ' + out);
+  });
+});
+
+// ─── resolveMilestoneSlug (stamped / legacy-fallback / fresh) ─────────────────
+
+describe('resolveMilestoneSlug', () => {
+  let env;
+  beforeEach(() => { env = createTestEnv(); });
+  afterEach(() => { env.cleanup(); });
+
+  it('returns the NEW composed slug when a worktree entry exists under it', () => {
+    const { resolveMilestoneSlug, composeMilestoneSlug } = require('./worktrees.cjs');
+    const newSlug = composeMilestoneSlug({ version: 'v25.0', name: 'Real Thing' });
+    // Seed a config entry keyed by the new slug.
+    const cfg = readLocalConfig(env.planDir);
+    cfg.projects = { tp: { worktrees: { [newSlug]: { type: 'milestone' } } } };
+    writeLocalConfig(env.planDir, cfg);
+
+    resetPaths(); initPaths(env.planDir);
+    const resolved = resolveMilestoneSlug(env.planDir, 'tp', { version: 'v25.0', name: 'Real Thing' });
+    assert.equal(resolved, newSlug);
+  });
+
+  it('LEGACY FALLBACK: returns the OLD bare-name slug when only an old-style entry exists', () => {
+    const { resolveMilestoneSlug } = require('./worktrees.cjs');
+    const { generateSlugInternal } = require('./core.cjs');
+    const oldSlug = generateSlugInternal('Legacy Milestone'); // bare-name formula
+    const cfg = readLocalConfig(env.planDir);
+    cfg.projects = { tp: { worktrees: { [oldSlug]: { type: 'milestone' } } } };
+    writeLocalConfig(env.planDir, cfg);
+
+    resetPaths(); initPaths(env.planDir);
+    // No entry under the new composed slug -> must legacy-fall-back to oldSlug.
+    const resolved = resolveMilestoneSlug(env.planDir, 'tp', { version: 'v9.9', name: 'Legacy Milestone' });
+    assert.equal(resolved, oldSlug, 'pre-upgrade milestone must still resolve (no orphaning)');
+  });
+
+  it('returns the NEW composed slug when neither entry exists (fresh creation stamps new formula)', () => {
+    const { resolveMilestoneSlug, composeMilestoneSlug } = require('./worktrees.cjs');
+    resetPaths(); initPaths(env.planDir);
+    const resolved = resolveMilestoneSlug(env.planDir, 'tp', { version: 'v3.0', name: 'Brand New' });
+    assert.equal(resolved, composeMilestoneSlug({ version: 'v3.0', name: 'Brand New' }));
+  });
+});
+
+describe('cmdWorktreesCreate — slug stamping', () => {
+  let env;
+  beforeEach(() => { env = createTestEnv(); });
+  afterEach(() => { env.cleanup(); });
+
+  it('stamps milestone_slug + slug_formula:v2 on milestone worktree entries', () => {
+    runCmd(env.planDir, 'worktrees create stamp-ms --type milestone');
+    const config = readLocalConfig(env.planDir);
+    const entry = config.projects.tp.worktrees['stamp-ms'];
+    assert.ok(entry);
+    assert.equal(entry.milestone_slug, 'stamp-ms');
+    assert.equal(entry.slug_formula, 'v2');
+  });
+
+  it('does NOT stamp milestone_slug/slug_formula on quick worktree entries', () => {
+    runCmd(env.planDir, 'worktrees create stamp-quick --type quick');
+    const config = readLocalConfig(env.planDir);
+    const entry = config.projects.tp.worktrees['stamp-quick'];
+    assert.ok(entry);
+    assert.equal(entry.milestone_slug, undefined);
+    assert.equal(entry.slug_formula, undefined);
+  });
+});
+
 // ─── REPOS.md setup field parsing ─────────────────────────────────────────────
 
 describe('REPOS.md setup field parsing', () => {
@@ -792,6 +911,102 @@ describe('rebaseAndMerge', () => {
     assert.ok(!result.success);
     assert.ok(result.error.includes('nonexistent'));
   });
+
+  it('deletes the owned remote milestone branch on merge success', () => {
+    const { slug, wtPath, branchName } = createWorktreeForRebase(env);
+
+    // Commit on milestone branch and push it to origin so a remote branch exists.
+    fs.writeFileSync(path.join(wtPath, 'feat.txt'), 'work');
+    execSync('git add . && git commit -m "ms work"', { cwd: wtPath, stdio: 'pipe', env: env.fullEnv });
+    execSync('git push origin ' + JSON.stringify(branchName), { cwd: wtPath, stdio: 'pipe', env: env.fullEnv });
+
+    // Precondition: remote has the milestone branch.
+    const before = execSync('git ls-remote --heads origin ' + JSON.stringify(branchName), { cwd: env.codeDir, encoding: 'utf-8', stdio: 'pipe', env: env.fullEnv });
+    assert.ok(before.trim().length > 0, 'precondition: remote milestone branch exists');
+
+    const { rebaseAndMerge } = require('./worktrees.cjs');
+    const result = rebaseAndMerge(env.planDir, 'code-repo', slug, { push: true });
+
+    assert.ok(result.success, 'should succeed: ' + (result.error || ''));
+    assert.ok(result.merged);
+    assert.equal(result.remoteBranchDeleted, true, 'should report remoteBranchDeleted:true');
+
+    // Remote no longer has the milestone branch.
+    const after = execSync('git ls-remote --heads origin ' + JSON.stringify(branchName), { cwd: env.codeDir, encoding: 'utf-8', stdio: 'pipe', env: env.fullEnv });
+    assert.equal(after.trim(), '', 'remote milestone branch should be deleted');
+  });
+
+  it('keeps success when there is no remote milestone branch to delete (non-fatal)', () => {
+    const { slug, wtPath } = createWorktreeForRebase(env);
+
+    // Commit on milestone branch but do NOT push it -> no remote milestone branch.
+    fs.writeFileSync(path.join(wtPath, 'feat.txt'), 'work');
+    execSync('git add . && git commit -m "ms work"', { cwd: wtPath, stdio: 'pipe', env: env.fullEnv });
+
+    const { rebaseAndMerge } = require('./worktrees.cjs');
+    const result = rebaseAndMerge(env.planDir, 'code-repo', slug, { push: true });
+
+    // Delete-failure (no such remote branch) must be non-fatal.
+    assert.ok(result.success, 'should still succeed: ' + (result.error || ''));
+    assert.ok(result.merged);
+    assert.equal(result.remoteBranchDeleted, false, 'no remote branch -> remoteBranchDeleted:false');
+  });
+
+  it('never attempts remote delete on a conflicted merge', () => {
+    const { slug, wtPath } = createWorktreeForRebase(env);
+
+    // Create a conflict.
+    fs.writeFileSync(path.join(env.codeDir, 'shared.txt'), 'main version');
+    execSync('git add . && git commit -m "main shared"', { cwd: env.codeDir, stdio: 'pipe', env: env.fullEnv });
+    execSync('git push origin main', { cwd: env.codeDir, stdio: 'pipe', env: env.fullEnv });
+    fs.writeFileSync(path.join(wtPath, 'shared.txt'), 'milestone version');
+    execSync('git add . && git commit -m "ms shared"', { cwd: wtPath, stdio: 'pipe', env: env.fullEnv });
+
+    const { rebaseAndMerge } = require('./worktrees.cjs');
+    const result = rebaseAndMerge(env.planDir, 'code-repo', slug, { push: true });
+
+    assert.ok(!result.success);
+    assert.ok(result.conflicted);
+    assert.equal(result.remoteBranchDeleted, undefined, 'remoteBranchDeleted only on success path');
+  });
+});
+
+// ─── checkRemoteCollision ────────────────────────────────────────────────────
+
+describe('checkRemoteCollision', () => {
+  let env;
+  beforeEach(() => { env = createRebaseTestEnv(); });
+  afterEach(() => { env.cleanup(); });
+
+  it('reports collision when origin has a milestone branch with unmerged commits', () => {
+    const slug = 'squat-slug';
+    const branch = 'milestone/' + slug;
+
+    // Create a milestone branch in the main checkout with a commit NOT on main,
+    // then push it to origin so it squats the name.
+    execSync('git checkout -b ' + branch, { cwd: env.codeDir, stdio: 'pipe', env: env.fullEnv });
+    fs.writeFileSync(path.join(env.codeDir, 'squat.txt'), 'unmerged work');
+    execSync('git add . && git commit -m "squatting commit"', { cwd: env.codeDir, stdio: 'pipe', env: env.fullEnv });
+    execSync('git push origin ' + JSON.stringify(branch), { cwd: env.codeDir, stdio: 'pipe', env: env.fullEnv });
+    // Return main checkout to base_branch.
+    execSync('git checkout main', { cwd: env.codeDir, stdio: 'pipe', env: env.fullEnv });
+
+    const { checkRemoteCollision } = require('./worktrees.cjs');
+    const result = checkRemoteCollision(env.planDir, slug);
+
+    assert.equal(result.collision, true, 'should detect collision');
+    assert.equal(result.branch, branch);
+    assert.ok(result.message && result.message.length > 0, 'should have an actionable message');
+    assert.ok(result.message.includes(branch), 'message should name the colliding branch');
+  });
+
+  it('reports no collision when origin has no such milestone branch', () => {
+    const { checkRemoteCollision } = require('./worktrees.cjs');
+    const result = checkRemoteCollision(env.planDir, 'no-such-slug');
+
+    assert.equal(result.collision, false);
+    assert.equal(result.message, '');
+  });
 });
 
 // ─── checkWorktreeHealth ─────────────────────────────────────────────────────
@@ -928,6 +1143,200 @@ describe('cmdWorktreesCreate — milestone_version', () => {
   });
 });
 
+// ─── new-milestone --adhoc creation ──────────────────────────────────────────
+
+/**
+ * Ad-hoc creation helpers.
+ *
+ * The `--adhoc` flow is driven through the CLI verb `milestone create-adhoc`
+ * (Wave 2), mirroring how the rest of this file invokes worktree commands via
+ * subprocess. The verb performs the canonical 6-step atomic creation:
+ *   1. assert preconditions   2. capture planning base ref
+ *   3. create code worktrees  4. mirror adhoc marker on worktree entry
+ *   5. commit STATE.md adhoc:true   6. set active_context LAST
+ * with full rollback on any failure.
+ */
+
+/** Run the ad-hoc creation verb, returning parsed JSON. */
+function runAdhocCreate(planDir, name, extraArgs) {
+  return runCmd(planDir, 'milestone create-adhoc ' + JSON.stringify(name) + ' ' + (extraArgs || ''));
+}
+
+/** Run the ad-hoc creation verb expecting an error; returns stderr string. */
+function runAdhocCreateError(planDir, name, extraArgs) {
+  return runCmdError(planDir, 'milestone create-adhoc ' + JSON.stringify(name) + ' ' + (extraArgs || ''));
+}
+
+/** True if a git ref resolves in the given repo. */
+function refExists(repoDir, ref) {
+  try {
+    execSync('git show-ref --verify --quiet ' + JSON.stringify(ref), { cwd: repoDir, stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Read STATE.md frontmatter (naive YAML key:value scan, adhoc/milestone only). */
+function readStateFrontmatter(planDir) {
+  const statePath = path.join(planDir, 'projects', 'tp', 'STATE.md');
+  if (!fs.existsSync(statePath)) return {};
+  const content = fs.readFileSync(statePath, 'utf-8');
+  const m = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return {};
+  const fm = {};
+  for (const line of m[1].split('\n')) {
+    const kv = line.match(/^([A-Za-z0-9_]+):\s*(.*)$/);
+    if (kv) fm[kv[1]] = kv[2].trim();
+  }
+  return fm;
+}
+
+describe('new-milestone --adhoc creation', () => {
+  let env;
+  beforeEach(() => { env = createTestEnv(); });
+  afterEach(() => { env.cleanup(); });
+
+  it('creates worktrees, marker, base ref, and sets active_context last', () => {
+    const result = runAdhocCreate(env.planDir, 'My Adhoc Thing');
+    const slug = result.slug;
+    assert.ok(slug, 'should return a slug');
+
+    // Structural composition: slug embeds the version segment (default v0.1 ->
+    // v0-1) ahead of the name, NOT the bare name — branch-name collision fix.
+    assert.ok(slug.startsWith('v0-1-'), 'ad-hoc slug should be version-prefixed: ' + slug);
+    assert.ok(slug.includes('my-adhoc-thing'), 'ad-hoc slug should include the name segment: ' + slug);
+
+    // Each registered code repo has a milestone/{slug} branch + worktree.
+    const branches = execSync('git branch', { cwd: env.codeDir, encoding: 'utf-8', stdio: 'pipe' });
+    assert.ok(branches.includes('milestone/' + slug), 'code repo should have milestone/{slug} branch');
+
+    // Worktree entry: type milestone, adhoc:true, non-empty adhoc_base_ref.
+    const config = readLocalConfig(env.planDir);
+    const entry = config.projects.tp.worktrees[slug];
+    assert.ok(entry, 'worktree entry should exist');
+    assert.equal(entry.type, 'milestone');
+    assert.equal(entry.adhoc, true, 'entry should carry adhoc:true');
+    assert.ok(entry.adhoc_base_ref && entry.adhoc_base_ref.length > 0, 'entry should record adhoc_base_ref');
+
+    // STATE.md frontmatter has adhoc: true.
+    const fm = readStateFrontmatter(env.planDir);
+    assert.equal(fm.adhoc, 'true', 'STATE.md frontmatter should carry adhoc: true');
+
+    // Base ref exists in planning repo.
+    assert.ok(refExists(env.planDir, 'refs/dgs/adhoc/' + slug + '/base'), 'base ref should exist');
+
+    // active_context set to slug (set LAST).
+    assert.equal(config.execution.active_context, slug, 'active_context should equal slug');
+  });
+
+  it('routes a quick run after --adhoc onto the milestone branch', () => {
+    const result = runAdhocCreate(env.planDir, 'Route Test');
+    const slug = result.slug;
+
+    // detectQuickMode must report milestone-context (NOT product) for the slug.
+    resetPaths();
+    initPaths(env.planDir);
+    const { detectQuickMode } = require('./quick.cjs');
+    const mode = detectQuickMode(env.planDir, false);
+    assert.equal(mode.mode, 'milestone-context', 'quick should route to milestone-context');
+    assert.equal(mode.activeSlug, slug);
+
+    // A code commit lands on milestone/{slug}, not base_branch.
+    const config = readLocalConfig(env.planDir);
+    const wtPath = config.projects.tp.worktrees[slug].repos['code-repo'];
+    fs.writeFileSync(path.join(wtPath, 'quick-work.txt'), 'work');
+    execSync('git add . && git commit -m "quick work"', { cwd: wtPath, stdio: 'pipe', env: { ...process.env, ...GIT_ENV } });
+    const wtBranch = execSync('git rev-parse --abbrev-ref HEAD', { cwd: wtPath, encoding: 'utf-8', stdio: 'pipe' }).trim();
+    assert.equal(wtBranch, 'milestone/' + slug, 'commit should be on milestone branch');
+    const mainLog = execSync('git log --oneline main', { cwd: env.codeDir, encoding: 'utf-8', stdio: 'pipe' });
+    assert.ok(!mainLog.includes('quick work'), 'base_branch must NOT have the quick commit');
+  });
+
+  it('rolls back fully when a code-repo worktree creation fails', () => {
+    // The structural ad-hoc slug is [<version>-]<name-slug>; 'conflict slug'
+    // with the default v0.1 version composes to 'v0-1-conflict-slug'.
+    const composedSlug = 'v0-1-conflict-slug';
+    // Force a worktree-create failure by pre-creating the conflicting branch that
+    // is already checked out in the main checkout (worktree add will refuse).
+    execSync('git branch milestone/' + composedSlug, { cwd: env.codeDir, stdio: 'pipe', env: { ...process.env, ...GIT_ENV } });
+    execSync('git checkout milestone/' + composedSlug, { cwd: env.codeDir, stdio: 'pipe', env: { ...process.env, ...GIT_ENV } });
+
+    const err = runAdhocCreateError(env.planDir, 'conflict slug');
+    assert.ok(err, 'should error on worktree-create failure');
+
+    // No residue: no base ref, no worktree entry, no STATE marker, no active_context.
+    assert.ok(!refExists(env.planDir, 'refs/dgs/adhoc/' + composedSlug + '/base'), 'base ref must be removed on rollback');
+    const config = readLocalConfig(env.planDir);
+    const wt = config.projects && config.projects.tp && config.projects.tp.worktrees;
+    assert.ok(!wt || !wt[composedSlug], 'no worktree entry should remain');
+    const fm = readStateFrontmatter(env.planDir);
+    assert.notEqual(fm.adhoc, 'true', 'STATE.md must not have adhoc:true after rollback');
+    assert.ok(!config.execution || !config.execution.active_context, 'active_context must be unset after rollback');
+  });
+
+  it('refuses when the planning or a code working tree is dirty', () => {
+    // Dirty a tracked file in the planning repo.
+    fs.writeFileSync(path.join(env.planDir, 'config.json'), JSON.stringify({ git: { base_branch: 'main' }, dirty: true }, null, 2));
+
+    const err = runAdhocCreateError(env.planDir, 'dirty test');
+    assert.ok(err, 'should refuse on dirty tree');
+
+    // ZERO mutation.
+    assert.ok(!refExists(env.planDir, 'refs/dgs/adhoc/dirty-test/base'), 'no base ref on refusal');
+    const config = readLocalConfig(env.planDir);
+    const wt = config.projects && config.projects.tp && config.projects.tp.worktrees;
+    assert.ok(!wt || !wt['dirty-test'], 'no worktree entry on refusal');
+    assert.ok(!config.execution || !config.execution.active_context, 'no active_context on refusal');
+  });
+
+  it('refuses when an active_context is already set', () => {
+    // Pre-set active_context.
+    const cfg = readLocalConfig(env.planDir);
+    cfg.execution = { active_context: 'someone-else' };
+    writeLocalConfig(env.planDir, cfg);
+
+    const err = runAdhocCreateError(env.planDir, 'second context');
+    assert.ok(err, 'should refuse when active_context already set');
+
+    // ZERO mutation — active_context unchanged, no new ref/entry.
+    const after = readLocalConfig(env.planDir);
+    assert.equal(after.execution.active_context, 'someone-else', 'active_context must be unchanged');
+    assert.ok(!refExists(env.planDir, 'refs/dgs/adhoc/second-context/base'), 'no base ref on refusal');
+    const wt = after.projects && after.projects.tp && after.projects.tp.worktrees;
+    assert.ok(!wt || !wt['second-context'], 'no worktree entry on refusal');
+  });
+
+  it('defaults the version recommendation to minor and writes vX.Y provisionally', () => {
+    const result = runAdhocCreate(env.planDir, 'Version Default');
+    const slug = result.slug;
+    const fm = readStateFrontmatter(env.planDir);
+    // STATE.md frontmatter carries a two-component vX.Y version.
+    const version = fm.milestone || fm.version || (result && result.version);
+    assert.ok(version, 'a version should be recorded');
+    assert.match(String(version), /^v?\d+\.\d+$/, 'version should be two-component vX.Y: ' + version);
+    assert.ok(slug);
+  });
+
+  it('prints the ADH-22 abandon advisory on successful creation', () => {
+    // The advisory is printed on stderr. Capture both streams (2>&1) so the
+    // advisory is visible whether the command succeeds or fails.
+    let out = '';
+    try {
+      out = execSync(
+        'node ' + JSON.stringify(DGS_TOOLS) + ' milestone create-adhoc ' + JSON.stringify('Advisory Test') + ' 2>&1',
+        { cwd: env.planDir, stdio: ['pipe', 'pipe', 'pipe'], encoding: 'utf-8', env: { ...process.env, ...GIT_ENV } }
+      );
+    } catch (e) {
+      out = (e.stdout || '') + (e.stderr || '');
+    }
+    const combined = out;
+    // Advisory mentions abandon + a --main / base_branch quick STATE.md revert.
+    assert.match(combined, /abandon/i, 'advisory should mention abandon');
+    assert.match(combined, /--main|base_branch|STATE\.md/, 'advisory should reference the --main quick STATE.md revert');
+  });
+});
+
 // ─── main checkout invariant ─────────────────────────────────────────────────
 
 describe('main checkout invariant', () => {

package/deliver-great-systems/templates/claude-md.md

@@ -53,6 +53,8 @@ When the request involves creating, modifying, or deleting code or configuration
 
 **Is it a trivial 1-line fix?** Route through `/dgs:fast` (always direct to main, zero overhead)
 
+- **Ad-hoc container milestone:** `/dgs:new-milestone --adhoc "title"` starts a lightweight container where quicks & fasts route into the milestone; `/dgs:abandon-milestone` discards it cleanly.
+
 **When ambiguous, default to the smaller command.** Prefer `/dgs:fast` or `/dgs:quick` over `/dgs:execute-phase`.
 
 Before invoking, mention briefly: "Small fix, routing through `/dgs:fast`." -- command name and short reason.

package/deliver-great-systems/templates/state.md

@@ -75,6 +75,22 @@ Stopped at: [Description of last completed action]
 Resume file: [Path to .continue-here*.md if exists, otherwise "None"]
 ```
 
+## Optional Frontmatter
+
+Ad-hoc container milestones (created via `/dgs:new-milestone --adhoc`) stamp an optional
+YAML frontmatter block at the top of STATE.md:
+
+```yaml
+---
+adhoc: true            # marks this as an ad-hoc container milestone
+milestone: v0.1        # provisional version
+---
+```
+
+The `adhoc` field is read by the tooling (`stateReadAdhoc`) to relax the completion
+readiness gate and surface the ad-hoc marker in `/dgs:progress` and the completion
+preamble. It is absent for normal spec/phase-driven milestones.
+
 <purpose>
 
 STATE.md is the project's short-term memory spanning all phases and sessions.

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

@@ -0,0 +1,120 @@
+<purpose>
+Abandon the active ad-hoc milestone: remove the milestone worktrees and local code branches, and path-scoped-restore the 5 project planning docs (PROJECT.md, STATE.md, ROADMAP.md, REQUIREMENTS.md, config.json) to their pre-milestone state from the snapshot base ref — without merging. An attributed reversion commit records the discard.
+
+Ad-hoc-only: spec/phase-driven milestones are refused with guidance. Requires explicit confirmation before proceeding. This is destructive and cannot be undone.
+</purpose>
+
+<context_tier>none</context_tier>
+
+<process>
+
+**Step 1: Validate active ad-hoc milestone**
+
+Resolve the active context slug:
+```bash
+SLUG=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" config-get execution.active_context 2>/dev/null | sed 's/^"//;s/"$//')
+```
+
+If `SLUG` is empty or `null`:
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+No active milestone to abandon.
+```
+End workflow.
+
+Verify the active milestone is ad-hoc (both the STATE.md marker AND the worktree entry):
+```bash
+ADHOC=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" state read-adhoc 2>/dev/null)
+ENTRY_ADHOC=$(node -e "
+  const fs = require('fs');
+  try {
+    const cfg = JSON.parse(fs.readFileSync('config.local.json', 'utf-8'));
+    const p = cfg.current_project;
+    const e = cfg.projects && cfg.projects[p] && cfg.projects[p].worktrees && cfg.projects[p].worktrees['$SLUG'];
+    process.stdout.write(String(!!(e && e.adhoc === true && e.adhoc_base_ref)));
+  } catch { process.stdout.write('false'); }
+")
+```
+
+If `ADHOC` is not `true` OR `ENTRY_ADHOC` is not `true`:
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+abandon-milestone only discards ad-hoc milestones.
+'${SLUG}' is spec/phase-driven — complete it with /dgs:complete-milestone.
+
+No changes made.
+```
+End workflow. (Make NO changes.)
+
+**Step 2: Confirm abandonment (ADH-12)**
+
+```
+AskUserQuestion(
+  header: "Abandon Milestone",
+  question: "Abandon ad-hoc milestone '${SLUG}'? All uncommitted and committed milestone changes will be lost — worktrees/branches removed and planning docs restored to their pre-milestone state.",
+  options: [
+    { label: "Yes, abandon", description: "Remove worktrees/branches and restore planning docs — changes are lost" },
+    { label: "No, keep", description: "Cancel — milestone remains active" }
+  ]
+)
+```
+
+If "No, keep": Display `Milestone '${SLUG}' remains active.` End workflow.
+
+**Step 3: Execute abandonment**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ DGS ► ABANDONING MILESTONE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ Removing worktrees/branches and restoring planning docs...
+```
+
+```bash
+RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" milestone abandon --confirmed 2>&1)
+EXIT_CODE=$?
+```
+
+**Step 4: Display result**
+
+**If exit code is 0 (success):**
+Parse the restored-docs list and any warnings from RESULT (JSON: `{ abandoned, slug, base_ref, restored, reverted, warnings }`).
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ DGS ► MILESTONE ABANDONED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Milestone '${SLUG}' abandoned.
+Worktrees and local branches removed; active context cleared.
+Restored to pre-milestone state: <restored docs>
+No changes merged to base_branch.
+```
+During teardown, abandon now also DELETES the owned remote `milestone/${SLUG}`
+branch on origin (`git push origin --delete milestone/<slug>`), reclaiming the
+milestone name to prevent future branch-name collisions. This replaces the prior
+warn-only "remote ref left for you to delete" behaviour. A failed remote delete
+is **non-fatal**: it is collected into `warnings` and the abandon still reports
+`abandoned: true`. Surface any such warnings from RESULT verbatim.
+
+**If error (non-zero exit):**
+Display the error / reverted-vs-not report from RESULT verbatim (ADH-20 — it states precisely what was and was not reverted, and how to recover the remainder). Make no further changes.
+
+</process>
+
+<success_criteria>
+- [ ] Active ad-hoc milestone validated (slug resolved from active_context)
+- [ ] Non-ad-hoc milestones refused with guidance, no changes (ADH-08)
+- [ ] Confirmation required before abandonment, with the loss-warning message (ADH-12)
+- [ ] Worktrees and local branches removed without merging
+- [ ] The 5 project docs path-scoped-restored to the base ref (never a whole-tree reset) (ADH-09)
+- [ ] Attributed reversion commit recorded (ADH-20)
+- [ ] active_context cleared
+- [ ] Owned remote milestone branch deleted during teardown (non-fatal on failure); failures surfaced as warnings (ADH-20)
+</success_criteria>