@entelligentsia/forgecli 0.15.0 → 0.20.0

package/dist/forge-payload/hooks/post-init.cjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+'use strict';
+
+// Forge hook: post-init
+// PostToolUse hook that fires once at the END of a successful /forge:init
+// Phase 4 (NOT on Resume "start over" or stale-checkpoint cleanup) and
+// invokes /forge:enhance --phase 1 --auto.
+//
+// Trigger detection uses a positive end-of-flow signal: the hook matches
+// `rm -f .forge/init-progress.json` AND requires `.forge/structure-versions.json`
+// to exist (T05 writes it just before the terminal rm in Phase 4).
+//
+// Idempotency: a sentinel file under .forge/cache/ is the SOLE idempotency
+// guard. The mtime check (H-5c) has been removed — it was redundant and
+// fragile; the sentinel file is reliable enough. Because cache/ lives inside
+// .forge/, a manual `rm -rf .forge/` followed by re-init naturally clears
+// the sentinel.
+//
+// Fail-open: any internal error → stderr warning + exit 0. Hook failure must
+// never block /forge:init.
+
+process.on('uncaughtException', (err) => {
+  try { process.stderr.write(`forge post-init: internal error (fail-open): ${err.message}\n`); } catch (_) {}
+  process.exit(0);
+});
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { resolveForgePaths, logSwallowedError } = require('./lib/common.cjs');
+
+let raw = '';
+try { raw = fs.readFileSync(0, 'utf8'); } catch (_) { process.exit(0); }
+
+let envelope;
+try { envelope = JSON.parse(raw); } catch (_) { process.exit(0); }
+
+if (!envelope || envelope.tool_name !== 'Bash') process.exit(0);
+
+const exitCode = envelope.tool_response && envelope.tool_response.exitCode;
+if (exitCode !== 0 && exitCode !== undefined) process.exit(0);
+
+const command = (envelope.tool_input && envelope.tool_input.command) || '';
+
+// Primary trigger: terminal rm of init-progress.json.
+const TRIGGER_RX = /\brm\s+-f\s+\.forge\/init-progress\.json\b/;
+if (!TRIGGER_RX.test(command)) process.exit(0);
+
+const paths = resolveForgePaths();
+if (!paths) process.exit(0);
+
+// Secondary positive signal: structure-versions.json must exist. T05 writes
+// it just before the terminal rm in Phase 4. Resume "start over" /
+// stale-checkpoint cleanup branches do NOT touch structure-versions.json.
+// (H-5c: mtime check removed — sentinel file is the sole idempotency guard.)
+if (!fs.existsSync(paths.structureVersionsPath)) process.exit(0);
+
+// Idempotency: sentinel under .forge/cache/.
+try { fs.mkdirSync(paths.cacheDir, { recursive: true }); } catch (_) {}
+const sentinel = path.join(paths.cacheDir, 'post-init-enhancement-triggered');
+if (fs.existsSync(sentinel)) process.exit(0);
+
+// Build a unique eventId — pid + hrtime guards against same-second collisions
+// when two firings occur in the same wall-clock second.
+const iso = new Date().toISOString().replace(/[:.]/g, '');
+const eventId = `${iso}_enhance_trigger_phase1_${process.pid}_${process.hrtime.bigint()}`;
+
+const now = new Date().toISOString();
+const event = {
+  eventId,
+  taskId: 'enhancement',
+  sprintId: 'enhancement',
+  role: 'hook',
+  action: 'enhancement-trigger',
+  phase: 'post-init',
+  iteration: 1,
+  startTimestamp: now,
+  endTimestamp: now,
+  durationMinutes: 0,
+  model: 'n/a',
+  notes: JSON.stringify({
+    triggerSource: 'post-init',
+    targetPhase: 1,
+    detectedSprintId: 'n/a',
+  }),
+};
+
+// Emit via store-cli.cjs when forgeRoot is known. spawnSync timeout of 3s
+// caps the impact of a hung child process — outer hook timeout is 10s.
+try {
+  if (paths.forgeRoot) {
+    const eventsBucket = path.join(paths.eventsRoot, 'enhancement');
+    fs.mkdirSync(eventsBucket, { recursive: true });
+    const cli = path.join(paths.forgeRoot, 'tools', 'store-cli.cjs');
+    if (fs.existsSync(cli)) {
+      spawnSync('node', [cli, 'emit', 'enhancement', JSON.stringify(event)], {
+        cwd: process.cwd(),
+        timeout: 3000,
+        encoding: 'utf8',
+      });
+    }
+  }
+} catch (emitErr) { logSwallowedError('post-init:emit', emitErr, process.env.CLAUDE_PLUGIN_DATA); }
+
+// Write sentinel AFTER emit so a crash during emit allows a retry on next
+// firing (the user can re-run init if the first attempt failed).
+try { fs.writeFileSync(sentinel, '', 'utf8'); } catch (sentinelErr) { logSwallowedError('post-init:sentinel', sentinelErr, process.env.CLAUDE_PLUGIN_DATA); }
+
+// Inject the slash-command request into the next assistant turn.
+try {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PostToolUse',
+      additionalContext:
+        'Forge: /forge:init has completed Phase 4. Run /forge:enhance --phase 1 --auto to materialise project-specific starter-pack content from the freshly captured structural snapshot.',
+    },
+  }) + '\n');
+} catch (outputErr) { logSwallowedError('post-init:output', outputErr, process.env.CLAUDE_PLUGIN_DATA); }
+
+process.exit(0);

