@entelligentsia/forgecli 0.11.3 → 0.19.0

package/dist/forge-payload/tools/replay-scoring.cjs

@@ -0,0 +1,117 @@
+'use strict';
+// FORGE-S24-T04 — cross-task replay scoring (recurrence boost).
+//
+// For each enhancement proposal synthesised from a friction event at task `t`,
+// scan friction events in tasks `t+1..N` (within the same sprint) for the
+// same `(subkind, evidence.skillId)` pair. Surface the count + task list on
+// the proposal so the T03 judge sees "this friction happened 3 times" rather
+// than "this friction happened once".
+//
+// Pure module; consumed by Phase 2 step 5/6 of meta-enhance.md after the
+// dedup pass and before the proposal artifact is written.
+//
+// Exports:
+//   computeRecurrence({ events, subkind, skillId, fromTaskId, taskOrder })
+//     -> { recurrence_count, recurrence_task_ids }
+//   annotateProposals(proposals, frictionEvents, taskOrder)
+//     -> new array of proposals, each carrying recurrence_count +
+//        recurrence_task_ids.
+
+function computeRecurrence({ events, subkind, skillId, fromTaskId, taskOrder }) {
+  if (!Array.isArray(events))    throw new TypeError('events must be an array');
+  if (!Array.isArray(taskOrder)) throw new TypeError('taskOrder must be an array');
+  if (typeof subkind    !== 'string' || subkind    === '') throw new TypeError('subkind required');
+  if (typeof skillId    !== 'string' || skillId    === '') throw new TypeError('skillId required');
+  if (typeof fromTaskId !== 'string' || fromTaskId === '') throw new TypeError('fromTaskId required');
+
+  const originIdx = taskOrder.indexOf(fromTaskId);
+
+  // Distinct taskIds with a matching friction event.
+  const matchingTaskIds = new Set();
+
+  for (const evt of events) {
+    if (!evt || evt.type !== 'friction') continue;
+    if (evt.subkind !== subkind) continue;
+    const evtSkillId = evt.evidence && evt.evidence.skillId;
+    if (evtSkillId !== skillId) continue;
+    if (!evt.taskId) continue;
+
+    if (originIdx === -1) {
+      // fromTaskId not in taskOrder: only count the origin task itself.
+      if (evt.taskId === fromTaskId) matchingTaskIds.add(evt.taskId);
+      continue;
+    }
+
+    const evtIdx = taskOrder.indexOf(evt.taskId);
+    // Forward-only: include origin task (evtIdx === originIdx) and later
+    // (evtIdx > originIdx). Skip earlier and unknown tasks.
+    if (evtIdx >= originIdx) matchingTaskIds.add(evt.taskId);
+  }
+
+  // Always include the origin task so recurrence_count >= 1.
+  matchingTaskIds.add(fromTaskId);
+
+  // Sort by taskOrder position; tasks not in taskOrder go last in insertion order.
+  const ordered = [...matchingTaskIds].sort((a, b) => {
+    const ai = taskOrder.indexOf(a);
+    const bi = taskOrder.indexOf(b);
+    if (ai === -1 && bi === -1) return 0;
+    if (ai === -1) return 1;
+    if (bi === -1) return -1;
+    return ai - bi;
+  });
+
+  return {
+    recurrence_count:    ordered.length,
+    recurrence_task_ids: ordered,
+  };
+}
+
+function annotateProposals(proposals, frictionEvents, taskOrder) {
+  if (!Array.isArray(proposals))      throw new TypeError('proposals must be an array');
+  if (!Array.isArray(frictionEvents)) throw new TypeError('frictionEvents must be an array');
+  if (!Array.isArray(taskOrder))      throw new TypeError('taskOrder must be an array');
+
+  // Index friction events by eventId for O(1) sourceFrictionIds resolution.
+  const byEventId = new Map();
+  for (const evt of frictionEvents) {
+    if (evt && evt.eventId) byEventId.set(evt.eventId, evt);
+  }
+
+  return proposals.map((proposal) => {
+    const sourceIds = Array.isArray(proposal.sourceFrictionIds)
+      ? proposal.sourceFrictionIds
+      : [];
+
+    // Resolve the first sourceFrictionId that points at a known friction event
+    // with subkind + evidence.skillId. The originating event determines
+    // (subkind, skillId, fromTaskId) for the recurrence scan.
+    let originEvent = null;
+    for (const id of sourceIds) {
+      const evt = byEventId.get(id);
+      if (evt && evt.subkind && evt.evidence && evt.evidence.skillId && evt.taskId) {
+        originEvent = evt;
+        break;
+      }
+    }
+
+    if (!originEvent) {
+      // No resolvable provenance: neutral annotation. recurrence_count=1
+      // keeps the schema invariant; recurrence_task_ids is empty so the
+      // judge can distinguish "single observation" from "unresolved origin".
+      return { ...proposal, recurrence_count: 1, recurrence_task_ids: [] };
+    }
+
+    const { recurrence_count, recurrence_task_ids } = computeRecurrence({
+      events:     frictionEvents,
+      subkind:    originEvent.subkind,
+      skillId:    originEvent.evidence.skillId,
+      fromTaskId: originEvent.taskId,
+      taskOrder,
+    });
+
+    return { ...proposal, recurrence_count, recurrence_task_ids };
+  });
+}
+
+module.exports = { computeRecurrence, annotateProposals };

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);
   }

