@entelligentsia/forgecli 0.11.2 → 0.15.0

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

@@ -0,0 +1,192 @@
+'use strict';
+// FORGE-S24-T06 — compression gate (reject >20% growth without 3+ frictions).
+//
+// Phase 2 of meta-enhance runs this gate BEFORE the LLM judge (T03). The gate
+// is a cheap deterministic filter: an `update_skill` proposal that grows the
+// target file by more than 20% (byte-wise) must be backed by at least 3
+// supporting friction events. Insufficient support → reject; the judge never
+// sees the proposal.
+//
+// Why a cheap pre-judge gate?
+//   - Judging is expensive (LLM call).
+//   - Unbounded growth of a skill body is the classic SkillOS failure mode —
+//     adding pages of trajectory copy-paste to "patch" a friction. Cheap to
+//     detect deterministically; wasteful to ask the judge to rule on.
+//
+// Op semantics:
+//   - `insert_skill`: not gated — the file doesn't exist yet, "growth" is
+//     undefined; the judge's body_under_2kb axis handles bloat instead.
+//   - `delete_skill`: not gated — deletion always shrinks.
+//   - `update_skill`: GATED. Growth is measured byte-wise (UTF-8) on the new
+//     body that would land after applying the diff. The caller resolves the
+//     "currentBody" and "newBody" by reading the file and applying the patch.
+//
+// Friction support:
+//   - Default: `proposal.sourceFrictionIds.length`.
+//   - Override: caller may supply `supportingFrictionCountFor(proposal) -> int`
+//     when the policy is "count frictions citing the same skill across the
+//     sprint" rather than "count citations on the proposal itself".
+//
+// Pure module: no fs access, no LLM call. Consumed by Phase 2 between
+// step 5b (delete-candidate detection) and step 5c (LLM-judge gate).
+//
+// Exports:
+//   GROWTH_THRESHOLD                       — 0.20 (strict >, ties admit).
+//   MIN_SUPPORTING_FRICTIONS               — 3.
+//   evaluateGrowth({ currentBody, newBody })
+//     -> { currentBytes, newBytes, growthRatio }
+//   evaluateProposal({ proposal, currentBody, newBody, supportingFrictionCount })
+//     -> { admit, reason, growthRatio, currentBytes, newBytes,
+//          supportingFrictionCount, threshold, minSupportingFrictions, op }
+//   filterProposals({ proposals, currentBodyFor, newBodyFor,
+//                     supportingFrictionCountFor })
+//     -> { admitted: proposal[], rejected: { proposal, ...evaluation }[] }
+
+const GROWTH_THRESHOLD         = 0.20;
+const MIN_SUPPORTING_FRICTIONS = 3;
+
+const VALID_OPS = new Set(['insert_skill', 'update_skill', 'delete_skill']);
+
+function evaluateGrowth({ currentBody, newBody }) {
+  if (typeof currentBody !== 'string') {
+    throw new TypeError('currentBody must be a string');
+  }
+  if (typeof newBody !== 'string') {
+    throw new TypeError('newBody must be a string');
+  }
+  const currentBytes = Buffer.byteLength(currentBody, 'utf8');
+  const newBytes     = Buffer.byteLength(newBody,     'utf8');
+  // When currentBytes === 0 the ratio is undefined for update; we return
+  // Infinity and let the caller decide. evaluateProposal treats Infinity as
+  // "over threshold" — an update on an empty file is, by definition,
+  // unbounded growth — so the friction-support gate still applies.
+  const growthRatio = currentBytes === 0
+    ? (newBytes === 0 ? 0 : Infinity)
+    : (newBytes - currentBytes) / currentBytes;
+  return { currentBytes, newBytes, growthRatio };
+}
+
+function evaluateProposal({
+  proposal,
+  currentBody,
+  newBody,
+  supportingFrictionCount,
+}) {
+  if (!proposal || typeof proposal !== 'object') {
+    throw new TypeError('proposal must be an object');
+  }
+  if (typeof proposal.op !== 'string' || !VALID_OPS.has(proposal.op)) {
+    throw new TypeError(
+      `proposal.op must be one of ${Array.from(VALID_OPS).join(', ')}; got ${JSON.stringify(proposal.op)}`,
+    );
+  }
+  if (typeof currentBody !== 'string') {
+    throw new TypeError('currentBody must be a string');
+  }
+  if (typeof newBody !== 'string') {
+    throw new TypeError('newBody must be a string');
+  }
+
+  // Resolve supporting friction count — explicit > proposal.sourceFrictionIds.
+  let frictionCount;
+  if (supportingFrictionCount === undefined) {
+    frictionCount = Array.isArray(proposal.sourceFrictionIds)
+      ? proposal.sourceFrictionIds.length
+      : 0;
+  } else {
+    if (!Number.isInteger(supportingFrictionCount) || supportingFrictionCount < 0) {
+      throw new TypeError(
+        'supportingFrictionCount must be a non-negative integer',
+      );
+    }
+    frictionCount = supportingFrictionCount;
+  }
+
+  const { currentBytes, newBytes, growthRatio } = evaluateGrowth({
+    currentBody, newBody,
+  });
+
+  const base = {
+    growthRatio,
+    currentBytes,
+    newBytes,
+    supportingFrictionCount: frictionCount,
+    threshold:               GROWTH_THRESHOLD,
+    minSupportingFrictions:  MIN_SUPPORTING_FRICTIONS,
+    op:                      proposal.op,
+  };
+
+  // Non-update ops are not gated.
+  if (proposal.op !== 'update_skill') {
+    return { admit: true, reason: 'op_not_gated', ...base };
+  }
+
+  // Strict >: growth exactly at threshold admits.
+  if (!(growthRatio > GROWTH_THRESHOLD)) {
+    return { admit: true, reason: 'admitted_below_threshold', ...base };
+  }
+
+  // Over threshold — admit only if enough friction support.
+  if (frictionCount >= MIN_SUPPORTING_FRICTIONS) {
+    return { admit: true, reason: 'admitted_with_friction_support', ...base };
+  }
+
+  return { admit: false, reason: 'compression_gate_growth_unsupported', ...base };
+}
+
+function filterProposals({
+  proposals,
+  currentBodyFor,
+  newBodyFor,
+  supportingFrictionCountFor,
+}) {
+  if (!Array.isArray(proposals)) {
+    throw new TypeError('proposals must be an array');
+  }
+  if (typeof currentBodyFor !== 'function') {
+    throw new TypeError('currentBodyFor must be a function');
+  }
+  if (typeof newBodyFor !== 'function') {
+    throw new TypeError('newBodyFor must be a function');
+  }
+  if (
+    supportingFrictionCountFor !== undefined &&
+    typeof supportingFrictionCountFor !== 'function'
+  ) {
+    throw new TypeError('supportingFrictionCountFor must be a function when provided');
+  }
+
+  const admitted = [];
+  const rejected = [];
+
+  for (const proposal of proposals) {
+    const currentBody = currentBodyFor(proposal);
+    const newBody     = newBodyFor(proposal);
+    const supportingFrictionCount = supportingFrictionCountFor
+      ? supportingFrictionCountFor(proposal)
+      : undefined;
+
+    const evaluation = evaluateProposal({
+      proposal,
+      currentBody,
+      newBody,
+      supportingFrictionCount,
+    });
+
+    if (evaluation.admit) {
+      admitted.push(proposal);
+    } else {
+      rejected.push({ proposal, ...evaluation });
+    }
+  }
+
+  return { admitted, rejected };
+}
+
+module.exports = {
+  GROWTH_THRESHOLD,
+  MIN_SUPPORTING_FRICTIONS,
+  evaluateGrowth,
+  evaluateProposal,
+  filterProposals,
+};

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