@ai-sdlc/orchestrator 0.10.0 → 0.13.0

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

@@ -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
@@ -18,16 +19,204 @@
  * up a TTY or shelling out to `gh`. Production callers in `init.ts` pass
  * the real adapters.
  */
+import type { DerivedGates } from '../../compliance/types.js';
+/**
+ * A single regulatory regime option shown in the init wizard multi-select.
+ */
+export interface ComplianceRegimeChoice {
+    /** Canonical regime identifier (e.g. 'HIPAA', 'SOC2-T2'). */
+    value: string;
+    /** Human-readable label shown in the prompt. */
+    label: string;
+}
+/**
+ * Canonical list of regulatory regimes presented in the compliance wizard.
+ * Mirrors the entries in spec/compliance/regime-mappings.yaml.
+ */
+export declare const COMPLIANCE_REGIME_CHOICES: readonly ComplianceRegimeChoice[];
+/**
+ * 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 declare function computeInitWizardDerivedGates(regimes: string[]): DerivedGates;
+/**
+ * RFC-0009 §8.7 enumerates THREE triggers under which the framework's
+ * `shared-with-rls` default for `DatabaseBranchPool` is INSUFFICIENT and the
+ * operator MUST upgrade to a per-soul (`per-shard`) pool:
+ *
+ *  1. **Regulatory hard requirement** — HIPAA / PCI-DSS L1 / FedRAMP /
+ *     SOC2-with-physical-isolation / regional data residency. The compliance
+ *     posture wizard already drives this trigger via `INIT_WIZARD_REGIME_GATES`
+ *     (regimes → `databaseBranchPool: 'per-shard'` on `DerivedGates`).
+ *
+ *  2. **Customer contract** — a vendor agreement explicitly requires tenant
+ *     physical isolation, independent of regulatory baseline. Adopter-declared
+ *     during `init`; not derivable from RFC-0022.
+ *
+ *  3. **Operator security review** — an explicit risk identified during
+ *     operator security review that RLS cannot mitigate (side-channel,
+ *     supply-chain, regulator pre-approval gap). Adopter-declared during
+ *     `init`; not derivable from RFC-0022.
+ *
+ *  If ANY trigger fires → per-soul pool is required. Triggers 2 + 3 are
+ *  opt-in answers the init wizard collects directly; trigger 1 is computed
+ *  from declared regimes upstream.
+ *
+ *  Per RFC-0009 OQ-11 resolution (2026-05-04): the framework cannot
+ *  auto-detect triggers 2 and 3 — the operator declares them via the wizard
+ *  checklist.
+ */
+export type Oq11TriggerKind = 'regulatory' | 'customer-contract' | 'operator-security-review';
+/**
+ * Adopter-declared answers for triggers 2 + 3 of the §8.7 checklist.
+ * Trigger 1 (regulatory) is sourced from declared regimes, not from this bag.
+ */
+export interface Oq11TriggerAnswers {
+    /** Trigger 2 — customer contract requires tenant physical isolation. */
+    customerContract: boolean;
+    /** Trigger 3 — operator security review identified a risk RLS cannot mitigate. */
+    operatorSecurityReview: boolean;
+}
+/**
+ * Result of applying the OQ-11 trigger checklist on top of regime-derived gates.
+ */
+export interface Oq11TriggerChecklistResult {
+    /** The (possibly upgraded) DerivedGates. `databaseBranchPool` is `per-shard` when any trigger fires. */
+    derivedGates: DerivedGates;
+    /** Names of the triggers that fired (empty when none fire — shared-with-rls remains). */
+    triggers: Oq11TriggerKind[];
+}
+/**
+ * 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 declare function applyOq11TriggerChecklistUpgrade(inputGates: DerivedGates, answers: Oq11TriggerAnswers): Oq11TriggerChecklistResult;
+/**
+ * Human-readable line for each trigger kind, shown in the wizard summary so
+ * the operator can see WHY the framework selected `per-shard`.
+ */
+export declare function describeOq11Trigger(kind: Oq11TriggerKind): string;
+/**
+ * Result of the compliance posture wizard step.
+ */
+export interface ComplianceStepResult {
+    /** Regime IDs declared by the operator (empty = "(none declared)" baseline). */
+    regimes: string[];
+    /** Who attested the regimes apply. Auto-filled from git config user.email. */
+    attestedBy: string;
+    /** ISO-8601 timestamp of attestation. Auto-filled at wizard run time. */
+    attestedAt: string;
+    /** Optional operator rationale for the attestation. */
+    attestedNotes?: string;
+    /** Derived gate values computed from the declared regimes (+ §8.7 trigger upgrade). */
+    derivedGates: DerivedGates;
+    /**
+     * Triggers from the RFC-0009 §8.7 / OQ-11 checklist that fired during this
+     * wizard run (empty when none fired — shared-with-rls is sufficient).
+     */
+    oq11Triggers: Oq11TriggerKind[];
+    /** Absolute path of the written compliance.yaml file. */
+    yamlPath: string;
+    /** True if compliance.yaml was written; false in dry-run or if already exists. */
+    written: boolean;
+}
+/**
+ * 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 declare function buildComplianceYaml(opts: {
+    projectName: string;
+    regimes: string[];
+    attestedBy: string;
+    attestedAt: string;
+    attestedNotes?: string;
+    derivedGates: DerivedGates;
+}): string;
+/**
+ * Format the derived gates for console display (the "✓ Wrote ... with derived gates:" block).
+ */
+export declare function formatDerivedGatesDisplay(derivedGates: DerivedGates): string;
+/**
+ * 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 declare function getDbPoolRationale(regimes: string[], derivedGates: DerivedGates): string | null;
+/**
+ * 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 declare function runComplianceStep(projectDir: string, flags: WizardFlags, adapters: FeatureAdapters): Promise<ComplianceStepResult>;
 /** Per-feature on/off bits derived from prompts + flags. */
 export interface FeatureSelection {
     dor: boolean;
     attestation: boolean;
     classifier: boolean;
     branchProtection: boolean;
+    /**
+     * `workflows` — scaffold the full GitHub Actions workflow bundle
+     * (ai-sdlc-gate, verify-attestation, ai-sdlc-review, auto-enable-auto-merge).
+     * Enabled by `--with-workflows` flag or `--add workflows` subcommand (AISDLC-261).
+     */
+    workflows: boolean;
+    /**
+     * `signalIngestion` — scaffold the RFC-0030 signal-ingestion config stub at
+     * `.ai-sdlc/signal-ingestion.yaml` (Phase 6 / AISDLC-348). The file ships
+     * `enabled: false`; the pipeline runtime stays dark until the operator
+     * explicitly flips it AND opts in via `AI_SDLC_SIGNAL_INGESTION` during
+     * the soak window. Default OFF in `--yes` mode (per the soak convention)
+     * but available via `--with-signal-ingestion` / `--add signal-ingestion`.
+     */
+    signalIngestion: boolean;
 }
 /** All feature flags off — used as the initial state before flags + prompts. */
 export declare const NO_FEATURES: FeatureSelection;
