@entelligentsia/forgecli 0.15.0 → 0.19.0

package/dist/forge-payload/tools/lib/schema-loader.cjs

@@ -0,0 +1,139 @@
+'use strict';
+// lib/schema-loader.cjs — memoized, multi-path schema search chain.
+//
+// Extracted from the _getSchemas() closure in tools/store-cli.cjs so both
+// store-cli.cjs and hooks/validate-write.js (and any future consumer) can
+// load schemas through one canonical place.
+//
+// Search order (first hit wins per schema file):
+//   1. project-installed:  {cwd}/.forge/schemas/{file}
+//   2. in-tree (dev):      {cwd}/forge/schemas/{file}
+//   3. plugin-installed:   {pluginDir}/{file}   (default: __dirname/../schemas)
+//   4. forge-cli bundled:  {bundledDir}/{file}  (default: __dirname/../.schemas)
+//   5. fallback:           minimal required-fields stub + WARN on stderr
+
+const fs = require('fs');
+const path = require('path');
+
+// schema-loader.cjs lives at tools/lib/schema-loader.cjs.
+// Default schema dirs are computed relative to the tools/ parent directory
+// (i.e., two levels up from __dirname) so they resolve correctly whether
+// loaded from a dev tree or a forge-cli bundled payload copy.
+//
+//   __dirname          = …/tools/lib
+//   TOOLS_DIR          = …/tools
+//   DEFAULT_PLUGIN_DIR = …/schemas           (= $FORGE_ROOT/schemas/)
+//   DEFAULT_BUNDLED_DIR= …/.schemas          (= forge-cli bundled .schemas/)
+const TOOLS_DIR = path.join(__dirname, '..');
+
+const ENTITY_TYPES = ['sprint', 'task', 'bug', 'event', 'feature'];
+
+// Canonical minimal required-field set per entity type.
+// Kept in one place here; store-cli.cjs and validate-write.js should import
+// this instead of re-declaring their own copies.
+const MINIMAL_REQUIRED = {
+  sprint:  ['sprintId', 'title', 'status', 'taskIds', 'createdAt'],
+  task:    ['taskId', 'sprintId', 'title', 'status', 'path'],
+  bug:     ['bugId', 'title', 'severity', 'status', 'path', 'reportedAt'],
+  event:   ['eventId', 'taskId', 'sprintId', 'role', 'action', 'phase', 'iteration',
+            'startTimestamp', 'endTimestamp', 'durationMinutes', 'model'],
+  feature: ['id', 'title', 'status', 'created_at'],
+};
+
+const AUX_SCHEMAS = {
+  'event-sidecar':   'event-sidecar.schema.json',
+  'progress-entry':  'progress-entry.schema.json',
+  'collation-state': 'collation-state.schema.json',
+};
+
+// Module-level memoization cache — cleared by resetSchemaCache() for testing.
+let _cache = null;
+
+/**
+ * Load the full set of Forge schemas, memoized per process.
+ *
+ * @param {object} [options]
+ * @param {string} [options.cwd]       Override process.cwd() for path resolution (testing).
+ * @param {string} [options.pluginDir] Override default plugin schema dir (testing).
+ * @param {string} [options.bundledDir] Override default forge-cli bundled schema dir (testing).
+ * @returns {{ [type: string]: object }} Map of entity/aux type → parsed JSON schema.
+ */
+function loadSchemas(options) {
+  if (_cache) return _cache;
+
+  const cwd       = (options && options.cwd)        || process.cwd();
+  const pluginDir = (options && options.pluginDir)   || path.join(TOOLS_DIR, '..', 'schemas');
+  const bundledDir = (options && options.bundledDir) || path.join(TOOLS_DIR, '..', '.schemas');
+
+  const projectDir = path.join(cwd, '.forge', 'schemas');
+  const inTreeDir  = path.join(cwd, 'forge', 'schemas');
+
+  const allTypes = [...ENTITY_TYPES, ...Object.keys(AUX_SCHEMAS)];
+  const schemas = {};
+
+  for (const type of allTypes) {
+    const schemaFile = AUX_SCHEMAS[type] || `${type}.schema.json`;
+    let schema = null;
+
+    // 1. project-installed
+    const projectPath = path.join(projectDir, schemaFile);
+    try {
+      if (fs.existsSync(projectPath)) {
+        schema = JSON.parse(fs.readFileSync(projectPath, 'utf8'));
+      }
+    } catch (_) {}
+
+    // 2. in-tree (dev mode)
+    if (!schema) {
+      const inTreePath = path.join(inTreeDir, schemaFile);
+      try {
+        if (fs.existsSync(inTreePath)) {
+          schema = JSON.parse(fs.readFileSync(inTreePath, 'utf8'));
+        }
+      } catch (_) {}
+    }
+
+    // 3. plugin-installed  (store-cli.cjs lives at $FORGE_ROOT/tools/, so
+    //    default pluginDir = __dirname/../schemas = $FORGE_ROOT/schemas/)
+    if (!schema) {
+      const pluginPath = path.join(pluginDir, schemaFile);
+      try {
+        if (fs.existsSync(pluginPath)) {
+          schema = JSON.parse(fs.readFileSync(pluginPath, 'utf8'));
+        }
+      } catch (_) {}
+    }
+
+    // 4. forge-cli bundled payload (build-payload.cjs writes schemas to .schemas/)
+    if (!schema) {
+      const bundledPath = path.join(bundledDir, schemaFile);
+      try {
+        if (fs.existsSync(bundledPath)) {
+          schema = JSON.parse(fs.readFileSync(bundledPath, 'utf8'));
+        }
+      } catch (_) {}
+    }
+
+    if (schema) {
+      schemas[type] = schema;
+    } else {
+      // eslint-disable-next-line no-console
+      process.stderr.write(`WARN: schema file ${schemaFile} not found, using minimal fallback\n`);
+      schemas[type] = { type: 'object', required: MINIMAL_REQUIRED[type] || [], properties: {} };
+    }
+  }
+
+  _cache = schemas;
+  return _cache;
+}
+
+/**
+ * Clear the memoization cache.
+ * FOR TESTING ONLY — not part of the production API.
+ * Do not call this from production code.
+ */
+function resetSchemaCache() {
+  _cache = null;
+}
+
+module.exports = { loadSchemas, resetSchemaCache, ENTITY_TYPES, MINIMAL_REQUIRED, AUX_SCHEMAS };

