@entelligentsia/forgecli 0.11.3 → 0.15.0

package/dist/forge-payload/tools/delete-candidate-detector.cjs

@@ -0,0 +1,114 @@
+'use strict';
+// FORGE-S24-T05 — delete-candidate detection (3-sprint zero-use).
+//
+// Scan `skill_usage` events across the trailing `windowSize` sprints of
+// `sprintOrder`. Any skill that has at least one observation inside the
+// window AND zero retrievals AND zero invocations across every in-window
+// observation is a delete candidate. The detector emits one `delete_skill`
+// proposal per qualifying skill.
+//
+// Pure module; consumed by Phase 2 of meta-enhance.md (between the
+// recurrence-annotation step and the proposal-artifact write step).
+//
+// Carry-over caveat (documented in the workflow): the window only becomes
+// meaningful once `windowSize` sprints have actually elapsed since
+// skill_usage emission landed in T01. Until then, the function still runs
+// over the available sprints but the signal is noisier.
+//
+// We deliberately do NOT propose deletion for skills with zero observations
+// in the window — that case is indistinguishable from a brand-new skill
+// that simply hasn't been loaded yet. The detector only deletes what it
+// has actually seen go cold.
+//
+// Exports:
+//   scanZeroUse({ events, sprintOrder, windowSize = 3 })
+//     -> [{ skillId, observedSprintIds }]
+//   buildDeleteProposals({ events, sprintOrder, windowSize = 3, targetPathFor })
+//     -> [proposal] — proposal shape conforming to proposal.schema.json.
+
+const DEFAULT_WINDOW_SIZE = 3;
+
+function scanZeroUse({ events, sprintOrder, windowSize = DEFAULT_WINDOW_SIZE }) {
+  if (!Array.isArray(events))      throw new TypeError('events must be an array');
+  if (!Array.isArray(sprintOrder)) throw new TypeError('sprintOrder must be an array');
+  if (!Number.isInteger(windowSize) || windowSize < 1) {
+    throw new TypeError('windowSize must be a positive integer');
+  }
+
+  // Trailing N sprints. If sprintOrder is shorter than the window, use all of it.
+  const window = sprintOrder.slice(-windowSize);
+  const windowSet = new Set(window);
+
+  // skillId -> { observedSprintIds: Set, anyRetrieved: bool, anyUsed: bool }
+  const bySkill = new Map();
+
+  for (const evt of events) {
+    if (!evt || evt.type !== 'skill_usage') continue;
+    if (typeof evt.skillId !== 'string' || evt.skillId === '') continue;
+    if (typeof evt.sprintId !== 'string' || evt.sprintId === '') continue;
+    if (!windowSet.has(evt.sprintId)) continue;
+
+    let agg = bySkill.get(evt.skillId);
+    if (!agg) {
+      agg = { observedSprintIds: new Set(), anyRetrieved: false, anyUsed: false };
+      bySkill.set(evt.skillId, agg);
+    }
+    agg.observedSprintIds.add(evt.sprintId);
+    if (evt.retrieved === true) agg.anyRetrieved = true;
+    if (evt.used      === true) agg.anyUsed      = true;
+  }
+
+  const results = [];
+  for (const [skillId, agg] of bySkill) {
+    if (agg.anyRetrieved || agg.anyUsed) continue;
+    if (agg.observedSprintIds.size === 0)   continue;
+
+    // Sort observedSprintIds by window order so output is deterministic and
+    // mirrors sprintOrder.
+    const ordered = window.filter(s => agg.observedSprintIds.has(s));
+    results.push({ skillId, observedSprintIds: ordered });
+  }
+
+  // Deterministic skill ordering.
+  results.sort((a, b) => a.skillId.localeCompare(b.skillId));
+  return results;
+}
+
+function buildDeleteProposals({
+  events,
+  sprintOrder,
+  windowSize = DEFAULT_WINDOW_SIZE,
+  targetPathFor,
+}) {
+  if (typeof targetPathFor !== 'function') {
+    throw new TypeError('targetPathFor must be a function');
+  }
+
+  const candidates = scanZeroUse({ events, sprintOrder, windowSize });
+  const window = sprintOrder.slice(-windowSize);
+
+  return candidates.map(({ skillId, observedSprintIds }) => ({
+    op:          'delete_skill',
+    target_path: targetPathFor(skillId),
+    diff_body:
+      `- entire skill removed: ${skillId}\n` +
+      `- reason: zero retrieval AND zero invocation across ` +
+      `${observedSprintIds.length} observed sprint(s) within trailing ` +
+      `${windowSize}-sprint window (${window.join(', ')})`,
+    rationale:
+      `Skill "${skillId}" has no retrieval and no invocation in any of the ` +
+      `trailing ${windowSize} sprints it was observed in (${observedSprintIds.join(', ')}). ` +
+      `Delete-candidate per FORGE-S24-T05 detector.`,
+    sourceFrictionIds:   [],
+    window_size:         windowSize,
+    window_sprint_ids:   observedSprintIds.slice(),
+    recurrence_count:    1,
+    recurrence_task_ids: [],
+  }));
+}
+
+module.exports = {
+  scanZeroUse,
+  buildDeleteProposals,
+  DEFAULT_WINDOW_SIZE,
+};