package/dist/forge-payload/hooks/post-sprint.cjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+'use strict';
+
+// Forge hook: post-sprint
+// PostToolUse hook that fires after a sprint retrospective completes
+// (`collate.cjs <SPRINT_ID> --purge-events` where the ID matches the
+// `*-S\d+` shape) and invokes /forge:enhance --phase 2.
+//
+// The sprint-ID shape gate ensures bug-fix invocations like
+// `collate.cjs FORGE-B07 --purge-events` (which run after every successful
+// bug fix) do NOT trigger sprint-level enhancement.
+//
+// Idempotency: a sprint-specific sentinel file under .forge/cache/ prevents
+// a second firing for the same sprint. Different sprints fire independently.
+//
+// Fail-open: any internal error → stderr warning + exit 0. Hook failure
+// must never block sprint completion.
+
+process.on('uncaughtException', (err) => {
+  try { process.stderr.write(`forge post-sprint: internal error (fail-open): ${err.message}\n`); } catch (_) {}
+  process.exit(0);
+});
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { resolveForgePaths, logSwallowedError } = require('./lib/common.cjs');
+
+let raw = '';
+try { raw = fs.readFileSync(0, 'utf8'); } catch (_) { process.exit(0); }
+
+let envelope;
+try { envelope = JSON.parse(raw); } catch (_) { process.exit(0); }
+
+if (!envelope || envelope.tool_name !== 'Bash') process.exit(0);
+
+const exitCode = envelope.tool_response && envelope.tool_response.exitCode;
+if (exitCode !== 0 && exitCode !== undefined) process.exit(0);
+
+const command = (envelope.tool_input && envelope.tool_input.command) || '';
+
+// Trigger: collate.cjs <PREFIX-S\d+> --purge-events. The capture group
+// extracts the sprint ID for the sentinel and event payload. The
+// `*-S\d+` shape rules out bug IDs like FORGE-B07.
+const TRIGGER_RX = /\bcollate\.cjs\s+(\S*-S\d+)\s+--purge-events\b/;
+const m = command.match(TRIGGER_RX);
+if (!m) process.exit(0);
+
+const detectedSprintId = m[1];
+
+const paths = resolveForgePaths();
+if (!paths) process.exit(0);
+
+try { fs.mkdirSync(paths.cacheDir, { recursive: true }); } catch (_) {}
+const sentinel = path.join(paths.cacheDir, `post-sprint-${detectedSprintId}-enhancement-triggered`);
+if (fs.existsSync(sentinel)) process.exit(0);
+
+const iso = new Date().toISOString().replace(/[:.]/g, '');
+const eventId = `${iso}_enhance_trigger_phase2_${process.pid}_${process.hrtime.bigint()}`;
+
+const now = new Date().toISOString();
+const event = {
+  eventId,
+  taskId: 'enhancement',
+  sprintId: 'enhancement',
+  role: 'hook',
+  action: 'enhancement-trigger',
+  phase: 'post-sprint',
+  iteration: 1,
+  startTimestamp: now,
+  endTimestamp: now,
+  durationMinutes: 0,
+  model: 'n/a',
+  notes: JSON.stringify({
+    triggerSource: 'post-sprint',
+    targetPhase: 2,
+    detectedSprintId,
+  }),
+};
+
+try {
+  if (paths.forgeRoot) {
+    const eventsBucket = path.join(paths.eventsRoot, 'enhancement');
+    fs.mkdirSync(eventsBucket, { recursive: true });
+    const cli = path.join(paths.forgeRoot, 'tools', 'store-cli.cjs');
+    if (fs.existsSync(cli)) {
+      spawnSync('node', [cli, 'emit', 'enhancement', JSON.stringify(event)], {
+        cwd: process.cwd(),
+        timeout: 3000,
+        encoding: 'utf8',
+      });
+    }
+  }
+} catch (emitErr) { logSwallowedError('post-sprint:emit', emitErr, process.env.CLAUDE_PLUGIN_DATA); }
+
+try { fs.writeFileSync(sentinel, '', 'utf8'); } catch (sentinelErr) { logSwallowedError('post-sprint:sentinel', sentinelErr, process.env.CLAUDE_PLUGIN_DATA); }
+
+try {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PostToolUse',
+      additionalContext:
+        `Forge: sprint ${detectedSprintId} retrospective has completed. Run /forge:enhance --phase 2 to propose KB enhancements derived from the sprint's lessons (proposals are written for review, not auto-applied).`,
+    },
+  }) + '\n');
+} catch (outputErr) { logSwallowedError('post-sprint:output', outputErr, process.env.CLAUDE_PLUGIN_DATA); }
+
+process.exit(0);

