forge-workflow 0.0.10 → 0.1.0-beta.2

package/scripts/install.sh

@@ -0,0 +1,268 @@
+#!/bin/sh
+# Forge single-binary installer for macOS and Linux (POSIX sh).
+#
+# One-line install:
+#   curl -fsSL https://raw.githubusercontent.com/harshanandak/forge/master/scripts/install.sh | sh
+#
+# Install a specific version:
+#   curl -fsSL https://raw.githubusercontent.com/harshanandak/forge/master/scripts/install.sh | sh -s -- --version v1.2.3
+#
+# What it does: detects your OS (darwin/linux), CPU arch (x64/arm64) and, on
+# Linux, your libc (glibc/musl), downloads the matching binary from the GitHub
+# Release, makes it executable, and installs it to ~/.local/bin/forge.
+#
+# The binary bundles Forge's own JavaScript, but NOT its external prerequisites:
+# git, gh (GitHub CLI) and — on Windows only — Git Bash still need to be on PATH.
+#
+# The asset-name mapping implemented by resolve_asset() below is the canonical
+# contract shared with scripts/lib/release-asset.mjs and is exercised by
+# scripts/release-asset.test.js via the hidden --print-asset mode.
+
+set -eu
+
+REPO="${FORGE_REPO:-harshanandak/forge}"
+INSTALL_DIR="${FORGE_INSTALL_DIR:-$HOME/.local/bin}"
+BIN_NAME="forge"
+VERSION="latest"
+
+# --- tiny helpers ----------------------------------------------------------
+err() { printf '%s\n' "forge-install: $*" >&2; }
+die() { err "$*"; exit 1; }
+
+# --- argument parsing ------------------------------------------------------
+PRINT_ASSET=0
+while [ $# -gt 0 ]; do
+	case "$1" in
+		--version)
+			[ $# -ge 2 ] || die "--version requires an argument (e.g. --version v1.2.3)"
+			VERSION="$2"; shift 2 ;;
+		--version=*)
+			VERSION="${1#--version=}"; shift ;;
+		--dir)
+			[ $# -ge 2 ] || die "--dir requires a path argument"
+			INSTALL_DIR="$2"; shift 2 ;;
+		--dir=*)
+			INSTALL_DIR="${1#--dir=}"; shift ;;
+		# Hidden: print the resolved asset name and exit (used by the test suite).
+		# Honors FORGE_OS / FORGE_ARCH / FORGE_LIBC overrides so the mapping can be
+		# unit-tested for every target without touching this host's real platform.
+		--print-asset)
+			PRINT_ASSET=1; shift ;;
+		-h|--help)
+			cat <<'EOF'
+Usage: install.sh [--version <tag>] [--dir <path>]
+  --version <tag>   Install a specific release (default: latest), e.g. v1.2.3
+  --dir <path>      Install directory (default: ~/.local/bin)
+Environment overrides: FORGE_REPO, FORGE_INSTALL_DIR, FORGE_VERSION
+EOF
+			exit 0 ;;
+		*)
+			die "unknown argument: $1 (try --help)" ;;
+	esac
+done
+# Env fallback for version (arg wins over env).
+if [ "$VERSION" = "latest" ] && [ -n "${FORGE_VERSION:-}" ]; then
+	VERSION="$FORGE_VERSION"
+fi
+
+# --- platform detection ----------------------------------------------------
+detect_os() {
+	if [ -n "${FORGE_OS:-}" ]; then printf '%s' "$FORGE_OS"; return; fi
+	case "$(uname -s)" in
+		Darwin) printf 'darwin' ;;
+		Linux) printf 'linux' ;;
+		*) printf 'unsupported' ;;
+	esac
+}
+
+detect_arch() {
+	if [ -n "${FORGE_ARCH:-}" ]; then printf '%s' "$FORGE_ARCH"; return; fi
+	case "$(uname -m)" in
+		x86_64|amd64) printf 'x64' ;;
+		arm64|aarch64) printf 'arm64' ;;
+		*) printf 'unsupported' ;;
+	esac
+}
+
+# Best-effort libc detection on Linux: musl vs glibc. Order of evidence:
+# 1) explicit override, 2) a musl loader in /lib, 3) `ldd --version` text,
+# 4) getconf glibc version. Defaults to glibc when nothing proves musl.
+detect_libc() {
+	if [ -n "${FORGE_LIBC:-}" ]; then printf '%s' "$FORGE_LIBC"; return; fi
+	# Non-Linux platforms have no libc variants.
+	[ "$(detect_os)" = "linux" ] || { printf 'none'; return; }
+	for f in /lib/ld-musl-* /lib/libc.musl-*; do
+		[ -e "$f" ] && { printf 'musl'; return; }
+	done
+	if ldd_out="$(ldd --version 2>&1)"; then
+		case "$ldd_out" in
+			*musl*) printf 'musl'; return ;;
+			*GNU*|*GLIBC*|*glibc*) printf 'glibc'; return ;;
+		esac
+	fi
+	if getconf GNU_LIBC_VERSION >/dev/null 2>&1; then printf 'glibc'; return; fi
+	printf 'glibc'
+}
+
+# Canonical asset-name mapping — MUST stay in sync with
+# scripts/lib/release-asset.mjs (guarded by scripts/release-asset.test.js).
+resolve_asset() {
+	_os="$1"; _arch="$2"; _libc="$3"
+	case "$_os" in
+		darwin|linux|windows) ;;
+		*) die "unsupported OS: '$_os' (need darwin, linux or windows)" ;;
+	esac
+	case "$_arch" in
+		x64|arm64) ;;
+		*) die "unsupported arch: '$_arch' (need x64 or arm64)" ;;
+	esac
+	# Reject os/arch pairs that are not published (parity with releaseAssetName()
+	# in scripts/lib/release-asset.mjs). Windows ships x64 only, so windows/arm64
+	# must not resolve to a phantom forge-windows-arm64.exe.
+	if [ "$_os" = "windows" ] && [ "$_arch" != "x64" ]; then
+		die "unsupported platform: windows/${_arch} is not a published target (windows is x64 only)"
+	fi
+	_name="forge-${_os}-${_arch}"
+	if [ "$_os" = "linux" ] && [ "$_libc" = "musl" ]; then
+		_name="${_name}-musl"
+	fi
+	if [ "$_os" = "windows" ]; then
+		_name="${_name}.exe"
+	fi
+	printf '%s' "$_name"
+}
+
+OS="$(detect_os)"
+ARCH="$(detect_arch)"
+LIBC="$(detect_libc)"
+
+[ "$OS" != "unsupported" ] || die "unsupported operating system: $(uname -s). Supported: macOS (darwin), Linux."
+[ "$ARCH" != "unsupported" ] || die "unsupported CPU architecture: $(uname -m). Supported: x86_64/amd64 (x64), arm64/aarch64 (arm64)."
+
+ASSET="$(resolve_asset "$OS" "$ARCH" "$LIBC")"
+
+if [ "$PRINT_ASSET" -eq 1 ]; then
+	printf '%s\n' "$ASSET"
+	exit 0
+fi
+
+# --- downloader ------------------------------------------------------------
+if command -v curl >/dev/null 2>&1; then
+	DL='curl -fSL --retry 3 --connect-timeout 10 --max-time 300 -o'
+	DL_QUIET='curl -fsSL --connect-timeout 10 --max-time 30'
+elif command -v wget >/dev/null 2>&1; then
+	DL='wget --timeout=300 -O'
+	DL_QUIET='wget --timeout=30 -qO-'
+else
+	die "need either curl or wget installed to download the binary."
+fi
+
+download_to() { # url dest
+	# shellcheck disable=SC2086
+	if command -v curl >/dev/null 2>&1; then
+		curl -fSL --retry 3 --connect-timeout 10 --max-time 300 -o "$2" "$1"
+	else
+		wget --timeout=300 -O "$2" "$1"
+	fi
+}
+
+# --- resolve version + URL -------------------------------------------------
+if [ "$VERSION" = "latest" ]; then
+	# The /releases/latest/download/<asset> path redirects to the newest release,
+	# so we can download without hitting the JSON API. We still try to resolve the
+	# human-readable tag for the summary line (best-effort, never fatal).
+	URL="https://github.com/${REPO}/releases/latest/download/${ASSET}"
+	RESOLVED_VERSION="$(
+		$DL_QUIET "https://api.github.com/repos/${REPO}/releases/latest" 2>/dev/null \
+			| sed -n 's/.*"tag_name"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' \
+			| head -n1
+	)" || true
+	[ -n "${RESOLVED_VERSION:-}" ] || RESOLVED_VERSION="latest"
+else
+	URL="https://github.com/${REPO}/releases/download/${VERSION}/${ASSET}"
+	RESOLVED_VERSION="$VERSION"
+fi
+
+printf 'forge-install: platform %s / %s / %s -> asset %s\n' "$OS" "$ARCH" "$LIBC" "$ASSET"
+printf 'forge-install: downloading %s (%s)\n' "$ASSET" "$RESOLVED_VERSION"
+
+# --- download + install ----------------------------------------------------
+TMP="$(mktemp -d "${TMPDIR:-/tmp}/forge-install.XXXXXX")"
+trap 'rm -rf "$TMP"' EXIT INT TERM
+TMP_BIN="$TMP/$BIN_NAME"
+
+download_to "$URL" "$TMP_BIN" || die "download failed from $URL — is the release published for your platform?"
+[ -s "$TMP_BIN" ] || die "downloaded file is empty — the asset '$ASSET' may not exist in release '$RESOLVED_VERSION'."
+
+# --- integrity verification (SHA-256) --------------------------------------
+# Verify the downloaded asset against the release's checksums.txt manifest BEFORE
+# making it executable or installing it. A mismatch is always fatal (corrupted or
+# substituted download). If the manifest cannot be fetched or no SHA-256 tool is
+# available we warn and continue; set FORGE_SKIP_CHECKSUM=1 to bypass entirely.
+verify_checksum() {
+	if [ "${FORGE_SKIP_CHECKSUM:-0}" = "1" ]; then
+		printf 'forge-install: FORGE_SKIP_CHECKSUM=1 set — skipping integrity check.\n' >&2
+		return 0
+	fi
+
+	_sha=""
+	if command -v sha256sum >/dev/null 2>&1; then _sha="sha256sum";
+	elif command -v shasum >/dev/null 2>&1; then _sha="shasum";
+	elif command -v openssl >/dev/null 2>&1; then _sha="openssl";
+	fi
+	if [ -z "$_sha" ]; then
+		printf 'forge-install: no sha256 tool (sha256sum/shasum/openssl) found — skipping integrity check.\n' >&2
+		return 0
+	fi
+
+	# The manifest lives beside the asset in the same release.
+	_sums_url="${URL%/*}/checksums.txt"
+	_manifest="$TMP/checksums.txt"
+	if ! download_to "$_sums_url" "$_manifest" >/dev/null 2>&1 || [ ! -s "$_manifest" ]; then
+		printf 'forge-install: could not download checksums.txt — skipping integrity check.\n' >&2
+		return 0
+	fi
+
+	# sha256sum manifest lines are "<hash>  <name>" (text) or "<hash> *<name>"
+	# (binary); match either form for our asset.
+	_expected="$(awk -v f="$ASSET" '{ n=$2; sub(/^\*/,"",n); if (n==f) { print $1; exit } }' "$_manifest")"
+	if [ -z "$_expected" ]; then
+		printf 'forge-install: %s not listed in checksums.txt — skipping integrity check.\n' "$ASSET" >&2
+		return 0
+	fi
+
+	case "$_sha" in
+		sha256sum) _actual="$(sha256sum "$TMP_BIN" | awk '{print $1}')" ;;
+		shasum) _actual="$(shasum -a 256 "$TMP_BIN" | awk '{print $1}')" ;;
+		openssl) _actual="$(openssl dgst -sha256 "$TMP_BIN" | awk '{print $NF}')" ;;
+	esac
+
+	if [ "$_actual" != "$_expected" ]; then
+		die "checksum mismatch for $ASSET
+  expected: $_expected
+  actual:   $_actual
+The download may be corrupted or tampered with — aborting."
+	fi
+	printf 'forge-install: checksum verified (sha256).\n'
+}
+verify_checksum
+
+chmod +x "$TMP_BIN"
+
+mkdir -p "$INSTALL_DIR"
+DEST="$INSTALL_DIR/$BIN_NAME"
+mv -f "$TMP_BIN" "$DEST"
+
+printf '\nforge-install: installed forge %s -> %s\n' "$RESOLVED_VERSION" "$DEST"
+
+# --- PATH note + next step -------------------------------------------------
+case ":${PATH}:" in
+	*":${INSTALL_DIR}:"*) : ;;  # already on PATH
+	*)
+		printf '\n%s is not on your PATH. Add it, e.g.:\n' "$INSTALL_DIR"
+		printf '  echo '\''export PATH="%s:$PATH"'\'' >> ~/.profile && . ~/.profile\n' "$INSTALL_DIR"
+		;;
+esac
+
+printf '\nNext: run '\''forge setup'\'' in a git repo to wire up Forge.\n'
+printf 'Note: git and gh (GitHub CLI) must be installed separately — the binary bundles Forge, not those tools.\n'

