coding-agent-harness 1.0.7 → 1.1.0

package/dist/lib/impact-classifier.mjs

@@ -0,0 +1,420 @@
+import path from "node:path";
+const surfaceOrder = [
+    "ts-runtime",
+    "type-island",
+    "runtime-build",
+    "built-test-runner",
+    "dashboard-data",
+    "template-schema",
+    "dashboard-ui",
+    "docs-release",
+    "preset-package",
+    "package-boundary",
+    "migration-legacy",
+    "multi-repo-contract",
+    "ci-pr-evidence",
+    "root-contributor-docs",
+    "skill-reference-distribution",
+    "fixture-golden",
+    "gui-submodule",
+    "private-local-only",
+    "unknown",
+];
+const runtimeLayerOrder = ["ts-source", "runtime-emit", "built-test", "package-runtime", "installed-target", "not-runtime"];
+const gateOrder = [
+    "typecheck",
+    "typecheck-guards",
+    "import-graph",
+    "dist-drift",
+    "runtime-emit-contract",
+    "dist-build-pipeline",
+    "dist-observation",
+    "temp-project-cli-smoke",
+    "status-json-contract",
+    "built-tests",
+    "target-project-check",
+    "dashboard-smoke",
+    "source-package-check",
+    "pack-dry-run",
+    "docs-leak-link-check",
+    "compatibility-policy",
+    "maintainer-review",
+    "dashboard-data-golden",
+    "preset-contract",
+    "migration-fixture",
+    "workflow-lint",
+    "fixture-manifest",
+    "gui-check",
+    "command-consistency",
+];
+const compatibilityPolicies = ["legacy-support", "migration-required", "hard-cutover"];
+const surfaceGateMap = {
+    "ts-runtime": ["typecheck", "typecheck-guards", "import-graph", "dist-drift"],
+    "type-island": ["typecheck", "typecheck-guards", "import-graph"],
+    "runtime-build": ["runtime-emit-contract", "dist-build-pipeline", "dist-observation", "dist-drift"],
+    "built-test-runner": ["built-tests", "typecheck"],
+    "dashboard-data": ["dashboard-data-golden", "status-json-contract", "dashboard-smoke"],
+    "template-schema": ["target-project-check", "compatibility-policy"],
+    "dashboard-ui": ["dashboard-smoke"],
+    "docs-release": ["docs-leak-link-check", "source-package-check"],
+    "preset-package": ["preset-contract", "source-package-check", "compatibility-policy"],
+    "package-boundary": ["source-package-check", "pack-dry-run", "compatibility-policy"],
+    "migration-legacy": ["migration-fixture", "compatibility-policy"],
+    "multi-repo-contract": ["target-project-check", "maintainer-review"],
+    "ci-pr-evidence": ["workflow-lint", "maintainer-review"],
+    "root-contributor-docs": ["docs-leak-link-check", "source-package-check", "command-consistency"],
+    "skill-reference-distribution": ["source-package-check", "pack-dry-run"],
+    "fixture-golden": ["fixture-manifest", "target-project-check"],
+    "gui-submodule": ["gui-check"],
+    "private-local-only": ["source-package-check", "maintainer-review"],
+    "unknown": ["maintainer-review"],
+};
+const gateReasonMap = {
+    typecheck: "TypeScript source changes must satisfy the enforced strict type gate.",
+    "typecheck-guards": "Type boundary and no-ts-nocheck guards protect shared type islands and implementation coverage.",
+    "import-graph": "Runtime and type island changes can introduce unresolved imports, cycles, or invalid type imports.",
+    "dist-drift": "Runtime source or emit changes can make committed/package dist drift from TypeScript source.",
+    "runtime-emit-contract": "Runtime build surfaces must prove TypeScript emits package-safe JavaScript.",
+    "dist-build-pipeline": "Runtime build changes must prove the dist build pipeline still emits required package files.",
+    "dist-observation": "Runtime/package changes need dist observation evidence across source, package, and command surfaces.",
+    "temp-project-cli-smoke": "CLI/runtime changes need target-project smoke evidence for the installed command path.",
+    "status-json-contract": "Status, scanner, and CLI JSON surfaces need machine-readable contract evidence.",
+    "built-tests": "Built tests prove the compiled test runner still exercises the package runtime shape.",
+    "target-project-check": "Target project fixtures prove templates, examples, and contracts remain usable.",
+    "dashboard-smoke": "Dashboard surfaces need smoke coverage for data and UI consumption.",
+    "source-package-check": "Package-facing changes must not publish private or local-only source state.",
+    "pack-dry-run": "Package boundary changes need file-list and npm packaging evidence.",
+    "docs-leak-link-check": "Public documentation changes need leak and link/path validation.",
+    "compatibility-policy": "Contract-changing surfaces must declare legacy-support, migration-required, or hard-cutover.",
+    "maintainer-review": "Unknown or high-cost surfaces require maintainer review before contributor verify can pass.",
+    "dashboard-data-golden": "Dashboard data contract changes need golden or schema evidence.",
+    "preset-contract": "Preset changes need install, resource, and safety contract evidence.",
+    "migration-fixture": "Migration and legacy changes need fixture evidence for supported or rejected formats.",
+    "workflow-lint": "CI and PR evidence changes need workflow and path-filter validation.",
+    "fixture-manifest": "Fixture and golden changes need drift policy evidence.",
+    "gui-check": "GUI submodule changes need path-filtered GUI validation or pointer evidence.",
+    "command-consistency": "Contributor docs must stay consistent with actual package commands and profiles.",
+};
+export function classifyImpact(changedFiles) {
+    const classifiedFiles = changedFiles.map(classifyChangedFile);
+    const surfaces = orderedUnique(classifiedFiles.flatMap((file) => file.surfaces), surfaceOrder);
+    const runtimeLayers = orderedUnique(classifiedFiles.flatMap((file) => file.runtimeLayers), runtimeLayerOrder);
+    const requiredGateIds = orderedUnique(classifiedFiles.flatMap((file) => file.requiredGates), gateOrder);
+    const compatibilityRequirements = classifiedFiles.flatMap((file) => buildCompatibilityRequirements(file));
+    return {
+        changedFiles: classifiedFiles,
+        surfaces,
+        runtimeLayers,
+        requiredGates: requiredGateIds.map((gate) => ({
+            id: gate,
+            blocking: gate === "maintainer-review" ? "maintainer-review" : "required",
+            reason: gateReasonMap[gate],
+            surfaces: surfacesForGate(surfaces, gate),
+        })),
+        unknownSurfaces: classifiedFiles.flatMap((file) => buildUnknownSurface(file)),
+        compatibilityPolicyRequired: compatibilityRequirements.length > 0,
+        compatibilityPolicyRequirements: compatibilityRequirements,
+    };
+}
+function classifyChangedFile(record) {
+    const normalizedPath = normalizeChangedPath(record.path);
+    const normalizedOldPath = record.oldPath ? normalizeChangedPath(record.oldPath) : undefined;
+    const pathClassifications = [
+        classifyPath(normalizedPath, record),
+        ...(normalizedOldPath && normalizedOldPath !== normalizedPath ? [classifyPath(normalizedOldPath, record)] : []),
+    ];
+    const surfaces = orderedUnique(pathClassifications.flatMap((classification) => classification.surfaces), surfaceOrder);
+    const runtimeLayers = orderedUnique(pathClassifications.flatMap((classification) => classification.runtimeLayers), runtimeLayerOrder);
+    const requiredGates = orderedUnique([...surfaces.flatMap((surface) => surfaceGateMap[surface]), ...pathClassifications.flatMap((classification) => classification.requiredGates)], gateOrder);
+    return {
+        path: normalizedPath,
+        status: record.status,
+        ...(normalizedOldPath ? { oldPath: normalizedOldPath } : {}),
+        surfaces,
+        runtimeLayers,
+        requiredGates,
+        compatibilityPolicyRequired: pathClassifications.some((classification) => classification.compatibilityPolicyRequired),
+    };
+}
+function classifyPath(relativePath, record) {
+    const surfaces = [];
+    const runtimeLayers = [];
+    const requiredGates = [];
+    let compatibilityPolicyRequired = false;
+    const addSurface = (surface) => {
+        surfaces.push(surface);
+    };
+    const addLayer = (layer) => {
+        runtimeLayers.push(layer);
+    };
+    const requirePolicy = () => {
+        compatibilityPolicyRequired = true;
+    };
+    const requireGate = (gate) => {
+        requiredGates.push(gate);
+    };
+    if (!isRepositoryRelativePath(relativePath)) {
+        addSurface("unknown");
+        addLayer("not-runtime");
+        return { surfaces: orderedUnique(surfaces, surfaceOrder), runtimeLayers: orderedUnique(runtimeLayers, runtimeLayerOrder), compatibilityPolicyRequired, requiredGates: orderedUnique(requiredGates, gateOrder) };
+    }
+    if (isPrivateLocalOnlyPath(relativePath)) {
+        addSurface("private-local-only");
+        addLayer("not-runtime");
+        return { surfaces: orderedUnique(surfaces, surfaceOrder), runtimeLayers: orderedUnique(runtimeLayers, runtimeLayerOrder), compatibilityPolicyRequired, requiredGates: orderedUnique(requiredGates, gateOrder) };
+    }
+    if (record.isSubmodule || relativePath === "harness-gui" || relativePath.startsWith("harness-gui/")) {
+        addSurface("gui-submodule");
+        addLayer("not-runtime");
+    }
+    if (relativePath.startsWith(".github/")) {
+        addSurface("ci-pr-evidence");
+        addLayer("not-runtime");
+        if (relativePath === ".github/pull_request_template.md")
+            requirePolicy();
+    }
+    if (isTypeIslandPath(relativePath)) {
+        addSurface("type-island");
+        addLayer("ts-source");
+    }
+    if (isCliContractPath(relativePath)) {
+        requireGate("temp-project-cli-smoke");
+        requireGate("status-json-contract");
+        requirePolicy();
+    }
+    if (isTsRuntimePath(relativePath)) {
+        addSurface("ts-runtime");
+        addLayer("ts-source");
+    }
+    if (isRuntimeBuildPath(relativePath)) {
+        addSurface("runtime-build");
+        addLayer("runtime-emit");
+        if (relativePath === "tsconfig.json")
+            addLayer("ts-source");
+        if (relativePath.startsWith("dist/")) {
+            addSurface("package-boundary");
+            addLayer("package-runtime");
+            requirePolicy();
+        }
+    }
+    if (isBuiltTestRunnerPath(relativePath)) {
+        addSurface("built-test-runner");
+        addLayer("built-test");
+        if (/^tests\/.*\.mts$/.test(relativePath))
+            addLayer("ts-source");
+    }
+    if (isDashboardDataPath(relativePath)) {
+        addSurface("dashboard-data");
+        requirePolicy();
+        if (relativePath.startsWith("scripts/"))
+            addLayer("ts-source");
+    }
+    if (relativePath.startsWith("templates/dashboard/assets/")) {
+        addSurface("dashboard-ui");
+        addLayer("installed-target");
+        if (relativePath.includes("manifest"))
+            requirePolicy();
+    }
+    else if (relativePath.startsWith("templates/") || relativePath.startsWith("templates-zh-CN/")) {
+        addSurface("template-schema");
+        addLayer("installed-target");
+        requirePolicy();
+    }
+    if (relativePath.startsWith("docs-release/")) {
+        addSurface("docs-release");
+        addLayer("not-runtime");
+        if (relativePath.includes("parent-control-repository-pattern"))
+            addSurface("multi-repo-contract");
+    }
+    if (isRootContributorDoc(relativePath)) {
+        addSurface("root-contributor-docs");
+        addLayer("not-runtime");
+    }
+    if (isPresetPackagePath(relativePath)) {
+        addSurface("preset-package");
+        addLayer(relativePath.startsWith("scripts/") ? "ts-source" : "installed-target");
+        requirePolicy();
+    }
+    if (isPackageBoundaryPath(relativePath)) {
+        addSurface("package-boundary");
+        addLayer("package-runtime");
+        requirePolicy();
+    }
+    if (isMigrationPath(relativePath)) {
+        addSurface("migration-legacy");
+        if (relativePath.startsWith("scripts/"))
+            addLayer("ts-source");
+        requirePolicy();
+    }
+    if (isSkillReferenceDistributionPath(relativePath)) {
+        addSurface("skill-reference-distribution");
+        addLayer("installed-target");
+    }
+    if (isFixtureGoldenPath(relativePath)) {
+        addSurface("fixture-golden");
+        addLayer(relativePath.startsWith("examples/") ? "installed-target" : "not-runtime");
+    }
+    if (surfaces.length === 0) {
+        addSurface("unknown");
+        addLayer("not-runtime");
+    }
+    return {
+        surfaces: orderedUnique(surfaces, surfaceOrder),
+        runtimeLayers: orderedUnique(runtimeLayers, runtimeLayerOrder),
+        compatibilityPolicyRequired,
+        requiredGates: orderedUnique(requiredGates, gateOrder),
+    };
+}
+function buildCompatibilityRequirements(file) {
+    if (!file.compatibilityPolicyRequired)
+        return [];
+    const policySurfaces = file.surfaces.filter((surface) => surfaceRequiresCompatibilityPolicy(surface));
+    const surfaces = policySurfaces.length > 0 ? policySurfaces : file.surfaces;
+    return surfaces.map((surface) => ({
+        path: file.path,
+        surface,
+        allowedPolicies: compatibilityPolicies,
+        reason: compatibilityReason(surface),
+    }));
+}
+function buildUnknownSurface(file) {
+    if (!file.surfaces.includes("unknown"))
+        return [];
+    return [
+        {
+            path: file.path,
+            status: file.status,
+            reason: "No public impact surface matched this repository-relative path.",
+        },
+    ];
+}
+function surfacesForGate(surfaces, gate) {
+    if ((gate === "temp-project-cli-smoke" || gate === "status-json-contract") && surfaces.includes("ts-runtime")) {
+        return ["ts-runtime", ...surfaces.filter((surface) => surface !== "ts-runtime" && surfaceGateMap[surface].includes(gate))];
+    }
+    return surfaces.filter((surface) => surfaceGateMap[surface].includes(gate));
+}
+function surfaceRequiresCompatibilityPolicy(surface) {
+    return [
+        "ts-runtime",
+        "dashboard-data",
+        "template-schema",
+        "preset-package",
+        "package-boundary",
+        "migration-legacy",
+        "ci-pr-evidence",
+    ].includes(surface);
+}
+function compatibilityReason(surface) {
+    switch (surface) {
+        case "ts-runtime":
+            return "CLI output, exit code, or machine-readable report contract may change.";
+        case "dashboard-data":
+            return "Dashboard data JSON or public manifest contract may change.";
+        case "template-schema":
+            return "Task schema, template frontmatter, or target-project layout may change.";
+        case "preset-package":
+            return "Preset registry, installed resources, or action contract may change.";
+        case "package-boundary":
+            return "Package file list or installed runtime layout may change.";
+        case "migration-legacy":
+            return "Migration or legacy adoption behavior may change.";
+        case "ci-pr-evidence":
+            return "PR evidence or workflow contract may change.";
+        default:
+            return "Contract-changing surface requires explicit compatibility policy.";
+    }
+}
+function normalizeChangedPath(inputPath) {
+    const normalized = inputPath.trim().replaceAll("\\", "/").replace(/\/+/g, "/");
+    if (normalized === ".")
+        return "";
+    return normalized.startsWith("./") ? normalized.slice(2) : normalized;
+}
+function isRepositoryRelativePath(relativePath) {
+    return relativePath.length > 0 && !relativePath.startsWith("/") && !relativePath.startsWith("../") && !path.isAbsolute(relativePath);
+}
+function isPrivateLocalOnlyPath(relativePath) {
+    return (relativePath === "AGENTS.md" ||
+        relativePath === "CLAUDE.md" ||
+        relativePath === "docs" ||
+        relativePath.startsWith("docs/") ||
+        relativePath === ".harness-private" ||
+        relativePath.startsWith(".harness-private/"));
+}
+function isTypeIslandPath(relativePath) {
+    return relativePath.startsWith("scripts/lib/types/") || /^tests\/helpers\/.*types.*\.(mts|ts)$/.test(relativePath);
+}
+function isTsRuntimePath(relativePath) {
+    return relativePath.startsWith("scripts/") && relativePath.endsWith(".mts");
+}
+function isCliContractPath(relativePath) {
+    return (relativePath === "scripts/harness.mts" ||
+        relativePath.startsWith("scripts/commands/") ||
+        relativePath === "scripts/lib/types/impact.ts" ||
+        relativePath === "scripts/lib/types/task-lifecycle.ts" ||
+        relativePath === "scripts/lib/check-profiles.mts" ||
+        relativePath === "scripts/lib/status-builder.mts" ||
+        relativePath === "scripts/lib/task-index.mts" ||
+        relativePath === "scripts/lib/task-lifecycle.mts");
+}
+function isRuntimeBuildPath(relativePath) {
+    return (relativePath === "scripts/build-dist.mts" ||
+        relativePath === "scripts/check-runtime-emit.mts" ||
+        relativePath === "scripts/check-dist-observation.mts" ||
+        /^tsconfig(?:\.[A-Za-z-]+)?\.json$/.test(relativePath) ||
+        relativePath.startsWith("dist/"));
+}
+function isBuiltTestRunnerPath(relativePath) {
+    return relativePath === "scripts/run-built-tests.mts" || relativePath === "tests/run-all.mts" || relativePath === "tsconfig.tests.json" || /^tests\/.*\.mts$/.test(relativePath);
+}
+function isDashboardDataPath(relativePath) {
+    return (relativePath === "scripts/lib/dashboard-data.mts" ||
+        relativePath === "scripts/lib/check-profiles.mts" ||
+        relativePath === "scripts/lib/status-builder.mts" ||
+        relativePath === "scripts/lib/status-dashboard-renderer.mts" ||
+        relativePath === "scripts/lib/task-scanner.mts" ||
+        relativePath === "scripts/lib/task-review-model.mts" ||
+        relativePath === "scripts/lib/task-index.mts" ||
+        relativePath === "scripts/lib/types/check-profiles.ts" ||
+        relativePath === "scripts/lib/types/task-scanner.ts" ||
+        relativePath === "scripts/lib/types/impact.ts" ||
+        relativePath.startsWith("tests/golden/dashboard/"));
+}
+function isRootContributorDoc(relativePath) {
+    return /^README(\.[A-Za-z-]+)?\.md$/.test(relativePath) || relativePath === "CONTRIBUTING.md" || relativePath === "CHANGELOG.md";
+}
+function isPackageBoundaryPath(relativePath) {
+    return (relativePath === "package.json" ||
+        relativePath === "package-lock.json" ||
+        relativePath === "postinstall.mjs" ||
+        relativePath === "run-dist.mjs" ||
+        relativePath === "LICENSE" ||
+        relativePath === "LICENSE-EXCEPTION.md");
+}
+function isPresetPackagePath(relativePath) {
+    return (relativePath.startsWith("presets/") ||
+        relativePath === "scripts/commands/preset-command.mts" ||
+        relativePath === "scripts/lib/core-shared.mts" ||
+        relativePath === "scripts/lib/types/preset.ts" ||
+        /^scripts\/lib\/preset-.*\.mts$/.test(relativePath));
+}
+function isMigrationPath(relativePath) {
+    return relativePath.includes("migration") || relativePath.includes("legacy") || relativePath.includes("hard-cutover");
+}
+function isSkillReferenceDistributionPath(relativePath) {
+    return relativePath === "SKILL.md" || relativePath.startsWith("skills/") || relativePath.startsWith("references/");
+}
+function isFixtureGoldenPath(relativePath) {
+    return (relativePath.startsWith("examples/") ||
+        relativePath.startsWith("fixtures/") ||
+        relativePath.startsWith("tests/fixtures/") ||
+        relativePath.startsWith("tests/golden/"));
+}
+function orderedUnique(values, order) {
+    const present = new Set(values);
+    const ordered = order.filter((value) => present.has(value));
+    const orderSet = new Set(order);
+    const extra = values.filter((value, index) => !orderSet.has(value) && values.indexOf(value) === index);
+    return [...ordered, ...extra];
+}