package/dist/forge-payload/hooks/triage-error.cjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+// Forge PostToolUse hook — error triage
+//
+// Fires after every Bash tool call. If the command is Forge-related and
+// exits non-zero, injects an additionalContext prompt asking Claude to offer
+// the user the option to file a bug via /forge:report-bug.
+//
+// Uses only Node.js built-ins — no npm dependencies required.
+
+'use strict';
+
+// FORGE_PATTERNS — inline copy of forge command recognition patterns.
+// Canonical source: hooks/lib/common.cjs:FORGE_COMMAND_PATTERNS (H-1d, FORGE-S25-T08).
+// This file intentionally does NOT require hooks/lib/common.cjs because
+// build-payload.cjs bundles hooks/*.cjs but excludes hooks/lib/ (forge-cli
+// bundle gap). When adding a new forge command, update BOTH this list AND
+// hooks/lib/common.cjs:FORGE_COMMAND_PATTERNS.
+const FORGE_PATTERNS = [
+  /manage-config/,
+  /\.forge\//,
+  /CLAUDE_PLUGIN_ROOT/,
+  /FORGE_ROOT/,
+  /MANAGE_CONFIG/,
+  /engineering\/tools\//,
+  /forge:init/,
+  /forge:health/,
+  /forge:regenerate/,
+  /forge:update/,
+  /forge:add-pipeline/,
+  /forge:add-task/,
+  /forge:plan/,
+  /forge:implement/,
+  /forge:approve/,
+  /forge:commit/,
+  /forge:review/,
+  /forge:sprint/,
+  /forge:run-task/,
+  /forge:run-sprint/,
+  /forge:fix-bug/,
+  /forge:retrospective/,
+  /forge:quiz-agent/,
+  /forge:report-bug/,
+  /forge:enhance/,
+  /forge:collate/,
+  /forge:validate/,
+  /forge:calibrate/,
+  /forge:materialize/,
+  /forge:remove/,
+  /forge:store-query/,
+  /forge:store-repair/,
+  /forge:store-custodian/,
+  /forge:config/,
+  /forge:ask/,
+  /forge:refresh-kb-links/,
+  /store-cli\.cjs/,
+  /validate-store\.cjs/,
+];
+
+function isForgeRelated(command) {
+  return FORGE_PATTERNS.some(p => p.test(command));
+}
+
+// The hook must never exit non-zero — a hook failure would surface as noise to
+// the user and defeat the purpose of silent triage. Wrap everything so that any
+// unexpected error causes a clean no-op exit instead of a crash report.
+process.on('uncaughtException', () => process.exit(0));
+
+let raw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => { raw += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const event = JSON.parse(raw);
+
+    if (event.tool_name !== 'Bash') return;
+
+    const command = event.tool_input?.command || '';
+    const exitCode = event.tool_response?.exitCode;
+
+    // Only act on non-zero exits for Forge-related commands.
+    if (!isForgeRelated(command)) return;
+    if (exitCode === 0 || exitCode === undefined) return;
+
+    const stderr = event.tool_response?.stderr || '';
+    const output = event.tool_response?.output || '';
+    const errorSnippet = (stderr || output).split('\n').slice(0, 3).join(' ').trim();
+
+    const context =
+      `FORGE_ERROR_TRIAGE: A Forge command just failed (exit ${exitCode}). ` +
+      (errorSnippet ? `First error line: "${errorSnippet}". ` : '') +
+      `Tell the user what went wrong, then ask: ` +
+      `"Would you like to file this as a Forge bug to help improve the tool? ` +
+      `Run /forge:report-bug and I will pre-fill the report from this conversation."`;
+
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext: context,
+      },
+    }) + '\n');
+  } catch {
+    // Swallow all errors — this hook must never become the problem.
+  }
+});

