@moretea-labs/forge 1.7.0 → 1.7.1

package/scripts/check-deploy-sql-order.sh

@@ -1,117 +1,4 @@
 #!/bin/bash
 set -euo pipefail
-
-usage() {
-  cat <<'USAGE_EOF'
-Usage: scripts/check-deploy-sql-order.sh [--quiet] [--root deploy/sql]
-
-Validates deployment SQL assets:
-- deployment SQL files must live directly under deploy/sql/
-- filenames must start with a 4-digit numeric prefix
-- prefixes must be strictly ascending in filename order
-- if tests/sql/control_plane_invariants.sql exists, it must reference every deployment SQL file
-
-Example: deploy/sql/0001_create_tables.sql
-USAGE_EOF
-}
-
-quiet=0
-sql_root="deploy/sql"
-invariant_file="tests/sql/control_plane_invariants.sql"
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --quiet)
-      quiet=1
-      shift
-      ;;
-    --root)
-      sql_root="${2:-}"
-      if [[ -z "$sql_root" ]]; then
-        echo "--root requires a path" >&2
-        exit 1
-      fi
-      shift 2
-      ;;
-    --help|-h)
-      usage
-      exit 0
-      ;;
-    *)
-      echo "Unknown argument: $1" >&2
-      usage
-      exit 1
-      ;;
-  esac
-done
-
-sql_root="${sql_root%/}"
-deploy_root="${sql_root%%/sql}"
-issues=0
-
-report_issue() {
-  echo "[deploy-sql] $1"
-  issues=$((issues + 1))
-}
-
-if [[ "$sql_root" != "deploy/sql" ]]; then
-  report_issue "SQL root must be deploy/sql; got: $sql_root"
-fi
-
-if [[ ! -d "$sql_root" ]]; then
-  report_issue "Missing SQL directory: $sql_root"
-else
-  if [[ -d "$deploy_root" ]]; then
-    while IFS= read -r file; do
-      [[ -z "$file" ]] && continue
-      if [[ "$file" != "$sql_root/"* ]]; then
-        report_issue "Deploy SQL file must live under $sql_root/: $file"
-        continue
-      fi
-
-      rel="${file#"$sql_root"/}"
-      if [[ "$rel" == */* ]]; then
-        report_issue "SQL file must be a direct child of $sql_root/: $file"
-      fi
-    done < <(find "$deploy_root" -type f -name '*.sql' | sort)
-  fi
-
-  previous_number=-1
-  previous_file=""
-  while IFS= read -r file; do
-    [[ -z "$file" ]] && continue
-    base="$(basename "$file")"
-
-    if [[ ! "$base" =~ ^([0-9]{4})[_-].+\.sql$ ]]; then
-      report_issue "SQL filename must start with a 4-digit prefix: $file (example: deploy/sql/0001_create_tables.sql)"
-      continue
-    fi
-
-    number="${BASH_REMATCH[1]}"
-    number_value=$((10#$number))
-    if (( previous_number >= 0 && number_value <= previous_number )); then
-      report_issue "SQL prefixes must be strictly ascending: $previous_file before $file"
-    fi
-
-    previous_number="$number_value"
-    previous_file="$file"
-  done < <(find "$sql_root" -maxdepth 1 -type f -name '*.sql' | sort)
-
-  if [[ -f "$invariant_file" ]]; then
-    while IFS= read -r file; do
-      [[ -z "$file" ]] && continue
-      base="$(basename "$file")"
-      if ! grep -Fq "$file" "$invariant_file" && ! grep -Fq "$base" "$invariant_file"; then
-        report_issue "SQL migration must be referenced by $invariant_file: $file"
-      fi
-    done < <(find "$sql_root" -maxdepth 1 -type f -name '*.sql' | sort)
-  fi
-fi
-
-if (( issues > 0 )); then
-  exit 1
-fi
-
-if (( quiet == 0 )); then
-  echo "[deploy-sql] OK"
-fi
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec "$SCRIPT_DIR/lib/run-forge-helper.sh" "check-deploy-sql-order.sh" "$@"

package/scripts/check-runtime-architecture.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { readFileSync, existsSync, lstatSync, readdirSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { createRequire } from 'node:module';
+import { dirname, extname, normalize, resolve } from 'node:path';
 
 const root = resolve(new URL('..', import.meta.url).pathname);
 const failures = [];
@@ -52,6 +53,105 @@ function sourceFiles(directory) {
   return files;
 }
 
+function relativeStaticTypeScriptDependencyGraph(directory = 'src') {
+  let ts;
+  try {
+    ts = createRequire(import.meta.url)('typescript');
+  } catch (error) {
+    failures.push(`TypeScript dependency is required for architecture import-cycle analysis: ${error instanceof Error ? error.message : String(error)}`);
+    return new Map();
+  }
+
+  const files = sourceFiles(directory).sort();
+  const known = new Set(files);
+  const graph = new Map(files.map((path) => [path, new Set()]));
+
+  function resolveTypeScriptImport(fromPath, specifier) {
+    if (!specifier.startsWith('.')) return undefined;
+    const base = normalize(`${dirname(fromPath)}/${specifier}`).replaceAll('\\', '/');
+    const extension = extname(base);
+    const withoutRuntimeExtension = ['.js', '.mjs', '.cjs'].includes(extension)
+      ? base.slice(0, -extension.length)
+      : base;
+    const candidates = extension === '.ts'
+      ? [base]
+      : [withoutRuntimeExtension, `${withoutRuntimeExtension}.ts`, `${withoutRuntimeExtension}/index.ts`];
+    return candidates.find((candidate) => known.has(candidate));
+  }
+
+  for (const path of files) {
+    const sourceFile = ts.createSourceFile(path, text(path), ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    for (const statement of sourceFile.statements) {
+      let specifier;
+      if ((ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement))
+          && statement.moduleSpecifier
+          && ts.isStringLiteralLike(statement.moduleSpecifier)) {
+        specifier = statement.moduleSpecifier.text;
+      } else if (ts.isImportEqualsDeclaration(statement)
+          && ts.isExternalModuleReference(statement.moduleReference)
+          && statement.moduleReference.expression
+          && ts.isStringLiteralLike(statement.moduleReference.expression)) {
+        specifier = statement.moduleReference.expression.text;
+      }
+      if (!specifier) continue;
+      const target = resolveTypeScriptImport(path, specifier);
+      if (target) graph.get(path).add(target);
+    }
+  }
+  return graph;
+}
+
+function stronglyConnectedComponents(graph) {
+  let index = 0;
+  const indices = new Map();
+  const lowLinks = new Map();
+  const stack = [];
+  const onStack = new Set();
+  const components = [];
+
+  function visit(node) {
+    indices.set(node, index);
+    lowLinks.set(node, index);
+    index += 1;
+    stack.push(node);
+    onStack.add(node);
+
+    for (const target of graph.get(node) ?? []) {
+      if (!indices.has(target)) {
+        visit(target);
+        lowLinks.set(node, Math.min(lowLinks.get(node), lowLinks.get(target)));
+      } else if (onStack.has(target)) {
+        lowLinks.set(node, Math.min(lowLinks.get(node), indices.get(target)));
+      }
+    }
+
+    if (lowLinks.get(node) !== indices.get(node)) return;
+    const component = [];
+    while (stack.length) {
+      const member = stack.pop();
+      onStack.delete(member);
+      component.push(member);
+      if (member === node) break;
+    }
+    components.push(component.sort());
+  }
+
+  for (const node of [...graph.keys()].sort()) {
+    if (!indices.has(node)) visit(node);
+  }
+  return components;
+}
+
+function requireAcyclicProductionTypeScript() {
+  const graph = relativeStaticTypeScriptDependencyGraph('src');
+  const cyclic = stronglyConnectedComponents(graph).filter((component) =>
+    component.length > 1 || (component.length === 1 && graph.get(component[0])?.has(component[0])),
+  );
+  for (const component of cyclic) {
+    failures.push(`production TypeScript import cycle: ${component.join(' -> ')}`);
+  }
+}
+
 const allowedArchitectureRootMarkdown = new Set(['CURRENT.md', 'EVOLUTION.md', 'history.md', 'index.md']);
 const architectureRootMarkdown = readdirSync(resolve(root, 'docs/architecture'), { withFileTypes: true })
   .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
@@ -96,6 +196,26 @@ const required = [
   'src/runtime/execution/thin-harness/index.ts',
   'src/runtime/execution/thin-harness/execution-router.ts',
   'src/runtime/control-plane/routing/route-policy.ts',
+  'src/runtime/control-plane/routing/workspace-admission.ts',
+  'src/runtime/control-plane/facade/requirement-authority.ts',
+  'src/runtime/control-plane/facade/repository-work-admission.ts',
+  'src/runtime/control-plane/execution/retained-work-resume.ts',
+  'src/runtime/control-plane/execution/work-handle-authority.ts',
+  'src/runtime/control-plane/execution/work-verification-context.ts',
+  'src/runtime/control-plane/execution/work-verification-service.ts',
+  'src/runtime/control-plane/execution/repository-work-attribution.ts',
+  'src/runtime/control-plane/execution/work-completion-authority.ts',
+  'src/runtime/control-plane/execution/work-evidence-policy.ts',
+  'src/runtime/control-plane/execution/work-execution-support.ts',
+  'src/runtime/control-plane/execution/work-finalization-service.ts',
+  'src/runtime/control-plane/execution/work-preparation-service.ts',
+  'src/runtime/control-plane/execution/work-operation-service.ts',
+  'src/runtime/control-plane/facade/work-state-machine.ts',
+  'src/runtime/evidence/process-check-execution.ts',
+  'src/runtime/context/semantic-navigation-contract.ts',
+  'src/cli/mcp/tool-contract.ts',
+  'src/cli/github/contracts.ts',
+  'src/runtime/gateway/mcp/runtime-tool-definitions.ts',
   'docs/architecture/CURRENT.md',
   'src/runtime/resources/leases/store.ts',
   'src/runtime/evidence/event-ledger.ts',
@@ -124,19 +244,33 @@ const required = [
   'src/cli/index.ts',
 ];
 for (const path of required) text(path);
+requireAcyclicProductionTypeScript();
+for (const path of sourceFiles('src/runtime/control-plane')) {
+  forbid(path, /(?:from\s+['"]|import\s*\(\s*['"])(?:\.\.\/)+gateway\//, 'control-plane domain/application code must not depend on Gateway transport');
+}
 requireText('src/runtime/control-plane/routing/route-policy.ts', "export function decideRoute");
 requireText('src/runtime/control-plane/routing/route-policy.ts', 'inputFingerprint');
 requireText('src/runtime/control-plane/routing/route-policy.ts', 'policyVersion');
-requireText('src/runtime/gateway/mcp/runtime-tools.ts', 'runPersistedCheckViaProcessRuntime({');
-requireText('src/runtime/gateway/mcp/runtime-tools.ts', 'interactiveWaitMs: 0');
-requireText('src/runtime/gateway/mcp/runtime-tools.ts', 'checkContentRevision');
-requireText('src/runtime/gateway/mcp/runtime-tools.ts', 'observedGitHead');
-forbidBetween(
+requireText('src/runtime/control-plane/execution/work-verification-service.ts', 'runPersistedCheckViaProcessRuntime({');
+requireText('src/runtime/control-plane/execution/work-verification-service.ts', 'interactiveWaitMs: input.interactiveWaitMs ?? 0');
+requireText('src/runtime/control-plane/execution/work-verification-service.ts', 'checkContentRevision');
+requireText('src/runtime/control-plane/execution/work-verification-service.ts', 'observedGitHead');
+requireText('src/runtime/gateway/mcp/runtime-tools.ts', 'executeWorkVerification({');
+requireText('src/cli/local-bridge/facade-api.ts', 'executeWorkVerification({');
+forbid(
+  'src/cli/local-bridge/facade-api.ts',
+  /runControllerCheck\s*\(/,
+  'Local Bridge Work verification must use the canonical persisted Work verification service',
+);
+forbid(
   'src/runtime/gateway/mcp/runtime-tools.ts',
-  'async function runFacadeVerify(',
-  'export async function callRuntimeTool',
+  /function\s+classifyTerminalCheckEvidence\s*\(/,
+  'terminal Check evidence classification belongs to Process Runtime, not the Gateway transport',
+);
+forbid(
+  'src/runtime/control-plane/execution/work-verification-service.ts',
   /runControllerCheck\s*\(/,
-  'route rh_work verify through persisted Process Runtime instead of synchronous check execution',
+  'route Work verification through persisted Process Runtime instead of synchronous check execution',
 );
 for (const adapter of [
   'src/cli/controller/work-mode.ts',
@@ -152,6 +286,52 @@ for (const path of sourceFiles('src')) {
   forbid(path, /requirePlanForGoalWorkloop\s*:\s*true/, 'never restore mandatory Plan gating in production');
 }
 if (routeAuthorityCount !== 1) failures.push(`exactly one decideRoute authority is required; found ${routeAuthorityCount}`);
+forbid(
+  'src/runtime/control-plane/facade/goal-workloop.ts',
+  /function\s+(?:evaluateWorkCompletionEvidence|evaluateWorkImplementationEvidence|verificationRecordAppliesToCurrentWorkspace)\s*\(/,
+  'keep Work evidence policy in the canonical work-evidence-policy module instead of reimplementing it in the facade',
+);
+requireText('src/runtime/control-plane/facade/goal-workloop.ts', "from '../execution/work-evidence-policy'");
+for (const path of sourceFiles('src/runtime/control-plane')) {
+  if (path === 'src/runtime/control-plane/facade/work-contract-store.ts' || path === 'src/runtime/control-plane/execution/work-completion-authority.ts') continue;
+  forbid(
+    path,
+    /\brecordWorkCompletionReceipt\s*\(/,
+    'route Work completion through the canonical work-completion-authority instead of writing terminal receipts directly',
+  );
+}
+requireText('src/runtime/control-plane/execution/work-finalization-service.ts', 'completeWorkWithReceipt(');
+forbid(
+  'src/runtime/plugins/browser-handoff-host.ts',
+  /browser\/sessions|saveBrowserSession|writeBrowserSession|sessionPath/,
+  'Browser handoff sidecars must return interaction results and never write BrowserSession authority directly',
+);
+forbid(
+  'src/runtime/plugins/browser-adapter.ts',
+  /BROWSER_POST_DISPATCH_REPLAY_SAFE_ACTIONS|POST_DISPATCH_REPLAY_SAFE_ACTIONS/,
+  'Browser replay safety must come from Browser Runtime transaction policy, not an adapter-local allowlist',
+);
+requireText('src/runtime/plugins/browser-runtime.ts', 'browserActionCanReplayAfterDispatch');
+forbid(
+  'src/runtime/gateway/mcp/runtime-tools.ts',
+  /\b(?:createRequirement|resumeRetainedCancelledWorkContract)\s*\(/,
+  'keep Requirement admission and retained-cancelled Work lifecycle authority out of the MCP transport',
+);
+forbid(
+  'src/runtime/gateway/mcp/runtime-tools.ts',
+  /\b(?:updateWorkContract|writeWorkHandle)\s*\(/,
+  'keep WorkContract/WorkHandle persistence policy out of the MCP transport',
+);
+forbid(
+  'src/runtime/gateway/mcp/execution-tools.ts',
+  /\bcreateWorkContract\s*\(/,
+  'route compatibility work preparation through canonical Work admission authority',
+);
+forbid(
+  'src/cli/mcp/legacy-tool-service.ts',
+  /\bcreateWorkContract\s*\(/,
+  'keep the legacy MCP surface as translation over canonical Work admission authority',
+);
 requireMissing('src/runtime/control-plane/daemon-entry.ts');
 requireMissing('scripts/smoke-runtime-control-plane.ts');
 requireMissing('src/cli/controller/lifecycle.ts');
@@ -386,7 +566,14 @@ requireText('src/runtime/gateway/mcp/execution-tools.ts', 'isDurableWorkOperatio
 requireText('src/runtime/gateway/mcp/execution-tools.ts', "'work_execute'");
 requireText('src/runtime/gateway/mcp/execution-tools.ts', "'work_validate'");
 requireText('src/runtime/gateway/mcp/execution-tools.ts', "'work_finalize'");
-requireText('src/runtime/execution/workers/executor.ts', 'callExecutionTool(runtimeContext');
+requireText('src/runtime/execution/workers/executor.ts', 'executeWork(runtimeContext');
+requireText('src/runtime/execution/workers/executor.ts', 'validateWork(runtimeContext');
+requireText('src/runtime/execution/workers/executor.ts', 'finalizeWork(runtimeContext');
+forbid(
+  'src/runtime/execution/workers/executor.ts',
+  /gateway\/mcp\/execution-tools|callExecutionTool\s*\(/,
+  'Execution Worker must invoke control-plane Work application services directly, never MCP transport',
+);
 requireText('src/runtime/execution/workers/executor.ts', '__from_durable_worker');
 requireText('src/runtime/gateway/mcp/runtime-tools.ts', 'managedProcessOperationDigest');
 forbid(
@@ -582,14 +769,50 @@ forbidBetween(
 requireText('src/runtime/control-plane/execution/session-store.ts', 'lastValidatedAt: now');
 requireText('src/runtime/control-plane/execution/validation.ts', 'warnings.push');
 requireText('src/runtime/control-plane/execution/work-handle-store.ts', "failed: ['validating', 'editing', 'committed', 'merged', 'cleaned', 'failed_terminal_cleanup']");
-requireText('src/runtime/gateway/mcp/execution-tools.ts', 'resetFinalizationStagesForRequest');
-requireText('src/runtime/gateway/mcp/execution-tools.ts', 'finalizationComplete');
-forbidBetween(
+requireText('src/runtime/gateway/mcp/execution-tools.ts', "from '../../control-plane/execution/work-finalization-service'");
+requireText('src/runtime/gateway/mcp/execution-tools.ts', "from '../../control-plane/execution/work-preparation-service'");
+requireText('src/runtime/gateway/mcp/execution-tools.ts', "from '../../control-plane/execution/work-operation-service'");
+requireText('src/runtime/gateway/mcp/execution-tools.ts', 'Compatibility exports: implementation authority lives in control-plane execution.');
+requireText('src/runtime/gateway/mcp/execution-tools.ts', 'resetFinalizationStagesForRequest,');
+requireText('src/runtime/gateway/mcp/execution-tools.ts', 'selectDefaultWorkValidationChecks');
+requireText('src/runtime/gateway/mcp/runtime-tools.ts', "callExecutionTool(ctx, 'work_finalize'");
+forbid(
+  'src/runtime/gateway/mcp/runtime-tools.ts',
+  /repositoryGit(?:Commit|FinishWorkflow|MergeBranch|DeleteBranch|RebaseOnto)\s*\(/,
+  'rh_work facade finalization must delegate to the canonical Work finalization application service instead of performing Git delivery itself',
+);
+forbid(
   'src/runtime/gateway/mcp/execution-tools.ts',
-  'function finalizeWork(',
-  'export async function callExecutionTool',
+  /function\s+finalizeWork\s*\(/,
+  'MCP execution transport must delegate Work finalization to the control-plane application service',
+);
+forbid(
+  'src/runtime/gateway/mcp/execution-tools.ts',
+  /function\s+(?:prepareWork|adoptExistingWorkHead)\s*\(/,
+  'MCP execution transport must delegate Work preparation/adoption to the control-plane application service',
+);
+forbid(
+  'src/runtime/gateway/mcp/execution-tools.ts',
+  /function\s+(?:executeWork|validateWork)\s*\(/,
+  'MCP execution transport must delegate Work execute/validate operations to the control-plane application service',
+);
+forbid(
+  'src/runtime/gateway/mcp/execution-tools.ts',
+  /(?:ensureManagedWorkspace|admitPreparedRepositoryWorkContract)\s*\(/,
+  'MCP execution transport must not own managed-workspace or WorkContract preparation admission',
+);
+requireText('src/runtime/control-plane/execution/work-preparation-service.ts', 'export function prepareWork(');
+requireText('src/runtime/control-plane/execution/work-preparation-service.ts', 'function adoptExistingWorkHead(');
+requireText('src/runtime/control-plane/execution/work-operation-service.ts', 'export async function executeWork(');
+requireText('src/runtime/control-plane/execution/work-operation-service.ts', 'export async function validateWork(');
+requireText('src/runtime/control-plane/execution/work-finalization-service.ts', 'resetFinalizationStagesForRequest');
+requireText('src/runtime/control-plane/execution/work-finalization-service.ts', 'finalizationComplete');
+forbidBetween(
+  'src/runtime/control-plane/execution/work-finalization-service.ts',
+  'export async function finalizeWork(',
+  '// WORK_FINALIZATION_SERVICE_END',
   /withControllerLock\([\s\S]{0,900}?(?:repositoryGitCommit|repositoryGitFinishWorkflow|runCleanup|repositoryGitDeleteBranch)/,
-  'work_finalize must not hold the controller lock while committing, merging, deleting branches, or removing worktrees',
+  'Work finalization must not hold the controller lock while committing, merging, deleting branches, or removing worktrees',
 );
 requireText('src/runtime/workflow/schedules/types.ts', "'repository-event'");
 requireText('src/runtime/workflow/schedules/types.ts', "'dependency-checkpoint'");
@@ -614,6 +837,10 @@ for (const path of [
   forbid(path, /\b(?:spawnSync|execSync|execFileSync)\s*\(/, 'the non-blocking Gateway/Controller hot-path rule');
 }
 
+requireText('scripts/run-governed-gate.ts', "label: 'source duplication'");
+requireText('scripts/run-governed-gate.ts', "args: ['scripts/check-source-duplication.mjs']");
+requireText('scripts/run-governed-gate.ts', "label: 'controller UI bundle'");
+requireText('scripts/run-governed-gate.ts', "args: ['run', 'check:controller-ui']");
 requireText('docs/architecture/CURRENT.md', '## State ownership');
 requireText('docs/architecture/CURRENT.md', '## Runtime and MCP boundary');
 requireText('docs/architecture/CURRENT.md', '## Testing and verification');

package/scripts/check-skill-version.ts

@@ -1,193 +1,5 @@
 #!/usr/bin/env bun
-/**
- * Skill Version Consistency Checker
- *
- * Validates that version numbers are consistent across:
- * - package.json
- * - assets/skill-version.json
- *
- * Also checks if a generated project needs migration.
- */
+export * from "../assets/templates/helpers/check-skill-version";
+import { runTrackedForgeHelper } from "./lib/run-forge-helper";
 
-import { readFileSync, existsSync } from "fs";
-import { join, dirname } from "path";
-import { fileURLToPath } from "url";
-import { resolveAgenticDevRoot } from "./workflow-contract.ts";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const REPO_ROOT = __dirname.endsWith("/.ai/harness/scripts")
-  ? join(__dirname, "../../..")
-  : __dirname.endsWith("/assets/templates/helpers")
-    ? join(__dirname, "../../..")
-    : join(__dirname, "..");
-
-export interface ConsistencyResult {
-  consistent: boolean;
-  packageJsonVersion: string | null;
-  skillVersionJsonVersion: string;
-  templateVersionJsonVersion: string;
-  skillVersionSource: string;
-  warnings: string[];
-  errors: string[];
-}
-
-export interface MigrationCheckResult {
-  needsMigration: boolean;
-  currentSkillVersion: string;
-  projectSkillVersion: string | null;
-  projectTemplatVersion: string | null;
-}
-
-/**
- * Check version consistency across the version sources this repo owns.
- */
-export function checkConsistency(repoRoot: string = REPO_ROOT): ConsistencyResult {
-  const errors: string[] = [];
-  const warnings: string[] = [];
-
-  // Read package.json
-  const pkgPath = join(repoRoot, "package.json");
-  if (!existsSync(pkgPath)) {
-    throw new Error(`package.json not found at ${pkgPath}`);
-  }
-  const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-  const packageJsonVersion =
-    typeof pkg.version === "string" && pkg.version.length > 0
-      ? (pkg.version as string)
-      : null;
-
-  // Read the local source manifest when this script runs inside forge;
-  // generated projects resolve the upstream skill root instead.
-  const localSvPath = join(repoRoot, "assets", "skill-version.json");
-  const svPath = existsSync(localSvPath)
-    ? localSvPath
-    : join(resolveAgenticDevRoot(repoRoot), "assets", "skill-version.json");
-  if (!existsSync(svPath)) {
-    throw new Error(`skill-version.json not found at ${svPath}`);
-  }
-  const sv = JSON.parse(readFileSync(svPath, "utf-8"));
-  const skillVersionJsonVersion = sv.version as string;
-  const templateVersionJsonVersion = sv.templateVersion as string;
-  const usingLocalSkillManifest = svPath === localSvPath;
-
-  const packageCoreVersion = packageJsonVersion?.split("-", 1)[0] ?? null;
-  const isForgePackage =
-    pkg.name === "forge" ||
-    pkg.name === "@moretea-labs/forge-controller" ||
-    pkg.name === "@moretea-labs/forge";
-
-  if (
-    usingLocalSkillManifest &&
-    isForgePackage &&
-    packageCoreVersion !== null &&
-    packageCoreVersion !== skillVersionJsonVersion
-  ) {
-    errors.push(
-      `package.json core version (${packageCoreVersion}) must match assets/skill-version.json version (${skillVersionJsonVersion})`
-    );
-  }
-
-  if (usingLocalSkillManifest && templateVersionJsonVersion !== skillVersionJsonVersion) {
-    errors.push(
-      `assets/skill-version.json templateVersion (${templateVersionJsonVersion}) must match version (${skillVersionJsonVersion})`
-    );
-  }
-
-  if (!usingLocalSkillManifest && packageJsonVersion !== null) {
-    warnings.push(
-      `package.json.version (${packageJsonVersion}) belongs to the target repo; workflow stamp uses upstream forge skill-version.json`
-    );
-  }
-
-  return {
-    consistent: errors.length === 0,
-    packageJsonVersion,
-    skillVersionJsonVersion,
-    templateVersionJsonVersion,
-    skillVersionSource: svPath,
-    warnings,
-    errors,
-  };
-}
-
-/**
- * Check if a generated project needs migration.
- */
-export function checkProjectNeedsMigration(
-  projectPath: string,
-  repoRoot: string = REPO_ROOT
-): MigrationCheckResult {
-  const localSvPath = join(repoRoot, "assets", "skill-version.json");
-  const svPath = existsSync(localSvPath)
-    ? localSvPath
-    : join(resolveAgenticDevRoot(repoRoot), "assets", "skill-version.json");
-  const sv = JSON.parse(readFileSync(svPath, "utf-8"));
-  const currentSkillVersion = sv.version as string;
-
-  const stampPath = join(projectPath, ".claude", ".skill-version");
-  if (!existsSync(stampPath)) {
-    return {
-      needsMigration: true,
-      currentSkillVersion,
-      projectSkillVersion: null,
-      projectTemplatVersion: null,
-    };
-  }
-
-  const stampContent = readFileSync(stampPath, "utf-8");
-  const skillVersionMatch = stampContent.match(/^skill_version=(.+)$/m);
-  const templateVersionMatch = stampContent.match(/^template_version=(.+)$/m);
-
-  const projectSkillVersion = skillVersionMatch?.[1] ?? null;
-  const projectTemplatVersion = templateVersionMatch?.[1] ?? null;
-
-  return {
-    needsMigration: projectSkillVersion !== currentSkillVersion,
-    currentSkillVersion,
-    projectSkillVersion,
-    projectTemplatVersion,
-  };
-}
-
-// CLI entry point
-if (import.meta.main) {
-  const args = process.argv.slice(2);
-  const projectIdx = args.indexOf("--project");
-  const projectPath = projectIdx !== -1 ? args[projectIdx + 1] : null;
-
-  try {
-    const result = checkConsistency();
-
-    if (result.consistent) {
-      console.log(
-        `Workflow version check passed: forge=${result.skillVersionJsonVersion}, template=${result.templateVersionJsonVersion}`
-      );
-      console.log(`Workflow version source: ${result.skillVersionSource}`);
-      for (const warning of result.warnings) {
-        console.log(`Warning: ${warning}`);
-      }
-    } else {
-      console.error("Version consistency check FAILED:");
-      for (const error of result.errors) {
-        console.error(`  - ${error}`);
-      }
-      process.exit(1);
-    }
-
-    if (projectPath) {
-      const migration = checkProjectNeedsMigration(projectPath);
-      if (migration.needsMigration) {
-        console.log(
-          `Project at ${projectPath} needs migration: ` +
-          `${migration.projectSkillVersion ?? "(no stamp)"} → ${migration.currentSkillVersion}`
-        );
-      } else {
-        console.log(`Project at ${projectPath} is up to date (${migration.currentSkillVersion})`);
-      }
-    }
-  } catch (error) {
-    console.error("Error:", error instanceof Error ? error.message : error);
-    process.exit(1);
-  }
-}
+if (import.meta.main) runTrackedForgeHelper("check-skill-version.ts");