forge-workflow 0.1.0-beta.4 → 0.1.0-beta.6

package/scripts/sync-agent-skills.js

@@ -1,26 +1,21 @@
 #!/usr/bin/env node
 'use strict';
 
-/**
- * Pre-commit auto-sync for the committed `.agents/skills` mirror.
- *
- * `.agents/skills` is Codex's repo-local discovery path and the ONE skill mirror
- * committed to the repo (so a teammate who clones WITHOUT running `forge setup`
- * still gets Forge skills/stages auto-discovered). It must stay byte-identical to
- * the canonical `skills/` source, which the structural drift gate enforces.
- *
- * This hook removes the regen friction: whenever `skills/**` is staged, it
- * regenerates `.agents/skills` from `skills/` (reusing the same
- * `populateCodexRepoSkills` / `populateAgentSkills` sync the drift gate checks
- * against) and re-stages it, so the committed mirror never drifts from canonical.
- *
- * It is intentionally scoped to `skills/**` via lefthook's `glob`, so it only runs
- * when the canonical source actually changes.
- */
+/** Command-owned pre-commit sync for the committed `.agents/skills` mirror. */
 
+const fs = require('node:fs');
 const path = require('node:path');
 const { execFileSync } = require('node:child_process');
 const { populateCodexRepoSkills, resolveCodexRepoSkillsDir } = require('../lib/codex-skills');
