@ai-sdlc/orchestrator 0.9.0 → 0.13.0

package/dist/signal-ingestion/types.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Signal ingestion source-adapter substrate for RFC-0030 Phase 1.
+ *
+ * Source adapters fetch raw demand signals from external systems while keeping
+ * classification, clustering, and scoring out of this layer.
+ */
+export type SignalSourceName = 'signal-source-support-ticket' | 'signal-source-community-thread' | 'signal-source-in-app-feedback' | 'signal-source-manual' | (string & {});
+export type SignalTier = 1 | 2;
+export type CustomerTier = 'enterprise' | 'mid' | 'smb' | 'free' | 'churned';
+export interface RawSignal {
+    /** Stable identifier in the source system, e.g. zendesk-ticket-12345. */
+    sourceId: string;
+    /** Original source timestamp. */
+    sourceTimestamp: Date;
+    /** Optional customer/account identifier supplied by the source. */
+    customerId?: string;
+    /** Optional structured tier supplied by the source. */
+    customerTier?: CustomerTier;
+    /** Free-text signal body. */
+    payload: string;
+    /** Source-specific structured metadata. */
+    metadata?: Record<string, unknown>;
+    /** Required for manual signals per RFC-0030 OQ-13.4. */
+    attestedBy?: string;
+    /** Auto-filled for manual signals when omitted. */
+    attestedAt?: Date;
+    /**
+     * Optional ISO-3166 country code or compliance region tag for the signal's
+     * origin (e.g. 'eu', 'us-east', 'gb', 'apac', 'us'). Consumed by the
+     * Phase 4 residency-violation gate per RFC-0030 OQ-13.3: when the adopter
+     * has a declared regime constraint (via RFC-0022 compliance posture) that
+     * requires data residency in a specific region, signals from outside the
+     * allowed region(s) are refused and emitted as
+     * `Decision: signal-residency-violation`. When undefined, the residency
+     * gate skips this signal (no false positives on adapters that don't surface
+     * region metadata).
+     */
+    region?: string;
+    /**
+     * Optional evidence link for manual signals per RFC-0030 OQ-13.4 v0.3
+     * re-walkthrough. When present (call recording URL, ticket URL, transcript
+     * link), the audit trail is materially stronger. When absent, the attested
+     * observation stands but is flagged in the manual-share quality metric.
+     *
+     * The pipeline preserves this field through classification + clustering +
+     * D1 aggregation so it remains visible in the audit export.
+     */
+    evidenceUrl?: string;
+}
+export interface SignalSourceAdapter {
+    readonly name: SignalSourceName;
+    readonly defaultTier: SignalTier;
+    /**
+     * RFC-0030 OQ-13.1 v0.3 re-walkthrough: when `true`, this adapter requires
+     * OAuth credential management (refresh tokens, scopes) which is deferred to
+     * a future credential-management RFC. The Phase 1 registry refuses to fetch
+     * from such adapters and emits `Decision: adapter-requires-credential-mgmt-rfc`.
+     *
+     * Defaults to `false` (undefined → false) — all v1-shipped adapters MUST be
+     * env-var-based.
+     */
+    readonly requiresOAuth?: boolean;
+    /**
+     * Adapter self-validation. Credential lifecycle is intentionally deferred to
+     * a future RFC; Phase 1 only reports whether this adapter can be used.
+     */
+    isAvailable(): Promise<boolean>;
+    /** Fetch immutable signals from the source since the provided timestamp. */
+    fetchSignals(since: Date): Promise<RawSignal[]>;
+}
+export interface AdapterCredentialInvalidDecision {
+    type: 'Decision';
+    decision: 'adapter-credential-invalid';
+    adapter: SignalSourceName;
+    message: string;
+}
+/**
+ * RFC-0030 OQ-13.1 v0.3 re-walkthrough: emitted when an adapter's required
+ * credential env var is missing or empty. Downstream auto-action: emit a
+ * SETUP task asking the operator to set the env var. Pipeline continues with
+ * remaining valid adapters.
+ *
+ * Distinct from `AdapterCredentialRejectedDecision` (env var present but
+ * upstream auth call failed). Two distinct operator actions: SETUP vs.
+ * ROTATION. v0.2's collapsed `adapter-credential-invalid` is preserved for
+ * backward compat — adapters that don't yet probe env vars surface the
+ * legacy Decision.
+ */
+export interface AdapterCredentialNotConfiguredDecision {
+    type: 'Decision';
+    decision: 'adapter-credential-not-configured';
+    adapter: SignalSourceName;
+    envVarName: string;
+    message: string;
+}
+/**
+ * RFC-0030 OQ-13.1 v0.3 re-walkthrough: emitted when an adapter has the
+ * credential env var present BUT the upstream service rejected the auth call
+ * (401 / 403). Downstream auto-action: emit a ROTATION task asking the
+ * operator to rotate / re-generate the credential. Pipeline continues with
+ * remaining valid adapters.
+ */
+export interface AdapterCredentialRejectedDecision {
+    type: 'Decision';
+    decision: 'adapter-credential-rejected';
+    adapter: SignalSourceName;
+    message: string;
+}
+/**
+ * RFC-0030 OQ-13.1 v0.3 re-walkthrough: emitted when an adapter declares
+ * `requiresOAuth = true`. Phase 1 ships ENV-VAR-ONLY adapters; OAuth lifecycle
+ * (refresh tokens, scopes) is a substantial separate concern deferred to a
+ * future credential-management RFC. The registry refuses such adapters and
+ * surfaces this Decision; pipeline continues with the env-var-based adapters.
+ */
+export interface AdapterRequiresCredentialMgmtRfcDecision {
+    type: 'Decision';
+    decision: 'adapter-requires-credential-mgmt-rfc';
+    adapter: SignalSourceName;
+    message: string;
+}
+export interface ManualSignalIncompleteDecision {
+    type: 'Decision';
+    decision: 'manual-signal-incomplete';
+    adapter: 'signal-source-manual';
+    sourceId?: string;
+    message: string;
+}
+/**
+ * RFC-0030 OQ-13.4 v0.3 re-walkthrough: emitted when a manual signal entry
+ * would exceed the per-operator daily cap (default 10/day, configurable via
+ * `manualEntry.dailyCapPerOperator`). Downstream auto-action: surface a
+ * batch-review escalation task. The signal is REFUSED (not silently dropped)
+ * so the operator sees the rejection and can escalate legitimately.
+ */
+export interface ManualSignalRateLimitExceededDecision {
+    type: 'Decision';
+    decision: 'manual-signal-rate-limit-exceeded';
+    adapter: 'signal-source-manual';
+    attestedBy: string;
+    /** UTC ISO date (YYYY-MM-DD) of the bucket that overflowed. */
+    utcDate: string;
+    dailyCap: number;
+    sourceId?: string;
+    message: string;
+}
+/**
+ * RFC-0030 OQ-13.4 v0.3 re-walkthrough: emitted when the rolling
+ * manual/total share metric exceeds the configured threshold (default 30%
+ * over a 7-day window). Architectural anti-pattern warning, NOT a block —
+ * surfaces that the pipeline is acting as a data-entry tool rather than
+ * automated demand-detection. Pipeline continues normally.
+ */
+export interface ManualSignalShareElevatedDecision {
+    type: 'Decision';
+    decision: 'manual-signal-share-elevated';
+    /** Computed manual/total ratio over the window. */
+    manualShare: number;
+    /** Threshold that was exceeded (config: `manualEntry.qualityMetric.shareWarningThreshold`). */
+    threshold: number;
+    windowDays: number;
+    manualSignals: number;
+    totalSignals: number;
+    message: string;
+}
+export interface SignalFetchResult {
+    signals: RawSignal[];
+    decisions: Array<AdapterCredentialInvalidDecision | AdapterCredentialNotConfiguredDecision | AdapterCredentialRejectedDecision | AdapterRequiresCredentialMgmtRfcDecision | ManualSignalIncompleteDecision | ManualSignalRateLimitExceededDecision | SignalResidencyViolationDecision>;
+}
+/**
+ * Emitted at adapter level when a signal's `region` doesn't match the adopter's
+ * declared regime constraints per RFC-0030 OQ-13.3 (composes with RFC-0022
+ * Compliance Posture). Adapter response: refuse the signal + log the Decision +
+ * emit a `compliance.yaml regimeOverrides` clarification task. Pipeline does
+ * NOT halt — the catalog absorbs the violation (G0 non-blocking pipeline contract
+ * per RFC-0035).
+ */
+export interface SignalResidencyViolationDecision {
+    type: 'Decision';
+    decision: 'signal-residency-violation';
+    adapter: SignalSourceName;
+    sourceId: string;
+    /** The region the signal claimed (or 'unknown' when region metadata absent). */
+    signalRegion: string;
+    /** Regime IDs (e.g. 'gdpr', 'hipaa') whose residency constraints were violated. */
+    violatedRegimes: string[];
+    /** Allowed regions per the adopter's regime declaration. */
+    allowedRegions: string[];
+    message: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/signal-ingestion/types.js

@@ -0,0 +1,8 @@
+/**
+ * Signal ingestion source-adapter substrate for RFC-0030 Phase 1.
+ *
+ * Source adapters fetch raw demand signals from external systems while keeping
+ * classification, clustering, and scoring out of this layer.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/substrate/drift-composition.d.ts

@@ -0,0 +1,270 @@
+/**
+ * RFC-0028 §7.2 — structural + statistical drift composition.
+ *
+ * Phase 3 of RFC-0028 §7.2 v0.2 resolution. Wires the canonical pairing of
+ * the two drift-detection layers with the explicit composition rules the
+ * operator resolved on 2026-05-27:
+ *
+ * 1. **Structural drift (CI authoring-time) REJECTS deployment.** The
+ *    type-registry CI gate (`scripts/check-substrate-contract.mjs`,
+ *    AISDLC-453) is the hard gate. When any of its 5 assertions fail it emits
+ *    `Decision: substrate-structural-drift-detected` (severity HIGH) and
+ *    blocks PR merge via a non-zero exit code. This module does NOT rebuild
+ *    that gate — it *represents* its outcome so the two layers can be
+ *    composed and correlated. {@link toStructuralDriftEvents} maps the gate's
+ *    result into the composition model.
+ *
+ * 2. **Statistical drift (runtime) SURFACES to operator (RFC-0035 G0
+ *    non-blocking).** PPA's `SoulDriftDetected` signal (rolling 30-day mean
+ *    < 0.4 or stddev > 0.15 sustained for 3 sprints) routes to
+ *    `Decision: soul-statistical-drift-detected` → operator batch review with
+ *    three reconciliation paths. The pipeline NEVER halts on statistical
+ *    drift. {@link evaluateStatisticalDrift} computes the signal;
+ *    {@link composeDrift} routes the firing signal to the catalog request.
+ *
+ * 3. **Both Decisions composable in the catalog.** Both classes carry a
+ *    `soulId` + a stable `driftClass` discriminant and share one catalog
+ *    scope ({@link DRIFT_DECISION_SCOPE}) so an operator can query
+ *    "show me all drift events for Soul X" and get structural (rejected at
+ *    CI) and statistical (caught at runtime) events side-by-side —
+ *    {@link correlateDriftBySoul}.
+ *
+ * 4. **Cold-start handling.** Statistical detection needs a rolling 30d
+ *    baseline. Pre-baseline (< 30d of signal), the detector returns a
+ *    `calibrating` status and emits NO statistical Decisions — structural
+ *    detection is the sole defense during the calibration window. The
+ *    cold-start shape mirrors RFC-0030 §13 OQ-13.5's z-score flooding
+ *    detector (calibrating until the rolling window fills, then active).
+ *
+ * **AC-8 — no parallel event emitter.** This module does NOT import or write
+ * to the catalog event log directly. Mirroring the Phase 1 `identity-class.ts`
+ * audit and the Phase 2 `check-substrate-contract.mjs` gate, it produces
+ * `DriftDecisionRequest` payloads (summary + scope + source + options) that
+ * the *caller* forwards to the existing RFC-0035 substrate via
+ * `node pipeline-cli/bin/cli-decisions.mjs add` (or `makeDecisionOpenedEvent`
+ * + `appendDecisionEvent` in-process). The request shape is byte-compatible
+ * with `cli-decisions add --summary … --scope … --option id:desc`. This keeps
+ * the orchestrator package free of a build-time dependency on
+ * `@ai-sdlc/pipeline-cli`'s dist output and avoids a second emitter.
+ *
+ * @see spec/rfcs/RFC-0028-engineering-axis-substrate-enforcement.md §7.2
+ * @see spec/rfcs/RFC-0035-decision-catalog-operator-routing.md (G0 routing)
+ * @see scripts/check-substrate-contract.mjs (the structural layer, AISDLC-453)
+ * @module substrate/drift-composition
+ */
+/**
+ * The two canonical drift classes per RFC-0028 §7.2. The discriminant is
+ * stable so the catalog can correlate both classes for a single Soul DID.
+ */
+export type DriftClass = 'structural' | 'statistical';
+/**
+ * The RFC-0035 Decision scope used for every drift Decision. Both classes
+ * share one scope so `cli-decisions list --scope substrate-drift` returns
+ * the composed view (AC-3 / AC-5).
+ */
+export declare const DRIFT_DECISION_SCOPE = "substrate-drift";
+/** Decision summary slug for structural drift (matches AISDLC-453 gate). */
+export declare const STRUCTURAL_DECISION_SLUG = "substrate-structural-drift-detected";
+/** Decision summary slug for statistical drift (RFC-0028 §7.2 rule 2). */
+export declare const STATISTICAL_DECISION_SLUG = "soul-statistical-drift-detected";
+/**
+ * Statistical-drift detection thresholds, frozen from RFC-0028 §7.2 / PPA's
+ * `SoulDriftDetected` definition. A drift fires when the rolling 30-day mean
+ * drops below {@link MEAN_FLOOR} OR the rolling stddev exceeds
+ * {@link STDDEV_CEILING}, sustained for {@link SUSTAINED_SPRINTS} sprints.
+ */
+export declare const MEAN_FLOOR = 0.4;
+export declare const STDDEV_CEILING = 0.15;
+export declare const SUSTAINED_SPRINTS = 3;
+/** Rolling baseline window in days (RFC-0028 §7.2 cold-start: 30d). */
+export declare const BASELINE_WINDOW_DAYS = 30;
+/**
+ * One Decision-option choice the operator picks from. Mirrors the
+ * RFC-0035 `DecisionOption` shape (`pipeline-cli/src/decisions/decision-record.ts`)
+ * without importing it — kept structurally identical so a caller can spread
+ * these directly into `makeDecisionOpenedEvent({ options })` or render them as
+ * `--option <id>:<description>` flags for `cli-decisions add`.
+ */
+export interface DriftDecisionOption {
+    id: string;
+    description: string;
+    consequences?: string[];
+}
+/**
+ * A ready-to-file Decision request. The caller forwards this to the RFC-0035
+ * catalog (CLI or in-process). The field names match the catalog's
+ * `OpenDecisionInput` so no translation layer is needed.
+ */
+export interface DriftDecisionRequest {
+    /** RFC-0035 Decision source. Structural=emergent-finding; statistical=framework-calibration. */
+    source: 'emergent-finding' | 'framework-calibration';
+    scope: string;
+    summary: string;
+    body?: string;
+    /** Statistical drift is reversible (G0 non-blocking); structural is a hard gate. */
+    reversible: boolean;
+    options: DriftDecisionOption[];
+}
+/**
+ * A drift event in the composition model — the side-by-side unit an operator
+ * sees. Both structural and statistical events project to this shape so the
+ * TUI / catalog can render them together.
+ */
+export interface DriftEvent {
+    driftClass: DriftClass;
+    /** Soul DID the drift applies to. */
+    soulId: string;
+    /**
+     * Structural = HIGH (hard gate). Statistical = advisory (non-blocking, G0).
+     */
+    severity: 'high' | 'advisory';
+    /** Whether this drift class blocks deployment. Structural=true always. */
+    blocking: boolean;
+    /** One-line operator-facing summary (used as the Decision summary). */
+    summary: string;
+    /** Free-form detail body for the Decision. */
+    detail?: string;
+}
+/**
+ * The three (and only three) operator reconciliation paths for a
+ * `soul-statistical-drift-detected` Decision, per RFC-0028 §7.2:
+ *
+ * (a) confirm drift as legitimate evolution → emit DID amendment
+ * (b) confirm drift as substrate violation → file fix task
+ * (c) defer for the next operator review window
+ */
+export declare const STATISTICAL_RECONCILIATION_OPTIONS: readonly DriftDecisionOption[];
+/** Structural-drift reconciliation options mirror the AISDLC-453 CI gate. */
+export declare const STRUCTURAL_RECONCILIATION_OPTIONS: readonly DriftDecisionOption[];
+/**
+ * The relevant subset of the structural gate's failure record
+ * (`scripts/check-substrate-contract.mjs#AssertionResult`). Re-declared here
+ * as a structural type so this module does not import the `.mjs` CI script
+ * (which lives outside the orchestrator build graph) — callers pass the
+ * gate's result through.
+ */
+export interface StructuralGateFailure {
+    soulId: string;
+    message: string;
+    /** The gate's pre-formatted Decision summary, when present. */
+    decisionSummary?: string;
+}
+export interface StructuralGateResult {
+    /** True when the gate passed (no structural drift). */
+    passed: boolean;
+    /** True when no contracts exist (cold-start no-op). */
+    coldStart: boolean;
+    failures: StructuralGateFailure[];
+}
+/**
+ * Project the structural CI gate's result into composition `DriftEvent`s.
+ *
+ * One `DriftEvent` per gate failure. Always `blocking: true` / severity
+ * `high` — structural drift is the hard gate (RFC-0028 §7.2 rule 1). Returns
+ * `[]` when the gate passed or was a cold-start no-op (no contracts).
+ */
+export declare function toStructuralDriftEvents(result: StructuralGateResult): DriftEvent[];
+/**
+ * A single dated drift-metric sample for one Soul DID. `value` is the PPA
+ * soul-coherence metric in [0, 1]; `at` is the sample timestamp.
+ */
+export interface SoulDriftSample {
+    /** ISO-8601 timestamp (or any Date-parseable string). */
+    at: string;
+    /** Coherence metric in [0, 1]; lower = more drift. */
+    value: number;
+}
+/**
+ * The detector's status. `calibrating` = pre-baseline (< 30d of signal); the
+ * detector emits NO statistical Decisions in this state (cold-start, AC-4).
+ * `active` = baseline accumulated; drift may fire.
+ */
+export type StatisticalDriftStatus = 'calibrating' | 'active';
+export interface StatisticalDriftResult {
+    status: StatisticalDriftStatus;
+    /** True only when status is `active` AND the drift condition is met. */
+    drifted: boolean;
+    /** Rolling mean over the baseline window (null while calibrating). */
+    rollingMean: number | null;
+    /** Rolling population stddev over the window (null while calibrating). */
+    rollingStdDev: number | null;
+    /** Consecutive sprints the drift condition has held (active state). */
+    sustainedSprints: number;
+    /** Human-readable reason — used for the Decision detail when drifted. */
+    reason: string;
+}
+/**
+ * Evaluate statistical drift for one Soul DID over its metric history.
+ *
+ * Cold-start (AC-4): if the span between the earliest sample and `now` is
+ * shorter than {@link BASELINE_WINDOW_DAYS}, the detector is still
+ * `calibrating` — it returns `drifted: false` with null statistics and the
+ * caller emits no Decision. Structural detection (AISDLC-453) is the sole
+ * defense during this window.
+ *
+ * Once the window is filled the detector is `active`: drift fires when the
+ * rolling mean < {@link MEAN_FLOOR} OR the rolling stddev >
+ * {@link STDDEV_CEILING}, AND that condition has held for at least
+ * {@link SUSTAINED_SPRINTS} consecutive sprint buckets.
+ *
+ * The cold-start shape mirrors RFC-0030 §13 OQ-13.5's z-score flooding
+ * detector (calibrating until the window accumulates, then active).
+ *
+ * @param samples Metric history (any order). Empty → calibrating.
+ * @param sprintFlags Per-sprint booleans (most-recent last) indicating
+ *   whether the drift condition held in each sprint; used to enforce the
+ *   "3 sustained sprints" rule independent of raw sample cadence. When
+ *   omitted, sustained-sprint accounting falls back to whether the current
+ *   window meets the condition (counts as 1 sprint, so a single-window
+ *   breach is reported but does not satisfy the 3-sprint rule).
+ * @param now Clock override for deterministic tests.
+ */
+export declare function evaluateStatisticalDrift(samples: SoulDriftSample[], sprintFlags?: boolean[], now?: Date): StatisticalDriftResult;
+/**
+ * Project an `active` + `drifted` statistical result into a composition
+ * `DriftEvent`. Returns `null` while calibrating or not drifted — there is
+ * nothing to surface to the operator (AC-4: no statistical Decisions during
+ * cold-start).
+ */
+export declare function toStatisticalDriftEvent(soulId: string, result: StatisticalDriftResult): DriftEvent | null;
+export interface ComposeDriftResult {
+    /** All composed drift events (structural + statistical), side-by-side. */
+    events: DriftEvent[];
+    /**
+     * Ready-to-file Decision requests, one per surfaced/blocked event, in the
+     * same order as `events`. The caller forwards each to the RFC-0035 catalog
+     * (`cli-decisions add` / `makeDecisionOpenedEvent`) — this module does NOT
+     * write the event log itself (AC-8).
+     */
+    requests: DriftDecisionRequest[];
+    /** True if any structural (blocking) drift is present — the CI hard gate. */
+    blocked: boolean;
+}
+/** Build the catalog request for one composed drift event. */
+export declare function toDecisionRequest(event: DriftEvent): DriftDecisionRequest;
+/**
+ * Compose the structural gate outcome with a set of statistical results.
+ *
+ * - Structural events → `substrate-structural-drift-detected` (HIGH,
+ *   blocking). Represented from the CI gate result; the gate itself already
+ *   emits + blocks at CI time (AISDLC-453), so the catalog request here is the
+ *   composition/audit projection (so structural + statistical sit
+ *   side-by-side in one scope).
+ * - Statistical drifted events → `soul-statistical-drift-detected`
+ *   (advisory, non-blocking, G0) with the three reconciliation options.
+ * - Calibrating / non-drifted statistical results emit NO request (AC-4).
+ *
+ * The pipeline never halts here: `blocked` reports the structural hard-gate
+ * state for the CI caller to act on, but statistical drift never sets it.
+ */
+export declare function composeDrift(structural: StructuralGateResult, statistical: Array<{
+    soulId: string;
+    result: StatisticalDriftResult;
+}>): ComposeDriftResult;
+/**
+ * Group composed drift events by Soul DID so an operator can query
+ * "show me all drift events for Soul X" and get both classes side-by-side.
+ * Returns a map keyed by `soulId` whose values preserve event order.
+ */
+export declare function correlateDriftBySoul(events: DriftEvent[]): Map<string, DriftEvent[]>;
+//# sourceMappingURL=drift-composition.d.ts.map