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

package/lib/commands/worktree.js

@@ -3,7 +3,12 @@
 const { execFileSync, spawnSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
-const { detectDefaultBranch } = require('../beads-sync-scaffold');
+const { detectDefaultBranch } = require('../git-defaults');
+const {
+  resolveRepoRelativePath,
+  assertNoAncestorSymlinkEscape,
+  assertNoSymlinkEscape,
+} = require('../protected-state-surfaces');
 
 /**
  * Forge Worktree Command
@@ -42,12 +47,13 @@ function detectPackageManager(projectRoot, fsApi) {
 /**
  * Check if a git branch already exists.
  * @param {string} branchName - Branch name to check
+ * @param {string} projectRoot - Repo root to run git in
  * @param {Function} runFile - execFileSync function (for DI)
  * @returns {boolean}
  */
-function branchExists(branchName, runFile) {
+function branchExists(branchName, projectRoot, runFile) {
   try {
-    const output = runFile('git', ['branch', '--list', branchName], { stdio: 'pipe' });
+    const output = runFile('git', ['-C', projectRoot, 'branch', '--list', branchName], { stdio: 'pipe' });
     return output.toString().trim().length > 0;
   } catch (_err) { /* intentional: branch doesn't exist */ // NOSONAR S2486
     return false;
@@ -99,35 +105,118 @@ function isLinkPermissionError(error) {
   return ['EPERM', 'EACCES', 'ENOSYS', 'UV_EPERM'].includes(error && error.code);
 }
 
+// Yarn is probe-less here: a Plug'n'Play install produces no node_modules tree to
+// inspect, and `yarn check` was removed in Berry, so there is nothing to verify.
+const PROBE_LESS_MANAGERS = new Set(['yarn']);
+
 /**
- * Run package install in the new worktree if a package manager is detected, and
- * SURFACE failures (spawn error or non-zero exit) instead of swallowing them.
- * @param {string} worktreePath - Absolute path to the new worktree
- * @param {string} projectRoot - Absolute path to the project root
- * @param {Function} spawnFn - spawnSync-compatible function
+ * 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.
+ * @param {string} worktreePath - Absolute path to the worktree
  * @param {object} fsApi - fs module (for DI)
- * @returns {{ linked: boolean, installed: boolean }}
- * @throws {Error} when the install cannot be spawned or exits non-zero.
+ * @returns {string[]} Declared package names
  */
-function runInstall(worktreePath, projectRoot, spawnFn, fsApi) {
-  const pkgManager = detectPackageManager(projectRoot, fsApi);
-  if (!pkgManager) return { linked: false, installed: false };
+function declaredDependencies(worktreePath, fsApi) {
+  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 [];
+  }
+}
+
+/**
+ * Verify the install actually landed: every declared direct dependency must be a
+ * real package in the worktree's node_modules.
+ *
+ * The package managers cannot answer this. `bun pm ls`, `bun list`, `bun pm why`
+ * and `bun install --dry-run` all read the LOCKFILE and exit 0 while packages are
+ * physically missing; `pnpm ls --depth=0` does the same; `bun -e require.resolve`
+ * is defeated by Bun's auto-install. Only `npm ls --depth=0` exits non-zero, so a
+ * filesystem check is the one probe that holds for every manager.
+ *
+ * @param {string} worktreePath - Absolute path to the worktree
+ * @param {object} fsApi - fs module (for DI)
+ * @returns {boolean} true when nothing is missing
+ */
+function dependenciesPresent(worktreePath, fsApi) {
+  const deps = declaredDependencies(worktreePath, fsApi);
+  return deps.every((name) => fsApi.existsSync(path.join(worktreePath, 'node_modules', name, 'package.json')));
+}
+
+const STDERR_DETAIL_LIMIT = 400;
+
+/**
+ * The install's captured stderr, trimmed and bounded — stdio 'pipe' otherwise
+ * hides why the install failed.
+ * @param {object} result - spawnSync result
+ * @returns {string} A leading-newline detail block, or '' when there is nothing
+ */
+function stderrDetail(result) {
+  const text = result && result.stderr ? String(result.stderr).trim() : '';
+  if (!text) return '';
+  return `\n${text.length > STDERR_DETAIL_LIMIT ? `${text.slice(0, STDERR_DETAIL_LIMIT)}...` : text}`;
+}
 
+/**
+ * Spawn one install, surfacing spawn errors, kills, and non-zero exits.
+ * @param {string} pkgManager - Detected package manager command
+ * @param {string[]} args - Install args (e.g. ['install'] or ['install', '--force'])
+ * @param {string} worktreePath - cwd for the install
+ * @param {Function} spawnFn - spawnSync-compatible function
+ * @throws {Error} when the install cannot be spawned, is killed, or exits non-zero.
+ */
+function spawnInstall(pkgManager, args, worktreePath, spawnFn) {
   // shell:true on Windows: npm/pnpm/yarn are .cmd shims that cannot be spawned
   // directly (ENOENT / EINVAL). pkgManager comes from lockfile detection (fixed
   // set) and args are hardcoded, so no user input reaches the shell.
-  const result = spawnFn(pkgManager, ['install'], {
+  const result = spawnFn(pkgManager, args, {
     cwd: worktreePath,
     stdio: 'pipe',
     shell: process.platform === 'win32',
   });
+  const label = `${pkgManager} ${args.join(' ')}`;
   if (result && result.error) {
-    throw new Error(`Dependency install failed: could not run '${pkgManager} install' in ${worktreePath}: ${result.error.message}`);
+    throw new Error(`Dependency install failed: could not run '${label}' in ${worktreePath}: ${result.error.message}${stderrDetail(result)}`);
+  }
+  // A killed install (OOM, SIGTERM, CI cancel) reports status null with a signal
+  // set — never a non-zero code — so it must be checked on its own.
+  if (result && result.signal) {
+    throw new Error(`Dependency install failed: '${label}' was killed by ${result.signal} in ${worktreePath}${stderrDetail(result)}`);
   }
   if (result && typeof result.status === 'number' && result.status !== 0) {
-    throw new Error(`Dependency install failed: '${pkgManager} install' exited with code ${result.status} in ${worktreePath}`);
+    throw new Error(`Dependency install failed: '${label}' exited with code ${result.status} in ${worktreePath}${stderrDetail(result)}`);
   }
-  return { linked: false, installed: true };
+}
+
+/**
+ * Run package install in the new worktree if a package manager is detected, then
+ * VERIFY it. A stale shared store makes a plain install report "no changes" while
+ * leaving packages and binaries missing, so the exit code alone is not evidence —
+ * on a failed probe, reinstall once with --force and re-probe.
+ * @param {string} worktreePath - Absolute path to the new worktree
+ * @param {string} projectRoot - Absolute path to the project root
+ * @param {Function} spawnFn - spawnSync-compatible function
+ * @param {object} fsApi - fs module (for DI)
+ * @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);
+  if (!pkgManager) return { linked: false, installed: false, healed: false };
+
+  spawnInstall(pkgManager, ['install'], worktreePath, spawnFn);
+
+  if (PROBE_LESS_MANAGERS.has(pkgManager) || dependenciesPresent(worktreePath, fsApi)) {
+    return { linked: false, installed: true, healed: false };
+  }
+
+  spawnInstall(pkgManager, ['install', '--force'], worktreePath, spawnFn);
+  if (!dependenciesPresent(worktreePath, fsApi)) {
+    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 };
 }
 
 /**
@@ -142,7 +231,7 @@ function runInstall(worktreePath, projectRoot, spawnFn, fsApi) {
  * @param {Function} deps.spawnFn - spawnSync-compatible function
  * @param {object} deps.fsApi - fs module (for DI)
  * @param {string} deps.platform - process.platform value
- * @returns {{ linked: boolean, installed: boolean }}
+ * @returns {{ linked: boolean, installed: boolean, healed: boolean }}
  * @throws {Error} when linking fails for a non-privilege reason or install fails.
  */
 function setupWorktreeDeps(worktreePath, projectRoot, { spawnFn, fsApi, platform }) {
@@ -150,14 +239,14 @@ function setupWorktreeDeps(worktreePath, projectRoot, { spawnFn, fsApi, platform
   const destModules = path.join(worktreePath, 'node_modules');
 
   // Already populated (e.g. git checkout carried it) — nothing to do.
-  if (fsApi.existsSync(destModules)) return { linked: false, installed: false };
+  if (fsApi.existsSync(destModules)) return { linked: false, installed: false, healed: false };
 
   // 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 };
+      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.
@@ -168,6 +257,72 @@ function setupWorktreeDeps(worktreePath, projectRoot, { spawnFn, fsApi, platform
   return runInstall(worktreePath, projectRoot, spawnFn, fsApi);
 }
 
+function readExistingWorktreeLinkage(driver, worktreePath, reuse) {
+  if (!reuse || !driver || typeof driver.getWorktreeLinkage !== 'function') return null;
+  return driver.getWorktreeLinkage({ path: worktreePath }) || null;
+}
+
+function detectLinkageConflict({ projectRoot, existing, issueId, workFolder, reuse }) {
+  if (!reuse || !existing) return null;
+  const existingIssue = existing.issue_id || null;
+  const existingFolder = existing.work_folder || null;
+  const folderChanged = workFolder && existingFolder
+    && path.resolve(projectRoot, workFolder) !== path.resolve(projectRoot, existingFolder);
+  if (!((issueId && existingIssue && issueId !== existingIssue) || folderChanged)) return null;
+  return {
+    issueId: issueId || existingIssue,
+    workFolder: workFolder || existingFolder,
+    reason: 'worktree linkage mismatch; existing issue/work-folder was not changed',
+    conflict: true,
+  };
+}
+
+function isAbsoluteWorkFolder(workFolder) {
+  return path.isAbsolute(workFolder) || path.posix.isAbsolute(workFolder) || path.win32.isAbsolute(workFolder);
+}
+
+function markerPathConflict(reason) {
+  return { conflict: true, reason: `worktree linkage marker path rejected: ${reason}` };
+}
+
+function validateMarkerTarget(projectRoot, workFolder, fsApi) {
+  if (!workFolder) return null;
+  if (isAbsoluteWorkFolder(workFolder)) return markerPathConflict('work-folder must be repo-relative');
+
+  const resolved = resolveRepoRelativePath(projectRoot, workFolder);
+  if (!resolved.insideRoot) return markerPathConflict('work-folder escapes project root');
+  const ancestorEscape = assertNoAncestorSymlinkEscape(resolved.root, resolved.target);
+  if (ancestorEscape) return markerPathConflict(ancestorEscape.reason);
+
+  const statSync = fsApi.statSync || fs.statSync;
+  const folderStat = fsApi.existsSync(resolved.target) ? statSync.call(fsApi, resolved.target) : null;
+  if (folderStat && !folderStat.isDirectory()) return markerPathConflict('work-folder is not a directory');
+  const markerPath = path.join(resolved.target, '.forge-issue');
+  const markerEscape = assertNoSymlinkEscape(resolved.root, markerPath);
+  if (markerEscape) {
+    return markerPathConflict(markerEscape.reason);
+  }
+  return { folderAbs: resolved.target, markerPath, folderExists: Boolean(folderStat) };
+}
+
+function reconcileIssueMarker({ target, linkedIssue, linkedFolder, fsApi }) {
+  if (!target || !linkedIssue || !target.folderExists) return null;
+  let markerIssue = null;
+  try {
+    if (fsApi.existsSync(target.markerPath)) markerIssue = fsApi.readFileSync(target.markerPath, 'utf8').trim() || null;
+  } catch { /* unreadable marker — let the write below repair it */ }
+  if (markerIssue && markerIssue !== linkedIssue) {
+    return {
+      issueId: linkedIssue,
+      workFolder: linkedFolder,
+      reason: 'worktree linkage mismatch; existing issue marker was not changed',
+      conflict: true,
+    };
+  }
+  fsApi.writeFileSync(target.markerPath, `${linkedIssue}\n`, 'utf8');
+  return null;
+}
+
 /**
  * Best-effort: record the issue → worktree → work-folder linkage in the Kernel so
  * `forge worktree list` and orientation READ it instead of guessing the work-folder by
@@ -185,30 +340,44 @@ function setupWorktreeDeps(worktreePath, projectRoot, { spawnFn, fsApi, platform
  * @param {string|null} params.issueId
  * @param {string|null} params.workFolder - Repo-relative work-folder path.
  * @param {object} params.opts - DI options (may inject `_kernelDriver`, `_exec`, `_fs`).
+ * @param {boolean} [params.reuse] - Validate existing linkage before reconciling.
  * @returns {Promise<{registered: boolean, issueId: string|null, workFolder: string|null, reason?: string}>}
  */
-async function registerWorktreeLinkage({ projectRoot, worktreePath, branch, issueId, workFolder, opts }) {
+async function registerWorktreeLinkage({ projectRoot, worktreePath, branch, issueId, workFolder, opts, reuse = false }) {
   const runFile = opts._exec || execFileSync;
   const fsApi = opts._fs || fs;
   try {
-    // Drop the folder → issue marker first — deterministic even if the DB write fails.
-    if (workFolder && issueId) {
-      const folderAbs = path.resolve(projectRoot, workFolder);
-      fsApi.mkdirSync(folderAbs, { recursive: true });
-      fsApi.writeFileSync(path.join(folderAbs, '.forge-issue'), `${issueId}\n`, 'utf8');
-    }
-
     let driver = opts._kernelDriver;
     if (!driver) {
       // No reachable git repo → no shared Kernel; skip quietly (orientation still works
       // off the folder heuristic). Avoids spawning `git` in a non-repo directory.
-      if (!fsApi.existsSync(path.join(projectRoot, '.git'))) {
-        return { registered: false, issueId: issueId || null, workFolder: workFolder || null, reason: 'no git repository' };
+      if (fsApi.existsSync(path.join(projectRoot, '.git'))) {
+        // Lazy require: keep the worktree command light and avoid paying kernel setup
+        // when linkage is not needed. Migrated deps guarantee the 007 columns exist.
+        const { buildMigratedKernelIssueDeps } = require('../kernel/cli-broker-factory');
+        driver = (await buildMigratedKernelIssueDeps({ projectRoot })).kernelDriver;
       }
-      // Lazy require: keep the worktree command light and avoid paying kernel setup
-      // when linkage is not needed. Migrated deps guarantee the 007 columns exist.
-      const { buildMigratedKernelIssueDeps } = require('../kernel/cli-broker-factory');
-      driver = (await buildMigratedKernelIssueDeps({ projectRoot })).kernelDriver;
+    }
+
+    const existing = readExistingWorktreeLinkage(driver, worktreePath, reuse);
+    const linkageConflict = detectLinkageConflict({ projectRoot, existing, issueId, workFolder, reuse });
+    if (linkageConflict) return { registered: false, ...linkageConflict };
+
+    const existingIssue = existing?.issue_id || null;
+    const existingFolder = existing?.work_folder || null;
+    const linkedIssue = issueId || (reuse ? existingIssue : null);
+    const linkedFolder = workFolder || (reuse ? existingFolder : null);
+    const markerTarget = validateMarkerTarget(projectRoot, linkedFolder, fsApi);
+    if (markerTarget?.conflict) {
+      return { registered: false, issueId: linkedIssue || null, workFolder: linkedFolder || null, ...markerTarget };
+    }
+    const markerConflict = reconcileIssueMarker({ target: markerTarget, linkedIssue, linkedFolder, fsApi });
+    if (markerConflict) {
+      return { registered: false, ...markerConflict };
+    }
+
+    if (!driver) {
+      return { registered: false, issueId: linkedIssue || null, workFolder: linkedFolder || null, reason: 'no git repository' };
     }
 
     const { resolveGitCommonDir } = require('../kernel/broker');
@@ -219,13 +388,13 @@ async function registerWorktreeLinkage({ projectRoot, worktreePath, branch, issu
       path: worktreePath,
       branch,
       actor: process.env.FORGE_ACTOR || null,
-      issue_id: issueId || null,
-      work_folder: workFolder || null,
+      issue_id: linkedIssue || null,
+      work_folder: linkedFolder || null,
       registered_at: new Date().toISOString(),
       state: 'active',
     });
 
-    return { registered: true, issueId: issueId || null, workFolder: workFolder || null };
+    return { registered: true, issueId: linkedIssue || null, workFolder: linkedFolder || null };
   } catch (error) {
     // Non-fatal: keep the worktree usable. Only warn when the caller explicitly asked
     // for linkage (--issue/--work-folder); a plain `worktree create` stays quiet.
@@ -331,7 +500,10 @@ async function handleCreate(slug, flags, projectRoot, opts) {
       // A detached worktree reports the literal "HEAD" — don't persist that; keep branchName.
       if (head && head !== 'HEAD') existingBranch = head;
     } catch (_error) { /* not a resolvable worktree HEAD — fall back to branchName */ }
-    const linkage = await registerWorktreeLinkage({ projectRoot, worktreePath, branch: existingBranch, issueId, workFolder, opts });
+    const linkage = await registerWorktreeLinkage({ projectRoot, worktreePath, branch: existingBranch, issueId, workFolder, opts, reuse: true });
+    if (linkage.conflict) {
+      return { success: false, reused: true, error: linkage.reason, worktreePath, linkage };
+    }
     const backing = await autoFileBackingIssue({ projectRoot, worktreePath, branch: existingBranch, issueId, opts });
     return {
       success: true,
@@ -350,13 +522,13 @@ async function handleCreate(slug, flags, projectRoot, opts) {
   // the repo's DEFAULT branch — NOT the checkout's current HEAD — so the worktree
   // never silently inherits unrelated WIP commits (B2). An existing branch is
   // checked out as-is (no base applies).
-  const hasBranch = branchExists(branchName, runFile);
+  const hasBranch = branchExists(branchName, projectRoot, runFile);
   let base = null;
   if (hasBranch) {
-    runFile('git', ['worktree', 'add', worktreePath, branchName], { stdio: 'pipe' });
+    runFile('git', ['-C', projectRoot, 'worktree', 'add', worktreePath, branchName], { stdio: 'pipe' });
   } else {
     base = explicitBase || resolveDefaultBase(projectRoot, runFile);
-    runFile('git', ['worktree', 'add', worktreePath, '-b', branchName, base], { stdio: 'pipe' });
+    runFile('git', ['-C', projectRoot, 'worktree', 'add', worktreePath, '-b', branchName, base], { stdio: 'pipe' });
   }
 
   // Step 3: Populate node_modules (link to the shared install, else install).
@@ -375,11 +547,16 @@ async function handleCreate(slug, flags, projectRoot, opts) {
   }
 
   const linkage = await registerWorktreeLinkage({ projectRoot, worktreePath, branch: branchName, issueId, workFolder, opts });
+  if (linkage.conflict) {
+    return { success: false, error: linkage.reason, worktreePath, branch: branchName, linkage };
+  }
   const backing = await autoFileBackingIssue({ projectRoot, worktreePath, branch: branchName, issueId, opts });
 
   // Report the base so the fork point is never silent. `base` is null when an
   // existing branch was checked out (no fork happened).
   const baseNote = base ? `based on ${base}` : `existing branch ${branchName}`;
+  // Never let a heal be silent — a stale store is worth knowing about.
+  const healNote = deps.healed ? ' Healed dependencies (store was stale): reinstalled with --force.' : '';
   return {
     success: true,
     worktreePath,
@@ -387,9 +564,10 @@ async function handleCreate(slug, flags, projectRoot, opts) {
     base,
     depsLinked: deps.linked,
     depsInstalled: deps.installed,
+    depsHealed: deps.healed,
     linkage,
     backing,
-    output: `Created worktree ${worktreePath} on ${branchName} (${baseNote}).`,
+    output: `Created worktree ${worktreePath} on ${branchName} (${baseNote}).${healNote}`,
   };
 }
 
@@ -406,12 +584,38 @@ async function handleList(projectRoot, opts) {
       const { buildMigratedKernelIssueDeps } = require('../kernel/cli-broker-factory');
       driver = (await buildMigratedKernelIssueDeps({ projectRoot })).kernelDriver;
     }
-    return { success: true, worktrees: driver.listWorktrees({}) };
+    // `forge worktree remove` / `forge clean` delete the checkout but do not yet
+    // reconcile the kernel_worktrees registry (issue ceeef92f), so the raw registry
+    // can still list already-removed paths. Filter to worktrees that still exist on
+    // disk so `forge worktree list` never surfaces stale entries agents could act on.
+    const existsSync = (opts._fs && opts._fs.existsSync) || require('node:fs').existsSync;
+    const worktrees = driver.listWorktrees({}).filter((w) => w && w.path && existsSync(w.path));
+    return { success: true, worktrees, output: renderWorktreeList(worktrees) };
   } catch (error) {
     return { success: false, error: error.message, worktrees: [] };
   }
 }
 
+/**
+ * Render the worktree registry as human-readable text for the CLI. The dispatcher
+ * prints only `result.output`, so without this `forge worktree list` is silent.
+ * @param {Array<object>} worktrees - Rows from driver.listWorktrees()
+ * @returns {string} One line per worktree (path, branch, linked issue, state).
+ */
+function renderWorktreeList(worktrees) {
+  if (!Array.isArray(worktrees) || worktrees.length === 0) {
+    return 'No worktrees registered.';
+  }
+  const lines = worktrees.map((w) => {
+    const parts = [w.path || '(unknown path)'];
+    if (w.branch) parts.push(`branch: ${w.branch}`);
+    if (w.issue_id) parts.push(`issue: ${w.issue_id}`);
+    if (w.state) parts.push(w.state);
+    return `  ${parts.join('  |  ')}`;
+  });
+  return `Registered worktrees (${worktrees.length}):\n${lines.join('\n')}`;
+}
+
 /**
  * Handle the "remove" subcommand.
  * @param {string} slug - Worktree slug

package/lib/core/runtime-graph.js

@@ -161,6 +161,55 @@ const PLAN_SUBSKILL_DEFINITIONS = [
 
 const PLAN_SUBSKILL_IDS = new Set(PLAN_SUBSKILL_DEFINITIONS.map(definition => definition.id));
 
+// The `smith` orchestrator composes the stage skills end-to-end. Its sub-skills
+// are the stage skill NAMES (each a real `skills/<name>/` dir), unlike plan's
+// fine-grained internal planning phases. Both resolve through the ONE generic
+// registry below (keyed by owning skill), so composition is no longer hardcoded
+// to plan. See docs/work kernel-native-skills composition epic (a0776e61) +
+// smith-orchestrator (7da81cbd).
+const SMITH_SUBSKILL_DEFINITIONS = ['plan', 'dev', 'validate', 'ship', 'review', 'verify']
+  .map(stage => ({ id: stage, label: `${stage} stage`, owner: 'smith' }));
+
+// Skills that `plan` COMPOSES at the whole-skill level (its SKILL.md `subskills:`
+// frontmatter), distinct from the fine-grained plan.* planning micro-phases in
+// PLAN_SUBSKILL_DEFINITIONS. A composed whole-skill is an advertised sub-skill
+// that must both VALIDATE and RESOLVE, but it is NOT a partialInvocation
+// micro-phase (it maps to no runtime-graph action), so it lives OUTSIDE
+// PLAN_SUBSKILL_IDS (which governs planning.template.only/skip).
+const PLAN_COMPOSED_SUBSKILLS = ['research'];
+const PLAN_COMPOSED_SUBSKILL_DEFINITIONS = PLAN_COMPOSED_SUBSKILLS.map(id => ({
+  id,
+  label: `${id.charAt(0).toUpperCase()}${id.slice(1)} (composed skill)`,
+  kind: 'composed-skill',
+  owner: 'plan',
+}));
+
+// Generic per-skill sub-skill registry, keyed by owning skill id. Generalizes
+// plan's previously hardcoded PLAN_SUBSKILL_DEFINITIONS / validatePlanSubSkillList
+// so any composing skill (plan, smith, ...) declares its sub-skill set through a
+// single mechanism. This registry is the SINGLE source for BOTH validation (ids)
+// and resolution (definitions), so getSubSkillDefinitions and validateSubSkillList
+// can never disagree. plan's set = its planning micro-phases + composed whole-skills.
+const SUBSKILL_REGISTRY = {
+  plan: [...PLAN_SUBSKILL_DEFINITIONS, ...PLAN_COMPOSED_SUBSKILL_DEFINITIONS],
+  smith: SMITH_SUBSKILL_DEFINITIONS,
+};
+
+// Validation id sets DERIVED from the registry definitions — guarantees
+// validate-vs-resolve parity for every owner (a subskill that validates also
+// resolves, and vice versa).
+const SUBSKILL_IDS_BY_OWNER = Object.fromEntries(
+  Object.entries(SUBSKILL_REGISTRY).map(([owner, defs]) => [owner, new Set(defs.map(d => d.id))])
+);
+
+function getSubSkillDefinitions(owner) {
+  return SUBSKILL_REGISTRY[owner] ? [...SUBSKILL_REGISTRY[owner]] : [];
+}
+
+function getSubSkillIds(owner) {
+  return new Set(SUBSKILL_IDS_BY_OWNER[owner] || []);
+}
+
 function planningSubSkillFromDefinition(definition) {
   return PlanningSubSkill({
     id: definition.id,
@@ -485,7 +534,7 @@ const RESOLVED_RUNTIME_GRAPH = {
       id: 'adapter.issue',
       kind: 'issue',
       label: 'Issue tracking adapter',
-      config: { primary: 'beads', mirrors: ['github'] },
+      config: { primary: 'kernel', mirrors: ['github'] },
     }),
     Adapter({
       id: 'adapter.harness',
@@ -777,31 +826,51 @@ function assertStringList(value, errors, code, message) {
   return valid;
 }
 
-function validatePlanSubSkillList(value, errors, path) {
-  if (!assertStringList(
-    value,
-    errors,
-    'INVALID_PLAN_SUBSKILL_LIST',
-    `${path} must be a list of planning sub-skill IDs.`
-  )) {
+function subSkillCodesForOwner(owner) {
+  return owner === 'plan'
+    ? { listCode: 'INVALID_PLAN_SUBSKILL_LIST', unknownCode: 'UNKNOWN_PLAN_SUBSKILL', noun: 'planning sub-skill' }
+    : { listCode: 'INVALID_SUBSKILL_LIST', unknownCode: 'UNKNOWN_SUBSKILL', noun: `${owner} sub-skill` };
+}
+
+// Core list validator against an explicit known-id Set. The two callers below
+// deliberately pass DIFFERENT id sets so the two contracts never leak into each
+// other (see validatePlanSubSkillList).
+function validateAgainstKnownIds(knownIds, codes, value, errors, path) {
+  const { listCode, unknownCode, noun } = codes;
+  if (!assertStringList(value, errors, listCode, `${path} must be a list of ${noun} IDs.`)) {
     return undefined;
   }
 
   const normalized = value.map(item => item.trim());
   let hasUnknown = false;
   for (const id of normalized) {
-    if (!PLAN_SUBSKILL_IDS.has(id)) {
+    if (!knownIds.has(id)) {
       hasUnknown = true;
       errors.push({
-        code: 'UNKNOWN_PLAN_SUBSKILL',
-        message: `Unknown planning sub-skill '${id}' in ${CONFIG_SOURCE}.`,
+        code: unknownCode,
+        message: `Unknown ${noun} '${id}' in ${CONFIG_SOURCE}.`,
       });
     }
   }
-  if (hasUnknown) {
-    return undefined;
-  }
-  return normalized;
+  return hasUnknown ? undefined : normalized;
+}
+
+// Generic COMPOSITION validator, keyed by owning skill — validates a skill's
+// ADVERTISED (SKILL.md frontmatter) subskills. For `plan` the known-id set is the
+// composition union (plan.* micro-phases + composed whole-skills like research).
+function validateSubSkillList(owner, value, errors, path) {
+  const knownIds = SUBSKILL_IDS_BY_OWNER[owner] || new Set();
+  return validateAgainstKnownIds(knownIds, subSkillCodesForOwner(owner), value, errors, path);
+}
+
+// partialInvocation validator (.forge/config.yaml planning.template.only/skip).
+// SEPARATE contract from composition: it MUST accept ONLY the fine-grained plan.*
+// MICRO-PHASE ids (PLAN_SUBSKILL_IDS), never composed whole-skill ids like
+// `research` — a composed skill maps to no runtime-graph action, so `only:
+// [research]` would be silent dead config. Validates against PLAN_SUBSKILL_IDS,
+// NOT the composition union, so it fails closed on composed ids.
+function validatePlanSubSkillList(value, errors, path) {
+  return validateAgainstKnownIds(PLAN_SUBSKILL_IDS, subSkillCodesForOwner('plan'), value, errors, path);
 }
 
 function applyPlanningMode(template, nextTemplate, errors) {
@@ -968,6 +1037,11 @@ module.exports = {
   PlanningSubSkill,
   Role,
   ROLE_IDS,
+  SUBSKILL_REGISTRY,
+  getSubSkillDefinitions,
+  getSubSkillIds,
+  validateSubSkillList,
+  validatePlanSubSkillList,
   loadRuntimeGraphConfig,
   lintRuntimeGraphConfig,
   resolveRuntimeGraph,