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

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "forge-workflow",
-  "version": "0.1.0-beta.4",
+  "version": "0.1.0-beta.6",
+  "packageManager": "bun@1.4.2",
   "description": "Local runtime control plane for AI-assisted engineering workflows, gates, evidence, and all AI agents",
   "bin": {
     "forge": "bin/forge.js",
@@ -34,7 +35,7 @@
     "test:benchmark:full": "node scripts/benchmark.js --output test-results/benchmark-full-results.json --profile-dir test-results/benchmark-full-profiles --group full-suite --group validate",
     "test:full:parallel": "node scripts/test-full-suite.js",
     "test:dashboard": "node scripts/test-dashboard.js",
-    "test:profile": "node scripts/test-profile.js --input-dir test-results --output test-results/test-profile.json --label local",
+    "test:profile": "node scripts/test-profile.js --input-dir test-results --output test-results/test-profile.profile.json --label local",
     "test:randomized": "bun test --timeout 15000 --randomize",
     "test:rerun": "bun test --timeout 15000 --rerun-each 2",
     "agentic:sync": "node scripts/sync-agentic-workflow.js"
@@ -53,11 +54,11 @@
     "@eslint/js": "^10.0.1",
     "@microsoft/eslint-formatter-sarif": "^3.1.0",
     "@stryker-mutator/core": "^9.6.0",
-    "c8": "^11.0.0",
+    "c8": "^12.0.0",
     "eslint": "^10.0.2",
     "eslint-plugin-sonarjs": "^4.1.0",
     "globals": "^17.3.0",
-    "js-yaml": "^5.1.0",
+    "js-yaml": "^5.2.3",
     "lefthook": "^2.1.4",
     "typescript": "7.0.2"
   },
@@ -96,13 +97,12 @@
     ".cursor/",
     "!.cursor/node_modules/",
     "scripts/",
-    "!scripts/github-beads-sync/",
-    "!scripts/github-beads-sync.config.json",
     "!scripts/**/*.test.js",
     ".github/PLUGIN_TEMPLATE.json",
     ".forge/hooks/",
     ".forge/protected-paths.yaml",
     "CHANGELOG.md",
+    "CODING_STANDARDS.md",
     "QUICKSTART.md",
     "docs/*.md",
     "docs/architecture/**/*.md",