package/scripts/lib/release-asset.mjs

@@ -0,0 +1,84 @@
+// Canonical GitHub Release asset-name mapping for the single-binary distribution
+// (epic 6f11d483, Step 4 / issue 50afbc47). This is the SINGLE SOURCE OF TRUTH
+// for how a detected platform (os / arch / libc) maps to the release asset that
+// `scripts/install.sh` and `scripts/install.ps1` download.
+//
+// The CI workflow `.github/workflows/build-binary.yml` compiles seven canonical
+// bun targets and publishes each to the GitHub Release under the names produced
+// here. The install scripts re-derive the same name from the host platform, so
+// this table is exercised by `scripts/release-asset.test.js` (which also
+// cross-checks the shell script's own detection against it) to guarantee the two
+// sides never drift.
+//
+// bun target            -> release asset
+// bun-windows-x64        -> forge-windows-x64.exe
+// bun-darwin-arm64       -> forge-darwin-arm64
+// bun-darwin-x64         -> forge-darwin-x64
+// bun-linux-x64          -> forge-linux-x64
+// bun-linux-arm64        -> forge-linux-arm64
+// bun-linux-x64-musl     -> forge-linux-x64-musl
+// bun-linux-arm64-musl   -> forge-linux-arm64-musl
+
+/** Operating systems we publish binaries for. */
+export const SUPPORTED_OS = ['windows', 'darwin', 'linux'];
+/** CPU architectures we publish binaries for. */
+export const SUPPORTED_ARCH = ['x64', 'arm64'];
+
+/**
+ * Map a detected platform to its GitHub Release asset filename.
+ *
+ * @param {object} p
+ * @param {string} p.os    - 'windows' | 'darwin' | 'linux'
+ * @param {string} p.arch  - 'x64' | 'arm64'
+ * @param {string} [p.libc] - 'glibc' | 'musl' (linux only; ignored elsewhere)
+ * @returns {string} asset filename, e.g. 'forge-linux-x64-musl' or 'forge-windows-x64.exe'
+ * @throws {Error} on an unsupported os/arch combination
+ */
+export function releaseAssetName({ os, arch, libc } = {}) {
+	if (!SUPPORTED_OS.includes(os)) {
+		throw new Error(`Unsupported OS: ${os} (supported: ${SUPPORTED_OS.join(', ')})`);
+	}
+	if (!SUPPORTED_ARCH.includes(arch)) {
+		throw new Error(`Unsupported arch: ${arch} (supported: ${SUPPORTED_ARCH.join(', ')})`);
+	}
+	// Reject os/arch pairs that are not actually published. The independent
+	// allowlists above would otherwise accept e.g. windows/arm64 and invent a
+	// `forge-windows-arm64.exe` asset that no release contains. Validate the
+	// tuple against the canonical matrix (windows is x64-only) so JS, install.sh
+	// and install.ps1 all agree on the same supported set.
+	if (!PUBLISHED_OS_ARCH.has(`${os}/${arch}`)) {
+		throw new Error(
+			`Unsupported platform: ${os}/${arch} is not a published target ` +
+				`(supported: ${[...PUBLISHED_OS_ARCH].join(', ')})`,
+		);
+	}
+	let name = `forge-${os}-${arch}`;
+	if (os === 'linux' && libc === 'musl') {
+		name += '-musl';
+	}
+	if (os === 'windows') {
+		name += '.exe';
+	}
+	return name;
+}
+
+/**
+ * The full set of seven canonical assets, in the same order as the CI matrix.
+ * Exported for tests and for anyone enumerating the published release.
+ */
+export const CANONICAL_ASSETS = [
+	{ os: 'windows', arch: 'x64', libc: undefined, asset: 'forge-windows-x64.exe' },
+	{ os: 'darwin', arch: 'arm64', libc: undefined, asset: 'forge-darwin-arm64' },
+	{ os: 'darwin', arch: 'x64', libc: undefined, asset: 'forge-darwin-x64' },
+	{ os: 'linux', arch: 'x64', libc: 'glibc', asset: 'forge-linux-x64' },
+	{ os: 'linux', arch: 'arm64', libc: 'glibc', asset: 'forge-linux-arm64' },
+	{ os: 'linux', arch: 'x64', libc: 'musl', asset: 'forge-linux-x64-musl' },
+	{ os: 'linux', arch: 'arm64', libc: 'musl', asset: 'forge-linux-arm64-musl' },
+];
+
+/**
+ * The set of published `os/arch` tuples, derived from CANONICAL_ASSETS so it can
+ * never drift from the actual release matrix. Used by releaseAssetName() to
+ * reject unsupported combinations (e.g. windows/arm64).
+ */
+export const PUBLISHED_OS_ARCH = new Set(CANONICAL_ASSETS.map((a) => `${a.os}/${a.arch}`));

