@aiwg/cli 2026.10.5 → 2026.10.7

package/dist/src/cli/handlers/setup.js

@@ -1,13 +1,29 @@
 import { boundedSpawnSync } from '../../process/bounded-child-process.mjs';
+import { helperEnvironment, HELPER_ENV_ALLOWLIST } from '../../process/cli-command.mjs';
+import { readPrivateValueFile } from '../../auth/sensitive-input.js';
+import { setupJev } from '../../decision/driver.js';
 import { existsSync } from 'fs';
 import { emptyConfig, FORCE_PUSH_POLICY_ALIAS_NOTE, normalizeForcePushPolicy as normalizeForcePushPolicyShared, getConfigPath, getProjectDir, readAiwgConfig, resolveRemoteProvider, VALID_PROVIDERS, writeAiwgConfig, } from '../../config/aiwg-config.js';
 import { AiwgError, EXIT_CODES } from '../errors.js';
-import { askChoice, askConsent, askString, askYesNo, createPromptInterface } from '../prompt-utils.js';
+import { askChoice, askConsent, askString, askYesNo, createPromptInterface, createSecretPromptInterface } from '../prompt-utils.js';
 import * as ui from '../ui.js';
+import { join } from 'node:path';
+import { validateJevOptions } from './guided-setup.js';
+import { validateParallelismConfig } from '../../config/aiwg-config.js';
+import { readFile } from 'node:fs/promises';
+import { discoverInventory } from '../../discovery/index.js';
+import { applyGuidedPlan, configPathFor, credentialReferenceFor, defaultPlanReviewIO, projectRootForWorkspace, renderHumanReview, reviewGuidedPlan, } from '../../discovery/plan-apply.js';
+import { readSetupPlan, writeSetupPlan } from '../../discovery/plan-store.js';
+import { workspaceSlug } from '../../discovery/interview.js';
+import { registerProjectMemory } from '../../memory/project-registry.js';
+import { verifyProviderDeployment } from '../services/deployment-verification.js';
 import { projectAiwgPath } from '../../config/project-artifacts.js';
+import { useHandler } from './use.js';
 import { normalizeProviderDefinitionId } from '../../providers/provider-definitions.js';
 import { isInteractive } from '../env.js';
 import { requireFlagValue as strictFlagValue, MissingFlagValueError } from '../flag-parsing.js';
+import { parseGuidedSetupFlags, runGuidedSetup } from './guided-setup.js';
+import { DEFAULT_SCRIPTS, parseInitArgInputs } from './init.js';
 import { detectInstalledWorkerClis, evaluateWorkerDispatchOffer, workerDispatchOfferHintWithArg, workerDispatchOfferQuestion, WORKER_DISPATCH_ARG_VALUES, } from '../../models/worker-dispatch-offer.js';
 const DELIVERY_MODES = ['pr-required', 'feature-branch', 'direct'];
 const FORCE_PUSH_POLICIES = ['never', 'own-branch-only', 'allowed'];
