@ai-sdlc/orchestrator 0.9.0 → 0.13.0

package/dist/compliance/types.d.ts

@@ -0,0 +1,184 @@
+/**
+ * TypeScript interfaces for the CompliancePosture resource (RFC-0022 §5).
+ *
+ * Lives at .ai-sdlc/compliance.yaml; schema at
+ * spec/schemas/compliance-posture.v1.schema.json.
+ *
+ * Design notes:
+ * - Loader returns CompliancePosture[] (single-element list in v1) per OQ-6
+ *   so v2 multi-tenant composition is additive — not a breaking API change.
+ * - derivedGates overrides require a sibling _notes map (OQ-2 enforcement).
+ * - All regime declarations require attestedBy + attestedAt (legal claim
+ *   discipline — loader rejects postures missing either field).
+ */
+/**
+ * A single regulatory regime declaration with attestation metadata.
+ *
+ * Convention for `id`: '<framework>-<tier-or-version>'.
+ * Examples: 'SOC2-T2', 'HIPAA', 'PCI-DSS-L1', 'GDPR', 'FedRAMP-Moderate', 'ISO-27001:2022'.
+ */
+export interface Regime {
+    /**
+     * Canonical regime identifier.
+     * Convention: '<framework>-<tier-or-version>'.
+     * Examples: 'SOC2-T2', 'HIPAA', 'PCI-DSS-L1', 'GDPR', 'FedRAMP-Moderate', 'ISO-27001:2022'.
+     */
+    id: string;
+    /**
+     * Optional explicit control list from the regime the adopter is claiming coverage for.
+     * Examples: ['CC6.6', 'CC8.1'] for SOC2; ['§164.308(a)(4)', '§164.312(a)'] for HIPAA.
+     * Used by the audit export to slice evidence per control.
+     */
+    controls?: string[];
+    /**
+     * Audit cadence — drives default retention windows and export pre-staging.
+     */
+    auditFrequency?: 'annual' | 'continuous' | 'on-demand';
+    /**
+     * Who declared this regime applies.
+     * E.g., 'Acme Legal LLP' or a contributor name.
+     * REQUIRED in v1: framework refuses to load a posture with regimes lacking attestation
+     * metadata (forces explicit operator/legal sign-off on each declaration).
+     */
+    attestedBy: string;
+    /**
+     * ISO 8601 date when the regime was attested.
+     * REQUIRED in v1 (same rationale as attestedBy).
+     */
+    attestedAt: string;
+    /**
+     * Operator's rationale for declaring this regime.
+     * Recommended for audit trail; not enforced by loader but strongly encouraged.
+     */
+    attestedNotes?: string;
+}
+/**
+ * Gate values derived from declared regimes.
+ * When multiple regimes are declared, tightest constraint wins per axis (RFC-0022 §6).
+ */
+export interface DerivedGates {
+    /**
+     * Per RFC-0009 OQ-11.
+     * 'shared-with-rls' = single Postgres branch with row-level security tenant isolation.
+     * 'per-shard' = one branch per shard / customer.
+     */
+    databaseBranchPool: 'shared-with-rls' | 'per-shard';
+    /**
+     * Per AISDLC-128.
+     * 'minimal' = framework-default patterns only.
+     * 'standard' = + common cloud provider keys.
+     * 'strict' = + entropy-based detection + adopter-supplied custom patterns.
+     */
+    secretScanStrictness: 'minimal' | 'standard' | 'strict';
+    /**
+     * Per AISDLC-74/146.
+     * When true, framework refuses to merge PRs without a valid DSSE attestation envelope at HEAD.
+     */
+    attestationRequired: boolean;
+    /**
+     * Floor for log retention in days.
+     * Framework keeps logs for at least this many days; GC by mtime.
+     */
+    auditRetentionDays: number;
+    /**
+     * Per config/trusted-reviewers.yaml.
+     * 'open' = any GitHub user can act as reviewer.
+     * 'allowlist' = explicit reviewer list; identity-only check.
+     * 'allowlist+role' = allowlist + per-role authority (review vs approve vs admin).
+     */
+    reviewerAuthorityModel: 'open' | 'allowlist' | 'allowlist+role';
+}
+/**
+ * Operator-supplied partial overrides for DerivedGates.
+ *
+ * Per OQ-2: each overridden field MUST have a corresponding non-empty entry
+ * in the sibling `_notes` map. The loader rejects any override missing notes.
+ *
+ * The `_notes` field is a sibling map keyed by field name to keep the override
+ * values themselves typed and to make the notes audit-traceable.
+ */
+export type PartialDerivedGatesOverrides = Partial<Omit<DerivedGates, never>> & {
+    /**
+     * Notes for each overridden gate field.
+     * Key = gate field name (e.g. 'databaseBranchPool').
+     * Value = non-empty rationale string.
+     * Loader rejects any gate field override whose corresponding _notes entry is missing or empty.
+     */
+    _notes?: Record<string, string>;
+};
+/**
+ * Specification for a single evidence bundle included in `cli-compliance-audit export`.
+ */
+export interface AuditExportSpec {
+    /**
+     * Which kind of evidence to include in the export bundle.
+     */
+    kind: 'dsse-envelope' | 'dor-calibration' | 'trusted-reviewers' | 'enforcement-events' | 'access-control-changes';
+    /**
+     * Output format for this evidence bundle.
+     */
+    format: 'json' | 'jsonl' | 'csv';
+    /**
+     * Retention policy for this evidence bundle.
+     */
+    retentionPolicy: {
+        /**
+         * Retention floor in days. Framework GC removes after `days + grace`.
+         */
+        days: number;
+        /**
+         * hot = on local disk; cold = expected to be archived externally.
+         */
+        tier?: 'hot' | 'cold';
+    };
+}
+/**
+ * The CompliancePosture resource.
+ *
+ * Lives at .ai-sdlc/compliance.yaml.
+ * Schema at spec/schemas/compliance-posture.v1.schema.json.
+ *
+ * Adopters declare which regulatory regimes apply; the framework derives gate
+ * defaults from those regimes and uses this posture to drive attestation
+ * requirements, secret-scan strictness, DB pool isolation, and audit-export
+ * configuration.
+ */
+export interface CompliancePosture {
+    apiVersion: 'ai-sdlc.io/v1alpha1';
+    kind: 'CompliancePosture';
+    metadata: {
+        /** Canonical project identifier. DNS-label format. */
+        name: string;
+        namespace?: string;
+        labels?: Record<string, string>;
+        annotations?: Record<string, string>;
+    };
+    spec: {
+        /**
+         * Declared regulatory posture. Empty array means "(none declared)" — baseline posture applies.
+         * Baseline: shared-with-rls, minimal, attestationRequired=false, 90d retention, open reviewer model.
+         */
+        regimes: Regime[];
+        /**
+         * Operator overrides for derived gate values.
+         * Each overridden field requires a non-empty _notes entry (OQ-2).
+         * The loader rejects any override missing a notes entry.
+         */
+        derivedGates?: PartialDerivedGatesOverrides;
+        /**
+         * Evidence bundles to produce on `cli-compliance-audit export`.
+         */
+        auditExports: AuditExportSpec[];
+    };
+}
+/**
+ * The "(none declared)" baseline DerivedGates — applies when no regimes are declared.
+ * Matches pre-RFC-0022 framework behavior (no gate changes for existing projects).
+ */
+export declare const BASELINE_DERIVED_GATES: Readonly<DerivedGates>;
+/**
+ * The "(none declared)" baseline CompliancePosture — returned when no
+ * .ai-sdlc/compliance.yaml exists (AC #6 / OQ-6 backward-compat).
+ */
+export declare const BASELINE_POSTURE: Readonly<CompliancePosture>;
+//# sourceMappingURL=types.d.ts.map

