forge-workflow 0.0.10 → 0.1.0-beta.2

package/scripts/spikes/patch-anchor-stability-bench.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+'use strict';
+
+const { performance } = require('node:perf_hooks');
+
+function readNumberFlag(args, name, fallback) {
+  const index = args.indexOf(name);
+  if (index === -1) return fallback;
+  const value = Number(args[index + 1]);
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error(`${name} must be a non-negative number`);
+  }
+  return value;
+}
+
+function assertPositiveInteger(name, value) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`${name} must be a positive integer`);
+  }
+}
+
+function assertNonNegativeInteger(name, value) {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error(`${name} must be a non-negative integer`);
+  }
+}
+
+function runBench(options = {}) {
+  const anchorCount = options.anchorCount ?? 500;
+  const patchCount = options.patchCount ?? 50;
+  const renameCount = options.renameCount ?? patchCount;
+  const unmappedCount = options.unmappedCount ?? 2;
+  const threshold = options.threshold ?? 0.10;
+
+  assertPositiveInteger('anchorCount', anchorCount);
+  assertPositiveInteger('patchCount', patchCount);
+  assertNonNegativeInteger('renameCount', renameCount);
+  assertNonNegativeInteger('unmappedCount', unmappedCount);
+  if (patchCount > anchorCount) {
+    throw new Error('patchCount must be <= anchorCount');
+  }
+  if (renameCount > patchCount) {
+    throw new Error('renameCount must be <= patchCount');
+  }
+  if (unmappedCount > renameCount) {
+    throw new Error('unmappedCount must be <= renameCount');
+  }
+
+  const start = performance.now();
+  const oldAnchors = Array.from({ length: anchorCount }, (_, i) => `stage.${i}.body`);
+  const patches = oldAnchors.slice(0, patchCount).map((anchor, i) => ({
+    id: `patch-${String(i + 1).padStart(3, '0')}`,
+    anchor,
+  }));
+
+  const currentAnchors = new Set(oldAnchors);
+  const aliases = new Map();
+  for (let i = 0; i < renameCount; i += 1) {
+    const oldAnchor = oldAnchors[i];
+    const newAnchor = `${oldAnchor}.v2`;
+    currentAnchors.delete(oldAnchor);
+    currentAnchors.add(newAnchor);
+    if (i >= unmappedCount) {
+      aliases.set(oldAnchor, newAnchor);
+    }
+  }
+
+  let resolved = 0;
+  let orphaned = 0;
+  const orphanIds = [];
+  for (const patch of patches) {
+    if (currentAnchors.has(patch.anchor)) {
+      resolved += 1;
+      continue;
+    }
+    const alias = aliases.get(patch.anchor);
+    if (alias && currentAnchors.has(alias)) {
+      resolved += 1;
+      continue;
+    }
+    orphaned += 1;
+    orphanIds.push(patch.id);
+  }
+
+  const elapsedMs = performance.now() - start;
+  const orphanRate = orphaned / patchCount;
+  return {
+    spike: 'patch-anchor-stability',
+    patchCount,
+    anchorCount,
+    renamedAnchors: renameCount,
+    aliasEntries: aliases.size,
+    orphaned,
+    resolved,
+    orphanRate,
+    threshold,
+    passed: orphanRate < threshold,
+    elapsedMs: Number(elapsedMs.toFixed(3)),
+    complexity: 'O(patches + anchors + aliases) with Map/Set lookups',
+    orphanIds,
+  };
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const patchCount = readNumberFlag(args, '--patches', 50);
+  const result = runBench({
+    anchorCount: readNumberFlag(args, '--anchors', 500),
+    patchCount,
+    renameCount: readNumberFlag(args, '--renames', patchCount),
+    unmappedCount: readNumberFlag(args, '--unmapped', 2),
+    threshold: readNumberFlag(args, '--threshold', 0.10),
+  });
+
+  console.log(JSON.stringify(result, null, args.includes('--json') ? 0 : 2));
+  if (!result.passed) {
+    process.exitCode = 1;
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { runBench };

package/scripts/spikes/protected-path-manifest.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('node:path');
+const {
+	buildProtectedPathManifestEvidence,
+	loadProtectedPathManifest,
+} = require('../../lib/protected-path-manifest');
+
+const root = path.resolve(__dirname, '..', '..');
+const manifestPath = path.join(root, '.forge', 'protected-paths.yaml');
+
+try {
+	const manifest = loadProtectedPathManifest(manifestPath);
+	process.stdout.write(`${JSON.stringify(buildProtectedPathManifestEvidence(manifest), null, 2)}\n`);
+} catch (error) {
+	const message = error instanceof Error ? error.message : String(error);
+	process.stderr.write(`Failed to build protected path manifest evidence from ${manifestPath}: ${message}\n`);
+	process.exit(1);
+}

package/scripts/spikes/skill-auto-invoke-parity.js

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const YAML = require('yaml');
+
+const CANONICAL_SKILL = {
+  name: 'guard-rails-audit',
+  description: 'Use when asked to inspect Forge L1 rail enforcement, audit events, or protected path policy.',
+  body: [
+    '# Guard Rails Audit',
+    '',
+    'Check Forge L1 rails, audit-event coverage, and protected path policy before recommending changes.',
+  ].join('\n'),
+};
+
+const MATCHING_PROMPT = 'Inspect Forge L1 rail enforcement and audit events for protected path policy.';
+const NON_MATCHING_PROMPT = 'Draft release notes for a minor README copy edit.';
+const FIXTURE_FILE = 'src/index.js';
+
+const SOURCES = [
+  {
+    label: 'S1',
+    harness: 'claude-code',
+    url: 'https://code.claude.com/docs/en/skills',
+    summary: 'Claude Code project skills live under .claude/skills/<skill>/SKILL.md and use description metadata for automatic invocation.',
+  },
+  {
+    label: 'S2',
+    harness: 'cursor',
+    url: 'https://docs.cursor.com/en/context',
+    summary: 'Cursor Project Rules live under .cursor/rules as .mdc files; Agent Requested rules are description-driven.',
+  },
+  {
+    label: 'S3',
+    harness: 'codex-cli',
+    url: 'https://github.com/openai/codex/blob/main/codex-rs/skills/src/assets/samples/skill-creator/SKILL.md',
+    summary: 'Codex skills use SKILL.md frontmatter name and description to determine when the skill gets used.',
+  },
+  {
+    label: 'S4',
+    harness: 'forge',
+    url: 'lib/codex-skills.js',
+    summary: 'Forge packages repository Codex skills from .codex/skills for installation into $CODEX_HOME/skills.',
+  },
+];
+
+const HARNESS_TARGETS = [
+  {
+    harness: 'claude-code',
+    target: '.claude/skills/guard-rails-audit/SKILL.md',
+    explicitInvocation: '/guard-rails-audit',
+    sourceLabel: 'S1',
+    source: 'Claude Code skill directory target',
+    buildFrontmatter: () => ({
+      name: CANONICAL_SKILL.name,
+      description: CANONICAL_SKILL.description,
+    }),
+  },
+  {
+    harness: 'cursor',
+    target: '.cursor/rules/guard-rails-audit.mdc',
+    explicitInvocation: '/guard-rails-audit',
+    sourceLabel: 'S2',
+    source: 'Cursor project rule with documented description/globs/alwaysApply metadata',
+    buildFrontmatter: () => ({
+      description: CANONICAL_SKILL.description,
+      globs: null,
+      alwaysApply: false,
+    }),
+  },
+  {
+    harness: 'codex-cli',
+    target: '.codex/skills/guard-rails-audit/SKILL.md',
+    explicitInvocation: '/guard-rails-audit',
+    sourceLabel: 'S4',
+    source: 'Forge repository Codex skills package surface; custom slash prompt files are intentionally not used',
+    buildFrontmatter: () => ({
+      name: CANONICAL_SKILL.name,
+      description: CANONICAL_SKILL.description,
+    }),
+  },
+];
+
+function buildMarkdown(frontmatter, body) {
+  return `---\n${YAML.stringify(frontmatter, {
+    lineWidth: 0,
+    defaultKeyType: 'PLAIN',
+    defaultStringType: 'PLAIN',
+  }).trimEnd()}\n---\n\n${body}\n`;
+}
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  if (!match) return {};
+  const parsed = YAML.parse(match[1]);
+  return parsed && typeof parsed === 'object' ? parsed : {};
+}
+
+function writeFile(root, relativePath, content) {
+  const absolutePath = path.join(root, relativePath);
+  fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+  fs.writeFileSync(absolutePath, content);
+}
+
+function isDirectoryEmpty(directory) {
+  return !fs.existsSync(directory) || fs.readdirSync(directory).length === 0;
+}
+
+function materializeFixture(root) {
+  if (!isDirectoryEmpty(root)) {
+    throw new Error(`fixture directory must be empty: ${root}`);
+  }
+
+  fs.mkdirSync(root, { recursive: true });
+  writeFile(root, FIXTURE_FILE, 'export function fixture() { return true; }\n');
+
+  for (const target of HARNESS_TARGETS) {
+    writeFile(
+      root,
+      target.target,
+      buildMarkdown(target.buildFrontmatter(), CANONICAL_SKILL.body),
+    );
+  }
+
+  return { root, skill: CANONICAL_SKILL, targets: HARNESS_TARGETS };
+}
+
+function tokens(value) {
+  return String(value)
+    .toLowerCase()
+    .match(/[a-z0-9]+/g)
+    ?.filter((token) => token.length >= 4) || [];
+}
+
+function descriptionMatches(description, prompt) {
+  const promptTokens = new Set(tokens(prompt));
+  const triggerTokens = tokens(description)
+    .filter((token) => !['when', 'asked', 'inspect'].includes(token));
+
+  return triggerTokens.some((token) => promptTokens.has(token));
+}
+
+function cursorGlobMatches(globs, filePath) {
+  void filePath;
+  if (!Array.isArray(globs) || globs.length === 0) return true;
+  return globs.includes('**/*') || globs.includes(filePath);
+}
+
+function validateHarness(root, target) {
+  const absolutePath = path.join(root, target.target);
+  const failures = [];
+
+  if (!fs.existsSync(absolutePath)) {
+    failures.push(`missing ${target.target}`);
+    return { ...target, passed: false, failures };
+  }
+
+  const frontmatter = parseFrontmatter(fs.readFileSync(absolutePath, 'utf8'));
+  const description = frontmatter.description;
+  const positiveMatch = descriptionMatches(description, MATCHING_PROMPT);
+  const negativeMatch = descriptionMatches(description, NON_MATCHING_PROMPT);
+
+  if (description !== CANONICAL_SKILL.description) {
+    failures.push('description does not match canonical skill description');
+  }
+  if (!positiveMatch) {
+    failures.push('matching prompt did not select the skill by description');
+  }
+  if (negativeMatch) {
+    failures.push('unrelated prompt selected the skill');
+  }
+  if (target.explicitInvocation !== `/${CANONICAL_SKILL.name}`) {
+    failures.push('explicit slash invocation does not match canonical skill name');
+  }
+
+  if (target.harness === 'claude-code') {
+    if (frontmatter.name !== CANONICAL_SKILL.name) failures.push('Claude skill name is missing or incorrect');
+  }
+
+  if (target.harness === 'cursor') {
+    if (frontmatter.alwaysApply !== false) failures.push('Cursor rule must keep alwaysApply: false for request-time selection');
+    if (!cursorGlobMatches(frontmatter.globs, FIXTURE_FILE)) failures.push(`Cursor globs do not include ${FIXTURE_FILE}`);
+  }
+
+  if (target.harness === 'codex-cli') {
+    if (!target.target.startsWith('.codex/skills/') || target.target.includes('/prompts/')) {
+      failures.push('Codex target must use .codex/skills, not undocumented prompt/slash files');
+    }
+  }
+
+  return {
+    ...target,
+    passed: failures.length === 0,
+    descriptionMatched: positiveMatch,
+    negativePromptIgnored: !negativeMatch,
+    frontmatter,
+    failures,
+  };
+}
+
+function runParity(options = {}) {
+  const root = options.fixtureDir || fs.mkdtempSync(path.join(os.tmpdir(), 'forge-w0-harness-parity-'));
+  const cleanup = options.fixtureDir ? false : options.cleanup !== false;
+
+  try {
+    materializeFixture(root);
+    const harnesses = HARNESS_TARGETS.map((target) => validateHarness(root, target));
+    const passed = harnesses.every((result) => result.passed);
+    const feasibleCount = harnesses.filter((result) => result.passed).length;
+    const knownIssues = passed ? [] : [{
+      issue: 'Cross-harness skill render parity did not pass for all three target harnesses.',
+      d38: 'D38 kills v3 if two of Claude/Cursor/Codex cannot render a single skill correctly by the W3 checkpoint.',
+      feasibleCount,
+    }];
+
+    return {
+      fixture: 'w0-skill-auto-invoke-parity',
+      fixtureRoot: root,
+      matchingPrompt: MATCHING_PROMPT,
+      nonMatchingPrompt: NON_MATCHING_PROMPT,
+      canonicalSkill: CANONICAL_SKILL,
+      harnesses,
+      sources: SOURCES,
+      proofBoundary: {
+        level: 'metadata-surface',
+        liveAgentInvocation: 'not-run',
+        codexRuntimeDiscovery: 'not-run',
+        reason: 'closed-source harness model invocation is outside this deterministic fixture; .codex/skills is the Forge repository packaging surface, not proof of direct Codex runtime discovery',
+      },
+      passed,
+      knownIssues,
+    };
+  } finally {
+    if (cleanup) fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function printText(result) {
+  console.log(`W0 skill auto-invoke parity: ${result.passed ? 'PASS' : 'FAIL'}`);
+  for (const harness of result.harnesses) {
+    const status = harness.passed ? 'PASS' : 'FAIL';
+    console.log(`${status} ${harness.harness} ${harness.target}`);
+    for (const failure of harness.failures) {
+      console.log(`  - ${failure}`);
+    }
+  }
+  if (result.knownIssues.length > 0) {
+    for (const issue of result.knownIssues) {
+      console.log(`Known issue: ${issue.issue} ${issue.d38}`);
+    }
+  }
+}
+
+function readStringFlag(args, name) {
+  const index = args.indexOf(name);
+  if (index === -1) return undefined;
+  const value = args[index + 1];
+  if (!value || value.startsWith('-')) return undefined;
+  return value;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const result = runParity({ fixtureDir: readStringFlag(args, '--fixture-dir') });
+
+  if (args.includes('--json')) {
+    console.log(JSON.stringify(result));
+  } else {
+    printText(result);
+  }
+
+  if (!result.passed) process.exitCode = 1;
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  CANONICAL_SKILL,
+  HARNESS_TARGETS,
+  MATCHING_PROMPT,
+  NON_MATCHING_PROMPT,
+  SOURCES,
+  descriptionMatches,
+  materializeFixture,
+  parseFrontmatter,
+  runParity,
+};

package/scripts/sync-agent-skills.js

@@ -0,0 +1,62 @@
+#!/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.
+ */
+
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { populateCodexRepoSkills, resolveCodexRepoSkillsDir } = require('../lib/codex-skills');
+
+function repoRoot() {
+  try {
+    return execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return path.resolve(__dirname, '..');
+  }
+}
+
+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);
+  }
+
+  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'],
+    });
+  } catch (error) {
+    console.error(`sync-agent-skills: failed to stage .agents/skills — ${error.message}`);
+    process.exit(1);
+  }
+
+  console.log(`sync-agent-skills: .agents/skills in sync with skills/ (${written.length} skills)`);
+}
+
+main();

