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

package/lib/status/identity.js

@@ -0,0 +1,46 @@
+'use strict';
+
+const { secureExecFileSync } = require('../shell-utils.js');
+
+// Developer identity for the status read model. Extracted from the retired
+// lib/status/beads-snapshot.js: the identity lookup is backend-agnostic (it reads
+// git config, never an issue store), so it outlived the Beads reader it shipped in.
+// Kept in its own module so lib/status/snapshot.js stays read-model-only.
+
+/**
+ * Read a single git config value, or '' when git is unavailable or the key is unset.
+ * Never throws — status must render even in a non-git directory.
+ *
+ * @param {string} projectRoot
+ * @param {string} key — git config key (e.g. 'user.email')
+ * @returns {string}
+ */
+function getGitConfig(projectRoot, key) {
+	try {
+		return secureExecFileSync('git', ['config', key], {
+			encoding: 'utf8',
+			cwd: projectRoot,
+			stdio: ['pipe', 'pipe', 'pipe'],
+		}).trim();
+	} catch (_error) {
+		return '';
+	}
+}
+
+/**
+ * The current developer's git identity, used to match claims to "my" work.
+ *
+ * @param {string} projectRoot
+ * @returns {{ email: string, name: string }}
+ */
+function getDeveloperIdentity(projectRoot) {
+	return {
+		email: getGitConfig(projectRoot, 'user.email'),
+		name: getGitConfig(projectRoot, 'user.name'),
+	};
+}
+
+module.exports = {
+	getDeveloperIdentity,
+	getGitConfig,
+};

package/lib/status/presenter.js

@@ -173,43 +173,8 @@ function buildPersonalStatusJson({ context, snapshot, workflowResult = null }) {
 	};
 }
 