package/dist/compliance/types.js

@@ -0,0 +1,41 @@
+/**
+ * TypeScript interfaces for the CompliancePosture resource (RFC-0022 §5).
+ *
+ * Lives at .ai-sdlc/compliance.yaml; schema at
+ * spec/schemas/compliance-posture.v1.schema.json.
+ *
+ * Design notes:
+ * - Loader returns CompliancePosture[] (single-element list in v1) per OQ-6
+ *   so v2 multi-tenant composition is additive — not a breaking API change.
+ * - derivedGates overrides require a sibling _notes map (OQ-2 enforcement).
+ * - All regime declarations require attestedBy + attestedAt (legal claim
+ *   discipline — loader rejects postures missing either field).
+ */
+// ── Baseline ──────────────────────────────────────────────────────────────
+/**
+ * The "(none declared)" baseline DerivedGates — applies when no regimes are declared.
+ * Matches pre-RFC-0022 framework behavior (no gate changes for existing projects).
+ */
+export const BASELINE_DERIVED_GATES = {
+    databaseBranchPool: 'shared-with-rls',
+    secretScanStrictness: 'minimal',
+    attestationRequired: false,
+    auditRetentionDays: 90,
+    reviewerAuthorityModel: 'open',
+};
+/**
+ * The "(none declared)" baseline CompliancePosture — returned when no
+ * .ai-sdlc/compliance.yaml exists (AC #6 / OQ-6 backward-compat).
+ */
+export const BASELINE_POSTURE = {
+    apiVersion: 'ai-sdlc.io/v1alpha1',
+    kind: 'CompliancePosture',
+    metadata: {
+        name: 'baseline',
+    },
+    spec: {
+        regimes: [],
+        auditExports: [],
+    },
+};
+//# sourceMappingURL=types.js.map

