@ai-sdlc/orchestrator 0.9.0 → 0.13.0

package/dist/cli/commands/init.d.ts

@@ -12,8 +12,24 @@
  *    orchestrator version that ran init, with an inline opt-out hint.
  *  - Skip `.cursor/mcp.json` unless Cursor is detected (project-local
  *    `.cursor/`, user-global `~/.cursor/`) or `--cursor` is passed.
+ *
+ * AISDLC-143 enhancements (Q4(b) of the quality-gate redesign):
+ *  - Default invocation is now an interactive WIZARD (DoR / attestation /
+ *    classifier / branch-protection prompts) so adopters get a guided
+ *    bootstrap instead of having to read the docs to discover features.
+ *  - `--yes` short-circuits all prompts to "accept defaults" (CI/scripts).
+ *  - `--with-X` flags opt into individual features without prompting.
+ *  - `--add <feature>` extends an already-initialized repo with a single
+ *    feature, idempotently — re-running on an initialized repo is safe.
+ *  - `.github/workflows/ai-sdlc-gate.yml` is scaffolded UNCONDITIONALLY
+ *    so every adopter gets the `ai-sdlc/pr-ready` rollup check on day one
+ *    (Q1: prescriptive default).
+ *  - A "next steps" summary closes the run with operator action items
+ *    conditional on which features were chosen.
  */
 import { Command } from 'commander';
+import { type WizardFlags } from './init-features.js';
+export declare const PIPELINE_YAML = "apiVersion: ai-sdlc.io/v1alpha1\nkind: Pipeline\nmetadata:\n  name: default\nspec:\n  triggers:\n    - event: issue.labeled\n      filter:\n        labels:\n          - ai-eligible\n  providers:\n    sourceControl:\n      type: github\n      config:\n        org: your-org\n  stages:\n    - name: validate\n      qualityGates:\n        - default-gates\n    - name: code\n      agent: default-agent\n      timeout: PT30M\n      onFailure:\n        strategy: retry\n        maxRetries: 2\n    - name: review\n      qualityGates:\n        - default-gates\n  # backlog: holds settings specific to the backlog-task (/ai-sdlc execute)\n  # workflow. These were formerly in a separate pipeline-backlog.yaml file\n  # (deprecated by AISDLC-245.5). Slash commands + pipeline-cli readers\n  # prefer this canonical location.\n  backlog:\n    branching:\n      pattern: 'ai-sdlc/{issueIdLower}-{slug}'\n      targetBranch: main\n      cleanup: on-merge\n    pullRequest:\n      titleTemplate: 'feat: {issueTitle} ({issueId})'\n      descriptionSections:\n        - summary\n        - changes\n        - closes\n      includeProvenance: true\n      closeKeyword: References\n";
 /**
  * Tier-based agent-role templates (AISDLC-79).
  *
@@ -28,5 +44,56 @@ export type AgentRoleTier = 'coding' | 'research' | 'meta';
 export declare const AGENT_ROLE_TIERS: readonly AgentRoleTier[];
 /** Resolve the agent-role.yaml template for a given tier. Default = `coding`. */
 export declare function getAgentRoleYaml(tier?: AgentRoleTier): string;
