@entelligentsia/forgecli 0.10.0 → 0.11.2

package/dist/forge-payload/tools/check-structure.cjs

@@ -0,0 +1,344 @@
+#!/usr/bin/env node
+'use strict';
+
+// Forge tool: check-structure
+// Checks that all files listed in structure-manifest.json are present
+// in a project's generated output.
+// Usage: node check-structure.cjs [--strict] [--path <project-root>] [--validate-manifest] [--forge-root <path>]
+//   --path <project-root>  Directory to check against (default: process.cwd())
+//   --strict               Also report files present but NOT in the manifest (extra files)
+//   --validate-manifest    Validate manifest against base-pack source files
+//   --forge-root <path>    Path to the forge/ plugin directory (required with --validate-manifest)
+//
+// Reads .forge/config.json paths.* for directory overrides.
+// Falls back to manifest dir field if config is absent or unparseable.
+//
+// Exit 0: all expected files present (or only extras found without --strict)
+// Exit 1: any missing files detected; also exit 1 if extras found with --strict
+
+const fs = require('fs');
+const path = require('path');
+const { getCommandsSubdir } = require('./lib/paths.cjs');
+
+// ── Per-namespace verification logic ──────────────────────────────────────────
+//
+// Returns { present, missing, extra, total } without calling process.exit.
+// - present: number of expected files found
+// - missing: array of { nsKey, dir, filename }
+// - extra:   array of { nsKey, dir, filename } (populated only when strict=true)
+// - total:   total number of expected files across all namespaces
+
+function checkNamespaces(manifest, projectRoot, options = {}) {
+  const { strict = false, configPaths = null } = options;
+
+  // Resolve config path overrides
+  let resolvedConfigPaths;
+  let projectPrefix = '';
+  if (configPaths !== null) {
+    resolvedConfigPaths = configPaths;
+  } else {
+    resolvedConfigPaths = {};
+    const configFile = path.join(projectRoot, '.forge', 'config.json');
+    if (fs.existsSync(configFile)) {
+      try {
+        const cfg = JSON.parse(fs.readFileSync(configFile, 'utf8'));
+        resolvedConfigPaths = (cfg && cfg.paths) ? cfg.paths : {};
+        projectPrefix = (cfg && cfg.project && cfg.project.prefix)
+          ? getCommandsSubdir(cfg.project.prefix)
+          : '';
+      } catch {
+        // unparseable — use defaults
+      }
+    }
+  }
+
+  let totalPresent = 0;
+  let totalExpected = 0;
+  const allMissing = [];
+  const allExtra = [];
+
+  for (const [nsKey, ns] of Object.entries(manifest.namespaces)) {
+    const logicalKey = ns.logicalKey || nsKey;
+    let resolvedDir = (resolvedConfigPaths[logicalKey] && typeof resolvedConfigPaths[logicalKey] === 'string')
+      ? resolvedConfigPaths[logicalKey]
+      : ns.dir;
+    if (ns.prefixed && projectPrefix) {
+      resolvedDir = resolvedDir + '/' + projectPrefix;
+    }
+    const absDir = path.join(projectRoot, resolvedDir);
+
+    const expected = ns.files || [];
+    totalExpected += expected.length;
+
+    const present = [];
+    const missing = [];
+    for (const filename of expected) {
+      const fullPath = path.join(absDir, filename);
+      if (fs.existsSync(fullPath)) {
+        present.push(filename);
+      } else {
+        missing.push({ nsKey, dir: resolvedDir, filename });
+      }
+    }
+
+    totalPresent += present.length;
+    allMissing.push(...missing);
+
+    if (strict) {
+      if (fs.existsSync(absDir)) {
+        try {
+          const expectedSet = new Set(expected);
+          const found = fs.readdirSync(absDir);
+          for (const f of found) {
+            if (!expectedSet.has(f)) {
+              allExtra.push({ nsKey, dir: resolvedDir, filename: f });
+            }
+          }
+        } catch {}
+      }
+    }
+  }
+
+  return {
+    present: totalPresent,
+    missing: allMissing,
+    extra: allExtra,
+    total: totalExpected,
+  };
+}
+
+// ── Manifest validation against base-pack ──────────────────────────────────────
+//
+// Convention-based reverse mapping: each manifest namespace's dir field maps
+// to a base-pack source directory. For schemas, the source is forgeRoot/schemas/.
+// This function validates that every file in the manifest has a corresponding
+// base-pack source, and vice versa.
+//
+// Returns { manifestOnly, basePackOnly }
+
+function validateManifest(manifest, forgeRoot) {
+  const basePackDir = path.join(forgeRoot, 'init', 'base-pack');
+
+  // Convention-based reverse mapping from manifest dir to base-pack source dir
+  const nsToSourceDir = {
+    personas:  path.join(basePackDir, 'personas'),
+    skills:    path.join(basePackDir, 'skills'),
+    workflows: path.join(basePackDir, 'workflows'),
+    fragments: path.join(basePackDir, 'workflows', '_fragments'),
+    templates: path.join(basePackDir, 'templates'),
+    commands:  path.join(basePackDir, 'commands'),
+    // schemas: not base-pack-sourced — source is forgeRoot/schemas/
+  };
+
+  const manifestOnly = [];  // Files in manifest but not in base-pack
+  const basePackOnly = [];   // Files in base-pack but not in manifest
+
+  for (const [nsKey, ns] of Object.entries(manifest.namespaces)) {
+    // Skip schemas — they ship from forgeRoot/schemas/, not base-pack
+    if (nsKey === 'schemas') continue;
+
+    const sourceDir = nsToSourceDir[nsKey];
+    if (!sourceDir) continue;
+
+    const manifestFiles = new Set(ns.files || []);
+
+    // Read base-pack source directory
+    let basePackFiles = [];
+    try {
+      basePackFiles = fs.readdirSync(sourceDir).filter(f => {
+        // Only include regular files, skip subdirectories (like _fragments under workflows)
+        const stat = fs.statSync(path.join(sourceDir, f));
+        return stat.isFile();
+      });
+    } catch {
+      // Directory doesn't exist — all manifest files are manifestOnly
+      for (const f of manifestFiles) {
+        manifestOnly.push({ nsKey, filename: f, dir: ns.dir });
+      }
+      continue;
+    }
+
+    const basePackFileSet = new Set(basePackFiles);
+
+    // Files in manifest but not in base-pack
+    for (const f of manifestFiles) {
+      if (!basePackFileSet.has(f)) {
+        manifestOnly.push({ nsKey, filename: f, dir: ns.dir });
+      }
+    }
+
+    // Files in base-pack but not in manifest
+    for (const f of basePackFileSet) {
+      if (!manifestFiles.has(f)) {
+        basePackOnly.push({ nsKey, filename: f, dir: ns.dir });
+      }
+    }
+  }
+
+  return { manifestOnly, basePackOnly };
+}
+
+// ── Exports ────────────────────────────────────────────────────────────────────
+
+module.exports = { checkNamespaces, validateManifest };
+
+// ── CLI ────────────────────────────────────────────────────────────────────────
+
+if (require.main === module) {
+try {
+  // ── Parse arguments ──────────────────────────────────────────────────────────
+
+  const argv = process.argv.slice(2);
+  let projectRoot = process.cwd();
+  let strict = false;
+  let validateManifestFlag = false;
+  let forgeRoot = null;
+
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--path' && argv[i + 1]) {
+      projectRoot = path.resolve(argv[++i]);
+    } else if (argv[i] === '--strict') {
+      strict = true;
+    } else if (argv[i] === '--validate-manifest') {
+      validateManifestFlag = true;
+    } else if (argv[i] === '--forge-root' && argv[i + 1]) {
+      forgeRoot = path.resolve(argv[++i]);
+    }
+  }
+
+  // ── Load structure-manifest.json ─────────────────────────────────────────────
+
+  const manifestPath = forgeRoot
+    ? path.join(forgeRoot, 'schemas', 'structure-manifest.json')
+    : path.join(__dirname, '..', 'schemas', 'structure-manifest.json');
+  if (!fs.existsSync(manifestPath)) {
+    process.stderr.write(`× structure-manifest.json not found at ${manifestPath}\n`);
+    process.exit(1);
+  }
+
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch (e) {
+    process.stderr.write(`× Failed to parse structure-manifest.json: ${e.message}\n`);
+    process.exit(1);
+  }
+
+  // ── Validate manifest against base-pack (if requested) ──────────────────────
+
+  if (validateManifestFlag) {
+    if (!forgeRoot) {
+      process.stderr.write('× --validate-manifest requires --forge-root <path>\n');
+      process.exit(1);
+    }
+
+    const { manifestOnly, basePackOnly } = validateManifest(manifest, forgeRoot);
+
+    if (manifestOnly.length > 0) {
+      process.stdout.write('× Files in manifest but absent from base-pack:\n');
+      for (const { nsKey, filename, dir } of manifestOnly) {
+        process.stdout.write(`    × ${dir}/${filename} (namespace: ${nsKey})\n`);
+      }
+    }
+
+    if (basePackOnly.length > 0) {
+      process.stdout.write('△ Files in base-pack but absent from manifest:\n');
+      for (const { nsKey, filename, dir } of basePackOnly) {
+        process.stdout.write(`    △ ${dir}/${filename} (namespace: ${nsKey})\n`);
+      }
+    }
+
+    if (manifestOnly.length === 0 && basePackOnly.length === 0) {
+      process.stdout.write('〇 Manifest and base-pack are in sync.\n');
+    }
+
+    if (manifestOnly.length > 0) {
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+
+  // ── Check namespaces ─────────────────────────────────────────────────────────
+
+  const result = checkNamespaces(manifest, projectRoot, { strict });
+
+  // ── Format output ────────────────────────────────────────────────────────────
+
+  // Group results by namespace for display
+  const byNs = {};
+  for (const m of result.missing) {
+    if (!byNs[m.nsKey]) byNs[m.nsKey] = { present: 0, missing: [], extra: [] };
+    byNs[m.nsKey].missing.push(m.filename);
+  }
+  for (const e of result.extra) {
+    if (!byNs[e.nsKey]) byNs[e.nsKey] = { present: 0, missing: [], extra: [] };
+    byNs[e.nsKey].extra.push(e.filename);
+  }
+
+  // Count present per namespace
+  for (const [nsKey, ns] of Object.entries(manifest.namespaces)) {
+    if (!byNs[nsKey]) byNs[nsKey] = { present: 0, missing: [], extra: [] };
+    const total = (ns.files || []).length;
+    const missingCount = byNs[nsKey].missing.length;
+    byNs[nsKey].present = total - missingCount;
+  }
+
+  const lines = [];
+  let anyMissing = result.missing.length > 0;
+  let anyExtra = result.extra.length > 0;
+
+  for (const [nsKey, ns] of Object.entries(manifest.namespaces)) {
+    const logicalKey = ns.logicalKey || nsKey;
+    const info = byNs[nsKey] || { present: 0, missing: [], extra: [] };
+    const total = (ns.files || []).length;
+    const dir = ns.dir;
+
+    if (info.missing.length === 0 && info.extra.length === 0) {
+      lines.push(`〇 ${dir}/ — ${info.present}/${total} present`);
+    } else {
+      if (info.missing.length > 0) {
+        lines.push(`× ${dir}/ — ${info.present}/${total} present, ${info.missing.length} missing:`);
+        for (const f of info.missing) {
+          lines.push(`    × ${f}`);
+        }
+      }
+      if (info.extra.length > 0) {
+        if (info.missing.length === 0) {
+          lines.push(`△ ${dir}/ — ${info.present}/${total} present, ${info.extra.length} extra:`);
+        }
+        for (const f of info.extra) {
+          lines.push(`    △ ${f} (not in manifest)`);
+        }
+      }
+    }
+  }
+
+  for (const line of lines) {
+    process.stdout.write(line + '\n');
+  }
+
+  if (!anyMissing && !anyExtra) {
+    process.stdout.write(`〇 Structure check: all ${result.total} expected files present.\n`);
+    process.exit(0);
+  }
+
+  const parts = [`${result.present} present`];
+  if (result.missing.length > 0) parts.push(`${result.missing.length} missing`);
+  if (strict && result.extra.length > 0) parts.push(`${result.extra.length} extra`);
+  process.stdout.write(`── Structure check: ${parts.join(', ')} (of ${result.total} expected)\n`);
+
+  if (anyMissing) {
+    process.exit(1);
+  }
+  // Extra-only without --strict → exit 0 already handled above
+  // Extra-only with --strict
+  if (strict && anyExtra) {
+    process.exit(1);
+  }
+  process.exit(0);
+
+} catch (err) {
+  process.stderr.write(`× check-structure fatal: ${err.message}\n${err.stack}\n`);
+  process.exit(1);
+}
+} // end if (require.main === module)

