@open-agent-toolkit/cli 0.2.51 → 0.2.53

package/dist/commands/init/tools/index.js

@@ -3,19 +3,22 @@ import { buildCommandContext, } from '../../../app/command-context.js';
 import { copyDirWithStatus } from '../../init/tools/shared/copy-helpers.js';
 import { applyGitignore } from '../../local/apply.js';
 import { addLocalPaths } from '../../local/manage.js';
-import { removeAgentsMdSection, upsertAgentsMdSection, } from '../../shared/agents-md.js';
+import { formatAgentsMdGuidanceResult, formatAgentsMdMutationFailure, upsertAgentsMdSection, } from '../../shared/agents-md.js';
 import { withScopeOption } from '../../shared/scope-option.js';
-import { selectManyWithAbort, selectWithAbort, } from '../../shared/shared.prompts.js';
+import { confirmAction, selectManyWithAbort, selectWithAbort, } from '../../shared/shared.prompts.js';
 import { readGlobalOptions } from '../../shared/shared.utils.js';
 import { canonicalPathsForPacks, getInstalledCanonicalPaths, setInstalledCanonicalPaths, } from '../../tools/shared/install-sync-context.js';
+import { packScopeFactsFromInventory, projectPackEvidence, } from '../../tools/shared/pack-evidence.js';
 import { inventoryPack, } from '../../tools/shared/pack-inventory.js';
 import { reconcilePackLifecycles, } from '../../tools/shared/pack-lifecycle.js';
+import { evaluatePackLifecycleOutcome, resolveAdditivePackScopeSelection, } from '../../tools/shared/pack-lifecycle-outcome.js';
 import { getPackDefinition } from '../../tools/shared/pack-manifest.js';
 import { reconcileProjectToolsConfig } from '../../tools/shared/project-tools-config.js';
 import { scanTools } from '../../tools/shared/scan-tools.js';
 import { readOatConfig, resolveLocalPaths, writeOatConfig, } from '../../../config/oat-config.js';
 import { resolveAssetsRoot } from '../../../fs/assets.js';
 import { resolveProjectRoot, resolveScopeRoot } from '../../../fs/paths.js';
+import { adviseProviderRefresh, } from '../../../providers/shared/restart-adviser.js';
 import { Command } from 'commander';
 import { createInitToolsBrainstormCommand } from './brainstorm/index.js';
 import { installBrainstorm as defaultInstallBrainstorm, } from './brainstorm/install-brainstorm.js';
@@ -25,7 +28,8 @@ import { createInitToolsDocsCommand } from './docs/index.js';
 import { installDocs as defaultInstallDocs, } from './docs/install-docs.js';
 import { createInitToolsIdeasCommand } from './ideas/index.js';
 import { installIdeas as defaultInstallIdeas, } from './ideas/install-ideas.js';
-import { buildPackInstallStateMap, buildPackInstallStateMapFromInventory, } from './install-state.js';
+import { buildPackInstallStateMap, buildPackInstallStateMapFromEvidence, } from './install-state.js';
+import { commandProjectGuidanceChoice, planProjectGuidance, reportableProjectGuidance, withProjectGuidanceOptions, } from './project-guidance.js';
 import { createInitToolsProjectManagementCommand } from './project-management/index.js';
 import { installProjectManagement as defaultInstallProjectManagement, } from './project-management/install-project-management.js';
 import { createInitToolsResearchCommand } from './research/index.js';
@@ -50,6 +54,7 @@ const ALL_TOOL_PACKS = [
 ];
 let lastRunInitToolsMetadata = null;
 const appliedScopesByCommand = new WeakMap();