package/dist/forge-payload/tools/lib/slug.cjs

@@ -0,0 +1,39 @@
+'use strict';
+// lib/slug.cjs — canonical slug generator.
+//
+// DECISION (FORGE-S25-T07, closes N-T-4):
+//   Default maxLen=30 — matches the canonical behavior in tools/seed-store.cjs.
+//   tools/lib/store-facade.cjs had no truncation; this module corrects that divergence.
+//
+// API:
+//   deriveSlug(title: string, options?: { maxLen?: number }) → string
+//
+//   Derives a URL-safe slug from a human-readable title:
+//   1. Lowercase
+//   2. Replace runs of non-alphanumeric characters with a single hyphen
+//   3. Strip leading and trailing hyphens
+//   4. Truncate to maxLen characters
+//   5. Strip trailing hyphens that appear after truncation
+//
+//   This behavior matches tools/seed-store.cjs:20 exactly (the canonical
+//   reference implementation). store-facade.cjs is now the consumer that
+//   was previously diverging (no truncation).
+
+/**
+ * Derive a URL-safe slug from a title.
+ *
+ * @param {string} title - Human-readable title string.
+ * @param {Object} [options]
+ * @param {number} [options.maxLen=30] - Maximum slug length (default 30).
+ * @returns {string} - The derived slug.
+ */
+function deriveSlug(title, { maxLen = 30 } = {}) {
+  return title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, maxLen)
+    .replace(/-+$/g, '');
+}
+
+module.exports = { deriveSlug };