+/**
+ * Options for `scaffoldSoulDsbs`.
+ */
+export interface ScaffoldSoulDsbsOptions {
+    /**
+     * Name of the platform-root DesignSystemBinding resource.
+     * Referenced in each per-soul DSB's `spec.extends` field.
+     * Defaults to `'platform-dsb'` when not supplied.
+     */
+    platformDsbName?: string;
+    /**
+     * When true, print what would be created without writing files.
+     * Mirrors the `--dry-run` semantics of `initProject()`.
+     */
+    dryRun?: boolean;
+    /**
+     * Output prefix for console lines (e.g. '  ' for indented workspace output).
+     * Defaults to empty string.
+     */
+    prefix?: string;
+}
+/**
+ * Scaffold per-soul DesignSystemBinding template files for a Tessellated Platform.
+ *
+ * Creates `.ai-sdlc/souls/<slug>/design-system-binding.yaml` for each soul slug.
+ * Each file is a complete `DesignSystemBinding` resource that additively extends
+ * the platform-root DSB per RFC-0009 §6 resolution rules.
+ *
+ * Idempotent: existing soul DSB files are skipped (not overwritten).
+ *
+ * @param soulSlugs - soul identifiers to scaffold (e.g. ['soul-a', 'soul-b'])
+ * @param aiSdlcDir - absolute path to the `.ai-sdlc/` directory (config dir)
+ * @param options - optional configuration: platformDsbName, dryRun, prefix
+ *
+ * @example
+ * ```ts
+ * scaffoldSoulDsbs(['soul-a', 'soul-b', 'soul-c'], '/project/.ai-sdlc', {
+ *   platformDsbName: 'acme-platform-dsb',
+ * });
+ * // Created: /project/.ai-sdlc/souls/soul-a/design-system-binding.yaml
+ * // Created: /project/.ai-sdlc/souls/soul-b/design-system-binding.yaml
+ * // Created: /project/.ai-sdlc/souls/soul-c/design-system-binding.yaml
+ * ```
+ */
+export declare function scaffoldSoulDsbs(soulSlugs: readonly string[], aiSdlcDir: string, options?: ScaffoldSoulDsbsOptions): void;
+/**
+ * Build the WizardFlags struct from Commander's parsed options. Pulled
+ * out into a function so tests can drive the wizard pipeline directly
+ * without going through Commander's stateful option store.
+ */
+export declare function buildWizardFlags(opts: Record<string, unknown>): WizardFlags;
 export declare const initCommand: Command;
 //# sourceMappingURL=init.d.ts.map

package/dist/cli/commands/init.js

@@ -12,6 +12,20 @@
  *    orchestrator version that ran init, with an inline opt-out hint.
  *  - Skip `.cursor/mcp.json` unless Cursor is detected (project-local
  *    `.cursor/`, user-global `~/.cursor/`) or `--cursor` is passed.
+ *
+ * AISDLC-143 enhancements (Q4(b) of the quality-gate redesign):
+ *  - Default invocation is now an interactive WIZARD (DoR / attestation /
+ *    classifier / branch-protection prompts) so adopters get a guided
+ *    bootstrap instead of having to read the docs to discover features.
+ *  - `--yes` short-circuits all prompts to "accept defaults" (CI/scripts).
+ *  - `--with-X` flags opt into individual features without prompting.
+ *  - `--add <feature>` extends an already-initialized repo with a single
+ *    feature, idempotently — re-running on an initialized repo is safe.
+ *  - `.github/workflows/ai-sdlc-gate.yml` is scaffolded UNCONDITIONALLY
+ *    so every adopter gets the `ai-sdlc/pr-ready` rollup check on day one
+ *    (Q1: prescriptive default).
+ *  - A "next steps" summary closes the run with operator action items
+ *    conditional on which features were chosen.
  */
 import { Command } from 'commander';
 import { existsSync, mkdirSync, writeFileSync, readFileSync, appendFileSync } from 'node:fs';
@@ -20,7 +34,9 @@ import { detectAgentsDetailed, installMcpServer } from './mcp-setup.js';
 import { detectWorkspace, generateWorkspaceYaml } from './workspace-detect.js';
 import { detectGitRemote, applyRemoteToPipelineYaml } from './git-remote.js';
 import { resolveVersions, formatVersionBlock } from '../versions.js';
-const PIPELINE_YAML = `apiVersion: ai-sdlc.io/v1alpha1
+import { applyFeatureSelection, buildProductionAdapters, ensureClaudeMdPointer, renderNextSteps, resolveFeatureSelection, resolveInstallTarget, runComplianceStep, } from './init-features.js';
+import { CALIBRATION_YAML_STUB, EMBEDDING_CONFIG_YAML_STUB, buildSoulDsbTemplate, } from './init-templates.js';
+export const PIPELINE_YAML = `apiVersion: ai-sdlc.io/v1alpha1
 kind: Pipeline
 metadata:
   name: default
@@ -48,6 +64,23 @@ spec:
     - name: review
       qualityGates:
         - default-gates
+  # backlog: holds settings specific to the backlog-task (/ai-sdlc execute)
+  # workflow. These were formerly in a separate pipeline-backlog.yaml file
+  # (deprecated by AISDLC-245.5). Slash commands + pipeline-cli readers
+  # prefer this canonical location.
+  backlog:
+    branching:
+      pattern: 'ai-sdlc/{issueIdLower}-{slug}'
+      targetBranch: main
+      cleanup: on-merge
+    pullRequest:
+      titleTemplate: 'feat: {issueTitle} ({issueId})'
+      descriptionSections:
+        - summary
+        - changes
+        - closes
+      includeProvenance: true
+      closeKeyword: References
 `;
 export const AGENT_ROLE_TIERS = ['coding', 'research', 'meta'];
 const AGENT_ROLE_YAML_CODING = `apiVersion: ai-sdlc.io/v1alpha1
