@ktpartners/dgs-platform 3.3.1 → 3.4.2

package/CHANGELOG.md

@@ -8,6 +8,34 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [3.4.2] - 2026-06-25
+
+### Fixed
+- **Shipped workflows no longer hardcode the author's home path (quick-260625-0b3)** — `workflows/init-product.md` (8 sites) and `workflows/execute-plan.md` (1 site) invoked `node`/`cat` against the literal `/Users/adrian/.claude/deliver-great-systems/...`, so on any other user's machine those `dgs-tools` calls and the CLAUDE.md template read pointed at a nonexistent directory and failed. Replaced every occurrence with the portable `~/.claude/deliver-great-systems/...` form already used by all other workflows. No code or config files were affected — this was the only path leak in the distribution; `git grep /Users/adrian` over the shipped workflows now returns nothing.
+
+## [3.4.1] - 2026-06-12
+
+### Fixed
+- **Milestone branch-name collision fixed across four levels (quick-260612-b2z)** — a placeholder/blank milestone name previously collapsed to the bare `milestone/milestone` branch (`init.cjs` derived the slug as `generateSlugInternal(name) || 'milestone'`), and lingering remote `milestone/<slug>` branches squatted the name because nothing ran `push origin --delete`. Cross-milestone branch-name collisions resulted. Fixed by:
+  1. **Structural slug composition** — new `composeMilestoneSlug({version,name,project,multiProject})` in `worktrees.cjs` builds `[<project>-]<version>-<name-slug>` (project prefix only when more than one active project exists). A non-empty version always guarantees uniqueness, so a blank name yields the version segment alone — the bare `milestone` slug is returned ONLY as a last resort when both version and name are empty.
+  2. **Stamped-slug persist + read with legacy fallback** — milestone worktree entries are stamped with `milestone_slug` + `slug_formula: 'v2'` on create; the new `resolveMilestoneSlug()` resolver prefers the stamped key and legacy-falls-back to the OLD bare-name slug, so in-flight milestones created before the upgrade are never orphaned. `init.cjs` reads all three slug-derivation sites through the resolver.
+  3. **Remote milestone-branch cleanup** — `rebaseAndMerge` deletes the owned remote `milestone/<slug>` branch on merge SUCCESS only (returning `remoteBranchDeleted`); `cmdAbandonMilestone` deletes it during teardown (replacing the prior warn-only behaviour). Both deletes are NON-FATAL — a failed `git push origin --delete` is collected as a warning and never fails the completion/abandon.
+  4. **Pre-flight collision guard** — new `checkRemoteCollision()` helper + `worktrees check-collision <slug>` CLI verb. `run-job` REFUSES at job start (the chosen safe default) when `origin/milestone/<slug>` exists with commits not reachable from `base_branch`, naming the colliding branch; `create-milestone-job` surfaces a non-blocking advisory.
+  - Ad-hoc milestones (`milestone create-adhoc`) adopt the same `composeMilestoneSlug` composition, so ad-hoc branches are version-prefixed and consistent. `detectQuickMode` is byte-unchanged.
+
+## [3.4.0] - 2026-06-11
+
+### Added — v24.0 Ad-hoc Container Milestone with Worktree Isolation
+- **`/dgs:new-milestone --adhoc`** — starts a worktree-isolated ad-hoc milestone container in one command, with no questioning/research/requirements/roadmap. Creation is atomic and canonically ordered (active_context set last) via `milestone create-adhoc`: it captures a `refs/dgs/adhoc/{slug}/base` snapshot ref of the pre-milestone planning HEAD and rolls back every artifact (worktrees, snapshot ref, STATE commit) on any failure — no leak window, no orphan ref. Quicks and fasts run after an ad-hoc start auto-join the `milestone/{slug}` branch with zero change to `detectQuickMode` (ADH-01/02/03/04/05/06/18/19/22).
+- **`/dgs:abandon-milestone`** (`cmdAbandonMilestone`) — the mirror of creation: removes the milestone worktrees/branches and path-scoped-restores the project planning docs (PROJECT/STATE/ROADMAP/REQUIREMENTS + config `new-milestone` keys) from the snapshot ref, attributing the reversion to the invoking user. Never a whole-tree reset; removes local branches only with a pushed-branch warning; gated behind a `--confirmed` data-loss message; errors on non-ad-hoc milestones (ADH-07/08/09/12/20).
+- **Marker-gated relaxed completion** — a quicks-only (zero-phase) ad-hoc milestone can complete and ship under its `vX.Y` tag. New `state adhoc-readiness` predicate counts completed quick rows + phases; the marker-gated `verify_readiness` path skips the 100%-phase assert and traceability audit for ad-hoc milestones while preserving the strict gate (with regression coverage) for normal milestones. Zero-work completion is refused with an actionable message (ADH-10/11/13).
+- **Lifecycle cleanup, status & docs** — `cleanupAdhoc` / `milestone cleanup-adhoc` removes the residual base ref and worktree entry on both complete and abandon (base ref resolved to an immutable SHA before abandon-restore). The `adhoc` marker now renders in `/dgs:progress` and the completion preamble; the `adhoc` field is documented in `templates/state.md`, help, and the command reference (ADH-14/15/21).
+
+### Fixed
+- **`docs add` now honours the flat idea layout** — idea-scoped attachments previously wrote to the legacy `ideas/pending/<id>/docs/` path even for flat-layout ideas (`ideas/<id>-slug.md`). `resolveDocsDir` now derives the docs dir from the resolved flat idea path, and the three previously-duplicated read paths (`docs list`, `search`, `context`) route through one shared flat-aware enumerator with a legacy back-compat fallback so pre-migration idea docs still resolve (quick-260611-jjv).
+- **Workflow-discipline hook no longer false-blocks `/dgs:*` workflow writes on slash-command entry** — the PreToolUse gate keyed its allow-decision on a marker that was only written via the `Skill` tool, so a slash-command-invoked workflow (e.g. `discuss-phase` writing its `CONTEXT.md`) had no marker and every Write denied. The hook now also writes the active-session marker when it observes a `dgs-tools … init` Bash call, and path-exempts planning artifacts, while still blocking real code edits with no active command (quick-260611-m3s).
+- **Hook active-marker persists across the Skill PostToolUse** — the marker was being deleted immediately after creation, re-blocking orchestrator writes mid-workflow; it now persists for the session.
+
 ## [3.3.1] - 2026-05-26
 
 ### Fixed