package/dist/forge-payload/tools/substitute-placeholders.cjs

@@ -35,19 +35,47 @@
  *     [--dry-run]
  *
  * Exported API (for unit testing):
- *   buildSubstitutionMap(config, context, rules?)
+ *   buildSubstitutionMap(config, context, rules?, { enumCatalog }?)
  *   applySubstitutions(text, map)
  *   extractFrontmatter(content)
  *   substituteFile(content, map)
  *   walkBasePackPi(src, outRoot, dryRun, io)
+ *   resolveEnumCatalog(forgeRoot)
  *   PI_TARGET_SUBDIRS
  *   REQUIRED_KEYS
  *   RUNTIME_PASSTHROUGH_KEYS
+ *
+ * ENUM placeholder syntax (added FORGE-S25-T26):
+ *   {{ENUM:task.status}} → expands to comma-separated enum values from enum-catalog.json
+ *   Requires enumCatalog to be passed to buildSubstitutionMap (4th arg: { enumCatalog }).
+ *   Fail-open: unreplaced + stderr warning when catalog absent or key not found.
  */
 
 const fs = require('node:fs');
 const path = require('node:path');
 const { getCommandsSubdir } = require('./lib/paths.cjs');
+const { extractFrontmatter: _extractFrontmatter } = require('./lib/frontmatter.cjs');
+
+// ── Enum catalog loader (FORGE-S25-T26) ──────────────────────────────────────
+
+/**
+ * Load the enum catalog from <forgeRoot>/schemas/enum-catalog.json.
+ * Returns the parsed catalog object, or null if absent or unparseable.
+ * Fail-open: never throws. Used by buildSubstitutionMap and by tests.
+ *
+ * @param {string} forgeRoot - absolute path to the forge plugin root directory
+ * @returns {object|null}
+ */
+function resolveEnumCatalog(forgeRoot) {
+  if (!forgeRoot) return null;
+  const catalogPath = path.join(forgeRoot, 'schemas', 'enum-catalog.json');
+  if (!fs.existsSync(catalogPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(catalogPath, 'utf8'));
+  } catch (_) {
+    return null;
+  }
+}
 
 // ── Constants ────────────────────────────────────────────────────────────────
 