@@ -228,6 +261,51 @@ spec:
       action: demote-one-level
       cooldown: 2w
 `;
+/**
+ * Scaffold per-soul DesignSystemBinding template files for a Tessellated Platform.
+ *
+ * Creates `.ai-sdlc/souls/<slug>/design-system-binding.yaml` for each soul slug.
+ * Each file is a complete `DesignSystemBinding` resource that additively extends
+ * the platform-root DSB per RFC-0009 §6 resolution rules.
+ *
+ * Idempotent: existing soul DSB files are skipped (not overwritten).
+ *
+ * @param soulSlugs - soul identifiers to scaffold (e.g. ['soul-a', 'soul-b'])
+ * @param aiSdlcDir - absolute path to the `.ai-sdlc/` directory (config dir)
+ * @param options - optional configuration: platformDsbName, dryRun, prefix
+ *
+ * @example
+ * ```ts
+ * scaffoldSoulDsbs(['soul-a', 'soul-b', 'soul-c'], '/project/.ai-sdlc', {
+ *   platformDsbName: 'acme-platform-dsb',
+ * });
+ * // Created: /project/.ai-sdlc/souls/soul-a/design-system-binding.yaml
+ * // Created: /project/.ai-sdlc/souls/soul-b/design-system-binding.yaml
+ * // Created: /project/.ai-sdlc/souls/soul-c/design-system-binding.yaml
+ * ```
+ */
+export function scaffoldSoulDsbs(soulSlugs, aiSdlcDir, options = {}) {
+    const { platformDsbName = 'platform-dsb', dryRun = false, prefix = '' } = options;
+    if (soulSlugs.length === 0) {
+        console.log(`${prefix}No soul slugs provided — skipping soul DSB scaffolding.`);
+        return;
+    }
+    for (const slug of soulSlugs) {
+        const soulDir = join(aiSdlcDir, 'souls', slug);
+        const dsbPath = join(soulDir, 'design-system-binding.yaml');
+        if (dryRun) {
+            console.log(`${prefix}Would create ${dsbPath}`);
+            continue;
+        }
+        if (existsSync(dsbPath)) {
+            console.log(`${prefix}  skip souls/${slug}/design-system-binding.yaml (already exists)`);
+            continue;
+        }
+        mkdirSync(soulDir, { recursive: true });
+        writeFileSync(dsbPath, buildSoulDsbTemplate(slug, platformDsbName), 'utf-8');
+        console.log(`${prefix}  created souls/${slug}/design-system-binding.yaml`);
+    }
+}
 const GITIGNORE_PATHS = ['.ai-sdlc/state.db', '.ai-sdlc/state/', '.ai-sdlc/audit.jsonl'];
 /** Ensure .gitignore includes AI-SDLC runtime artifact entries. */
 function ensureGitignore(projectDir, dryRun, prefix = '') {
@@ -255,6 +333,16 @@ function initProject(projectDir, configDirName, dryRun, prefix = '', options = {
         { name: 'agent-role.yaml', content: getAgentRoleYaml(options.tier) },
         { name: 'quality-gate.yaml', content: QUALITY_GATE_YAML },
         { name: 'autonomy-policy.yaml', content: AUTONOMY_POLICY_YAML },
+        // RFC-0031 §12.6 per-org calibration config (Refit AISDLC-310):
+        // confidence thresholds + rejection weights/floor for the DID revision
+        // proposal mechanism. Defaults match the operator-affirmed shipped values.
+        { name: 'calibration.yaml', content: CALIBRATION_YAML_STUB },
+        // RFC-0019 §15.1 per-org embedding-framework defaults (AISDLC-340).
+        // Documents every NEW re-walkthrough field (scaleEscalationHeuristic,
+        // perConsumerOverridesAllowed, crossProviderPolicy split, catalogDedup
+        // milestones, unifiedCostReport, adapterBillingModelRespected). The
+        // file is OPTIONAL — when absent, framework defaults match these values.
+        { name: 'embedding-config.yaml', content: EMBEDDING_CONFIG_YAML_STUB },
     ];
     if (dryRun) {
         console.log(`${prefix}Would create ${configDir}/`);
@@ -301,6 +389,60 @@ function initWorkspaceRoot(workspacePath, repos, configDirName, dryRun) {
         console.log(`  created workspace.yaml`);
     }
 }
+/**
+ * Build the WizardFlags struct from Commander's parsed options. Pulled
+ * out into a function so tests can drive the wizard pipeline directly
+ * without going through Commander's stateful option store.
+ */
+export function buildWizardFlags(opts) {
+    const addRaw = typeof opts.add === 'string' ? opts.add : undefined;
+    let add;
+    if (addRaw === 'dor' ||
+        addRaw === 'attestation' ||
+        addRaw === 'classifier' ||
+        addRaw === 'branch-protection' ||
+        addRaw === 'workflows' ||
+        addRaw === 'signal-ingestion') {
+        add = addRaw;
+    }
+    return {
+        yes: !!opts.yes,
+        withDor: !!opts.withDor,
+        withAttestation: !!opts.withAttestation,
+        withClassifier: !!opts.withClassifier,
+        withBranchProtection: !!opts.withBranchProtection,
+        withWorkflows: !!opts.withWorkflows,
+        withSignalIngestion: !!opts.withSignalIngestion,
+        add,
+        dryRun: !!opts.dryRun,
+        workspace: typeof opts.workspace === 'string' ? opts.workspace : undefined,
+        force: !!opts.force,
+    };
+}
+/** Validate a `--add` arg and return either the normalized value or null+error. */
+function validateAddArg(addRaw) {
+    if (addRaw === undefined || addRaw === null || addRaw === false)
+        return { ok: true };
+    if (typeof addRaw !== 'string')
+        return { ok: false, error: `--add must be a string` };
+    const allowed = [
+        'dor',
+        'attestation',
+        'classifier',
+        'branch-protection',
+        'workflows',
+        'signal-ingestion',
+        'souls',
+    ];
+    if (!allowed.includes(addRaw)) {
+        return {
+            ok: false,
+            error: `--add: unknown feature '${addRaw}'. Expected one of: ${allowed.join(', ')}.`,
+        };
+    }
+    // 'souls' is handled separately in the action; cast the rest to WizardFlags['add']
+    return { ok: true, value: addRaw };
+}
 export const initCommand = new Command('init')
     .description('Initialize AI-SDLC configuration in the current project')
     .option('--dry-run', 'Show what would be created without writing files')
@@ -308,10 +450,48 @@ export const initCommand = new Command('init')
     .option('--cursor', 'Force-install Cursor MCP config even if Cursor is not detected')
     .option('-d, --dir <path>', 'Config directory name', '.ai-sdlc')
     .option('--role <tier>', `Agent-role tool tier: ${AGENT_ROLE_TIERS.join(' | ')} (default: coding)`, 'coding')
+    // ── AISDLC-143 wizard flags ─────────────────────────────────────────
+    .option('-y, --yes', 'Accept all defaults (non-interactive; CI/scripts)')
+    .option('--with-dor', 'Scaffold Definition-of-Ready gate config + workflow')
+    .option('--with-attestation', 'Scaffold attestation infrastructure (audit-only)')
+    .option('--with-classifier', 'Scaffold review classifier config stub')
+    .option('--with-branch-protection', 'Apply recommended branch-protection rule to main (requires gh)')
+    // ── AISDLC-261 workflow scaffold flags ──────────────────────────────
+    .option('--with-workflows', 'Scaffold GitHub Actions workflow bundle (gate, review, attestation, auto-merge)')
+    .option('--force', 'Overwrite existing workflow files (use with --with-workflows or --add workflows)')
+    // ── AISDLC-348 RFC-0030 signal-ingestion scaffold flag ──────────────
+    .option('--with-signal-ingestion', 'Scaffold RFC-0030 signal-ingestion config (default OFF; opt in via AI_SDLC_SIGNAL_INGESTION soak)')
+    .option('--add <feature>', 'Extend an already-initialized repo with a single feature: dor | attestation | classifier | branch-protection | workflows | signal-ingestion | souls')
+    // ── RFC-0009 Phase 2.2 — per-soul DSB scaffolding ──────────────────
+    .option('--souls <slugs>', 'Comma-separated soul slugs for --add souls (e.g. --souls soul-a,soul-b,soul-c)')
+    .option('--platform-dsb <name>', 'Platform-root DSB name for --add souls extends reference (default: platform-dsb)', 'platform-dsb')
+    .option('--workspace <name>', 'Opt into a per-workspace install at packages/<name>/.ai-sdlc/ instead of the git-root default')
     .action(async (opts) => {
-    const projectDir = process.cwd();
     const configDirName = opts.dir ?? '.ai-sdlc';
     const dryRun = !!opts.dryRun;
+    // ── AISDLC-262: resolve install target via git rev-parse --show-toplevel ─
+    // Default: install at the git root. If the root already has .ai-sdlc/,
+    // refuse with a clear message unless --workspace <name> is passed.
+    // Printed on the first output line so adopters can sanity-check the
+    // resolved target before any files are written (AC #4).
+    const targetResult = resolveInstallTarget({
+        cwd: process.cwd(),
+        workspace: typeof opts.workspace === 'string' ? opts.workspace : undefined,
+        configDirName,
+        // --add is the extension path: the root's .ai-sdlc/ already exists by
+        // design, so the "already installed" nesting check must be suppressed.
+        skipExistingCheck: !!opts.add,
+    });
+    if (targetResult.error) {
+        console.error(`Error: ${targetResult.error}`);
+        process.exitCode = 1;
+        return;
+    }
+    const projectDir = targetResult.installDir;
+    if (targetResult.resolved) {
+        console.log(`Resolved install target: ${projectDir}`);
+        console.log('');
+    }
     const tierInput = (opts.role ?? 'coding');
     if (!AGENT_ROLE_TIERS.includes(tierInput)) {
         console.error(`Error: invalid --role value '${tierInput}'. Expected one of: ${AGENT_ROLE_TIERS.join(', ')}.`);
@@ -320,6 +500,76 @@ export const initCommand = new Command('init')
     }
     const tier = tierInput;
     const cursorOptIn = !!opts.cursor;
+    // ── Validate --add early so we error before doing any work. ────────
+    const addCheck = validateAddArg(opts.add);
+    if (!addCheck.ok) {
+        console.error(`Error: ${addCheck.error}`);
+        process.exitCode = 1;
+        return;
+    }
+    const flags = buildWizardFlags(opts);
+    // ── --add souls path (RFC-0009 Phase 2.2) ─────────────────────────
+    // Scaffold per-soul DSB templates for a Tessellated Platform.
+    // Usage: ai-sdlc init --add souls --souls soul-a,soul-b,soul-c
+    if (addCheck.value === 'souls') {
+        const soulsRaw = typeof opts.souls === 'string' ? opts.souls : '';
+        const platformDsbName = typeof opts.platformDsb === 'string' ? opts.platformDsb : 'platform-dsb';
+        const soulSlugs = soulsRaw
+            .split(',')
+            .map((slug) => slug.trim())
+            .filter((slug) => slug.length > 0);
+        if (soulSlugs.length === 0) {
+            console.error('Error: --add souls requires --souls <slug1,slug2,...> with at least one soul slug.');
+            process.exitCode = 1;
+            return;
+        }
+        // Validate soul slugs (must match ^[a-z0-9-]+$ per RFC-0009 §5.2 soulId pattern)
+        const invalidSlugs = soulSlugs.filter((slug) => !/^[a-z0-9-]+$/.test(slug));
+        if (invalidSlugs.length > 0) {
+            console.error(`Error: invalid soul slug(s): ${invalidSlugs.join(', ')}. Slugs must match ^[a-z0-9-]+$.`);
+            process.exitCode = 1;
+            return;
+        }
+        const aiSdlcDir = join(projectDir, configDirName);
+        console.log(`Scaffolding per-soul DSB templates in ${aiSdlcDir}/souls/:`);
+        console.log('');
+        scaffoldSoulDsbs(soulSlugs, aiSdlcDir, {
+            platformDsbName,
+            dryRun,
+            prefix: '  ',
+        });
+        console.log('');
+        console.log(`Done. Edit each .ai-sdlc/souls/<slug>/design-system-binding.yaml to`);
+        console.log(`configure soul-specific design system bindings.`);
+        return;
+    }
+    // ── --add path: extend an already-initialized repo ────────────────
+    // AC #7: skip the "always-scaffold-baseline" path entirely; the
+    // wizard dispatcher's `--add` branch knows to write only the chosen
+    // feature's templates (no pipeline.yaml, no MCP setup, no workspace
+    // detection). This is the safe re-run path on a repo that already
+    // ran `ai-sdlc init` once.
+    if (flags.add) {
+        const adapters = buildProductionAdapters();
+        const selection = await resolveFeatureSelection(flags, adapters);
+        console.log(`Extending AI-SDLC config with --add ${flags.add}:`);
+        console.log('');
+        const result = await applyFeatureSelection(projectDir, selection, flags, adapters);
+        renderNextSteps(selection, result, adapters);
+        // Reviewer feedback (round 2, suggestion #5): when the operator
+        // explicitly requested branch-protection via a non-interactive flag
+        // (--add branch-protection here; --yes / --with-branch-protection
+        // in runWizardStage) and the apply failed (gh missing, not
+        // authenticated, etc.), surface a non-zero exit so CI scripts can
+        // detect failure instead of seeing the silent log line.
+        if (flags.add === 'branch-protection' &&
+            result.branchProtection &&
+            !result.branchProtection.applied &&
+            result.branchProtection.error) {
+            process.exitCode = 1;
+        }
+        return;
+    }
     // ── version provenance (AC #1) ────────────────────────────────────
     const versions = resolveVersions({ workDir: projectDir });
     console.log(formatVersionBlock(versions));
@@ -377,6 +627,12 @@ export const initCommand = new Command('init')
             }
         }
         console.log(`\nAI-SDLC workspace initialized in ${projectDir}/`);
+        // ── AISDLC-143 wizard (workspace root) ────────────────────────
+        // The wizard runs ONCE at the workspace root: the baseline gate
+        // workflow + per-feature workflows live at `<workspace-root>/.github/`,
+        // not in each child repo. Children share the same CI from the
+        // root since GHA workflows always live at the repo root anyway.
+        await runWizardStage(projectDir, flags);
         console.log(`Run 'ai-sdlc health' to verify your configuration.`);
     }
     else {
@@ -399,7 +655,50 @@ export const initCommand = new Command('init')
             }
         }
         console.log(`\nAI-SDLC config initialized in ${join(projectDir, configDirName)}/`);
+        // ── AISDLC-143 wizard (single-repo) ──────────────────────────
+        await runWizardStage(projectDir, flags);
         console.log(`Run 'ai-sdlc health' to verify your configuration.`);
     }
 });
+/**
+ * Run the AISDLC-143 wizard stage: prompt the user (or short-circuit on
+ * --yes / --with-X), apply the chosen feature templates, append the
+ * CLAUDE.md pointer, and render the "next steps" summary.
+ *
+ * Pulled out of the inline action body so both the single-repo and
+ * workspace-root branches share the same wiring. Adapters are built
+ * once here (production = real disk writes; tests inject stubs by
+ * calling `applyFeatureSelection`/`renderNextSteps` directly).
+ */
+async function runWizardStage(projectDir, flags) {
+    const adapters = buildProductionAdapters();
+    console.log('');
+    console.log('━━━ Compliance posture ━━━');
+    console.log('');
+    // RFC-0022 §7 / AISDLC-324: compliance step runs BEFORE gate-config feature prompts
+    await runComplianceStep(projectDir, flags, adapters);
+    console.log('');
+    console.log('━━━ Feature wizard ━━━');
+    console.log('');
+    const selection = await resolveFeatureSelection(flags, adapters);
+    console.log('');
+    console.log('Scaffolding selected features:');
+    const result = await applyFeatureSelection(projectDir, selection, flags, adapters);
+    ensureClaudeMdPointer(projectDir, adapters, flags.dryRun);
+    renderNextSteps(selection, result, adapters);
+    // Reviewer feedback (round 2, suggestion #5): when branch-protection
+    // was non-interactively requested (--with-branch-protection or --yes,
+    // both used by CI scripts) and the apply failed (gh missing, not
+    // authenticated, etc.), surface a non-zero exit so CI can detect
+    // failure instead of seeing the silent log line. Interactive prompt
+    // answers don't trip this — the human already saw the error and can
+    // re-run `ai-sdlc init --add branch-protection` themselves.
+    const branchProtectionRequestedNonInteractively = flags.yes || flags.withBranchProtection;
+    if (branchProtectionRequestedNonInteractively &&
+        result.branchProtection &&
+        !result.branchProtection.applied &&
+        result.branchProtection.error) {
+        process.exitCode = 1;
+    }
+}
 //# sourceMappingURL=init.js.map

package/dist/cli/commands/run.js

@@ -8,6 +8,8 @@ export const runCommand = new Command('run')
     .description('Run the AI-SDLC pipeline for a specific issue')
     .requiredOption('-i, --issue <id>', 'Issue ID to process')
     .option('--state <path>', 'SQLite state database path')
+    .option('--runner <name>', 'Select a registered runner by name (e.g. claude-code, copilot, cursor). ' +
+    'Fails fast when the name is not registered — no silent fallback.')
     .action(async (opts, cmd) => {
     const globalOpts = cmd.parent?.opts() ?? {};
     const format = globalOpts.format ?? 'table';
@@ -16,7 +18,13 @@ export const runCommand = new Command('run')
         statePath: opts.state,
     });
     try {
-        const result = await orchestrator.run(opts.issue);
+        // opts.runner maps to ExecuteOptions.runnerName; resolveRunner() in execute.ts
+        // applies the full precedence chain and throws on unknown names.
+        // Only pass overrides when a flag is explicitly set to avoid breaking callers
+        // that match on the exact argument list (e.g. existing tests).
+        const result = opts.runner
+            ? await orchestrator.run(opts.issue, { runnerName: opts.runner })
+            : await orchestrator.run(opts.issue);
         console.log(formatOutput(format, {
             type: 'run',
             issueId: opts.issue,

package/dist/cli/index.d.ts

@@ -16,4 +16,15 @@ import { type VersionTriple } from './versions.js';
  * exact factory at startup.
  */
 export declare function buildProgram(versions: VersionTriple): Command;
+/**
+ * Determine whether this module is being run as the CLI entry point,
+ * correctly handling npm bin symlinks.
+ *
+ * Exported for unit-testing; production callers should use the module-level
+ * `isMainEntry` constant instead.
+ *
+ * @param moduleUrl  - The `import.meta.url` of the caller module.
+ * @param argv1      - `process.argv[1]` (the script path Node was given).
+ */
+export declare function computeIsMainEntry(moduleUrl: string, argv1: string | undefined): boolean;
 //# sourceMappingURL=index.d.ts.map

package/dist/cli/index.js

@@ -7,6 +7,8 @@
  * unknown-subcommand hint that points at the upgrade flow when version
  * drift is detected.
  */
+import { fileURLToPath } from 'url';
+import { realpathSync } from 'fs';
 import { Command } from 'commander';
 import { initCommand } from './commands/init.js';
 import { runCommand } from './commands/run.js';
@@ -83,14 +85,46 @@ export function buildProgram(versions) {
 // Bin entry: only run argv parsing when invoked as a script, not when the
 // module is imported by tests.
 //
-// `process.argv[1]` is the path Node resolved for the entry script.
-// When it ends with the compiled CLI bundle (`dist/cli/index.js`) we are
-// the main entry. When imported (e.g. via Vitest) argv[1] points at the
-// test runner, so we skip parsing.
-const isMainEntry = (() => {
-    const entry = process.argv[1] ?? '';
-    return entry.endsWith('cli/index.js') || entry.endsWith('cli/index.ts');
-})();
+// IMPORTANT: Node does NOT resolve symlinks for `process.argv[1]`. When
+// the CLI is installed globally via npm (`npm install -g`), the bin path
+// is a symlink (e.g. `/usr/local/bin/ai-sdlc`) that points to the real
+// `dist/cli/index.js`. The old `endsWith('cli/index.js')` check failed
+// for that case because argv[1] held the symlink path, not the target.
+//
+// Fix: compare `import.meta.url` (always the real module's file URL) to
+// `pathToFileURL(realpathSync(argv[1]))` (which resolves the symlink).
+// When imported by Vitest, argv[1] points at the test runner, so
+// `realpathSync` still returns a path that differs from import.meta.url
+// and the guard correctly returns false.
+/**
+ * Determine whether this module is being run as the CLI entry point,
+ * correctly handling npm bin symlinks.
+ *
+ * Exported for unit-testing; production callers should use the module-level
+ * `isMainEntry` constant instead.
+ *
+ * @param moduleUrl  - The `import.meta.url` of the caller module.
+ * @param argv1      - `process.argv[1]` (the script path Node was given).
+ */
+export function computeIsMainEntry(moduleUrl, argv1) {
+    if (!argv1)
+        return false;
+    try {
+        // Resolve symlinks on BOTH sides before comparing, so that:
+        //   1. npm bin symlinks in argv1 resolve to the real dist/cli/index.js.
+        //   2. OS-level dir symlinks (e.g. macOS /tmp → /private/tmp) don't cause
+        //      spurious mismatches when moduleUrl itself was built from an
+        //      unresolved path.
+        const realArgv1 = realpathSync(argv1);
+        const realModule = realpathSync(fileURLToPath(moduleUrl));
+        return realArgv1 === realModule;
+    }
+    catch {
+        // realpathSync / fileURLToPath can throw — treat as "not main".
+        return false;
+    }
+}
+const isMainEntry = computeIsMainEntry(import.meta.url, process.argv[1]);
 if (isMainEntry) {
     const program = buildProgram(resolveVersions());
     program.parse();

package/dist/compliance/composer.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Regime → DerivedGates composer (RFC-0022 §9 Phase 2).
+ *
+ * Reads the CompliancePosture's declared regime list, looks up each regime's
+ * DerivedGates values from spec/compliance/regime-mappings.yaml, composes
+ * them using "tightest-wins" semantics (RFC-0022 §6), applies adopter
+ * regimeOverrides per-regime (OQ-1), and finally applies operator-level
+ * derivedGates overrides last.
+ *
+ * Key design decisions:
+ *  - YAML mapping file is read at call time (not module load) so tests can
+ *    supply a custom mappings path without patching module state.
+ *  - Tightest-wins is axis-specific: ordinal enums max, boolean OR, numeric max.
+ *  - UnknownRegime is thrown when a declared regime ID has no entry in the
+ *    mapping table (Phase 2 activation of the placeholder from Phase 1 errors.ts).
+ *  - Adopter regimeOverrides (OQ-1) let per-regime control values be adjusted
+ *    before the operator-override pass, enabling bespoke auditor interpretations
+ *    without changing the canonical mapping table.
+ *  - Operator derivedGates overrides (validated by the loader) always win last.
+ */
+import type { CompliancePosture, DerivedGates } from './types.js';
+/**
+ * Options for `composePostureDerivedGates`.
+ */
+export interface ComposerOptions {
+    /**
+     * Absolute path to the regime-mappings.yaml file.
+     * Defaults to resolving `spec/compliance/regime-mappings.yaml` from the
+     * repository root (detected by walking up from __dirname).
+     *
+     * Override in tests to supply fixture mapping files.
+     */
+    mappingsPath?: string;
+    /**
+     * Root directory for finding the default mappings file.
+     * Defaults to walking up from the module file location.
+     */
+    repoRoot?: string;
+}
+/**
+ * The result of composing a CompliancePosture's regimes into DerivedGates.
+ */
+export interface CompositionResult {
+    /**
+     * The composed DerivedGates after regime composition + overrides.
+     */
+    derivedGates: DerivedGates;
+    /**
+     * List of regime IDs that were composed.
+     * Empty means baseline was used (no regimes declared).
+     */
+    composedRegimes: string[];
+    /**
+     * Regime IDs that had adopter regimeOverrides applied.
+     */
+    regimesWithAdopterOverrides: string[];
+    /**
+     * Gate fields that were overridden by the operator-level derivedGates.
+     */
+    operatorOverriddenFields: string[];
+}
+/**
+ * Compose a loaded CompliancePosture into a concrete DerivedGates value.
+ *
+ * Algorithm (RFC-0022 §6):
+ *  1. Start from BASELINE_DERIVED_GATES.
+ *  2. For each declared regime, look up its entry in regime-mappings.yaml.
+ *     Throw UnknownRegime if not found.
+ *  3. Apply adopter regimeOverrides (per-regime) before composition (OQ-1).
+ *  4. Merge each regime's gates into the accumulator via tightest-wins.
+ *  5. Apply operator derivedGates overrides last — they always win.
+ *
+ * @param posture - A single CompliancePosture (element from the loader's list).
+ * @param options - Optional override for the mappings file path.
+ * @returns CompositionResult with the resolved DerivedGates.
+ * @throws UnknownRegime if any declared regime ID is not in the mapping table.
+ */
+export declare function composePostureDerivedGates(posture: CompliancePosture, options?: ComposerOptions): CompositionResult;
+//# sourceMappingURL=composer.d.ts.map