@entelligentsia/forgecli 0.11.3 → 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/manage-versions.cjs

@@ -152,7 +152,11 @@ function copyFileWithDirs(src, dest) {
  *
  * @param {string} projectRoot        - path to the project root (where .forge/ lives)
  * @param {string} source             - snapshot source label (post-init | post-sprint:<ID> | on-demand)
- * @param {string[]} enhancedElements - list of .forge/-relative paths that were enhanced
+ * @param {string[]} enhancedElements - list of paths that were enhanced. Both
+ *                                       ".forge/-relative" (e.g. "personas/X.md") and
+ *                                       project-root-relative (".forge/personas/X.md")
+ *                                       forms accepted; the tool strips a leading
+ *                                       ".forge/" if present. See forge#108.
  * @param {boolean} [dryRun]          - when true, log intent but perform no I/O
  */
 function addSnapshot(projectRoot, source, enhancedElements, dryRun) {
@@ -191,9 +195,23 @@ function addSnapshot(projectRoot, source, enhancedElements, dryRun) {
   }
 
   // Archive each enhanced element by copying from .forge/ into the archive dir.
+  //
+  // Workflow callers pass paths in two forms historically:
+  //   (a) ".forge/-relative", e.g. "personas/engineer.md"
+  //   (b) project-root-relative, e.g. ".forge/personas/engineer.md"
+  // The docstring at the top of this function declared (a), but every meta-enhance
+  // and base-pack/enhance.md invocation passes (b). The previous code did
+  // path.join(projectRoot, ".forge", relPath) which double-prefixed (b) paths
+  // and silently skipped them via fs.existsSync. Result: every archive directory
+  // since basePackVersion 0.43.3 was created empty — layer 2 of the composition
+  // contract (manage-versions.cjs:13) became a no-op. See forge#108 / FORGE-BUG-038.
+  //
+  // Fix: normalize each relPath by stripping a leading ".forge/" if present.
+  // Archive destination uses the normalized form for consistency.
   for (const relPath of (enhancedElements || [])) {
-    const srcPath = path.join(projectRoot, '.forge', relPath);
-    const destPath = path.join(archiveAbsPath, relPath);
+    const normalizedRel = relPath.replace(/^\.\/?(?=\.forge\/)/, '').replace(/^\.forge\//, '');
+    const srcPath = path.join(projectRoot, '.forge', normalizedRel);
+    const destPath = path.join(archiveAbsPath, normalizedRel);
     if (fs.existsSync(srcPath)) {
       copyFileWithDirs(srcPath, destPath);
     }
@@ -261,6 +279,101 @@ function initStructureVersions(projectRoot, forgeRoot, dryRun, source) {
   console.log(`ノ structure-versions.json written (snapshot 0, source: ${effectiveSource}, plugin: v${basePackVersion})`);
 }
 
+// ---------------------------------------------------------------------------
+// forge#107 — Approach A layer 3: snapshot replay
+//
+// After /forge:regenerate writes fresh base-pack content over .forge/{personas,
+// skills,workflows,templates}/, walk the snapshots in order and restore each
+// enhancedElement that matches the target prefix. Later snapshots win on file
+// collision (last write).
+//
+// Semantics: "overlay" — user-enhanced files retain their captured content
+// even when the base-pack version of that file has changed in a plugin
+// update. Trade-off accepted for v1; future v2 may layer 3-way merge.
+//
+// Target prefix is normalized (leading ".forge/" stripped) and matches against
+// the normalized form of each enhancedElement's path. So:
+//   --target personas              matches  personas/X.md, personas/Y.md
+//   --target personas/engineer.md  matches only that exact file
+//   --target .forge/personas       same as --target personas
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalize a path by stripping a leading ".forge/" prefix.
+ * Symmetric with addSnapshot's archive normalization (forge#108).
+ */
+function normalizeRel(p) {
+  return p.replace(/^\.\/?(?=\.forge\/)/, '').replace(/^\.forge\//, '');
+}
+
+/**
+ * Replay snapshots — restore enhanced files matching the target prefix.
+ *
+ * @param {string} projectRoot - cwd; project root with .forge/
+ * @param {string} target       - prefix (e.g. "personas") or exact path
+ *                                (e.g. "personas/engineer.md"); ".forge/" prefix tolerated
+ * @param {boolean} [dryRun]    - log intent without copying
+ * @returns {{restored: string[], skipped: string[]}}
+ */
+function replaySnapshots(projectRoot, target, dryRun) {
+  if (!target) {
+    throw new Error('replay requires --target <prefix>. Examples: --target personas, --target personas/engineer.md');
+  }
+
+  const normalizedTarget = normalizeRel(target);
+  const doc = readStructureVersions(projectRoot);
+
+  // Build a per-file map: relPath -> { archivePath, snapshotIndex }.
+  // Later snapshots overwrite earlier on collision (Map insertion semantics
+  // give us first-set value; we want last-set, so iterate ascending and
+  // overwrite explicitly).
+  const fileMap = new Map();
+  for (const snap of doc.snapshots) {
+    if (!snap.enhancedElements || !snap.archivePath) continue;
+    for (const elem of snap.enhancedElements) {
+      const normalized = normalizeRel(elem);
+      // Match: target is a path-prefix of normalized element.
+      // Path-boundary: ensure "personas" matches "personas/X.md" but not "personas-foo.md".
+      const isMatch = normalized === normalizedTarget ||
+                      normalized.startsWith(normalizedTarget + '/');
+      if (!isMatch) continue;
+
+      const archiveAbs = path.join(projectRoot, snap.archivePath, normalized);
+      fileMap.set(normalized, { archiveAbs, snapshotIndex: snap.index });
+    }
+  }
+
+  const restored = [];
+  const skipped = [];
+
+  for (const [normalized, { archiveAbs, snapshotIndex }] of fileMap) {
+    const destAbs = path.join(projectRoot, '.forge', normalized);
+    if (!fs.existsSync(archiveAbs)) {
+      // Archive missing (pre-forge#108 snapshots created empty archives).
+      // Skip — we can't restore what we don't have.
+      skipped.push(normalized);
+      continue;
+    }
+    if (dryRun) {
+      console.log(`[dry-run] Would restore ${normalized} from snap-${snapshotIndex}`);
+      restored.push(normalized);
+      continue;
+    }
+    copyFileWithDirs(archiveAbs, destAbs);
+    restored.push(normalized);
+  }
+
+  if (restored.length > 0) {
+    console.log(`〇 replay complete — ${restored.length} file(s) restored from snapshots matching '${target}'`);
+  } else if (skipped.length > 0) {
+    console.log(`△ replay — ${skipped.length} matching element(s) skipped (archive missing; created before forge#108 fix)`);
+  } else {
+    console.log(`〇 replay — no enhanced elements match target '${target}'; nothing to restore`);
+  }
+
+  return { restored, skipped };
+}
+
 // ---------------------------------------------------------------------------
 // Exports (for unit tests)
 // ---------------------------------------------------------------------------
@@ -268,12 +381,14 @@ function initStructureVersions(projectRoot, forgeRoot, dryRun, source) {
 module.exports = {
   initStructureVersions,
   addSnapshot,
+  replaySnapshots,
   readStructureVersions,
   writeStructureVersions,
   VERSIONS_PATH,
   versionsPath,
   readPluginVersion,
   readOverlayToolVersion,
+  normalizeRel,
 };
 
 // ---------------------------------------------------------------------------
@@ -352,9 +467,22 @@ if (require.main === module) {
         break;
       }
 
+      case 'replay': {
+        // forge#107 — Approach A layer 3
+        const targetIdx = args.indexOf('--target');
+        const target = targetIdx !== -1 ? args[targetIdx + 1] : null;
+        if (!target || target.startsWith('--')) {
+          console.error('× replay requires --target <prefix>.');
+          console.error('  Examples: --target personas, --target personas/engineer.md');
+          process.exit(1);
+        }
+        replaySnapshots(projectRoot, target, DRY_RUN);
+        break;
+      }
+
       default: {
         console.error(`× Unknown subcommand: ${subcommand || '(none)'}`);
-        console.error('  Usage: manage-versions.cjs <init|current|list|add-snapshot> [--dry-run]');
+        console.error('  Usage: manage-versions.cjs <init|current|list|add-snapshot|replay> [--dry-run]');
         process.exit(1);
       }
     }

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/queue-drain.cjs

@@ -0,0 +1,152 @@
+'use strict';
+// FORGE-S24-T07 — queue drain at sprint close (per-task curator → batched review).
+//
+// Paper §3.2.1 grouped reward: one batched review at sprint close, not one
+// prompt per task. Per-task curators (T10) append proposals to a project-local
+// queue as they encounter friction during the sprint; Phase 2 drains the queue,
+// dedupes by {op, target_path, body-hash}, and feeds a single batch into the
+// downstream pipeline (compression gate T06 → replay scoring T04 → judge T03).
+//
+// Queue layout (canonical):
+//   .forge/enhancement-proposals/queue/<sprintId>/<taskId>-<ts>.json
+//
+//   - One file per per-task curator run.
+//   - The `<ts>` suffix (ISO compact timestamp) means concurrent or repeated
+//     curator runs on the same task never collide; each run produces a fresh
+//     file. Files are append-only — once written, never overwritten. The drain
+//     is a read-only pass that does NOT delete the queue (operators triage
+//     queue files for retrospective debugging).
+//
+// Dedup key: `<op>|<target_path>|sha256(diff_body)`.
+//   - `op` and `target_path` together identify "what artifact and how" (insert
+//     vs update vs delete).
+//   - `sha256(diff_body)` makes two proposals with byte-identical diff bodies
+//     collapse to one even if their rationales or sourceFrictionIds differ.
+//     Different bodies → different proposals (a smaller surgical patch and a
+//     full-file rewrite are distinct decisions for the judge).
+//
+// Pure helpers (`bodyHash`, `dedupeKey`, `dedupeProposals`, `queuePathFor`) are
+// fs-free. `appendToQueue` and `drainQueue` touch the filesystem.
+//
+// Exports:
+//   bodyHash(body)                    → sha256 hex digest of body (UTF-8).
+//   dedupeKey(proposal)               → composite key string.
+//   dedupeProposals(proposals)        → first-seen-wins deduped array.
+//   queuePathFor({ queueRoot, sprintId, taskId, ts })
+//                                     → canonical file path (string).
+//   appendToQueue({ queueRoot, sprintId, taskId, ts, proposals })
+//                                     → absolute path written; throws if path
+//                                       already exists (append-only invariant).
+//   drainQueue({ queueRoot, sprintId })
+//                                     → { proposals: [...deduped], files: [...],
+//                                         errors: [...] } — fs read, never write.
+
+const fs     = require('node:fs');
+const path   = require('node:path');
+const crypto = require('node:crypto');
+
+function bodyHash(body) {
+  if (typeof body !== 'string') {
+    throw new TypeError('bodyHash: body must be a string');
+  }
+  return crypto.createHash('sha256').update(body, 'utf8').digest('hex');
+}
+
+function dedupeKey(proposal) {
+  if (!proposal || typeof proposal !== 'object') {
+    throw new TypeError('dedupeKey: proposal must be an object');
+  }
+  const op          = String(proposal.op          ?? '');
+  const target_path = String(proposal.target_path ?? '');
+  const diff_body   = String(proposal.diff_body   ?? '');
+  return `${op}|${target_path}|${bodyHash(diff_body)}`;
+}
+
+function dedupeProposals(proposals) {
+  if (!Array.isArray(proposals)) {
+    throw new TypeError('dedupeProposals: proposals must be an array');
+  }
+  const seen = new Set();
+  const out  = [];
+  for (const p of proposals) {
+    const k = dedupeKey(p);
+    if (seen.has(k)) continue;
+    seen.add(k);
+    out.push(p);
+  }
+  return out;
+}
+
+function queuePathFor({ queueRoot, sprintId, taskId, ts } = {}) {
+  if (typeof sprintId !== 'string' || !sprintId) {
+    throw new TypeError('queuePathFor: sprintId is required');
+  }
+  if (typeof taskId !== 'string' || !taskId) {
+    throw new TypeError('queuePathFor: taskId is required');
+  }
+  if (typeof ts !== 'string' || !ts) {
+    throw new TypeError('queuePathFor: ts is required');
+  }
+  const root = queueRoot ?? '.forge/enhancement-proposals/queue';
+  return path.join(root, sprintId, `${taskId}-${ts}.json`);
+}
+
+function appendToQueue({ queueRoot, sprintId, taskId, ts, proposals } = {}) {
+  if (!Array.isArray(proposals)) {
+    throw new TypeError('appendToQueue: proposals must be an array');
+  }
+  const target = queuePathFor({ queueRoot, sprintId, taskId, ts });
+  if (fs.existsSync(target)) {
+    throw new Error(
+      `appendToQueue: queue file already exists at ${target} ` +
+      `(queue is append-only; choose a fresh ts).`,
+    );
+  }
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, JSON.stringify(proposals, null, 2), 'utf8');
+  return target;
+}
+
+function drainQueue({ queueRoot, sprintId } = {}) {
+  if (typeof sprintId !== 'string' || !sprintId) {
+    throw new TypeError('drainQueue: sprintId is required');
+  }
+  if (typeof queueRoot !== 'string' || !queueRoot) {
+    throw new TypeError('drainQueue: queueRoot is required');
+  }
+  const sprintDir = path.join(queueRoot, sprintId);
+  const result = { proposals: [], files: [], errors: [] };
+  if (!fs.existsSync(sprintDir)) return result;
+
+  const entries = fs.readdirSync(sprintDir)
+    .filter((name) => name.endsWith('.json'))
+    .sort(); // deterministic order: lexicographic ⇒ chronological because of ts suffix
+  const merged = [];
+  for (const name of entries) {
+    const abs = path.join(sprintDir, name);
+    result.files.push(abs);
+    let parsed;
+    try {
+      parsed = JSON.parse(fs.readFileSync(abs, 'utf8'));
+    } catch (err) {
+      result.errors.push({ file: abs, error: err.message });
+      continue;
+    }
+    if (!Array.isArray(parsed)) {
+      result.errors.push({ file: abs, error: 'expected JSON array of proposals' });
+      continue;
+    }
+    for (const p of parsed) merged.push(p);
+  }
+  result.proposals = dedupeProposals(merged);
+  return result;
+}
+
+module.exports = {
+  bodyHash,
+  dedupeKey,
+  dedupeProposals,
+  queuePathFor,
+  appendToQueue,
+  drainQueue,
+};