@ai-sdlc/orchestrator 0.10.0 → 0.14.0

package/dist/cli/commands/init-features.js

@@ -11,6 +11,7 @@
  *   3. The branch-protection helper (applyBranchProtection) including the
  *      `--dry-run` JSON-print path required by AC #6.
  *   4. The "next steps" summary printed at the end of init (AC #5).
+ *   5. The compliance-posture wizard step (RFC-0022 §7 / AISDLC-324).
  *
  * Test surface: every public function takes a small options bag with
  * injectable side-effect adapters (prompter, writeFile, runCommand) so the
@@ -19,23 +20,551 @@
  * the real adapters.
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join, dirname } from 'node:path';
-import { execFileSync } from 'node:child_process';
-import { ATTESTATION_TEMPLATES, BASELINE_WORKFLOW_TEMPLATES, CLASSIFIER_TEMPLATES, DOR_TEMPLATES, HUSKY_PREPUSH_SIGN_SNIPPET, } from './init-templates.js';
+import { join, dirname, basename } from 'node:path';
+import { execFileSync, execSync } from 'node:child_process';
+import { BASELINE_DERIVED_GATES } from '../../compliance/types.js';
+import { ATTESTATION_TEMPLATES, BASELINE_WORKFLOW_TEMPLATES, CLASSIFIER_TEMPLATES, DOR_TEMPLATES, HUSKY_PREPUSH_SIGN_SNIPPET, SIGNAL_INGESTION_TEMPLATES, WORKFLOWS_TEMPLATES, } from './init-templates.js';
+/**
+ * Canonical list of regulatory regimes presented in the compliance wizard.
+ * Mirrors the entries in spec/compliance/regime-mappings.yaml.
+ */
+export const COMPLIANCE_REGIME_CHOICES = [
+    { value: 'SOC2-T2', label: 'SOC2 Type 2 (Service Organization Control)' },
+    { value: 'HIPAA', label: 'HIPAA (Health Insurance Portability and Accountability Act)' },
+    { value: 'PCI-DSS-L1', label: 'PCI-DSS Level 1 (Payment Card Industry Data Security Standard)' },
+    { value: 'GDPR', label: 'GDPR (General Data Protection Regulation; EU)' },
+    { value: 'FedRAMP-Moderate', label: 'FedRAMP Moderate (US federal)' },
+    { value: 'ISO-27001:2022', label: 'ISO 27001:2022' },
+];
+/**
+ * Inline regime → DerivedGates mapping for the init wizard.
+ * Mirrors spec/compliance/regime-mappings.yaml so the wizard works in
+ * installed-package contexts (where the YAML file is not bundled).
+ *
+ * NOTE: This data is intentionally duplicated from regime-mappings.yaml to
+ * avoid a runtime file-read dependency in the init wizard. When regime-mappings.yaml
+ * is updated, this table MUST be updated in sync. The RFC-0022 §13 Q7 PR-template
+ * compliance-impact checkbox enforces this via reviewer check.
+ */
+const INIT_WIZARD_REGIME_GATES = {
+    'SOC2-T2': {
+        databaseBranchPool: 'per-shard',
+        secretScanStrictness: 'strict',
+        attestationRequired: true,
+        auditRetentionDays: 2555,
+        reviewerAuthorityModel: 'allowlist+role',
+    },
+    HIPAA: {
+        databaseBranchPool: 'per-shard',
+        secretScanStrictness: 'strict',
+        attestationRequired: true,
+        auditRetentionDays: 2190,
+        reviewerAuthorityModel: 'allowlist+role',
+    },
+    'PCI-DSS-L1': {
+        databaseBranchPool: 'per-shard',
+        secretScanStrictness: 'strict',
+        attestationRequired: true,
+        auditRetentionDays: 365,
+        reviewerAuthorityModel: 'allowlist+role',
+    },
+    GDPR: {
+        databaseBranchPool: 'per-shard',
+        secretScanStrictness: 'standard',
+        attestationRequired: true,
+        auditRetentionDays: 365,
+        reviewerAuthorityModel: 'allowlist',
+    },
+    'FedRAMP-Moderate': {
+        databaseBranchPool: 'per-shard',
+        secretScanStrictness: 'strict',
+        attestationRequired: true,
+        auditRetentionDays: 1095,
+        reviewerAuthorityModel: 'allowlist+role',
+    },
+    'ISO-27001:2022': {
+        databaseBranchPool: 'per-shard',
+        secretScanStrictness: 'strict',
+        attestationRequired: true,
+        auditRetentionDays: 365,
+        reviewerAuthorityModel: 'allowlist+role',
+    },
+};
+/**
+ * Ordinal scales for tightest-wins composition.
+ */
+const SECRET_SCAN_ORDINAL = {
+    minimal: 0,
+    standard: 1,
+    strict: 2,
+};
+const REVIEWER_AUTHORITY_ORDINAL = {
+    open: 0,
+    allowlist: 1,
+    'allowlist+role': 2,
+};
+/**
+ * Compute DerivedGates from a list of regime IDs using tightest-wins semantics.
+ * Unknown regime IDs are skipped (the wizard's informational display degrades
+ * gracefully rather than throwing).
+ *
+ * This is a lightweight inline computation used exclusively by the init wizard.
+ * The canonical composer (orchestrator/src/compliance/composer.ts) is used for
+ * all post-init runtime gate resolution.
+ */
+export function computeInitWizardDerivedGates(regimes) {
+    if (regimes.length === 0)
+        return { ...BASELINE_DERIVED_GATES };
+    let accumulated = { ...BASELINE_DERIVED_GATES };
+    for (const regimeId of regimes) {
+        const entry = INIT_WIZARD_REGIME_GATES[regimeId];
+        if (!entry)
+            continue; // Unknown regime — skip gracefully
+        // databaseBranchPool: per-shard beats shared-with-rls
+        if (entry.databaseBranchPool === 'per-shard') {
+            accumulated = { ...accumulated, databaseBranchPool: 'per-shard' };
+        }
+        // secretScanStrictness: ordinal max
+        if (SECRET_SCAN_ORDINAL[entry.secretScanStrictness] >
+            SECRET_SCAN_ORDINAL[accumulated.secretScanStrictness]) {
+            accumulated = { ...accumulated, secretScanStrictness: entry.secretScanStrictness };
+        }
+        // attestationRequired: boolean OR
+        if (entry.attestationRequired) {
+            accumulated = { ...accumulated, attestationRequired: true };
+        }
+        // auditRetentionDays: max
+        if (entry.auditRetentionDays > accumulated.auditRetentionDays) {
+            accumulated = { ...accumulated, auditRetentionDays: entry.auditRetentionDays };
+        }
+        // reviewerAuthorityModel: ordinal max
+        if (REVIEWER_AUTHORITY_ORDINAL[entry.reviewerAuthorityModel] >
+            REVIEWER_AUTHORITY_ORDINAL[accumulated.reviewerAuthorityModel]) {
+            accumulated = { ...accumulated, reviewerAuthorityModel: entry.reviewerAuthorityModel };
+        }
+    }
+    return accumulated;
+}
+/**
+ * Apply the RFC-0009 §8.7 / OQ-11 trigger checklist on top of regime-derived
+ * `DerivedGates`. Upgrades `databaseBranchPool` from `shared-with-rls` to
+ * `per-shard` when ANY of the three triggers fires:
+ *
+ *  - Regulatory: already reflected in `inputGates.databaseBranchPool === 'per-shard'`
+ *    (set by `computeInitWizardDerivedGates` when a per-shard-forcing regime was
+ *    declared). When this is the case, 'regulatory' is recorded in `triggers`.
+ *  - Customer contract: `answers.customerContract === true`.
+ *  - Operator security review: `answers.operatorSecurityReview === true`.
+ *
+ *  The function is monotonic — once `databaseBranchPool` is `per-shard`, it stays
+ *  `per-shard`. Other DerivedGates fields are passed through unchanged.
+ *
+ *  Pure function — no I/O, no side-effects. The wizard wires it into
+ *  `runComplianceStep`; tests pin behavior directly.
+ */
+export function applyOq11TriggerChecklistUpgrade(inputGates, answers) {
+    const triggers = [];
+    // Trigger 1 (regulatory) — surfaces only when the gate was already
+    // upgraded upstream by a per-shard-forcing regime declaration.
+    if (inputGates.databaseBranchPool === 'per-shard') {
+        triggers.push('regulatory');
+    }
+    if (answers.customerContract) {
+        triggers.push('customer-contract');
+    }
+    if (answers.operatorSecurityReview) {
+        triggers.push('operator-security-review');
+    }
+    const upgraded = triggers.length > 0;
+    return {
+        derivedGates: upgraded ? { ...inputGates, databaseBranchPool: 'per-shard' } : { ...inputGates },
+        triggers,
+    };
+}
+/**
+ * Human-readable line for each trigger kind, shown in the wizard summary so
+ * the operator can see WHY the framework selected `per-shard`.
+ */
+export function describeOq11Trigger(kind) {
+    switch (kind) {
+        case 'regulatory':
+            return 'regulatory regime declared in .ai-sdlc/compliance.yaml (RFC-0022 derivedGates)';
+        case 'customer-contract':
+            return 'customer contract requires tenant physical isolation (operator-declared)';
+        case 'operator-security-review':
+            return 'operator security review identified a risk RLS cannot mitigate (operator-declared)';
+    }
+}
+/**
+ * Escape a string for safe embedding inside a YAML double-quoted scalar.
+ * YAML double-quoted strings treat `\` as an escape character, so backslashes
+ * must be escaped first, then double-quotes.  Escaping only `"` (without
+ * first escaping `\`) is an incomplete sanitization — a value like `foo\bar`
+ * would produce `"foo\bar"` where `\b` is a YAML escape sequence.
+ * (CodeQL js/incomplete-sanitization alerts #68, #69, #70.)
+ */
+function escapeYamlDoubleQuoted(value) {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+/**
+ * Build the .ai-sdlc/compliance.yaml content for a given compliance declaration.
+ *
+ * The written file contains the declared `spec.regimes` with attestation metadata.
+ * The computed `derivedGates` are added as YAML comments (read-only reference)
+ * so the loader continues to compute them from regimes (not from spec.derivedGates,
+ * which is the operator-override field requiring _notes for each entry).
+ *
+ * Pure function — no filesystem side-effects, fully testable.
+ */
+export function buildComplianceYaml(opts) {
+    const { projectName, regimes, attestedBy, attestedAt, attestedNotes, derivedGates } = opts;
+    // AISDLC-324 review fix: quote attestedBy/id/attestedAt so an operator
+    // git config user.email containing ": " or other YAML-significant chars
+    // can't break the YAML structure. Use escapeYamlDoubleQuoted() which
+    // escapes backslashes before quotes (incomplete-sanitization fix for
+    // CodeQL alerts #68/#69/#70).
+    const quotedAttestedBy = `"${escapeYamlDoubleQuoted(attestedBy)}"`;
+    const regimeItems = regimes
+        .map((id) => {
+        // id is from hardcoded COMPLIANCE_REGIME_CHOICES (validated upstream)
+        // so it's safe to emit unquoted; YAML-significant chars never reach here.
+        const lines = [
+            `    - id: ${id}`,
+            `      attestedBy: ${quotedAttestedBy}`,
+            `      attestedAt: "${escapeYamlDoubleQuoted(attestedAt)}"`,
+        ];
+        if (attestedNotes) {
+            lines.push(`      attestedNotes: "${escapeYamlDoubleQuoted(attestedNotes)}"`);
+        }
+        return lines.join('\n');
+    })
+        .join('\n');
+    const derivedGatesComment = [
+        '# --- Derived gates (computed from declared regimes; read-only) ---',
+        `# databaseBranchPool: ${derivedGates.databaseBranchPool}`,
+        `# secretScanStrictness: ${derivedGates.secretScanStrictness}`,
+        `# attestationRequired: ${derivedGates.attestationRequired}`,
+        `# auditRetentionDays: ${derivedGates.auditRetentionDays}`,
+        `# reviewerAuthorityModel: ${derivedGates.reviewerAuthorityModel}`,
+        '#',
+        '# To override a gate, add spec.derivedGates.<field> with a sibling _notes entry.',
+        '# See docs/operations/compliance-posture.md for override patterns.',
+    ].join('\n');
+    // AISDLC-324 review fix: avoid duplicate `regimes:` key when empty.
+    // Inline `[]` for empty case; emit block under `regimes:` for non-empty.
+    const regimesSection = regimes.length === 0 ? `  regimes: []` : `  regimes:\n${regimeItems}`;
+    return [
+        `apiVersion: ai-sdlc.io/v1alpha1`,
+        `kind: CompliancePosture`,
+        `metadata:`,
+        `  name: "${escapeYamlDoubleQuoted(projectName)}"`,
+        `spec:`,
+        regimesSection,
+        `  auditExports: []`,
+        '',
+        derivedGatesComment,
+        '',
+    ].join('\n');
+}
+/**
+ * Format the derived gates for console display (the "✓ Wrote ... with derived gates:" block).
+ */
+export function formatDerivedGatesDisplay(derivedGates) {
+    return [
+        `   databaseBranchPool: ${derivedGates.databaseBranchPool}`,
+        `   secretScanStrictness: ${derivedGates.secretScanStrictness}`,
+        `   attestationRequired: ${derivedGates.attestationRequired}`,
+        `   auditRetentionDays: ${derivedGates.auditRetentionDays}`,
+        `   reviewerAuthorityModel: ${derivedGates.reviewerAuthorityModel}`,
+    ].join('\n');
+}
+/**
+ * DB-pool rationale displayed when a compliance regime forces `per-shard`.
+ * Returns null if the DB-pool is `shared-with-rls` (no rationale needed).
+ */
+export function getDbPoolRationale(regimes, derivedGates) {
+    if (derivedGates.databaseBranchPool !== 'per-shard')
+        return null;
+    if (regimes.length === 0)
+        return null;
+    const forcingRegimes = regimes.filter((id) => INIT_WIZARD_REGIME_GATES[id]?.databaseBranchPool === 'per-shard');
+    if (forcingRegimes.length === 0)
+        return null;
+    return `  (${forcingRegimes.join(', ')} declared at .ai-sdlc/compliance.yaml requires per-shard isolation)`;
+}
+/**
+ * Run the compliance posture wizard step (RFC-0022 §7 / AISDLC-324).
+ *
+ * Inserted into the init wizard BEFORE the gate-config feature prompts.
+ * Always runs — even for unregulated projects (declaring "(none)" is the
+ * explicit choice; the resulting compliance.yaml carries that decision).
+ *
+ * Flow:
+ *  1. Auto-detect git config user.email for attestedBy default.
+ *  2. If --yes or non-TTY: use baseline (no regimes), auto-fill attestedBy.
+ *  3. Otherwise: multi-select regimes, text-input attestedBy + notes.
+ *  4. Compute derivedGates via inline tightest-wins composition.
+ *  5. Write .ai-sdlc/compliance.yaml (skips if file already exists and not
+ *     in --add compliance mode).
+ *  6. Log derived gates + DB-pool rationale.
+ */
+export async function runComplianceStep(projectDir, flags, adapters) {
+    const compliancePath = join(projectDir, '.ai-sdlc', 'compliance.yaml');
+    // ── Auto-detect git email for attestedBy default ──────────────────────
+    let gitEmail = '';
+    try {
+        const result = adapters.runCommand('git', ['config', 'user.email']);
+        if (result.exitCode === 0) {
+            gitEmail = result.stdout.trim();
+        }
+    }
+    catch {
+        // Ignore — git config may not be set; attestedBy will be empty default
+    }
+    // Resolve project name from git remote or directory basename.
+    const projectName = (() => {
+        try {
+            const r = adapters.runCommand('git', ['remote', 'get-url', 'origin']);
+            if (r.exitCode === 0) {
+                // Extract repo name from remote URL (ssh: git@github.com:org/repo.git, https: .../org/repo.git)
+                const m = r.stdout.trim().match(/\/([^/]+?)(\.git)?$/);
+                if (m)
+                    return m[1];
+            }
+        }
+        catch {
+            // Ignore
+        }
+        return basename(projectDir);
+    })();
+    // ── --yes / non-TTY path: baseline (no regimes, no triggers) ──────────
+    if (flags.yes || !process.stdin.isTTY) {
+        const derivedGates = computeInitWizardDerivedGates([]);
+        const attestedAt = new Date().toISOString();
+        const written = writeComplianceYaml({
+            projectDir,
+            compliancePath,
+            projectName,
+            regimes: [],
+            attestedBy: gitEmail,
+            attestedAt,
+            attestedNotes: undefined,
+            derivedGates,
+            flags,
+            adapters,
+        });
+        adapters.log('');
+        adapters.log(`  Compliance posture: no regimes declared (unregulated baseline)`);
+        adapters.log(`  derivedGates: ${JSON.stringify(derivedGates)}`);
+        return {
+            regimes: [],
+            attestedBy: gitEmail,
+            attestedAt,
+            attestedNotes: undefined,
+            derivedGates,
+            oq11Triggers: [],
+            yamlPath: compliancePath,
+            written,
+        };
+    }
+    // ── Interactive path ──────────────────────────────────────────────────
+    adapters.log('> Compliance posture');
+    adapters.log('');
+    const selectedRegimes = await adapters.multiSelect('Which regulatory regimes apply to this project? (space to toggle, enter to confirm)', COMPLIANCE_REGIME_CHOICES);
+    const attestedBy = await adapters.textInput('Who is attesting these regimes apply?', gitEmail || undefined);
+    const attestedNotesRaw = await adapters.textInput('Notes on the attestation (optional, audit-visible):', undefined);
+    const attestedNotes = attestedNotesRaw.trim() || undefined;
+    const attestedAt = new Date().toISOString();
+    const regimeDerivedGates = computeInitWizardDerivedGates(selectedRegimes);
+    // ── RFC-0009 §8.7 / OQ-11 trigger checklist (AISDLC-319) ──────────────
+    // Trigger 1 (regulatory) is already reflected in `regimeDerivedGates`;
+    // collect triggers 2 + 3 from the operator. The framework cannot auto-detect
+    // these (per RFC-0009 §8.7) — operator declares.
+    adapters.log('');
+    adapters.log('> DatabaseBranchPool trigger checklist (RFC-0009 §8.7)');
+    adapters.log('  Default is shared pool with row-level-security isolation. Answer Yes only');
+    adapters.log('  if the trigger actually applies — per-soul pools add operational complexity.');
+    const customerContract = await adapters.prompt('Does any customer contract require tenant physical isolation (independent of regulatory baseline)?', false);
+    const operatorSecurityReview = await adapters.prompt('Has operator security review identified a risk that RLS cannot mitigate?', false);
+    const triggerResult = applyOq11TriggerChecklistUpgrade(regimeDerivedGates, {
+        customerContract,
+        operatorSecurityReview,
+    });
+    const derivedGates = triggerResult.derivedGates;
+    const oq11Triggers = triggerResult.triggers;
+    const written = writeComplianceYaml({
+        projectDir,
+        compliancePath,
+        projectName,
+        regimes: selectedRegimes,
+        attestedBy,
+        attestedAt,
+        attestedNotes,
+        derivedGates,
+        flags,
+        adapters,
+    });
+    adapters.log('');
+    if (written) {
+        adapters.log(`✓ Wrote .ai-sdlc/compliance.yaml with derived gates:`);
+    }
+    else {
+        adapters.log(`  .ai-sdlc/compliance.yaml already exists — skipped (run --add compliance to update)`);
+        adapters.log(`  Derived gates (from existing compliance.yaml, if unchanged):`);
+    }
+    adapters.log(formatDerivedGatesDisplay(derivedGates));
+    // DB-pool rationale: surface BOTH the regime-derived rationale (AC #6) and
+    // the OQ-11 trigger checklist rationale (AISDLC-319 AC #2/#4).
+    const dbRationale = getDbPoolRationale(selectedRegimes, derivedGates);
+    if (dbRationale) {
+        adapters.log('');
+        adapters.log(`  DatabaseBranchPool pre-selection: per-shard`);
+        adapters.log(dbRationale);
+    }
+    else if (oq11Triggers.length > 0) {
+        // Triggers 2 / 3 fired but no regulatory trigger — explain the upgrade.
+        adapters.log('');
+        adapters.log(`  DatabaseBranchPool pre-selection: per-shard`);
+        adapters.log(`  (RFC-0009 §8.7 trigger fired:`);
+        for (const t of oq11Triggers) {
+            if (t === 'regulatory')
+                continue; // already covered by dbRationale path
+            adapters.log(`    - ${describeOq11Trigger(t)}`);
+        }
+        adapters.log(`  )`);
+    }
+    adapters.log('');
+    adapters.log(`  Review with: cat .ai-sdlc/compliance.yaml`);
+    adapters.log(`  Override any field with the attestedNotes pattern (see docs/operations/compliance-posture.md).`);
+    return {
+        regimes: selectedRegimes,
+        attestedBy,
+        attestedAt,
+        attestedNotes,
+        derivedGates,
+        oq11Triggers,
+        yamlPath: compliancePath,
+        written,
+    };
+}
+/** Helper: write .ai-sdlc/compliance.yaml (or skip if exists). Returns true if written. */
+function writeComplianceYaml(opts) {
+    const { compliancePath, flags, adapters } = opts;
+    if (flags.dryRun) {
+        adapters.log(`  would write .ai-sdlc/compliance.yaml`);
+        return false;
+    }
+    if (adapters.exists(compliancePath)) {
+        return false;
+    }
+    const yamlContent = buildComplianceYaml({
+        projectName: opts.projectName,
+        regimes: opts.regimes,
+        attestedBy: opts.attestedBy,
+        attestedAt: opts.attestedAt,
+        attestedNotes: opts.attestedNotes,
+        derivedGates: opts.derivedGates,
+    });
+    adapters.mkdirp(join(opts.projectDir, '.ai-sdlc'));
+    adapters.writeFile(compliancePath, yamlContent);
+    return true;
+}
 /** All feature flags off — used as the initial state before flags + prompts. */
 export const NO_FEATURES = {
     dor: false,
     attestation: false,
     classifier: false,
     branchProtection: false,
+    workflows: false,
+    signalIngestion: false,
 };
-/** All features on — the answer used by `--yes` (accept all defaults). */
+/**
+ * All features on — the answer used by `--yes` (accept all defaults).
+ *
+ * Note: `signalIngestion` is deliberately FALSE in this set even though
+ * `--yes` accepts all *defaults*. RFC-0030's pipeline is gated by the
+ * `AI_SDLC_SIGNAL_INGESTION` env flag during its soak window, and the
+ * shipped default for the flag is OFF. Scaffolding the config stub on a
+ * fresh adopter who hasn't opted in would be noise; the file is only
+ * meaningful when the operator has explicit interest. Adopters opt in
+ * via `--with-signal-ingestion` or `--add signal-ingestion`.
+ */
 export const ALL_FEATURES = {
     dor: true,
     attestation: true,
     classifier: true,
     branchProtection: true,
+    workflows: true,
+    signalIngestion: false,
 };
+/**
+ * Resolve the AI-SDLC install target directory for the current invocation
+ * (AISDLC-262).
+ *
+ * ## Default behavior (no `--workspace` flag)
+ *
+ * 1. Shell out to `git rev-parse --show-toplevel` to find the repo root.
+ *    - If the cwd is not inside a git repo, install at cwd (plain-dir
+ *      fallback — same as the pre-AISDLC-262 behavior).
+ * 2. If `<git-root>/.ai-sdlc/` **already exists**, refuse with a clear
+ *    "already installed at <root>; pass --workspace <name>" message so
+ *    the operator knows exactly what to do next.
+ * 3. Otherwise install at the git root.
+ *
+ * ## `--workspace <name>` mode
+ *
+ * The operator explicitly wants a per-workspace install at
+ * `packages/<name>/.ai-sdlc/` (or `<name>/.ai-sdlc/` if `packages/` does
+ * not exist under the git root). No nesting check is performed — the
+ * operator has opted in.
+ *
+ * ## Dry-run output
+ *
+ * The resolved `installDir` is logged by the caller on the FIRST output
+ * line so adopters can sanity-check the target before any files are written.
+ */
+export function resolveInstallTarget(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const configDirName = opts.configDirName ?? '.ai-sdlc';
+    const exists = opts.exists ?? existsSync;
+    // Resolve git root (or fall back to cwd when not in a git repo).
+    let gitRoot;
+    try {
+        const getToplevel = opts.gitShowToplevel ??
+            ((dir) => execSync(`git rev-parse --show-toplevel`, {
+                cwd: dir,
+                encoding: 'utf-8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+            }).trim());
+        gitRoot = getToplevel(cwd);
+    }
+    catch {
+        // Not inside a git repo — install at cwd (plain-dir fallback).
+        gitRoot = cwd;
+    }
+    if (opts.workspace) {
+        // Per-workspace install: `<git-root>/packages/<name>` if packages/ exists,
+        // otherwise `<git-root>/<name>`.
+        const packagesDir = join(gitRoot, 'packages');
+        const workspaceBase = exists(packagesDir) ? packagesDir : gitRoot;
+        const installDir = join(workspaceBase, opts.workspace);
+        return { installDir, resolved: installDir !== cwd };
+    }
+    // Default: install at git root. If `.ai-sdlc/` already exists there,
+    // refuse with a helpful message — UNLESS `skipExistingCheck` is set
+    // (used by `--add <feature>`, which intentionally extends an existing
+    // install and thus expects the directory to already be present).
+    const rootConfigDir = join(gitRoot, configDirName);
+    if (exists(rootConfigDir) && !opts.skipExistingCheck) {
+        return {
+            installDir: gitRoot,
+            resolved: gitRoot !== cwd,
+            error: `AI-SDLC is already installed at ${gitRoot}; ` +
+                `pass --workspace <name> to add a child install at packages/<name>/.ai-sdlc/`,
+        };
+    }
+    return { installDir: gitRoot, resolved: gitRoot !== cwd };
+}
 // ── Production adapter factory ───────────────────────────────────────────
 /**
  * Build the production adapter bag. Pulled into a factory so tests can
@@ -55,6 +584,17 @@ export function buildProductionAdapters() {
             const { confirm } = await import('@inquirer/prompts');
             return confirm({ message: question, default: defaultYes });
         },
+        multiSelect: async (question, choices) => {
+            const { checkbox } = await import('@inquirer/prompts');
+            return checkbox({
+                message: question,
+                choices: choices.map((c) => ({ name: c.label, value: c.value })),
+            });
+        },
+        textInput: async (question, defaultValue) => {
+            const { input } = await import('@inquirer/prompts');
+            return input({ message: question, default: defaultValue });
+        },
         writeFile: (path, contents) => writeFileSync(path, contents, 'utf-8'),
         appendOnce: (path, contents, sentinel) => {
             // Make sure the parent dir exists (appendFileSync errors with ENOENT
@@ -129,6 +669,12 @@ export async function resolveFeatureSelection(flags, adapters) {
             case 'branch-protection':
                 sel.branchProtection = true;
                 break;
+            case 'workflows':
+                sel.workflows = true;
+                break;
+            case 'signal-ingestion':
+                sel.signalIngestion = true;
+                break;
         }
         return sel;
     }
@@ -136,6 +682,18 @@ export async function resolveFeatureSelection(flags, adapters) {
     if (flags.yes) {
         return { ...ALL_FEATURES };
     }
+    // ── Path 2b: non-TTY auto-fall-through ────────────────────────────────
+    // When stdin is not a TTY (CI runners, agent bash, piped input, Docker
+    // containers without `-it`), interactive prompts hang then throw an
+    // unhandled ExitPromptError. Auto-fall-through to ALL_FEATURES (same
+    // as --yes) so adopters can run `ai-sdlc init` in CI without any
+    // additional flags. This matches the documented behavior of --yes, which
+    // is defined as "accept all defaults non-interactively".
+    if (!process.stdin.isTTY) {
+        adapters.log('Non-TTY stdin detected — auto-accepting all feature defaults (equivalent to --yes).');
+        adapters.log('Pass --yes explicitly to suppress this message.');
+        return { ...ALL_FEATURES };
+    }
     // ── Path 3+4: `--with-X` overrides + prompts for the rest ─────────────
     const sel = { ...NO_FEATURES };
     // DoR
@@ -166,6 +724,24 @@ export async function resolveFeatureSelection(flags, adapters) {
     else {
         sel.branchProtection = await adapters.prompt('Apply recommended branch protection? (required: ai-sdlc/pr-ready + codecov/patch)', true);
     }
+    // GitHub Actions workflows bundle (AISDLC-261)
+    if (flags.withWorkflows) {
+        sel.workflows = true;
+    }
+    else {
+        sel.workflows = await adapters.prompt('Scaffold GitHub Actions workflows (gate, review, attestation, auto-merge)?', true);
+    }
+    // RFC-0030 Signal Ingestion Pipeline (AISDLC-348)
+    // Default to FALSE in the interactive prompt: the pipeline is in a soak
+    // window gated by AI_SDLC_SIGNAL_INGESTION; scaffolding the config on a
+    // fresh adopter who hasn't opted in is noise. Opt-in path: --with-signal-
+    // ingestion or --add signal-ingestion.
+    if (flags.withSignalIngestion) {
+        sel.signalIngestion = true;
+    }
+    else {
+        sel.signalIngestion = await adapters.prompt('Scaffold RFC-0030 signal-ingestion config (default OFF; opt in via AI_SDLC_SIGNAL_INGESTION soak)?', false);
+    }
     return sel;
 }
 /**
@@ -176,12 +752,18 @@ export async function resolveFeatureSelection(flags, adapters) {
  * Idempotent: any file that already exists at the target path is skipped
  * with a "skip" log line. This is what makes `--add <feature>` safe to
  * run on an already-initialized repo (AC #7).
+ *
+ * The `workflows` feature (AISDLC-261) supports `--force` to overwrite
+ * existing workflow files with the current template versions. Use this
+ * to upgrade a pre-261 repo to the full workflow bundle.
  */
 export async function applyFeatureSelection(projectDir, selection, flags, adapters) {
     const result = { created: [], skipped: [], wouldCreate: [] };
     // Build the union of templates to write.
     const templateSets = [];
     // `--add` mode: skip the baseline (we're EXTENDING an existing init).
+    // Exception: `--add workflows` must write the workflows bundle even in
+    // --add mode (the bundle IS the feature; it's not an extension of baseline).
     if (!flags.add) {
         templateSets.push(BASELINE_WORKFLOW_TEMPLATES);
     }
@@ -191,15 +773,36 @@ export async function applyFeatureSelection(projectDir, selection, flags, adapte
         templateSets.push(ATTESTATION_TEMPLATES);
     if (selection.classifier)
         templateSets.push(CLASSIFIER_TEMPLATES);
+    if (selection.workflows)
+        templateSets.push(WORKFLOWS_TEMPLATES);
+    if (selection.signalIngestion)
+        templateSets.push(SIGNAL_INGESTION_TEMPLATES);
+    // AISDLC-261 PR #480 review fix: dedupe across template sets so e.g.
+    // `ai-sdlc-gate.yml` (in BOTH BASELINE_WORKFLOW_TEMPLATES and
+    // WORKFLOWS_TEMPLATES) doesn't get written twice on
+    // `--with-workflows --force` (which would log "overwrite ${relPath}
+    // (--force)" against the duplicate, doubling result.created entries).
+    // First-set wins (BASELINE comes first, then feature bundles).
+    const seenRelPaths = new Set();
     for (const set of templateSets) {
         for (const [relPath, contents] of Object.entries(set.files)) {
+            if (seenRelPaths.has(relPath))
+                continue;
+            seenRelPaths.add(relPath);
             const absPath = join(projectDir, relPath);
             if (flags.dryRun) {
+                const isWorkflowFileDry = relPath.startsWith('.github/workflows/');
+                const wouldForce = isWorkflowFileDry && flags.force && adapters.exists(absPath);
                 result.wouldCreate.push(relPath);
-                adapters.log(`  would create ${relPath}`);
+                adapters.log(wouldForce ? `  would overwrite ${relPath} (--force)` : `  would create ${relPath}`);
                 continue;
             }
-            if (adapters.exists(absPath)) {
+            // For the workflows feature: `--force` overwrites existing files.
+            // For all other features: existing files are always skipped (idempotent).
+            const isWorkflowFile = relPath.startsWith('.github/workflows/');
+            const shouldForce = isWorkflowFile && flags.force;
+            const alreadyExists = adapters.exists(absPath);
+            if (alreadyExists && !shouldForce) {
                 result.skipped.push(relPath);
                 adapters.log(`  skip ${relPath} (already exists)`);
                 continue;
@@ -208,7 +811,12 @@ export async function applyFeatureSelection(projectDir, selection, flags, adapte
             adapters.mkdirp(dirname(absPath));
             adapters.writeFile(absPath, contents);
             result.created.push(relPath);
-            adapters.log(`  created ${relPath}`);
+            if (alreadyExists && shouldForce) {
+                adapters.log(`  overwrite ${relPath} (--force)`);
+            }
+            else {
+                adapters.log(`  created ${relPath}`);
+            }
         }
     }
     // Husky pre-push sign hook is a separate concern from the
@@ -402,6 +1010,38 @@ export function renderNextSteps(selection, result, adapters) {
         lines.push('');
         stepN++;
     }
+    if (selection.workflows) {
+        lines.push(`${stepN}. GitHub Actions workflows were scaffolded into .github/workflows/.`);
+        lines.push('     Four files are now in place:');
+        lines.push('       - ai-sdlc-gate.yml       — ai-sdlc/pr-ready rollup check');
+        lines.push('       - verify-attestation.yml  — DSSE attestation verifier (audit-only)');
+        lines.push('       - ai-sdlc-review.yml      — PR review status (stub: wire your reviewers)');
+        lines.push('       - auto-enable-auto-merge.yml — arms auto-merge on same-repo PRs');
+        lines.push('     To activate auto-merge:');
+        lines.push('       a) Enable "Allow auto-merge" in GitHub Settings → General.');
+        lines.push('       b) Set the AI_SDLC_PAT secret with write access to the repo.');
+        lines.push('     Re-run with --force to overwrite workflows on a pre-261 repo:');
+        lines.push('       ai-sdlc init --add workflows --force');
+        lines.push('');
+        stepN++;
+    }
+    if (selection.signalIngestion) {
+        lines.push(`${stepN}. RFC-0030 signal-ingestion config was scaffolded (DISABLED by default).`);
+        lines.push('     .ai-sdlc/signal-ingestion.yaml ships every block commented-out under');
+        lines.push('     enabled: false. The pipeline is gated by BOTH the YAML toggle AND the');
+        lines.push('     AI_SDLC_SIGNAL_INGESTION env flag during the soak window.');
+        lines.push('     To opt in:');
+        lines.push('       a) Read docs/operations/signal-ingestion.md (adapter setup +');
+        lines.push('          tier-multiplier + SA-threshold tuning + manual entry workflow).');
+        lines.push('       b) Set AI_SDLC_SIGNAL_INGESTION=1 in your shell / CI env.');
+        lines.push('       c) Edit .ai-sdlc/signal-ingestion.yaml, set spec.enabled: true,');
+        lines.push('          uncomment the adapters block, and confirm tier multipliers.');
+        lines.push('     Config edits emit SignalIngestionConfigChanged governance events to');
+        lines.push('     <ARTIFACTS_DIR>/_orchestrator/events-YYYY-MM-DD.jsonl.');
+        lines.push('     Promotion runbook: docs/operations/signal-ingestion-promotion.md');
+        lines.push('');
+        stepN++;
+    }
     if (selection.branchProtection) {
         if (result.branchProtection?.applied) {
             lines.push(`${stepN}. Branch protection on \`main\` was updated.`);