@ktpartners/dgs-platform 3.5.1 → 3.5.3

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

@@ -8,7 +8,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { safeReadFile, getProjectFolders, output, error, getProjectDir } = require('./core.cjs');
+const { safeReadFile, getProjectFolders, output, error, getProjectDir, isValidMilestoneVersion } = require('./core.cjs');
 const { parseProjectsMd, readProjectState } = require('./projects.cjs');
 const { parseReposMd, resolveFileToRepo } = require('./repos.cjs');
 
@@ -32,18 +32,28 @@ function scanProjectPlanFiles(cwd, slug) {
   const phasesDir = path.join(getProjectDir(cwd, slug), 'phases');
   const results = [];
 
+  // Per-milestone versioned layout: descend a single vN.N child dir if present
+  // (phases/<version>/NN-slug). Detect via core.isValidMilestoneVersion — no
+  // parallel version regex. No version child → stay flat (back-compat).
+  let scanRoot = phasesDir;
   try {
-    const phaseDirs = fs.readdirSync(phasesDir, { withFileTypes: true })
+    const kids = fs.readdirSync(scanRoot, { withFileTypes: true });
+    const vd = kids.find(e => e.isDirectory() && isValidMilestoneVersion(e.name));
+    if (vd) scanRoot = path.join(scanRoot, vd.name);
+  } catch {}
+
+  try {
+    const phaseDirs = fs.readdirSync(scanRoot, { withFileTypes: true })
       .filter(e => e.isDirectory())
       .map(e => e.name);
 
     // Exclude archived phase directories
     const activePhaseDirs = excludeArchivedPhases(
-      phaseDirs.map(d => path.join(phasesDir, d))
+      phaseDirs.map(d => path.join(scanRoot, d))
     ).map(d => path.basename(d));
 
     for (const phaseDir of activePhaseDirs) {
-      const fullPhaseDir = path.join(phasesDir, phaseDir);
+      const fullPhaseDir = path.join(scanRoot, phaseDir);
       let files;
       try {
         files = fs.readdirSync(fullPhaseDir)

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

@@ -85,6 +85,19 @@ describe('scanProjectPlanFiles', () => {
     assert.deepStrictEqual(result[0].files, ['web-app/src/app.js', 'web-app/src/index.js']);
   });
 
+  it('descends versioned phases/<version>/ layout (260628-p59)', () => {
+    createProject(tmpDir, 'project-a');
+    // Plan lives one level deeper, under phases/v25.0/01-setup/
+    createPlanFile(tmpDir, 'project-a', 'v25.0/01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['web-app/src/index.js'], repos: ['web-app'] },
+    ]);
+    const result = scanProjectPlanFiles(tmpDir, 'project-a');
+    assert.strictEqual(result.length, 1, 'plan under phases/v25.0/ must be found');
+    assert.deepStrictEqual(result[0].repos, ['web-app']);
+    assert.deepStrictEqual(result[0].files, ['web-app/src/index.js']);
+    assert.strictEqual(result[0].plan, '01-setup/01-01-PLAN.md');
+  });
+
   it('handles plans with multiple tasks', () => {
     createProject(tmpDir, 'project-a');
     createPlanFile(tmpDir, 'project-a', '01-setup', '01-01-PLAN.md', [

package/deliver-great-systems/bin/lib/package-scan-report.cjs

@@ -25,6 +25,7 @@ const fs = require('fs');
 const path = require('path');
 const { getPlanningRoot } = require('./paths.cjs');
 const { getLocalConfigPath } = require('./config.cjs');
+const { isValidMilestoneVersion } = require('./core.cjs');
 
 // ─── Canonical frontmatter constants ─────────────────────────────────────────
 // Every findings[] entry emitted by this module carries these two constant
@@ -886,6 +887,24 @@ function _resolveReportPath(cwd, opts) {
         const phaseEntries = fs.readdirSync(phasesDir, { withFileTypes: true });
         for (const phEnt of phaseEntries) {
           if (!phEnt.isDirectory()) continue;
+          // Per-milestone versioned layout: the immediate child is a vN.N dir, so
+          // the active phase lives one level deeper (phases/<version>/NN-slug).
+          // Detect via core.isValidMilestoneVersion (no parallel version regex)
+          // and match the active phase among the version dir's children.
+          if (isValidMilestoneVersion(phEnt.name)) {
+            const versionDir = path.join(phasesDir, phEnt.name);
+            let candidates;
+            try { candidates = fs.readdirSync(versionDir, { withFileTypes: true }); } catch { continue; }
+            for (const cand of candidates) {
+              if (!cand.isDirectory()) continue;
+              if (cand.name === activeContext) {
+                const cm = cand.name.match(/^(\d+)/);
+                const cprefix = cm ? cm[1] : cand.name;
+                return path.join(versionDir, cand.name, cprefix + '-PACKAGE-SCAN.md');
+              }
+            }
+            continue;
+          }
           if (phEnt.name === activeContext) {
             const m = phEnt.name.match(/^(\d+)/);
             const prefix = m ? m[1] : phEnt.name;

package/deliver-great-systems/bin/lib/package-scan-report.test.cjs

@@ -494,6 +494,24 @@ describe('_resolveReportPath — tier 1 (active phase)', () => {
     }
   });
 
+  test('active_context resolves under versioned phases/<version>/ layout (260628-p59)', () => {
+    tmpDir = setupPlanningRoot({
+      local: {
+        current_project: 'gsd',
+        execution: { active_context: '03-foo' },
+      },
+    });
+    // Phase dir lives one level deeper, under phases/v25.0/03-foo
+    const versionedPhaseDir = path.join(tmpDir, 'projects', 'gsd', 'phases', 'v25.0', '03-foo');
+    fs.mkdirSync(versionedPhaseDir, { recursive: true });
+    try {
+      const resolved = _resolveReportPath(tmpDir, {});
+      assert.equal(resolved, path.join(versionedPhaseDir, '03-PACKAGE-SCAN.md'));
+    } finally {
+      cleanup(tmpDir);
+    }
+  });
+
   test('active_context points at a phase that does NOT exist → falls through', () => {
     tmpDir = setupPlanningRoot({
       local: {

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

@@ -381,14 +381,22 @@ function cmdPhaseAdd(cwd, description, raw) {
     updatedContent = content + phaseEntry;
   }
 
-  // Update milestone summary range (e.g., "Phases 124-128" -> "Phases 124-129")
-  const rangePattern = /Phases\s+(\d+)-(\d+)\s*\(in progress\)/;
+  // Update milestone summary range. Handles both the legacy non-namespaced form
+  // ("Phases 124-128" -> "Phases 124-129") and the per-milestone-namespaced form
+  // ("Phases v25.1/1-9" -> "Phases v25.1/1-10"). In the live namespaced layout the
+  // START endpoint carries the `vX.Y/` prefix while the END endpoint is BARE
+  // (e.g. start "v25.1/1", end "9"), so the prefix is derived from whichever
+  // endpoint carries it; the START (rangeMatch[1]) is preserved verbatim and the
+  // rebuilt END reuses the END endpoint's own prefix (empty in the live form).
+  const rangePattern = /Phases\s+((?:v\d+\.\d+\/)?\d+)\s*-\s*((?:v\d+\.\d+\/)?\d+)\s*\(in progress\)/i;
   const rangeMatch = updatedContent.match(rangePattern);
   if (rangeMatch) {
-    const rangeEnd = parseInt(rangeMatch[2], 10);
+    const endRaw = rangeMatch[2];                          // e.g. "9" (bare) or "v25.1/9"
+    const prefix = (endRaw.match(/^v\d+\.\d+\//) || [''])[0];
+    const rangeEnd = parseInt(endRaw.replace(/^v\d+\.\d+\//, ''), 10);
     if (newPhaseNum > rangeEnd) {
       updatedContent = updatedContent.replace(rangePattern,
-        `Phases ${rangeMatch[1]}-${newPhaseNum} (in progress)`);
+        `Phases ${rangeMatch[1]}-${prefix}${newPhaseNum} (in progress)`);
     }
   }
 

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

@@ -585,3 +585,72 @@ describe('cmdPhaseInitVersionedDir (NUM-02 versioned write path)', () => {
     }
   });
 });
+
+describe('cmdPhaseAdd milestone-summary range bump', () => {
+  let phase;
+
+  beforeEach(() => {
+    resetPaths();
+    delete require.cache[require.resolve('./phase.cjs')];
+    phase = require('./phase.cjs');
+  });
+
+  afterEach(() => {
+    resetPaths();
+  });
+
+  it('bumps a namespaced "Phases v25.1/1-9 (in progress)" range to v25.1/1-10, preserving the prefix', () => {
+    // maxPhase resolves to 9 from the `### Phase 9:` heading → newPhaseNum=10.
+    const roadmap = `# Roadmap
+
+- 🚧 **v25.1 add-prs** -- Phases v25.1/1-9 (in progress)
+
+## Phases
+
+### Phase 9: Ninth
+**Goal:** done
+
+---
+`;
+    const fixture = createFixture({ 'config.json': JSON.stringify({}), 'ROADMAP.md': roadmap });
+    try {
+      captureStdout(() => phase.cmdPhaseAdd(fixture.cwd, 'Tenth phase', false));
+      const updated = fs.readFileSync(path.join(fixture.cwd, 'ROADMAP.md'), 'utf-8');
+      assert.ok(
+        updated.includes('Phases v25.1/1-10 (in progress)'),
+        `expected namespaced bump to v25.1/1-10, got:\n${updated}`
+      );
+      // Prefix preserved on the START endpoint; END stays bare (no v25.1/ on the 10).
+      assert.ok(!/Phases v25\.1\/1-v25\.1\/10/.test(updated), 'END endpoint must stay bare');
+      assert.ok(!updated.includes('Phases v25.1/1-9 (in progress)'), 'old range must be gone');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('bumps a legacy non-namespaced "Phases 124-129 (in progress)" range to 124-130 (regression)', () => {
+    const roadmap = `# Roadmap
+
+- 🚧 **v19.0 Git Worktrees** -- Phases 124-129 (in progress)
+
+## Phases
+
+### Phase 129: One-twenty-nine
+**Goal:** done
+
+---
+`;
+    const fixture = createFixture({ 'config.json': JSON.stringify({}), 'ROADMAP.md': roadmap });
+    try {
+      captureStdout(() => phase.cmdPhaseAdd(fixture.cwd, 'One thirty', false));
+      const updated = fs.readFileSync(path.join(fixture.cwd, 'ROADMAP.md'), 'utf-8');
+      assert.ok(
+        updated.includes('Phases 124-130 (in progress)'),
+        `expected legacy bump to 124-130, got:\n${updated}`
+      );
+      assert.ok(!updated.includes('Phases 124-129 (in progress)'), 'old range must be gone');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+});

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

@@ -8,7 +8,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { safeReadFile, getProjectFolders, generateSlugInternal, isV2Install, output, error, loadConfig, getProjectDir } = require('./core.cjs');
+const { safeReadFile, getProjectFolders, generateSlugInternal, isV2Install, output, error, loadConfig, getProjectDir, isValidMilestoneVersion } = require('./core.cjs');
 const { writeConfigField } = require('./config.cjs');
 const { getPlanningRoot } = require('./paths.cjs');
 
@@ -126,13 +126,23 @@ function scanProjectReposTags(cwd, slug) {
   const phasesDir = path.join(getProjectDir(cwd, slug), 'phases');
   const allRepos = new Set();
 
+  // Per-milestone versioned layout: descend a single vN.N child dir if present
+  // (phases/<version>/NN-slug). Detect via core.isValidMilestoneVersion — no
+  // parallel version regex. No version child → stay flat (back-compat).
+  let scanRoot = phasesDir;
   try {
-    const phaseDirs = fs.readdirSync(phasesDir, { withFileTypes: true })
+    const kids = fs.readdirSync(scanRoot, { withFileTypes: true });
+    const vd = kids.find(e => e.isDirectory() && isValidMilestoneVersion(e.name));
+    if (vd) scanRoot = path.join(scanRoot, vd.name);
+  } catch {}
+
+  try {
+    const phaseDirs = fs.readdirSync(scanRoot, { withFileTypes: true })
       .filter(e => e.isDirectory())
       .map(e => e.name);
 
     for (const phaseDir of phaseDirs) {
-      const fullPhaseDir = path.join(phasesDir, phaseDir);
+      const fullPhaseDir = path.join(scanRoot, phaseDir);
       let planFiles;
       try {
         planFiles = fs.readdirSync(fullPhaseDir)

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

@@ -320,6 +320,14 @@ describe('scanProjectReposTags', () => {
     const repos = scanProjectReposTags(tmpDir, 'proj');
     assert.deepStrictEqual(repos, []);
   });
+
+  it('descends versioned phases/<version>/ layout (260628-p59)', () => {
+    createProjectManually(tmpDir, 'proj', '# State\n');
+    // Plan lives one level deeper, under phases/v25.0/01-setup/
+    createPlanFile(tmpDir, 'proj', 'v25.0/01-setup', '01-01-PLAN.md', '<repos>server</repos>\n');
+    const repos = scanProjectReposTags(tmpDir, 'proj');
+    assert.deepStrictEqual(repos, ['server']);
+  });
 });
 
 // ─── regenerateProjectsMd ───────────────────────────────────────────────────

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

@@ -188,6 +188,20 @@ function cmdRoadmapAnalyze(cwd, raw) {
       version: 'v' + mMatch[2],
     });
   }
+  // Bold-line single-milestone fallback: a `**Milestone:** vX.Y` roadmap has no
+  // `## vX.Y` heading, so the scan above yields []. Fire ONLY when the heading
+  // scan produced zero milestones — the `milestones.length === 0` guard is the
+  // over-match gate, so any roadmap that already has `##` version headings (incl.
+  // the `## Active Milestone:` ad-hoc heading, already matched above) ignores it.
+  if (milestones.length === 0) {
+    const bold = content.match(/^\*\*Milestone:\*\*\s*(v\d+\.\d+)([^\n]*)/im);
+    if (bold) {
+      milestones.push({
+        heading: ('Milestone: ' + bold[1] + bold[2]).trim(),
+        version: bold[1],
+      });
+    }
+  }
 
   // Find current and next phase
   const currentPhase = phases.find(p => p.disk_status === 'planned' || p.disk_status === 'partial') || null;

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

@@ -0,0 +1,86 @@
+/**
+ * Tests for roadmap.cjs::cmdRoadmapAnalyze milestone enumeration.
+ *
+ * Focus: the bold-line single-milestone fallback (`**Milestone:** vX.Y`) that
+ * fires ONLY when the `## vX.Y` heading scan yields zero milestones, gated by
+ * `milestones.length === 0` so it never double-counts a heading roadmap.
+ *
+ * Invokes the dgs-tools.cjs CLI via execSync against isolated temp fixtures
+ * (mirrors init.test.cjs's CLI-invocation style).
+ */
+
+const { describe, it, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const { execSync } = require('child_process');
+const path = require('path');
+
+const { createFixture } = require('./test-helpers.cjs');
+
+// Path to CLI entry point
+const CLI = path.resolve(__dirname, '..', 'dgs-tools.cjs');
+
+/**
+ * Run `dgs-tools roadmap analyze --raw` in a fixture and return parsed JSON.
+ */
+function runAnalyze(cwd) {
+  const stdout = execSync(`node "${CLI}" roadmap analyze --raw`, {
+    cwd,
+    encoding: 'utf-8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  return JSON.parse(stdout.trim());
+}
+
+describe('cmdRoadmapAnalyze milestone enumeration', () => {
+  let fixture;
+
+  afterEach(() => {
+    if (fixture) fixture.cleanup();
+  });
+
+  // Single-milestone roadmap whose version lives only in the title + bold line —
+  // there is NO `## vX.Y` heading, so the heading scan yields [].
+  const BOLD_LINE_ROADMAP = `# Roadmap: Tenant data-quality metrics in Admin UI (v30.1)
+
+**Milestone:** v30.1 — Tenant data-quality metrics in Admin UI
+
+## Overview
+
+Single-milestone roadmap.
+
+### Phase 1: Metrics schema
+**Goal:** Define metrics tables
+
+### Phase 2: Admin UI surface
+**Goal:** Surface metrics in admin
+`;
+
+  // Classic multi-milestone heading roadmap WITH a stray bold line: the heading
+  // scan enumerates the `## vX.Y` headings; the bold fallback must stay inert.
+  const HEADING_ROADMAP = `# Roadmap
+
+**Milestone:** v9.9 — stray bold line that must NOT be enumerated
+
+## v1.0 Foundation
+### Phase 1: Base
+
+## v2.0 Next (In Progress)
+### Phase 2: New
+`;
+
+  it('enumerates a bold-line-only roadmap (>=1 milestone, correct version)', () => {
+    fixture = createFixture({ 'config.json': JSON.stringify({}), 'ROADMAP.md': BOLD_LINE_ROADMAP });
+    const result = runAnalyze(fixture.cwd);
+    assert.ok(result.milestones.length >= 1, 'expected at least one milestone');
+    assert.equal(result.milestones[0].version, 'v30.1');
+  });
+
+  it('still enumerates a `## vX.Y` heading roadmap via headings (bold fallback inert, no double-count)', () => {
+    fixture = createFixture({ 'config.json': JSON.stringify({}), 'ROADMAP.md': HEADING_ROADMAP });
+    const result = runAnalyze(fixture.cwd);
+    const versions = result.milestones.map(m => m.version);
+    assert.deepEqual(versions, ['v1.0', 'v2.0']);
+    // The stray bold line (v9.9) was NOT enumerated — the length===0 gate held.
+    assert.ok(!versions.includes('v9.9'), 'stray bold line must not be enumerated');
+  });
+});

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

@@ -161,8 +161,10 @@ function parseFrontmatter(content) {
 // ─── Content Scanners ───────────────────────────────────────────────────────
 
 /**
- * Scan ideas directories for searchable idea files.
- * Scans ideas/{pending,done,rejected}/ for .md files.
+ * Scan ideas for searchable idea files — flat-first.
+ * Reads flat ideas/*.md deriving `state` from frontmatter.status (mirror
+ * scanSpecs / cmdIdeasList). Legacy ideas/{pending,done,rejected}/ subdirs are
+ * an existence-gated dedup fallback so back-compat installs still surface.
  *
  * @param {string} cwd - Working directory
  * @param {object} options - { include_rejected, tags }
@@ -172,12 +174,60 @@ function scanIdeas(cwd, options) {
   const results = [];
   const planRoot = getPlanningRoot(cwd);
   const planRootRel = path.relative(cwd, planRoot) || '.';
-  const states = options.include_rejected
+  const includeRejected = !!options.include_rejected;
+  const seenIds = new Set();
+
+  // Tag filter: if tags option set, idea must have at least one matching tag (OR logic).
+  function tagMatches(tags) {
+    if (!options.tags) return true;
+    const filterTags = options.tags.split(',').map(t => t.trim().toLowerCase());
+    const ideaTags = tags.map(t => t.toLowerCase());
+    return filterTags.some(ft => ideaTags.includes(ft));
+  }
+
+  // Flat-first scan: ideas/*.md (excluding subdirs), state from frontmatter.status.
+  const flatDir = path.join(planRoot, 'ideas');
+  let flatFiles;
+  try {
+    flatFiles = fs.readdirSync(flatDir).filter(f => f.endsWith('.md')
+      && !fs.statSync(path.join(flatDir, f)).isDirectory());
+  } catch {
+    flatFiles = [];
+  }
+
+  for (const file of flatFiles) {
+    const content = safeReadFile(path.join(flatDir, file));
+    if (!content) continue;
+
+    const { frontmatter, body } = parseFrontmatter(content);
+    const state = frontmatter.status || 'pending';
+    if (!includeRejected && state === 'rejected') continue;
+
+    const tags = frontmatter.tags || [];
+    if (!tagMatches(tags)) continue;
+
+    results.push({
+      type: 'idea',
+      id: frontmatter.id,
+      title: frontmatter.title || file,
+      filePath: path.join(planRootRel, 'ideas', file),
+      state,
+      tags,
+      author: frontmatter.author || '',
+      content: (frontmatter.title || '') + ' ' + body,
+    });
+    if (frontmatter.id !== undefined) seenIds.add(frontmatter.id);
+  }
+
+  // Legacy subdir fallback (existence-gated, deduped by id).
+  const legacyStates = includeRejected
     ? ['pending', 'done', 'rejected']
     : ['pending', 'done'];
 
-  for (const state of states) {
-    const dir = path.join(planRoot, 'ideas', state);
+  for (const dirState of legacyStates) {
+    const dir = path.join(planRoot, 'ideas', dirState);
+    if (!fs.existsSync(dir)) continue;
+
     let files;
     try {
       files = fs.readdirSync(dir).filter(f => f.endsWith('.md'));
@@ -191,26 +241,22 @@ function scanIdeas(cwd, options) {
       if (!content) continue;
 
       const { frontmatter, body } = parseFrontmatter(content);
-      const tags = frontmatter.tags || [];
+      if (frontmatter.id !== undefined && seenIds.has(frontmatter.id)) continue;
 
-      // Tag filter: if tags option set, idea must have at least one matching tag (OR logic)
-      if (options.tags) {
-        const filterTags = options.tags.split(',').map(t => t.trim().toLowerCase());
-        const ideaTags = tags.map(t => t.toLowerCase());
-        const hasMatch = filterTags.some(ft => ideaTags.includes(ft));
-        if (!hasMatch) continue;
-      }
+      const tags = frontmatter.tags || [];
+      if (!tagMatches(tags)) continue;
 
       results.push({
         type: 'idea',
         id: frontmatter.id,
         title: frontmatter.title || file,
-        filePath: path.join(planRootRel, 'ideas', state, file),
-        state,
+        filePath: path.join(planRootRel, 'ideas', dirState, file),
+        state: frontmatter.status || dirState,
         tags,
         author: frontmatter.author || '',
         content: (frontmatter.title || '') + ' ' + body,
       });
+      if (frontmatter.id !== undefined) seenIds.add(frontmatter.id);
     }
   }
 
@@ -553,6 +599,7 @@ function cmdSearch(cwd, query, options, raw) {
 
 module.exports = {
   cmdSearch,
+  scanIdeas,
   fuzzyMatch,
   levenshteinDistance,
   matchesQuery,

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

@@ -0,0 +1,94 @@
+/**
+ * Tests for search.cjs scanIdeas — flat-first idea scanning.
+ *
+ * Verifies that scanIdeas reads the migrated flat layout (ideas/*.md with
+ * `status:` in frontmatter), honours include_rejected, and still surfaces
+ * legacy status-subdir ideas as an existence-gated fallback.
+ */
+
+const { describe, it, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const { createFixture } = require('./test-helpers.cjs');
+const { resetPaths } = require('./paths.cjs');
+const { scanIdeas } = require('./search.cjs');
+
+function ideaContent(id, title, status, tags = []) {
+  const tagsStr = tags.length > 0 ? `[${tags.map(t => `"${t}"`).join(', ')}]` : '[]';
+  return `---\nid: ${id}\ntitle: "${title}"\nstatus: ${status}\ntags: ${tagsStr}\n---\n\n${title} body.\n`;
+}
+
+describe('search scanIdeas (flat-first)', () => {
+  let fixture;
+
+  afterEach(() => {
+    if (fixture) fixture.cleanup();
+    resetPaths();
+  });
+
+  it('finds flat-layout ideas with state derived from frontmatter.status', () => {
+    fixture = createFixture({
+      'ideas/001-alpha.md': ideaContent(1, 'Alpha', 'pending', ['api']),
+      'ideas/002-beta.md': ideaContent(2, 'Beta', 'done', ['ui']),
+    });
+
+    const results = scanIdeas(fixture.cwd, { include_rejected: false });
+    assert.equal(results.length, 2);
+
+    const byId = Object.fromEntries(results.map(r => [r.id, r]));
+    assert.equal(byId[1].state, 'pending');
+    assert.equal(byId[1].title, 'Alpha');
+    assert.equal(byId[2].state, 'done');
+    // filePath is the flat location — no status subdir segment.
+    assert.match(byId[1].filePath, /ideas[\\/]001-alpha\.md$/);
+    assert.ok(!byId[1].filePath.includes('pending'));
+  });
+
+  it('hides rejected flat ideas by default and includes them when requested', () => {
+    fixture = createFixture({
+      'ideas/001-alpha.md': ideaContent(1, 'Alpha', 'pending'),
+      'ideas/009-reject.md': ideaContent(9, 'Rejected idea', 'rejected'),
+    });
+
+    const hidden = scanIdeas(fixture.cwd, { include_rejected: false });
+    assert.equal(hidden.length, 1);
+    assert.equal(hidden[0].id, 1);
+
+    const shown = scanIdeas(fixture.cwd, { include_rejected: true });
+    assert.equal(shown.length, 2);
+    assert.ok(shown.some(r => r.id === 9 && r.state === 'rejected'));
+  });
+
+  it('still finds legacy subdir ideas (back-compat)', () => {
+    fixture = createFixture({
+      'ideas/pending/003-gamma.md': ideaContent(3, 'Gamma', 'pending'),
+    });
+
+    const results = scanIdeas(fixture.cwd, { include_rejected: false });
+    assert.equal(results.length, 1);
+    assert.equal(results[0].id, 3);
+    assert.equal(results[0].state, 'pending');
+    assert.match(results[0].filePath, /ideas[\\/]pending[\\/]003-gamma\.md$/);
+  });
+
+  it('dedupes a flat idea against a legacy subdir copy (by id)', () => {
+    fixture = createFixture({
+      'ideas/003-gamma.md': ideaContent(3, 'Gamma flat', 'pending'),
+      'ideas/pending/003-gamma.md': ideaContent(3, 'Gamma legacy', 'pending'),
+    });
+
+    const results = scanIdeas(fixture.cwd, { include_rejected: false });
+    assert.equal(results.length, 1);
+    assert.equal(results[0].title, 'Gamma flat');
+  });
+
+  it('applies the OR tag filter', () => {
+    fixture = createFixture({
+      'ideas/001-alpha.md': ideaContent(1, 'Alpha', 'pending', ['api']),
+      'ideas/002-beta.md': ideaContent(2, 'Beta', 'pending', ['ui']),
+    });
+
+    const results = scanIdeas(fixture.cwd, { include_rejected: false, tags: 'api' });
+    assert.equal(results.length, 1);
+    assert.equal(results[0].id, 1);
+  });
+});