+const syncHandledByCommand = new WeakSet();
 const DEFAULT_DEPENDENCIES = {
     buildCommandContext,
     resolveProjectRoot,
@@ -58,6 +63,8 @@ const DEFAULT_DEPENDENCIES = {
     scanTools,
     selectManyWithAbort,
     selectWithAbort,
+    confirmAction,
+    planProjectGuidance,
     installCore: defaultInstallCore,
     installDocs: defaultInstallDocs,
     installIdeas: defaultInstallIdeas,
@@ -73,7 +80,6 @@ const DEFAULT_DEPENDENCIES = {
     writeOatConfig,
     resolveLocalPaths,
     upsertAgentsMdSection,
-    removeAgentsMdSection,
     reconcilePacks: reconcilePackLifecycles,
     inventoryPack,
 };
@@ -89,6 +95,24 @@ const USER_ELIGIBLE_PACKS = new Set([
 function isUserEligiblePack(pack) {
     return USER_ELIGIBLE_PACKS.has(pack);
 }
+async function loadPackEvidence(pack, projectRoot, userRoot, assetsRoot, inventory) {
+    const canonical = await inventory({
+        pack,
+        assetsRoot,
+        ...(projectRoot ? { projectRoot } : {}),
+        userRoot,
+    });
+    return projectPackEvidence({
+        canonical,
+        scopes: canonical.scopes.map(packScopeFactsFromInventory),
+    });
+}
+function assertVerifiedPackScopes(evidence, expected) {
+    if (evidence.unknownScopes.length > 0 ||
+        expected.some((scope) => !evidence.knownRealizedScopes.includes(scope))) {
+        throw new Error(`Pack ${evidence.pack} placement verification failed for ${expected.join(', ')} scope`);
+    }
+}
 /**
  * Concrete scopes implied by a desired end-state placement.
  */
@@ -167,7 +191,10 @@ async function loadInstalledPackStates(projectRoot, userRoot, assetsRoot, depend
             ...(projectRoot ? { projectRoot } : {}),
             userRoot,
         })));
-        return buildPackInstallStateMapFromInventory(ALL_TOOL_PACKS, inventories);
+        return buildPackInstallStateMapFromEvidence(ALL_TOOL_PACKS, inventories.map((canonical) => projectPackEvidence({
+            canonical,
+            scopes: canonical.scopes.map(packScopeFactsFromInventory),
+        })));
     }
     const [projectTools, userTools] = await Promise.all([
         projectRoot
@@ -249,6 +276,9 @@ export function consumeInitToolsRunMetadata() {
     lastRunInitToolsMetadata = null;
     return metadata;
 }
+export function wasInstallSyncHandled(command) {
+    return syncHandledByCommand.has(command);
+}
 /**
  * Resolve a possibly-deferred scope-selection signal into a concrete mode.
  *
@@ -389,12 +419,16 @@ function buildPackEndStateChoices(pack, currentLocation, defaultEndState) {
         {
             label: `Project scope (${pack})`,
             value: 'project',
-            description: 'Install at project scope only',
+            description: currentLocation === 'user' || currentLocation === 'both'
+                ? 'Add or refresh project scope; keep user scope'
+                : 'Install at project scope',
         },
         {
             label: `User scope (${pack})`,
             value: 'user',
-            description: 'Install at user scope only',
+            description: currentLocation === 'project' || currentLocation === 'both'
+                ? 'Add or refresh user scope; keep project scope'
+                : 'Install at user scope',
         },
         {
             label: `Project + user (${pack})`,
@@ -411,13 +445,31 @@ function buildPackEndStateChoices(pack, currentLocation, defaultEndState) {
     const rest = annotated.filter((choice) => choice.value !== defaultEndState);
     return defaultChoice ? [defaultChoice, ...rest] : annotated;
 }
-function reportSuccess(context, packs, syncScopes, adoptedPacks) {
+function reportSuccess(context, packs, syncScopes, adoptedPacks, lifecycle, projectGuidance) {
+    const providerVisibility = initProviderVisibility(syncScopes);
     if (context.json) {
+        if (projectGuidance.action === 'blocked' ||
+            projectGuidance.action === 'manual-required') {
+            context.logger.json({
+                status: 'partial',
+                installedPacks: packs,
+                syncScopes,
+                lifecycle: lifecycle.map(({ selection, status }) => ({
+                    pack: selection.pack,
+                    status,
+                })),
+                projectGuidance: reportableProjectGuidance(projectGuidance),
+            });
+            return;
+        }
         context.logger.json({
             status: 'ok',
             installedPacks: packs,
             syncScopes,
             ...(adoptedPacks.length > 0 ? { adoptedPacks } : {}),
+            lifecycle,
+            projectGuidance: reportableProjectGuidance(projectGuidance),
+            ...(providerVisibility ? { providerVisibility } : {}),
         });
         return;
     }
@@ -431,6 +483,117 @@ function reportSuccess(context, packs, syncScopes, adoptedPacks) {
     if (syncScopes.length === 0) {
         context.logger.info('No sync needed.');
     }
+    else if (providerVisibility) {
+        context.logger.info(`Provider catalog visibility: ${providerVisibility.state} — ${providerVisibility.reason}`);
+    }
+    for (const outcome of lifecycle) {
+        context.logger.info(`Lifecycle ${outcome.selection.pack}: ${outcome.status} (${outcome.canonical.status})`);
+    }
+    const guidanceMessage = `Project guidance: ${projectGuidance.action} — ${projectGuidance.reason}`;
+    if (projectGuidance.action === 'blocked' ||
+        projectGuidance.action === 'manual-required') {
+        context.logger.warn(guidanceMessage);
+        if (projectGuidance.manualPatch) {
+            for (const line of formatAgentsMdGuidanceResult({
+                action: 'manual-required',
+                manualPatch: projectGuidance.manualPatch,
+            })) {
+                context.logger.info(line);
+            }
+        }
+    }
+    else {
+        context.logger.info(guidanceMessage);
+    }
+}
+async function applyProjectGuidance(plan, dependencies) {
+    if (plan.action !== 'create' || !plan.repoRoot)
+        return plan;
+    try {
+        const sectionResult = await dependencies.upsertAgentsMdSection(plan.repoRoot, plan.sectionKey, plan.body, plan.legacySectionAction === 'remove'
+            ? { removeSectionKeys: ['workflows'] }
+            : undefined);
+        if (sectionResult.action === 'manual-required') {
+            return {
+                ...plan,
+                action: 'manual-required',
+                reason: 'Accepted project guidance requires the reported manual AGENTS.md patch. Capability placement and PJM adoption were unchanged.',
+                manualPatch: sectionResult.manualPatch,
+            };
+        }
+        if (sectionResult.action === 'blocked') {
+            return {
+                ...plan,
+                action: 'blocked',
+                reason: `Accepted project guidance was blocked: ${sectionResult.blocked?.reason ?? 'AGENTS.md could not be planned safely.'} ${sectionResult.blocked?.action ?? ''}`.trim(),
+            };
+        }
+        return {
+            ...plan,
+            action: sectionResult.action === 'created' ? 'create' : 'no-change',
+            reason: `Accepted project guidance ${sectionResult.action}. Capability placement and PJM adoption were unchanged.`,
+        };
+    }
+    catch (error) {
+        return {
+            ...plan,
+            action: 'blocked',
+            reason: `Accepted project guidance was blocked: ${formatAgentsMdMutationFailure(error)}`,
+        };
+    }
+}
+async function planAndApplyProjectGuidanceAfterInstall(context, assetsRoot, installedProjectRoot, explicitChoice, dependencies) {
+    const initialPlan = await dependencies.planProjectGuidance({
+        repoRoot: installedProjectRoot,
+        packs: [],
+        explicitChoice,
+        interactive: context.interactive,
+        confirmAction: dependencies.confirmAction,
+    });
+    if (initialPlan.choice.choice !== 'accepted')
+        return initialPlan;
+    try {
+        const repoRoot = installedProjectRoot ??
+            (await dependencies.resolveProjectRoot(context.cwd));
+        const userRoot = dependencies.resolveScopeRoot('user', context.cwd, context.home);
+        const finalPackStates = await loadInstalledPackStates(repoRoot, userRoot, assetsRoot, dependencies);
+        const realizedPacks = ALL_TOOL_PACKS.flatMap((pack) => {
+            const scope = finalPackStates[pack].location;
+            return scope === 'not-installed'
+                ? []
+                : [{ pack, scope }];
+        });
+        const completePlan = await dependencies.planProjectGuidance({
+            repoRoot,
+            packs: realizedPacks,
+            explicitChoice: true,
+            interactive: false,
+            confirmAction: dependencies.confirmAction,
+        });
+        return applyProjectGuidance(completePlan, dependencies);
+    }
+    catch (error) {
+        return {
+            ...initialPlan,
+            action: 'blocked',
+            reason: `Accepted project guidance was blocked: ${formatAgentsMdMutationFailure(error)}`,
+        };
+    }
+}
+function initProviderVisibility(syncScopes) {
+    if (syncScopes.length === 0)
+        return null;
+    return adviseProviderRefresh({
+        policy: {
+            state: 'unknown',
+            reason: 'Init does not select one provider/content refresh contract for the aggregate sync',
+        },
+        materialization: 'unknown',
+        observation: {
+            state: 'not-reported',
+            reference: 'oat init records provider sync completion but does not query any active provider catalog',
+        },
+    });
 }
 function reportOutdatedSkills(context, outdatedSkills) {
     if (outdatedSkills.length === 0) {
@@ -451,47 +614,12 @@ async function updateOutdatedSkills(outdatedSkills, assetsRoot, dependencies) {
     }
     return updatedNames;
 }
-const PACK_DESCRIPTIONS = {
-    core: 'Diagnostics and documentation (oat-doctor, oat-docs)',
-    docs: 'Documentation and instruction governance workflows',
-    workflows: 'Project lifecycle (create, discover, plan, implement, review, complete)',
-    ideas: 'Idea capture and refinement',
-    'project-management': 'Local backlog, roadmap, and reference doc management (oat-pjm-* skills)',
-    utility: 'Standalone utilities (skill authoring, maintainability review, code reviews)',
-    research: 'Research, analysis, verification, and synthesis',
-    brainstorm: 'Always-on brainstorming entry point with visual companion',
-};
-export function buildToolPacksSectionBody(packs) {
-    const userPacks = packs.filter((p) => p.scope === 'user' || p.scope === 'both');
-    const hasWorkflows = packs.some((p) => p.pack === 'workflows');
-    const lines = [
-        '## Tool Packs',
-        '',
-        '- **Skills directory:** `.agents/skills/`',
-        '- **Discover available skills:** scan `.agents/skills/*/SKILL.md`',
-        '- **Refresh provider views:** `oat sync --scope all`',
-        '- **Update skills to latest versions:** `oat tools update`',
-    ];
-    if (userPacks.length > 0) {
-        const userPackNames = userPacks.map((p) => p.pack).join(', ');
-        lines.push(`- **User-scoped skills:** \`~/.agents/skills/\` (${userPackNames} packs installed at user scope)`);
-    }
-    lines.push('', '### Installed Packs', '');
-    for (const { pack, scope } of packs) {
-        const suffix = scope === 'user'
-            ? ' _(user scope)_'
-            : scope === 'both'
-                ? ' _(project + user scope)_'
-                : '';
-        lines.push(`- **${pack}** — ${PACK_DESCRIPTIONS[pack]}${suffix}`);
-    }
-    if (hasWorkflows) {
-        lines.push('', '### Workflow Execution Continuation', '', '- This guidance applies only to OAT project lifecycle execution, such as `oat-project-implement`, and OAT project review/receive flows. It does not apply to non-OAT tasks or ad-hoc work outside the OAT project workflow.', '- When executing an OAT project implementation or OAT project review workflow, do not stop at task boundaries, phase boundaries, or other clean checkpoints unless the configured HiLL checkpoint has been reached, a real blocker exists, or explicit user input is required.', '- Status summaries, completed bookkeeping, and "clean boundary" pauses are not valid stop reasons. After updating tracking artifacts, continue execution until an allowed stop condition applies.');
-    }
-    return lines.join('\n');
-}
-export async function runInitTools(context, dependencies) {
+export { buildToolPacksSectionBody } from './project-guidance.js';
+export async function runInitTools(context, dependencies, explicitProjectGuidance) {
     lastRunInitToolsMetadata = null;
+    let attemptedPacks = [];
+    let attemptedSelections = [];
+    let lifecycleOutcomes = [];
     try {
         const userRoot = dependencies.resolveScopeRoot('user', context.cwd, context.home);
         const assetsRoot = await dependencies.resolveAssetsRoot();
@@ -518,11 +646,13 @@ export async function runInitTools(context, dependencies) {
         if (!context.interactive) {
             selectedPacks.push('project-management');
         }
+        attemptedPacks = selectedPacks;
         if (selectedPacks.length === 0) {
             lastRunInitToolsMetadata = {
                 affectedScopes: [],
                 appliedScopes: [],
                 adoptedPacks: [],
+                syncHandled: dependencies.syncAfterInstall !== undefined,
             };
             if (!context.json) {
                 context.logger.info('No tool packs selected.');
@@ -531,6 +661,12 @@ export async function runInitTools(context, dependencies) {
             return [];
         }
         const packScopes = await resolvePackScopes(context, selectedPacks, initialPackStates, dependencies);
+        attemptedSelections = selectedPacks.map((pack) => resolveAdditivePackScopeSelection({
+            pack,
+            requested: pack === 'core' ? 'user' : packScopes[pack],
+            knownRealizedScopes: scopesForLocation(initialPackStates[pack].location),
+            unknownScopes: [],
+        }));
         function scopeRoot(scope) {
             if (scope === 'user')
                 return userRoot;
@@ -565,6 +701,25 @@ export async function runInitTools(context, dependencies) {
                 if (plan.operations.length > 0)
                     affectedScopes.add(plan.scope);
             }
+            if (dependencies.inventoryPack) {
+                const finalEvidence = await Promise.all(selectedPacks.map((pack) => loadPackEvidence(pack, projectRoot, userRoot, assetsRoot, dependencies.inventoryPack)));
+                lifecycleOutcomes = finalEvidence.map((evidence) => {
+                    const packResults = lifecycle.filter(({ request }) => request.pack === evidence.pack);
+                    const selection = attemptedSelections.find(({ pack }) => pack === evidence.pack);
+                    return evaluatePackLifecycleOutcome({
+                        selection,
+                        lifecycle: packResults,
+                        sync: { scopes: [], status: 'not-run', providers: [] },
+                        finalEvidence: evidence,
+                    });
+                });
+                for (const evidence of finalEvidence) {
+                    const target = evidence.pack === 'core'
+                        ? ['user']
+                        : scopesForEndState(packScopes[evidence.pack]);
+                    assertVerifiedPackScopes(evidence, target);
+                }
+            }
             if (requests.some(({ pack, scope }) => pack === 'workflows' && scope === 'project')) {
                 const repoRoot = scopeRoot('project');
                 const existingConfig = await dependencies.readOatConfig(repoRoot);
@@ -828,20 +983,6 @@ export async function runInitTools(context, dependencies) {
             pack,
             scope: packScopes[pack],
         }));
-        const adoptsProject = packScopeInfo.some(({ scope }) => scope !== 'user');
-        const sectionBody = buildToolPacksSectionBody(packScopeInfo);
-        const sectionResult = adoptsProject
-            ? await dependencies.upsertAgentsMdSection(scopeRoot('project'), 'tools', sectionBody)
-            : { action: 'no-change' };
-        // Pack placement never writes the project-management or decisions AGENTS
-        // sections. Those belong to explicit repository adoption (`oat pjm init`,
-        // via `initializeRepoReference`), which owns the `pjm.initialized` marker.
-        if (adoptsProject) {
-            await dependencies.removeAgentsMdSection(scopeRoot('project'), 'workflows');
-        }
-        if (!context.json && sectionResult.action !== 'no-change') {
-            context.logger.info(`AGENTS.md tool packs section ${sectionResult.action}.`);
-        }
         const affectedScopesList = [...affectedScopes];
         const appliedScopes = [
             ...new Set(packScopeInfo.flatMap(({ scope }) => scopesForEndState(scope))),
@@ -853,20 +994,86 @@ export async function runInitTools(context, dependencies) {
                 home: context.home,
             }, dependencies)).adoptedPacks
             : [];
+        const finalPackStates = await loadInstalledPackStates(projectRoot, userRoot, assetsRoot, dependencies);
+        const realizedPacks = ALL_TOOL_PACKS.flatMap((pack) => {
+            const scope = finalPackStates[pack].location;
+            return scope === 'not-installed'
+                ? []
+                : [{ pack, scope }];
+        });
+        const plannedGuidance = await dependencies.planProjectGuidance({
+            repoRoot: projectRoot,
+            packs: realizedPacks,
+            explicitChoice: explicitProjectGuidance,
+            interactive: context.interactive,
+            confirmAction: dependencies.confirmAction,
+        });
+        const guidancePlan = await applyProjectGuidance(plannedGuidance, dependencies);
+        if (dependencies.syncAfterInstall) {
+            const sync = await dependencies.syncAfterInstall(affectedScopesList, context, canonicalPathsForPacks(selectedPacks));
+            lifecycleOutcomes = lifecycleOutcomes.map((outcome) => evaluatePackLifecycleOutcome({
+                selection: outcome.selection,
+                lifecycle: outcome.canonical.results,
+                sync: {
+                    scopes: sync.scopes.filter((scope) => outcome.selection.targetScopes.includes(scope)),
+                    status: sync.scopes.length === 0
+                        ? 'not-run'
+                        : sync.synced
+                            ? 'complete'
+                            : 'failed',
+                    providers: [],
+                    ...(sync.error ? { error: sync.error } : {}),
+                },
+                finalEvidence: outcome.finalEvidence,
+            }));
+        }
         lastRunInitToolsMetadata = {
             affectedScopes: affectedScopesList,
             appliedScopes,
             adoptedPacks,
+            syncHandled: dependencies.syncAfterInstall !== undefined,
         };
-        reportSuccess(context, packScopeInfo, affectedScopesList, adoptedPacks);
-        process.exitCode = 0;
+        reportSuccess(context, packScopeInfo, affectedScopesList, adoptedPacks, lifecycleOutcomes, guidancePlan);
+        process.exitCode =
+            lifecycleOutcomes.some(({ status }) => status !== 'complete') ||
+                guidancePlan.action === 'blocked' ||
+                guidancePlan.action === 'manual-required'
+                ? 1
+                : 0;
         return selectedPacks;
     }
     catch (error) {
         lastRunInitToolsMetadata = null;
         const message = error instanceof Error ? error.message : String(error);
         if (context.json) {
-            context.logger.json({ status: 'error', message });
+            context.logger.json({
+                status: 'error',
+                message,
+                ...(attemptedPacks.length > 0
+                    ? {
+                        lifecycle: lifecycleOutcomes.length > 0
+                            ? lifecycleOutcomes
+                            : attemptedPacks.map((pack) => ({
+                                schemaVersion: 1,
+                                selection: attemptedSelections.find((selection) => selection.pack === pack) ?? {
+                                    pack,
+                                    requested: 'user',
+                                    retainedRealizedScopes: [],
+                                    targetScopes: [],
+                                },
+                                canonical: { status: 'failed', results: [] },
+                                sync: {
+                                    scopes: [],
+                                    status: 'not-run',
+                                    providers: [],
+                                },
+                                finalEvidence: null,
+                                status: 'failed',
+                                recovery: [{ code: 'canonical-apply-failed', message }],
+                            })),
+                    }
+                    : {}),
+            });
         }
         else {
             context.logger.error(message);
@@ -875,8 +1082,8 @@ export async function runInitTools(context, dependencies) {
         return [];
     }
 }
-export async function runInitToolsWithDefaults(context) {
-    return runInitTools(context, { ...DEFAULT_DEPENDENCIES });
+export async function runInitToolsWithDefaults(context, explicitProjectGuidance) {
+    return runInitTools(context, { ...DEFAULT_DEPENDENCIES }, explicitProjectGuidance);
 }
 /**
  * Scopes a bare `oat tools install <pack>` (no explicit `--scope`) should
@@ -888,30 +1095,46 @@ export async function runInitToolsWithDefaults(context) {
  * `defaultScope`. Falls back to the configured default only when placement
  * cannot be observed (no inventory dependency, or an inventory failure).
  */
-async function resolvePackCommandScopes(pack, context, assetsRoot, dependencies) {
+async function resolvePackCommandSelection(pack, context, assetsRoot, dependencies, requested) {
     const definition = getPackDefinition(pack);
     const inventory = dependencies.inventoryPack;
-    if (!inventory)
-        return [definition.defaultScope];
-    try {
-        const userRoot = dependencies.resolveScopeRoot('user', context.cwd, context.home);
-        const projectRoot = definition.allowedScopes.includes('project')
-            ? await dependencies
-                .resolveProjectRoot(context.cwd)
-                .catch(() => undefined)
-            : undefined;
-        const packInventory = await inventory({
+    if (!inventory) {
+        const fallback = requested ?? definition.defaultScope;
+        const fallbackScopes = fallback === 'both' ? ['project', 'user'] : [fallback];
+        return {
             pack,
-            assetsRoot,
-            ...(projectRoot ? { projectRoot } : {}),
-            userRoot,
-        });
-        const states = buildPackInstallStateMapFromInventory([pack], [packInventory]);
-        return scopesForEndState(resolvePackDefaultEndState(pack, states[pack].location)).filter((scope) => definition.allowedScopes.includes(scope));
-    }
-    catch {
-        return [definition.defaultScope];
+            requested: fallback,
+            retainedRealizedScopes: [],
+            targetScopes: fallbackScopes.filter((scope) => definition.allowedScopes.includes(scope)),
+        };
     }
+    const userRoot = dependencies.resolveScopeRoot('user', context.cwd, context.home);
+    const projectRoot = definition.allowedScopes.includes('project')
+        ? await dependencies.resolveProjectRoot(context.cwd).catch(() => undefined)
+        : undefined;
+    const canonical = await inventory({
+        pack,
+        assetsRoot,
+        ...(projectRoot ? { projectRoot } : {}),
+        userRoot,
+    });
+    const evidence = projectPackEvidence({
+        canonical,
+        scopes: canonical.scopes.map(packScopeFactsFromInventory),
+    });
+    const defaultRequest = evidence.knownRealizedScopes.length === 2
+        ? 'both'
+        : (evidence.knownRealizedScopes[0] ?? definition.defaultScope);
+    const selection = resolveAdditivePackScopeSelection({
+        pack,
+        requested: requested ?? defaultRequest,
+        knownRealizedScopes: evidence.knownRealizedScopes,
+        unknownScopes: evidence.unknownScopes,
+    });
+    return {
+        ...selection,
+        targetScopes: selection.targetScopes.filter((scope) => definition.allowedScopes.includes(scope)),
+    };
 }
 function createReconciledPackCommand(pack, dependencies) {
     const definition = getPackDefinition(pack);
@@ -926,22 +1149,31 @@ function createReconciledPackCommand(pack, dependencies) {
         brainstorm: 'Install OAT brainstorm skill (always-on entry point with visual companion)',
     };
     const base = new Command(pack).description(descriptions[pack]);
-    const packCommand = pack === 'core' ? base : withScopeOption(base);
+    const scopedCommand = pack === 'core' ? base : withScopeOption(base);
+    const packCommand = pack === 'workflows'
+        ? withProjectGuidanceOptions(scopedCommand)
+        : scopedCommand;
     return packCommand
         .allowUnknownOption(false)
         .action(async (_options, command) => {
         const context = dependencies.buildCommandContext(readGlobalOptions(command));
+        let lifecycleOutcome = null;
+        let selection = null;
         try {
+            const explicitProjectGuidance = pack === 'workflows'
+                ? commandProjectGuidanceChoice(command)
+                : undefined;
             const assetsRoot = await dependencies.resolveAssetsRoot();
             const explicitScope = command.getOptionValueSourceWithGlobals('scope') === 'cli';
             const requestedScope = context.scope === 'project' || context.scope === 'user'
                 ? context.scope
                 : null;
-            const scopes = explicitScope && context.scope === 'all'
-                ? [...definition.allowedScopes]
-                : requestedScope
-                    ? [requestedScope]
-                    : await resolvePackCommandScopes(pack, context, assetsRoot, dependencies);
+            selection = await resolvePackCommandSelection(pack, context, assetsRoot, dependencies, explicitScope && context.scope === 'all'
+                ? 'both'
+                : explicitScope && requestedScope
+                    ? requestedScope
+                    : undefined);
+            const scopes = [...selection.targetScopes];
             for (const scope of scopes) {
                 if (!definition.allowedScopes.includes(scope)) {
                     throw new Error(`Pack ${pack} does not allow ${scope} scope`);
@@ -957,8 +1189,46 @@ function createReconciledPackCommand(pack, dependencies) {
                 action: 'install',
             })));
             const results = await dependencies.reconcilePacks(requests);
-            appliedScopesByCommand.set(command, results.map(({ request }) => request.scope));
+            let finalEvidence = null;
+            if (dependencies.inventoryPack) {
+                finalEvidence = await loadPackEvidence(pack, requests.some(({ scope }) => scope === 'project')
+                    ? await dependencies.resolveProjectRoot(context.cwd)
+                    : null, dependencies.resolveScopeRoot('user', context.cwd, context.home), assetsRoot, dependencies.inventoryPack);
+            }
+            lifecycleOutcome = evaluatePackLifecycleOutcome({
+                selection,
+                lifecycle: results,
+                sync: { scopes: [], status: 'not-run', providers: [] },
+                finalEvidence,
+            });
+            if (finalEvidence)
+                assertVerifiedPackScopes(finalEvidence, scopes);
+            appliedScopesByCommand.set(command, results
+                .filter(({ plan }) => plan.operations.length > 0)
+                .map(({ request }) => request.scope));
             setInstalledCanonicalPaths(command, canonicalPathsForPacks([pack]));
+            if (dependencies.syncAfterInstall) {
+                syncHandledByCommand.add(command);
+                const changedScopes = results
+                    .filter(({ plan }) => plan.operations.length > 0)
+                    .map(({ request }) => request.scope);
+                const sync = await dependencies.syncAfterInstall(changedScopes, context, canonicalPathsForPacks([pack]));
+                lifecycleOutcome = evaluatePackLifecycleOutcome({
+                    selection,
+                    lifecycle: results,
+                    sync: {
+                        scopes: sync.scopes,
+                        status: sync.scopes.length === 0
+                            ? 'not-run'
+                            : sync.synced
+                                ? 'complete'
+                                : 'failed',
+                        providers: [],
+                        ...(sync.error ? { error: sync.error } : {}),
+                    },
+                    finalEvidence,
+                });
+            }
             // Project-scope placement installs capability only. The
             // project-management and decisions AGENTS sections are written by the
             // explicit adoption action (`oat pjm init`), never by pack placement.
@@ -969,12 +1239,28 @@ function createReconciledPackCommand(pack, dependencies) {
                     home: context.home,
                 }, dependencies)).adoptedPacks
                 : [];
+            const providerVisibility = initProviderVisibility(results
+                .filter(({ plan }) => plan.operations.length > 0)
+                .map(({ request }) => request.scope));
+            const projectGuidance = pack === 'workflows'
+                ? await planAndApplyProjectGuidanceAfterInstall(context, assetsRoot, requests.find(({ scope }) => scope === 'project')?.scopeRoot ??
+                    null, explicitProjectGuidance, dependencies)
+                : null;
             if (context.json) {
+                const guidanceIncomplete = projectGuidance?.action === 'blocked' ||
+                    projectGuidance?.action === 'manual-required';
                 context.logger.json({
-                    status: 'ok',
+                    status: guidanceIncomplete ? 'partial' : 'ok',
                     pack,
                     scopes,
                     results,
+                    lifecycle: lifecycleOutcome,
+                    ...(projectGuidance
+                        ? {
+                            projectGuidance: reportableProjectGuidance(projectGuidance),
+                        }
+                        : {}),
+                    ...(providerVisibility ? { providerVisibility } : {}),
                     ...(adoptedPacks.length > 0 ? { adoptedPacks } : {}),
                 });
             }
@@ -983,6 +1269,28 @@ function createReconciledPackCommand(pack, dependencies) {
                     context.logger.info(`Adopted project tool pack: ${adoptedPack}`);
                 }
                 context.logger.info(`Installed ${pack} tool pack.`);
+                context.logger.info(`Lifecycle: ${lifecycleOutcome.status} (${lifecycleOutcome.canonical.status})`);
+                if (providerVisibility) {
+                    context.logger.info(`Provider catalog visibility: ${providerVisibility.state} — ${providerVisibility.reason}`);
+                }
+                if (projectGuidance) {
+                    const guidanceMessage = `Project guidance: ${projectGuidance.action} — ${projectGuidance.reason}`;
+                    if (projectGuidance.action === 'blocked' ||
+                        projectGuidance.action === 'manual-required') {
+                        context.logger.warn(guidanceMessage);
+                        if (projectGuidance.manualPatch) {
+                            for (const line of formatAgentsMdGuidanceResult({
+                                action: 'manual-required',
+                                manualPatch: projectGuidance.manualPatch,
+                            })) {
+                                context.logger.info(line);
+                            }
+                        }
+                    }
+                    else {
+                        context.logger.info(guidanceMessage);
+                    }
+                }
                 for (const result of results) {
                     context.logger.info(`Scope: ${result.request.scope}`);
                     context.logger.info(`Target root: ${result.request.scopeRoot}`);
@@ -990,12 +1298,35 @@ function createReconciledPackCommand(pack, dependencies) {
                     context.logger.info(`Run: oat sync --scope ${result.request.scope}`);
                 }
             }
-            process.exitCode = 0;
+            process.exitCode =
+                lifecycleOutcome.status === 'complete' &&
+                    projectGuidance?.action !== 'blocked' &&
+                    projectGuidance?.action !== 'manual-required'
+                    ? 0
+                    : 1;
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
+            lifecycleOutcome ??= {
+                schemaVersion: 1,
+                selection: selection ?? {
+                    pack,
+                    requested: 'user',
+                    retainedRealizedScopes: [],
+                    targetScopes: [],
+                },
+                canonical: { status: 'failed', results: [] },
+                sync: { scopes: [], status: 'not-run', providers: [] },
+                finalEvidence: null,
+                status: 'failed',
+                recovery: [{ code: 'canonical-apply-failed', message }],
+            };
             if (context.json)
-                context.logger.json({ status: 'error', message });
+                context.logger.json({
+                    status: 'error',
+                    message,
+                    lifecycle: lifecycleOutcome,
+                });
             else
                 context.logger.error(message);
             process.exitCode = 1;
@@ -1079,13 +1410,13 @@ export function createInitToolsCommand(overrides = {}) {
             });
         }
     }
-    const command = new Command('tools').description('Install OAT tool packs (core, ideas, docs, workflows, utility, project-management, research, brainstorm)');
+    const command = withProjectGuidanceOptions(new Command('tools').description('Install OAT tool packs (core, ideas, docs, workflows, utility, project-management, research, brainstorm)'));
     for (const packCommand of packCommands) {
         command.addCommand(packCommand);
     }
     command.action(async (_options, actionCommand) => {
         const context = dependencies.buildCommandContext(readGlobalOptions(actionCommand));
-        const selectedPacks = await runInitTools(context, dependencies);
+        const selectedPacks = await runInitTools(context, dependencies, commandProjectGuidanceChoice(actionCommand));
         appliedScopesByCommand.set(actionCommand, lastRunInitToolsMetadata?.appliedScopes ?? []);
         setInstalledCanonicalPaths(actionCommand, canonicalPathsForPacks(selectedPacks));
     });