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

package/lib/doc-assertions.js

@@ -0,0 +1,297 @@
+'use strict';
+
+/**
+ * Doc-assertion index — which test suites assert on which tracked markdown.
+ *
+ * Several suites read repository markdown and assert on its CONTENT (the README
+ * package-size badge, the AGENTS.md convention section, docs/ consistency). A
+ * markdown-only PR is classified as "docs" and skips the code matrix, so without
+ * this index those suites never run on the PR that breaks them — they fail later,
+ * on master, for the next unrelated code PR. That happened twice (kernel issue
+ * 63556816): the README size badge (#307/#310) and the AGENTS.md convention test
+ * after #325.
+ *
+ * The mapping is DERIVED by scanning the test sources rather than hardcoded, so a
+ * newly added markdown-reading suite is selected automatically instead of drifting
+ * out of a stale list.
+ *
+ * Detection is deliberately anchored, not literal-matching: only markdown reached
+ * from the REPOSITORY ROOT counts. Tests that write a throwaway `AGENTS.md` into a
+ * temp fixture directory join a tmpdir, not the repo root, so they are not selected.
+ *
+ * Suites that DISCOVER markdown (directory traversal, a glob, a `.md` filter) name
+ * no file to attribute, so they are selected on ANY markdown change instead — see
+ * `scansMarkdownDynamically`.
+ *
+ * @module doc-assertions
+ */
+
+const defaultFs = require('node:fs');
+const path = require('node:path');
+
+/** `path.join(...)` / `path.resolve(...)` (or bare `join`/`resolve`) with a flat argument list. */
+const PATH_CALL = /(?:path\s*\.\s*)?\b(?:join|resolve)\s*\(([^()]*)\)/g;
+
+/** A `const ROOT = path.resolve(__dirname, '..')`-style anchor declaration. */
+const ANCHOR_DECL = /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:path\s*\.\s*)?(?:join|resolve)\s*\(([^()]*)\)/g;
+
+/** A quoted string literal ending in `.md`. */
+const MARKDOWN_LITERAL = /['"`]([^'"`\n]*\.md)['"`]/g;
+
+/** A call that enumerates a directory or expands a glob instead of naming files. */
+// `.sync` member forms matter: `glob.sync('**/*.md')` has a `.` where this pattern would
+// otherwise expect `(`, so without the optional `.sync` the scanner is invisible and the
+// suite is under-selected — the exact failure this module exists to prevent.
+const DIRECTORY_SCAN_CALL = /\b(?:readdir|readdirSync|opendir|opendirSync|glob(?:Sync|\.sync)?|globby(?:\.sync)?|fastGlob(?:\.sync)?|walk|walkSync)\s*\(/;
+
+/** `.md` used as an EXTENSION test rather than a filename: glob, regex, or bare extension. */
+const MARKDOWN_EXTENSION_FILTER = /\*\.md\b|\\\.md\b|['"`]\.md['"`]/;
+
+/**
+ * Reports whether a repository-relative path is a markdown file.
+ *
+ * @param {string} file Repository-relative path.
+ * @returns {boolean} True for markdown paths.
+ */
+function isMarkdownPath(file) {
+	return typeof file === 'string' && file.toLowerCase().endsWith('.md');
+}
+
+/** Converts an absolute path to a forward-slash repository-relative path. */
+function toRepoRelative(repoRoot, absolutePath) {
+	return path.relative(repoRoot, absolutePath).split(path.sep).join('/');
+}
+
+/** Returns the value of a single-quoted/double-quoted/backtick string literal, or null. */
+function readStringLiteral(token) {
+	const match = /^'([^']*)'$|^"([^"]*)"$|^`([^`$]*)`$/.exec(token.trim());
+	if (!match) return null;
+	return match[1] ?? match[2] ?? match[3];
+}
+
+/** Splits a flat call-argument list into trimmed, non-empty tokens. */
+function splitArguments(rawArgs) {
+	return rawArgs.split(',').map((token) => token.trim()).filter(Boolean);
+}
+
+/**
+ * Collects every path anchor a test file can resolve against, keyed by identifier.
+ *
+ * Starts from `__dirname` and follows literal-only `path.join`/`path.resolve`
+ * declarations (e.g. `const ROOT = path.resolve(__dirname, '..')`).
+ *
+ * @param {string} source Test file source.
+ * @param {string} testDir Absolute directory containing the test file.
+ * @returns {Map<string, string>} Identifier → absolute directory.
+ */
+function collectAnchors(source, testDir) {
+	const anchors = new Map([['__dirname', testDir]]);
+	let match;
+	ANCHOR_DECL.lastIndex = 0;
+	while ((match = ANCHOR_DECL.exec(source)) !== null) {
+		const args = splitArguments(match[2]);
+		if (args.length === 0) continue;
+		const base = anchors.get(args[0]);
+		if (!base) continue;
+		const segments = args.slice(1).map(readStringLiteral);
+		if (segments.some((segment) => segment === null)) continue;
+		anchors.set(match[1], path.resolve(base, ...segments));
+	}
+	return anchors;
+}
+
+/**
+ * Finds markdown a single test file reads from the repository root.
+ *
+ * Two shapes are recognized:
+ *  1. A fully literal anchored path, e.g. `path.resolve(__dirname, '..', 'AGENTS.md')`.
+ *  2. A root-relative read helper, e.g. `const ROOT = join(__dirname, '..')` plus
+ *     `readFileSync(join(ROOT, relPath))`. Because the path is assembled at run
+ *     time, every markdown literal in the file that resolves to a real repository
+ *     file is attributed to that test (this is how `test/docs-consistency.test.js`
+ *     reads its documents).
+ *
+ * @param {string} repoRoot Absolute repository root.
+ * @param {string} testFile Absolute path to the test file.
+ * @param {string} source Test file source.
+ * @param {Object} fs Injected fs module.
+ * @returns {Set<string>} Repository-relative markdown paths the test asserts on.
+ */
+function findAssertedMarkdown(repoRoot, testFile, source, fs) {
+	const anchors = collectAnchors(source, path.dirname(testFile));
+	const found = new Set();
+
+	const addIfTracked = (relativePath) => {
+		if (!isMarkdownPath(relativePath)) return;
+		if (relativePath.startsWith('..')) return;
+		if (!fs.existsSync(path.join(repoRoot, relativePath))) return;
+		found.add(relativePath);
+	};
+
+	let match;
+	PATH_CALL.lastIndex = 0;
+	while ((match = PATH_CALL.exec(source)) !== null) {
+		const args = splitArguments(match[1]);
+		if (args.length === 0) continue;
+		const base = anchors.get(args[0]);
+		if (!base) continue;
+		const segments = args.slice(1).map(readStringLiteral);
+		if (segments.some((segment) => segment === null)) continue;
+		addIfTracked(toRepoRelative(repoRoot, path.resolve(base, ...segments)));
+	}
+
+	const rootAnchors = [...anchors]
+		.filter(([, directory]) => path.resolve(directory) === path.resolve(repoRoot))
+		.map(([identifier]) => identifier);
+	const readsRootRelativePaths = rootAnchors.some((identifier) => new RegExp(
+		`\\b(?:join|resolve)\\s*\\(\\s*${identifier}\\s*,\\s*[A-Za-z_$]`,
+	).test(source));
+
+	if (readsRootRelativePaths) {
+		MARKDOWN_LITERAL.lastIndex = 0;
+		while ((match = MARKDOWN_LITERAL.exec(source)) !== null) {
+			addIfTracked(match[1].replace(/^\.\//, ''));
+		}
+	}
+
+	return found;
+}
+
+/**
+ * Reports whether a test DISCOVERS markdown instead of naming it.
+ *
+ * `findAssertedMarkdown` can only attribute markdown that appears as a literal, so
+ * a suite that walks a directory (or expands a glob) and filters on `.md` maps to
+ * nothing and would never be selected — the false green this module exists to
+ * remove (`test/cleanup/dropped-agent-docs.test.js` is exactly that shape).
+ *
+ * Deliberately biased to OVER-selection: the two signals need not be on the same
+ * expression, because a few extra suites cost CI seconds while under-selection is
+ * what broke master twice. No attempt is made to resolve traversal roots into a
+ * file set — that would silently under-select again.
+ *
+ * @param {string} source Test file source.
+ * @returns {boolean} True when the test reaches markdown it does not name.
+ */
+function scansMarkdownDynamically(source) {
+	return DIRECTORY_SCAN_CALL.test(source) && MARKDOWN_EXTENSION_FILTER.test(source);
+}
+
+/** Recursively lists `*.test.js` files under a directory. */
+function listTestFiles(directory, fs, collected = []) {
+	let entries;
+	try {
+		entries = fs.readdirSync(directory, { withFileTypes: true });
+	} catch (_e) { // NOSONAR S2486
+		/* intentional: missing test directory yields no suites */
+		return collected;
+	}
+	for (const entry of entries) {
+		const entryPath = path.join(directory, entry.name);
+		if (entry.isDirectory()) {
+			listTestFiles(entryPath, fs, collected);
+		} else if (entry.name.endsWith('.test.js')) {
+			collected.push(entryPath);
+		}
+	}
+	return collected;
+}
+
+/** Sorts test paths deterministically. */
+function sortPaths(paths) {
+	return [...paths].sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * Scans the test tree once, splitting suites into the two ways they reach markdown.
+ *
+ * @param {string} repoRoot Absolute repository root.
+ * @param {Object} fs Injected fs module.
+ * @returns {{index: Map<string, string[]>, scanners: string[]}} Named-markdown index
+ *   plus the suites that discover markdown dynamically.
+ */
+function scanTestSuites(repoRoot, fs) {
+	const index = new Map();
+	const scanners = new Set();
+
+	for (const testFile of listTestFiles(path.join(repoRoot, 'test'), fs)) {
+		let source;
+		try {
+			source = fs.readFileSync(testFile, 'utf8');
+		} catch (_e) { // NOSONAR S2486
+			/* intentional: unreadable test file contributes nothing */
+			continue;
+		}
+		const testPath = toRepoRelative(repoRoot, testFile);
+		for (const docPath of findAssertedMarkdown(repoRoot, testFile, source, fs)) {
+			if (!index.has(docPath)) index.set(docPath, new Set());
+			index.get(docPath).add(testPath);
+		}
+		if (scansMarkdownDynamically(source)) scanners.add(testPath);
+	}
+
+	return {
+		index: new Map([...index].map(([docPath, suites]) => [docPath, sortPaths(suites)])),
+		scanners: sortPaths(scanners),
+	};
+}
+
+/**
+ * Builds the markdown → test-suite index for a checkout.
+ *
+ * Only covers suites that NAME their markdown; suites that discover it are returned
+ * by {@link findDynamicMarkdownScanners} because they map to no specific file.
+ *
+ * @param {string} repoRoot Absolute repository root.
+ * @param {Object} [fs=defaultFs] Injected fs module.
+ * @returns {Map<string, string[]>} Repository-relative markdown path → sorted test files.
+ */
+function buildDocAssertionIndex(repoRoot, fs = defaultFs) {
+	return scanTestSuites(repoRoot, fs).index;
+}
+
+/**
+ * Lists the suites that read markdown they never name (traversal, glob, `.md` filter).
+ *
+ * @param {string} repoRoot Absolute repository root.
+ * @param {Object} [fs=defaultFs] Injected fs module.
+ * @returns {string[]} Sorted test file paths.
+ */
+function findDynamicMarkdownScanners(repoRoot, fs = defaultFs) {
+	return scanTestSuites(repoRoot, fs).scanners;
+}
+
+/**
+ * Selects the suites that assert on the changed markdown.
+ *
+ * Returns an empty selection when no markdown changed, so the index is only built
+ * for changes that can actually break a doc-asserting suite.
+ *
+ * @param {string[]} changedFiles Repository-relative changed paths.
+ * @param {string} repoRoot Absolute repository root.
+ * @param {Object} [fs=defaultFs] Injected fs module.
+ * @returns {string[]} Sorted, de-duplicated test file paths.
+ */
+function selectDocAssertingTests(changedFiles, repoRoot, fs = defaultFs) {
+	const changedMarkdown = (changedFiles || []).filter(isMarkdownPath);
+	if (changedMarkdown.length === 0) return [];
+
+	const { index, scanners } = scanTestSuites(repoRoot, fs);
+	// Scanners discover markdown by traversal, so no changed path maps to them —
+	// any markdown change selects all of them.
+	const selected = new Set(scanners);
+	for (const docPath of changedMarkdown) {
+		for (const suite of index.get(docPath) || []) {
+			selected.add(suite);
+		}
+	}
+	return sortPaths(selected);
+}
+
+module.exports = {
+	buildDocAssertionIndex,
+	findDynamicMarkdownScanners,
+	isMarkdownPath,
+	scansMarkdownDynamically,
+	selectDocAssertingTests,
+};

package/lib/existing-tdd-gate.js

@@ -0,0 +1,253 @@
+/**
+ * Detect a repo's PRE-EXISTING pre-commit TDD / source-test coupling gate, so `forge setup`
+ * can DEFER to it instead of stacking Forge's own `rail.tdd_intent` gate on top.
+ *
+ * The in-the-wild beta.3 adoption report (kernel 5b425a85, predecessor 2699b234): a repo that
+ * already ships e.g. `scripts/check-source-test-coupling.mjs` on pre-commit ended up with TWO
+ * TDD gates blocking the same commit, with no detection and no reconciliation.
+ *
+ * Detection is by MECHANISM, not by a filename list: we enumerate the pre-commit COMMANDS that
+ * whatever pre-commit runner is actually installed (lefthook / husky / the `pre-commit`
+ * framework / a raw `.git/hooks/pre-commit`) will really execute, then classify those command
+ * strings. A repo's gate can be named anything, so the mechanism is what we key on.
+ *
+ * @module lib/existing-tdd-gate
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const YAML = require('yaml');
+
+const {
+  FORGE_NATIVE_HOOK_SENTINEL,
+  resolveGitHooksDir,
+} = require('./lefthook-wiring');
+
+// A pre-commit command is a TDD/coupling gate when its text carries one of these narrow
+// tokens: a `tdd` word, a source↔test coupling phrase, or an explicit require/check/enforce
+// tests task. Deliberately narrow — a plain test RUNNER (`npm test`) or a formatter is not a
+// TDD-intent gate and must not trigger a deferral.
+const TDD_GATE_PATTERNS = [
+  /(^|[^a-z0-9])tdd([^a-z0-9]|$)/i,
+  /(source[-_. ]?test|test[-_. ]?source)/i,
+  /((test|spec)[-_. ]?coupling|coupling[-_. ]?(test|spec|check))/i,
+  /(require|enforce|verify|guard)[-_. ]?(tests?|specs?)([^a-z0-9]|$)/i,
+  /check[-_. ]?(tests?|specs?)([^a-z0-9]|$)/i,
+];
+
+// Commands that ARE Forge's own gate. Excluded before classification so a second `forge setup`
+// never "detects" the gate its own first run installed and defers to itself.
+const FORGE_OWN_COMMAND_MARKERS = ['check-tdd.js', 'forge-native-hook.js'];
+
+// Signatures of a hook lefthook GENERATED (a disposable artifact that only dispatches to
+// lefthook.yml, which we read directly) — mirrors lib/lefthook-wiring.js's own classifier.
+const LEFTHOOK_GENERATED_MARKERS = ['call_lefthook', 'LEFTHOOK_BIN'];
+
+const LEFTHOOK_CONFIG_FILES = [
+  'lefthook.yml',
+  'lefthook.yaml',
+  '.lefthook.yml',
+  '.lefthook.yaml',
+  'lefthook-local.yml',
+  'lefthook-local.yaml',
+];
+
+const PRE_COMMIT_FRAMEWORK_FILES = ['.pre-commit-config.yaml', '.pre-commit-config.yml'];
+
+function isForgeOwnCommand(text) {
+  return FORGE_OWN_COMMAND_MARKERS.some((marker) => text.includes(marker));
+}
+
+function looksLikeTddGate(text) {
+  return TDD_GATE_PATTERNS.some((pattern) => pattern.test(text));
+}
+
+function readFileOrNull(absolute) {
+  try {
+    return fs.readFileSync(absolute, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+// One candidate = one command string a pre-commit runner will execute, plus where it came from.
+function candidate(source, command) {
+  return { source, command: String(command).trim() };
+}
+
+// Shell-script hooks (husky, raw .git/hooks): every meaningful line is a command.
+function commandsFromScript(source, body) {
+  return body
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0 && !line.startsWith('#'))
+    .map((line) => candidate(source, line));
+}
+
+// lefthook pre-commit: `commands.<name>.run`, `scripts.<name>`, and the v1.11+ `jobs` list.
+// The job NAME carries signal too (a job called `tdd-guard`), so both are collected.
+function commandsFromLefthookPreCommit(source, preCommit) {
+  const out = [];
+  if (!preCommit || typeof preCommit !== 'object') return out;
+
+  for (const [name, job] of Object.entries(preCommit.commands || {})) {
+    out.push(candidate(source, `${name}: ${(job && job.run) || ''}`));
+  }
+  for (const [name, job] of Object.entries(preCommit.scripts || {})) {
+    out.push(candidate(source, `${name} ${(job && job.runner) || ''}`));
+  }
+  for (const job of Array.isArray(preCommit.jobs) ? preCommit.jobs : []) {
+    if (job && typeof job === 'object') {
+      out.push(candidate(source, `${job.name || ''}: ${job.run || ''}`));
+    }
+  }
+  return out;
+}
+
+// Returns { candidates } normally, or { unknown: true } when a pre-commit mechanism is present
+// but its content cannot be read/parsed — we cannot rule out a TDD gate, so the caller defers.
+function collectFromLefthookConfigs(projectRoot) {
+  const candidates = [];
+  for (const name of LEFTHOOK_CONFIG_FILES) {
+    const absolute = path.join(projectRoot, name);
+    if (!fs.existsSync(absolute)) continue;
+    const body = readFileOrNull(absolute);
+    if (body === null) return { unknown: true, source: name };
+
+    let doc;
+    try {
+      doc = YAML.parse(body);
+    } catch {
+      // Unparseable: only ambiguous if it actually declares a pre-commit section.
+      if (body.includes('pre-commit')) return { unknown: true, source: name };
+      continue;
+    }
+    if (!doc || typeof doc !== 'object') continue;
+    candidates.push(...commandsFromLefthookPreCommit(name, doc['pre-commit']));
+  }
+  return { candidates };
+}
+
+function collectFromHusky(projectRoot) {
+  const relative = '.husky/pre-commit'; // display label — always POSIX-style, never OS-separated
+  const absolute = path.join(projectRoot, '.husky', 'pre-commit');
+  if (!fs.existsSync(absolute)) return { candidates: [] };
+  const body = readFileOrNull(absolute);
+  if (body === null) return { unknown: true, source: relative };
+  return { candidates: commandsFromScript(relative, body) };
+}
+
+function collectFromPreCommitFramework(projectRoot) {
+  const candidates = [];
+  for (const name of PRE_COMMIT_FRAMEWORK_FILES) {
+    const absolute = path.join(projectRoot, name);
+    if (!fs.existsSync(absolute)) continue;
+    const body = readFileOrNull(absolute);
+    if (body === null) return { unknown: true, source: name };
+
+    let doc;
+    try {
+      doc = YAML.parse(body);
+    } catch {
+      return { unknown: true, source: name };
+    }
+    for (const repo of (doc && Array.isArray(doc.repos)) ? doc.repos : []) {
+      for (const hook of (repo && Array.isArray(repo.hooks)) ? repo.hooks : []) {
+        if (!hook || typeof hook !== 'object') continue;
+        candidates.push(candidate(name, `${hook.id || ''} ${hook.name || ''} ${hook.entry || ''}`));
+      }
+    }
+  }
+  return { candidates };
+}
+
+// The raw hook git will actually run. Forge's own native hook and a lefthook-GENERATED
+// dispatcher are skipped: neither is a third-party gate (the latter's real jobs live in
+// lefthook.yml, which collectFromLefthookConfigs already read).
+function collectFromNativeHook(projectRoot) {
+  const hooksDir = resolveGitHooksDir(projectRoot);
+  if (!hooksDir) return { candidates: [] };
+  const absolute = path.join(hooksDir, 'pre-commit');
+  if (!fs.existsSync(absolute)) return { candidates: [] };
+  const body = readFileOrNull(absolute);
+  if (body === null) return { unknown: true, source: 'pre-commit (git hooks dir)' };
+  if (body.includes(FORGE_NATIVE_HOOK_SENTINEL)) return { candidates: [] };
+  if (LEFTHOOK_GENERATED_MARKERS.some((marker) => body.includes(marker))) return { candidates: [] };
+  return { candidates: commandsFromScript('pre-commit (git hooks dir)', body) };
+}
+
+/**
+ * Detect a pre-existing pre-commit TDD / source-test coupling gate in the project.
+ *
+ * @param {string} projectRoot - Absolute path to the project root.
+ * @returns {{ found: boolean, source?: string, command?: string, unknown?: boolean }}
+ *   `found:true` with `source`/`command` for a classified gate; `found:true, unknown:true`
+ *   when a pre-commit mechanism exists but could not be read (defer — the safe side);
+ *   `found:false` when nothing pre-existing enforces TDD.
+ */
+function detectExistingTddGate(projectRoot) {
+  const collectors = [
+    collectFromLefthookConfigs,
+    collectFromHusky,
+    collectFromPreCommitFramework,
+    collectFromNativeHook,
+  ];
+
+  let ambiguous = null;
+  const candidates = [];
+  for (const collect of collectors) {
+    let result;
+    try {
+      result = collect(projectRoot);
+    } catch {
+      continue; // a collector failure must never break setup
+    }
+    if (result.unknown) {
+      ambiguous = ambiguous || { source: result.source };
+      continue;
+    }
+    candidates.push(...(result.candidates || []));
+  }
+
+  for (const item of candidates) {
+    if (isForgeOwnCommand(item.command)) continue;
+    if (looksLikeTddGate(item.command)) {
+      return { found: true, source: item.source, command: item.command };
+    }
+  }
+
+  if (ambiguous) {
+    return { found: true, unknown: true, source: ambiguous.source, command: '' };
+  }
+  return { found: false };
+}
+
+/**
+ * The user-facing deferral report. Silent stacking and silent skipping are BOTH wrong — the
+ * adopter must see what was detected, what Forge did not install, and how to choose otherwise.
+ *
+ * @param {{ found: boolean, source?: string, command?: string, unknown?: boolean }} detection
+ * @returns {string|null} Report text, or null when there is nothing to defer to.
+ */
+function describeExistingGateDeferral(detection) {
+  if (!detection || !detection.found) return null;
+
+  const what = detection.unknown
+    ? `an existing pre-commit hook Forge could not read (${detection.source})`
+    : `an existing pre-commit TDD/coupling gate in ${detection.source}:\n      ${detection.command}`;
+
+  return [
+    `  ⚠ Detected ${what}`,
+    '    Forge did NOT install its own TDD gate on pre-commit — deferring to yours, so you',
+    '    do not get two gates blocking the same commit. rail.tdd_intent is off in .forge/config.yaml.',
+    "    Prefer Forge's gate instead? Remove or disable your own, then run:",
+    '      forge gate enable rail.tdd_intent',
+  ].join('\n');
+}
+
+module.exports = {
+  detectExistingTddGate,
+  describeExistingGateDeferral,
+};

package/lib/fixtures/beta5-corpus/v1/README.md

@@ -0,0 +1,9 @@
+# Forge 0.1.0-beta.5 compatibility corpus v1
+
+This immutable corpus is derived from release commit
+`ebeb4e5b31fc2dacdf23c5936c02fb2656990f49`. Contract snapshots retain only
+public package, binary, command, alias, and workflow facts. State rows are
+synthetic and contain no user, device, prompt, tool-log, or repository data.
+
+`manifest.json` hashes every corpus member. Change requires a new corpus
+version; never rewrite v1 after it becomes release evidence.

package/lib/fixtures/beta5-corpus/v1/contract/command-contract.json

@@ -0,0 +1,26 @@
+{
+  "commands": ["adapter", "add", "audit", "blocked", "claim", "claims", "clean", "close", "comment", "control", "create", "dev", "doc-gate", "doctor", "explain", "export", "gate", "hooks", "inbox", "init", "insights", "issue", "issues", "lint", "list", "memory", "merge", "migrate", "new", "options", "orient", "orphans", "patch", "plan", "pr", "preflight", "prime", "push", "ready", "recall", "recap", "recommend", "release", "remember", "role", "serve", "setup", "shepherd", "ship", "show", "skill", "stage", "stale", "status", "sync", "team", "test", "update", "upgrade", "validate", "worktree"],
+  "aliases": {
+    "blocked": { "canonical": "issue blocked", "visible": false },
+    "claim": { "canonical": "issue claim", "visible": false },
+    "claims": { "canonical": "issue claims", "visible": false },
+    "close": { "canonical": "issue close", "visible": false },
+    "create": { "canonical": "issue create", "visible": false },
+    "doc-gate": { "canonical": "gate doc", "visible": false },
+    "insights": { "canonical": "memory insights", "visible": true },
+    "issues": { "canonical": "issue list", "visible": false },
+    "lint": { "canonical": "issue lint", "visible": false },
+    "list": { "canonical": "issue list", "visible": false },
+    "merge": { "canonical": "pr merge", "visible": false },
+    "orphans": { "canonical": "issue orphans", "visible": false },
+    "preflight": { "canonical": "pr preflight", "visible": true },
+    "ready": { "canonical": "issue ready", "visible": false },
+    "recall": { "canonical": "memory recall", "visible": true },
+    "remember": { "canonical": "memory add", "visible": true },
+    "shepherd": { "canonical": "pr shepherd", "visible": false },
+    "ship": { "canonical": "pr ship", "visible": true },
+    "show": { "canonical": "issue show", "visible": false },
+    "stale": { "canonical": "issue stale", "visible": false },
+    "update": { "canonical": "issue update", "visible": false }
+  }
+}

package/lib/fixtures/beta5-corpus/v1/contract/package-contract.json

@@ -0,0 +1,13 @@
+{
+  "name": "forge-workflow",
+  "version": "0.1.0-beta.5",
+  "release_commit": "ebeb4e5b31fc2dacdf23c5936c02fb2656990f49",
+  "binaries": {
+    "forge": "bin/forge.js",
+    "forge-workflow": "bin/forge.js",
+    "forge-preflight": "bin/forge-preflight.js"
+  },
+  "engines": {
+    "node": ">=22.16.0"
+  }
+}

package/lib/fixtures/beta5-corpus/v1/contract/workflow-stage-matrix.json

@@ -0,0 +1,8 @@
+{
+  "critical": ["plan", "dev", "validate", "ship", "review", "verify"],
+  "standard": ["plan", "dev", "validate", "ship", "review"],
+  "refactor": ["plan", "dev", "validate", "ship"],
+  "simple": ["dev", "validate", "ship"],
+  "hotfix": ["dev", "validate", "ship"],
+  "docs": ["verify", "ship"]
+}

package/lib/fixtures/beta5-corpus/v1/manifest.json

@@ -0,0 +1,25 @@
+{
+  "schema_version": "forge.beta5-corpus.v1",
+  "corpus_version": 1,
+  "release_version": "0.1.0-beta.5",
+  "release_commit": "ebeb4e5b31fc2dacdf23c5936c02fb2656990f49",
+  "source_blobs": {
+    "package.json": "6f3f112341cd50e0e76fad615beb007b9e6dff2c",
+    "lib/commands/_manifest.js": "62595c38b66b139244ca1f54cb034f67d849247d",
+    "lib/commands/_aliases.js": "2b16d61d1cdb9ef3e594b5a5093206d05844b460",
+    "lib/workflow/stages.js": "0b7ae32bddcbb9bd6dd52a07ca22e43364621918"
+  },
+  "hash_algorithm": "sha256",
+  "content_hash": "c6978eed757c6255f2d25ea6d49ada44e5b3da91830d348016267981d13afd18",
+  "files": [
+    { "path": "README.md", "sha256": "3cfcc78856e397f2cfd3fee9fa2fffb630e27ea3e76ee8d8b5d9a77cb366a709" },
+    { "path": "contract/command-contract.json", "sha256": "8b4f885091fa8afe72b7b5a5a8039869c871f4fb1dc3344728b2c4322f491a84" },
+    { "path": "contract/package-contract.json", "sha256": "a65280ede51d62c1913140c83b40e6c3312c991c7a173e7a9ad52d3d5ea0fd47" },
+    { "path": "contract/workflow-stage-matrix.json", "sha256": "2aadafdb5f5c1817c8289dd6134d034e3ccc6579438935520bd3c6b90401e5bf" },
+    { "path": "state/comments.jsonl", "sha256": "ae4f694f207a11a22b6798943cc6d07487d1dc2be83a78ceadad947a3ff40113" },
+    { "path": "state/config.yaml", "sha256": "0b877d9180cf14951657254b50cd771e131970e92582a7c0337f36418a35e1c0" },
+    { "path": "state/dependencies.jsonl", "sha256": "cb43cc053d6dd885254a26f6d6b024883f770eb68f50b715cc2f0f05e2cd31e5" },
+    { "path": "state/issues.jsonl", "sha256": "425567c5c7b70fd6bbdf9ead3aff78c09a77ebe7b78d3c856c045743b8cb924e" },
+    { "path": "state/kernel.sql", "sha256": "4208aabcadc6cec3234ebb5abd4cbf32cc74805433d04a05801e0b6354b53d27" }
+  ]
+}

package/lib/fixtures/beta5-corpus/v1/state/comments.jsonl

@@ -0,0 +1 @@
+{"id":"synthetic-comment-1","issue_id":"synthetic-issue-1","body":"Synthetic comment","actor":"fixture"}

package/lib/fixtures/beta5-corpus/v1/state/config.yaml

@@ -0,0 +1,6 @@
+workflow:
+  profile: default
+gates:
+  gate.issue_verify: true
+rails:
+  rail.kernel_tracking: true

package/lib/fixtures/beta5-corpus/v1/state/dependencies.jsonl

@@ -0,0 +1 @@
+{"issue_id":"synthetic-issue-1","blocks_issue_id":"synthetic-issue-2"}

package/lib/fixtures/beta5-corpus/v1/state/issues.jsonl

@@ -0,0 +1,2 @@
+{"id":"synthetic-issue-1","title":"Synthetic issue","status":"open","entity_revision":2}
+{"id":"synthetic-issue-2","title":"Synthetic dependency","status":"done","entity_revision":1}