-function formatBoard({ context, snapshot }) {
-	return [
-		'',
-		'Team Runtime Board',
-		`Source: local Beads runtime state`,
-		`Branch: ${context.branch}`,
-		`Working tree: ${context.workingTree.summary}`,
-		'',
-		...buildSection('Active', (snapshot.active || []).map(issue => formatIssue(issue, { includeStatus: true })), { limit: DEFAULT_SECTION_LIMIT }),
-		...buildSection('Ready', (snapshot.ready || []).map(issue => formatIssue(issue)), { limit: DEFAULT_SECTION_LIMIT }),
-		...buildSection('Blocked', (snapshot.blocked || []).map(issue => formatIssue(issue, { includeStatus: true })), { limit: DEFAULT_SECTION_LIMIT }),
-		...buildSection('Stale', (snapshot.stale || []).map(issue => formatIssue(issue, { includeStatus: true })), { limit: DEFAULT_SECTION_LIMIT }),
-		...buildSection('Parked', (snapshot.parked || []).map(issue => formatIssue(issue, { includeStatus: true })), { limit: DEFAULT_SECTION_LIMIT }),
-		...buildSection('Recent Completions', (snapshot.recentCompleted || []).map(issue => formatIssue(issue)), { limit: DEFAULT_SECTION_LIMIT }),
-		...buildSection('Limits', snapshot.limits || []),
-	].join('\n');
-}
-
-function buildBoardJson({ context, snapshot }) {
-	return {
-		context,
-		board: {
-			active: (snapshot.active || []).map(toIssueSummary),
-			ready: (snapshot.ready || []).map(toIssueSummary),
-			blocked: (snapshot.blocked || []).map(toIssueSummary),
-			stale: (snapshot.stale || []).map(toIssueSummary),
-			parked: (snapshot.parked || []).map(toIssueSummary),
-			recentCompleted: (snapshot.recentCompleted || []).map(toIssueSummary),
-		},
-		limits: snapshot.limits || [],
-	};
-}
-
 module.exports = {
-	buildBoardJson,
 	buildPersonalStatusJson,
-	formatBoard,
 	formatRunNextLines,
 	formatZeroArgStatus,
 	toIssueSummary,

package/lib/status/snapshot.js

@@ -2,15 +2,14 @@
 
 const { resolveIssueBackend } = require('../issue-backend.js');
 const { runIssueOperation: defaultRunIssueOperation } = require('../forge-issues.js');
-const { readBeadsSnapshot, getDeveloperIdentity } = require('./beads-snapshot.js');
+const { getDeveloperIdentity } = require('./identity.js');
 
 // Kernel status vocabulary (taxonomy-validator): 'open', 'in_progress', 'review',
 // the parked 'backlog', and the terminal 'done' / 'cancelled'. `ready` / `blocked`
 // are DERIVED read-model facts, never stored. An issue is treated as active here when
 // it is OPEN and carries a live claim (claimed_by); parked (`backlog`) work is its own
 // bucket so it stays visible instead of vanishing between ready and done. These buckets
-// mirror the shape readBeadsSnapshot produces so lib/status/presenter.js consumes
-// either backend's snapshot identically.
+// are the contract lib/status/presenter.js renders against.
 const KERNEL_LIMITS = Object.freeze([
 	'Reads Forge Kernel issue authority (ready/blocked/stale/active).',
 	'Does not read GitHub review, CI, project, or sync freshness state.',
@@ -102,7 +101,7 @@ function emptyKernelSnapshot(developer) {
  * @param {object} [options]
  * @param {function} [options.runIssueOperation] — injectable kernel read (tests)
  * @param {object} [options.env]
- * @returns {Promise<object>} snapshot shaped like readBeadsSnapshot's output
+ * @returns {Promise<object>} snapshot in the presenter's bucket contract
  */
 async function readKernelSnapshot(projectRoot, options = {}) {
 	const runIssueOperation = options.runIssueOperation || defaultRunIssueOperation;
@@ -153,29 +152,25 @@ async function readKernelSnapshot(projectRoot, options = {}) {
 }
 
 /**
- * Read the personal/board status snapshot from the active issue backend. Reads the
- * Kernel by default (the flagship `forge status` view); reads Beads only when Beads is
- * explicitly selected (--issue-backend beads / FORGE_ISSUE_BACKEND=beads /
- * issueBackend: beads in .forge/config.yaml). Resolution reuses lib/issue-backend.js
- * so the snapshot never drifts from the issue commands' backend authority.
+ * Read the personal/board status snapshot from the Kernel — the only issue backend.
+ *
+ * A repo that still carries the retired `issueBackend: beads` signal alongside an
+ * unmigrated `.beads/*.jsonl` store now renders the (empty) kernel board rather than
+ * the legacy Beads one; `forge upgrade`'s advisory is what points those users at
+ * `forge migrate --from beads`.
  *
  * @param {string} projectRoot
- * @param {object} [options] — forwarded to the backend reader; `issueBackend` selects
- *   an explicit backend, `env` overrides process.env, `backend` short-circuits resolution.
+ * @param {object} [options] — forwarded to the backend reader; `env` overrides
+ *   process.env, `backend` short-circuits resolution entirely.
  * @returns {Promise<object>} snapshot for lib/status/presenter.js
  */
 async function readStatusSnapshot(projectRoot, options = {}) {
 	const backend = options.backend || resolveIssueBackend({
-		deps: options.issueBackend ? { issueBackend: options.issueBackend } : {},
 		env: options.env || process.env,
 		projectRoot,
 		warn: () => {},
 	});
 
-	if (backend === 'beads') {
-		return readBeadsSnapshot(projectRoot, options);
-	}
-
 	return readKernelSnapshot(projectRoot, { ...options, backend });
 }
 

package/lib/upgrade-safety.js

@@ -6,6 +6,8 @@ const path = require('node:path');
 const { lintRuntimeGraphConfig } = require('./core/runtime-graph');
 const { resolvePatchIntentRecords } = require('./patch-intent');
 const { verifyForgeLock, readForgeLock } = require('./forge-lock');
+const { readConfigBackend, resolveIssueBackend } = require('./issue-backend');
+const { detectBeadsJsonlSource } = require('./beads-detect');
 
 function checkStatus(ok) {
   return ok ? 'pass' : 'fail';
@@ -56,7 +58,34 @@ function buildSelfHealCandidates(projectRoot) {
   return candidates;
 }
 
-function buildUpgradeDryRunReport(projectRoot = process.cwd()) {
+function safeConfigBackend(projectRoot) {
+  try {
+    return readConfigBackend(projectRoot);
+  } catch {
+    return null;
+  }
+}
+
+// Detect the 0.0.10 -> current breaking boundary that hides a returning user's
+// issues (kernel issue a5399f3d): a `.beads/*.jsonl` store still present now that
+// the Kernel is the only backend. There is no longer any way to opt back into
+// Beads, so a leftover `issueBackend: beads` in `.forge/config.yaml` (or
+// FORGE_ISSUE_BACKEND) can no longer suppress this advisory — resolveIssueBackend
+// answers 'kernel' regardless, which is precisely when the user needs to migrate.
+// `configBackend` is still reported so the surface can name the stale setting.
+// Uses the single shared detector so the two surfaces cannot drift.
+function buildBeadsMigrationSummary(projectRoot, env = process.env) {
+  const jsonlPresent = detectBeadsJsonlSource(projectRoot) !== null;
+  const configBackend = safeConfigBackend(projectRoot);
+  const backend = resolveIssueBackend({ env, projectRoot, warn: () => {} });
+  return {
+    jsonlPresent,
+    configBackend,
+    needsMigration: jsonlPresent && backend === 'kernel',
+  };
+}
+
+function buildUpgradeDryRunReport(projectRoot = process.cwd(), env = process.env) {
   const root = path.resolve(projectRoot);
   const runtime = lintRuntimeGraphConfig({ projectRoot: root });
   const patchIntent = buildPatchIntentSummary(root);
@@ -66,8 +95,12 @@ function buildUpgradeDryRunReport(projectRoot = process.cwd()) {
   const failedLockEntries = lockReport.results.filter(result => result.status === 'fail');
   const untrustedOptIns = countUntrustedOptIns(lock);
   const lockTrustOk = lockReport.ok && untrustedOptIns === 0;
+  const beadsMigration = buildBeadsMigrationSummary(root, env);
 
   return {
+    // A pending beads -> kernel migration is a guided ADVISORY, not an integrity
+    // failure — it never flips `ok` (scripts keying on it stay stable); it surfaces
+    // as its own prominent "action required" section in the rendered report.
     ok: runtime.ok && patchIntent.ok && lockTrustOk,
     projectRoot: root,
     runtime,
@@ -77,6 +110,7 @@ function buildUpgradeDryRunReport(projectRoot = process.cwd()) {
     lockTrustOk,
     selfHealCandidates,
     failedLockEntries,
+    beadsMigration,
   };
 }
 
@@ -139,6 +173,21 @@ function appendSelfHealResult(lines, selfHealResult) {
   }
 }
 
+function appendBeadsMigration(lines, beadsMigration) {
+  if (!beadsMigration || !beadsMigration.needsMigration) {
+    return;
+  }
+  lines.push(
+    '',
+    'Breaking change since 0.0.10 — action required',
+    'Detected a Beads issue store (.beads/*.jsonl). The Kernel is now the only',
+    'issue backend, so these issues will NOT appear until migrated (your data is safe',
+    'on disk in the meantime). To migrate:',
+    '  forge migrate --from beads   # import your Beads issues into the Kernel',
+    '  forge setup                  # (re)wire hooks + provision the Kernel store',
+  );
+}
+
 function renderUpgradeDryRunReport(report, selfHealResult = null) {
   const lines = [
     'Forge upgrade dry-run',
@@ -149,6 +198,7 @@ function renderUpgradeDryRunReport(report, selfHealResult = null) {
     ...readinessLines(report),
   ];
 
+  appendBeadsMigration(lines, report.beadsMigration);
   appendPlannedSelfHeal(lines, report.selfHealCandidates);
   appendSelfHealResult(lines, selfHealResult);
 
@@ -194,6 +244,7 @@ function applySelfHeal(projectRoot, report) {
 module.exports = {
   applySelfHeal,
   buildUpgradeDryRunReport,
+  buildBeadsMigrationSummary,
   buildSelfHealCandidates,
   renderUpgradeDryRunReport,
 };

package/lib/using-forge.js

@@ -0,0 +1,315 @@
+'use strict';
+
+/**
+ * using-forge dispatch: shared helpers for Forge's reasoning-driven skill auto-trigger.
+ *
+ * Two consumers share this module:
+ *  - the SessionStart context hook (lib/commands/hooks.js), which injects the using-forge
+ *    dispatch bootstrap text so an agent auto-triggers skills from turn one (the Superpowers
+ *    mechanism), and
+ *  - the "forge skill for" router (lib/commands/skill.js), the DETERMINISTIC intent-to-skill
+ *    fallback for harnesses without a SessionStart hook.
+ *
+ * Skills are read from the Forge PACKAGE's canonical skills/ dir (resolved via getPackageRoot:
+ * the on-disk npm/dev package, or the compiled binary's extracted embedded assets) -- NEVER from
+ * the consumer's projectRoot, which after `forge setup` has only generated mirrors and no root
+ * skills/. Everything here is deterministic and NEVER throws -- an unresolved asset root or a
+ * missing skills dir degrades to empty results.
+ *
+ * @module using-forge
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { getPackageRoot } = require('./package-root');
+
+const DISPATCH_SKILL = 'using-forge';
+
+/** Strip a leading UTF-8 BOM (U+FEFF) without embedding the char literally in source. */
+function stripBom(value) {
+  const s = String(value);
+  return s.charCodeAt(0) === 0xFEFF ? s.slice(1) : s;
+}
+
+/**
+ * Resolve the root that carries the canonical `skills/` dir. Default: the Forge PACKAGE root
+ * (getPackageRoot) so the dispatch skill/catalog work in a consumer project and a compiled
+ * binary, not only in the Forge source checkout. An explicit `override` is honored where a
+ * caller intentionally wants a specific root (tests / repo-local use). Never throws -> null.
+ * @param {string} [override]
+ * @returns {string|null}
+ */
+function resolveSkillsRoot(override) {
+  if (override) return override;
+  try {
+    return getPackageRoot();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read the using-forge SKILL.md body (everything AFTER the frontmatter) -- the dispatch
+ * bootstrap text the SessionStart hook injects. Empty string when unresolved/absent (fail-open).
+ * @param {string} [override] - optional skills-root override (defaults to the package root).
+ * @returns {string}
+ */
+function loadDispatchText(override) {
+  const root = resolveSkillsRoot(override);
+  if (!root) return '';
+  const raw = readSkillFile(root, DISPATCH_SKILL);
+  return raw ? stripFrontmatter(raw).trim() : '';
+}
+
+/** Read a canonical skill's SKILL.md text under `<root>/skills/<name>`, or null when absent. */
+function readSkillFile(root, name) {
+  try {
+    const filePath = path.join(root, 'skills', name, 'SKILL.md');
+    if (!fs.existsSync(filePath)) return null;
+    return fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/** Remove a leading YAML frontmatter block (--- ... ---), returning the body. */
+function stripFrontmatter(raw) {
+  const text = stripBom(String(raw));
+  if (!text.startsWith('---')) return text;
+  const end = text.indexOf('\n---', 3);
+  if (end === -1) return text;
+  const afterClose = text.indexOf('\n', end + 1);
+  return afterClose === -1 ? '' : text.slice(afterClose + 1);
+}
+
+/** Return the raw frontmatter block (between the leading `---` fences), or null when absent. */
+function frontmatterBlock(raw) {
+  const text = stripBom(String(raw));
+  if (!text.startsWith('---')) return null;
+  const end = text.indexOf('\n---', 3);
+  return end === -1 ? text.slice(3) : text.slice(3, end);
+}
+
+/** Strip a single pair of leading/trailing quotes from a scalar value. */
+function unquote(value) {
+  return value.replace(/^['"]|['"]$/g, '');
+}
+
+/** Apply one frontmatter line to the running parse state (name / folded description block). */
+function applyFrontmatterLine(state, line) {
+  if (state.inDescription) {
+    if (/^\s+\S/.test(line)) {
+      state.descParts.push(line.trim());
+    } else if (line.trim() !== '') {
+      state.inDescription = false;
+    }
+    return;
+  }
+  // Detect the `name:` key without a regex: SonarCloud flags every /^name:.../ variant for
+  // super-linear backtracking. startsWith + slice is behavior-identical — the remainder is
+  // trimmed and unquoted, and an empty value leaves state.name unset just as `.+` required a value.
+  if (line.startsWith('name:')) {
+    const value = line.slice('name:'.length).trim();
+    if (value) state.name = unquote(value);
+    return;
+  }
+  const descMatch = /^description:\s*(.*)$/.exec(line);
+  if (descMatch) {
+    state.inDescription = true;
+    const inline = descMatch[1].trim();
+    if (inline && !['>', '|', '>-', '|-'].includes(inline)) state.descParts.push(unquote(inline));
+  }
+}
+
+/** Parse the name and (flattened) description from a SKILL.md frontmatter block. */
+function parseFrontmatter(raw) {
+  const block = frontmatterBlock(raw);
+  if (block === null) return { name: null, description: '' };
+  const state = { name: null, descParts: [], inDescription: false };
+  for (const line of block.split(/\r?\n/)) applyFrontmatterLine(state, line);
+  return { name: state.name, description: state.descParts.join(' ').replace(/\s+/g, ' ').trim() };
+}
+
+/** Read one skill dir into a `{ name, description }` catalog entry, or null when unreadable. */
+function readCatalogEntry(root, name) {
+  const raw = readSkillFile(root, name);
+  if (!raw) return null;
+  const fm = parseFrontmatter(raw);
+  return { name: fm.name || name, description: fm.description || '' };
+}
+
+/**
+ * Load the canonical Forge skill catalog: name + description for every skills/*\/SKILL.md under
+ * the resolved root. Sorted by name for determinism. Never throws -- an unresolved root or
+ * absent dir yields an empty array (the router then honestly returns no matches).
+ * @param {string} [override] - optional skills-root override (defaults to the package root).
+ * @returns {{name: string, description: string}[]}
+ */
+function loadSkillCatalog(override) {
+  const root = resolveSkillsRoot(override);
+  if (!root) return [];
+  let entries;
+  try {
+    entries = fs.readdirSync(path.join(root, 'skills'), { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const catalog = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const item = readCatalogEntry(root, entry.name);
+    if (item) catalog.push(item);
+  }
+  catalog.sort((a, b) => a.name.localeCompare(b.name));
+  return catalog;
+}
+
+// Curated intent-to-skill rules: the deterministic backbone of the router. Each rule scores when
+// a situation contains one of its keyword phrases; weight lets a strong signal outrank an
+// incidental token. Keywords match as normalized substrings, so a multi-word phrase matches only
+// when adjacent. This is the reasoning fallback for harnesses that cannot auto-load the skill.
+const INTENT_RULES = Object.freeze([
+  { skill: 'plan', weight: 3, keywords: ['add a feature', 'add feature', 'new feature', 'build a', 'build the', 'scope', 'design a', 'design intent', 'brainstorm', 'plan ', 'break this into tasks', 'task list'] },
+  { skill: 'dev', weight: 3, keywords: ['fix a failing test', 'failing test', 'fix a bug', 'fix the bug', 'fix this bug', 'debug', 'implement', 'write the code', 'red-green', 'tdd', 'unexpected behavior', 'broken'] },
+  { skill: 'validate', weight: 3, keywords: ['run tests', 'run the tests', 'lint', 'type check', 'typecheck', 'type-check', 'validate', 'security scan', 'run checks', 'all checks'] },
+  { skill: 'ship', weight: 3, keywords: ['open a pr', 'open pr', 'create a pr', 'create pr', 'raise a pr', 'push the branch', 'push branch', 'ship it', 'make a pull request', 'pull request'] },
+  { skill: 'review', weight: 3, keywords: ['review feedback', 'address feedback', 'pr feedback', 'coderabbit', 'greptile', 'review comment', 'resolve threads', 'address the review'] },
+  { skill: 'verify', weight: 3, keywords: ['post-merge', 'after merge', 'verify health', 'health check', 'ci on main', 'close the issue after merge'] },
+  { skill: 'triage-ready', weight: 3, keywords: ['what should i work on', 'what to work on', 'next ready', 'ready queue', 'pick the next', 'what is ready', 'rank the'] },
+  { skill: 'status', weight: 3, keywords: ['where am i', 'current stage', 'what stage', 'stale work', 'status', 'active work', 'whats going on'] },
+  { skill: 'issue-basics', weight: 2, keywords: ['create an issue', 'close an issue', 'update an issue', 'search issues', 'comment on an issue', 'file an issue', 'new issue'] },
+  { skill: 'memory', weight: 2, keywords: ['remember', 'recall', 'remember that', 'recall the', 'save a note', 'persist a note', 'note the decision', 'jot down', 'remind me'] },
+  { skill: 'claim-safety', weight: 2, keywords: ['claim an issue', 'claim the issue', 'prove ownership', 'own the lease', 'lease'] },
+  { skill: 'smith', weight: 2, keywords: ['end to end', 'end-to-end', 'drive one issue', 'plan to merged', 'whole issue', 'from plan to pr'] },
+  { skill: 'shepherd', weight: 3, keywords: ['monitor a pr', 'shepherd', 'watch the pr', 'watch my pr', 'ci status', 'poll the pr', 'pr checks', 'pr blocked', 'blocking my pr', 'blocking the pr', 'pr merging', 'pr not merging', 'ready to merge', 'merge ready', 'pr check failed', 'pr check went red', 'keep an eye on my pr', 'keep an eye on the pr', 'keep an eye on my prs', 'babysit my pr', 'babysit the pr', 'keep watching my pr', 'keep watching the pr', 'pr verdict', 'shepherd daemon', 'watch the pull request'] },
+  { skill: 'worktree', weight: 3, keywords: ['forge worktree', 'create a worktree', 'worktree list', 'isolated branch', 'isolated worktree', 'isolated checkout', 'spin up a worktree', 'work on another pr', 'merged worktrees', 'clean up merged', 'clean merged', 'orphaned worktree', 'remove the worktree', 'worktree miss', 'worktree dependencies', 'forge clean'] },
+  { skill: 'gates', weight: 3, keywords: ['disable the gate', 'disable a gate', 'enable a gate', 'enable the gate', 'toggle a gate', 'toggle the gate', 'tdd gate', 'disable the tdd', 'turn off tdd', 'tdd enforcement', 'tdd intent', 'kernel tracking rail', 'auto shepherd rail', 'loosen enforcement', 'approve the human gate', 'approve a human gate', 'human gate', 'forge control', 'forge gate', 'forge gate check', 'forge gate status', 'doc-gate', 'forge doc-gate'] },
+  { skill: 'setup', weight: 3, keywords: ['forge setup', 'install forge', 'set up forge', 'forge init', 'initialize forge', 'adoption profile', 'forge doctor', 'forge upgrade', 'upgrade forge', 'forge hooks', 'hooks globally', 'native hooks', 'forge reset', 'reset the forge', 'forge install', 'forge reinstall', 'reinstall forge', 'forge recommend', 'scaffold forge'] },
+  { skill: 'portability', weight: 3, keywords: ['forge export', 'export the backlog', 'export the kernel', 'kernel backlog', 'backlog jsonl', 'back up the backlog', 'snapshot the backlog', 'hydrate the backlog', 'forge migrate', 'migrate from beads', 'beads migration', 'migrate the beads', 'beads issue', 'import the beads', 'import a beads store', 'v2 to v3 migration'] },
+  { skill: 'research', weight: 2, keywords: ['research', 'best practices', 'investigate the landscape', 'deep research', 'compare libraries'] },
+  { skill: 'parallel-deep-research', weight: 2, keywords: ['market research', 'competitive research', 'competitor analysis', 'competitive analysis', 'competitive landscape', 'market landscape'] },
+  { skill: 'sonarcloud', weight: 2, keywords: ['sonarcloud', 'sonar', 'quality gate', 'code smell', 'code smells', 'cognitive complexity'] },
+  { skill: 'sonarcloud-analysis', weight: 1, keywords: ['sonarcloud analysis', 'sonar analysis', 'sonarcloud report', 'analyze with sonar'] },
+  { skill: 'rollback', weight: 2, keywords: ['revert', 'roll back', 'rollback', 'undo the merge', 'undo a change'] },
+  { skill: 'kernel', weight: 1, keywords: ['how does forge', 'which command', 'which skill', 'how is forge set up', 'new here', 'orient'] },
+  { skill: 'hermes-forge', weight: 2, keywords: ['hermes', 'hermes session', 'hermes harness'] },
+]);
+
+/** Normalize a situation string for matching: lowercase, collapse whitespace, strip punctuation. */
+function normalizeSituation(situation) {
+  return String(situation || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/**
+ * True when `norm` contains `keyword` as a WHOLE token/phrase, not as a substring inside a larger
+ * word. Bare "lease" must not fire on "please review"; "plan" must not fire on "planning". `norm`
+ * is pre-normalized (lowercase; only [a-z0-9\s-]), so the boundary is start/end or a non-[a-z0-9]
+ * char. Works for single words and multi-word phrases alike.
+ */
+function matchesKeyword(norm, keyword) {
+  const needle = keyword.trim();
+  if (!needle) return false;
+  const escaped = needle.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp('(?:^|[^a-z0-9])' + escaped + '(?:[^a-z0-9]|$)').test(norm);
+}
+
+/** Accumulate a weighted score + reason for a skill into the scores map. */
+function bumpScore(scores, skill, amount, reason) {
+  if (!scores.has(skill)) scores.set(skill, { score: 0, reasons: new Set() });
+  const entry = scores.get(skill);
+  entry.score += amount;
+  if (reason) entry.reasons.add(reason);
+}
+
+/**
+ * Score curated intent rules. Only skills PRESENT in the catalog (`known`) are ever scored, so an
+ * empty/unavailable catalog produces no matches instead of fabricating nonexistent skill names.
+ */
+function scoreCuratedRules(norm, known, scores) {
+  for (const rule of INTENT_RULES) {
+    if (!known.has(rule.skill)) continue;
+    for (const kw of rule.keywords) {
+      if (matchesKeyword(norm, kw)) bumpScore(scores, rule.skill, rule.weight, 'matches "' + kw.trim() + '"');
+    }
+  }
+}
+
+/**
+ * Light token-overlap bonus against each skill's own description — a TIE-BREAKER ONLY. It bumps
+ * ONLY skills that already earned a curated INTENT_RULES hit (present in `scores`); it never
+ * introduces a new skill on description overlap alone. Otherwise a generic, non-Forge prompt
+ * ("please review this commit") would route into a workflow stage via incidental token overlap.
+ */
+function scoreDescriptionOverlap(norm, catalog, scores) {
+  const tokens = new Set(norm.split(' ').filter(t => t.length >= 4));
+  for (const skill of catalog) {
+    if (!scores.has(skill.name)) continue; // no curated hit -> not a routing candidate
+    const desc = normalizeSituation(skill.description);
+    let overlap = 0;
+    for (const token of tokens) {
+      if (desc.includes(token)) overlap += 1;
+    }
+    if (overlap > 0) bumpScore(scores, skill.name, Math.min(overlap * 0.25, 1), 'described intent');
+  }
+}
+
+/** Rank scored skills highest-first (name tiebreak) and cap to `limit`. */
+function rankMatches(scores, limit) {
+  return [...scores.entries()]
+    .filter(([, v]) => v.score > 0)
+    .map(([name, v]) => ({ name, score: Math.round(v.score * 100) / 100, why: [...v.reasons].join('; ') }))
+    .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name))
+    .slice(0, limit);
+}
+
+/**
+ * Deterministically route a natural-language situation to the best-fit Forge skill(s).
+ *
+ * Scoring: curated INTENT_RULES keyword hits (weighted, catalog-gated) PLUS a light token-overlap
+ * bonus against each skill's own description. Ties break by skill name for determinism. When the
+ * catalog is empty/unavailable, returns no matches (unknown:true) rather than nonexistent skills.
+ *
+ * @param {string} situation
+ * @param {object} [options]
+ * @param {{name: string, description: string}[]} [options.catalog] - skill catalog (injectable).
+ * @param {number} [options.limit=3] - max matches to return.
+ * @returns {{ situation: string, matches: {name: string, score: number, why: string}[], best: string|null, unknown: boolean }}
+ */
+function routeSkill(situation, options = {}) {
+  const catalog = options.catalog || [];
+  const limit = Number.isInteger(options.limit) && options.limit > 0 ? options.limit : 3;
+  const norm = normalizeSituation(situation);
+  const known = new Set(catalog.map(s => s.name));
+
+  const scores = new Map();
+  if (norm) {
+    scoreCuratedRules(norm, known, scores);
+    // Description overlap is a tie-breaker among curated hits only. With NO curated hit the situation
+    // is not a confident Forge-skill match -> unknown (no overlap-only routing of generic prompts).
+    if (scores.size > 0) scoreDescriptionOverlap(norm, catalog, scores);
+  }
+
+  const matches = rankMatches(scores, limit);
+  return {
+    situation: String(situation || ''),
+    matches,
+    best: matches.length > 0 ? matches[0].name : null,
+    unknown: matches.length === 0,
+  };
+}
+
+module.exports = {
+  DISPATCH_SKILL,
+  INTENT_RULES,
+  resolveSkillsRoot,
+  loadDispatchText,
+  loadSkillCatalog,
+  parseFrontmatter,
+  stripFrontmatter,
+  normalizeSituation,
+  routeSkill,
+};