@entelligentsia/forgecli 0.11.3 → 0.19.0

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

@@ -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/integrity.json

@@ -0,0 +1,38 @@
+{
+  "version": "0.51.1",
+  "generated": "2026-05-23",
+  "note": "Tamper-evident only. Authoritative source: /forge:update from remote.",
+  "files": {
+    "commands/add-pipeline.md": "402c1deb6f19ad99561b48548ad89e3e1f625b827dce633eb84317556c0a1a4a",
+    "commands/add-task.md": "b2640c4b3c8c4fb9d4a82633d8c4d8fcd13bd63d4d6deb2c5c6a2008508de770",
+    "commands/ask.md": "df15f0aa68c93d65bfef05adb514c377bfc65617cafcd79534eb9b4149302657",
+    "commands/calibrate.md": "c764e735c9212eaf785d3d0afaf926f536fef099421b2b1bde7a4b1e3114d443",
+    "commands/config.md": "67251316b806d706bb77f063128e29995c6b4abaf554f4d5558bd97a1a6cfcfe",
+    "commands/enhance.md": "4bbfc05cf85c862c49883bc36f1272f87cd49c8cbe00f9196e76d542e6eaa720",
+    "commands/health.md": "31fdc6e01529b0ee8cfea4a4937e140bacec78f273260d5406108f8be1bf7aea",
+    "commands/init.md": "3c0522294c692e8fbb75f925370caee66f54b23d7dd3a692bedcd69f95718b28",
+    "commands/materialize.md": "195292c9e98f50773c1b0c84f9bbc42438c4c8c989a84bd98092f6692799d6d6",
+    "commands/migrate.md": "b226f10a6f202bfd4a840314f34d503da34a077abbf1dff8d2b40f864474a76b",
+    "commands/quiz-agent.md": "ed261a5c8ac7cd3a1d7c8b372c9bf099bba9a4f9dc0a41cb5c80f22b57a133a1",
+    "commands/regenerate.md": "7c14f87b1bb178dd98ebdf0efafb86792c2b8b079bc5052d02a7e618165ec525",
+    "commands/remove.md": "de8802ee8ad5db4c4f3d0f526eb8735ab7de1a4b8ad307355d11dac5e1e04fc6",
+    "commands/report-bug.md": "af8a54bf8887b35e5c880898dd45783f6c2e80d3dc031d6479a6be613ac43053",
+    "commands/store-query.md": "28925bd257ceb6645254628abf0e76524481460382192ea00081b17310b88fed",
+    "commands/store-repair.md": "9317be65deb400953b8642b4d353d5583d3b032546c0b8f73d6c3a9b3445ebdd",
+    "commands/update-tools.md": "768c0d7ec07a17055c3d4b1b31370812f4292e03b1496723ba36f8caf596a609",
+    "commands/update.md": "6f7be76884888b0cbbe5e60a6926bbaa368f2ee3191f2be40adc8d263ad414aa",
+    "agents/store-query-validator.md": "f4c3573edcf6e28809515705362df611806a805c5269404fb17e31433cf3a81c",
+    "agents/tomoshibi.md": "0112604af0856235d7f028683dbfa3f4af63355cb2dd79d26592e983a6ecec8b",
+    "hooks/check-update.cjs": "e66a03eeca609c7426ba7ab8502d41a10b4d740861a6f9728e8ca1e49db8c86a",
+    "hooks/forge-permissions.cjs": "8de18fe7e6c9ee1751926275a37f4bb68a5a53090d366d2aa44157c106e7857e",
+    "hooks/post-init.cjs": "c82bc76e846708a471acfbbc6839f341be843a3fb8d711e3a0f2733aa3da9b3d",
+    "hooks/post-sprint.cjs": "21099458fcde372f0f40895447ea76318de88d2a857d764f8fbbd0adab3ad74a",
+    "hooks/triage-error.cjs": "f33e4fd67168c437d55d059f67cf893f1d11b59df4c712153a1dfd7d9bb55930",
+    "hooks/validate-write.cjs": "3ec7bbbb2cc19f22c78da5a9e7b5031066f4b669c76a10c9f8a92a1a48fcea0a",
+    "schemas/transitions/bug.json": "27b17da42d1cebffbd4f61ab3dcd432a0017aa71997d548ed80d22c2fc3fad6a",
+    "schemas/transitions/sprint.json": "2e0a629396e687b0ca88e1814ac3e35d84533a5d55b25237ab67feddce3c9deb",
+    "schemas/transitions/task.json": "4c71849747baa0d585756e57c56325ff6219c078178374e60815dff91e25e3e7",
+    "schemas/enum-catalog.json": "db3ae83b313b5cea9186b3e28f8290daa1f562afd610d4ce9d1e52abbd0b13a4",
+    "tools/verify-integrity.cjs": "3ec3c970dd3d7c3001f8f373bcc40556803eadd2fc2afafb14f1c232cba4cc3f"
+  }
+}