@@ -117,16 +117,19 @@
   ],
   "dependencies": {
     "@babel/parser": "^8.0.0",
+    "cross-spawn": "^7.0.6",
     "fastest-levenshtein": "^1.0.16",
     "yaml": "^2.8.3"
   },
   "overrides": {
     "eslint": "^10.0.2",
-    "fast-uri": "^3.1.2",
+    "fast-uri": "^3.1.4",
     "flatted": "3.4.2",
     "minimatch": "10.2.4",
-    "brace-expansion": "5.0.6",
-    "lodash": "4.18.1"
+    "brace-expansion": "5.0.9",
+    "linkify-it": "^5.0.2",
+    "lodash": "4.18.1",
+    "qs": "6.16.0"
   },
   "c8": {
     "lines": 80,

package/scripts/commitlint.js

@@ -1,15 +1,11 @@
 #!/usr/bin/env node
 /**
  * Cross-platform commitlint runner for lefthook commit-msg hook.
- * Replaces direct npx invocation which fails on Windows without shell: true.
- * Works on Windows CMD, PowerShell, macOS, Linux.
+ * Executes the installed commitlint CLI directly on Windows, macOS, and Linux.
  */
 
 const { spawnSync } = require('node:child_process');
 
-// On Windows, npx is npx.cmd — shell: true resolves .cmd extensions
-const isWindows = process.platform === 'win32';
-
 const commitMsgFile = process.argv[2];
 if (!commitMsgFile) {
   // Write synchronously so the message is flushed before exit: on Windows the
@@ -18,17 +14,19 @@ if (!commitMsgFile) {
   process.exit(1);
 }
 
-// Detect package manager: prefer bun (fast, works with bun.lock), fall back to npx
-// npx fails on Windows when npm 11's arborist encounters bun.lock instead of package-lock.json
-const hasBunLock = require('node:fs').existsSync(
-  require('node:path').join(__dirname, '../bun.lock')
-);
-const runner = hasBunLock ? 'bunx' : 'npx';
+let commitlintCli;
+try {
+  commitlintCli = require.resolve('@commitlint/cli/cli.js');
+} catch (error) {
+  console.error(`❌ Failed to resolve commitlint: ${error.message}`);
+  console.error('   Install project dependencies before committing.');
+  process.exit(1);
+}
 
 const result = spawnSync(
-  runner,
-  ['commitlint', '--edit', commitMsgFile],
-  { stdio: 'inherit', shell: isWindows }
+  process.execPath,
+  [commitlintCli, '--edit', commitMsgFile],
+  { stdio: 'inherit', shell: false }
 );
 
 if (result.error) {
@@ -40,5 +38,5 @@ if (result.error) {
 }
 
 if (result.status !== 0) {
-  process.exit(result.status);
+  process.exit(result.status ?? 1);
 }

package/scripts/doc-asserting-tests.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Runs (or lists) the test suites that assert on changed markdown.
+ *
+ * A markdown-only PR does not match the `paths:` filter in
+ * `.github/workflows/test.yml`, so the full matrix never runs and
+ * `required-checks-bypass.yml` reports the required "Test Suite" check green.
+ * Several suites nevertheless assert on markdown CONTENT, so such a PR merged
+ * green and then broke master for the next unrelated code PR — twice (kernel
+ * issue 63556816: the README size badge in #307/#310, and the AGENTS.md
+ * convention test after #325).
+ *
+ * This script closes that gap by running exactly the doc-asserting suites for the
+ * changed markdown. It shares `lib/doc-assertions.js` with the local push lane
+ * (`lib/commands/test.js`), so CI and local selection cannot drift apart.
+ *
+ * Usage:
+ *   node scripts/doc-asserting-tests.js [--base <ref>] [--list]
+ *
+ *   --base <ref>  Compare against <ref> (default: origin/<default-branch> or HEAD~1).
+ *   --list        Print the selected suites instead of running them.
+ */
+
+const { execFileSync, spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { selectDocAssertingTests } = require('../lib/doc-assertions');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+
+/** Wall-clock ceiling for the doc-asserting lane; it is a small, fast subset. */
+const LANE_TIMEOUT_MS = 5 * 60 * 1000;
+
+/**
+ * Parses the supported command-line flags.
+ *
+ * @param {string[]} argv Raw arguments (without node/script).
+ * @returns {{base: string|null, list: boolean}} Parsed options.
+ */
+function parseArgs(argv) {
+	const baseIndex = argv.indexOf('--base');
+	return {
+		base: baseIndex !== -1 ? argv[baseIndex + 1] || null : null,
+		list: argv.includes('--list'),
+	};
+}
+
+/**
+ * Resolves the ref the PR should be compared against.
+ *
+ * @param {string|null} explicitBase Base supplied with `--base`.
+ * @returns {string} A git ref usable in `git diff <ref>...HEAD`.
+ */
+function resolveBase(explicitBase) {
+	if (explicitBase) return explicitBase;
+	for (const ref of ['origin/master', 'origin/main']) {
+		try {
+			execFileSync('git', ['rev-parse', '--verify', ref], { cwd: REPO_ROOT, stdio: 'pipe', timeout: 5000 });
+			return ref;
+		} catch (_e) { /* intentional: ref not present in this checkout, try next */ } // NOSONAR S2486
+	}
+	return 'HEAD~1';
+}
+
+/**
+ * Parses `git diff --name-only` output into repository-relative paths.
+ *
+ * Split out so the parsing contract (trimmed, no blanks) is testable without a live
+ * repository: CI checks out shallow, so a test that reaches for `HEAD~1` passes locally
+ * and fails on the runner.
+ *
+ * @param {string} output Raw `git diff --name-only` stdout.
+ * @returns {string[]} Changed file paths.
+ */
+function parseChangedFiles(output) {
+	return output.split('\n').map((line) => line.trim()).filter(Boolean);
+}
+
+/**
+ * Lists repository-relative paths changed against the base ref.
+ *
+ * @param {string} base Base git ref.
+ * @returns {string[]} Changed file paths.
+ */
+function changedFilesSince(base) {
+	const output = execFileSync('git', ['diff', '--name-only', `${base}...HEAD`], {
+		cwd: REPO_ROOT,
+		encoding: 'utf8',
+		timeout: 15000,
+	});
+	return parseChangedFiles(output);
+}
+
+/**
+ * Turns a `spawnSync` result into a process exit status.
+ *
+ * A spawn that never produced a status (`error`, or killed by a signal so `status`
+ * is null) MUST report FAILURE. Reporting 0 there would re-create the bug this lane
+ * exists to remove: a required check reporting green without running the tests.
+ *
+ * @param {{status: number|null, error?: Error}} result Result of `spawnSync`.
+ * @returns {number} Exit status; non-zero whenever the run did not demonstrably pass.
+ */
+function resolveSpawnStatus(result) {
+	if (!result || result.error) return 1;
+	return result.status ?? 1;
+}
+
+function main() {
+	const { base: explicitBase, list } = parseArgs(process.argv.slice(2));
+	const base = resolveBase(explicitBase);
+
+	let changedFiles;
+	try {
+		changedFiles = changedFilesSince(base);
+	} catch (error) {
+		// Fail closed: if the change set cannot be determined we cannot prove the
+		// doc-asserting suites are unaffected.
+		console.error(`Could not compute changed files against ${base}: ${error.message}`);
+		return 1;
+	}
+
+	const suites = selectDocAssertingTests(changedFiles, REPO_ROOT, fs);
+
+	if (suites.length === 0) {
+		console.log('No changed markdown asserts on by any test suite — nothing to run.');
+		return 0;
+	}
+
+	if (list) {
+		console.log(suites.join('\n'));
+		return 0;
+	}
+
+	console.log(`Running ${suites.length} doc-asserting suite${suites.length === 1 ? '' : 's'} for changed markdown:`);
+	for (const suite of suites) console.log(`  ${suite}`);
+
+	const result = spawnSync('bun', ['test', ...suites], {
+		cwd: REPO_ROOT,
+		stdio: 'inherit',
+		timeout: LANE_TIMEOUT_MS,
+		shell: process.platform === 'win32',
+	});
+
+	if (result.error) {
+		console.error(`Failed to run doc-asserting suites: ${result.error.message}`);
+	}
+	return resolveSpawnStatus(result);
+}
+
+if (require.main === module) {
+	process.exit(main());
+}
+
+module.exports = { changedFilesSince, parseArgs, parseChangedFiles, resolveBase, resolveSpawnStatus };

package/scripts/generate-risk-manifest.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { parse } = require('yaml');
+const { stableStringify } = require('../lib/kernel/evaluators');
+const { hashManifest, validateManifest } = require('../lib/validation/risk-manifest');
+const crypto = require('node:crypto');
+
+const ROOT = path.resolve(__dirname, '..');
+const SOURCE_PATH = path.join(ROOT, 'validation', 'risk-manifest.source.yaml');
+const OUTPUT_PATH = path.join(ROOT, 'validation', 'risk-manifest.v1.json');
+
+function sha256(value) {
+  return `sha256:${crypto.createHash('sha256').update(value, 'utf8').digest('hex')}`;
+}
+
+function compareText(left, right) {
+  if (left === right) return 0;
+  return left < right ? -1 : 1;
+}
+
+function sortById(entries) {
+  return [...entries].sort((left, right) => compareText(left.id, right.id));
+}
+
+function normalizeSource(source) {
+  const canonicalSource = source.replaceAll('\r\n', '\n').replaceAll('\r', '\n');
+  const parsed = parse(canonicalSource);
+  const manifest = {
+    schema_id: parsed.schema_id,
+    revision: parsed.revision,
+    source_hash: sha256(canonicalSource),
+    generator_version: 'forge-risk-manifest-generator.v1',
+    commands: sortById(parsed.commands).map((command) => ({
+      ...command,
+      argv: [...command.argv],
+    })),
+    gates: sortById(parsed.gates).map((gate) => ({
+      ...gate,
+      command_ids: [...gate.command_ids].sort(compareText),
+    })),
+    lanes: sortById(parsed.lanes).map((lane) => ({
+      ...lane,
+      command_ids: [...lane.command_ids].sort(compareText),
+    })),
+    risks: sortById(parsed.risks).map((risk) => ({
+      ...risk,
+      gate_ids: [...risk.gate_ids].sort(),
+    })),
+    owners: sortById(parsed.owners).map((owner) => ({
+      ...owner,
+      risk_ids: [...owner.risk_ids].sort(),
+      canonical_test_ids: [...owner.canonical_test_ids].sort(),
+      dependent_routes: [...owner.dependent_routes].sort(),
+      platform_runtime_additions: [...owner.platform_runtime_additions].sort(),
+      lanes: [...owner.lanes].sort(),
+      package_roots: [...owner.package_roots].sort(),
+      selectors: [...owner.selectors].sort((left, right) => compareText(left.kind, right.kind)
+        || compareText(left.prefix, right.prefix)),
+    })),
+    unknown_owner_fallback: {
+      ...parsed.unknown_owner_fallback,
+      required_gates: [...parsed.unknown_owner_fallback.required_gates].sort(),
+    },
+  };
+  manifest.manifest_hash = hashManifest(manifest);
+  validateManifest(manifest);
+  return JSON.parse(stableStringify(manifest));
+}
+
+function generateRiskManifest(source) {
+  return `${JSON.stringify(normalizeSource(source), null, 2)}\n`;
+}
+
+function main(args = process.argv.slice(2)) {
+  const generated = generateRiskManifest(fs.readFileSync(SOURCE_PATH, 'utf8'));
+  if (args.includes('--check')) {
+    if (!fs.existsSync(OUTPUT_PATH) || fs.readFileSync(OUTPUT_PATH, 'utf8') !== generated) {
+      console.error('Risk manifest is stale. Run: node scripts/generate-risk-manifest.js');
+      process.exitCode = 1;
+    }
+    return;
+  }
+  fs.writeFileSync(OUTPUT_PATH, generated, 'utf8');
+}
+
+if (require.main === module) main();
+
+module.exports = { generateRiskManifest, normalizeSource };

package/scripts/github-context-bridge.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# GH_CMD bridge: re-enter this Forge runtime without credentials in the Bash parent.
+set -euo pipefail
+
+: "${FORGE_GITHUB_RUNTIME:?Forge GitHub runtime is required}"
+if [[ -n "${FORGE_GITHUB_ENTRY:-}" ]]; then
+  exec "$FORGE_GITHUB_RUNTIME" "$FORGE_GITHUB_ENTRY" github run -- gh "$@"
+else
+  exec "$FORGE_GITHUB_RUNTIME" github run -- gh "$@"
+fi

package/scripts/legacy-claim-repair.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('node:path');
+
+const {
+	createBuiltinSQLiteDriver,
+	hardenBackupPermissions,
+	hardenBackupPermissionsBatch,
+} = require('../lib/kernel/sqlite-driver');
+const {
+	ClaimRepairError,
+	createVerifiedClaimRepairBackup,
+} = require('../lib/kernel/legacy-claim-repair');
+
+const HELP = `Usage:
+  bun scripts/legacy-claim-repair.js --dry-run --database <kernel.sqlite> --backup <separate.sqlite> --at <canonical-UTC>
+  bun scripts/legacy-claim-repair.js --apply --database <kernel.sqlite> --backup <separate.sqlite> --at <canonical-UTC> --approved-digest <sha256> --actor <identity>
+
+The tool never discovers or repairs a database automatically. Apply is rejected
+without a verified restorable backup and the exact human-approved dry-run digest.`;
+
+function parseArgs(argv = []) {
+	const result = { mode: null };
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index];
+		if (arg === '--help' || arg === '-h') return { help: true };
+		if (arg === '--dry-run' || arg === '--apply') {
+			const mode = arg.slice(2);
+			if (result.mode && result.mode !== mode) throw new Error('Choose exactly one of --dry-run or --apply');
+			result.mode = mode;
+			continue;
+		}
+		const names = {
+			'--database': 'databasePath',
+			'--backup': 'backupPath',
+			'--at': 'observedAt',
+			'--approved-digest': 'approvedDigest',
+			'--actor': 'actor',
+		};
+		if (!Object.hasOwn(names, arg)) throw new Error(`Unknown argument: ${arg}`);
+		const name = names[arg];
+		const value = argv[index + 1];
+		if (!value || value.startsWith('--')) throw new Error(`${arg} requires a value`);
+		result[name] = value;
+		index += 1;
+	}
+	if (!result.mode) throw new Error('Choose exactly one of --dry-run or --apply');
+	for (const required of ['databasePath', 'backupPath', 'observedAt']) {
+		if (!result[required]) throw new Error(`Missing required option: ${required}`);
+	}
+	for (const requiredPath of ['databasePath', 'backupPath']) {
+		if (!path.isAbsolute(result[requiredPath])) {
+			throw new Error(`${requiredPath} must be an absolute path`);
+		}
+	}
+	if (result.mode === 'apply' && !result.approvedDigest) {
+		throw new Error('--apply requires --approved-digest');
+	}
+	if (result.mode === 'apply' && !result.actor) {
+		throw new Error('--apply requires --actor');
+	}
+	if (result.mode === 'dry-run' && result.approvedDigest) {
+		throw new Error('--approved-digest is valid only with --apply');
+	}
+	if (result.mode === 'dry-run' && result.actor) {
+		throw new Error('--actor is valid only with --apply');
+	}
+	return result;
+}
+
+async function run(options, dependencies = {}) {
+	const openDriver = dependencies.openDriver
+		|| (databasePath => createBuiltinSQLiteDriver({ databasePath }));
+	const createBackup = dependencies.createVerifiedClaimRepairBackup
+		|| createVerifiedClaimRepairBackup;
+	const hardenPath = dependencies.hardenPath || hardenBackupPermissions;
+	const hardenPaths = dependencies.hardenPaths
+		|| (dependencies.hardenPath ? dependencies.hardenPath.batch : hardenBackupPermissionsBatch);
+	const sourceDriver = openDriver(options.databasePath);
+	try {
+		if (options.mode === 'dry-run') {
+			const backup = await createBackup({
+				sourceDriver,
+				backupPath: options.backupPath,
+				observedAt: options.observedAt,
+				openDriver,
+				hardenPath,
+				hardenPaths,
+			});
+			const preflight = await sourceDriver.preflightLegacyClaimRepair({ observedAt: options.observedAt });
+			if (preflight.digest !== backup.plan_digest) {
+				throw new ClaimRepairError(
+					'CLAIM_REPAIR_BACKUP_DRIFT',
+					'Live claim authority changed while binding the reported preflight to its verified backup',
+				);
+			}
+			return { ok: true, preflight, backup };
+		}
+
+		const receipt = await sourceDriver.applyLegacyClaimRepair({
+			observedAt: options.observedAt,
+			approvedDigest: options.approvedDigest,
+			backupPath: options.backupPath,
+			actor: options.actor,
+		});
+		return { ok: true, receipt };
+	} finally {
+		sourceDriver.close();
+	}
+}
+
+async function main(argv = process.argv.slice(2)) {
+	try {
+		const options = parseArgs(argv);
+		if (options.help) {
+			process.stdout.write(`${HELP}\n`);
+			return;
+		}
+		process.stdout.write(`${JSON.stringify(await run(options), null, 2)}\n`);
+	} catch (error) {
+		const recoveryPath = error?.code === 'CLAIM_REPAIR_BACKUP_POSTCOMMIT_DRIFT'
+			&& typeof error?.details?.recovery_path === 'string'
+			? error.details.recovery_path
+			: null;
+		process.stderr.write(`${JSON.stringify({
+			ok: false,
+			error: {
+				code: error?.code || 'CLAIM_REPAIR_USAGE',
+				message: error?.message || String(error),
+				...(recoveryPath ? { recovery_path: recoveryPath } : {}),
+			},
+		}, null, 2)}\n`);
+		process.exitCode = 1;
+	}
+}
+
+if (require.main === module) void main();
+
+module.exports = {
+	HELP,
+	main,
+	parseArgs,
+	run,
+};