package/dist/forge-payload/tools/collate.cjs

@@ -952,10 +952,16 @@ for (const bug of allBugs) {
   // When purging events for a bug, aggregate cost data from event files
   // before they are deleted. The aggregated cost summary is embedded in
   // the bug's INDEX.md so the information survives the purge.
+  //
+  // Bug-phase events live in the shared `events/bugs/` virtual sprint dir
+  // (see meta-fix-bug.md § Event Emission). Read from that dir and filter
+  // by `event.bugId === bug.bugId` — the per-bug `events/{bugId}/` path
+  // never existed (silent data loss before this fix).
   let costTotals;
   if (PURGE_EVENTS && SPRINT_ARG && SPRINT_ARG === bug.bugId) {
-    const { events } = loadSprintEvents(bug.bugId);
-    const tokenEvents = events.filter(e => e.inputTokens !== undefined);
+    const { events } = loadSprintEvents('bugs');
+    const bugEvents = events.filter(e => e.bugId === bug.bugId);
+    const tokenEvents = bugEvents.filter(e => e.inputTokens !== undefined);
     if (tokenEvents.length > 0) {
       const totals = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, estimatedCostUSD: 0, sources: new Set() };
       for (const e of tokenEvents) {
@@ -1022,16 +1028,35 @@ const tag = DRY_RUN ? '[dry-run] ' : '';
 console.log(`${tag}Collated: ${targetSprints.length} sprint(s), ${allBugs.length} bug(s) → MASTER_INDEX.md updated, ${sprintIndexesWritten} sprint INDEX(es), ${taskIndexesWritten} task INDEX(es), ${bugIndexesWritten} bug INDEX(es), ${costReportsWritten} COST_REPORT(s) written`);
 
 // --- Purge event directory if requested ---
+//
+// Bug arg → purge only the bug-matching events from the shared
+// `events/bugs/` dir (filter by event.bugId). Sprint arg → purge the
+// whole sprint event directory as before.
 if (PURGE_EVENTS) {
-  const relDir = path.relative(cwd, path.join(storeRoot, 'events', SPRINT_ARG));
   try {
-    const result = _getStore().purgeEvents(SPRINT_ARG, { dryRun: DRY_RUN });
-    if (result.fileCount === 0) {
-      console.log(`${tag}Purge: no events directory found for '${SPRINT_ARG}' — nothing to delete`);
-    } else if (DRY_RUN) {
-      console.log(`[dry-run] would purge: ${relDir}/ (${result.fileCount} file(s))`);
+    let result;
+    let relDir;
+    if (IS_BUG_ARG) {
+      relDir = path.relative(cwd, path.join(storeRoot, 'events', 'bugs'));
+      result = _getStore().purgeBugEvents(SPRINT_ARG, { dryRun: DRY_RUN });
+      const label = `'${SPRINT_ARG}' in ${relDir}/`;
+      if (result.fileCount === 0) {
+        console.log(`${tag}Purge: no events for ${label} — nothing to delete`);
+      } else if (DRY_RUN) {
+        console.log(`[dry-run] would purge: ${label} (${result.fileCount} file(s))`);
+      } else {
+        console.log(`Purged: ${label} (${result.fileCount} event file(s) deleted)`);
+      }
     } else {
-      console.log(`Purged: ${relDir}/ (${result.fileCount} event file(s) deleted)`);
+      relDir = path.relative(cwd, path.join(storeRoot, 'events', SPRINT_ARG));
+      result = _getStore().purgeEvents(SPRINT_ARG, { dryRun: DRY_RUN });
+      if (result.fileCount === 0) {
+        console.log(`${tag}Purge: no events directory found for '${SPRINT_ARG}' — nothing to delete`);
+      } else if (DRY_RUN) {
+        console.log(`[dry-run] would purge: ${relDir}/ (${result.fileCount} file(s))`);
+      } else {
+        console.log(`Purged: ${relDir}/ (${result.fileCount} event file(s) deleted)`);
+      }
     }
   } catch (err) {
     console.error(`Error: ${err.message}`);

package/dist/forge-payload/tools/list-skills.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+// Forge skill query helper
+//
+// Usage:
+//   node list-skills.js                  — print all available skill names (one per line)
+//   node list-skills.js <skill-name>     — exit 0 if available, exit 1 if not
+//
+// Sources checked:
+//   ~/.claude/plugins/installed_plugins.json  — marketplace plugins
+//     scope "user"  → always available
+//     scope "local" → only if projectPath matches cwd
+//   ~/.claude/skills/                          — personal skills (subdirs with SKILL.md)
+//
+// Uses only Node.js built-ins — no npm dependencies required.
+// Works on Linux, macOS, and Windows wherever Claude Code runs.
+
+'use strict';
+
+// On unexpected failure, exit 0 so hook callers degrade gracefully
+// (assume skill absent / no output) rather than propagating an error.
+process.on('uncaughtException', () => process.exit(0));
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const pluginsFile = process.env.CLAUDE_PLUGIN_DATA_ROOT
+  ? path.join(process.env.CLAUDE_PLUGIN_DATA_ROOT, 'installed_plugins.json')
+  : path.join(os.homedir(), '.claude', 'plugins', 'installed_plugins.json');
+
+const personalSkillsDir = process.env.CLAUDE_SKILLS_DIR
+  || path.join(os.homedir(), '.claude', 'skills');
+
+const cwd = process.cwd();
+const skills = new Set();
+
+// Source 1: marketplace plugins from installed_plugins.json
+if (fs.existsSync(pluginsFile)) {
+  try {
+    const data = JSON.parse(fs.readFileSync(pluginsFile, 'utf8'));
+    for (const [key, installs] of Object.entries(data.plugins || {})) {
+      for (const install of installs) {
+        const isUser = install.scope === 'user';
+        const isLocal = install.scope === 'local' && install.projectPath === cwd;
+        if (isUser || isLocal) {
+          skills.add(key.split('@')[0]);
+        }
+      }
+    }
+  } catch { /* non-fatal */ }
+}
+
+// Source 2: personal skills — subdirectories containing a SKILL.md
+if (fs.existsSync(personalSkillsDir)) {
+  try {
+    for (const entry of fs.readdirSync(personalSkillsDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const skillMd = path.join(personalSkillsDir, entry.name, 'SKILL.md');
+      if (fs.existsSync(skillMd)) {
+        skills.add(entry.name);
+      }
+    }
+  } catch { /* non-fatal */ }
+}
+
+const sorted = [...skills].sort();
+const query = process.argv[2];
+
+if (!query) {
+  // Print all available skill names
+  if (sorted.length > 0) process.stdout.write(sorted.join('\n') + '\n');
+  process.exit(0);
+} else {
+  // Exit 0 if skill is available, 1 if not
+  process.exit(sorted.includes(query) ? 0 : 1);
+}

package/dist/forge-payload/tools/parse-gates.cjs

@@ -18,7 +18,13 @@
 const FENCE_OPEN = /^```gates\s+phase=([A-Za-z0-9_-]+)\s*$/;
 const FENCE_CLOSE = /^```\s*$/;
 
-const VALID_VERDICTS = new Set(['approved', 'revision']);
+// Verdicts a workflow can carry in an `after <phase> = <verdict>` directive.
+// Mirrors `read-verdict.cjs § ALLOWED_VERDICTS` — both must accept the same
+// set. `n/a` is the legitimate verdict for setup phases (plan, implement,
+// triage) that do not produce an approval/revision signal. Rejecting it
+// here caused EMBERGLOW-BUG-001 (v0.44.1) to halt at preflight exit 2
+// when the new fix-bug meta tried to use `after triage = n/a`.
+const VALID_VERDICTS = new Set(['approved', 'revision', 'n/a']);
 
 function parseGates(markdown) {
   if (typeof markdown !== 'string' || markdown.length === 0) return {};
@@ -142,7 +148,7 @@ function parseAfter(rest, lineNo) {
   const verdict = m[2].toLowerCase();
   if (!VALID_VERDICTS.has(verdict)) {
     throw new Error(
-      `parse-gates: line ${lineNo}: "after" verdict must be "approved" or "revision", got "${m[2]}"`,
+      `parse-gates: line ${lineNo}: "after" verdict must be "approved", "revision", or "n/a", got "${m[2]}"`,
     );
   }
   return { phase: m[1], verdict };

package/dist/forge-payload/tools/store-cli.cjs

@@ -140,6 +140,12 @@ const { suggest, suggestEntityType, formatSuggestion } = require('./lib/suggest.
 const VALID_SUMMARY_PHASES = new Set(['plan', 'review_plan', 'implementation', 'code_review', 'validation', 'triage', 'approve']);
 
 // Schema for a single phase summary (used by set-summary / set-bug-summary)
+// Mirror of bug.schema.json § $defs.phaseSummary. Both definitions MUST stay
+// in sync — this constant validates set-summary / set-bug-summary writes;
+// the JSON schema validates entity reads. `route` is an optional triage-only
+// field carrying the fix-bug pipeline route decision (A | B) and exists here
+// for bug.summaries.triage in particular; non-triage phases simply do not
+// set it.
 const PHASE_SUMMARY_SCHEMA = {
   type: 'object',
   required: ['objective', 'written_at'],
@@ -149,7 +155,8 @@ const PHASE_SUMMARY_SCHEMA = {
     findings:    { type: 'array', items: { type: 'string', maxLength: 200 }, maxItems: 12 },
     verdict:     { type: 'string', enum: ['approved', 'revision', 'n/a'] },
     written_at:  { type: 'string' },
-    artifact_ref:{ type: 'string' }
+    artifact_ref:{ type: 'string' },
+    route:       { type: 'string', enum: ['A', 'B'] }
   },
   additionalProperties: false
 };
@@ -181,12 +188,21 @@ const SPRINT_TRANSITIONS = {
 };
 
 const BUG_TRANSITIONS = {
-  reported:     ['triaged'],
-  triaged:      ['in-progress'],
-  'in-progress': ['fixed', 'approved'],   // fixed: code complete; approved: architect direct sign-off
-  fixed:        ['approved', 'in-progress'],   // approved: architect sign-off; in-progress: revision
-  approved:     ['verified', 'in-progress', 'fixed'],   // verified: commit; in-progress/ fixed: revision
-  // Terminal: verified
+  reported:      ['triaged'],
+  triaged:       ['in-progress'],
+  'in-progress': ['fixed'],
+  // Terminal: fixed
+  //
+  // The `approved` and `verified` enum members were removed (forge#GH-NNN).
+  // The architect-approve verdict signal for bugs travels through
+  // `bug.summaries.approve.verdict` (see read-verdict.cjs §
+  // BUG_PHASE_VERDICT_SOURCE), not `bug.status`. Keeping them in the enum
+  // created an LLM-translation trap whereby a task-shaped approve workflow
+  // run on a bug improvised `update-status bug ... approved`, which failed
+  // either at the schema layer (illegal transition out of terminal
+  // `verified`) or, post-FORGE-BUG-002 preflight defence, at the gate
+  // layer (forbid bug.status == approved). Dropping the enum removes the
+  // trap at its source.
 };
 
 const FEATURE_TRANSITIONS = {
@@ -205,7 +221,7 @@ const TRANSITION_MAP = {
 const TERMINAL_STATES = new Set([
   'committed', 'abandoned',          // task
   'retrospective-done',              // sprint
-  'verified',                        // bug
+  'fixed',                           // bug
   'shipped', 'retired'               // feature
 ]);
 
@@ -373,6 +389,32 @@ function listEntities(entity, filter) {
     case 'task':    return store.listTasks(filter);
     case 'bug':     return store.listBugs(filter);
     case 'feature': return store.listFeatures(filter);
+    case 'event': {
+      // Defect D fix: traverse all sub-directories under events/ — sprints write
+      // to events/<sprintId>/, bugs to events/bugs/, enhancements to events/enhancement/.
+      // Return the union of all event JSONs across every sub-directory, skipping
+      // sidecar files (_-prefixed) and non-JSON files.
+      const eventsBase = path.join(store.impl.storeRoot, 'events');
+      if (!fs.existsSync(eventsBase)) return [];
+      const allEvents = [];
+      const subDirs = fs.readdirSync(eventsBase, { withFileTypes: true });
+      for (const entry of subDirs) {
+        if (!entry.isDirectory()) continue;
+        const subDir = path.join(eventsBase, entry.name);
+        const files = fs.readdirSync(subDir).filter(
+          (f) => f.endsWith('.json') && !f.startsWith('_')
+        );
+        for (const file of files) {
+          try {
+            const rec = JSON.parse(fs.readFileSync(path.join(subDir, file), 'utf8'));
+            if (rec && (!filter || Object.entries(filter).every(([k, v]) => rec[k] === v))) {
+              allEvents.push(rec);
+            }
+          } catch (_) { /* skip malformed files */ }
+        }
+      }
+      return allEvents;
+    }
     default:
       console.error(`Unknown entity type: ${entity}${formatSuggestion(suggestEntityType(entity, ['sprint', 'task', 'bug', 'feature']))}`);
       process.exit(1);
@@ -619,7 +661,7 @@ function cmdList() {
   }
 
   if (!ENTITY_TYPES.includes(entity)) {
-    console.error(`Unknown entity type: ${entity}${formatSuggestion(suggestEntityType(entity, ['sprint', 'task', 'bug', 'feature']))}`);
+    console.error(`Unknown entity type: ${entity}${formatSuggestion(suggestEntityType(entity, ['sprint', 'task', 'bug', 'event', 'feature']))}`);
     process.exit(1);
   }
 
@@ -785,10 +827,13 @@ function cmdEmit() {
   }
 
   // FK check: reject sprintIds that are not in the store and not reserved.
-  // SYS-* prefix is reserved for system-generated events that predate sprint records.
+  // Reserved sprintIds:
+  //   - SYS-*  — system-generated events that predate sprint records
+  //   - bugs   — virtual sprint dir for fix-bug phase events (see
+  //              meta/tool-specs/validate-store.spec.md §"event.sprintId")
   // --allow-synthetic bypasses the check for test-harness or synthetic events.
   if (!allowSynthetic) {
-    const RESERVED_GLOB = /^SYS-/;
+    const RESERVED_GLOB = /^(SYS-|bugs$)/;
     if (!RESERVED_GLOB.test(sprintId)) {
       const validSprintIds = resolveValidSprintIds();
       if (!validSprintIds.includes(sprintId)) {