@@ -111,38 +139,14 @@ const PI_TARGET_SUBDIRS = new Set(['workflows', 'personas', 'skills', 'templates
 
 /**
  * Extract YAML frontmatter from a file's content.
- *
- * The opening `---` must be at line 1, column 0 (no leading whitespace) to
- * avoid false positives from `---` horizontal rules in Markdown body content.
+ * Delegates to lib/frontmatter.cjs (canonical CRLF-normalizing implementation).
+ * Exported for backward compat with existing tests.
  *
  * @param {string} content
  * @returns {{ frontmatter: string|null, body: string }}
  */
 function extractFrontmatter(content) {
-  // Opening --- must be at the very start of the file, at column 0.
-  if (!content.startsWith('---\n') && !content.startsWith('---\r\n')) {
-    return { frontmatter: null, body: content };
-  }
-
-  // Find the closing ---
-  const lines = content.split('\n');
-  for (let i = 1; i < lines.length; i++) {
-    if (lines[i] === '---' || lines[i] === '---\r') {
-      // Closing delimiter found at line i (0-indexed)
-      // Reconstruct frontmatter (lines 0..i inclusive) and body (lines i+1..)
-      const frontmatterLines = lines.slice(0, i + 1);
-      const bodyLines = lines.slice(i + 1);
-
-      // Re-attach trailing newline to closing --- so frontmatter ends with \n
-      const frontmatter = frontmatterLines.join('\n') + '\n';
-      const body = bodyLines.join('\n');
-
-      return { frontmatter, body };
-    }
-  }
-
-  // No closing --- found — treat entire content as body (malformed frontmatter)
-  return { frontmatter: null, body: content };
+  return _extractFrontmatter(content);
 }
 
 // ── Substitution ─────────────────────────────────────────────────────────────
@@ -151,15 +155,31 @@ function extractFrontmatter(content) {
  * Apply substitution map to a string. Keys in RUNTIME_PASSTHROUGH_KEYS are
  * left intact. Unknown keys are also left intact (missing optional keys).
  *
+ * Two pass strategy:
+ *   Pass 1: ENUM placeholders ({{ENUM:entity.field}}) — resolved via enumCatalog
+ *           entries pre-loaded into the map by buildSubstitutionMap.
+ *   Pass 2: Standard {{KEY}} placeholders — flat alphanumeric/hyphen keys.
+ *
  * @param {string} text
  * @param {Map<string, string>} map
  * @returns {string}
  */
 function applySubstitutions(text, map) {
-  // Only match placeholders whose keys are ALL_CAPS_WITH_UNDERSCORES or
-  // lowercase-with-hyphens (for skill names). Dot-notation is intentionally
-  // NOT matched — T03 uses flat keys only.
-  return text.replace(/\{\{([A-Za-z][A-Za-z0-9_-]*)\}\}/g, (full, key) => {
+  // Pass 1: ENUM placeholders — {{ENUM:entity.field}} (added FORGE-S25-T26).
+  // Resolved via map entries with keys like 'ENUM:task.status'.
+  // Fail-open: unknown ENUM key emits warning to stderr and leaves placeholder unreplaced.
+  let result = text.replace(/\{\{ENUM:([a-z]+\.[a-z]+)\}\}/g, (full, enumKey) => {
+    const mapKey = 'ENUM:' + enumKey;
+    if (map.has(mapKey)) return map.get(mapKey);
+    // Warn but leave unreplaced — do not throw.
+    process.stderr.write(`substitute-placeholders: unknown ENUM key '${enumKey}' — leaving unreplaced\n`);
+    return full;
+  });
+
+  // Pass 2: Standard {{KEY}} placeholders.
+  // Only match flat keys (ALL_CAPS_WITH_UNDERSCORES or lowercase-with-hyphens).
+  // Dot-notation and colon-notation are intentionally NOT matched — handled above.
+  return result.replace(/\{\{([A-Za-z][A-Za-z0-9_-]*)\}\}/g, (full, key) => {
     if (RUNTIME_PASSTHROUGH_KEYS.has(key)) return full;
     if (map.has(key)) return map.get(key);
     // Unknown key — leave intact (missing optional)
@@ -195,7 +215,11 @@ function substituteFile(content, map) {
  * @returns {Map<string, string>}
  * @throws {Error} if PROJECT_NAME or PREFIX is missing
  */
-function buildSubstitutionMap(config, context, rules) {
+function buildSubstitutionMap(config, context, rules, opts) {
+  // opts: optional 4th arg — { enumCatalog?: object }
+  // enumCatalog, if provided, is used to expand {{ENUM:entity.field}} placeholders.
+  // (FORGE-S25-T26)
+  const enumCatalog = (opts && opts.enumCatalog) || null;
   const project = (config && config.project) || {};
   const commands = (config && config.commands) || {};
   const paths = (config && config.paths) || {};
@@ -314,6 +338,20 @@ function buildSubstitutionMap(config, context, rules) {
     map.set(placeholder, substituted);
   }
 
+  // ── ENUM catalog keys (FORGE-S25-T26) ────────────────────────────────────────
+  // Pre-expand ENUM placeholders into the map as 'ENUM:entity.field' keys.
+  // applySubstitutions() pass 1 uses these to resolve {{ENUM:task.status}}.
+  // Fail-open: if enumCatalog is null, no ENUM keys are added and the
+  // applySubstitutions ENUM pass will leave placeholders unreplaced with a warning.
+  if (enumCatalog && enumCatalog.enums && typeof enumCatalog.enums === 'object') {
+    for (const [enumKey, enumValues] of Object.entries(enumCatalog.enums)) {
+      if (Array.isArray(enumValues)) {
+        // Format: comma + space, schema-definition order (values in catalog order, not sorted).
+        map.set('ENUM:' + enumKey, enumValues.join(', '));
+      }
+    }
+  }
+
   return map;
 }
 
@@ -670,8 +708,9 @@ module.exports = {
   applySubstitutions,
   extractFrontmatter,
   substituteFile,
-  walkBasePackPi,        // NEW — layout-reshape walker for --target pi
-  PI_TARGET_SUBDIRS,     // NEW — exported constant for tests
+  walkBasePackPi,        // layout-reshape walker for --target pi
+  resolveEnumCatalog,    // FORGE-S25-T26 — load enum-catalog.json; pass to buildSubstitutionMap
+  PI_TARGET_SUBDIRS,
   REQUIRED_KEYS,
   RUNTIME_PASSTHROUGH_KEYS,
 };

package/node_modules/@earendil-works/pi-agent-core/dist/agent-loop.d.ts

@@ -3,7 +3,7 @@
  * Transforms to Message[] only at the LLM call boundary.
  */
 import { EventStream } from "@earendil-works/pi-ai";
-import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, StreamFn } from "./types.js";
+import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, StreamFn } from "./types.ts";
 export type AgentEventSink = (event: AgentEvent) => Promise<void> | void;
 /**
  * Start an agent loop with a new prompt message.