@ktpartners/dgs-platform 3.3.0 → 3.4.1

package/CHANGELOG.md

@@ -8,6 +8,38 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [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
+- **`execGit` works on Windows** — `bin/lib/core.cjs:execGit` previously POSIX-quoted args (`'arg with spaces'`) then ran them through `execSync`'s shell. On Windows `execSync` invokes `cmd.exe`, which treats single quotes as literal characters — so `git commit -m 'docs(88): create phase plan'` was tokenised into separate args and git interpreted the trailing words as pathspecs. Every multi-word commit message broke on Windows, affecting essentially every DGS command that commits (`/dgs:fast`, `/dgs:quick`, `/dgs:execute-phase`, `/dgs:complete-quick`, the v1→v2 migration self-commit, etc.). Replaced with `execFileSync('git', args, ...)` which bypasses the shell entirely on both platforms — no quoting needed since `args` is already an array. Preserved the existing `{exitCode, stdout, stderr}` return shape and `.trim()` behaviour. Added round-trip regression test in `tests/core.test.cjs` that asserts a message with spaces, parens, colon, ampersand, and percent (`docs(88): create phase plan & 100% coverage`) survives `init`→`commit`→`log` verbatim (quick-260526-dip).
+- **`execGitWithTimeout` works on Windows** — `bin/lib/sync.cjs:execGitWithTimeout` was a fork of `execGit` (added a `timeout` option per its `(NOT execGit)` comment) and inherited the identical POSIX-quoting bug. Affected `/dgs:sync` pre-flight checks across every registered repo (`remote`, `rev-parse --abbrev-ref HEAD`, etc.). Same fix: `execFileSync('git', args, { ..., timeout: timeoutMs })`. Preserved the `isTimeout`/`isAuth` error classification in the catch block (quick-260526-e5l).
+- **`hasCodeFiles` no longer shells out** — `bin/lib/init.cjs` used `execSync('find . -maxdepth 3 \\( -name "*.ts" -o ... \\) | grep -v node_modules | head -5')` during `/dgs:new-project` to detect existing source files for template selection. `find`/`grep`/`head` aren't on Windows by default and the bash-style `\\(` escaping is shell-specific; the catch-block silently fell back to `hasCode = false`, producing wrong init heuristics on Windows. Extracted a pure-Node `hasCodeFiles(cwd)` helper using `fs.readdirSync({ withFileTypes: true })` — depth 3, skips `node_modules` and `.git`, early-exits at 5 matches across `.ts/.js/.py/.go/.rs/.swift/.java`. Exported for testability; added unit tests in `tests/init.test.cjs` covering depth-3 boundary, depth-4 cap, `node_modules`/`.git` skip, the 7-extension matrix, and nonexistent paths (quick-260526-e5l).
+- **`~/` tilde expansion works on Windows** — `bin/lib/verify.cjs` resolved `~/path` canonical_refs via `path.join(process.env.HOME || '', cleanRef.slice(2))`. On Windows `HOME` is unset, so `|| ''` produced a relative path and `cmdVerifyReferences` falsely reported the ref as missing. Replaced with `path.join(os.homedir(), cleanRef.slice(2))` — `os.homedir()` returns `USERPROFILE` on Windows and `HOME` elsewhere. Added a sentinel-file test in `tests/verify.test.cjs` that creates a real file under `os.homedir()` and verifies the `~/` resolution finds it (quick-260526-e5l).
+- **PDF/DOCX/XLSX extraction no longer shells out** — `bin/lib/docs.cjs` ran the async `pdf-parse`/`mammoth`/`exceljs` libs in a sync context via three near-identical `` execSync(`node -e ${JSON.stringify(script)}`) `` sites. Although `JSON.stringify`'s double quotes are cmd.exe-friendly, this path (a) triggered cmd.exe %-variable expansion on filenames containing `%`, and (b) pushed the script body toward cmd.exe's 8191-char command-line limit on long inputs. Replaced all three with `spawnSync('node', ['-e', script], { shell: false, ... })` — same script body, no shell at all. Added structural source-grep guard in `tests/docs.test.cjs` (`!/execSync\(\s*\`node -e/.test(src)`) so the bug pattern can't regress (quick-260526-e5l).
+
 ## [3.3.0] - 2026-05-15
 
 ### Added

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/core.cjs

@@ -4,7 +4,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { execSync } = require('child_process');
+const { execSync, execFileSync } = require('child_process');
 const { getPlanningRoot, isV2Install, PROJECTS_DIR } = require('./paths.cjs');
 
 // ─── Path helpers ────────────────────────────────────────────────────────────
@@ -181,11 +181,7 @@ function isGitIgnored(cwd, targetPath) {
 
 function execGit(cwd, args) {
   try {
-    const escaped = args.map(a => {
-      if (/^[a-zA-Z0-9._\-/=:@]+$/.test(a)) return a;
-      return "'" + a.replace(/'/g, "'\\''") + "'";
-    });
-    const stdout = execSync('git ' + escaped.join(' '), {
+    const stdout = execFileSync('git', args, {
       cwd,
       stdio: 'pipe',
       encoding: 'utf-8',

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.
@@ -14,9 +14,10 @@
 const fs = require('fs');
 const path = require('path');
 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 ──────────────────────────────────────────────────────────────
 
@@ -84,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');
@@ -109,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 ────────────────────────────────────────────────────────
 
 /**
@@ -129,10 +190,11 @@ function extractText(filePath, ext) {
       try {
         const pdfParse = require('pdf-parse');
         const buffer = fs.readFileSync(filePath);
-        // pdf-parse returns a promise; we use execSync workaround for sync context
-        // Instead, we'll use a sync extraction approach
+        // pdf-parse returns a promise; run it in a child node process via
+        // spawnSync so the parent can stay synchronous. spawnSync (not
+        // execSync with a shell-built command) is required on Windows where
+        // cmd.exe applies different quoting rules.
         let result = null;
-        const { execSync } = require('child_process');
         const script = `
           const pdfParse = require('pdf-parse');
           const fs = require('fs');
@@ -143,12 +205,15 @@ function extractText(filePath, ext) {
             process.stdout.write(JSON.stringify({ error: err.message }));
           });
         `;
-        const out = execSync(`node -e ${JSON.stringify(script)}`, {
+        const r = spawnSync('node', ['-e', script], {
           encoding: 'utf-8',
           timeout: 30000,
           stdio: ['pipe', 'pipe', 'pipe'],
         });
-        result = JSON.parse(out.trim());
+        if (r.status !== 0) {
+          return { text: null, error: `PDF extraction failed: ${r.stderr || r.error?.message || 'unknown'}` };
+        }
+        result = JSON.parse(r.stdout.trim());
         if (result.error) {
           return { text: null, error: result.error };
         }
@@ -160,7 +225,6 @@ function extractText(filePath, ext) {
 
     if (ext === '.xlsx') {
       try {
-        const { execSync } = require('child_process');
         const script = `
           const ExcelJS = require('exceljs');
           const workbook = new ExcelJS.Workbook();
@@ -178,11 +242,15 @@ function extractText(filePath, ext) {
             process.stdout.write(JSON.stringify({ error: err.message }));
           });
         `;
-        const out = execSync(`node -e ${JSON.stringify(script)}`, {
+        const r = spawnSync('node', ['-e', script], {
           encoding: 'utf-8',
           timeout: 30000,
-        }).trim();
-        const parsed = JSON.parse(out);
+          stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        if (r.status !== 0) {
+          return { text: null, error: `XLSX extraction failed: ${r.stderr || r.error?.message || 'unknown'}` };
+        }
+        const parsed = JSON.parse(r.stdout.trim());
         if (parsed.error) return { text: null, error: parsed.error };
         return { text: parsed.text, error: null };
       } catch (e) {
@@ -202,7 +270,6 @@ function extractText(filePath, ext) {
     if (ext === '.docx') {
       try {
         const mammoth = require('mammoth');
-        const { execSync } = require('child_process');
         const script = `
           const mammoth = require('mammoth');
           mammoth.extractRawText({ path: ${JSON.stringify(filePath)} })
@@ -213,12 +280,15 @@ function extractText(filePath, ext) {
               process.stdout.write(JSON.stringify({ error: err.message }));
             });
         `;
-        const out = execSync(`node -e ${JSON.stringify(script)}`, {
+        const r = spawnSync('node', ['-e', script], {
           encoding: 'utf-8',
           timeout: 30000,
           stdio: ['pipe', 'pipe', 'pipe'],
         });
-        const result = JSON.parse(out.trim());
+        if (r.status !== 0) {
+          return { text: null, error: `DOCX extraction failed: ${r.stderr || r.error?.message || 'unknown'}` };
+        }
+        const result = JSON.parse(r.stdout.trim());
         if (result.error) {
           return { text: null, error: result.error };
         }
@@ -611,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 });
       }
     }
   }
@@ -918,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', () => {