package/dist/compliance-clearance.d.ts

@@ -0,0 +1,269 @@
+/**
+ * RFC-0009 Phase 4.1 — Eρ₅ Compliance Clearance scoring.
+ *
+ * Implements the categorical 0/1 gating dimension from RFC-0009 §7.1:
+ *
+ *   Eρ₅ = soul.triad.engineering.complianceRegimes[].clearance(work_item)
+ *       = 0 if any named regime is violated
+ *       = 1 otherwise
+ *
+ * **OQ-5 scope** (v3.3 resolution, 2026-05-03): HARD regulatory frameworks
+ * ONLY — anything with formal external-audit consequences. Internal best
+ * practices, code style, architectural preferences, and team conventions are
+ * OUT OF SCOPE and rejected at declaration time per the boundary test:
+ * "would an external regulator or auditor have grounds to act on a violation?"
+ *
+ *   In scope:
+ *     - GDPR (EU data protection)
+ *     - HIPAA (US healthcare)
+ *     - SOC2 (audit trust framework — variants like SOC2-T2 accepted)
+ *     - PCI-DSS (payment card data — variants like PCI-DSS-L1 accepted)
+ *     - FedRAMP (US federal cloud — variants like FedRAMP-Moderate accepted)
+ *     - Regional data-residency (Schrems II, EU data-localization, China PIPL,
+ *       Canadian PIPEDA cross-border)
+ *     - Regulated-industry rules (financial KYC/AML, healthcare device
+ *       certification, telecom regulations, ISO-27001 audit framework, etc.)
+ *
+ *   Out of scope (rejected at declaration time):
+ *     - Internal best-practices ("clean-code", "team-style", "house-style")
+ *     - Code-quality rules ("eslint-recommended", "prettier-standard")
+ *     - Architectural preferences ("hexagonal", "ddd-strict")
+ *     - Team conventions ("our-conventions", "internal-coding-standard")
+ *
+ * **Adopter opt-in gate** (RFC-0009 §10 Phase 4): Eρ₅ is gated behind
+ * `ComplianceClearanceContext.enabled === true` initially. Promotion to
+ * default behavior is subject to ecosystem feedback. When disabled (default),
+ * the admission composite does not apply the Eρ₅ multiplier and behaves
+ * exactly as in Phase 2/3 — full backward compatibility.
+ *
+ * **RFC-0022 consumption surface**: when an adopter wires the loaded
+ * `CompliancePosture[]` into `ComplianceClearanceContext.posture`, the
+ * declared regimes from that resource compose with the soul's own
+ * `complianceRegimes` field. Both sources contribute to the regime set
+ * the work item is checked against; clearance is gating across the union.
+ *
+ * @see spec/rfcs/RFC-0009-tessellated-design-intent-documents.md §7.1 + §10
+ * @see spec/rfcs/RFC-0022-compliance-posture-audit-surface.md (consumption surface)
+ */
+import type { CompliancePosture } from './compliance/types.js';
+/**
+ * Canonical hard-regulatory framework prefixes per RFC-0009 §7.1 OQ-5 resolution.
+ *
+ * Matching is **prefix-based** to accept variants like `SOC2-T2`, `PCI-DSS-L1`,
+ * `FedRAMP-Moderate`, `FedRAMP-High`, `ISO-27001:2022`. The exact framework name
+ * (without tier/version suffix) is the prefix; anything starting with one of
+ * these prefixes is considered a hard-regulatory regime.
+ *
+ * Regional data-residency frameworks (Schrems II / PIPL / PIPEDA) are listed
+ * explicitly. Generic `DATA-RESIDENCY-*` prefix is also accepted for adopters
+ * who declare per-region constraints under a unified naming scheme.
+ */
+export declare const HARD_REGULATORY_REGIME_PREFIXES: readonly string[];
+/**
+ * Predicate: returns true iff the regime ID matches a hard-regulatory prefix
+ * per the OQ-5 scope whitelist.
+ *
+ * Comparison is case-insensitive on the regime ID (`HIPAA` and `hipaa` both
+ * match) but the canonical prefixes are uppercase by convention.
+ *
+ * **Boundary guard (AISDLC-316 round-2 code-review fix)**: a match requires the
+ * prefix to be either the WHOLE regime id OR followed by a separator
+ * (`-`, `_`, `:`, `.`) or a digit (tier-variant pattern). This prevents
+ * collision-prone soft regimes like `SOXophone`, `AMLET`, `KYCS-internal`,
+ * `HIPAAphobia` from being mis-classified as hard-regulatory by a naive
+ * `startsWith` check. Tier-variants like `SOC2-T2`, `PCI-DSS-L1`,
+ * `FedRAMP-Moderate`, `ISO-27001:2022`, `SOC2T2` (digit boundary) still match.
+ *
+ * @example
+ *   isHardRegulatoryRegime('HIPAA')           // true
+ *   isHardRegulatoryRegime('SOC2-T2')         // true (SOC2 prefix + '-' boundary)
+ *   isHardRegulatoryRegime('PCI-DSS-L1')      // true (PCI-DSS prefix + '-' boundary)
+ *   isHardRegulatoryRegime('FedRAMP-Moderate')// true (FedRAMP prefix + '-' boundary)
+ *   isHardRegulatoryRegime('ISO-27001:2022')  // true (ISO-27001 prefix + ':' boundary)
+ *   isHardRegulatoryRegime('clean-code')      // false (soft / out of scope)
+ *   isHardRegulatoryRegime('team-style')      // false (soft / out of scope)
+ *   isHardRegulatoryRegime('SOXophone')       // false (SOX prefix but letter boundary)
+ *   isHardRegulatoryRegime('AMLET')           // false (AML prefix but letter boundary)
+ *   isHardRegulatoryRegime('HIPAAphobia')     // false (HIPAA prefix but letter boundary)
+ */
+export declare function isHardRegulatoryRegime(regimeId: string): boolean;
+/**
+ * Result of validating a set of declared regimes against the OQ-5 scope.
+ */
+export interface ValidateComplianceRegimesResult {
+    /** True iff every input regime passes `isHardRegulatoryRegime`. */
+    valid: boolean;
+    /** The subset of inputs that are hard-regulatory (in-scope). */
+    accepted: string[];
+    /** The subset rejected as soft / out of scope per OQ-5. */
+    rejected: string[];
+}
+/**
+ * Validate a list of declared compliance regimes against the OQ-5 hard-regulatory
+ * scope. Used at declaration time (DID load, RFC-0022 posture parse) to reject
+ * soft regimes before they reach the Eρ₅ scoring path.
+ *
+ * Per RFC-0009 OQ-5 sub-decision: soft/advisory regimes are NOT in scope and
+ * MUST be filtered at declaration time. Internal best-practices, code style,
+ * and team conventions belong to other mechanisms (code review, lint).
+ *
+ * @param regimes - Declared regime IDs from a soul's `complianceRegimes`
+ *                  field or an RFC-0022 `CompliancePosture.spec.regimes[].id`.
+ * @returns Validation result with split accepted/rejected lists.
+ */
+export declare function validateComplianceRegimes(regimes: readonly string[] | undefined): ValidateComplianceRegimesResult;
+/**
+ * A single asserted compliance violation against a work item.
+ *
+ * Adopters populate these from regime-specific clearance checks they run as
+ * part of admission enrichment — e.g., a HIPAA preprocessor that detects PHI
+ * fields in a work item's payload, a GDPR preprocessor that detects
+ * cross-border data transfers without lawful-basis annotation, etc.
+ *
+ * Phase 4.1 ships the **surface** for these violations; the per-regime
+ * clearance checkers themselves are out of scope (per RFC-0009 §10 Phase 4 —
+ * the scoring path activates first; specific checkers ship incrementally).
+ */
+export interface ComplianceViolation {
+    /** Regime ID the violation is asserted against (e.g. 'HIPAA'). */
+    regimeId: string;
+    /**
+     * Optional control / clause the violation cites
+     * (e.g. '§164.312(a)' for HIPAA technical safeguards).
+     */
+    control?: string;
+    /** Human-readable reason — surfaced in audit logs + operator UI. */
+    reason: string;
+    /** Optional severity hint; Eρ₅ is gating regardless of severity. */
+    severity?: 'critical' | 'major' | 'minor';
+}
+/**
+ * Per-work-item compliance violations, keyed by canonical work-item ID
+ * (e.g. `AISDLC-316`). Empty / missing entries imply no violations — clearance
+ * holds and Eρ₅ = 1.
+ */
+export interface ComplianceViolationEntry {
+    /** Canonical work item ID (case-insensitive match used internally). */
+    id: string;
+    /** Asserted violations against this work item. Empty = clearance holds. */
+    violations: ComplianceViolation[];
+}
+/**
+ * Per-soul declared compliance regimes, keyed by `soulId` matching
+ * `Tessellation.souls[].soulId`. Sourced from each Soul DID's
+ * `spec.triad.engineering.complianceRegimes` field at load time.
+ *
+ * In the non-tessellated (single-DID) path, callers populate a single entry
+ * under a sentinel `__platform` key with the DID's own engineering regimes.
+ */
+export interface SoulComplianceRegimes {
+    /** Soul ID this entry applies to (or `__platform` for non-tessellated). */
+    soulId: string;
+    /** Hard-regulatory regimes declared on the soul's engineering vertex. */
+    regimes: string[];
+}
+/**
+ * All Eρ₅ Compliance Clearance inputs needed by the admission composite.
+ *
+ * Callers build this once per pipeline tick and pass it to
+ * `computeAdmissionComposite` via `AdmissionCompositeOptions.complianceClearanceContext`.
+ *
+ * **Adopter opt-in gate** (Phase 4.1): when `enabled === false` (the default
+ * for `undefined`), the admission composite does NOT apply Eρ₅ — full
+ * backward compatibility with Phase 2/3 behavior.
+ */
+export interface ComplianceClearanceContext {
+    /**
+     * Adopter opt-in gate. When `false` (default), Eρ₅ is not applied and the
+     * admission composite behaves as Phase 2/3 (no compliance multiplier).
+     *
+     * Initially gated on adopter opt-in per RFC-0009 §10 Phase 4; promotion
+     * to default-on subject to ecosystem feedback (tracked as a follow-up).
+     */
+    enabled: boolean;
+    /**
+     * Per-soul declared regimes from each soul's `triad.engineering.complianceRegimes`.
+     *
+     * In tessellated mode, one entry per active soul; in non-tessellated mode,
+     * one entry under sentinel soulId `__platform`.
+     *
+     * Regimes here MUST already be filtered by `validateComplianceRegimes` —
+     * the loader / adapter that builds this struct is the OQ-5 enforcement
+     * boundary. Anything that slips through is treated as a soft regime that
+     * does NOT contribute to the gating decision.
+     */
+    perSoulRegimes: SoulComplianceRegimes[];
+    /**
+     * Optional RFC-0022 `CompliancePosture[]` from
+     * `loadCompliancePosture()`. When present, declared regime IDs from the
+     * posture compose with the soul-declared regimes — both contribute to the
+     * regime set the work item is checked against. This is the RFC-0022
+     * consumption surface (AC #4).
+     *
+     * Regime IDs from the posture pass the same OQ-5 scope filter; the loader's
+     * own validation (`MissingComplianceAttestation`) is independent.
+     */
+    posture?: readonly CompliancePosture[];
+    /**
+     * Asserted violations per work item, indexed by work-item ID. Absent ID
+     * (or empty `violations` array) implies clearance holds for that item.
+     */
+    violations?: ComplianceViolationEntry[];
+}
+/**
+ * Result of the Eρ₅ Compliance Clearance pass.
+ *
+ * `er5` is categorical 0/1 per RFC-0009 §7.1 — `0` means at least one declared
+ * regime was violated; `1` means clearance holds (or no regimes apply, or the
+ * adopter has not opted in yet).
+ */
+export interface ComplianceClearanceResult {
+    /** Categorical clearance score in {0, 1}. */
+    er5: 0 | 1;
+    /**
+     * Routing path taken (matches the scoring algorithm's decision branches).
+     *
+     * - `'disabled'`           — adopter opt-in gate is off; Eρ₅ not applied.
+     * - `'no-regimes'`         — no hard-regulatory regimes declared for any
+     *                            affected soul (or platform); Eρ₅ = 1.
+     * - `'clearance-holds'`    — regimes declared, no violations asserted; Eρ₅ = 1.
+     * - `'clearance-violated'` — at least one declared regime asserts a violation; Eρ₅ = 0.
+     */
+    routingPath: 'disabled' | 'no-regimes' | 'clearance-holds' | 'clearance-violated';
+    /**
+     * The regime IDs the work item was checked against (union of soul-declared
+     * regimes from `affectedSoulIds` and any RFC-0022 posture regimes).
+     */
+    checkedRegimes: string[];
+    /**
+     * Violations that drove Eρ₅ to 0. Empty when clearance holds.
+     */
+    violations: ComplianceViolation[];
+}
+/**
+ * Compute Eρ₅ Compliance Clearance for a work item.
+ *
+ * Algorithm (RFC-0009 §7.1 + §10 Phase 4):
+ * 1. If `ctx.enabled !== true` → return `er5 = 1` with `routingPath = 'disabled'`.
+ * 2. Build the regime set from:
+ *    - Each soul in `affectedSoulIds`'s `perSoulRegimes` entry, OR
+ *      the `__platform` sentinel entry when `affectedSoulIds` is empty.
+ *    - All RFC-0022 posture regimes (if `ctx.posture` present).
+ *    Filter through `isHardRegulatoryRegime` (defense-in-depth on the OQ-5 boundary).
+ * 3. If regime set is empty → `er5 = 1`, `routingPath = 'no-regimes'`.
+ * 4. Look up violations for `workItemId` in `ctx.violations` (case-insensitive).
+ *    Filter to violations whose `regimeId` is in the regime set.
+ *    - If any remain → `er5 = 0`, `routingPath = 'clearance-violated'`.
+ *    - Else → `er5 = 1`, `routingPath = 'clearance-holds'`.
+ *
+ * @param workItemId        - Canonical work item ID (e.g. `AISDLC-316`).
+ * @param affectedSoulIds   - Soul IDs the work item targets (from
+ *                            `resolveAffectedSouls()`). Empty array =
+ *                            non-tessellated or substrate-only; uses
+ *                            `__platform` sentinel.
+ * @param ctx               - Compliance clearance context (or undefined =
+ *                            treated as disabled).
+ * @returns Eρ₅ clearance result with routing audit trail.
+ */
+export declare function computeComplianceClearance(workItemId: string, affectedSoulIds: readonly string[], ctx: ComplianceClearanceContext | undefined): ComplianceClearanceResult;
+//# sourceMappingURL=compliance-clearance.d.ts.map