+const { gitIgnoredCanonicalPaths, isValidSkillName, listCanonicalSkills } = require('../lib/skills-sync');
+const {
+  completeGeneratedHarnessSkillAuthorization,
+  issueGeneratedHarnessSkillAuthorization,
+} = require('../lib/protected-state-authority');
+
+function strictIgnoredCanonicalPaths(root, runGit) {
+  return gitIgnoredCanonicalPaths(root, runGit, { strict: true });
+}
 
 function repoRoot() {
   try {
@@ -33,30 +28,334 @@ function repoRoot() {
   }
 }
 
-function main() {
-  const root = repoRoot();
-  let written = [];
-  try {
-    // clean: true so skills removed from canonical are dropped from the mirror too.
-    ({ written } = populateCodexRepoSkills({ sourceRoot: root, projectRoot: root, clean: true }));
-  } catch (error) {
-    console.error(`sync-agent-skills: failed to regenerate .agents/skills — ${error.message}`);
-    process.exit(1);
+function actorFromEnv(env) {
+  return env.FORGE_ACTOR || env.USER || env.USERNAME || 'unknown';
+}
+
+function parseGitPaths(output) {
+  return output.split('\0').filter(Boolean);
+}
+
+function toRepoPath(value) {
+  return path.sep === '\\' ? value.replace(/\\/g, '/') : value;
+}
+
+function generatedDriftPaths(root, runGit) {
+  const commands = [
+    ['diff', '--cached', '--name-only', '-z', '--diff-filter=ACMRDT', '--', '.agents/skills'],
+    ['diff', '--name-only', '-z', '--diff-filter=ACMRDT', '--', '.agents/skills'],
+    ['ls-files', '-z', '--others', '--exclude-standard', '--', '.agents/skills'],
+  ];
+  return new Set(commands.flatMap(args => parseGitPaths(runGit('git', args, {
+    cwd: root,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }))));
+}
+
+function gitObjectHash(root, args, content, runGit) {
+  const hash = runGit('git', ['hash-object', ...args, '--stdin'], {
+    cwd: root,
+    encoding: 'utf8',
+    input: content,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  }).trim();
+  if (!/^[0-9a-f]{40,64}$/.test(hash)) throw new Error('Git returned an invalid object hash while inspecting canonical skill parity');
+  return hash;
+}
+
+function worktreeMatchesIndex(root, repoPath, indexedContent, worktreeContent, runGit) {
+  return gitObjectHash(root, [], indexedContent, runGit)
+    === gitObjectHash(root, [`--path=${repoPath}`], worktreeContent, runGit);
+}
+
+function normalizedRepoPath(repoPath) {
+  return repoPath.normalize('NFC');
+}
+
+function recordNormalizedPath(paths, repoPath) {
+  const key = normalizedRepoPath(repoPath);
+  const existing = paths.get(key);
+  if (existing && existing !== repoPath) throw new Error(`Unicode-equivalent canonical skill paths are ambiguous: ${existing}, ${repoPath}`);
+  paths.set(key, repoPath);
+}
+
+function ambiguousCanonicalPaths(root, runGit) {
+  const indexedEntries = parseGitPaths(runGit('git', ['ls-files', '-t', '-z', '--', 'skills'], {
+    cwd: root,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }));
+  const mirrorSkipWorktree = new Set(parseGitPaths(runGit('git', ['ls-files', '-t', '-z', '--', '.agents/skills'], {
+    cwd: root,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })).filter(entry => entry.startsWith('S ')).map(entry => normalizedRepoPath(entry.slice(2))));
+  const ignoredWorktree = strictIgnoredCanonicalPaths(root, runGit);
+  const filesystemPrefixes = listCanonicalSkills(root).map(({ name }) => `skills/${name}/`);
+  const canonicalPrefixKeys = new Set(filesystemPrefixes.map(normalizedRepoPath));
+  for (const entry of indexedEntries) {
+    const match = /^skills\/([^/]+)\/SKILL\.md$/.exec(entry.slice(2));
+    if (match && isValidSkillName(match[1])) canonicalPrefixKeys.add(normalizedRepoPath(`skills/${match[1]}/`));
+  }
+  const participatesInMirror = repoPath => [...canonicalPrefixKeys].some(prefix => normalizedRepoPath(repoPath).startsWith(prefix));
+  const indexed = new Map();
+  for (const repoPath of indexedEntries.map(entry => entry.slice(2)).filter(participatesInMirror)) recordNormalizedPath(indexed, repoPath);
+  const skipWorktree = new Map();
+  for (const repoPath of indexedEntries
+    .filter(entry => entry.startsWith('S '))
+    .map(entry => entry.slice(2))
+    .filter(participatesInMirror)) recordNormalizedPath(skipWorktree, repoPath);
+  const worktree = new Map();
+  for (const prefix of filesystemPrefixes) {
+    const sourceRoot = path.join(root, prefix);
+    walkRegularFiles(
+      sourceRoot,
+      (_file, relative) => recordNormalizedPath(worktree, `${prefix}${relative}`),
+      sourceRoot,
+      (relative, entry) => entry.isSymbolicLink()
+        && ignoredWorktree.has(normalizedRepoPath(`${prefix}${relative}`)),
+    );
+  }
+  for (const key of ignoredWorktree) {
+    if (!indexed.has(key)) worktree.delete(key);
   }
+  for (const repoPath of skipWorktree.values()) {
+    const mirrorPath = `.agents/${repoPath}`;
+    if (!fs.existsSync(path.join(root, repoPath))
+      && (!mirrorSkipWorktree.has(normalizedRepoPath(mirrorPath)) || fs.existsSync(path.join(root, mirrorPath)))) {
+      throw new Error(`asymmetric sparse checkout exposes mirror without canonical: ${repoPath}`);
+    }
+  }
+  const paths = new Set([...indexed.keys(), ...worktree.keys()]);
+  return new Set([...paths].filter(key => {
+    const indexedPath = indexed.get(key);
+    const worktreePath = worktree.get(key);
+    const indexedContent = indexedPath ? indexedFile(root, indexedPath, runGit) : null;
+    let worktreeContent = null;
+    try {
+      if (worktreePath) worktreeContent = fs.readFileSync(path.join(root, worktreePath));
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+    return indexedContent === null
+      ? worktreeContent !== null
+      : (worktreeContent === null && !skipWorktree.has(key))
+        || (worktreeContent !== null && !worktreeMatchesIndex(root, indexedPath, indexedContent, worktreeContent, runGit));
+  }).map(key => indexed.get(key) || worktree.get(key)));
+}
+
+function indexedFile(root, repoPath, runGit) {
+  const tracked = parseGitPaths(runGit('git', ['ls-files', '-z', '--', `:(literal)${repoPath}`], {
+    cwd: root,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }));
+  const trackedPath = tracked.find(candidate => normalizedRepoPath(candidate) === normalizedRepoPath(repoPath));
+  if (!trackedPath) return null;
+  return runGit('git', ['show', `:${trackedPath}`], {
+    cwd: root,
+    encoding: null,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+function walkRegularFiles(root, visit, current = root, shouldSkip = () => false) {
+  if (!fs.existsSync(current)) return;
+  const currentStat = fs.lstatSync(current);
+  if (!currentStat.isDirectory() || currentStat.isSymbolicLink()) throw new Error(`skill sync path is not a real directory: ${current}`);
+  for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+    const entryPath = path.join(current, entry.name);
+    const relative = toRepoPath(path.relative(root, entryPath));
+    if (shouldSkip(relative, entry)) continue;
+    const stat = fs.lstatSync(entryPath);
+    if (stat.isSymbolicLink()) throw new Error(`skill sync refuses symlink: ${entryPath}`);
+    if (stat.isDirectory()) walkRegularFiles(root, visit, entryPath, shouldSkip);
+    else if (stat.isFile()) visit(entryPath, relative);
+  }
+}
 
+function rejectIgnoredSkillDescriptors(root, ignoredCanonical) {
+  for (const { name } of listCanonicalSkills(root)) {
+    const descriptorRepoPath = `skills/${name}/SKILL.md`;
+    if (ignoredCanonical.has(normalizedRepoPath(descriptorRepoPath))) {
+      throw new Error(`ignored canonical skill descriptor: ${descriptorRepoPath}`);
+    }
+  }
+}
+
+function changedSkillFiles(root, runGit = execFileSync, ignoredCanonical = strictIgnoredCanonicalPaths(root, runGit)) {
   const mirror = resolveCodexRepoSkillsDir(root);
-  try {
-    // Stage the regenerated mirror (and any deletions within it).
-    execFileSync('git', ['add', '--all', '--', mirror], {
-      cwd: root,
-      stdio: ['ignore', 'ignore', 'inherit'],
+  const drift = generatedDriftPaths(root, runGit);
+  const changed = [];
+  rejectIgnoredSkillDescriptors(root, ignoredCanonical);
+  for (const { name, sourcePath: sourceRoot } of listCanonicalSkills(root)) {
+    walkRegularFiles(sourceRoot, (sourcePath, relative) => {
+      const canonicalRepoPath = `skills/${name}/${relative}`;
+      if (ignoredCanonical.has(normalizedRepoPath(canonicalRepoPath))) {
+        const mirrorRepoPath = `.agents/${canonicalRepoPath}`;
+        if (indexedFile(root, mirrorRepoPath, runGit) !== null || fs.existsSync(path.join(root, mirrorRepoPath))) {
+          throw new Error(`ignored canonical skill path still has a mirror: ${canonicalRepoPath}`);
+        }
+        return;
+      }
+      const canonical = fs.readFileSync(sourcePath);
+      const mirrorPath = path.join(mirror, name, relative);
+      const repoPath = `.agents/skills/${name}/${relative}`;
+      const indexedCanonical = indexedFile(root, canonicalRepoPath, runGit);
+      if (indexedCanonical !== null
+        && gitObjectHash(root, [], indexedCanonical, runGit)
+          !== gitObjectHash(root, [`--path=${repoPath}`], canonical, runGit)) {
+        throw new Error(`canonical and generated mirror clean filters differ: ${canonicalRepoPath}`);
+      }
+      try {
+        if (canonical.equals(fs.readFileSync(mirrorPath)) && !drift.has(repoPath)) return;
+      } catch (error) {
+        if (error.code !== 'ENOENT') throw error;
+      }
+      changed.push({ path: repoPath, canonical, writeIntent: 'update' });
+    }, sourceRoot, (relative, entry) => entry.isSymbolicLink()
+      && ignoredCanonical.has(normalizedRepoPath(`skills/${name}/${relative}`)));
+  }
+  walkRegularFiles(mirror, (mirrorPath, relative) => {
+    const canonicalPath = path.join(root, 'skills', relative);
+    if (!fs.existsSync(canonicalPath)) {
+      changed.push({
+        path: `.agents/skills/${relative}`,
+        canonical: fs.readFileSync(mirrorPath),
+        writeIntent: 'delete',
+      });
+    }
+  });
+  const seen = new Set(changed.map(file => file.path));
+  for (const repoPath of drift) {
+    if (!repoPath.startsWith('.agents/skills/') || seen.has(repoPath)) continue;
+    const relative = repoPath.slice('.agents/skills/'.length);
+    const canonicalPath = path.join(root, 'skills', relative);
+    const mirrorPath = path.join(root, repoPath);
+    if (fs.existsSync(canonicalPath) || fs.existsSync(mirrorPath)) continue;
+    let priorContent;
+    try {
+      priorContent = runGit('git', ['show', `HEAD:${repoPath}`], {
+        cwd: root,
+        encoding: null,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } catch {
+      continue;
+    }
+    changed.push({ path: repoPath, canonical: priorContent, writeIntent: 'delete' });
+  }
+  return changed;
+}
+
+function sameSkillChanges(expected, actual) {
+  if (expected.length !== actual.length) return false;
+  const byPath = new Map(actual.map(file => [normalizedRepoPath(file.path), file]));
+  if (byPath.size !== actual.length) return false;
+  return expected.every(file => {
+    const candidate = byPath.get(normalizedRepoPath(file.path));
+    return candidate
+      && candidate.writeIntent === file.writeIntent
+      && candidate.canonical.equals(file.canonical);
+  });
+}
+
+async function syncAgentSkills(options = {}) {
+  const root = options.root || repoRoot();
+  const env = options.env || process.env;
+  const runGit = options.execFileSync || execFileSync;
+  const issueAuthorization = options.issueAuthorization || issueGeneratedHarnessSkillAuthorization;
+  const completeAuthorization = options.completeAuthorization || completeGeneratedHarnessSkillAuthorization;
+  const actor = actorFromEnv(env);
+  const sourceHead = runGit('git', ['rev-parse', '--verify', 'HEAD^{commit}'], {
+    cwd: root,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim();
+  if (!/^[0-9a-f]{40}$/.test(sourceHead)) throw new Error('source HEAD is not a full lowercase commit SHA');
+
+  const ignoredCanonical = strictIgnoredCanonicalPaths(root, runGit);
+  rejectIgnoredSkillDescriptors(root, ignoredCanonical);
+  const ambiguousCanonical = ambiguousCanonicalPaths(root, runGit);
+  for (const canonicalPath of ambiguousCanonical) {
+    const indexedCanonical = indexedFile(root, canonicalPath, runGit);
+    const indexedMirror = indexedFile(root, `.agents/${canonicalPath}`, runGit);
+    if (indexedCanonical === null ? indexedMirror !== null : indexedMirror === null || !indexedCanonical.equals(indexedMirror)) {
+      throw new Error(`canonical index differs from generated mirror index: ${canonicalPath}`);
+    }
+  }
+  if (ambiguousCanonical.size > 0) {
+    throw new Error(`unstaged canonical skill changes must be reconciled before mirror sync: ${[...ambiguousCanonical].join(', ')}`);
+  }
+
+  const changed = changedSkillFiles(root, runGit, ignoredCanonical);
+  const authorizations = [];
+  for (const file of changed) {
+    const authorization = await issueAuthorization(root, {
+      actor,
+      path: file.path,
+      sourceHead,
+      writeIntent: file.writeIntent,
+      ...(file.writeIntent === 'delete' ? { priorContent: file.canonical } : {}),
     });
-  } catch (error) {
-    console.error(`sync-agent-skills: failed to stage .agents/skills — ${error.message}`);
-    process.exit(1);
+    if (!authorization.success) throw new Error(`authorization failed for ${file.path}: ${authorization.error}`);
+    authorizations.push({ ...file, capabilityId: authorization.capabilityId });
+  }
+
+  const refreshedIgnoredCanonical = strictIgnoredCanonicalPaths(root, runGit);
+  rejectIgnoredSkillDescriptors(root, refreshedIgnoredCanonical);
+  const refreshedAmbiguousCanonical = ambiguousCanonicalPaths(root, runGit);
+  if (refreshedAmbiguousCanonical.size > 0) {
+    throw new Error(`canonical skill state changed during authorization: ${[...refreshedAmbiguousCanonical].join(', ')}`);
+  }
+  const refreshedChanged = changedSkillFiles(root, runGit, refreshedIgnoredCanonical);
+  if (!sameSkillChanges(changed, refreshedChanged)) {
+    throw new Error('canonical skill state changed during authorization');
+  }
+
+  const excludeRelativePaths = new Set([...refreshedIgnoredCanonical]
+    .map(repoPath => repoPath.slice('skills/'.length)));
+  const { written } = populateCodexRepoSkills({
+    sourceRoot: root,
+    projectRoot: root,
+    clean: true,
+    excludeRelativePaths,
+  });
+  for (const file of authorizations) {
+    const mirrorExists = fs.existsSync(path.join(root, file.path));
+    if (file.writeIntent === 'delete' ? mirrorExists : !file.canonical.equals(fs.readFileSync(path.join(root, file.path)))) {
+      throw new Error(`canonical mirror intent failed for ${file.path}`);
+    }
+    const completion = await completeAuthorization(root, {
+      actor,
+      path: file.path,
+      sourceHead,
+      capabilityId: file.capabilityId,
+      writeIntent: file.writeIntent,
+      ...(file.writeIntent === 'delete' ? { priorContent: file.canonical } : {}),
+    });
+    if (!completion.success) throw new Error(`completion failed for ${file.path}: ${completion.error}`);
   }
 
+  const mirror = resolveCodexRepoSkillsDir(root);
+  runGit('git', ['add', '--all', '--', mirror], {
+    cwd: root,
+    stdio: ['ignore', 'ignore', 'inherit'],
+  });
   console.log(`sync-agent-skills: .agents/skills in sync with skills/ (${written.length} skills)`);
+  return { written, changed: changed.map(file => file.path), deferred: [], sourceHead };
 }
 
-main();
+async function main() {
+  try {
+    await syncAgentSkills();
+  } catch (error) {
+    console.error(`sync-agent-skills: failed — ${error.message}`);
+    process.exitCode = 1;
+  }
+}
+
+if (require.main === module) main();
+
+module.exports = { actorFromEnv, changedSkillFiles, parseGitPaths, syncAgentSkills };

package/scripts/sync-d20-audit.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Pre-commit auto-heal for the D20 bd call-site kill-list artifact.
+ *
+ * The `d20-audit-artifact-current` release gate compares the checked-in kill-list
+ * against a live re-scan, so any commit that shifts the bd call-site census leaves the
+ * artifact stale until someone runs `forge release regen-audit`. Five builders in a row
+ * forgot, and each found out a full CI round later (kernel issue 4cf2c43d).
+ *
+ * This removes the regen from the human's list, the same way scripts/sync-agent-skills.js
+ * removed the `.agents/skills` mirror regen: gate on a cheap changed-path predicate,
+ * regenerate, re-stage, succeed quietly. The release gate stays as the backstop for
+ * anything committed without this hook.
+ *
+ * The predicate is `isBdCensusPath`, exported by the gate's own module, so the hook and
+ * the gate always agree on which files count. The artifact itself is not a census path,
+ * so re-staging it cannot re-trigger the hook.
+ *
+ * The guarantee, stated honestly: the auto-heal applies when the counted staged paths
+ * match the working tree. It decides from the index but regenerates from the working tree
+ * (`auditBdCallSites` walks the filesystem), so those two agree only when the counted paths
+ * are staged whole. When any of them is partially staged the hook regenerates nothing, says
+ * so on stderr, and defers to a manual `forge release regen-audit` plus the
+ * `d20-audit-artifact-current` release gate — which still fails a genuinely stale artifact.
+ */
+
+const { execFileSync } = require('node:child_process');
+const path = require('node:path');
+const { AUDIT_ARTIFACT, isBdCensusPath, writeAuditArtifact } = require('../lib/release-readiness');
+
+function repoRoot(exec = execFileSync) {
+  try {
+    return exec('git', ['rev-parse', '--show-toplevel'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return path.resolve(__dirname, '..');
+  }
+}
+
+/**
+ * Parses `git diff --cached --name-status -z`: a flat NUL-delimited token stream of a
+ * status followed by its path — `A\0path\0`, and `R100\0old\0new\0` for a rename or copy,
+ * which is read from both sides because both shift the census (the old path leaves it and
+ * the new one may not enter it).
+ *
+ * NUL delimiting is what makes this safe. Git's default output quotes and backslash-
+ * escapes pathnames with non-ASCII or special characters, and no line/tab split can
+ * represent a pathname that itself contains a tab or a newline. Under -z the pathnames are
+ * verbatim, so nothing here may trim them — a mis-read path silently drops a
+ * census-impacting change and skips the regen this hook exists to perform.
+ */
+function parseStagedNameStatus(output) {
+  const tokens = output.split('\0');
+  const files = [];
+
+  for (let index = 0; index < tokens.length; index++) {
+    const status = tokens[index];
+    if (status.length === 0) {
+      continue;
+    }
+    const pathCount = /^[RC]/.test(status) ? 2 : 1;
+    files.push(...tokens.slice(index + 1, index + 1 + pathCount).filter(Boolean));
+    index += pathCount;
+  }
+
+  return [...new Set(files)];
+}
+
+function stagedPaths(projectRoot, exec = execFileSync) {
+  return parseStagedNameStatus(
+    exec('git', ['-C', projectRoot, 'diff', '--cached', '--name-status', '-z', '--diff-filter=ACMRDT'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }),
+  );
+}
+
+/**
+ * Parses a bare NUL-delimited path list (`git diff --name-only -z`). Same rule as
+ * parseStagedNameStatus: under -z the pathnames are verbatim, so nothing here may trim them.
+ */
+function parseNulPaths(output) {
+  return output.split('\0').filter(Boolean);
+}
+
+/**
+ * Of the given paths, the ones whose working-tree content differs from their staged content.
+ * `git diff` without `--cached` is index-vs-worktree, which is exactly the question the
+ * auto-heal must answer before regenerating an artifact it builds from the working tree.
+ */
+function worktreeModifiedPaths(projectRoot, paths, exec = execFileSync) {
+  if (paths.length === 0) {
+    return [];
+  }
+
+  return parseNulPaths(
+    exec('git', ['-C', projectRoot, 'diff', '--name-only', '-z', '--', ...paths], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }),
+  );
+}
+
+function stageArtifact(projectRoot, relativePath) {
+  execFileSync('git', ['-C', projectRoot, 'add', '--', relativePath], {
+    stdio: ['ignore', 'ignore', 'inherit'],
+  });
+}
+
+function run(deps) {
+  const { projectRoot, staged, worktreeModified, isCensusPath, writeArtifact, stage, log, warn } = deps;
+
+  const triggers = staged().filter(filePath => isCensusPath(projectRoot, filePath));
+  if (triggers.length === 0) {
+    return { regenerated: false, triggers: [], partiallyStaged: [] };
+  }
+
+  const partiallyStaged = worktreeModified(projectRoot, triggers);
+  if (partiallyStaged.length > 0) {
+    warn(
+      `sync-d20-audit: SKIPPED — the index is partially staged, so ${AUDIT_ARTIFACT} was NOT regenerated.\n` +
+      `  Staged and separately modified in the working tree: ${partiallyStaged.join(', ')}\n` +
+      '  The artifact is built from the working tree, so regenerating it now would commit a\n' +
+      '  census of content this commit does not contain.\n' +
+      `  Run \`forge release regen-audit\` and stage ${AUDIT_ARTIFACT} yourself if this commit\n` +
+      '  shifts the bd call-site census; the d20-audit-artifact-current gate checks it either way.',
+    );
+    return { regenerated: false, triggers, partiallyStaged };
+  }
+
+  writeArtifact(projectRoot);
+  stage(projectRoot, AUDIT_ARTIFACT);
+  log(`sync-d20-audit: regenerated ${AUDIT_ARTIFACT} (census paths staged: ${triggers.join(', ')})`);
+  return { regenerated: true, triggers, partiallyStaged: [] };
+}
+
+function main() {
+  const projectRoot = repoRoot();
+  try {
+    run({
+      projectRoot,
+      staged: () => stagedPaths(projectRoot),
+      worktreeModified: (root, paths) => worktreeModifiedPaths(root, paths),
+      isCensusPath: isBdCensusPath,
+      writeArtifact: root => writeAuditArtifact(root),
+      stage: stageArtifact,
+      log: message => console.log(message),
+      warn: message => console.error(message),
+    });
+  } catch (error) {
+    console.error(`sync-d20-audit: failed to regenerate ${AUDIT_ARTIFACT} — ${error.message}`);
+    console.error('Run `forge release regen-audit` and stage the result, or fix the error above.');
+    process.exit(1);
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  run,
+  parseStagedNameStatus,
+  parseNulPaths,
+  stagedPaths,
+  worktreeModifiedPaths,
+  repoRoot,
+};