-/** 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 declare const ALL_FEATURES: FeatureSelection;
 /** Flag-bag controlling wizard behavior (already parsed from argv). */
 export interface WizardFlags {
@@ -41,14 +230,41 @@ export interface WizardFlags {
     withClassifier: boolean;
     /** `--with-branch-protection` forces branch-protection on without prompting. */
     withBranchProtection: boolean;
+    /**
+     * `--with-workflows` scaffolds the full GitHub Actions workflow bundle
+     * (ai-sdlc-gate, verify-attestation, ai-sdlc-review, auto-enable-auto-merge)
+     * without prompting (AISDLC-261).
+     */
+    withWorkflows: boolean;
+    /**
+     * `--with-signal-ingestion` scaffolds the RFC-0030 signal-ingestion config
+     * stub at `.ai-sdlc/signal-ingestion.yaml` without prompting (AISDLC-348).
+     * The file ships `enabled: false`; the pipeline stays dark until the
+     * operator explicitly opts in. Always OFF by default in `--yes` mode.
+     */
+    withSignalIngestion: boolean;
     /**
      * `--add <feature>` extends an already-initialized repo with a single
      * feature without re-prompting. AC #7 (idempotent extension). When set,
      * the wizard short-circuits to scaffold ONLY this feature.
      */
-    add?: 'dor' | 'attestation' | 'classifier' | 'branch-protection';
+    add?: 'dor' | 'attestation' | 'classifier' | 'branch-protection' | 'workflows' | 'signal-ingestion';
     /** `--dry-run` — print what would be done, don't write. */
     dryRun: boolean;
+    /**
+     * `--workspace <name>` opts into a per-workspace install at
+     * `packages/<name>/.ai-sdlc/` instead of the git-root default.
+     * Only relevant when the git root already has an `.ai-sdlc/` directory
+     * (e.g. the repo root already has AI-SDLC installed and the operator
+     * wants to add a child-workspace install). Without this flag, init
+     * refuses to nest if the git root already has `.ai-sdlc/`.
+     */
+    workspace?: string;
+    /**
+     * `--force` — when set, overwrite workflow files that already exist instead
+     * of skipping them. Only applies to the `workflows` feature (AISDLC-261).
+     */
+    force: boolean;
 }
 /**
  * Single-question prompter contract — accepts a question + default and
@@ -91,7 +307,86 @@ export interface FeatureAdapters {
     };
     /** Sink for operator-visible output (defaults to console.log). */
     log: (line: string) => void;
+    /**
+     * Multi-select prompt — returns the array of selected choice values.
+     * Production adapter uses `@inquirer/prompts` `checkbox`.
+     * Tests inject a stub that returns scripted selections.
+     */
+    multiSelect: (question: string, choices: ComplianceRegimeChoice[]) => Promise<string[]>;
+    /**
+     * Text input prompt — returns the entered string.
+     * Production adapter uses `@inquirer/prompts` `input`.
+     * Tests inject a stub that returns scripted values.
+     */
+    textInput: (question: string, defaultValue?: string) => Promise<string>;
+}
+/**
+ * Result returned by `resolveInstallTarget`. The caller uses `installDir`
+ * as the `projectDir` argument passed down to `initProject` and the wizard
+ * stage. The `resolved` flag is true when the target differs from `cwd`
+ * (i.e. we walked up to the git root).
+ */
+export interface InstallTargetResult {
+    /** Absolute path to the directory where `.ai-sdlc/` should be written. */
+    installDir: string;
+    /** True when `installDir !== cwd` (we resolved up to the git root). */
+    resolved: boolean;
+    /** Error message when the target is refused; installDir is unset in this case. */
+    error?: string;
 }