package/dist/forge-payload/tools/judge-proposal.cjs

@@ -0,0 +1,177 @@
+'use strict';
+// FORGE-S24-T03 — LLM-judge step in Phase 2 (Sonnet rubric, drop <3/5).
+//
+// Pure module consumed by meta-enhance.md Phase 2 (step 5c) after the
+// recurrence annotator (step 5a) and delete-candidate detector (step 5b)
+// and BEFORE the artifact write (step 6).
+//
+// Two roles:
+//
+//   1. scoreProposal(proposal) — deterministic per-axis scorer. The workflow
+//      instructs Sonnet to apply the same rubric and emit scores; this
+//      module is both the fallback when Sonnet is unavailable AND the
+//      reference implementation tests pin so the rubric definition stays
+//      single-sourced. The five axes (RUBRIC_AXES) each carry a 0..5 score.
+//
+//   2. decideJudgement({ axes }) — pure aggregation. average < 3 -> drop;
+//      otherwise keep. Reason names the average so the rejection log is
+//      self-describing for retro review (AC3).
+//
+// The judge runs against every proposal pre-presentation (AC1). Dropped
+// proposals are logged with per-axis scores (AC3) by the workflow caller.
+//
+// Iron Law 2: tests for this module landed first (see judge-proposal.test.cjs).
+
+const RUBRIC_AXES = Object.freeze([
+  'specificity',
+  'when_not_to_use',
+  'no_trajectory_copy_paste',
+  'body_under_2kb',
+  'cites_friction',
+]);
+
+const DROP_THRESHOLD = 3;             // avg < 3 -> drop (AC: drop < 3/5)
+const MAX_BODY_BYTES = 2048;          // 2KB cap (AC: <=2KB body)
+const TRAJECTORY_RUN_BYTES = 400;     // suspicious verbatim run length
+
+// --- Per-axis scorers -----------------------------------------------------
+
+function scoreSpecificity(proposal) {
+  // Specificity heuristic: a specific proposal names a concrete artifact
+  // path beyond the generic top-level skills directory AND has a non-empty
+  // rationale OR a recurrence trail.
+  const t = String(proposal.target_path || '');
+  const r = String(proposal.rationale || '');
+  const seg = t.split('/').filter(Boolean);
+  const deepPath = seg.length >= 3;        // forge/skills/<name>.md is the floor
+  const namedSkill =
+    seg.length >= 1 &&
+    !/^(misc|tips|notes|general)\b/i.test(seg[seg.length - 1] || '');
+  const hasRationale = r.trim().length >= 16;
+  const recurrent = Number(proposal.recurrence_count || 1) > 1;
+
+  let s = 0;
+  if (deepPath)      s += 2;
+  if (namedSkill)    s += 1;
+  if (hasRationale)  s += 1;
+  if (recurrent)     s += 1;
+  return clamp05(s);
+}
+
+function scoreWhenNotToUse(proposal) {
+  // AC: rubric axis "When NOT to use" present. Phrase-based check. We accept
+  // the canonical phrase or any reasonable case variation.
+  const body = String(proposal.diff_body || '');
+  return /when\s+not\s+to\s+use/i.test(body) ? 5 : 0;
+}
+
+function scoreNoTrajectoryCopyPaste(proposal) {
+  // Heuristic: long verbatim runs of the same character or massive
+  // unbroken whitespace-free blocks suggest pasted trajectory output.
+  const body = String(proposal.diff_body || '');
+  // Penalise long runs of the same character (>= TRAJECTORY_RUN_BYTES).
+  const longRun = new RegExp('(.)\\1{' + (TRAJECTORY_RUN_BYTES - 1) + ',}');
+  if (longRun.test(body)) return 0;
+  // Penalise any unbroken non-whitespace block >= TRAJECTORY_RUN_BYTES.
+  if (/\S{400,}/.test(body)) return 0;
+  // Penalise lines that look like raw log entries dominating the body.
+  const lines = body.split(/\n/);
+  const longLines = lines.filter((l) => l.length >= 300).length;
+  if (longLines >= 3) return 1;
+  return 5;
+}
+
+function scoreBodyUnder2KB(proposal) {
+  const body = String(proposal.diff_body || '');
+  const bytes = Buffer.byteLength(body, 'utf8');
+  return bytes <= MAX_BODY_BYTES ? 5 : 0;
+}
+
+function scoreCitesFriction(proposal) {
+  const ids = Array.isArray(proposal.sourceFrictionIds)
+    ? proposal.sourceFrictionIds
+    : [];
+  if (ids.length === 0) return 0;
+  if (ids.length >= 3)  return 5;
+  if (ids.length === 2) return 4;
+  // Single citation: boost when recurrence trail shows the friction is real.
+  const recurrent =
+    Number(proposal.recurrence_count || 1) > 1 &&
+    Array.isArray(proposal.recurrence_task_ids) &&
+    proposal.recurrence_task_ids.length > 1;
+  return recurrent ? 3 : 1;
+}
+
+// --- Aggregators ----------------------------------------------------------
+
+function scoreProposal(proposal) {
+  if (!proposal || typeof proposal !== 'object') {
+    throw new TypeError('proposal must be an object');
+  }
+
+  const axes = {
+    specificity:              scoreSpecificity(proposal),
+    when_not_to_use:          scoreWhenNotToUse(proposal),
+    no_trajectory_copy_paste: scoreNoTrajectoryCopyPaste(proposal),
+    body_under_2kb:           scoreBodyUnder2KB(proposal),
+    cites_friction:           scoreCitesFriction(proposal),
+  };
+
+  validateAxes(axes);
+
+  const average = averageOf(axes);
+  return { axes, average };
+}
+
+function decideJudgement({ axes }) {
+  if (!axes || typeof axes !== 'object') {
+    throw new TypeError('axes must be an object');
+  }
+  validateAxes(axes);
+  const average = averageOf(axes);
+  const verdict = average < DROP_THRESHOLD ? 'drop' : 'keep';
+  const reason = verdict === 'drop'
+    ? `dropped: rubric average ${average.toFixed(1)} < ${DROP_THRESHOLD}/5 (axes: ${formatAxes(axes)})`
+    : `kept: rubric average ${average.toFixed(1)} >= ${DROP_THRESHOLD}/5 (axes: ${formatAxes(axes)})`;
+  return { verdict, average, axes: { ...axes }, reason };
+}
+
+// --- Internal helpers -----------------------------------------------------
+
+function validateAxes(axes) {
+  for (const axis of RUBRIC_AXES) {
+    if (!(axis in axes)) {
+      throw new RangeError(`missing axis: ${axis}`);
+    }
+    const v = axes[axis];
+    if (!Number.isFinite(v) || v < 0 || v > 5) {
+      throw new RangeError(`axis ${axis} out of range [0,5]: ${v}`);
+    }
+  }
+}
+
+function averageOf(axes) {
+  let sum = 0;
+  for (const axis of RUBRIC_AXES) sum += axes[axis];
+  // Round to one decimal place; rubric resolution is intentionally coarse so
+  // the rejection log reads cleanly in retros.
+  return Math.round((sum / RUBRIC_AXES.length) * 10) / 10;
+}
+
+function formatAxes(axes) {
+  return RUBRIC_AXES.map((a) => `${a}=${axes[a]}`).join(', ');
+}
+
+function clamp05(n) {
+  if (n < 0) return 0;
+  if (n > 5) return 5;
+  return n;
+}
+
+module.exports = {
+  RUBRIC_AXES,
+  DROP_THRESHOLD,
+  MAX_BODY_BYTES,
+  scoreProposal,
+  decideJudgement,
+};

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/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,
+};