package/dist/forge-payload/tools/lib/store-facade.cjs

@@ -4,6 +4,8 @@
 
 const fs = require('fs');
 const path = require('path');
+const { readJson } = require('./json-io.cjs');
+const { deriveSlug } = require('./slug.cjs');
 
 class StoreFacade {
   constructor(storeDir) {
@@ -16,7 +18,7 @@ class StoreFacade {
     return fs.readdirSync(full)
       .filter(f => f.endsWith('.json'))
       .map(f => {
-        try { return JSON.parse(fs.readFileSync(path.join(full, f), 'utf8')); }
+        try { return readJson(path.join(full, f)); }
         catch { return null; }
       })
       .filter(Boolean);
@@ -45,8 +47,7 @@ class StoreFacade {
     const dir = { tasks: 'tasks', bugs: 'bugs', sprints: 'sprints', features: 'features' }[type];
     if (!dir) return null;
     const filePath = path.join(this.storeDir, dir, `${id}.json`);
-    if (!fs.existsSync(filePath)) return null;
-    try { return JSON.parse(fs.readFileSync(filePath, 'utf8')); }
+    try { return readJson(filePath); }
     catch { return null; }
   }
 
@@ -115,7 +116,7 @@ function loadForgeConfig(cwd) {
   const configPath = path.join(root, '.forge', 'config.json');
   let cfg = {};
   if (fs.existsSync(configPath)) {
-    try { cfg = JSON.parse(fs.readFileSync(configPath, 'utf8')); } catch {}
+    try { cfg = readJson(configPath) || {}; } catch {}
   }
   const prefix = cfg.project?.prefix || 'WI';
   const kbRel = cfg.paths?.engineering || 'engineering';
@@ -152,7 +153,7 @@ function findIndexPath(entity, kbPath) {
   }
   if (entity.bugId) {
     const slug = entity.title
-      ? entity.title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/-+$/, '')
+      ? deriveSlug(entity.title, { maxLen: 30 })
       : entity.bugId;
     return path.join(kbPath, 'bugs', `${entity.bugId}-${slug}`, 'INDEX.md');
   }

package/dist/forge-payload/tools/preflight-gate.cjs

@@ -113,12 +113,48 @@ function describePredicate(pred) {
   return `${pred.field} ${pred.op} ${pred.value}`;
 }
 
-module.exports = { preflight, resolveTaskArtifactDir };
+module.exports = { preflight, resolveTaskArtifactDir, resolveSprintArtifactDir };
 
 // CLI shim: `node preflight-gate.cjs --phase <name> --task <taskId> [--bug <bugId>] [--workflow <name>]`
 // exit codes: 0 ok, 1 gate(s) failed, 2 invalid args / missing definitions
-// Scan the sprint directory for a subdirectory matching the task ID prefix.
-// Returns the directory name (e.g. "FORGE-S12-T06-model-discovery") or null.
+
+// Scan the sprints root for a directory matching sprintId exactly or as a prefix slug.
+//
+// Two patterns supported (in order of preference):
+//   1. <sprintId>          — exact match (no slug)
+//   2. <sprintId>-<slug>   — slug suffix (e.g. "FORGE-S25-foundation-refactor")
+//
+// Returns the directory name (e.g. "FORGE-S25-foundation-refactor") or null.
+function resolveSprintArtifactDir(sprintId, engineeringRoot, cwd) {
+  if (!sprintId) return null;
+  const base = cwd || process.cwd();
+  const sprintsRoot = path.resolve(base, engineeringRoot, 'sprints');
+  let entries;
+  try {
+    entries = fs.readdirSync(sprintsRoot);
+  } catch (_) {
+    return null;
+  }
+  const isDir = (entry) => {
+    try {
+      return fs.statSync(path.join(sprintsRoot, entry)).isDirectory();
+    } catch (_) {
+      return false;
+    }
+  };
+  // Pass 1: exact match
+  for (const entry of entries) {
+    if (!isDir(entry)) continue;
+    if (entry === sprintId) return entry;
+  }
+  // Pass 2: slug match — dir starts with "<sprintId>-"
+  for (const entry of entries) {
+    if (!isDir(entry)) continue;
+    if (entry.startsWith(sprintId + '-')) return entry;
+  }
+  return null;
+}
+
 // Scan the sprint directory for a subdirectory matching the task.
 //
 // Two patterns supported (in order of preference, to avoid false positives):
@@ -129,10 +165,14 @@ module.exports = { preflight, resolveTaskArtifactDir };
 //                                  prefix explicitly (e.g., "S003-T-C1-1-...").
 //
 // Returns the directory name or null.
-function resolveTaskArtifactDir(taskRecord, engineeringRoot, cwd) {
+// The optional resolvedSprintDir parameter allows the caller to pass a pre-resolved
+// sprint directory name (e.g. "FORGE-S25-foundation-refactor") so the task scan
+// happens inside the correct on-disk directory rather than the bare sprintId dir.
+function resolveTaskArtifactDir(taskRecord, engineeringRoot, cwd, resolvedSprintDir) {
   if (!taskRecord || !taskRecord.sprintId || !taskRecord.taskId) return null;
   const base = cwd || process.cwd();
-  const sprintDir = path.resolve(base, engineeringRoot, 'sprints', taskRecord.sprintId);
+  const sprintDirName = resolvedSprintDir || taskRecord.sprintId;
+  const sprintDir = path.resolve(base, engineeringRoot, 'sprints', sprintDirName);
   let entries;
   try {
     entries = fs.readdirSync(sprintDir);
@@ -201,7 +241,15 @@ if (require.main === module) {
     const parts = String(p || '').split('/').filter(Boolean);
     return parts[parts.length - 1] || '';
   }
-  const taskArtifactDir = resolveTaskArtifactDir(taskRecord, engineeringRoot);
+  // Resolve the sprint directory name first (may have a slug suffix, e.g.
+  // "FORGE-S25-foundation-refactor" for sprintId "FORGE-S25"). This resolved
+  // name is used both as the {sprint} substitution and as the directory in
+  // which resolveTaskArtifactDir scans for task subdirectories.
+  const sprintId = taskRecord ? taskRecord.sprintId : undefined;
+  const resolvedSprintDir = sprintId
+    ? (resolveSprintArtifactDir(sprintId, engineeringRoot) || sprintId)
+    : undefined;
+  const taskArtifactDir = resolveTaskArtifactDir(taskRecord, engineeringRoot, undefined, resolvedSprintDir);
   // Fallback: if task.path points to a file (e.g., TASK_PROMPT.md) we want
   // the *directory* segment, not the filename. Without this, a project that
   // stores task.path as the prompt file would propagate "TASK_PROMPT.md" as
@@ -216,7 +264,7 @@ if (require.main === module) {
 
   const substitutions = {
     engineering: engineeringRoot,
-    sprint: taskRecord ? taskRecord.sprintId : undefined,
+    sprint: resolvedSprintDir,
     task: taskDir,
     bug: bugDir,
   };

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

@@ -10,22 +10,10 @@
 const fs = require('fs');
 const path = require('path');
 const Store = require('./store.cjs');
+const { deriveSlug } = require('./lib/slug.cjs');
 
 const DRY_RUN = process.argv.includes('--dry-run');
 
-/**
- * Convert a title string to a lower-kebab-case slug, truncated to 30 chars.
- * Non-alphanumeric characters are collapsed to a single hyphen.
- */
-function deriveSlug(title) {
-  return title
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '')
-    .slice(0, 30)
-    .replace(/-+$/g, '');       // trim trailing hyphens after truncation
-}
-
 // ── Exports for testing ────────────────────────────────────────────────────────
 
 module.exports = { deriveSlug };

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

@@ -12,6 +12,7 @@ let _projectRoot;
 function _getProjectRoot() { return _projectRoot || (_projectRoot = require('./lib/project-root.cjs').findProjectRoot()); }
 
 const _path = require('path');
+const { loadSchemas } = require('./lib/schema-loader.cjs');
 
 // Path traversal guard — resolves the events directory and validates that
 // sprintOrBugId doesn't escape it. Same pattern as store.cjs purgeEvents.
@@ -28,91 +29,10 @@ function _resolveEventsDir(sprintOrBugId) {
   return resolvedDir;
 }
 
-let _schemas;
+// _getSchemas() delegates to lib/schema-loader.cjs (memoized, 4-path search
+// chain). Callers use _getSchemas() so no call-sites need updating.
 function _getSchemas() {
-  if (_schemas) return _schemas;
-  const fs = require('fs');
-  const path = require('path');
-
-  const ENTITY_TYPES = ['sprint', 'task', 'bug', 'event', 'feature'];
-
-  const MINIMAL_REQUIRED = {
-    sprint:  ['sprintId', 'title', 'status', 'taskIds', 'createdAt'],
-    task:    ['taskId', 'sprintId', 'title', 'status', 'path'],
-    bug:     ['bugId', 'title', 'severity', 'status', 'path', 'reportedAt'],
-    event:   ['eventId', 'taskId', 'sprintId', 'role', 'action', 'phase', 'iteration', 'startTimestamp', 'endTimestamp', 'durationMinutes', 'model'],
-    feature: ['id', 'title', 'status', 'created_at']
-  };
-
-  const schemas = {};
-  const projectDir   = path.join('.forge', 'schemas');
-  const inTreeDir    = path.join('forge', 'schemas');
-  const pluginDir    = path.join(__dirname, '..', 'schemas');
-
-  const AUX_SCHEMAS = {
-    'event-sidecar':    'event-sidecar.schema.json',
-    'progress-entry':   'progress-entry.schema.json',
-    'collation-state':  'collation-state.schema.json',
-  };
-
-  const allTypes = [...ENTITY_TYPES, ...Object.keys(AUX_SCHEMAS)];
-  for (const type of allTypes) {
-    const schemaFile = AUX_SCHEMAS[type] || `${type}.schema.json`;
-    let schema = null;
-
-    // 1. Try project-installed schemas first
-    const projectPath = path.join(projectDir, schemaFile);
-    try {
-      if (fs.existsSync(projectPath)) {
-        schema = JSON.parse(fs.readFileSync(projectPath, 'utf8'));
-      }
-    } catch (_) {}
-
-    // 2. Fall back to in-tree source schemas (development mode)
-    if (!schema) {
-      const inTreePath = path.join(inTreeDir, schemaFile);
-      try {
-        if (fs.existsSync(inTreePath)) {
-          schema = JSON.parse(fs.readFileSync(inTreePath, 'utf8'));
-        }
-      } catch (_) {}
-    }
-
-    // 3. Fall back to plugin-installed schemas (production mode)
-    //    store-cli.cjs lives at $FORGE_ROOT/tools/, so __dirname/../schemas/
-    //    resolves to $FORGE_ROOT/schemas/ — always correct for installed plugins.
-    if (!schema) {
-      const pluginPath = path.join(pluginDir, schemaFile);
-      try {
-        if (fs.existsSync(pluginPath)) {
-          schema = JSON.parse(fs.readFileSync(pluginPath, 'utf8'));
-        }
-      } catch (_) {}
-    }
-
-    // 4. Fall back to forge-cli bundled payload layout, where build-payload.cjs
-    //    writes plugin schemas to `.schemas/` (dot-prefixed). Without this lookup,
-    //    bundled `forgecli` installs silently degrade to the minimal fallback at
-    //    the bottom and stop enforcing schema constraints at runtime.
-    if (!schema) {
-      const bundledPath = path.join(__dirname, '..', '.schemas', schemaFile);
-      try {
-        if (fs.existsSync(bundledPath)) {
-          schema = JSON.parse(fs.readFileSync(bundledPath, 'utf8'));
-        }
-      } catch (_) {}
-    }
-
-    if (schema) {
-      schemas[type] = schema;
-    } else {
-      console.error(`WARN: schema file ${schemaFile} not found, using minimal fallback`);
-      schemas[type] = { type: 'object', required: MINIMAL_REQUIRED[type] || [], properties: {} };
-    }
-  }
-
-  _schemas = schemas;
-  return _schemas;
+  return loadSchemas();
 }
 
 // ---------------------------------------------------------------------------
@@ -167,32 +87,45 @@ const PHASE_SUMMARY_SCHEMA = {
 // Transition tables
 // ---------------------------------------------------------------------------
 
+// Canonical transition tables — reconciled by T25 ADR (doc/decisions/state-machine-reconciliation.md).
+// Authoritative source: forge/tools/build-enum-catalog.cjs (CANONICAL_*_TRANSITIONS).
+// These tables are kept in sync with enum-catalog.json via the drift detection test.
+// Task: FORGE-S25-T26 (closes N-E-2 on the plugin side; T27 closes it on forge-cli side).
+
 const TASK_TRANSITIONS = {
-  draft:                 ['planned', 'plan-revision-required', 'code-revision-required', 'blocked', 'escalated', 'abandoned'],
-  planned:               ['plan-approved', 'implemented', 'plan-revision-required', 'code-revision-required', 'blocked', 'escalated', 'abandoned'],
-  'plan-approved':       ['implementing', 'plan-revision-required', 'code-revision-required', 'blocked', 'escalated', 'abandoned'],
-  implementing:          ['implemented', 'plan-revision-required', 'code-revision-required', 'blocked', 'escalated', 'abandoned'],
-  implemented:           ['review-approved', 'plan-revision-required', 'code-revision-required', 'blocked', 'escalated', 'abandoned'],
-  'review-approved':     ['approved', 'plan-revision-required', 'code-revision-required', 'blocked', 'escalated', 'abandoned'],
-  approved:              ['committed', 'plan-revision-required', 'code-revision-required', 'blocked', 'escalated', 'abandoned'],
+  draft:                    ['planned', 'blocked', 'escalated', 'abandoned'],
+  planned:                  ['plan-approved', 'plan-revision-required', 'blocked', 'escalated', 'abandoned'],
+  'plan-approved':          ['implementing', 'plan-revision-required', 'blocked', 'escalated', 'abandoned'],
+  implementing:             ['implemented', 'plan-revision-required', 'code-revision-required', 'blocked', 'escalated', 'abandoned'],
+  implemented:              ['review-approved', 'plan-revision-required', 'code-revision-required', 'blocked', 'escalated', 'abandoned'],
+  'review-approved':        ['approved', 'plan-revision-required', 'code-revision-required', 'blocked', 'escalated', 'abandoned'],
+  approved:                 ['committed', 'plan-revision-required', 'code-revision-required', 'blocked', 'escalated', 'abandoned'],
   'plan-revision-required': ['planned', 'blocked', 'escalated', 'abandoned'],
   'code-revision-required': ['implementing', 'blocked', 'escalated', 'abandoned'],
-  // Terminal: committed, abandoned — no transitions out
+  // Explicit terminal/sink entries — prevents FAILED_STATES bypass from allowing illegal re-opens.
+  committed:                [],
+  blocked:                  [],
+  escalated:                [],
+  abandoned:                [],
 };
 
 const SPRINT_TRANSITIONS = {
-  planning:    ['active', 'blocked', 'partially-completed', 'abandoned'],
-  active:      ['completed', 'blocked', 'partially-completed', 'abandoned'],
-  completed:   ['retrospective-done', 'blocked', 'partially-completed', 'abandoned'],
-  // Terminal: retrospective-done, abandoned
+  planning:              ['active', 'blocked', 'abandoned'],
+  active:                ['completed', 'partially-completed', 'blocked', 'abandoned'],
+  completed:             ['retrospective-done'],
+  'partially-completed': ['retrospective-done'],
+  'retrospective-done':  [],
+  blocked:               ['active', 'abandoned'],
+  abandoned:             [],
 };
 
 const BUG_TRANSITIONS = {
-  reported:      ['triaged'],
-  triaged:       ['in-progress'],
-  'in-progress': ['fixed'],
-  // Terminal: fixed
-  //
+  reported:      ['triaged', 'abandoned'],
+  triaged:       ['in-progress', 'abandoned'],
+  'in-progress': ['fixed', 'abandoned'],
+  // Explicit terminal entries.
+  fixed:         [],
+  abandoned:     [],
   // 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 §
@@ -225,10 +158,22 @@ const TERMINAL_STATES = new Set([
   'shipped', 'retired'               // feature
 ]);
 
-// Failed states that may be entered from any non-terminal state
+// Failed/escape states that may be entered from any non-terminal state via the
+// FAILED_STATES bypass in isLegalTransition.
+//
+// FORGE-S25-T26 (T25 ADR canonicalization):
+// - `blocked` REMOVED — now has explicit table entries; removing prevents `committed → blocked`
+//   and `bug → blocked` (neither in canonical tables).
+// - `plan-revision-required`, `code-revision-required` REMOVED — now fully explicit in
+//   TASK_TRANSITIONS; removing prevents `draft → plan-revision-required` (D-T-1).
+//   All legitimate transitions to these states are covered by explicit table entries.
+// - `escalated`, `abandoned` RETAINED — not in every entity's explicit table (e.g.,
+//   FEATURE_TRANSITIONS has no escalated/abandoned entries). Universal escape remains.
+// - `partially-completed` RETAINED — sprint-only escape.
+// See: doc/decisions/state-machine-reconciliation.md; FORGE-S25-T26.
 const FAILED_STATES = new Set([
-  'plan-revision-required', 'code-revision-required', 'blocked', 'escalated', 'abandoned',  // task
-  'blocked', 'partially-completed'  // sprint
+  'escalated', 'abandoned',   // universal escapes (task explicit + feature bypass)
+  'partially-completed'       // sprint
 ]);
 
 function isLegalTransition(entityType, field, currentValue, newValue) {
@@ -828,12 +773,14 @@ function cmdEmit() {
 
   // FK check: reject sprintIds that are not in the store and not reserved.
   // 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")
+  //   - 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")
+  //   - enhancement — virtual sprint dir for post-init / post-sprint
+  //                   enhancement-trigger events (FORGE-S25-T01)
   // --allow-synthetic bypasses the check for test-harness or synthetic events.
   if (!allowSynthetic) {
-    const RESERVED_GLOB = /^(SYS-|bugs$)/;
+    const RESERVED_GLOB = /^(SYS-|bugs$|enhancement$)/;
     if (!RESERVED_GLOB.test(sprintId)) {
       const validSprintIds = resolveValidSprintIds();
       if (!validSprintIds.includes(sprintId)) {

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

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const { findProjectRoot } = require('./lib/project-root.cjs');
+const { readJson, writeJson } = require('./lib/json-io.cjs');
 
 /**
  * Store Facade for Forge
@@ -104,29 +105,38 @@ class FSImpl {
   }
 
   _readJson(filePath) {
-    if (!fs.existsSync(filePath)) return null;
-    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return readJson(filePath);
   }
 
   _writeJson(filePath, data) {
-    const dir = path.dirname(filePath);
-    if (!fs.existsSync(dir)) {
-      fs.mkdirSync(dir, { recursive: true });
-    }
-    fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8');
-    return data;
+    return writeJson(filePath, data);
   }
 
-  // Sprints
-  getSprint(id) { return this._readJson(this._getPath('sprint', id)); }
-  listSprints(filter) {
-    const dir = path.join(this.storeRoot, 'sprints');
+  /**
+   * Shared list helper: read all .json files in a store subdirectory and
+   * apply an optional filter. Only top-level files are read (no recursion).
+   *
+   * NOTE: listEvents is intentionally excluded from this helper. It requires
+   * an extra `sprintId` path segment and a different call shape, making it
+   * impossible to express as a simple `_listEntities('events', filter)` call.
+   * Do not attempt to unify listEvents here — the distinction is load-bearing.
+   *
+   * @param {string} subdir - subdirectory under storeRoot (e.g. 'sprints')
+   * @param {object|null} filter - field equality filter, or null for all records
+   * @returns {Array} matching records (null entries from parse failures included)
+   */
+  _listEntities(subdir, filter) {
+    const dir = path.join(this.storeRoot, subdir);
     if (!fs.existsSync(dir)) return [];
     return fs.readdirSync(dir)
       .filter(f => f.endsWith('.json'))
       .map(f => this._readJson(path.join(dir, f)))
-      .filter(s => !s || (filter ? this._matches(s, filter) : true));
+      .filter(r => !r || (filter ? this._matches(r, filter) : true));
   }
+
+  // Sprints
+  getSprint(id) { return this._readJson(this._getPath('sprint', id)); }
+  listSprints(filter) { return this._listEntities('sprints', filter); }
   writeSprint(data) {
     return this._writeJson(this._getPath('sprint', data.sprintId), data);
   }
@@ -137,14 +147,7 @@ class FSImpl {
 
   // Tasks
   getTask(id) { return this._readJson(this._getPath('task', id)); }
-  listTasks(filter) {
-    const dir = path.join(this.storeRoot, 'tasks');
-    if (!fs.existsSync(dir)) return [];
-    return fs.readdirSync(dir)
-      .filter(f => f.endsWith('.json'))
-      .map(f => this._readJson(path.join(dir, f)))
-      .filter(t => !t || (filter ? this._matches(t, filter) : true));
-  }
+  listTasks(filter) { return this._listEntities('tasks', filter); }
   writeTask(data) {
     return this._writeJson(this._getPath('task', data.taskId), data);
   }
@@ -155,14 +158,7 @@ class FSImpl {
 
   // Bugs
   getBug(id) { return this._readJson(this._getPath('bug', id)); }
-  listBugs(filter) {
-    const dir = path.join(this.storeRoot, 'bugs');
-    if (!fs.existsSync(dir)) return [];
-    return fs.readdirSync(dir)
-      .filter(f => f.endsWith('.json'))
-      .map(f => this._readJson(path.join(dir, f)))
-      .filter(b => !b || (filter ? this._matches(b, filter) : true));
-  }
+  listBugs(filter) { return this._listEntities('bugs', filter); }
   writeBug(data) {
     return this._writeJson(this._getPath('bug', data.bugId), data);
   }
@@ -236,14 +232,7 @@ class FSImpl {
 
   // Features
   getFeature(id) { return this._readJson(this._getPath('feature', id)); }
-  listFeatures(filter) {
-    const dir = path.join(this.storeRoot, 'features');
-    if (!fs.existsSync(dir)) return [];
-    return fs.readdirSync(dir)
-      .filter(f => f.endsWith('.json'))
-      .map(f => this._readJson(path.join(dir, f)))
-      .filter(f => !f || (filter ? this._matches(f, filter) : true));
-  }
+  listFeatures(filter) { return this._listEntities('features', filter); }
   writeFeature(data) {
     return this._writeJson(this._getPath('feature', data.feature_id), data);
   }