@@ -120,6 +136,7 @@ export function parseSetupProjectOptions(ctx) {
 }
 export function detectGitRemotes(projectDir) {
     const result = boundedSpawnSync('git', ['-C', projectDir, 'remote', '-v'], 'quick', {
+        env: helperEnvironment(),
         encoding: 'utf-8',
         stdio: ['ignore', 'pipe', 'ignore'],
     });
@@ -143,6 +160,7 @@ export function detectGitRemotes(projectDir) {
 }
 function detectDefaultBranch(projectDir) {
     const symbolic = boundedSpawnSync('git', ['-C', projectDir, 'symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'], 'quick', {
+        env: helperEnvironment(),
         encoding: 'utf-8',
         stdio: ['ignore', 'pipe', 'ignore'],
     });
@@ -150,6 +168,7 @@ function detectDefaultBranch(projectDir) {
     if (symbolic.status === 0 && fromOrigin)
         return fromOrigin;
     const branch = boundedSpawnSync('git', ['-C', projectDir, 'branch', '--show-current'], 'quick', {
+        env: helperEnvironment(),
         encoding: 'utf-8',
         stdio: ['ignore', 'pipe', 'ignore'],
     });
@@ -157,6 +176,7 @@ function detectDefaultBranch(projectDir) {
 }
 function gitConfig(projectDir, key) {
     const result = boundedSpawnSync('git', ['-C', projectDir, 'config', '--get', key], 'quick', {
+        env: helperEnvironment(),
         encoding: 'utf-8',
         stdio: ['ignore', 'pipe', 'ignore'],
     });
@@ -470,6 +490,310 @@ function printPlan(plan) {
             ui.warn(warning);
     }
 }
+// ---------------------------------------------------------------------------
+// Guided plan review and apply (#3449 A4).
+//
+// `--review` renders a saved guided plan per workspace and provider without
+// writing anything. `--apply` executes `remainingPlanActions` in dependency
+// order through the existing owners: project policy through
+// `buildSetupProjectPlan` + `writeAiwgConfig` (the setup/init config owners),
+// framework deployment through the `use` handler (consuming its
+// `aiwg.use.result.v1` verification), and project registration through the
+// project registry owner. Nothing here re-implements those paths.
+// ---------------------------------------------------------------------------
+/** Legacy policy flags: when any is present, `--dry-run` keeps its legacy preview meaning. */
+const LEGACY_SETUP_POLICY_FLAGS = [
+    '--primary', '--issue-tracker', '--customer-issue-tracker', '--ci',
+    '--issue-provider', '--customer-issue-provider', '--delivery-mode', '--default-branch',
+    '--require-ci-green', '--auto-close-issues', '--issue-comment-on-cycle', '--force-push-policy',
+    '--require-signed-commits', '--committer-name', '--committer-email', '--signing-format',
+    '--signing-key', '--signing-enforce', '--tracker-actor-login', '--tracker-actor-via',
+    '--customer-tracker-actor-login', '--customer-tracker-actor-via', '--worker-dispatch', '--providers',
+];
+function hasLegacySetupPolicyFlags(args) {
+    return LEGACY_SETUP_POLICY_FLAGS.some(flag => args.includes(flag) || args.some(arg => arg.startsWith(`${flag}=`)));
+}
+const GUIDED_INTENT_FRAMEWORK = {
+    code: 'sdlc', docs: 'writing', ops: 'ops', mixed: 'sdlc',
+};
+function guidedAnswer(plan, workspace, block, topic, provider = 'shared') {
+    const projectRoot = projectRootForWorkspace(plan, workspace) ?? workspace;
+    return plan.answers[`${block}.${topic}.ws-${workspaceSlug(projectRoot)}.${provider}`]?.value;
+}
+function guidedProviders(plan, workspace) {
+    const projectRoot = projectRootForWorkspace(plan, workspace) ?? workspace;
+    const prefix = `tools.provider.ws-${workspaceSlug(projectRoot)}.`;
+    return Object.entries(plan.answers)
+        .filter(([id, answer]) => id.startsWith(prefix) && answer.value === true)
+        .map(([id]) => id.slice(prefix.length))
+        .sort();
+}
+async function writeGuidedProjectConfig(plan, action) {
+    const asRecord = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+    const delivery = asRecord(guidedAnswer(plan, action.workspace, 'capabilities', 'delivery'));
+    const signing = guidedAnswer(plan, action.workspace, 'capabilities', 'signing');
+    const tracker = asRecord(guidedAnswer(plan, action.workspace, 'capabilities', 'tracker'));
+    const team = guidedAnswer(plan, action.workspace, 'intent', 'team');
+    const string = (value) => typeof value === 'string' ? value : undefined;
+    const boolean = (value) => typeof value === 'boolean' ? value : undefined;
+    const built = await buildSetupProjectPlan({
+        projectDir: action.workspace,
+        providers: guidedProviders(plan, action.workspace),
+        ...(string(delivery.mode) ? { deliveryMode: string(delivery.mode) } : {}),
+        ...(string(delivery.default_branch) ? { defaultBranch: string(delivery.default_branch) } : {}),
+        ...(boolean(delivery.require_ci_green) ? { requireCiGreen: boolean(delivery.require_ci_green) } : {}),
+        ...(boolean(delivery.auto_close_issues) ? { autoCloseIssues: boolean(delivery.auto_close_issues) } : {}),
+        ...(boolean(delivery.issue_comment_on_cycle) ? { issueCommentOnCycle: boolean(delivery.issue_comment_on_cycle) } : {}),
+        ...(!delivery.force_push_policy && team === 'shared' ? { forcePushPolicy: 'never' } : {}),
+        ...(string(delivery.force_push_policy) ? { forcePushPolicy: string(delivery.force_push_policy) } : {}),
+        ...(signing === false ? { requireSignedCommits: false } : {}),
+        ...(typeof signing?.required === 'boolean'
+            ? { requireSignedCommits: signing.required } : {}),
+        ...(string(signing?.format) ? { signingFormat: string(signing.format) } : {}),
+        ...(string(signing?.key) ? { signingKey: string(signing.key) } : {}),
+        ...(string(signing?.enforce) ? { signingEnforce: string(signing.enforce) } : {}),
+        ...(string(tracker.primary) ? { primary: string(tracker.primary) } : {}),
+        ...(string(tracker.issue_tracker) ? { issueTracker: string(tracker.issue_tracker) } : {}),
+        ...(string(tracker.issue_provider) ? { issueProvider: string(tracker.issue_provider) } : {}),
+        ...(string(tracker.customer_issue_tracker) ? { customerIssueTracker: string(tracker.customer_issue_tracker) } : {}),
+        ...(string(tracker.customer_issue_provider) ? { customerIssueProvider: string(tracker.customer_issue_provider) } : {}),
+        ...(string(tracker.ci) ? { ci: string(tracker.ci) } : {}),
+        ...(string(tracker.tracker_actor_login) ? { trackerActorLogin: string(tracker.tracker_actor_login) } : {}),
+        ...(string(tracker.tracker_actor_via) ? { trackerActorVia: string(tracker.tracker_actor_via) } : {}),
+        ...(string(tracker.customer_tracker_actor_login) ? { customerTrackerActorLogin: string(tracker.customer_tracker_actor_login) } : {}),
+        ...(string(tracker.customer_tracker_actor_via) ? { customerTrackerActorVia: string(tracker.customer_tracker_actor_via) } : {}),
+    });
+    // Interview script answers merge on top of the preserved config: init owns
+    // the default-script set, setup owns the policy merge above.
+    const scripts = asRecord(guidedAnswer(plan, action.workspace, 'tools', 'scripts'));
+    let next = built.next;
+    if (Object.keys(scripts).length > 0) {
+        const merged = { ...(next.scripts ?? {}) };
+        if (scripts.defaultScripts === true) {
+            for (const [name, command] of Object.entries(DEFAULT_SCRIPTS)) {
+                if (!merged[name])
+                    merged[name] = command;
+            }
+        }
+        const custom = scripts.scripts;
+        if (custom && typeof custom === 'object' && !Array.isArray(custom))
+            Object.assign(merged, custom);
+        next = { ...next, scripts: merged };
+    }
+    await writeAiwgConfig(action.workspace, next);
+    return `merged guided policy into ${getConfigPath(action.workspace)}`;
+}
+// configure-provider writes no provider files: provider config files belong
+// to the existing deployment owner (`aiwg use`, the `deploy-framework`
+// action), which `PLAN_APPLY_KIND_ORDER` runs after every
+// configure-provider. An existing file is user-authored and left untouched
+// (applied, preserved); a missing one defers to deploy-framework. The
+// credential reference was already resolved at apply time by the apply engine
+// and is never written anywhere.
+async function writeGuidedProviderConfig(plan, action, configPath) {
+    if (!configPath)
+        throw new Error(`Cannot apply '${action.id}': no provider config path was recorded for ${action.provider}.`);
+    try {
+        await readFile(configPath, 'utf8');
+        return `preserved existing provider file ${configPath} (left untouched)`;
+    }
+    catch (error) {
+        if (error?.code !== 'ENOENT')
+            throw error;
+    }
+    const deploy = plan.actions.find(other => other.workspace === action.workspace &&
+        other.provider === action.provider && other.kind === 'deploy-framework');
+    const owner = deploy ? `'${deploy.id}'` : 'deploy-framework';
+    return `provider files for ${action.provider} in ${action.workspace} are owned by ${owner}; nothing written`;
+}
+async function verifyGuidedProvider(plan, fresh, action, reference) {
+    const executable = action.dependsOn.find(fact => fact.kind === 'tool')?.executable ?? action.provider;
+    const tool = fresh.tools.find(entry => entry.executable === executable);
+    if (!tool || tool.installed !== 'yes') {
+        throw new Error(`Provider tool '${executable}' is not installed; install it and re-run discovery before verifying '${action.id}'.`);
+    }
+    const configPath = action.dependsOn.find(fact => fact.kind === 'path')?.path
+        ?? configPathFor(plan, action.workspace, action.provider);
+    let configNote = 'no config path recorded';
+    if (configPath) {
+        try {
+            await readFile(configPath, 'utf8');
+            configNote = `config present at ${configPath}`;
+        }
+        catch {
+            configNote = `config missing at ${configPath}`;
+        }
+    }
+    const version = tool.version ? `version ${tool.version}` : 'version unknown';
+    // Hyphenated wording: receipt messages persist through the plan store,
+    // whose redaction gate rejects `credential <value>` phrasing.
+    const credential = reference ? `credential-ref ${reference.source}:${reference.name} readable at apply time` : 'no credential-reference recorded';
+    return `verified ${action.provider} (${executable} installed, ${version}; ${configNote}; ${credential}; read-back only)`;
+}
+async function deployGuidedFramework(plan, action, frameworkRoot, signal) {
+    const intent = guidedAnswer(plan, action.workspace, 'intent', 'use');
+    const framework = GUIDED_INTENT_FRAMEWORK[typeof intent === 'string' ? intent : 'code'] ?? 'sdlc';
+    const args = [framework, '--provider', action.provider, ...(action.scope === 'user' ? ['--scope', 'user'] : [])];
+    const deployed = await useHandler.execute({ cwd: action.workspace, args, rawArgs: args, frameworkRoot, dryRun: false, signal });
+    if (deployed.exitCode !== 0) {
+        throw new Error(`aiwg use ${framework} --provider ${action.provider} failed${deployed.message ? `: ${deployed.message}` : ` (exit ${deployed.exitCode})`}.`);
+    }
+    // Consume the aiwg.use.result.v1 verification for this provider and scope.
+    const verification = await verifyProviderDeployment({
+        projectRoot: action.workspace,
+        frameworkRoot,
+        provider: action.provider,
+        scope: action.scope,
+        requestedBundles: [framework],
+    });
+    const blocking = verification.findings.filter(finding => finding.severity === 'blocking');
+    if (verification.outcome === 'failed' || blocking.length > 0) {
+        throw new Error(`Deployment verification failed for ${action.provider}: ${blocking[0]?.message ?? verification.outcome}.`);
+    }
+    return `deployed ${framework} for ${action.provider} (verification: ${verification.outcome})`;
+}
+function defaultGuidedApplyIO(plan, fresh, ctx, projectDir, frameworkRoot, canPrompt) {
+    return {
+        ...defaultPlanReviewIO(),
+        readEnv: name => process.env[name],
+        // Headless apply can consume redirected stdin. Interactive apply uses the prompt below.
+        ...(!canPrompt ? { readStdinCredential: async () => {
+                const chunks = [];
+                for await (const chunk of process.stdin)
+                    chunks.push(Buffer.from(chunk));
+                return Buffer.concat(chunks).toString('utf8');
+            } } : {}),
+        readCredentialFile: async (path) => readPrivateValueFile(path, '--credential'),
+        // stdin-at-apply prompts for the value without echoing it anywhere: the
+        // label names the consumer only, and the value never reaches output.
+        ...(canPrompt ? { promptCredential: async (label) => {
+                const rl = createSecretPromptInterface();
+                try {
+                    process.stdout.write(label);
+                    return await askString(rl, '', '', ctx.signal);
+                }
+                finally {
+                    rl.close();
+                }
+            } } : {}),
+        now: () => new Date().toISOString(),
+        save: async (next) => {
+            await writeSetupPlan(projectDir, next);
+        },
+        owners: {
+            configureJev: async ({ action, token, options }) => {
+                if (options != null)
+                    validateJevOptions(options);
+                const settings = (options ?? {});
+                // Invoke the existing owner directly. spawnSync's input option is
+                // rendered by NODE_DEBUG=child_process before the child can read it.
+                const result = await setupJev({
+                    token,
+                    ...(typeof settings.region === 'string' ? { region: settings.region } : {}),
+                    ...(typeof settings.endpoint === 'string' ? { endpoint: settings.endpoint } : {}),
+                    verify: settings.verify === true,
+                    remove: settings.remove === true,
+                }, { env: process.env, cwd: action.workspace });
+                if (settings.verify === true && settings.remove !== true && result.verified !== true) {
+                    throw new Error('Jev verification incomplete.');
+                }
+            },
+            configureWorkerDispatch: async ({ action }) => {
+                const built = await buildSetupProjectPlan({ projectDir: action.workspace, workerDispatchChoice: 'enable' });
+                const settings = guidedAnswer(plan, action.workspace, 'capabilities', 'worker-config');
+                let next = built.next;
+                if (settings && typeof settings === 'object' && !Array.isArray(settings)) {
+                    if (Object.keys(settings).some(key => !['clis', 'groups', 'admission', 'budgets'].includes(key)))
+                        throw new Error('Invalid worker settings.');
+                    next = { ...next, parallelism: { ...next.parallelism, ...settings } };
+                }
+                if (validateParallelismConfig(next.parallelism).length)
+                    throw new Error('Invalid worker settings.');
+                await writeAiwgConfig(action.workspace, next);
+                const child = boundedSpawnSync(process.execPath, [join(frameworkRoot, 'bin', 'aiwg.mjs'),
+                    'doctor', '--probe-workers', '--qualify', '--yes', '--json'], 'long', {
+                    cwd: action.workspace, env: helperEnvironment(process.env, [...HELPER_ENV_ALLOWLIST,
+                        'AIWG_ROOT', 'AIWG_HOME', 'AIWG_CONFIG', 'XDG_CONFIG_HOME', 'XDG_DATA_HOME',
+                        'AIWG_ARTIFACTS_PATH', 'AIWG_PROJECT_ARTIFACTS_PATH', 'AIWG_PROJECT_AIWG_DIR',
+                        'AIWG_PROJECT_MEMORY_HOME', 'NO_UPDATE_NOTIFIER', 'NO_COLOR', 'CI']), encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 1024 * 1024,
+                });
+                if (child.error || child.status !== 0)
+                    throw new Error('Worker qualification failed.');
+                const report = JSON.parse(child.stdout);
+                if (report.qualification?.status !== 'recorded' || !report.qualification?.results?.length || report.qualification.results.some((row) => row.status !== 'qualified'))
+                    throw new Error('Worker qualification incomplete.');
+            },
+            configureProvider: async ({ action, configPath }) => writeGuidedProviderConfig(plan, action, configPath),
+            verifyProvider: async ({ action }) => verifyGuidedProvider(plan, fresh, action, credentialReferenceFor(plan, action.workspace, action.provider)),
+            writeProjectConfig: async ({ action }) => writeGuidedProjectConfig(plan, action),
+            deployFramework: async ({ action }) => deployGuidedFramework(plan, action, frameworkRoot, ctx.signal),
+            registerProject: async ({ action }) => {
+                const entry = await registerProjectMemory({ workspaceRoot: action.workspace });
+                return `registered project '${entry.id}'`;
+            },
+            recordDecline: async ({ action }) => {
+                const built = await buildSetupProjectPlan({ projectDir: action.workspace, workerDispatchChoice: 'decline' });
+                await writeAiwgConfig(action.workspace, built.next);
+                return `recorded worker-dispatch decline in ${getConfigPath(action.workspace)}`;
+            },
+        },
+    };
+}
+async function loadGuidedPlan(projectDir, planId) {
+    const fresh = await discoverInventory({ workspaceRoot: projectDir });
+    const workspaceRoot = fresh.projects.find(project => project.sources.includes('workspace'))?.root ?? projectDir;
+    const id = planId ?? `setup-${workspaceSlug(workspaceRoot)}`;
+    let plan;
+    try {
+        plan = await readSetupPlan(projectDir, id);
+    }
+    catch {
+        throw new AiwgError({
+            code: 'ERR_SETUP_PLAN_NOT_FOUND',
+            message: `No guided setup plan '${id}' for ${projectDir}.`,
+            hint: 'Record one first with `aiwg setup --scope project|user` (or `aiwg init --scope ...`).',
+            exitCode: EXIT_CODES.GENERAL,
+        });
+    }
+    return { plan, fresh };
+}
+async function runGuidedReview(_ctx, projectDir, planId, json) {
+    const { plan, fresh } = await loadGuidedPlan(projectDir, planId);
+    // Review is read-only: findings come from revalidation plus filesystem
+    // reads, and nothing here writes (not even receipts).
+    const review = await reviewGuidedPlan(plan, fresh, defaultPlanReviewIO());
+    if (json)
+        return { exitCode: 0, rawOutput: true, message: JSON.stringify(review, null, 2) };
+    return { exitCode: 0, message: renderHumanReview(review) };
+}
+async function runGuidedApply(ctx, projectDir, planId, options) {
+    const { plan, fresh } = await loadGuidedPlan(projectDir, planId);
+    // The existing --yes/confirmation gate and TTY rules: a write that can
+    // never be confirmed is refused before any owner runs.
+    if (!options.yes && !options.canPrompt) {
+        throw new AiwgError({
+            code: 'ERR_NON_INTERACTIVE_CONFIRMATION_REQUIRED',
+            message: 'Refusing to apply the guided setup plan in a non-interactive context without --yes.',
+            hint: 'Re-run with `aiwg setup --apply --yes` or use `--review`/`--dry-run` to preview only.',
+            exitCode: EXIT_CODES.USAGE,
+        });
+    }
+    if (!options.yes && options.canPrompt) {
+        const rl = createPromptInterface();
+        try {
+            const confirmed = await askYesNo(rl, `Apply the guided setup plan '${plan.id}'? [y/N]: `, false, ctx.signal);
+            if (!confirmed)
+                return { exitCode: 0, message: 'Guided setup apply cancelled.' };
+        }
+        finally {
+            rl.close();
+        }
+    }
+    const { result } = await applyGuidedPlan(plan, fresh, defaultGuidedApplyIO(plan, fresh, ctx, projectDir, options.frameworkRoot, options.canPrompt));
+    if (options.json)
+        return { exitCode: result.exitCode, rawOutput: true, message: JSON.stringify(result, null, 2) };
+    return { exitCode: result.exitCode, message: result.message };
+}
 export const setupHandler = {
     id: 'setup',
     name: 'Setup',
@@ -484,8 +808,21 @@ export const setupHandler = {
 
 Options:
   --target <dir>                  Project directory
+  --scope project|user            Record guided plan only (no config writes)
+  --force                         Recreate guided interview answers
+  --workspace <root>              Observed workspace to configure (repeatable)
+  --monorepo root|package         Monorepo target selection
+  --package <root>                Observed package root (with --monorepo package)
+  --scan-roots <dir>              Opt in to bounded discovery (repeatable)
+  --intent code|docs|ops|mixed     Workspace usage intent
+  --jev enable|decline|defer     Optional external decision service (default off)
+  --region <r> --endpoint <url> --verify --remove --token-stdin  Existing Jev options
+  --credential <provider>=stdin|file:PATH|store:NAME|env:NAME  Credential reference only
   --yes                           Confirm writes without prompting
   --dry-run                       Preview the setup plan
+  --review                        Render the saved guided plan per workspace/provider (writes nothing)
+  --apply                         Apply the saved guided plan through the existing owners
+  --plan <id>                     Guided plan ID (default: setup plan for the target directory)
   --non-interactive               Disable prompts
   --json                          Emit the plan as JSON
   --primary <remote>              Primary repository remote
@@ -524,12 +861,106 @@ Options:
             };
         }
         const args = subcommand === 'project' ? ctx.args.slice(1) : ctx.args;
+        let guidedFlags;
+        try {
+            guidedFlags = parseGuidedSetupFlags(args, 'setup');
+        }
+        catch (error) {
+            throw new AiwgError({ code: 'ERR_INVALID_VALUE', exitCode: EXIT_CODES.USAGE,
+                message: error instanceof Error ? error.message : String(error) });
+        }
         const options = parseSetupProjectOptions({ ...ctx, args });
         // #3062 review item 12: the one shared interactive decision (TTY, TERM,
         // CI, DEBIAN_FRONTEND) — this used to check only `process.stdin.isTTY &&
         // process.stdout.isTTY`, so a CI job with a pseudo-terminal could still
         // reach these prompts.
         const canPrompt = isInteractive(options.nonInteractive);
+        // #3449 A4: operate on a saved guided plan. `--review` renders it
+        // read-only; `--apply` executes it through the existing owners behind the
+        // same --yes/confirmation gate as legacy writes. `--dry-run` on a guided
+        // plan (no planning or policy flags) previews the same review and writes
+        // nothing. `--review` and `--apply` together is a usage error.
+        const wantsReview = boolFlag(args, '--review');
+        const wantsApply = boolFlag(args, '--apply');
+        if (wantsReview && wantsApply) {
+            throw new AiwgError({
+                code: 'ERR_USAGE_CONFLICTING_FLAGS',
+                message: 'Cannot combine --review with --apply; use --review to preview or --apply to write.',
+                exitCode: EXIT_CODES.USAGE,
+            });
+        }
+        if (wantsReview || wantsApply || (options.dryRun && !guidedFlags.enabled && !hasLegacySetupPolicyFlags(args))) {
+            let planId;
+            try {
+                planId = flagValue(args, '--plan');
+            }
+            catch (error) {
+                if (error instanceof MissingFlagValueError) {
+                    throw new AiwgError({ code: 'ERR_USAGE_MISSING_FLAG_VALUE', message: `${error.message}.`, exitCode: EXIT_CODES.USAGE });
+                }
+                throw error;
+            }
+            // A bare `--dry-run` without a saved plan keeps its legacy preview
+            // meaning; only an existing plan switches it to the guided review.
+            if (!wantsReview && !wantsApply && options.dryRun) {
+                try {
+                    return await runGuidedReview({ ...ctx, args }, options.projectDir, planId, options.json ?? false);
+                }
+                catch (error) {
+                    if (error instanceof AiwgError && error.code === 'ERR_SETUP_PLAN_NOT_FOUND') {
+                        // Fall through to the legacy setup preview below.
+                    }
+                    else
+                        throw error;
+                }
+            }
+            else if (wantsReview || options.dryRun) {
+                return runGuidedReview({ ...ctx, args }, options.projectDir, planId, options.json ?? false);
+            }
+            else {
+                return runGuidedApply({ ...ctx, args }, options.projectDir, planId, { yes: options.yes ?? false, json: options.json ?? false, canPrompt, frameworkRoot: ctx.frameworkRoot });
+            }
+        }
+        if (guidedFlags.enabled) {
+            const target = flagValue(args, '--target');
+            const projectDir = target ?? options.projectDir;
+            let inputs;
+            try {
+                inputs = parseInitArgInputs(args);
+            }
+            catch (error) {
+                throw new AiwgError({ code: 'ERR_INVALID_VALUE', exitCode: EXIT_CODES.USAGE,
+                    message: error instanceof Error ? error.message : String(error) });
+            }
+            const selected = (entries) => {
+                const present = entries.filter((entry) => entry[1] !== undefined);
+                return present.length ? Object.fromEntries(present) : undefined;
+            };
+            const tracker = selected([
+                ['primary', options.primary], ['issue_tracker', options.issueTracker], ['issue_provider', options.issueProvider],
+                ['customer_issue_tracker', options.customerIssueTracker], ['customer_issue_provider', options.customerIssueProvider],
+                ['ci', options.ci], ['tracker_actor_login', options.trackerActorLogin], ['tracker_actor_via', options.trackerActorVia],
+                ['customer_tracker_actor_login', options.customerTrackerActorLogin], ['customer_tracker_actor_via', options.customerTrackerActorVia],
+            ]);
+            const delivery = selected([
+                ['mode', options.deliveryMode], ['default_branch', options.defaultBranch], ['require_ci_green', options.requireCiGreen],
+                ['auto_close_issues', options.autoCloseIssues], ['issue_comment_on_cycle', options.issueCommentOnCycle], ['force_push_policy', options.forcePushPolicy],
+            ]);
+            const signing = options.requireSignedCommits === false ? false : selected([
+                ['required', options.requireSignedCommits], ['format', options.signingFormat], ['key', options.signingKey], ['enforce', options.signingEnforce],
+            ]);
+            const hasScripts = inputs.defaultScriptsArg !== undefined || inputs.customScriptsArg !== undefined || Object.keys(inputs.scriptPairs).length > 0;
+            const remotes = detectGitRemotes(projectDir);
+            const primary = options.primary ?? choosePrimary(remotes);
+            return runGuidedSetup({ ...ctx, args }, guidedFlags, { providers: inputs.providersArg,
+                workerDispatch: options.workerDispatchChoice, tracker, delivery, signing,
+                team: options.forcePushPolicy === undefined ? undefined : options.forcePushPolicy === 'never' ? 'shared' : 'solo',
+                ...(hasScripts ? { scripts: { defaultScripts: inputs.defaultScriptsArg ?? true,
+                        customScripts: inputs.customScriptsArg ?? Object.keys(inputs.scriptPairs).length > 0, scripts: inputs.scriptPairs } } : {}),
+            }, canPrompt, projectDir, remotes.find(r => r.name === primary)?.provider === 'unknown', remotes.length ? { primary, issue_tracker: primary, ci: primary,
+                ...(remotes.find(r => r.name === primary)?.provider !== 'unknown'
+                    ? { issue_provider: remotes.find(r => r.name === primary).provider } : {}) } : undefined);
+        }
         // #3062 second review, finding 6: refuse before any child process runs
         // — `buildSetupProjectPlan()` below makes four `git` calls on its own,
         // and this exact refusal used to happen only after building (and

package/dist/src/cli/handlers/skill-lint.js

@@ -47,7 +47,7 @@ function scoreSchema(frontmatter, diagnostics) {
     const result = validateSkillFrontmatter(frontmatter);
     if (result.success)
         return scoreDimension(true);
-    const notes = result.errors.errors.map((e) => `${e.path.join('.') || '<root>'}: ${e.message}`);
+    const notes = result.errors.issues.map((e) => `${e.path.join('.') || '<root>'}: ${e.message}`);
     return scoreDimension(false, notes);
 }
 /**