@entelligentsia/forgecli 0.11.3 → 0.19.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/friction-emit.cjs

@@ -24,6 +24,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { ensureDir } = require('./lib/fsutil.cjs');
 
 const REQUIRED = ['workflow', 'persona', 'issue'];
 const OPTIONAL = ['subkind', 'evidence'];
@@ -99,7 +100,7 @@ function main(argv) {
   }
 
   const cacheDir = path.join(process.cwd(), '.forge', 'cache');
-  fs.mkdirSync(cacheDir, { recursive: true });
+  ensureDir(cacheDir);
   const target = path.join(cacheDir, `FRICTION-${args.workflow}.jsonl`);
   fs.appendFileSync(target, `${JSON.stringify(record)}\n`, 'utf8');
   process.stdout.write(`${target}\n`);

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/lib/frontmatter.cjs

@@ -0,0 +1,62 @@
+'use strict';
+// lib/frontmatter.cjs — canonical YAML frontmatter extractor.
+//
+// CRLF POSTURE (canonical, enforced by test suite):
+//   Normalize to LF on read. All \r characters are stripped before processing.
+//   Output (both frontmatter and body) always uses LF-only line endings,
+//   regardless of the source line ending style (LF / CRLF / CR-only / mixed).
+//
+//   Rationale: plugin template files are distributed and consumed across
+//   platforms; LF is the canonical line ending for the forge plugin. Two prior
+//   divergent implementations (build-base-pack.cjs and substitute-placeholders.cjs)
+//   differed in CRLF handling — this module resolves them to a single behavior.
+//
+//   To preserve CRLF on write, the caller must re-introduce \r\n explicitly;
+//   this module does not offer a write path.
+//
+// API:
+//   extractFrontmatter(content: string) → { frontmatter: string|null, body: string }
+//
+//   - frontmatter: the YAML block including both opening and closing ---
+//     delimiters, normalized to LF. null if no valid frontmatter found.
+//   - body: the content after the closing --- delimiter, normalized to LF.
+//     If no frontmatter found, body is the full input (LF-normalized).
+//
+// Opening --- MUST appear at column 0 (no leading whitespace).
+
+/**
+ * Extract YAML frontmatter from content.
+ *
+ * @param {string} content - Raw file content (any line ending style).
+ * @returns {{ frontmatter: string|null, body: string }}
+ */
+function extractFrontmatter(content) {
+  // Normalize all line endings to LF before any processing.
+  // This handles CRLF (\r\n), CR-only (\r), and mixed inputs uniformly.
+  const normalized = content.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+
+  // Opening --- must be at column 0, immediately followed by \n.
+  if (!normalized.startsWith('---\n') && normalized !== '---') {
+    return { frontmatter: null, body: normalized };
+  }
+
+  const lines = normalized.split('\n');
+
+  // Find the closing --- delimiter (must be on its own line, exact match).
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === '---') {
+      const frontmatterLines = lines.slice(0, i + 1);
+      const bodyLines = lines.slice(i + 1);
+
+      const frontmatter = frontmatterLines.join('\n') + '\n';
+      const body = bodyLines.join('\n');
+
+      return { frontmatter, body };
+    }
+  }
+
+  // No closing --- found — malformed frontmatter; return full normalized content as body.
+  return { frontmatter: null, body: normalized };
+}
+
+module.exports = { extractFrontmatter };

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

@@ -0,0 +1,61 @@
+'use strict';
+// lib/fsutil.cjs — filesystem utility helpers.
+//
+// DECISION (FORGE-S25-T07, closes T-5):
+//   Extracted from four inline mkdirSync sites across forge plugin tools:
+//   - tools/build-base-pack.cjs (private ensureDir function + 6 call sites)
+//   - tools/friction-emit.cjs (inline fs.mkdirSync)
+//   - tools/build-context-pack.cjs (2x inline fs.mkdirSync)
+//   - tools/build-manifest.cjs (inline fs.mkdirSync)
+//
+// API:
+//   ensureDir(dirPath: string) → void
+//     Creates the directory recursively if it does not exist. Idempotent.
+//
+//   isFile(filePath: string) → boolean
+//     Returns true if the path exists and is a regular file. Never throws.
+//
+//   isDirectory(dirPath: string) → boolean
+//     Returns true if the path exists and is a directory. Never throws.
+
+const fs = require('node:fs');
+
+/**
+ * Create a directory (and all intermediate parents) if it does not exist.
+ * Safe to call on an existing directory — no-op in that case.
+ *
+ * @param {string} dirPath - Absolute or relative directory path.
+ */
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+/**
+ * Check whether a path exists and is a regular file.
+ *
+ * @param {string} filePath - Path to test.
+ * @returns {boolean}
+ */
+function isFile(filePath) {
+  try {
+    return fs.statSync(filePath).isFile();
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Check whether a path exists and is a directory.
+ *
+ * @param {string} dirPath - Path to test.
+ * @returns {boolean}
+ */
+function isDirectory(dirPath) {
+  try {
+    return fs.statSync(dirPath).isDirectory();
+  } catch (_) {
+    return false;
+  }
+}
+
+module.exports = { ensureDir, isFile, isDirectory };

package/dist/forge-payload/tools/lib/json-io.cjs

@@ -0,0 +1,43 @@
+'use strict';
+// lib/json-io.cjs — shared JSON read/write primitives.
+//
+// Extracted from FSImpl._readJson / FSImpl._writeJson in tools/store.cjs so
+// any tool or hook can reuse them without taking a dependency on the full
+// store facade.
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Read and parse a JSON file.
+ *
+ * @param {string} filePath - absolute or cwd-relative path to the JSON file
+ * @returns {object|null} parsed object, or null if the file does not exist
+ * @throws {SyntaxError} if the file exists but contains invalid JSON (fail-fast)
+ */
+function readJson(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+/**
+ * Write an object to a JSON file with 2-space indentation and a trailing
+ * newline. Creates all parent directories as needed.
+ *
+ * Mirrors FSImpl._writeJson contract exactly so consumers can swap in this
+ * function without behavioural change.
+ *
+ * @param {string} filePath - absolute or cwd-relative path for the output file
+ * @param {object} data     - value to serialise
+ * @returns {object} the same `data` object that was written
+ */
+function 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;
+}
+
+module.exports = { readJson, writeJson };