package/dist/forge-payload/hooks/triage-error.js

@@ -9,6 +9,12 @@
 
 'use strict';
 
+// FORGE_PATTERNS — inline copy of forge command recognition patterns.
+// Canonical source: hooks/lib/common.cjs:FORGE_COMMAND_PATTERNS (H-1d, FORGE-S25-T08).
+// This file intentionally does NOT require hooks/lib/common.cjs because
+// build-payload.cjs bundles hooks/*.js but excludes hooks/lib/ (forge-cli
+// bundle gap). When adding a new forge command, update BOTH this list AND
+// hooks/lib/common.cjs:FORGE_COMMAND_PATTERNS.
 const FORGE_PATTERNS = [
   /manage-config/,
   /\.forge\//,

package/dist/forge-payload/hooks/validate-write.cjs

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+// Forge write-boundary hook — runs PreToolUse on Write / Edit / MultiEdit.
+//
+// Purpose: enforce Forge schemas at the filesystem boundary so agents remain
+// free to bypass deterministic tools (store-cli), as long as any write they
+// do against Forge-owned paths honors the schema contract.
+//
+// Protocol (Claude Code PreToolUse hook):
+//   - stdin: JSON envelope { tool_name, tool_input, ... }
+//   - exit 0: allow the tool call
+//   - exit 2 with stderr payload: block the tool call and surface the message
+//
+// Fail-open philosophy: any internal error (unreadable schema, parse bug,
+// unexpected tool input shape) exits 0 with a stderr warning. A broken
+// validator must never block legitimate work — validate-store.cjs remains
+// as a post-hoc auditor.
+
+'use strict';
+
+process.on('uncaughtException', (err) => {
+  try { process.stderr.write(`forge validate-write: internal error (fail-open): ${err.message}\n`); } catch (_) {}
+  process.exit(0);
+});
+
+const fs = require('fs');
+const path = require('path');
+
+const { matchRegistry } = require('./lib/write-registry.js');
+
+// Schema resolution — delegates to lib/schema-loader.cjs which implements the
+// same 4-path search chain (project → in-tree → plugin-installed → bundled)
+// that store-cli.cjs uses. This ensures the hook sees the exact same schemas
+// as tool writes do, and gains the bundled .schemas/ lookup that the previous
+// inline loadSchema() was missing.
+const PLUGIN_ROOT = process.env.CLAUDE_PLUGIN_ROOT || path.join(__dirname, '..');
+
+function resolveValidator() {
+  // store-cli's shared validator lives at forge/tools/lib/validate.js. Require
+  // it relative to the plugin root so the hook works from both dev tree and
+  // installed plugin cache.
+  const candidates = [
+    path.join(PLUGIN_ROOT, 'tools', 'lib', 'validate.js'),
+    path.join(__dirname, '..', 'tools', 'lib', 'validate.js'),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return require(c);
+  }
+  throw new Error(`validate.js not found (looked in: ${candidates.join(', ')})`);
+}
+
+function resolveSchemaLoader() {
+  // schema-loader.cjs lives at forge/tools/lib/schema-loader.cjs. Resolve it
+  // relative to the plugin root so the hook works from both dev tree and
+  // installed plugin cache.
+  const candidates = [
+    path.join(PLUGIN_ROOT, 'tools', 'lib', 'schema-loader.cjs'),
+    path.join(__dirname, '..', 'tools', 'lib', 'schema-loader.cjs'),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return require(c);
+  }
+  throw new Error(`schema-loader.cjs not found (looked in: ${candidates.join(', ')})`);
+}
+
+function loadSchema(filename) {
+  // filename is e.g. "task.schema.json"; the schema-loader key is "task".
+  const typeKey = filename.replace(/\.schema\.json$/, '');
+  const { loadSchemas } = resolveSchemaLoader();
+  const schemas = loadSchemas();
+  const schema = schemas[typeKey];
+  if (!schema) {
+    throw new Error(`schema not found: ${filename}`);
+  }
+  return schema;
+}
+
+function readStdinSync() {
+  try {
+    return fs.readFileSync(0, 'utf8');
+  } catch (_) {
+    return '';
+  }
+}
+
+// Apply Edit semantics: replace old_string with new_string in contents.
+// If replace_all is true, replace every occurrence; otherwise replace the
+// first (and only) occurrence. Errors if old_string is absent or ambiguous
+// when replace_all is false — mirrors the Edit tool contract.
+function applyEdit(contents, oldStr, newStr, replaceAll) {
+  if (oldStr === '' && contents === '') return newStr; // new-file Edit
+  if (oldStr === '') throw new Error('Edit: old_string is empty');
+  if (replaceAll) return contents.split(oldStr).join(newStr);
+  const idx = contents.indexOf(oldStr);
+  if (idx === -1) throw new Error('Edit: old_string not found in file');
+  const next = contents.indexOf(oldStr, idx + oldStr.length);
+  if (next !== -1) throw new Error('Edit: old_string is ambiguous (appears more than once)');
+  return contents.slice(0, idx) + newStr + contents.slice(idx + oldStr.length);
+}
+
+function computePostEditContents(toolName, toolInput) {
+  const filePath = toolInput.file_path;
+  if (toolName === 'Write') {
+    return { filePath, contents: toolInput.content != null ? String(toolInput.content) : '' };
+  }
+  const prior = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+  if (toolName === 'Edit') {
+    return {
+      filePath,
+      contents: applyEdit(prior, toolInput.old_string || '', toolInput.new_string || '', !!toolInput.replace_all),
+    };
+  }
+  // MultiEdit
+  let cur = prior;
+  const edits = Array.isArray(toolInput.edits) ? toolInput.edits : [];
+  for (const e of edits) {
+    cur = applyEdit(cur, e.old_string || '', e.new_string || '', !!e.replace_all);
+  }
+  return { filePath, contents: cur, prior };
+}
+
+function parseProgressLine(line) {
+  // timestamp|agentName|bannerKey|status|detail
+  const parts = line.split('|');
+  if (parts.length < 4) return null;
+  return {
+    timestamp: parts[0],
+    agentName: parts[1],
+    bannerKey: parts[2],
+    status:    parts[3],
+    detail:    parts.slice(4).join('|'),
+  };
+}
+
+function validateProgressAppend(prior, proposed, validator, schema) {
+  // Only validate lines that are NEW — anything already on disk is grandfathered.
+  if (!proposed.startsWith(prior)) {
+    // Wholesale rewrite, not an append. Validate every non-empty line.
+    const lines = proposed.split('\n').filter(l => l.length > 0);
+    return lines.flatMap((l, i) => annotateLine(validator, schema, l, i));
+  }
+  const suffix = proposed.slice(prior.length);
+  const newLines = suffix.split('\n').filter(l => l.length > 0);
+  return newLines.flatMap((l, i) => annotateLine(validator, schema, l, i));
+}
+
+function annotateLine(validator, schema, line, idx) {
+  const rec = parseProgressLine(line);
+  if (!rec) return [`line ${idx + 1}: malformed (expected 4+ pipe-delimited fields)`];
+  const errors = validator.validateRecord(rec, schema);
+  return errors.map(e => `line ${idx + 1}: ${e}`);
+}
+
+function writeBypassAudit(filePath, reason) {
+  try {
+    const m = /\/\.forge\/store\/events\/([^/]+)\//.exec(filePath) || /\.forge\/store\/events\/([^/]+)\//.exec(filePath);
+    const bucket = m ? m[1] : 'unknown';
+    const logPath = path.join(process.cwd(), '.forge', 'store', 'events', bucket, 'progress.log');
+    if (!fs.existsSync(path.dirname(logPath))) return;
+    const ts = new Date().toISOString();
+    const line = `${ts}|forge-hook|write-boundary|progress|${reason}\n`;
+    fs.appendFileSync(logPath, line, 'utf8');
+  } catch (_) { /* audit best-effort */ }
+}
+
+function block(message) {
+  process.stderr.write(message + '\n');
+  process.exit(2);
+}
+
+function main() {
+  const raw = readStdinSync();
+  if (!raw) process.exit(0);
+
+  let envelope;
+  try { envelope = JSON.parse(raw); } catch (_) { process.exit(0); }
+
+  const toolName = envelope.tool_name;
+  if (!['Write', 'Edit', 'MultiEdit'].includes(toolName)) process.exit(0);
+
+  const toolInput = envelope.tool_input || {};
+  const filePath = toolInput.file_path;
+  if (!filePath || typeof filePath !== 'string') process.exit(0);
+
+  const entry = matchRegistry(filePath);
+  if (!entry) process.exit(0);
+
+  if (process.env.FORGE_SKIP_WRITE_VALIDATION === '1') {
+    writeBypassAudit(filePath, `FORGE_SKIP_WRITE_VALIDATION=1 bypass on ${toolName} ${path.relative(process.cwd(), filePath)}`);
+    process.exit(0);
+  }
+
+  let validator, schema, post;
+  try {
+    validator = resolveValidator();
+    schema = loadSchema(entry.schema);
+    post = computePostEditContents(toolName, toolInput);
+  } catch (err) {
+    process.stderr.write(`forge validate-write: setup error (fail-open): ${err.message}\n`);
+    process.exit(0);
+  }
+
+  const relPath = path.relative(process.cwd(), post.filePath);
+
+  if (entry.format === 'line-pipe-delimited') {
+    const prior = post.prior != null ? post.prior : (fs.existsSync(post.filePath) ? fs.readFileSync(post.filePath, 'utf8') : '');
+    const errs = validateProgressAppend(prior, post.contents, validator, schema);
+    if (errs.length > 0) {
+      block(
+        '❌ Forge schema violation — write blocked\n' +
+        `Path: ${relPath}\n` +
+        `Kind: ${entry.kind}\n` +
+        `Violations:\n  - ${errs.join('\n  - ')}\n` +
+        `Hint: progress.log lines must be "timestamp|agentName|bannerKey|status|detail"; see forge/schemas/${entry.schema}.\n` +
+        'To bypass for one turn (emergency repair): FORGE_SKIP_WRITE_VALIDATION=1.'
+      );
+    }
+    process.exit(0);
+  }
+
+  // JSON payloads
+  let parsed;
+  try {
+    parsed = JSON.parse(post.contents);
+  } catch (err) {
+    block(
+      '❌ Forge schema violation — write blocked\n' +
+      `Path: ${relPath}\n` +
+      `Kind: ${entry.kind}\n` +
+      `Violation: Invalid JSON: ${err.message}\n` +
+      `Hint: see forge/schemas/${entry.schema} for the expected shape.\n` +
+      'To bypass for one turn (emergency repair): FORGE_SKIP_WRITE_VALIDATION=1.'
+    );
+  }
+
+  const errs = validator.validateRecord(parsed, schema);
+  if (errs.length > 0) {
+    block(
+      '❌ Forge schema violation — write blocked\n' +
+      `Path: ${relPath}\n` +
+      `Kind: ${entry.kind}\n` +
+      `Violations:\n  - ${errs.join('\n  - ')}\n` +
+      `Hint: see forge/schemas/${entry.schema} for the full shape.\n` +
+      'To bypass for one turn (emergency repair): FORGE_SKIP_WRITE_VALIDATION=1.'
+    );
+  }
+
+  process.exit(0);
+}
+
+main();

package/dist/forge-payload/hooks/validate-write.js

@@ -27,8 +27,11 @@ const path = require('path');
 
 const { matchRegistry } = require('./lib/write-registry.js');
 
-// Schema resolution order mirrors store-cli.cjs so the hook sees the exact
-// same schemas as tool writes do.
+// Schema resolution — delegates to lib/schema-loader.cjs which implements the
+// same 4-path search chain (project → in-tree → plugin-installed → bundled)
+// that store-cli.cjs uses. This ensures the hook sees the exact same schemas
+// as tool writes do, and gains the bundled .schemas/ lookup that the previous
+// inline loadSchema() was missing.
 const PLUGIN_ROOT = process.env.CLAUDE_PLUGIN_ROOT || path.join(__dirname, '..');
 
 function resolveValidator() {
@@ -45,19 +48,30 @@ function resolveValidator() {
   throw new Error(`validate.js not found (looked in: ${candidates.join(', ')})`);
 }
 
-function loadSchema(filename) {
+function resolveSchemaLoader() {
+  // schema-loader.cjs lives at forge/tools/lib/schema-loader.cjs. Resolve it
+  // relative to the plugin root so the hook works from both dev tree and
+  // installed plugin cache.
   const candidates = [
-    path.join(process.cwd(), '.forge', 'schemas', filename),
-    path.join(process.cwd(), 'forge', 'schemas', filename),
-    path.join(PLUGIN_ROOT, 'schemas', filename),
-    path.join(__dirname, '..', 'schemas', filename),
+    path.join(PLUGIN_ROOT, 'tools', 'lib', 'schema-loader.cjs'),
+    path.join(__dirname, '..', 'tools', 'lib', 'schema-loader.cjs'),
   ];
   for (const c of candidates) {
-    if (fs.existsSync(c)) {
-      return JSON.parse(fs.readFileSync(c, 'utf8'));
-    }
+    if (fs.existsSync(c)) return require(c);
+  }
+  throw new Error(`schema-loader.cjs not found (looked in: ${candidates.join(', ')})`);
+}
+
+function loadSchema(filename) {
+  // filename is e.g. "task.schema.json"; the schema-loader key is "task".
+  const typeKey = filename.replace(/\.schema\.json$/, '');
+  const { loadSchemas } = resolveSchemaLoader();
+  const schemas = loadSchemas();
+  const schema = schemas[typeKey];
+  if (!schema) {
+    throw new Error(`schema not found: ${filename}`);
   }
-  throw new Error(`schema not found: ${filename}`);
+  return schema;
 }
 
 function readStdinSync() {