package/dist/lib/lesson-maintenance.mjs

@@ -1,4 +1,3 @@
-// @ts-nocheck
 import fs from "node:fs";
 import path from "node:path";
 import { datePrefix, lessonCandidatesFile, normalizeTarget, readFileSafe, slug, toPosix, } from "./core-shared.mjs";
@@ -64,7 +63,7 @@ export function promoteLessonCandidate(targetInput, taskId, candidateId, { dryRu
     try {
         fs.mkdirSync(path.dirname(detailPath), { recursive: true });
         if (!fs.existsSync(detailPath))
-            fs.writeFileSync(detailPath, renderLessonDetail({ lessonId, candidate: row, task, detailRelative }));
+            fs.writeFileSync(detailPath, renderLessonDetail({ lessonId, candidate: row, task }));
         fs.writeFileSync(candidatePath, markCandidatePromoted(candidateContent, row.id, lessonId));
         const commit = commitGovernanceSync(governanceContext, [
             detailRelative,

package/dist/lib/markdown-utils.mjs

@@ -1,4 +1,3 @@
-// @ts-nocheck
 import { sanitizeText, slug } from "./core-shared.mjs";
 export function markdownTableRows(content) {
     return content
@@ -89,6 +88,56 @@ export function tableAfterHeading(content, headerPattern) {
     }
     return { header, rows: body };
 }
+export function stripFencedCodeBlocks(content) {
+    const lines = String(content || "").split(/\r?\n/);
+    const result = [];
+    let fence = "";
+    for (const line of lines) {
+        const match = line.match(/^\s{0,3}(```|~~~)/);
+        if (match) {
+            if (!fence)
+                fence = match[1];
+            else if (match[1] === fence)
+                fence = "";
+            continue;
+        }
+        if (!fence)
+            result.push(line);
+    }
+    return result.join("\n");
+}
+export function removeHeadingSectionOutsideFences(content, headingPattern) {
+    const lines = String(content || "").split(/\r?\n/);
+    let fence = "";
+    let start = -1;
+    let end = lines.length;
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        const fenceMatch = line.match(/^\s{0,3}(```|~~~)/);
+        if (fenceMatch) {
+            if (!fence)
+                fence = fenceMatch[1];
+            else if (fenceMatch[1] === fence)
+                fence = "";
+            continue;
+        }
+        if (fence)
+            continue;
+        if (start < 0 && headingPattern.test(line.trim())) {
+            start = index;
+            if (start > 0 && !lines[start - 1].trim())
+                start -= 1;
+            continue;
+        }
+        if (start >= 0 && index > start && /^##\s+/.test(line.trim())) {
+            end = index;
+            break;
+        }
+    }
+    if (start < 0)
+        return String(content || "");
+    return [...lines.slice(0, start), ...lines.slice(end)].join("\n");
+}
 export function getColumn(header, name) {
     return header.findIndex((cell) => cell.toLowerCase() === name.toLowerCase());
 }

package/dist/lib/migration-planner.mjs

@@ -1,4 +1,3 @@
-// @ts-nocheck
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -22,7 +21,8 @@ export function buildMigrationPlan(targetInput, { limit = 20 } = {}) {
     const legacyActions = [];
     const legacyResiduals = [];
     const warningGroups = new Map();
-    const tasksByShortId = new Map(status.tasks.map((task) => [task.shortId, task]));
+    const tasks = status.tasks;
+    const tasksByShortId = new Map(tasks.map((task) => [task.shortId, task]));
     function addTaskAction(taskId, actionPath, fileName, actionText) {
         const existing = taskActionsByTask.get(taskId) || {
             taskId,
@@ -85,7 +85,7 @@ export function buildMigrationPlan(targetInput, { limit = 20 } = {}) {
     const legacyVisualOnlyTasks = [];
     const unknownClassificationTasks = [];
     const weakBriefTasks = [];
-    for (const task of status.tasks) {
+    for (const task of tasks) {
         if (task.visualMapStatus === "legacy-only") {
             legacyVisualOnlyTasks.push({
                 taskId: task.shortId,
@@ -133,7 +133,7 @@ export function buildMigrationPlan(targetInput, { limit = 20 } = {}) {
     const recommendedCapabilities = recommendedMigrationCapabilities(status, target, registry);
     const missingExecutionStrategy = taskActions.filter((action) => action.files.includes("execution_strategy.md")).length;
     const missingVisualMap = taskActions.filter((action) => action.files.includes(visualMapFile)).length;
-    const cutoverCounters = taskCutoverCounters(status.tasks);
+    const cutoverCounters = taskCutoverCounters(tasks);
     const visualMapActions = taskActions.filter((action) => action.files.includes(visualMapFile)).length;
     const fullCutoverEligible = status.checkState.status === "pass" &&
         taskActions.length === 0 &&
@@ -177,7 +177,7 @@ export function buildMigrationPlan(targetInput, { limit = 20 } = {}) {
             fullCutoverEligible,
         },
         recommendedCapabilities,
-        phases: migrationPhases({ locale, recommendedCapabilities }),
+        phases: migrationPhases({ locale, recommendedCapabilities: recommendedCapabilities.map((capability) => ({ ...capability, state: "recommended" })) }),
         taskActions: taskActions.slice(0, limit),
         visualMapActions: taskActions.filter((action) => action.files.includes(visualMapFile)).slice(0, limit),
         legacyVisualOnlyTasks: legacyVisualOnlyTasks.slice(0, limit),
@@ -229,6 +229,7 @@ export function runMigration(targetInput, options = {}) {
     const strictStatus = buildStatus(targetInput, { strict: true, strictLegacy: true, allowLegacyTarget: true });
     const finalPlan = buildMigrationPlan(targetInput, { limit: options.limit || 50 });
     const afterGit = inspectGitStatus(target.projectRoot);
+    const finalTarget = normalizeTarget(targetInput);
     const strictDeferred = strictDeferredFromStatus(strictStatus);
     const result = options.planOnly
         ? "plan-only"
@@ -251,7 +252,7 @@ export function runMigration(targetInput, options = {}) {
             source: options.locale ? "explicit" : localeProbe.mixedLanguageDetected ? "assumed-from-probe" : "probe",
             probe: localeProbe,
         },
-        capabilities: readCapabilityRegistry(target).capabilities,
+        capabilities: readCapabilityRegistry(finalTarget).capabilities,
         baseline: {
             statusPath: path.join(sessionDir, "baseline-status.json"),
             migratePlanPath: path.join(sessionDir, "migrate-plan.json"),
@@ -289,7 +290,7 @@ export function runMigration(targetInput, options = {}) {
     return { ...session, sessionPath, reportPath };
 }
 export function verifyMigrationSession(sessionPathInput, { fullCutover = false } = {}) {
-    const sessionPath = path.resolve(sessionPathInput || "");
+    const sessionPath = path.resolve(String(sessionPathInput || ""));
     if (!sessionPath || !fs.existsSync(sessionPath)) {
         return { operation: "migrate-verify", status: "fail", failures: [`session file not found: ${sessionPathInput}`], warnings: [] };
     }
@@ -298,7 +299,7 @@ export function verifyMigrationSession(sessionPathInput, { fullCutover = false }
     let readError = null;
     const session = readJsonSafe(sessionPath, null, { onError: (error) => { readError = error; } });
     if (!session)
-        return { operation: "migrate-verify", status: "fail", failures: [`invalid session json: ${readError?.message || "unknown parse error"}`], warnings };
+        return { operation: "migrate-verify", status: "fail", failures: [`invalid session json: ${errorMessage(readError)}`], warnings };
     if (session.operation !== "migrate-run")
         failures.push("session operation is not migrate-run");
     if (session.schemaVersion !== 1 && session.version !== 1)
@@ -395,19 +396,23 @@ export function verifyMigrationSession(sessionPathInput, { fullCutover = false }
         else {
             try {
                 const dashboardBundle = JSON.parse(dataMatch[1]);
+                const dashboardStatus = asRecord(dashboardBundle.status);
+                const dashboardProject = asRecord(dashboardStatus.project);
+                const dashboardCheckState = dashboardStatus.checkState;
+                const dashboardAdoption = asRecord(dashboardBundle.adoption);
                 const expectedProjectName = session.target ? path.basename(session.target) : "";
-                if (dashboardBundle.status?.schemaVersion !== 2)
+                if (dashboardStatus.schemaVersion !== 2)
                     failures.push("dashboard bundle missing status schemaVersion 2");
-                if (expectedProjectName && dashboardBundle.status?.project?.name !== expectedProjectName) {
-                    failures.push(`dashboard bundle project ${dashboardBundle.status?.project?.name || "(none)"} does not match target ${expectedProjectName}`);
+                if (expectedProjectName && dashboardProject.name !== expectedProjectName) {
+                    failures.push(`dashboard bundle project ${dashboardProject.name || "(none)"} does not match target ${expectedProjectName}`);
                 }
-                if (!dashboardBundle.status?.checkState)
+                if (!dashboardCheckState)
                     failures.push("dashboard bundle missing checkState");
-                if (!Array.isArray(dashboardBundle.adoption?.warnings))
+                if (!Array.isArray(dashboardAdoption.warnings))
                     failures.push("dashboard bundle missing adoption warnings array");
             }
             catch (error) {
-                failures.push(`dashboard-data.js contains invalid dashboard JSON: ${error.message}`);
+                failures.push(`dashboard-data.js contains invalid dashboard JSON: ${errorMessage(error)}`);
             }
         }
     }
@@ -422,8 +427,9 @@ export function verifyMigrationSession(sessionPathInput, { fullCutover = false }
             warnings.push(`strict cutover deferred: ${deferred.failureCount} failures`);
         }
     }
-    if (fullCutover)
-        validateFullCutoverSession(session, failures);
+    if (fullCutover) {
+        validateFullCutoverSession({ ...session, dashboard: session.dashboard || undefined }, failures);
+    }
     return {
         operation: "migrate-verify",
         status: failures.length ? "fail" : "pass",
@@ -437,3 +443,12 @@ export function verifyMigrationSession(sessionPathInput, { fullCutover = false }
         warnings,
     };
 }
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asRecord(value) {
+    return isRecord(value) ? value : {};
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : "unknown parse error";
+}

package/dist/lib/migration-support.mjs

@@ -1,4 +1,3 @@
-// @ts-nocheck
 // Migration support scans dynamic target state until migration session domain types are modeled.
 import fs from "node:fs";
 import os from "node:os";
@@ -68,11 +67,12 @@ export function ensureSessionDir(projectName, requestedDir = "") {
     return base;
 }
 export function statusCheckSummary(status) {
+    const legacy = status.checkState.legacy;
     return {
         status: status.checkState.status,
         failures: status.checkState.failures,
         warnings: status.checkState.warnings,
-        legacyStatus: status.checkState.legacy?.status || "skipped",
+        legacyStatus: legacy?.status || "skipped",
         failureDetails: status.checkState.details.failures,
         warningDetails: status.checkState.details.warnings,
     };
@@ -162,8 +162,9 @@ export function validateFullCutoverSession(session, failures) {
     }
     if (summary.fullCutoverEligible !== true)
         failures.push("full cutover requires summary.fullCutoverEligible=true");
-    if ((summary.recommendedCapabilities || []).length) {
-        failures.push(`full cutover has recommended capabilities: ${summary.recommendedCapabilities.join(", ")}`);
+    const recommendedCapabilities = summary.recommendedCapabilities || [];
+    if (recommendedCapabilities.length) {
+        failures.push(`full cutover has recommended capabilities: ${recommendedCapabilities.join(", ")}`);
     }
     if (!session.target || !fs.existsSync(session.target))
         return;