package/scripts/parity-check.mjs

@@ -0,0 +1,145 @@
+// Byte-for-byte parity check between the two Forge distribution channels.
+//
+// Runs `forge setup` from BOTH the npm path (`node bin/forge.js`) and the compiled
+// single-file binary into two throwaway git projects, then compares the produced
+// trees by relative-path set + per-file SHA-256. Catches flattening, missing files,
+// CRLF mangling, and corruption in one assertion.
+//
+// This is the "one real-compile leg" the reliability guidance asks for. It is
+// runnable locally (`bun run parity:binary`) and by the step-3 CI matrix on each
+// host target. Requires `bun` and `git` on PATH.
+
+import { execFileSync, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const BIN = process.platform === 'win32' ? 'forge-bin.exe' : 'forge-bin';
+const BIN_PATH = path.join(REPO, BIN);
+
+function run(cmd, args, opts = {}) {
+  const r = spawnSync(cmd, args, { encoding: 'utf8', ...opts });
+  return r;
+}
+
+function sha256(file) {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+// Directories to skip entirely while walking a setup tree. `node_modules` is a
+// package-manager install artifact, NOT a Forge-managed asset — `setup --quick`
+// may run an npm/bun install whose output (dependency trees, registry metadata)
+// is legitimately non-deterministic between runs, channels, and OSes. Comparing
+// it produces false-positive drift, so it is excluded. `.git` is runtime VCS state.
+const EXCLUDED_DIRS = new Set(['.git', 'node_modules']);
+
+// Files to skip regardless of location. Lockfiles are install byproducts: their
+// bytes vary with registry ordering/timestamps and are not Forge assets. Excluding
+// them keeps parity strict for real assets (skills/rules/hooks/.forge/AGENTS.md)
+// while ignoring package-manager noise. `.package-lock.json` normally lives under
+// node_modules/ (already excluded) but is guarded here too for robustness.
+const EXCLUDED_FILES = new Set(['package-lock.json', '.package-lock.json']);
+
+/**
+ * Map of relative-posix-path → sha256 for every Forge-managed file under dir.
+ * Excludes .git, node_modules/**, and package-manager lockfiles (see the
+ * EXCLUDED_* sets above) so parity compares only Forge assets, not install output.
+ */
+function hashTree(dir) {
+  const map = {};
+  const walk = (abs, rel) => {
+    for (const e of fs.readdirSync(abs)) {
+      if (EXCLUDED_DIRS.has(e)) continue;
+      const a = path.join(abs, e);
+      const r = rel ? `${rel}/${e}` : e;
+      const st = fs.lstatSync(a);
+      if (st.isDirectory()) walk(a, r);
+      else if (st.isFile() && !EXCLUDED_FILES.has(e)) map[r] = sha256(a);
+    }
+  };
+  walk(dir, '');
+  return map;
+}
+
+function makeProject(label) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), `forge-parity-${label}-`));
+  execFileSync('git', ['init', '-q'], { cwd: dir });
+  execFileSync('git', ['config', 'user.email', 'parity@forge.test'], { cwd: dir });
+  execFileSync('git', ['config', 'user.name', 'parity'], { cwd: dir });
+  return dir;
+}
+
+function runSetup(label, cmd, args, dir) {
+  console.log(`\n[${label}] ${cmd} ${args.join(' ')}  (cwd=${dir})`);
+  const r = run(cmd, args, { cwd: dir });
+  if (r.status !== 0) {
+    console.error(`[${label}] setup exited ${r.status}`);
+    if (r.stdout) console.error(r.stdout.slice(-2000));
+    if (r.stderr) console.error(r.stderr.slice(-2000));
+    throw new Error(`[${label}] setup failed`);
+  }
+  return r;
+}
+
+function main() {
+  // 1. Build the binary (regenerates the embed manifest first).
+  console.log('Building single-file binary (bun run build:binary)…');
+  const build = run('bun', ['run', 'build:binary'], { cwd: REPO });
+  if (build.status !== 0) {
+    console.error(build.stdout || '');
+    console.error(build.stderr || '');
+    throw new Error('build:binary failed');
+  }
+  if (!fs.existsSync(BIN_PATH)) throw new Error(`binary not found at ${BIN_PATH}`);
+
+  // 2. Run setup from both channels into fresh git projects.
+  const setupArgs = ['setup', '--quick', '--yes'];
+  const npmDir = makeProject('npm');
+  const binDir = makeProject('bin');
+
+  // try/finally so the throwaway temp git projects are removed even when setup
+  // or the comparison throws (no leaked dirs on any failure path).
+  try {
+    runSetup('npm', 'node', [path.join(REPO, 'bin', 'forge.js'), ...setupArgs], npmDir);
+    runSetup('bin', BIN_PATH, setupArgs, binDir);
+
+    // 3. Compare trees.
+    const a = hashTree(npmDir);
+    const b = hashTree(binDir);
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    const missingInBin = [];
+    const missingInNpm = [];
+    const differing = [];
+    for (const k of keys) {
+      if (!(k in b)) missingInBin.push(k);
+      else if (!(k in a)) missingInNpm.push(k);
+      else if (a[k] !== b[k]) differing.push(k);
+    }
+
+    const problems = missingInBin.length + missingInNpm.length + differing.length;
+    console.log(`\nParity: ${Object.keys(a).length} npm files vs ${Object.keys(b).length} binary files.`);
+    if (missingInBin.length) console.log(`  Missing in binary: ${missingInBin.join(', ')}`);
+    if (missingInNpm.length) console.log(`  Missing in npm:    ${missingInNpm.join(', ')}`);
+    if (differing.length) console.log(`  Differing bytes:   ${differing.join(', ')}`);
+
+    if (problems > 0) {
+      console.error(`\nPARITY FAILED (${problems} discrepancies).`);
+      process.exit(1);
+    }
+    console.log('\nPARITY OK — npm and compiled binary produced byte-identical setup trees.');
+  } finally {
+    fs.rmSync(npmDir, { recursive: true, force: true });
+    fs.rmSync(binDir, { recursive: true, force: true });
+  }
+}
+
+// Exported for unit testing the asset-vs-install-artifact filtering. `hashTree`
+// and the exclusion sets are the load-bearing parity logic; the rest of the file
+// drives real builds and only runs when executed directly (guarded below).
+export { hashTree, EXCLUDED_DIRS, EXCLUDED_FILES };
+
+// Only build + compare when run as a script, not when imported by a test.
+if (import.meta.main) main();