package/scripts/sync-utils.sh

@@ -13,6 +13,9 @@ fi
 
 # Source shared sanitize library
 _SU_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [[ -f "$_SU_SCRIPT_DIR/bootstrap-windows-tools.sh" ]]; then
+  source "$_SU_SCRIPT_DIR/bootstrap-windows-tools.sh"
+fi
 source "$_SU_SCRIPT_DIR/lib/sanitize.sh"
 
 # ── Session Identity ───────────────────────────────────────────────────

package/scripts/test-ci-shard.js

@@ -177,17 +177,23 @@ function getShardPlan(args, { allUnitTests, durationMap }) {
   };
 }
 
-function runTests(label, files) {
-  fs.mkdirSync(reportDir, { recursive: true });
-  const junitPath = path.join(reportDir, `${label}.xml`);
-  const bunCommand = process.env.BUN_EXE || 'bun';
-  const result = spawnSync(bunCommand, [
+function buildBunTestArgs({ junitPath, files }) {
+  return [
     'test',
+    '--timeout',
+    '15000',
     '--reporter=junit',
     '--reporter-outfile',
     junitPath,
     ...files,
-  ], {
+  ];
+}
+
+function runTests(label, files) {
+  fs.mkdirSync(reportDir, { recursive: true });
+  const junitPath = path.join(reportDir, `${label}.xml`);
+  const bunCommand = process.env.BUN_EXE || 'bun';
+  const result = spawnSync(bunCommand, buildBunTestArgs({ junitPath, files }), {
     cwd: rootDir,
     stdio: 'inherit',
     shell: process.platform === 'win32',
@@ -226,6 +232,7 @@ if (require.main === module) {
 module.exports = {
   DEFAULT_SMOKE_FILES,
   PROFILE_MAX_AGE_MS,
+  buildBunTestArgs,
   createDurationMap,
   ensureFilesExist,
   getShardPlan,