package/dist/forge-payload/meta/workflows/_fragments/generation-instructions.md

@@ -0,0 +1,81 @@
+# Fragment: Generation Instructions — Structural Template Guide
+
+> **Pattern:** This fragment is a template guide, not a verbatim include.  
+> Each workflow's `## Generation Instructions` section is kept inline because the
+> content is workflow-specific (slug names, persona paths, project-specific markers,
+> and stack commands vary per workflow). Use this guide to ensure every `## Generation
+> Instructions` section has the required subsections in the required order.
+>
+> **Distinction from verbatim fragments:** CM-6 (Generation Instructions repetition)
+> is closed-as-documented, not closed-as-deduplicated. The prose stays inline; this
+> guide documents the canonical template so future authors follow the same structure.
+> See `doc/decisions/meta-fragment-includes.md`.
+
+---
+
+## Required subsection order
+
+```markdown
+## Generation Instructions
+
+- **Persona Self-Load:** (if applicable — see below)
+- **Workflow Structure:** The generated `{slug}.md` must follow the strict "Algorithm" block format.
+- **Markers:** (if applicable — see kickoff-shim marker requirements)
+- **Context Isolation:** Forbid inline execution of {domain}; use the `Agent` tool for sub-tasks.
+- **Project Specifics:**
+  - {stack-specific notes}
+- **Token Reporting:** See `_fragments/finalize.md` — wire via `file_ref:`.
+- **Event Emission:** Ensure the "complete" event includes the `eventId` passed by the orchestrator.
+```
+
+### Subsection definitions
+
+**`Persona Self-Load`** — *conditional*. Required when the generated workflow uses the
+Persona Self-Load pattern (the generated file must begin by reading a persona `.md` file
+before any other tool use). Specify the exact persona path. Used in: `meta-collate.md`,
+`meta-retrospective.md`, `meta-review-sprint-completion.md`, `meta-sprint-intake.md`,
+`meta-sprint-plan.md`. Omit for subagent-targeted workflows where the persona is loaded
+by the orchestrator before dispatch.
+
+**`Workflow Structure`** — *required*. Names the generated file slug and asserts the
+"Algorithm" block format. Format: `The generated \`{slug}.md\` must follow the strict "Algorithm" block format.`
+
+**`Markers`** — *conditional*. Required when a kickoff shim validates structural markers
+in the generated workflow (e.g., presence of `## Iron Laws`, `## Store-Write Verification`,
+`forge_store` token, persona path). Omit when no kickoff shim validates the output.
+
+**`Context Isolation`** — *required*. Names the domain-specific operation that must NOT
+run inline, and mandates the `Agent` tool for sub-tasks.
+
+**`Project Specifics`** — *required*. One or more bullets describing the project-context
+substitutions the generator must embed (stack commands, KB paths, template references,
+task ID format, etc.).
+
+**`Token Reporting`** — *required* (with one exception: `meta-quiz-agent.md` omits it
+because quiz-agent is an inline helper, not an orchestrated phase). Standard form: `See
+\`_fragments/finalize.md\` — wire via \`file_ref:\`.` Expanded token-reporting prose is
+used in workflows where the generated file must mandate a specific sidecar-emit sequence
+(retrospective, sprint-intake, sprint-plan, review-sprint-completion) — in those cases,
+the full expanded form lives inline.
+
+**`Event Emission`** — *required* (same exception as Token Reporting). Standard form:
+`Ensure the "complete" event includes the \`eventId\` passed by the orchestrator.`
+
+---
+
+## Orchestrator-special cases
+
+`meta-fix-bug.md` and `meta-orchestrate.md` have Generation Instructions that contain
+workflow-specific structural requirements (role-to-noun mapping, PERSONA_MAP, spawn
+patterns, fault tolerance rules). These cannot be collapsed into the standard subsection
+template. Their Generation Instructions are long-form inline prose.
+
+---
+
+## Byte-budget note
+
+A standard Generation Instructions section (five subsections, no expanded token reporting)
+contributes approximately 350–450 bytes. Sections with expanded token-reporting prose
+(sprint-intake, retrospective) may reach 700–900 bytes. Byte budgets in
+`phase-frontmatter.test.cjs` must be set ≥ the actual byte count of the file (with
+≤ 512 bytes headroom).