@msn-control/liftoff 0.6.2 → 0.8.0

package/dist/commands.js

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { cp, lstat, mkdir, mkdtemp, readFile, readdir, readlink, rm, stat } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
@@ -9,8 +9,8 @@ import { getCodingAgent, getFrameworkDefinition, getSpecWorkflow, listRegions, p
 import { probeCodeAppsPlugin } from './code-apps-plugin.js';
 import { initializeFramework } from './framework-adapters.js';
 import { validateFrameworkInstallation } from './framework-validation.js';
-import { artifactPath, applyProjectFileTransaction, assertNewOrEmptyDirectory, captureProjectFileSnapshot, findProjectRoot, loadManifest, manifestDisplayPath, resolveProjectPath, validateGeneratedProject, writeArtifacts, writeProjectFile } from './file-system.js';
-import { InteractiveCancelledError, InteractivePrompter, isInteractiveTerminal } from './interactive.js';
+import { artifactPath, applyProjectFileTransaction, assertNewOrEmptyDirectory, captureProjectFileSnapshot, findProjectRoot, loadManifest, manifestHadFilteredLegacySeedOwnership, manifestDisplayPath, resolveProjectPath, validateGeneratedProject, writeArtifacts, writeProjectFile } from './file-system.js';
+import { InteractiveCancelledError, InteractivePrompter } from './interactive.js';
 import { applyMergePreflight, assertSafeInitTarget, authorizeMergePreflight, buildMergePreflight, captureTreeState, discoverGitRoot, resolveInitTargetFromDiscovery, validateStagedTree, withStagingArea, writeStagedArtifacts } from './init-filesystem.js';
 import { renderMigrationChecklist, renderMigrationProposal, renderMigrationTasks, seedMigrationGroups } from './migrate-plan.js';
 import { buildProjectPlan, loadConfigOptions, mergeOptions, PlanValidationError, projectPlanEntries } from './planner.js';
@@ -19,15 +19,19 @@ import { formatCommand, NodeCommandRunner } from './process-runner.js';
 import { scanDefaults, scanLegacyProject } from './scan.js';
 import { hasDrift, reconcileProject } from './reconcile.js';
 import { compareSemver } from './semver.js';
+import { checkConfiguredRegistryTarget, runSelfUpgrade, selfUpgradeExitCode, selfUpgradeRemedy, selfUpgradeSummary } from './self-upgrade.js';
+import { canonicalManualInstallCommand, canonicalNpmRegistry, } from './package-identity.js';
+import { lookupStableRelease } from './stable-release.js';
+import { supportedStack } from './supported-stack.js';
 import { buildArtifacts, buildManifest, partitionGeneratedArtifacts } from './templates.js';
 import { PresentationSession } from './terminal.js';
-import { buildUpdateImpact } from './update-impact.js';
 import { liftoffVersion } from './version.js';
 import { blockingReadinessFailures, detectHostEnvironment, installRequirement, probeWorkstation, selectLiftoffRuntimeRequirements, selectWorkstationRequirements } from './workstation.js';
 export async function runCommand(parsed, context) {
     const helpRequested = parsed.command !== undefined && readBooleanFlag(parsed.flags, 'help') === true;
     const jsonMode = !helpRequested && (parsed.command === 'doctor' ||
         parsed.command === 'update' ||
+        parsed.command === 'upgrade' ||
         parsed.command === 'validate') &&
         readBooleanFlag(parsed.flags, 'json') === true;
     const presentation = new PresentationSession({
@@ -70,6 +74,8 @@ export async function runCommand(parsed, context) {
                 return await validateCommand(parsed, executionContext);
             case 'update':
                 return await updateCommand(parsed, executionContext);
+            case 'upgrade':
+                return await upgradeCommand(parsed, executionContext);
             case 'migrate':
                 return await migrateCommand(parsed, executionContext);
             case 'doctor':
@@ -199,7 +205,10 @@ async function initCommand(parsed, context) {
         presentation.bullets('Configured integrations', [
             `${plan.specWorkflow.label} ${plan.framework.version}`,
             ...plan.agents.map((agent) => `${agent.label}${plan.defaultAgent?.id === agent.id ? ' (default)' : ''}`),
-            ...readiness.pluginProbes.map((probe) => `Code Apps plugin for ${probe.agent.label}: ${probe.state}`)
+            ...readiness.pluginProbes.map((probe) => `Code Apps plugin for ${probe.agent.label}: ${probe.state}`),
+            plan.governanceProfile.id === 'none'
+                ? 'Repository governance: disabled'
+                : `Repository governance: ${plan.governanceProfile.label} policy ${plan.governanceProfile.policyVersion}; local handoff generated, live activation deferred`
         ]);
         if (readiness.deferred.length > 0) {
             presentation.bullets('Deferred advisory checks', readiness.deferred);
@@ -210,7 +219,13 @@ async function initCommand(parsed, context) {
         presentation.completion(`Initialized ${plan.projectName}`, target.root, [
             { label: 'Target', value: target.root },
             { label: 'Spec workflow', value: plan.specWorkflow.label },
-            { label: 'Coding agents', value: plan.agents.map((agent) => agent.label).join(', ') }
+            { label: 'Coding agents', value: plan.agents.map((agent) => agent.label).join(', ') },
+            {
+                label: 'Repository governance',
+                value: plan.governanceProfile.id === 'none'
+                    ? 'Disabled'
+                    : 'Handoff generated; commit and push before read-only Phase 0'
+            }
         ], `liftoff validate ${JSON.stringify(target.root)}`);
         return 0;
     }
@@ -376,7 +391,7 @@ async function handleProjectDependencies(plan, projectRoot, options, probes, con
     if (plan.workload === 'power-apps-code-app') {
         const issues = await verifyPowerAppsPackageMetadata(projectRoot);
         if (issues.length > 0) {
-            presentation.error('Power Apps dependency installation blocked', `${issues.join(' ')} Restore package.json and package-lock.json or run \`liftoff update --apply\`.`);
+            presentation.error('Power Apps dependency installation blocked', `${issues.join(' ')} Restore package.json and package-lock.json or run \`liftoff update\`.`);
             return { success: false, deferred: [] };
         }
     }
@@ -809,71 +824,54 @@ async function preflightUpdate(projectRoot, entries, force) {
 function updateSnapshotKey(pathParts) {
     return pathParts.join('\0');
 }
-function reconciliationSignature(entries) {
-    return JSON.stringify(entries.map((entry) => ({
-        logicalName: entry.logicalName,
-        status: entry.status,
-        pathParts: entry.pathParts,
-        previousPathParts: entry.previousPathParts,
-        reason: entry.reason,
-        cleanMove: entry.cleanMove,
-        sourceModified: entry.sourceModified,
-        destinationOccupied: entry.destinationOccupied,
-        refreshHash: entry.refreshHash,
-        destinationMatches: entry.destinationMatches
-    })));
-}
-async function captureInteractiveUpdateSnapshots(projectRoot, entries, inputSnapshots) {
-    const snapshots = new Map(inputSnapshots.map((snapshot) => [updateSnapshotKey(snapshot.pathParts), snapshot]));
-    for (const entry of entries) {
-        const actionable = entry.status !== 'orphan' &&
-            (entry.status !== 'unchanged' || entry.refreshHash === true);
-        if (!actionable) {
-            continue;
-        }
-        for (const pathParts of [entry.pathParts, entry.previousPathParts]) {
-            if (!pathParts) {
-                continue;
-            }
-            const key = updateSnapshotKey(pathParts);
-            if (!snapshots.has(key)) {
-                snapshots.set(key, await captureProjectFileSnapshot(projectRoot, pathParts));
-            }
+async function captureUpdateSnapshots(projectRoot, manifest, render, initialSnapshots) {
+    const snapshots = new Map(initialSnapshots.map((snapshot) => [updateSnapshotKey(snapshot.pathParts), snapshot]));
+    const seenKeys = new Set(snapshots.keys());
+    const candidates = [
+        ...manifest.artifacts.map((artifact) => artifact.pathParts),
+        ...render
+            .filter((artifact) => artifact.category !== 'seed' && artifact.category !== 'framework')
+            .map((artifact) => artifact.pathParts)
+    ];
+    const uncaptured = [];
+    for (const pathParts of candidates) {
+        const key = updateSnapshotKey(pathParts);
+        if (!seenKeys.has(key)) {
+            seenKeys.add(key);
+            uncaptured.push(pathParts);
         }
     }
-    return snapshots;
+    for (const snapshot of await Promise.all(uncaptured.map((pathParts) => captureProjectFileSnapshot(projectRoot, pathParts)))) {
+        snapshots.set(updateSnapshotKey(snapshot.pathParts), snapshot);
+    }
+    return [...snapshots.values()];
 }
-function authorizedInteractiveSnapshotKeys(entries, force) {
-    const keys = new Set([
+function selectUpdatePreconditions(snapshots, entries, mutations) {
+    const requiredKeys = new Set([
         updateSnapshotKey(['liftoff.config.json']),
-        updateSnapshotKey(['liftoff.manifest.json'])
+        ...mutations.map((mutation) => updateSnapshotKey(mutation.pathParts))
     ]);
     for (const entry of entries) {
-        const authorized = entry.status === 'new' ||
-            entry.status === 'missing' ||
-            entry.status === 'upgrade' ||
-            entry.status === 'unchanged' && entry.refreshHash === true ||
-            entry.status === 'moved' && (entry.cleanMove === true || force) ||
-            entry.status === 'conflict' && force;
-        if (!authorized) {
+        const adoptsExistingDestination = entry.status === 'moved' && entry.destinationMatches === true;
+        if (!(entry.status === 'unchanged' && entry.refreshHash) &&
+            !adoptsExistingDestination) {
             continue;
         }
-        keys.add(updateSnapshotKey(entry.pathParts));
+        requiredKeys.add(updateSnapshotKey(entry.pathParts));
         if (entry.previousPathParts) {
-            keys.add(updateSnapshotKey(entry.previousPathParts));
+            requiredKeys.add(updateSnapshotKey(entry.previousPathParts));
         }
     }
-    return keys;
+    return snapshots.filter((snapshot) => requiredKeys.has(updateSnapshotKey(snapshot.pathParts)));
 }
 async function updateCommand(parsed, context) {
     const { presentation } = context;
-    let apply = readBooleanFlag(parsed.flags, 'apply') ?? false;
-    let force = readBooleanFlag(parsed.flags, 'force') ?? false;
+    const check = readBooleanFlag(parsed.flags, 'check') ?? false;
+    const force = readBooleanFlag(parsed.flags, 'force') ?? false;
     const jsonMode = readBooleanFlag(parsed.flags, 'json') ?? false;
-    let dirtyWorktreeWarningShown = false;
     presentation.commandIdentity('update', 'Reconcile the project with current Liftoff templates');
-    if (force && !apply) {
-        presentation.error('--force requires --apply.', 'Run `liftoff update --apply --force` only after reviewing the reported conflicts.');
+    if (force && check) {
+        presentation.error('--force cannot be combined with --check.', 'Run `liftoff update --check` to inspect drift or `liftoff update --force` to overwrite conflicts.');
         return 1;
     }
     const explicit = parsed.positional[0] ?? readStringFlag(parsed.flags, 'project');
@@ -882,15 +880,12 @@ async function updateCommand(parsed, context) {
         presentation.error(`No liftoff.manifest.json found in ${context.cwd} or any parent directory.`, 'Run this command inside a Liftoff project or provide its path explicitly.');
         return 1;
     }
-    const interactiveReview = !apply &&
-        !jsonMode &&
-        isInteractiveTerminal(context.stdin, context.stdout);
-    const interactiveInputSnapshots = interactiveReview
-        ? await Promise.all([
+    const initialUpdateSnapshots = check
+        ? []
+        : await Promise.all([
             captureProjectFileSnapshot(projectRoot, ['liftoff.manifest.json']),
             captureProjectFileSnapshot(projectRoot, ['liftoff.config.json'])
-        ])
-        : [];
+        ]);
     const manifest = await loadManifest(projectRoot);
     if (compareSemver(manifest.liftoffVersion, liftoffVersion) > 0) {
         presentation.error(`This project was written by Liftoff ${manifest.liftoffVersion}, which is newer than this CLI (${liftoffVersion}).`, 'Upgrade the CLI first.');
@@ -909,10 +904,13 @@ async function updateCommand(parsed, context) {
     }
     if (plan.workload === 'power-apps-code-app' && recordedWorkload.kind === 'power-apps-code-app') {
         const recordedStarter = recordedWorkload.starter;
-        if (plan.starter.repository !== recordedStarter.repository ||
-            plan.starter.path !== recordedStarter.path ||
-            plan.starter.commit !== recordedStarter.commit) {
-            presentation.error('The Power Apps starter repository, path, or commit differs from the recorded immutable source.', 'Restore the recorded source identity or initialize a fresh project.');
+        const starterBaseline = supportedStack.upstreams['power-apps-code-app'];
+        if (plan.starter.repository !== starterBaseline.repository ||
+            plan.starter.path !== starterBaseline.path ||
+            recordedStarter.repository !== starterBaseline.repository ||
+            recordedStarter.path !== starterBaseline.path ||
+            !starterBaseline.compatibleSourceCommits.includes(recordedStarter.commit)) {
+            presentation.error('The Power Apps starter repository, path, or commit is not represented by this Liftoff release catalog.', 'Restore the recorded source identity or use a Liftoff version that catalogs the transition.');
             return 1;
         }
     }
@@ -939,14 +937,60 @@ async function updateCommand(parsed, context) {
         presentation.error('AI agent or default-agent changes require official framework initialization and are not supported by liftoff update.', 'Restore liftoff.config.json to the integrations recorded in liftoff.manifest.json.');
         return 1;
     }
-    const render = buildArtifacts(plan);
+    const renderPlan = manifest.framework.state === 'legacy'
+        ? { ...plan, agents: [], defaultAgent: undefined }
+        : plan;
+    const render = buildArtifacts(renderPlan);
+    const updateSnapshots = check
+        ? []
+        : await captureUpdateSnapshots(projectRoot, manifest, render, initialUpdateSnapshots);
     const entries = await reconcileProject(manifest, render, projectRoot);
     const summary = summarizeEntries(entries);
-    const drift = hasDrift(entries);
+    const manifestUpgradePending = manifest.artifactVersion !== 5;
+    const starterUpgradePending = plan.workload === 'power-apps-code-app' &&
+        recordedWorkload.kind === 'power-apps-code-app' &&
+        recordedWorkload.starter.commit !== plan.starter.commit;
+    const nonDurableNames = new Set(render
+        .filter((artifact) => artifact.category === 'seed' || artifact.category === 'framework')
+        .map((artifact) => artifact.logicalName));
+    const manifestOwnershipCleanupPending = manifest.artifacts.some((artifact) => nonDurableNames.has(artifact.logicalName)) || manifestHadFilteredLegacySeedOwnership(manifest);
+    const manifestRewritePending = manifestUpgradePending ||
+        manifestOwnershipCleanupPending ||
+        starterUpgradePending;
+    const drift = hasDrift(entries) || manifestRewritePending;
     const visible = entries.filter((entry) => entry.status !== 'unchanged' || entry.refreshHash);
-    const impact = buildUpdateImpact(entries);
-    let interactiveSnapshots;
-    if (!apply) {
+    if (!drift) {
+        if (jsonMode) {
+            presentation.rawStdout(`${JSON.stringify(check ? {
+                schemaVersion: 1,
+                mode: 'check',
+                cliVersion: liftoffVersion,
+                projectVersion: manifest.liftoffVersion,
+                entries: [],
+                manifestUpgradePending,
+                manifestOwnershipCleanupPending,
+                summary
+            } : {
+                schemaVersion: 1,
+                mode: 'apply',
+                cliVersion: liftoffVersion,
+                projectVersion: manifest.liftoffVersion,
+                written: [],
+                skipped: [],
+                manifestUpgradePending,
+                manifestOwnershipCleanupPending,
+                summary
+            }, null, 2)}\n`);
+            return 0;
+        }
+        presentation.definitions('Project versions', [
+            { label: 'Liftoff CLI', value: liftoffVersion },
+            { label: 'Project generated by', value: manifest.liftoffVersion }
+        ]);
+        presentation.status('success', 'No drift', `${summary.unchanged} artifacts match the current templates and configuration`);
+        return 0;
+    }
+    if (check) {
         if (jsonMode) {
             presentation.rawStdout(`${JSON.stringify({
                 schemaVersion: 1,
@@ -960,80 +1004,59 @@ async function updateCommand(parsed, context) {
                     previousPath: entry.previousPathParts ? manifestDisplayPath(entry.previousPathParts) : undefined,
                     reason: entry.reason
                 })),
+                manifestUpgradePending,
+                manifestOwnershipCleanupPending,
                 summary
             }, null, 2)}\n`);
-            return drift ? 2 : 0;
+            return 2;
         }
         presentation.definitions('Project versions', [
             { label: 'Liftoff CLI', value: liftoffVersion },
             { label: 'Project generated by', value: manifest.liftoffVersion }
         ]);
-        if (!drift) {
-            presentation.status('success', 'No drift', `${summary.unchanged} artifacts match the current templates and configuration`);
-            return 0;
-        }
-        if (presentation.stdout.layout === 'plain') {
-            presentation.section('Template drift', visible.map((entry) => `${entryMarker(entry)} ${entryDisplay(entry)}  ${entry.reason}`));
-        }
-        else {
-            presentation.table('Template drift', ['Change', 'Artifact', 'Reason'], visible.map((entry) => [entryMarker(entry), entryDisplay(entry), entry.reason]));
-        }
-        const toWrite = summary.new + summary.missing + summary.upgrade + summary.moved + summary.refresh;
-        presentation.status('warning', 'Drift detected', `${toWrite} to write, ${summary.conflict} conflict(s), ${summary.orphan} orphan(s), ${summary.unchanged} unchanged`);
-        if (!impact.hasActionableChanges ||
-            !interactiveReview) {
-            if (impact.hasActionableChanges) {
-                presentation.command('liftoff update --apply');
-            }
-            return 2;
-        }
-        if (isDirtyGitWorktree(projectRoot)) {
-            presentation.warning('The project worktree has uncommitted changes; commit or back up local work before accepting an update.');
-            dirtyWorktreeWarningShown = true;
-        }
-        interactiveSnapshots = await captureInteractiveUpdateSnapshots(projectRoot, entries, interactiveInputSnapshots);
-        const reviewedEntries = await reconcileProject(manifest, render, projectRoot);
-        if (reconciliationSignature(reviewedEntries) !== reconciliationSignature(entries)) {
-            presentation.error('The project changed while Liftoff prepared the update.', 'Run `liftoff update` again to review the current state.');
-            return 1;
-        }
-        const prompter = new InteractivePrompter({
-            input: context.stdin,
-            output: context.stdout,
-            presentation,
-            cwd: projectRoot
-        });
-        try {
-            prompter.presentUpdateImpact(impact);
-            if (impact.hasSafeActions) {
-                const safeAccepted = await prompter.confirmSafeUpdate(impact.safeActionCount);
-                if (!safeAccepted) {
-                    presentation.cancellation('Update declined; no project files were changed.');
-                    return 2;
-                }
+        if (visible.length > 0) {
+            if (presentation.stdout.layout === 'plain') {
+                presentation.section('Template drift', visible.map((entry) => `${entryMarker(entry)} ${entryDisplay(entry)}  ${entry.reason}`));
             }
-            if (impact.conflicts.length > 0) {
-                force = await prompter.confirmConflictOverwrite(impact.conflicts, impact.managedPathsRemovedOnOverwrite);
-                if (!impact.hasSafeActions && !force) {
-                    presentation.cancellation('Update declined; no project files were changed.');
-                    return 2;
-                }
+            else {
+                presentation.table('Template drift', ['Change', 'Artifact', 'Reason'], visible.map((entry) => [entryMarker(entry), entryDisplay(entry), entry.reason]));
             }
-            apply = true;
         }
-        catch (error) {
-            if (error instanceof InteractiveCancelledError) {
-                presentation.cancellation('Update stopped before authorization; no project files were changed.');
-                return 0;
-            }
-            throw error;
+        const manifestMaintenance = [
+            manifestUpgradePending ? 'upgrade liftoff.manifest.json to schema v5' : undefined,
+            manifestOwnershipCleanupPending
+                ? 'remove obsolete seed or framework entries from durable manifest ownership'
+                : undefined,
+            starterUpgradePending
+                ? `record the current packaged Power Apps starter ${plan.starter.commit}`
+                : undefined
+        ].filter((item) => item !== undefined);
+        if (manifestMaintenance.length > 0) {
+            presentation.bullets('Manifest maintenance', manifestMaintenance);
+        }
+        const toWrite = summary.new +
+            summary.missing +
+            summary.upgrade +
+            summary.moved +
+            summary.refresh +
+            (manifestRewritePending ? 1 : 0);
+        presentation.status('warning', 'Drift detected', `${toWrite} to write, ${summary.conflict} conflict(s), ${summary.orphan} orphan(s), ${summary.unchanged} unchanged`);
+        if (toWrite > 0) {
+            presentation.command('liftoff update');
         }
-        finally {
-            prompter.close();
+        if (summary.conflict > 0) {
+            presentation.command('liftoff update --force');
         }
+        return 2;
     }
-    if (!dirtyWorktreeWarningShown && isDirtyGitWorktree(projectRoot)) {
-        presentation.warning('The project worktree has uncommitted changes; consider committing before applying.');
+    if (isDirtyGitWorktree(projectRoot)) {
+        const warning = 'The project worktree has uncommitted changes; consider committing before applying.';
+        if (jsonMode) {
+            presentation.rawStderr(`Warning: ${warning}\n`);
+        }
+        else {
+            presentation.warning(warning);
+        }
     }
     presentation.stage('Apply safe template changes', projectRoot);
     await preflightUpdate(projectRoot, entries, force);
@@ -1090,6 +1113,9 @@ async function updateCommand(parsed, context) {
     }
     const oldByName = new Map(manifest.artifacts.map((artifact) => [artifact.logicalName, artifact]));
     const skippedByName = new Map(skipped.map((entry) => [entry.logicalName, entry]));
+    const hasUnrecordedGovernanceConflict = skipped.some((entry) => entry.status === 'conflict' &&
+        entry.rendered?.category === 'governance' &&
+        !oldByName.has(entry.logicalName));
     const nextManifest = buildManifest(plan, render.filter((artifact) => artifact.logicalName !== 'manifest'), { frameworkState: manifest.framework.state });
     nextManifest.framework = manifest.framework;
     nextManifest.project.specWorkflow = manifest.project.specWorkflow;
@@ -1100,6 +1126,10 @@ async function updateCommand(parsed, context) {
     else {
         delete nextManifest.project.defaultAgent;
     }
+    if (hasUnrecordedGovernanceConflict &&
+        nextManifest.governance.profile !== 'none') {
+        nextManifest.governance.state = 'handoff-partial';
+    }
     nextManifest.artifacts = nextManifest.artifacts.flatMap((artifact) => {
         // config is user-owned after create: carry the recorded entry forward untouched
         if (artifact.logicalName === 'liftoff-config') {
@@ -1116,7 +1146,12 @@ async function updateCommand(parsed, context) {
     });
     for (const entry of entries) {
         if (entry.status === 'orphan') {
-            nextManifest.artifacts.push(oldByName.get(entry.logicalName));
+            const previous = oldByName.get(entry.logicalName);
+            if (plan.governanceProfile.id === 'none' &&
+                previous.category === 'governance') {
+                continue;
+            }
+            nextManifest.artifacts.push(previous);
         }
     }
     mutations.push({
@@ -1124,14 +1159,8 @@ async function updateCommand(parsed, context) {
         pathParts: ['liftoff.manifest.json'],
         content: `${JSON.stringify(nextManifest, null, 2)}\n`
     });
-    const authorizedSnapshotKeys = interactiveSnapshots
-        ? authorizedInteractiveSnapshotKeys(entries, force)
-        : undefined;
-    const transactionPreconditions = interactiveSnapshots && authorizedSnapshotKeys
-        ? [...interactiveSnapshots.values()].filter((snapshot) => authorizedSnapshotKeys.has(updateSnapshotKey(snapshot.pathParts)))
-        : undefined;
     await applyProjectFileTransaction(projectRoot, mutations, {
-        ...(transactionPreconditions ? { preconditions: transactionPreconditions } : {})
+        preconditions: selectUpdatePreconditions(updateSnapshots, entries, mutations)
     });
     if (jsonMode) {
         presentation.rawStdout(`${JSON.stringify({
@@ -1141,6 +1170,8 @@ async function updateCommand(parsed, context) {
             projectVersion: manifest.liftoffVersion,
             written: written.map((entry) => manifestDisplayPath(entry.pathParts)),
             skipped: skipped.map((entry) => ({ path: manifestDisplayPath(entry.pathParts), reason: entry.reason })),
+            manifestUpgradePending,
+            manifestOwnershipCleanupPending,
             summary
         }, null, 2)}\n`);
         return 0;
@@ -1149,7 +1180,7 @@ async function updateCommand(parsed, context) {
         presentation.bullets('Applied changes', written.map((entry) => `wrote ${entryDisplay(entry)}`));
     }
     if (skipped.length > 0) {
-        presentation.bullets('Skipped conflicts', skipped.map((entry) => `skipped ${entryDisplay(entry)}  ${entry.reason}${force ? '' : ' (use --apply --force to overwrite)'}`));
+        presentation.bullets('Skipped conflicts', skipped.map((entry) => `skipped ${entryDisplay(entry)}  ${entry.reason}${force ? '' : ' (use --force to overwrite)'}`));
     }
     const orphans = entries.filter((entry) => entry.status === 'orphan');
     if (orphans.length > 0) {
@@ -1158,6 +1189,85 @@ async function updateCommand(parsed, context) {
     presentation.completion('Updated project', `${written.length} written, ${skipped.length} skipped, ${summary.orphan} orphan(s)`, [{ label: 'Manifest version', value: liftoffVersion }], 'liftoff validate && liftoff doctor');
     return 0;
 }
+function renderSelfUpgradeResult(value, presentation) {
+    const details = [
+        { label: 'Current CLI', value: value.currentVersion },
+        ...('targetVersion' in value && value.targetVersion
+            ? [{ label: 'Canonical target', value: value.targetVersion }]
+            : []),
+        ...('registryKind' in value && value.registryKind
+            ? [{ label: 'Delivery registry', value: value.registryKind }]
+            : [])
+    ];
+    presentation.definitions('CLI upgrade result', details);
+    switch (value.status) {
+        case 'current':
+            presentation.status('success', 'CLI is current', selfUpgradeSummary(value));
+            return;
+        case 'update-available':
+            presentation.status('warning', 'CLI update available', selfUpgradeSummary(value));
+            presentation.command('liftoff upgrade');
+            return;
+        case 'upgraded':
+            presentation.completion('Liftoff CLI upgraded', selfUpgradeSummary(value), [{ label: 'Installed version', value: value.targetVersion }], 'liftoff update --check');
+            return;
+        case 'blocked':
+        case 'failed': {
+            presentation.status(value.status === 'blocked' ? 'warning' : 'error', value.status === 'blocked' ? 'CLI upgrade blocked' : 'CLI upgrade failed', selfUpgradeSummary(value));
+            const remedy = selfUpgradeRemedy(value);
+            if (remedy) {
+                presentation.remedy(remedy);
+            }
+            return;
+        }
+        default: {
+            const exhaustive = value;
+            throw new Error(`Unhandled self-upgrade result: ${String(exhaustive)}`);
+        }
+    }
+}
+async function upgradeCommand(parsed, context) {
+    const mode = readBooleanFlag(parsed.flags, 'check') === true ? 'check' : 'apply';
+    const json = readBooleanFlag(parsed.flags, 'json') === true;
+    if (!json) {
+        context.presentation.commandIdentity('upgrade', 'Replace the supported global Liftoff CLI installation');
+    }
+    const execute = context.selfUpgrade ?? ((request) => runSelfUpgrade(request, {
+        environment: context.env ?? process.env
+    }));
+    let value;
+    try {
+        value = await execute({
+            mode,
+            currentVersion: liftoffVersion,
+            stdout: context.stdout,
+            stderr: context.stderr,
+            json,
+            ...(!json
+                ? {
+                    onStage: (stage, detail) => context.presentation.stage(stage, detail),
+                    onInstallCommand: (command) => context.presentation.command(formatCommand(command))
+                }
+                : {})
+        });
+    }
+    catch {
+        value = {
+            schemaVersion: 1,
+            mode,
+            status: 'failed',
+            currentVersion: liftoffVersion,
+            reasonCode: 'verification_failed'
+        };
+    }
+    if (json) {
+        context.presentation.rawStdout(`${JSON.stringify(value, null, 2)}\n`);
+    }
+    else {
+        renderSelfUpgradeResult(value, context.presentation);
+    }
+    return selfUpgradeExitCode(value);
+}
 function versionedBinaryCheck(label, command, args, minimum, remedy) {
     const result = spawnSync(command, args, { encoding: 'utf8' });
     if (result.status !== 0) {
@@ -1175,6 +1285,9 @@ function versionedBinaryCheck(label, command, args, minimum, remedy) {
     return { label, severity: 'ok', detail: output };
 }
 function pythonRuntime() {
+    const [major, minor] = (supportedStack.runtimes.python.minimumVersion ??
+        supportedStack.runtimes.python.version).split('.');
+    const minimum = [Number(major), Number(minor)];
     const candidates = process.platform === 'win32'
         ? [
             { command: 'py', versionArgs: ['-3', '--version'], commandArgs: ['-3'] },
@@ -1185,7 +1298,7 @@ function pythonRuntime() {
             { command: 'python3', versionArgs: ['--version'], commandArgs: [] },
             { command: 'python', versionArgs: ['--version'], commandArgs: [] }
         ];
-    return candidates.find((candidate) => versionedBinaryCheck('python', candidate.command, candidate.versionArgs, [3, 12], 'install Python 3.12 or newer').severity === 'ok') ?? candidates.find((candidate) => binaryPresent(candidate.command));
+    return candidates.find((candidate) => versionedBinaryCheck('python', candidate.command, candidate.versionArgs, minimum, `install Python ${major}.${minor} or newer`).severity === 'ok') ?? candidates.find((candidate) => binaryPresent(candidate.command));
 }
 function doctorCheckFromProbe(probe) {
     const severity = probe.state === 'ready'
@@ -1309,6 +1422,34 @@ async function frameworkDoctorChecks(projectRoot, manifest) {
     ];
 }
 function stackProjectCheck(projectRoot, apiStack) {
+    const requiredMetadata = {
+        'python-fastapi': ['backend/pyproject.toml', 'backend/uv.lock'],
+        'node-fastify': ['backend/package.json', 'backend/package-lock.json'],
+        'go-huma': ['backend/go.mod', 'backend/go.sum']
+    };
+    const missingMetadata = requiredMetadata[apiStack].find((relativePath) => !existsSync(path.join(projectRoot, ...relativePath.split('/'))));
+    if (missingMetadata) {
+        return {
+            label: `${apiStack} project`,
+            severity: 'fail',
+            detail: `missing locked dependency metadata: ${missingMetadata}`,
+            remedy: `restore ${missingMetadata} or run liftoff update`
+        };
+    }
+    if (apiStack === 'python-fastapi') {
+        const pyproject = readFileSync(path.join(projectRoot, 'backend', 'pyproject.toml'), 'utf8');
+        const lock = readFileSync(path.join(projectRoot, 'backend', 'uv.lock'), 'utf8');
+        const projectName = pyproject.match(/^\s*name\s*=\s*"([^"]+)"/m)?.[1];
+        const lockedProjectName = lock.match(/\[\[package\]\]\s+name\s*=\s*"([^"]+)"\s+version\s*=\s*"[^"]+"\s+source\s*=\s*\{\s*editable\s*=\s*"\."\s*\}/m)?.[1];
+        if (!projectName || lockedProjectName !== projectName) {
+            return {
+                label: `${apiStack} project`,
+                severity: 'fail',
+                detail: 'pyproject.toml and uv.lock do not identify the same project',
+                remedy: 'restore backend/pyproject.toml and backend/uv.lock or run liftoff update'
+            };
+        }
+    }
     let result;
     switch (apiStack) {
         case 'python-fastapi':
@@ -1357,7 +1498,7 @@ async function powerAppsProjectCheck(projectRoot) {
         severity: 'fail',
         state: 'unhealthy',
         detail: issues[0],
-        remedy: 'restore package.json and package-lock.json or run liftoff update --apply'
+        remedy: 'restore package.json and package-lock.json or run liftoff update'
     };
 }
 function runReadOnly(command, args, cwd) {
@@ -1388,39 +1529,37 @@ async function cloudLayer(cloud, runner) {
         : [{ label: cloud, severity: 'skipped', detail: `${cloud} provider checks are not available yet` }];
     return { title: `Cloud - ${cloud}`, checks };
 }
-async function lookupLatestPublishedVersion() {
-    const registry = process.env.LIFTOFF_REGISTRY ?? 'https://registry.npmjs.org';
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), 2000);
-    try {
-        const response = await fetch(`${registry}/@msn-control%2fliftoff/latest`, { signal: controller.signal });
-        if (!response.ok) {
-            return undefined;
-        }
-        const data = (await response.json());
-        return data.version;
-    }
-    catch {
-        return undefined; // offline or unreachable: doctor stays quiet about freshness
-    }
-    finally {
-        clearTimeout(timer);
-    }
-}
-async function cliLayer() {
+async function cliLayer(releaseLookup, configuredRegistryLookup) {
     const checks = [
         { label: 'version', severity: 'ok', detail: `Liftoff ${liftoffVersion}` }
     ];
-    const latest = await lookupLatestPublishedVersion();
-    if (!latest) {
+    let latest;
+    try {
+        latest = (await releaseLookup()).version;
+    }
+    catch {
         return { title: 'CLI', checks };
     }
     if (compareSemver(latest, liftoffVersion) > 0) {
+        let registryState = {
+            status: 'unavailable'
+        };
+        try {
+            registryState = await configuredRegistryLookup(latest);
+        }
+        catch {
+            // Canonical freshness remains useful when local npm registry inspection fails.
+        }
+        const manual = canonicalManualInstallCommand(latest);
         checks.push({
             label: 'cli freshness',
             severity: 'warn',
-            detail: `Liftoff ${latest} is published, this CLI is ${liftoffVersion}`,
-            remedy: `install Liftoff ${latest} from an approved registry that exposes it; where direct public npm access is permitted: npm install -g @msn-control/liftoff@${latest} --registry=https://registry.npmjs.org`
+            detail: registryState.status === 'stale'
+                ? `Liftoff ${latest} is published, but the configured npm registry does not expose it`
+                : `Liftoff ${latest} is published, this CLI is ${liftoffVersion}`,
+            remedy: registryState.status === 'stale'
+                ? 'ask the managed registry owner to synchronize the canonical target, then run liftoff upgrade --check'
+                : `run liftoff upgrade --check, then liftoff upgrade; manual fallback where canonical npm is permitted: ${manual}`
         });
     }
     else {
@@ -1440,7 +1579,7 @@ async function projectLayer(projectRoot, manifest) {
             label: 'manifest',
             severity: 'fail',
             detail: `${issues.length} issue(s): ${issues[0]}${issues.length > 1 ? ' ...' : ''}`,
-            remedy: 'restore missing artifacts or run liftoff update --apply'
+            remedy: 'restore missing artifacts or run liftoff update'
         });
     }
     else {
@@ -1451,12 +1590,53 @@ async function projectLayer(projectRoot, manifest) {
             label: 'version',
             severity: 'warn',
             detail: `project written by Liftoff ${manifest.liftoffVersion}, CLI is ${liftoffVersion}`,
-            remedy: 'upgrade the CLI: npm install -g @msn-control/liftoff@latest'
+            remedy: `run liftoff upgrade --check, then liftoff upgrade; manual fallback: ${canonicalManualInstallCommand(manifest.liftoffVersion)}`
         });
     }
     else {
         checks.push({ label: 'version', severity: 'ok', detail: `generated by ${manifest.liftoffVersion}, CLI ${liftoffVersion}` });
     }
+    if (manifest.governance.profile === 'unspecified') {
+        checks.push({
+            id: 'repository-governance',
+            label: 'repository governance',
+            severity: 'warn',
+            state: 'not-observable',
+            detail: 'manifest predates local governance handoff state',
+            remedy: 'run liftoff update --check to inspect default handoff adoption'
+        });
+    }
+    else if (manifest.governance.profile === 'none') {
+        checks.push({
+            id: 'repository-governance',
+            label: 'repository governance',
+            severity: 'ok',
+            state: 'disabled',
+            detail: 'disabled; no local handoff or live-enforcement claim'
+        });
+    }
+    else {
+        const governanceIssue = issues.find((issue) => /governance|repository-governance/i.test(issue));
+        const partialHandoff = manifest.governance.state === 'handoff-partial';
+        const severity = governanceIssue ? 'fail' : partialHandoff ? 'warn' : 'ok';
+        const detail = governanceIssue ??
+            (partialHandoff
+                ? `local ${manifest.governance.profile} policy ${manifest.governance.policyVersion} handoff is incomplete; one or more exact destinations remain outside Liftoff ownership`
+                : `local ${manifest.governance.profile} policy ${manifest.governance.policyVersion} handoff is intact; live enforcement is not inferred`);
+        const remedy = governanceIssue
+            ? 'inspect with liftoff update --check; run liftoff update for safe repairs or use --force only after reviewing exact conflicts; neither activates GitHub governance'
+            : partialHandoff
+                ? 'inspect liftoff update --check; use liftoff update --force only after reviewing each governance conflict'
+                : undefined;
+        checks.push({
+            id: 'repository-governance',
+            label: 'repository governance',
+            severity,
+            state: governanceIssue ? 'unhealthy' : manifest.governance.state,
+            detail,
+            ...(remedy ? { remedy } : {})
+        });
+    }
     checks.push(...await frameworkDoctorChecks(projectRoot, manifest));
     if (manifest.project.workload.kind === 'power-apps-code-app') {
         const starter = manifest.project.workload.starter;
@@ -1614,6 +1794,7 @@ async function doctorCommand(parsed, context) {
     const cloudOverride = readStringFlag(parsed.flags, 'cloud');
     const layers = [];
     context.presentation.commandIdentity('doctor', 'Inspect CLI, workstation, project, runtime, and cloud readiness');
+    const runner = context.runner ?? new NodeCommandRunner();
     const projectRoot = await findProjectRoot(context.cwd);
     let manifest;
     let manifestError;
@@ -1625,8 +1806,17 @@ async function doctorCommand(parsed, context) {
             manifestError = error;
         }
     }
-    layers.push(await cliLayer());
-    const runner = context.runner ?? new NodeCommandRunner();
+    const releaseLookup = context.stableReleaseLookup ?? (() => lookupStableRelease({
+        registry: context.env?.LIFTOFF_REGISTRY ??
+            process.env.LIFTOFF_REGISTRY ??
+            canonicalNpmRegistry
+    }));
+    const configuredRegistryLookup = context.configuredRegistryTargetLookup ??
+        ((targetVersion) => checkConfiguredRegistryTarget(targetVersion, {
+            runner,
+            environment: context.env ?? process.env
+        }));
+    layers.push(await cliLayer(releaseLookup, configuredRegistryLookup));
     const requirements = manifest
         ? selectWorkstationRequirements(workstationSelectionFromManifest(manifest), { includeFramework: manifest.framework.state === 'initialized' })
         : selectLiftoffRuntimeRequirements();
@@ -1749,6 +1939,7 @@ async function optionsFromParsedArgs(parsed, cwd, includeProjectName) {
         agents: readListFlag(parsed.flags, 'agents'),
         defaultAgent: readStringFlag(parsed.flags, 'default-agent'),
         codeAppsPlugin: readBooleanFlag(parsed.flags, 'code-apps-plugin'),
+        governanceProfile: readStringFlag(parsed.flags, 'governance'),
         configPath,
         yes: readBooleanFlag(parsed.flags, 'yes') ?? false,
         force: readBooleanFlag(parsed.flags, 'force'),
@@ -1777,6 +1968,7 @@ function hasMissingInitInputs(options) {
         projectType !== 'power-apps-code-app' && options.includeFrontend === undefined ||
         !options.specWorkflow ||
         !options.agents ||
+        !options.governanceProfile ||
         missingDefaultAgent ||
         projectType !== 'power-apps-code-app' && !options.environments;
 }