@ai-sdlc/orchestrator 0.10.0 → 0.14.0

package/dist/journey/metric-snapshot.js

@@ -0,0 +1,370 @@
+/**
+ * RFC-0018 Phase 4 — MetricSnapshot resource read API (OQ-5 resolution).
+ *
+ * Implements:
+ *   AC #1: MetricSnapshot schema (spec/schemas/metric-snapshot.v1.schema.json)
+ *   AC #2: MetricSnapshot read API — `getLatestMetricSnapshot(journey, metricId)`
+ *   AC #3: Stale-metric detection (default 30d; per-Soul configurable) with
+ *          `Decision: journey-metric-stale` + warn-and-unknown Cκ behavior
+ *   AC #4: Graduated Eρ₅ degradation (0-30/30-60/60-90/90+ thresholds + Decisions)
+ *   AC #5: Per-Soul `accessibility.auditOverdueGracePolicy` modes
+ *   AC #6: RFC-0022 multi-posture composition (strictest cadence applies)
+ *
+ * ### OQ-5 design summary
+ *
+ * Operators supply MetricSnapshot resources from their analytics pipeline
+ * (Mixpanel, Amplitude, Heap, internal-pipeline). The framework reads
+ * `completion-rate` and other journey-success values; it does NOT compute
+ * them from an analytics backend.
+ *
+ * Staleness: when `recordedAt` is older than `thresholdDays` (default 30),
+ * the scorer treats the metric as an unknown input (warn-and-unknown, NOT
+ * fail-closed). A `Decision: journey-metric-stale` is emitted for operator
+ * batch review.
+ *
+ * ### OQ-6 design summary
+ *
+ * When a journey's accessibility audit is overdue, Eρ₅ degrades on this
+ * graduated schedule (per-Soul policy `auditOverdueGracePolicy`):
+ *
+ *   Policy `graduated` (default):
+ *     0–30d past cadence  → warn only  (`journey-audit-overdue-warn`)
+ *     30–60d              → Eρ₅ -25%   (`journey-audit-overdue-graduated`)
+ *     60–90d              → Eρ₅ -50%   (`journey-audit-overdue-graduated`)
+ *     90d+                → effective block (`journey-audit-overdue-blocking`)
+ *
+ *   Policy `binary-30d`:
+ *     0–30d → no impact (SOC2/HIPAA early-warning model)
+ *     30d+  → immediate Eρ₅ fail
+ *
+ *   Policy `hard-block`:
+ *     Immediate Eρ₅ fail at cadence+0d (strictest, no grace)
+ *
+ * ### RFC-0022 multi-posture composition (AC #6)
+ *
+ * When the RFC-0022 compliance posture declares a stricter cadence than
+ * the soul-default, the strictest constraint wins. This mirrors the
+ * RFC-0030 OQ-13.3 UNION precedent for multi-posture composition.
+ *
+ * ### Decision-routing must-consume contract
+ *
+ * `getLatestMetricSnapshot` emits `decision: 'journey-metric-stale'` when a
+ * snapshot is present but older than `thresholdDays`. Callers MUST inspect
+ * `result.decision` and route it — typically to the RFC-0035 G0 batch-review
+ * queue — before using `result.snapshot.spec.value` for Cκ scoring. Silently
+ * dropping `result.decision` defeats the operator-visibility guarantee that
+ * makes warn-and-unknown safe (non-fail-closed). A typed must-consume pattern:
+ *
+ *   ```ts
+ *   const result = getLatestMetricSnapshot(journey, metricId, opts);
+ *   if (result.decision) emitDecision(result.decision); // required
+ *   if (result.freshness === 'fresh') useValue(result.snapshot!.spec.value);
+ *   ```
+ *
+ * @see spec/rfcs/RFC-0018-in-soul-journey-pattern.md §10.1 OQ-5 + OQ-6
+ * @see spec/schemas/metric-snapshot.v1.schema.json
+ */
+/** Default staleness threshold per OQ-5 resolution (30 days). */
+export const DEFAULT_STALENESS_THRESHOLD_DAYS = 30;
+/**
+ * Retrieve the **latest** MetricSnapshot for the given journey + metricId pair
+ * and classify it as fresh, stale, or missing.
+ *
+ * Selection: when multiple snapshots match, the one with the most recent
+ * `spec.recordedAt` is returned (latest-wins). This covers the case where
+ * the operator's pipeline emits snapshots on a periodic schedule.
+ *
+ * Staleness: `ageInDays = (now - recordedAt) / (1000 * 60 * 60 * 24)`.
+ * When `ageInDays > thresholdDays`, the result carries:
+ *   - `freshness: 'stale'`
+ *   - `decision: 'journey-metric-stale'`
+ *
+ * This Decision routes through RFC-0035 G0 (non-blocking batch review):
+ * the Cκ scorer treats a stale metric as an unknown input (same behavior as
+ * `freshness: 'missing'`), NOT as a hard fail. The pipeline continues.
+ *
+ * @param journey   Path-style journey URI (e.g. 'spry-engage/onboarding')
+ * @param metricId  Metric identifier (e.g. 'completion-rate')
+ * @param options   Snapshot collection + optional per-Soul config
+ */
+export function getLatestMetricSnapshot(journey, metricId, options) {
+    const { snapshots, stalenessConfig, now } = options;
+    const thresholdDays = stalenessConfig?.thresholdDays ?? DEFAULT_STALENESS_THRESHOLD_DAYS;
+    const nowMs = now ? new Date(now).getTime() : Date.now();
+    // Filter to snapshots matching this journey + metricId pair.
+    const matching = snapshots.filter((s) => s.metadata.journey === journey && s.metadata.metricId === metricId);
+    if (matching.length === 0) {
+        return {
+            journey,
+            metricId,
+            freshness: 'missing',
+            thresholdDays,
+        };
+    }
+    // Select the most recent by recordedAt (latest-wins).
+    const latest = matching.reduce((best, candidate) => {
+        const bestMs = new Date(best.spec.recordedAt).getTime();
+        const candidateMs = new Date(candidate.spec.recordedAt).getTime();
+        return candidateMs > bestMs ? candidate : best;
+    });
+    const recordedAtMs = new Date(latest.spec.recordedAt).getTime();
+    // Guard: a future-dated recordedAt (recordedAt > now) would yield a negative
+    // ageInDays, making the metric appear perpetually fresh and suppressing the
+    // journey-metric-stale Decision. Clamp negative ages to stale so a
+    // misconfigured analytics pipeline cannot silently defeat staleness checks.
+    const rawAgeInDays = (nowMs - recordedAtMs) / (1000 * 60 * 60 * 24);
+    const ageInDays = rawAgeInDays < 0 ? thresholdDays + 1 : rawAgeInDays;
+    if (ageInDays > thresholdDays) {
+        return {
+            journey,
+            metricId,
+            freshness: 'stale',
+            snapshot: latest,
+            decision: 'journey-metric-stale',
+            ageInDays,
+            thresholdDays,
+        };
+    }
+    return {
+        journey,
+        metricId,
+        freshness: 'fresh',
+        snapshot: latest,
+        ageInDays,
+        thresholdDays,
+    };
+}
+/** Eρ₅ multiplier for each impact tier. */
+export const ERHO5_MULTIPLIERS = {
+    warn: 1.0,
+    'reduced-25': 0.75,
+    'reduced-50': 0.5,
+    'effective-block': 0.0,
+};
+/** Default graduated thresholds per OQ-6 resolution. */
+export const DEFAULT_GRADUATED_THRESHOLDS = {
+    warnAt: 0,
+    reduced25At: 30,
+    reduced50At: 60,
+    effectiveBlockAt: 90,
+};
+/**
+ * Compute the Eρ₅ impact and Decision for an overdue accessibility audit.
+ *
+ * Implements RFC-0018 §10.1 OQ-6 graduated Eρ₅ degradation:
+ *
+ * Policy `graduated` (default):
+ *   - 0 ≤ daysOverdue < 30  → `warn`           (multiplier 1.0)
+ *   - 30 ≤ daysOverdue < 60 → `reduced-25`     (multiplier 0.75)
+ *   - 60 ≤ daysOverdue < 90 → `reduced-50`     (multiplier 0.50)
+ *   - daysOverdue ≥ 90      → `effective-block` (multiplier 0.0)
+ *
+ * Policy `binary-30d` (SOC2/HIPAA strict):
+ *   - daysOverdue < 30  → no impact (multiplier 1.0, no Decision)
+ *   - daysOverdue ≥ 30  → `effective-block` (multiplier 0.0)
+ *
+ * Policy `hard-block` (HIPAA/PCI-DSS ultra-strict):
+ *   - daysOverdue < 0   → no impact (multiplier 1.0, no Decision; not yet due)
+ *   - daysOverdue ≥ 0   → `effective-block` (multiplier 0.0) — cadence+0d, no grace
+ *
+ * When `daysOverdue < 0`, returns multiplier 1.0 and `decision: null`
+ * regardless of policy (audit is not yet due). At daysOverdue ≥ 0 each policy
+ * emits its Decision (no implicit grace day).
+ */
+export function computeAuditOverdueErho5(options) {
+    const { soulId, journeyId, daysOverdue, policy = 'graduated', graduatedThresholds } = options;
+    // Strictly negative daysOverdue means the audit is not yet due — no impact
+    // regardless of policy. Note: daysOverdue === 0 means "exactly at cadence
+    // boundary (cadence+0d)" and is intentionally NOT caught here so the
+    // policy-specific logic below can apply. In particular, `hard-block`
+    // specifies "no grace at cadence+0d", meaning it must fire at daysOverdue=0.
+    if (daysOverdue < 0) {
+        return {
+            soulId,
+            journeyId,
+            daysOverdue,
+            policy,
+            impact: 'warn',
+            erho5Multiplier: 1.0,
+            decision: null,
+        };
+    }
+    if (policy === 'hard-block') {
+        return {
+            soulId,
+            journeyId,
+            daysOverdue,
+            policy,
+            impact: 'effective-block',
+            erho5Multiplier: ERHO5_MULTIPLIERS['effective-block'],
+            decision: 'journey-audit-overdue-blocking',
+        };
+    }
+    if (policy === 'binary-30d') {
+        const threshold = 30;
+        if (daysOverdue < threshold) {
+            // SOC2/HIPAA grace window: warn only, no Eρ₅ impact.
+            return {
+                soulId,
+                journeyId,
+                daysOverdue,
+                policy,
+                impact: 'warn',
+                erho5Multiplier: 1.0,
+                decision: 'journey-audit-overdue-warn',
+            };
+        }
+        return {
+            soulId,
+            journeyId,
+            daysOverdue,
+            policy,
+            impact: 'effective-block',
+            erho5Multiplier: ERHO5_MULTIPLIERS['effective-block'],
+            decision: 'journey-audit-overdue-blocking',
+        };
+    }
+    // policy === 'graduated' (default)
+    // Guard: NaN daysOverdue (e.g. from a division by zero or bad caller) must
+    // not fall through to the warn/1.0 return at the bottom of the graduated
+    // path, producing a fail-open result. Treat non-finite values as
+    // effective-block (conservative) so the pipeline aborts rather than silently
+    // continuing with an unknown overdue duration.
+    if (!Number.isFinite(daysOverdue)) {
+        return {
+            soulId,
+            journeyId,
+            daysOverdue,
+            policy,
+            impact: 'effective-block',
+            erho5Multiplier: ERHO5_MULTIPLIERS['effective-block'],
+            decision: 'journey-audit-overdue-blocking',
+        };
+    }
+    const thresholds = {
+        warnAt: graduatedThresholds?.warnAt ?? DEFAULT_GRADUATED_THRESHOLDS.warnAt,
+        reduced25At: graduatedThresholds?.reduced25At ?? DEFAULT_GRADUATED_THRESHOLDS.reduced25At,
+        reduced50At: graduatedThresholds?.reduced50At ?? DEFAULT_GRADUATED_THRESHOLDS.reduced50At,
+        effectiveBlockAt: graduatedThresholds?.effectiveBlockAt ?? DEFAULT_GRADUATED_THRESHOLDS.effectiveBlockAt,
+    };
+    if (daysOverdue >= thresholds.effectiveBlockAt) {
+        return {
+            soulId,
+            journeyId,
+            daysOverdue,
+            policy,
+            impact: 'effective-block',
+            erho5Multiplier: ERHO5_MULTIPLIERS['effective-block'],
+            decision: 'journey-audit-overdue-blocking',
+        };
+    }
+    if (daysOverdue >= thresholds.reduced50At) {
+        return {
+            soulId,
+            journeyId,
+            daysOverdue,
+            policy,
+            impact: 'reduced-50',
+            erho5Multiplier: ERHO5_MULTIPLIERS['reduced-50'],
+            decision: 'journey-audit-overdue-graduated',
+        };
+    }
+    if (daysOverdue >= thresholds.reduced25At) {
+        return {
+            soulId,
+            journeyId,
+            daysOverdue,
+            policy,
+            impact: 'reduced-25',
+            erho5Multiplier: ERHO5_MULTIPLIERS['reduced-25'],
+            decision: 'journey-audit-overdue-graduated',
+        };
+    }
+    // daysOverdue >= warnAt (default 0) but below reduced25At
+    return {
+        soulId,
+        journeyId,
+        daysOverdue,
+        policy,
+        impact: 'warn',
+        erho5Multiplier: 1.0,
+        decision: 'journey-audit-overdue-warn',
+    };
+}
+/**
+ * Numeric strictness order for cadence values.
+ * Higher = stricter (shorter audit interval).
+ * Used by `resolveStrictestCadence` to pick the UNION result.
+ */
+export const AUDIT_CADENCE_STRICTNESS = {
+    continuous: 4,
+    'release-gated': 3,
+    quarterly: 2,
+    annually: 1,
+};
+/**
+ * Resolve the effective audit cadence by applying the strictest constraint
+ * from the journey declaration and all active RFC-0022 compliance postures.
+ *
+ * This implements RFC-0018 AC #6 + RFC-0030 OQ-13.3 UNION precedent:
+ * the strictest constraint among all active postures and the journey's own
+ * declaration wins.
+ *
+ * @example
+ * // Journey declares 'annually', but SOC2 posture requires 'quarterly'
+ * resolveStrictestCadence({
+ *   journeyCadence: 'annually',
+ *   postureCadences: ['quarterly'],
+ * })
+ * // → 'quarterly' (posture wins — stricter)
+ *
+ * @example
+ * // Journey declares 'continuous' (strictest possible)
+ * resolveStrictestCadence({
+ *   journeyCadence: 'continuous',
+ *   postureCadences: ['quarterly', 'annually'],
+ * })
+ * // → 'continuous' (journey wins — already strictest)
+ */
+export function resolveStrictestCadence(options) {
+    const { journeyCadence, postureCadences } = options;
+    const all = [journeyCadence, ...postureCadences];
+    // UNION = strictest (highest strictness number wins).
+    return all.reduce((strictest, candidate) => {
+        const currentOrder = AUDIT_CADENCE_STRICTNESS[strictest] ?? 0;
+        const candidateOrder = AUDIT_CADENCE_STRICTNESS[candidate] ?? 0;
+        return candidateOrder > currentOrder ? candidate : strictest;
+    });
+}
+/**
+ * Policy strictness order (higher = stricter).
+ */
+export const GRACE_POLICY_STRICTNESS = {
+    graduated: 1,
+    'binary-30d': 2,
+    'hard-block': 3,
+};
+/**
+ * Resolve the effective grace policy by picking the STRICTEST among the
+ * soul-level policy and all active RFC-0022 compliance posture policies.
+ *
+ * RFC-0022 + RFC-0018 AC #6: multi-posture UNION → strictest applies.
+ *
+ * @example
+ * // Soul defaults to 'graduated'; SOC2 posture requires 'binary-30d'
+ * resolveStrictestGracePolicy({
+ *   soulPolicy: 'graduated',
+ *   posturesPolicies: ['binary-30d'],
+ * })
+ * // → 'binary-30d' (posture wins — stricter)
+ */
+export function resolveStrictestGracePolicy(options) {
+    const { soulPolicy = 'graduated', posturesPolicies } = options;
+    const all = [soulPolicy, ...posturesPolicies];
+    return all.reduce((strictest, candidate) => {
+        const currentOrder = GRACE_POLICY_STRICTNESS[strictest] ?? 0;
+        const candidateOrder = GRACE_POLICY_STRICTNESS[candidate] ?? 0;
+        return candidateOrder > currentOrder ? candidate : strictest;
+    });
+}
+//# sourceMappingURL=metric-snapshot.js.map