+/**
+ * Options bag for `resolveInstallTarget`. Adapters allow tests to inject
+ * controlled filesystem / subprocess behaviour without touching real disk.
+ */
+export interface ResolveInstallTargetOptions {
+    /** Working directory to start from (defaults to `process.cwd()`). */
+    cwd?: string;
+    /** The `--workspace <name>` flag value, if provided. */
+    workspace?: string;
+    /** Config directory name (defaults to `.ai-sdlc`). */
+    configDirName?: string;
+    /**
+     * Override for `git rev-parse --show-toplevel`. Receives the cwd and
+     * returns the git root path, or throws if not inside a git repo.
+     */
+    gitShowToplevel?: (cwd: string) => string;
+    /** Override for existence checks (defaults to `node:fs.existsSync`). */
+    exists?: (path: string) => boolean;
+    /**
+     * When true, skip the "already installed at <root>" nesting check.
+     * Used by the `--add <feature>` extension path, which intentionally
+     * extends an already-initialized repo (the existing `.ai-sdlc/` IS
+     * the install the operator wants to extend).
+     */
+    skipExistingCheck?: boolean;
+}
+/**
+ * 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 declare function resolveInstallTarget(opts?: ResolveInstallTargetOptions): InstallTargetResult;
 /**
  * Build the production adapter bag. Pulled into a factory so tests can
  * compose a partial override bag (e.g. only override `prompt`) and let
@@ -135,6 +430,10 @@ export interface ApplyResult {
  * 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 declare function applyFeatureSelection(projectDir: string, selection: FeatureSelection, flags: WizardFlags, adapters: FeatureAdapters): Promise<ApplyResult>;
 export interface BranchProtectionResult {