package/scripts/parity-check.test.mjs

@@ -0,0 +1,58 @@
+// Unit test for the parity-check asset filtering. The parity check compares the
+// npm-vs-binary `setup --quick` trees; it MUST ignore package-manager install
+// byproducts (node_modules/**, lockfiles) that are legitimately non-deterministic
+// between runs/channels/OSes, while staying strict for real Forge assets. This
+// test pins that exclusion so a genuine skills/rules/hook drift still fails but
+// install junk never produces a false-positive parity failure.
+
+import { test, expect } from 'bun:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { hashTree, EXCLUDED_DIRS, EXCLUDED_FILES } from './parity-check.mjs';
+
+function mkTree() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'parity-hashtree-'));
+  // Real Forge-managed assets — these MUST be compared.
+  fs.mkdirSync(path.join(dir, 'skills'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'skills', 'SKILL.md'), 'real asset\n');
+  fs.writeFileSync(path.join(dir, 'AGENTS.md'), 'real asset\n');
+  // Install byproducts — these MUST be excluded.
+  fs.mkdirSync(path.join(dir, 'node_modules', 'left-pad'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'node_modules', 'left-pad', 'index.js'), 'junk\n');
+  fs.writeFileSync(path.join(dir, 'node_modules', '.package-lock.json'), '{}\n');
+  fs.writeFileSync(path.join(dir, 'package-lock.json'), '{"v":1}\n');
+  return dir;
+}
+
+test('hashTree excludes node_modules and lockfiles but keeps real assets', () => {
+  const dir = mkTree();
+  try {
+    const keys = Object.keys(hashTree(dir)).sort();
+    expect(keys).toEqual(['AGENTS.md', 'skills/SKILL.md']);
+    // No install artifact leaked into the comparison set.
+    expect(keys.some(k => k.includes('node_modules'))).toBe(false);
+    expect(keys.some(k => k.endsWith('package-lock.json'))).toBe(false);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('a real asset byte change is still detected (parity stays strict)', () => {
+  const dir = mkTree();
+  try {
+    const before = hashTree(dir);
+    fs.writeFileSync(path.join(dir, 'skills', 'SKILL.md'), 'DRIFTED asset\n');
+    const after = hashTree(dir);
+    expect(after['skills/SKILL.md']).not.toBe(before['skills/SKILL.md']);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('exclusion sets document the intended artifacts', () => {
+  expect(EXCLUDED_DIRS.has('node_modules')).toBe(true);
+  expect(EXCLUDED_DIRS.has('.git')).toBe(true);
+  expect(EXCLUDED_FILES.has('package-lock.json')).toBe(true);
+  expect(EXCLUDED_FILES.has('.package-lock.json')).toBe(true);
+});

package/scripts/pin-agentic-workflow-images.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DEFAULT_LOCK_FILES = [
+	'.github/agentic-workflows/behavioral-test.lock.yml',
+	'.github/workflows/behavioral-test.lock.yml',
+];
+
+const IMAGE_PINS = [
+	{
+		image: 'ghcr.io/github/gh-aw-mcpg:v0.3.0',
+		digest: 'sha256:9c2228324fb1f26f39dc9471612e530ae3efc3156dac05efb2e8d212878d454d',
+		pinnedImage: 'ghcr.io/github/gh-aw-mcpg@sha256:9c2228324fb1f26f39dc9471612e530ae3efc3156dac05efb2e8d212878d454d',
+	},
+	{
+		image: 'ghcr.io/github/github-mcp-server:v1.0.2',
+		digest: 'sha256:26db03408086a99cf1916348dcc4f9614206658f9082a8060dc7c81ad787f4ba',
+		pinnedImage: 'ghcr.io/github/github-mcp-server@sha256:26db03408086a99cf1916348dcc4f9614206658f9082a8060dc7c81ad787f4ba',
+	},
+];
+
+function updateManifestLine(line) {
+	const prefix = '# gh-aw-manifest: ';
+	if (!line.startsWith(prefix)) {
+		return line;
+	}
+
+	const manifest = JSON.parse(line.slice(prefix.length));
+	if (!Array.isArray(manifest.containers)) {
+		return line;
+	}
+
+	manifest.containers = manifest.containers.map((container) => {
+		const pin = IMAGE_PINS.find(candidate => candidate.image === container.image);
+		if (!pin) {
+			return container;
+		}
+
+		return {
+			...container,
+			digest: pin.digest,
+			pinned_image: pin.pinnedImage,
+		};
+	});
+
+	return `${prefix}${JSON.stringify(manifest)}`;
+}
+
+function pinLockContent(content) {
+	const lines = content.split(/\r?\n/);
+	if (lines.length > 1) {
+		lines[1] = updateManifestLine(lines[1]);
+	}
+
+	let pinned = lines.join('\n');
+	const manifestPrefix = /^# gh-aw-manifest: .*$/m;
+	const manifestMatch = pinned.match(manifestPrefix);
+	const manifestLine = manifestMatch ? manifestMatch[0] : null;
+	pinned = pinned.replace(manifestPrefix, '__GH_AW_MANIFEST_PLACEHOLDER__');
+
+	for (const pin of IMAGE_PINS) {
+		pinned = pinned.split(pin.image).join(pin.pinnedImage);
+	}
+
+	if (manifestLine) {
+		pinned = pinned.replace('__GH_AW_MANIFEST_PLACEHOLDER__', updateManifestLine(manifestLine));
+	}
+
+	return pinned;
+}
+
+function pinLockFile(filePath) {
+	const original = fs.readFileSync(filePath, 'utf8');
+	const pinned = pinLockContent(original);
+	if (pinned !== original) {
+		fs.writeFileSync(filePath, pinned, 'utf8');
+		return true;
+	}
+	return false;
+}
+
+function main() {
+	const args = process.argv.slice(2);
+	const files = args.length > 0 ? args : DEFAULT_LOCK_FILES;
+	const changed = [];
+
+	for (const file of files) {
+		const filePath = path.resolve(process.cwd(), file);
+		if (pinLockFile(filePath)) {
+			changed.push(file);
+		}
+	}
+
+	if (changed.length === 0) {
+		console.log('Agentic workflow runtime images already pinned');
+		return;
+	}
+
+	console.log(`Pinned agentic workflow runtime images: ${changed.join(', ')}`);
+}
+
+if (require.main === module) {
+	main();
+}
+
+module.exports = {
+	IMAGE_PINS,
+	pinLockContent,
+	pinLockFile,
+};

package/scripts/pr-coordinator.sh

@@ -15,6 +15,9 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [[ -f "$SCRIPT_DIR/bootstrap-windows-tools.sh" ]]; then
+  source "$SCRIPT_DIR/bootstrap-windows-tools.sh"
+fi
 source "$SCRIPT_DIR/lib/sanitize.sh" || { echo "FATAL: failed to source sanitize.sh" >&2; exit 2; }
 
 # Source these but don't fail if missing (tests may not have them)