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

package/lib/commands/worktree.js

@@ -109,20 +109,106 @@ function isLinkPermissionError(error) {
 // inspect, and `yarn check` was removed in Berry, so there is nothing to verify.
 const PROBE_LESS_MANAGERS = new Set(['yarn']);
 
+function samePath(left, right) {
+  return path.relative(left, right) === '';
+}
+
 /**
- * Direct dependencies the worktree declares. Optional/peer deps are excluded —
- * they may legitimately be absent. An unreadable package.json yields none, so an
- * unverifiable worktree is left alone rather than force-reinstalled.
+ * Direct dependencies the root and its workspaces declare. Optional/peer deps
+ * are excluded — they may legitimately be absent. Workspace discovery fails
+ * closed so an incomplete manifest set cannot prove an install complete.
  * @param {string} worktreePath - Absolute path to the worktree
  * @param {object} fsApi - fs module (for DI)
- * @returns {string[]} Declared package names
+ * @returns {Array<{dir: string, name: string, workspaceDir: string|null}>} Declaring directory and package name
  */
 function declaredDependencies(worktreePath, fsApi) {
+  let rootPkg;
+  try {
+    rootPkg = JSON.parse(fsApi.readFileSync(path.join(worktreePath, 'package.json'), 'utf8'));
+  } catch (error) {
+    throw new Error(`Cannot verify dependencies: unreadable worktree package.json: ${error.message}`);
+  }
+
+  let workspacePatterns = [];
+  if (rootPkg.workspaces != null) {
+    workspacePatterns = Array.isArray(rootPkg.workspaces)
+      ? rootPkg.workspaces
+      : rootPkg.workspaces.packages;
+    if (!Array.isArray(workspacePatterns)) {
+      throw new Error('Cannot verify dependencies: workspaces must be an array or an object with a packages array');
+    }
+  }
+
+  if (workspacePatterns.length && typeof fsApi.globSync !== 'function') {
+    throw new Error('Cannot verify dependencies: this runtime does not provide workspace glob support');
+  }
+
+  const manifestPaths = new Set();
+  for (const rawPattern of workspacePatterns) {
+    if (typeof rawPattern !== 'string' || !rawPattern.trim()) {
+      throw new Error(`Cannot verify dependencies: invalid workspace pattern ${JSON.stringify(rawPattern)}`);
+    }
+    const exclude = rawPattern.startsWith('!');
+    const pattern = (exclude ? rawPattern.slice(1) : rawPattern).replace(/\\/g, '/').replace(/\/+$/, '');
+    const resolvedPattern = resolveRepoRelativePath(worktreePath, pattern);
+    if (!pattern || pattern.includes('\0') || path.isAbsolute(pattern) || !resolvedPattern.insideRoot) {
+      throw new Error(`Cannot verify dependencies: workspace pattern resolves outside the worktree: ${rawPattern}`);
+    }
+
+    let matches;
+    try {
+      matches = fsApi.globSync(`${pattern}/package.json`, {
+        cwd: worktreePath,
+        exclude: candidate => String(candidate).split(/[\\/]/).includes('node_modules'),
+      });
+    } catch (error) {
+      throw new Error(`Cannot verify dependencies: workspace glob failed for ${rawPattern}: ${error.message}`);
+    }
+    for (const match of matches) {
+      const resolved = resolveRepoRelativePath(worktreePath, String(match));
+      if (!resolved.insideRoot) {
+        throw new Error(`Cannot verify dependencies: workspace glob resolved outside the worktree: ${match}`);
+      }
+      const existing = [...manifestPaths].find(manifestPath => samePath(manifestPath, resolved.target));
+      if (exclude && existing) manifestPaths.delete(existing);
+      else if (!exclude && !existing) manifestPaths.add(resolved.target);
+    }
+  }
+
+  const manifests = [{ dir: worktreePath, pkg: rootPkg }];
+  for (const manifestPath of manifestPaths) {
+    try {
+      manifests.push({
+        dir: path.dirname(manifestPath),
+        pkg: JSON.parse(fsApi.readFileSync(manifestPath, 'utf8')),
+      });
+    } catch (error) {
+      if (error && ['ENOENT', 'ENOTDIR'].includes(error.code)) continue;
+      throw new Error(`Cannot verify dependencies: unreadable workspace manifest ${manifestPath}: ${error.message}`);
+    }
+  }
+
+  const workspaceDirs = new Map();
+  for (const { dir, pkg } of manifests.slice(1)) {
+    if (!pkg.name) continue;
+    if (workspaceDirs.has(pkg.name) && !samePath(workspaceDirs.get(pkg.name), dir)) {
+      throw new Error(`Cannot verify dependencies: duplicate workspace package name ${pkg.name}`);
+    }
+    workspaceDirs.set(pkg.name, dir);
+  }
+  return manifests.flatMap(({ dir, pkg }) => [
+    ...Object.keys(pkg.dependencies || {}),
+    ...Object.keys(pkg.devDependencies || {}),
+  ].map(name => ({ dir, name, workspaceDir: workspaceDirs.get(name) || null })));
+}
+
+function dependencyCandidatePresent(candidate, workspaceDir, fsApi) {
+  if (!fsApi.existsSync(path.join(candidate, 'package.json'))) return false;
+  if (!workspaceDir) return true;
   try {
-    const pkg = JSON.parse(fsApi.readFileSync(path.join(worktreePath, 'package.json'), 'utf8'));
-    return [...Object.keys(pkg.dependencies || {}), ...Object.keys(pkg.devDependencies || {})];
-  } catch (_err) { /* intentional: no readable package.json → nothing to verify */ // NOSONAR S2486
-    return [];
+    return path.relative(fsApi.realpathSync(workspaceDir), fsApi.realpathSync(candidate)) === '';
+  } catch (_err) { /* intentional: an unresolvable workspace link is not installed */ // NOSONAR S2486
+    return false;
   }
 }
 
@@ -138,11 +224,33 @@ function declaredDependencies(worktreePath, fsApi) {
  *
  * @param {string} worktreePath - Absolute path to the worktree
  * @param {object} fsApi - fs module (for DI)
+ * @param {string|null} pkgManager - Detected package manager
  * @returns {boolean} true when nothing is missing
  */
-function dependenciesPresent(worktreePath, fsApi) {
+function dependenciesPresent(worktreePath, fsApi, pkgManager) {
+  if (!pkgManager) return true;
   const deps = declaredDependencies(worktreePath, fsApi);
-  return deps.every((name) => fsApi.existsSync(path.join(worktreePath, 'node_modules', name, 'package.json')));
+  return deps.every(({ dir, name, workspaceDir }) => {
+    const localPackage = path.join(dir, 'node_modules', name);
+    if (fsApi.existsSync(localPackage)) {
+      return dependencyCandidatePresent(localPackage, workspaceDir, fsApi);
+    }
+
+    const rootPackage = path.join(worktreePath, 'node_modules', name);
+    if (dir === worktreePath || (pkgManager === 'bun' && !workspaceDir)) return false;
+    return dependencyCandidatePresent(rootPackage, workspaceDir, fsApi);
+  });
+}
+
+function detachModulesLink(modulesPath, fsApi) {
+  try {
+    if (!fsApi.lstatSync(modulesPath).isSymbolicLink()) return false;
+    fsApi.unlinkSync(modulesPath);
+    return true;
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return false;
+    throw error;
+  }
 }
 
 const STDERR_DETAIL_LIMIT = 400;
@@ -199,21 +307,21 @@ function spawnInstall(pkgManager, args, worktreePath, spawnFn) {
  * @param {string} projectRoot - Absolute path to the project root
  * @param {Function} spawnFn - spawnSync-compatible function
  * @param {object} fsApi - fs module (for DI)
+ * @param {string|null} [pkgManager] - Detected package manager
  * @returns {{ linked: boolean, installed: boolean, healed: boolean }}
  * @throws {Error} when the install fails, or the tree is still broken after --force.
  */
-function runInstall(worktreePath, projectRoot, spawnFn, fsApi) {
-  const pkgManager = detectPackageManager(projectRoot, fsApi);
+function runInstall(worktreePath, projectRoot, spawnFn, fsApi, pkgManager = detectPackageManager(projectRoot, fsApi)) {
   if (!pkgManager) return { linked: false, installed: false, healed: false };
 
   spawnInstall(pkgManager, ['install'], worktreePath, spawnFn);
 
-  if (PROBE_LESS_MANAGERS.has(pkgManager) || dependenciesPresent(worktreePath, fsApi)) {
+  if (PROBE_LESS_MANAGERS.has(pkgManager) || dependenciesPresent(worktreePath, fsApi, pkgManager)) {
     return { linked: false, installed: true, healed: false };
   }
 
   spawnInstall(pkgManager, ['install', '--force'], worktreePath, spawnFn);
-  if (!dependenciesPresent(worktreePath, fsApi)) {
+  if (!dependenciesPresent(worktreePath, fsApi, pkgManager)) {
     throw new Error(`Dependency install could not be verified: packages are still missing in ${worktreePath} after '${pkgManager} install --force'. Run it manually there and inspect the output.`);
   }
   return { linked: false, installed: true, healed: true };
@@ -237,24 +345,38 @@ function runInstall(worktreePath, projectRoot, spawnFn, fsApi) {
 function setupWorktreeDeps(worktreePath, projectRoot, { spawnFn, fsApi, platform }) {
   const srcModules = path.join(projectRoot, 'node_modules');
   const destModules = path.join(worktreePath, 'node_modules');
+  const pkgManager = detectPackageManager(projectRoot, fsApi);
+
+  // Keep the zero-install fast path only when root and workspace dependencies
+  // are complete; Bun's isolated linker keeps workspace packages below each workspace.
+  if (fsApi.existsSync(destModules)) {
+    if (dependenciesPresent(worktreePath, fsApi, pkgManager)) return { linked: false, installed: false, healed: false };
+    detachModulesLink(destModules, fsApi);
+    return runInstall(worktreePath, projectRoot, spawnFn, fsApi, pkgManager);
+  }
 
-  // Already populated (e.g. git checkout carried it) — nothing to do.
-  if (fsApi.existsSync(destModules)) return { linked: false, installed: false, healed: false };
+  // existsSync follows links, so remove a dangling directory entry before
+  // either replacing it with the shared install or installing in its place.
+  detachModulesLink(destModules, fsApi);
 
   // Fast path: link to the shared install when the main repo has one.
   if (fsApi.existsSync(srcModules)) {
     const linkType = platform === 'win32' ? 'junction' : 'dir';
     try {
       fsApi.symlinkSync(srcModules, destModules, linkType);
-      return { linked: true, installed: false, healed: false };
     } catch (error) {
       // Degrade to a real install only when the link was refused for lack of
       // privilege/support; any other failure is surfaced to the caller.
       if (!isLinkPermissionError(error)) throw error;
+      return runInstall(worktreePath, projectRoot, spawnFn, fsApi, pkgManager);
+    }
+    if (dependenciesPresent(worktreePath, fsApi, pkgManager)) {
+      return { linked: true, installed: false, healed: false };
     }
+    fsApi.unlinkSync(destModules);
   }
 
-  return runInstall(worktreePath, projectRoot, spawnFn, fsApi);
+  return runInstall(worktreePath, projectRoot, spawnFn, fsApi, pkgManager);
 }
 
 function readExistingWorktreeLinkage(driver, worktreePath, reuse) {
@@ -504,12 +626,26 @@ async function handleCreate(slug, flags, projectRoot, opts) {
     if (linkage.conflict) {
       return { success: false, reused: true, error: linkage.reason, worktreePath, linkage };
     }
+    let deps;
+    try {
+      deps = setupWorktreeDeps(worktreePath, projectRoot, {
+        spawnFn: runSpawn,
+        fsApi,
+        platform: opts._platform || process.platform,
+      });
+    } catch (error) {
+      return { success: false, reused: true, error: error.message, worktreePath, linkage };
+    }
     const backing = await autoFileBackingIssue({ projectRoot, worktreePath, branch: existingBranch, issueId, opts });
+    const healNote = deps.healed ? ' Healed dependencies (store was stale): reinstalled with --force.' : '';
     return {
       success: true,
       reused: true,
-      message: `Worktree already exists at ${worktreePath}`,
+      message: `Worktree already exists at ${worktreePath}.${healNote}`,
       worktreePath,
+      depsLinked: deps.linked,
+      depsInstalled: deps.installed,
+      depsHealed: deps.healed,
       linkage,
       backing,
     };

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}

package/lib/fixtures/beta5-corpus/v1/state/kernel.sql

@@ -0,0 +1,20 @@
+PRAGMA user_version = 1;
+CREATE TABLE kernel_migrations (id TEXT PRIMARY KEY, applied_at TEXT NOT NULL);
+CREATE TABLE kernel_issues (id TEXT PRIMARY KEY, title TEXT NOT NULL, status TEXT NOT NULL, entity_revision INTEGER NOT NULL);
+CREATE TABLE kernel_comments (id TEXT PRIMARY KEY, issue_id TEXT NOT NULL, body TEXT NOT NULL, actor TEXT NOT NULL);
+CREATE TABLE kernel_dependencies (id TEXT PRIMARY KEY, issue_id TEXT NOT NULL, blocks_issue_id TEXT NOT NULL);
+CREATE TABLE kernel_claims (id TEXT PRIMARY KEY, issue_id TEXT NOT NULL, actor TEXT NOT NULL, state TEXT NOT NULL);
+CREATE TABLE kernel_worktrees (id TEXT PRIMARY KEY, path TEXT NOT NULL, branch TEXT NOT NULL, state TEXT NOT NULL);
+CREATE TABLE kernel_stage_runs (id TEXT PRIMARY KEY, issue_id TEXT NOT NULL, stage TEXT NOT NULL, status TEXT NOT NULL);
+CREATE TABLE kernel_projections (id TEXT PRIMARY KEY, target TEXT NOT NULL, entity_type TEXT NOT NULL, entity_id TEXT NOT NULL, status TEXT NOT NULL);
+CREATE TABLE kernel_events (id TEXT PRIMARY KEY, entity_type TEXT NOT NULL, entity_id TEXT NOT NULL, event_type TEXT NOT NULL);
+INSERT INTO kernel_migrations VALUES ('001_initial_kernel_schema', '2026-08-09T00:00:00.000Z');
+INSERT INTO kernel_issues VALUES ('synthetic-issue-1', 'Synthetic issue', 'open', 2); -- NOSONAR S1192: repeated synthetic foreign key preserves fixture readability.
+INSERT INTO kernel_issues VALUES ('synthetic-issue-2', 'Synthetic dependency', 'done', 1);
+INSERT INTO kernel_comments VALUES ('synthetic-comment-1', 'synthetic-issue-1', 'Synthetic comment', 'fixture');
+INSERT INTO kernel_dependencies VALUES ('synthetic-dependency-1', 'synthetic-issue-1', 'synthetic-issue-2');
+INSERT INTO kernel_claims VALUES ('synthetic-claim-1', 'synthetic-issue-1', 'fixture', 'active');
+INSERT INTO kernel_worktrees VALUES ('synthetic-worktree-1', '/synthetic/worktree', 'fixture/branch', 'active');
+INSERT INTO kernel_stage_runs VALUES ('synthetic-run-1', 'synthetic-issue-1', 'dev', 'done');
+INSERT INTO kernel_projections VALUES ('synthetic-projection-1', 'jsonl', 'issue', 'synthetic-issue-1', 'delivered');
+INSERT INTO kernel_events VALUES ('synthetic-event-1', 'issue', 'synthetic-issue-1', 'issue.updated');

package/lib/forge-issues.js

@@ -7,6 +7,8 @@ const { createLocalBroker, buildLocalBrokerConfig } = require('./kernel/broker')
 const { createBuiltinSQLiteDriver } = require('./kernel/sqlite-driver');
 const { detectWorktree } = require('./detect-worktree');
 const { DEFAULT_LEASE_TTL_MS } = require('./kernel/lease-enforcer');
+const { ISSUE_TYPES } = require('./kernel/issue-command-contract');
+const { loadRuntimeGraphConfig } = require('./core/runtime-graph');
 
 const OPERATION_METHOD_ALIASES = {
   'dep.add': 'depAdd',
@@ -199,6 +201,75 @@ function resolveLeaseTtlMs(env = {}) {
   return ttl;
 }
 
+function readIssueContractValues(loaded, fail) {
+	const missing = Symbol('missing issue contract config');
+	const ownDataValue = (object, key, path) => {
+		if (!object || (typeof object !== 'object' && typeof object !== 'function')) return missing;
+		const descriptor = Object.getOwnPropertyDescriptor(object, key);
+		if (!descriptor) return missing;
+		if (!Object.prototype.hasOwnProperty.call(descriptor, 'value')) {
+			fail(`${path} must be a data property`);
+		}
+		return descriptor.value;
+	};
+	const issues = ownDataValue(loaded?.config, 'issues', 'issues');
+	const readiness = issues === missing ? missing : ownDataValue(issues, 'readiness', 'issues.readiness');
+	const configured = readiness === missing
+		? missing
+		: ownDataValue(readiness, 'contracts', 'issues.readiness.contracts');
+	if (configured === missing || configured == null) return null;
+	if (typeof configured !== 'object'
+		|| Array.isArray(configured)
+		|| Object.getPrototypeOf(configured) !== Object.prototype) {
+		fail('issues.readiness.contracts must be a plain JSON object');
+	}
+	const allowedKeys = new Set(['enabled', 'workClasses']);
+	const ownKeys = Reflect.ownKeys(configured);
+	const unknownKeys = ownKeys.filter(key => typeof key !== 'string' || !allowedKeys.has(key));
+	if (unknownKeys.length > 0) {
+		fail(`unknown issues.readiness.contracts keys: ${unknownKeys.map(String).sort((left, right) => left.localeCompare(right)).join(', ')}`);
+	}
+	const values = Object.create(null);
+	for (const key of ownKeys) {
+		const descriptor = Object.getOwnPropertyDescriptor(configured, key);
+		if (!descriptor || !Object.prototype.hasOwnProperty.call(descriptor, 'value')) {
+			fail(`issues.readiness.contracts.${key} must be a data property`);
+		}
+		values[key] = descriptor.value;
+	}
+	return values;
+}
+
+function resolveIssueContractPolicy(projectRoot, deps = {}) {
+	const loadConfig = deps.loadRuntimeGraphConfig || loadRuntimeGraphConfig;
+	const loaded = loadConfig({ projectRoot });
+	const fail = message => {
+		const error = new Error(`FORGE_ISSUE_CONTRACT_CONFIG_INVALID: ${message}`);
+		error.code = 'FORGE_ISSUE_CONTRACT_CONFIG_INVALID';
+		throw error;
+	};
+	if (Array.isArray(loaded?.errors) && loaded.errors.length > 0) {
+		fail(loaded.errors.map(error => error.message || error.code || String(error)).join('; '));
+	}
+	const values = readIssueContractValues(loaded, fail);
+	if (values === null) return null;
+	if (values.enabled !== undefined && typeof values.enabled !== 'boolean') {
+		fail('issues.readiness.contracts.enabled must be a boolean');
+	}
+	if (values.enabled !== true) return { enabled: false, workClasses: [] };
+	if (!Array.isArray(values.workClasses) || values.workClasses.length === 0) {
+		fail('issues.readiness.contracts.workClasses must be a non-empty array');
+	}
+	const allowedClasses = new Set(ISSUE_TYPES);
+	if (values.workClasses.some(value => typeof value !== 'string' || !allowedClasses.has(value))) {
+		fail('issues.readiness.contracts.workClasses contains an unknown work class');
+	}
+	return {
+		enabled: true,
+		workClasses: [...new Set(values.workClasses)],
+	};
+}
+
 async function runIssueOperation(operation, rawArgs, projectRoot, deps = {}) {
   const injectedService = deps.createService;
 
@@ -206,6 +277,7 @@ async function runIssueOperation(operation, rawArgs, projectRoot, deps = {}) {
     backend: createKernelIssueBackend({ projectRoot, deps }),
   }));
 
+  const contractPolicy = resolveIssueContractPolicy(projectRoot, deps);
   const service = createService();
   // Thread a distinct per-agent actor (and, when present, a stable session id) into the
   // mutation context so the Kernel's claim idempotency key is scoped per agent rather than
@@ -223,6 +295,9 @@ async function runIssueOperation(operation, rawArgs, projectRoot, deps = {}) {
   const isClaim = operation === 'claim';
   const worktreeId = isClaim ? resolveWorktreeId(projectRoot, actorEnv, deps) : undefined;
   const leaseTtlMs = isClaim ? resolveLeaseTtlMs(actorEnv) : undefined;
+	const isTrustedAdoption = typeof deps.verifyIssueContractAdoption === 'function'
+		? deps.verifyIssueContractAdoption
+		: undefined;
   try {
     const result = await service.run(operation, rawArgs, {
       projectRoot,
@@ -231,6 +306,8 @@ async function runIssueOperation(operation, rawArgs, projectRoot, deps = {}) {
       ...(sessionId ? { sessionId } : {}),
       ...(worktreeId ? { worktreeId } : {}),
       ...(leaseTtlMs ? { leaseTtlMs } : {}),
+		...(contractPolicy ? { contractPolicy } : {}),
+		...(isTrustedAdoption ? { isTrustedAdoption } : {}),
       // Kernel mutations enqueue a projection-outbox "dirty marker" that `forge export`
       // (the D16 git-JSONL portability projection) drains under target 'jsonl'. The
       // broker's legacy primitive default is still 'beads', so without steering the target
@@ -267,4 +344,5 @@ module.exports = {
   runIssueOperation,
   isHelpInvocation,
   resolveIssueActor,
+	resolveIssueContractPolicy,
 };