package/README.md

@@ -373,6 +373,8 @@ Code repos are isolated using git worktrees. Each milestone gets its own directo
 | Quick | `dgs:quick` | Ephemeral worktree — auto-cleanup on complete |
 | Milestone | `execute-phase` | Dedicated worktree — persists across phases |
 
+You can also start a lightweight **ad-hoc container milestone** with `/dgs:new-milestone --adhoc` — a worktree-isolated branch with no spec or roadmap, just a window for batching small work. Quicks and fasts that run during it auto-join the milestone branch unchanged, no extra flags. When you're done, `/dgs:complete-milestone` ships the whole batch as one vX.Y, or `/dgs:abandon-milestone` discards it as a unit and restores your planning docs.
+
 When a milestone or quick fix finishes, DGS rebases onto main and cleans up automatically. See [How Git is Used](docs/GIT-WORKFLOW.md) for the full model.
 
 ---
@@ -591,7 +593,8 @@ See the [User Guide](docs/USER-GUIDE.md#context-tiers) for the complete command-
 | `/dgs:audit-phase <phase> [--rerun-failed]` | Automated phase verification: test execution + structural inspection |
 | `/dgs:audit-milestone` | Verify milestone achieved its definition of done |
 | `/dgs:complete-milestone` | Archive milestone, tag release |
-| `/dgs:new-milestone [name]` | Start milestone: research → requirements → roadmap (first or subsequent) |
+| `/dgs:new-milestone [name] [--adhoc]` | Start milestone: research → requirements → roadmap (first or subsequent); `--adhoc` creates a lightweight worktree-isolated container for batching quicks/fasts |
+| `/dgs:abandon-milestone` | Discard an ad-hoc container milestone, restore planning docs |
 
 ### Navigation
 

package/bin/install.js

@@ -1822,7 +1822,7 @@ function install(isGlobal, runtime = 'claude') {
 
     if (!hasDisciplineHook) {
       settings.hooks.PreToolUse.push({
-        matcher: 'Edit|Write|Skill',
+        matcher: 'Edit|Write|Skill|Bash',
         hooks: [
           {
             type: 'command',

package/commands/dgs/abandon-milestone.md

@@ -0,0 +1,28 @@
+---
+name: dgs:abandon-milestone
+description: Abandon active ad-hoc milestone — remove worktrees and restore planning docs without merging
+argument-hint: "[--confirmed]"
+allowed-tools:
+  - Read
+  - Bash
+  - AskUserQuestion
+---
+<objective>
+Abandon the active ad-hoc milestone.
+
+Remove all milestone worktrees + local code branches and path-scoped-restore the project planning docs (PROJECT.md, STATE.md, ROADMAP.md, REQUIREMENTS.md, config.json) to their pre-milestone state from the snapshot base ref, committing an attributed reversion.
+
+Ad-hoc-only; spec/phase-driven milestones are refused with guidance. Requires confirmation; this action cannot be undone.
+</objective>
+
+<execution_context>
+@~/.claude/deliver-great-systems/workflows/abandon-milestone.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+Execute the abandon-milestone workflow from @~/.claude/deliver-great-systems/workflows/abandon-milestone.md end-to-end.
+</process>

package/commands/dgs/new-milestone.md

@@ -1,7 +1,7 @@
 ---
 name: dgs:new-milestone
 description: Start a new milestone cycle — update PROJECT.md and route to requirements
-argument-hint: "[milestone name, e.g., 'v1.1 Notifications']"
+argument-hint: "[milestone name | --adhoc] (--adhoc: start a worktree-isolated container with no spec/requirements/roadmap)"
 allowed-tools:
   - Read
   - Write
@@ -14,6 +14,8 @@ Start a new milestone: questioning → research (optional) → requirements →
 
 Brownfield equivalent of new-project. Project exists, PROJECT.md has history. Gathers "what's next", updates PROJECT.md, then runs requirements → roadmap cycle.
 
+With `--adhoc`, the command skips questioning, research, requirements, and roadmap and instead establishes a worktree-isolated milestone container directly (creates milestone worktrees for every registered code repo and sets it active). Subsequent quicks/fasts then auto-route into that container. See workflow step `## 1a. Ad-hoc Container (--adhoc)`.
+
 **Creates/Updates:**
 - `${project_path}` — updated with new milestone goals
 - `${project_root}/research/` — domain research (optional, NEW features only)

package/deliver-great-systems/bin/dgs-tools.cjs

@@ -205,6 +205,7 @@
  *   worktrees prune                    Remove orphaned worktree entries
  *   worktrees rebase-and-merge <slug> --repo <name>  Rebase and merge worktree branch
  *   worktrees health <slug>            Check worktree health
+ *   worktrees check-collision <slug>   Pre-flight remote milestone-branch collision check
  *
  * Ideas Operations:
  *   ideas create --title T --body B     Create new idea with auto-assigned ID
@@ -645,8 +646,9 @@ async function main() {
   switch (command) {
     case 'state': {
       const subcommand = args[1];
-      // Gate write subcommands
-      if (subcommand && subcommand !== 'load' && subcommand !== 'get') {
+      // Gate write subcommands. read-adhoc and adhoc-readiness are read-only.
+      if (subcommand && subcommand !== 'load' && subcommand !== 'get' &&
+          subcommand !== 'read-adhoc' && subcommand !== 'adhoc-readiness') {
         gateIdentity();
       }
       if (subcommand === 'update') {
@@ -706,6 +708,12 @@ async function main() {
         state.cmdStateArchiveQuickTasks(cwd, raw);
       } else if (subcommand === 'mark-milestone-complete') {
         state.cmdMarkMilestoneComplete(cwd, raw);
+      } else if (subcommand === 'read-adhoc') {
+        state.cmdStateReadAdhoc(cwd, raw);
+      } else if (subcommand === 'adhoc-readiness') {
+        state.cmdStateAdhocReadiness(cwd, raw);
+      } else if (subcommand === 'set-adhoc') {
+        state.cmdStateSetAdhoc(cwd, args.slice(2), raw);
       } else {
         state.cmdStateLoad(cwd, raw);
       }
@@ -1218,8 +1226,14 @@ async function main() {
           milestoneName = nameArgs.join(' ') || null;
         }
         milestone.cmdMilestoneComplete(cwd, args[2], { name: milestoneName, archivePhases, force }, raw);
+      } else if (subcommand === 'create-adhoc') {
+        milestone.cmdMilestoneCreateAdhoc(cwd, args.slice(2), raw);
+      } else if (subcommand === 'abandon') {
+        milestone.cmdAbandonMilestone(cwd, args.slice(2), raw);
+      } else if (subcommand === 'cleanup-adhoc') {
+        milestone.cmdMilestoneCleanupAdhoc(cwd, args[2], raw);
       } else {
-        error('Unknown milestone subcommand. Available: complete');
+        error('Unknown milestone subcommand. Available: complete, create-adhoc, abandon, cleanup-adhoc');
       }
       break;
     }
@@ -1986,8 +2000,12 @@ async function main() {
         if (!slug) error('Usage: worktrees health <slug>');
         const result = worktrees.checkWorktreeHealth(cwd, slug);
         wtOutput(result);
+      } else if (subcommand === 'check-collision') {
+        const slug = args[2];
+        if (!slug) error('Usage: worktrees check-collision <slug>');
+        wtOutput(worktrees.checkRemoteCollision(cwd, slug));
       } else {
-        error('Unknown worktrees subcommand: ' + subcommand + '. Available: create, remove, list, setup, prune, rebase-and-merge, health');
+        error('Unknown worktrees subcommand: ' + subcommand + '. Available: create, remove, list, setup, prune, rebase-and-merge, health, check-collision');
       }
       break;
     }

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

@@ -588,6 +588,49 @@ function resolveIdeaScope(ideaId, planningRoot, cwd) {
   const paddedId = String(parseInt(idStr, 10)).padStart(3, '0');
   const planRootRel = path.relative(cwd || process.cwd(), planningRoot) || '.';
 
+  const cwdAbs = cwd || process.cwd();
+
+  // Assemble idea-docs for a matched idea file, flat-first then legacy.
+  // `docsBaseDir` is the directory that contains the idea .md file on disk
+  // (ideas/ for flat, ideas/<state>/ for legacy). The flat candidate always
+  // sits at the ideas root, the legacy candidate beside the matched file.
+  function pushIdeaDocs(stem, legacyBaseDir) {
+    const flatDocsDir = path.join(planningRoot, 'ideas', stem, 'docs');
+    const legacyDocsDir = path.join(legacyBaseDir, stem, 'docs');
+    let chosenDocsDir = null;
+    if (fs.existsSync(flatDocsDir)) {
+      chosenDocsDir = flatDocsDir;
+    } else if (fs.existsSync(legacyDocsDir)) {
+      chosenDocsDir = legacyDocsDir;
+    }
+    if (!chosenDocsDir) return;
+    const docFiles = readdirRecursive(chosenDocsDir);
+    for (const docFile of docFiles) {
+      const docRelPath = toPosixPath(path.relative(cwdAbs, path.join(chosenDocsDir, docFile)));
+      results.push({ path: docRelPath, category: 'idea-docs' });
+    }
+  }
+
+  // FLAT first: idea files live directly at ideas/<id>-slug.md
+  const ideasRoot = path.join(planningRoot, 'ideas');
+  let flatFiles;
+  try {
+    flatFiles = fs.readdirSync(ideasRoot, { withFileTypes: true })
+      .filter(e => e.isFile() && e.name.endsWith('.md'))
+      .map(e => e.name);
+  } catch {
+    flatFiles = [];
+  }
+  for (const file of flatFiles) {
+    if (file.startsWith(paddedId + '-') || file === ideaId || file === ideaId + '.md') {
+      const relPath = toPosixPath(path.join(planRootRel, 'ideas', file));
+      results.push({ path: relPath, category: 'idea' });
+      pushIdeaDocs(file.replace(/\.md$/, ''), ideasRoot);
+      return results; // Found the flat idea, stop searching
+    }
+  }
+
+  // LEGACY fallback: idea files under ideas/<state>/<id>-slug.md
   const ideaStates = ['pending', 'done', 'rejected', 'consolidated'];
 
   for (const state of ideaStates) {
@@ -605,21 +648,8 @@ function resolveIdeaScope(ideaId, planningRoot, cwd) {
         const relPath = toPosixPath(path.join(planRootRel, 'ideas', state, file));
         results.push({ path: relPath, category: 'idea' });
 
-        // Check for docs/ directory alongside the idea
-        // Idea docs/ is at ideas/<state>/<idea-slug>/docs/ where idea-slug matches the filename stem
-        const stem = file.replace(/\.md$/, '');
-        const docsDir = path.join(dir, stem, 'docs');
-        if (fs.existsSync(docsDir)) {
-          const docFiles = readdirRecursive(docsDir);
-          for (const docFile of docFiles) {
-            const docRelPath = toPosixPath(path.join(planRootRel, 'ideas', state, stem, 'docs', docFile));
-            results.push({ path: docRelPath, category: 'idea-docs' });
-          }
-        }
-
-        // Also check docs/ directly under the ideas state dir named by idea slug
-        const altDocsDir = path.join(planningRoot, 'ideas', state, 'docs');
-        // This is less common, skip unless the first pattern doesn't exist
+        // Resolve docs/ flat-first then legacy (ideas/<state>/<slug>/docs).
+        pushIdeaDocs(file.replace(/\.md$/, ''), dir);
 
         return results; // Found the idea, stop searching
       }

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

@@ -5,7 +5,7 @@
  * add, list, remove, move, and INDEX.md maintenance.
  * Documents are stored in scope-specific docs/ directories:
  * - Product-level: docs/
- * - Idea-scoped: ideas/{state}/{idea-slug}/docs/
+ * - Idea-scoped: ideas/{idea-slug}/docs/   (flat; legacy ideas/{state}/{idea-slug}/docs/ still read for back-compat)
  * - Spec-scoped: specs/{spec-slug}/docs/
  * Text extraction produces .extracted.txt sidecars for PDF, XLSX, CSV, DOCX.
  * Large extractions also generate .summary.txt sidecars.
@@ -17,7 +17,7 @@ const crypto = require('crypto');
 const { spawnSync } = require('child_process');
 const { safeReadFile, execGit, generateSlugInternal, output, error } = require('./core.cjs');
 const { getPlanningRoot } = require('./paths.cjs');
-const { findIdeaFile } = require('./ideas.cjs');
+const { findIdeaFile, IDEA_STATES } = require('./ideas.cjs');
 
 // ─── Constants ──────────────────────────────────────────────────────────────
 
@@ -85,9 +85,12 @@ function resolveDocsDir(cwd, scope, scopeId) {
     if (!idea) {
       error(`idea not found: ${scopeId}. No matching idea file exists in pending, done, or rejected`);
     }
-    // Derive directory name from idea filename (strip .md extension)
-    const ideaDirName = idea.filename.replace(/\.md$/, '');
-    const ideaDir = path.join(planRoot, 'ideas', idea.state, ideaDirName);
+    // Derive the docs dir directly from the idea's REAL on-disk location, never
+    // from idea.state. Flat ideas live at ideas/<id>-slug.md, so the docs dir is
+    // the sibling ideas/<id>-slug/docs/. Legacy ideas live at
+    // ideas/<state>/<id>-slug.md, so findIdeaFile returns that path and the same
+    // derivation yields ideas/<state>/<id>-slug/docs/ — correct in both cases.
+    const ideaDir = idea.path.replace(/\.md$/, '');
     // Auto-create idea directory if it only exists as a file
     fs.mkdirSync(ideaDir, { recursive: true });
     return path.join(ideaDir, 'docs');
@@ -110,6 +113,63 @@ function ensureDocsDir(dirPath) {
   fs.mkdirSync(dirPath, { recursive: true });
 }
 
+/**
+ * Enumerate all idea docs directories, flat-aware with legacy fallback.
+ *
+ * Flat layout (current):  ideas/<id>-slug/docs/      (sibling of ideas/<id>-slug.md)
+ * Legacy layout (read-only back-compat): ideas/<state>/<id>-slug/docs/
+ *
+ * This is the SINGLE shared enumerator used by every idea-docs READ path
+ * (docs list, search, context) so they cannot drift into split-brain.
+ *
+ * @param {string} cwd - Working directory
+ * @returns {Array<{ ideaSlug: string, docsDir: string, state: string|null, legacy: boolean }>}
+ */
+function enumerateIdeaDocsDirs(cwd) {
+  const planRoot = getPlanningRoot(cwd);
+  const ideasRoot = path.join(planRoot, 'ideas');
+  const out = [];
+
+  // FLAT first: ideas/<slug>/docs (directories at the ideas root whose name is
+  // NOT a legacy state segment).
+  let topEntries;
+  try {
+    topEntries = fs.readdirSync(ideasRoot, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of topEntries) {
+    if (!entry.isDirectory()) continue;
+    if (IDEA_STATES.includes(entry.name)) continue;
+    const docsDir = path.join(ideasRoot, entry.name, 'docs');
+    if (fs.existsSync(docsDir)) {
+      out.push({ ideaSlug: entry.name, docsDir, state: null, legacy: false });
+    }
+  }
+
+  // LEGACY fallback: ideas/<state>/<slug>/docs (pre-migration dirs).
+  for (const state of IDEA_STATES) {
+    const stateDir = path.join(ideasRoot, state);
+    let stateEntries;
+    try {
+      stateEntries = fs.readdirSync(stateDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of stateEntries) {
+      if (!entry.isDirectory()) continue;
+      const docsDir = path.join(stateDir, entry.name, 'docs');
+      if (fs.existsSync(docsDir)) {
+        out.push({ ideaSlug: entry.name, docsDir, state, legacy: true });
+      }
+    }
+  }
+
+  // No de-dup needed: flat (ideas/<slug>/docs) and legacy
+  // (ideas/<state>/<slug>/docs) paths can never collide.
+  return out;
+}
+
 // ─── Text Extraction ────────────────────────────────────────────────────────
 
 /**
@@ -621,31 +681,14 @@ function cmdDocsList(cwd, scopeFilter, raw) {
     }
   }
 
-  // Idea docs
+  // Idea docs — flat-aware via the shared enumerator (legacy dirs still resolved)
   if (!filterScope || filterScope === 'idea') {
-    const states = ['pending', 'done', 'rejected'];
-    for (const state of states) {
-      const stateDir = path.join(getPlanningRoot(cwd), 'ideas', state);
-      if (!fs.existsSync(stateDir)) continue;
-
-      let ideaDirs;
-      try {
-        ideaDirs = fs.readdirSync(stateDir, { withFileTypes: true })
-          .filter(e => e.isDirectory())
-          .map(e => e.name);
-      } catch {
-        continue;
-      }
-
-      for (const ideaSlug of ideaDirs) {
-        if (filterId && ideaSlug !== filterId) continue;
-        const docsDir = path.join(stateDir, ideaSlug, 'docs');
-        if (!fs.existsSync(docsDir)) continue;
-
-        const docs = scanDocsDir(docsDir);
-        if (docs.length > 0) {
-          scopes.push({ scope: 'idea', scope_id: `${state}/${ideaSlug}`, docs });
-        }
+    for (const { ideaSlug, docsDir, state, legacy } of enumerateIdeaDocsDirs(cwd)) {
+      if (filterId && ideaSlug !== filterId) continue;
+      if (!fs.existsSync(docsDir)) continue;
+      const docs = scanDocsDir(docsDir);
+      if (docs.length > 0) {
+        scopes.push({ scope: 'idea', scope_id: legacy ? `${state}/${ideaSlug}` : ideaSlug, docs });
       }
     }
   }
@@ -928,6 +971,7 @@ module.exports = {
   computeChecksum,
   resolveDocsDir,
   ensureDocsDir,
+  enumerateIdeaDocsDirs,
   extractText,
   updateIndex,
   updateIndexWithNames,

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

@@ -21,6 +21,7 @@ const {
   scanDocsDir,
   updateIndexWithNames,
   updateIndex,
+  enumerateIdeaDocsDirs,
 } = require('./docs.cjs');
 
 // ─── resolveDocsDir Tests ────────────────────────────────────────────────────
@@ -52,13 +53,15 @@ describe('docs', () => {
         `Expected path ending with docs/product, got: ${result}`);
     });
 
-    it('idea scope returns docs path for idea found in pending', () => {
-      // Create the idea file that resolveDocsDir searches for
-      fs.mkdirSync(path.join(tmpDir, 'ideas', 'pending'), { recursive: true });
-      fs.writeFileSync(path.join(tmpDir, 'ideas', 'pending', '001-my-idea.md'), '---\nid: 1\ntitle: "My Idea"\n---\n');
+    it('idea scope returns flat docs path', () => {
+      // Create the flat idea file that resolveDocsDir keys off (idea.path)
+      fs.mkdirSync(path.join(tmpDir, 'ideas'), { recursive: true });
+      fs.writeFileSync(path.join(tmpDir, 'ideas', '001-my-idea.md'), '---\nid: 1\ntitle: "My Idea"\n---\n');
       const result = resolveDocsDir(tmpDir, 'idea', '1');
-      assert.ok(result.includes(path.join('ideas', 'pending', '001-my-idea', 'docs')),
-        `Expected ideas/pending/001-my-idea/docs in path, got: ${result}`);
+      assert.ok(result.includes(path.join('ideas', '001-my-idea', 'docs')),
+        `Expected flat ideas/001-my-idea/docs in path, got: ${result}`);
+      assert.ok(!result.includes(path.join('ideas', 'pending', '001-my-idea')),
+        `Should NOT inject state segment, got: ${result}`);
     });
 
     it('spec scope returns correct path', () => {
@@ -68,6 +71,46 @@ describe('docs', () => {
     });
   });
 
+  // ─── enumerateIdeaDocsDirs (flat + legacy) ─────────────────────────────────
+
+  describe('enumerateIdeaDocsDirs', () => {
+    let tmpDir;
+
+    beforeEach(() => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'dgs-enum-idea-'));
+      tmpDir = fs.realpathSync(tmpDir);
+      initGitRepo(tmpDir);
+    });
+
+    afterEach(() => {
+      resetPaths();
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it('returns both flat and legacy idea docs dirs', () => {
+      // Flat: ideas/001-foo/docs/
+      const flatDocs = path.join(tmpDir, 'ideas', '001-foo', 'docs');
+      fs.mkdirSync(flatDocs, { recursive: true });
+      fs.writeFileSync(path.join(flatDocs, 'a.txt'), 'flat');
+      // Legacy: ideas/pending/002-bar/docs/
+      const legacyDocs = path.join(tmpDir, 'ideas', 'pending', '002-bar', 'docs');
+      fs.mkdirSync(legacyDocs, { recursive: true });
+      fs.writeFileSync(path.join(legacyDocs, 'b.txt'), 'legacy');
+
+      const dirs = enumerateIdeaDocsDirs(tmpDir);
+
+      const flat = dirs.find(d => d.ideaSlug === '001-foo');
+      assert.ok(flat, 'flat idea docs dir should be enumerated');
+      assert.equal(flat.legacy, false);
+      assert.equal(flat.state, null);
+
+      const legacy = dirs.find(d => d.ideaSlug === '002-bar');
+      assert.ok(legacy, 'legacy idea docs dir should be enumerated');
+      assert.equal(legacy.legacy, true);
+      assert.equal(legacy.state, 'pending');
+    });
+  });
+
   // ─── scanDocsDir directory resilience ──────────────────────────────────────
 
   describe('scanDocsDir', () => {

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

@@ -12,6 +12,7 @@ const { parseReposMd, validateReposMdEager } = require('./repos.cjs');
 const { getCadence, pullAll } = require('./sync.cjs');
 const { detectQuickMode, generateQuickId, getActiveQuick } = require('./quick.cjs');
 const { listProjectsReadonly } = require('./projects.cjs');
+const { resolveMilestoneSlug } = require('./worktrees.cjs');
 
 /**
  * Safely resolve the current git author string.
@@ -252,6 +253,10 @@ function cmdInitExecutePhase(cwd, phase, raw) {
     : null;
   const phase_req_ids = (reqExtracted && reqExtracted !== 'TBD') ? reqExtracted : null;
 
+  // Multi-project determination for the structural milestone slug's project
+  // prefix: only prefix with <project> when more than one ACTIVE project exists.
+  const multiProject = listProjectsReadonly(cwd).projects.length > 1;
+
   // Resolve {project} in a branch template — errors if template uses {project} but current_project is not set
   function resolveProjectInTemplate(template, currentProject) {
     if (template.includes('{project}')) {
@@ -301,13 +306,13 @@ function cmdInitExecutePhase(cwd, phase, raw) {
       if (resolved.error) return resolved.error;
       return resolved.value
         .replace('{milestone}', milestone.version)
-        .replace('{slug}', generateSlugInternal(milestone.name) || 'milestone');
+        .replace('{slug}', resolveMilestoneSlug(cwd, ctx.current_project, { version: milestone.version, name: milestone.name, multiProject }));
     })(),
 
     // Milestone info
     milestone_version: milestone.version,
     milestone_name: milestone.name,
-    milestone_slug: generateSlugInternal(milestone.name),
+    milestone_slug: resolveMilestoneSlug(cwd, ctx.current_project, { version: milestone.version, name: milestone.name, multiProject }),
 
     // File existence
     state_exists: ctx.root ? pathExistsInternal(cwd, path.join(ctx.root, 'STATE.md')) : false,
@@ -1045,6 +1050,7 @@ function cmdInitMilestoneOp(cwd, raw, workflow) {
   const milestone = getMilestoneInfo(cwd);
   const planRootRel = path.relative(cwd, getPlanningRoot(cwd)) || '.';
   const cadence = getCadence(workflow || 'complete-milestone');
+  const multiProject = listProjectsReadonly(cwd).projects.length > 1;
 
   // Count phases (project-qualified)
   let phaseCount = 0;
@@ -1089,7 +1095,7 @@ function cmdInitMilestoneOp(cwd, raw, workflow) {
     // Current milestone
     milestone_version: milestone.version,
     milestone_name: milestone.name,
-    milestone_slug: generateSlugInternal(milestone.name),
+    milestone_slug: resolveMilestoneSlug(cwd, ctx.current_project, { version: milestone.version, name: milestone.name, multiProject }),
 
     // Phase counts
     phase_count: phaseCount,

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

@@ -1177,7 +1177,10 @@ describe('branch_name with {project} resolution', () => {
     });
     try {
       const result = runInit(fixture.cwd, 'execute-phase 3');
-      assert.equal(result.branch_name, 'dgs/myapp/v1.0-milestone');
+      // Structural slug now embeds the version segment (v1.0 -> v1-0) so a
+      // placeholder/default 'milestone' name no longer collapses to a bare
+      // milestone/milestone branch (branch-name collision fix).
+      assert.equal(result.branch_name, 'dgs/myapp/v1.0-v1-0-milestone');
     } finally {
       fixture.cleanup();
     }
@@ -1196,7 +1199,7 @@ describe('branch_name with {project} resolution', () => {
     });
     try {
       const result = runInit(fixture.cwd, 'execute-phase 1');
-      assert.equal(result.branch_name, 'dgs/checkout/v1.0-milestone');
+      assert.equal(result.branch_name, 'dgs/checkout/v1.0-v1-0-milestone');
     } finally {
       fixture.cleanup();
     }
@@ -1216,7 +1219,7 @@ describe('branch_name with {project} resolution', () => {
     });
     try {
       const result = runInit(fixture.cwd, 'execute-phase 3');
-      assert.equal(result.branch_name, 'dgs/myapp/v1.0-milestone');
+      assert.equal(result.branch_name, 'dgs/myapp/v1.0-v1-0-milestone');
     } finally {
       fixture.cleanup();
     }
@@ -1240,6 +1243,61 @@ describe('branch_name with {project} resolution', () => {
   });
 });
 
+// ─── milestone_slug resolution (stamped / legacy fallback) ───────────────────
+
+describe('milestone_slug resolution via resolveMilestoneSlug', () => {
+  // ROADMAP carries an in-progress marker so version+name are deterministic:
+  // 'v25.0' + 'Cool Thing' -> composed slug 'v25-0-cool-thing';
+  // old bare-name slug 'cool-thing'.
+  const roadmap = '# Roadmap\n\n- 🚧 **v25.0 Cool Thing** — Phases 1-2 (in progress)\n';
+
+  function fixtureWithWorktrees(worktrees) {
+    return createFixture({
+      'config.json': JSON.stringify({ current_project: 'test-project' }),
+      'config.local.json': JSON.stringify({
+        current_project: 'test-project',
+        projects: { 'test-project': { worktrees } },
+      }),
+      'PROJECTS.md': '# Projects\n\n| Project | Status |\n|---------|--------|\n| test-project | Active |\n',
+      'REPOS.md': '# Repos\n\n| Name | Path |\n|------|------|\n',
+      'projects/test-project/STATE.md': '# State',
+      'projects/test-project/ROADMAP.md': roadmap,
+      'projects/test-project/REQUIREMENTS.md': '# Requirements',
+      'projects/test-project/PROJECT.md': '# Project',
+    });
+  }
+
+  it('returns the stamped NEW composed slug when an entry exists under it', () => {
+    const fixture = fixtureWithWorktrees({ 'v25-0-cool-thing': { type: 'milestone', milestone_slug: 'v25-0-cool-thing', slug_formula: 'v2' } });
+    try {
+      const result = runInit(fixture.cwd, 'milestone-op');
+      assert.equal(result.milestone_slug, 'v25-0-cool-thing');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('LEGACY FALLBACK: returns the OLD bare-name slug when only an old-style entry exists (no orphaning)', () => {
+    const fixture = fixtureWithWorktrees({ 'cool-thing': { type: 'milestone' } });
+    try {
+      const result = runInit(fixture.cwd, 'milestone-op');
+      assert.equal(result.milestone_slug, 'cool-thing', 'pre-upgrade in-flight milestone must still resolve');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('returns the NEW composed slug when neither entry exists (fresh)', () => {
+    const fixture = fixtureWithWorktrees({});
+    try {
+      const result = runInit(fixture.cwd, 'milestone-op');
+      assert.equal(result.milestone_slug, 'v25-0-cool-thing');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+});
+
 // ─── Backward Compatibility ──────────────────────────────────────────────────
 
 // ─── Sync Pull: needs_pull field tests ────────────────────────────────────────