package/dist/journey/state-id-drift-rule.d.ts

@@ -0,0 +1,137 @@
+/**
+ * RFC-0018 Phase 3 — JourneyStateIdDriftRule (RFC-0009 §13 Rule #4).
+ *
+ * Implements the 4th §13 drift-detection rule resolving RFC-0018 OQ-8 + OQ-10
+ * (2026-05-28, full rubric):
+ *
+ *   OQ-8: "AST scan from v1, reusing RFC-0009 §13 Rule #1 infrastructure."
+ *         The existing AST scan engine ALREADY EXISTS for soul-slug leakage
+ *         detection — adding journey state-ID detection is extending the
+ *         engine with one additional rule, not building from scratch.
+ *
+ *   OQ-10: "4th rule in the same §13 engine + concrete registration mechanism
+ *           spec'd: Tessellation§13RuleRegistry.register(rule)."
+ *
+ * ### Detection strategy
+ *
+ * The rule reuses the `scanSubstrateFile` textual-scan approach from the
+ * existing AST scan engine in `tessellation-drift.ts`. This is deliberately
+ * NOT a string match — it uses the same regex-based pattern matching that
+ * Rule #1 employs, consistent with the OQ-8 resolution:
+ *
+ * - Bare string literal: `'<state-id>'` or `"<state-id>"`
+ * - State-discriminating conditional: `state === '<state-id>'` / similar
+ *
+ * This matches the OQ-8 resolution that explicitly rejected the string-match
+ * path in favour of the existing AST scan infrastructure.
+ *
+ * ### Drift conditions
+ *
+ * Emits `Decision: journey-state-id-drift` when substrate code references:
+ * 1. A state ID that is NOT declared in any active journey.
+ * 2. A state ID from a journey that has been removed (lifecycle = 'removed').
+ *
+ * ### Composition with RFC-0028 OQ-7.2
+ *
+ * Structural drift (this rule at CI authoring time) slots into the structural
+ * side of the OQ-7.2 pairing:
+ * - `severity === 'high'` → BLOCKS PR via Decision severity HIGH.
+ * - `severity === 'medium'` (default) → SURFACES non-blocking via RFC-0035
+ *   G0 catalog route for operator batch review.
+ *
+ * Default severity is `'medium'` per RFC-0018 §10.1 (per-org configurable
+ * via `journey-config.yaml driftDetection.severityOverride`).
+ *
+ * @see spec/rfcs/RFC-0018-in-soul-journey-pattern.md §6.2 + §10.1 OQ-8 + OQ-10
+ * @see spec/rfcs/RFC-0009-tessellated-design-intent-documents.md §13
+ * @see spec/rfcs/RFC-0028-engineering-axis-substrate-enforcement.md OQ-7.2
+ * @see orchestrator/src/tessellation-drift.ts (source of the AST-scan engine reused here)
+ */
+import type { TessellationRule, DriftEvent, DriftSeverity, RuleScanTarget } from '../tessellation/rule-registry.js';
+/**
+ * Discriminator for a single journey-state-id drift finding.
+ *
+ * - `'undeclared-state-id'` — state ID referenced in substrate but not
+ *   declared in any active journey.
+ * - `'removed-journey-state-id'` — state ID referenced in substrate from
+ *   a journey that has been removed (lifecycle = 'removed').
+ */
+export type JourneyStateIdFindingKind = 'undeclared-state-id' | 'removed-journey-state-id';
+/**
+ * A single journey-state-id drift finding from the AST scan.
+ */
+export interface JourneyStateIdFinding {
+    /** What kind of drift was detected. */
+    kind: JourneyStateIdFindingKind;
+    /** The state ID that was found in substrate code. */
+    stateId: string;
+    /** The journey ID the state ID came from (for removed-journey findings). */
+    journeyId?: string;
+    /** The soul ID the journey belongs to (for context). */
+    soulId?: string;
+    /** Path of the substrate file containing the reference. */
+    filePath: string;
+    /** 1-based line number in `filePath`. */
+    line: number;
+    /**
+     * Scan pattern that triggered the finding:
+     * - `'string-literal'`       — bare `'<state-id>'` in substrate code.
+     * - `'state-conditional'`    — `state === '<state-id>'` / similar branching.
+     */
+    pattern: 'string-literal' | 'state-conditional';
+    /** The raw matching line (trimmed, max 200 chars) for operator inspection. */
+    excerpt: string;
+}
+/** Structured details payload for journey-state-id-drift events. */
+export interface JourneyStateIdDriftDetails {
+    rule: 'journey-state-id-drift';
+    findings: JourneyStateIdFinding[];
+}
+/**
+ * Per-org / per-soul drift detection configuration for JourneyStateIdDriftRule.
+ *
+ * Maps to the `driftDetection` block in `.ai-sdlc/journey-config.yaml`
+ * per RFC-0018 §10.1 OQ-8 resolution.
+ */
+export interface JourneyStateIdDriftConfig {
+    /**
+     * Severity override for this rule.
+     *
+     * Per RFC-0028 OQ-7.2:
+     * - `'high'`    → structural-blocking (BLOCKS PR at CI)
+     * - `'medium'`  → non-blocking, RFC-0035 G0 catalog route (DEFAULT)
+     * - `'warning'` → informational
+     */
+    severityOverride?: DriftSeverity;
+}
+/**
+ * JourneyStateIdDriftRule — RFC-0009 §13 Rule #4.
+ *
+ * Scans substrate code for references to journey-state-id strings using
+ * the existing AST scan engine from Rule #1 (OQ-8 resolution: NOT string
+ * match). Emits `Decision: journey-state-id-drift` when:
+ *
+ * - Referenced state ID is not declared in any active journey, OR
+ * - The journey itself has been removed (cross-references journey lifecycle /
+ *   deprecation tooling).
+ *
+ * Severity is per-org configurable (default `'medium'`).
+ *
+ * ### Registration
+ *
+ * ```ts
+ * const registry = createTessellation13Registry();
+ * registry.register(new JourneyStateIdDriftRule());
+ * // With config override:
+ * registry.register(new JourneyStateIdDriftRule({ severityOverride: 'high' }));
+ * ```
+ */
+export declare class JourneyStateIdDriftRule implements TessellationRule {
+    readonly name = "journey-state-id-drift";
+    readonly description = "Scans substrate code for references to journey state IDs that are not declared in any active journey or belong to a removed journey (RFC-0018 Phase 3, OQ-8 resolution)";
+    readonly severity: DriftSeverity;
+    private readonly config;
+    constructor(config?: JourneyStateIdDriftConfig);
+    scan(target: RuleScanTarget): DriftEvent[];
+}
+//# sourceMappingURL=state-id-drift-rule.d.ts.map