@ai-sdlc/orchestrator 0.10.0 → 0.13.0

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

@@ -44,6 +44,51 @@ 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

package/dist/cli/commands/init.js

@@ -34,7 +34,8 @@ 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';
-import { applyFeatureSelection, buildProductionAdapters, ensureClaudeMdPointer, renderNextSteps, resolveFeatureSelection, } from './init-features.js';
+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:
@@ -260,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 = '') {
@@ -287,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}/`);
@@ -344,7 +400,9 @@ export function buildWizardFlags(opts) {
     if (addRaw === 'dor' ||
         addRaw === 'attestation' ||
         addRaw === 'classifier' ||
-        addRaw === 'branch-protection') {
+        addRaw === 'branch-protection' ||
+        addRaw === 'workflows' ||
+        addRaw === 'signal-ingestion') {
         add = addRaw;
     }
     return {
@@ -353,8 +411,12 @@ export function buildWizardFlags(opts) {
         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. */
@@ -363,13 +425,22 @@ function validateAddArg(addRaw) {
         return { ok: true };
     if (typeof addRaw !== 'string')
         return { ok: false, error: `--add must be a string` };
-    const allowed = ['dor', 'attestation', 'classifier', 'branch-protection'];
+    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')
@@ -385,11 +456,42 @@ export const initCommand = new Command('init')
     .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)')
-    .option('--add <feature>', 'Extend an already-initialized repo with a single feature: dor | attestation | classifier | branch-protection')
+    // ── 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(', ')}.`);
@@ -406,6 +508,41 @@ export const initCommand = new Command('init')
         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
@@ -536,6 +673,11 @@ export const initCommand = new Command('init')
 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);

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