@ai-sdlc/orchestrator 0.6.0 → 0.9.0

package/dist/admission-composite.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Admission-subset composite (RFC-0008 §A.6).
+ *
+ * The admission gate uses a subset of the full PPA composite:
+ *
+ *   P_admission = SA × D-pi_adjusted × ER × (1 + HC)
+ *
+ * where:
+ *   SA             = soulAlignment               (0–1)
+ *   D-pi_adjusted  = rawDP × (1 − defectRiskFactor)
+ *   rawDP          = (demand + consensus + conviction + drift) / 4
+ *   ER             = min(baseER × autonomyFactor, designSystemReadiness)
+ *   baseER         = 1 − complexity / 10
+ *   HC             = tanh(weighted sum — see §A.6 Amendment 4)
+ *
+ * M-phi, E-tau, C-kappa are **deferred to runtime scoring** (§A.6 table):
+ * they apply once the issue is admitted and picked up by an executor,
+ * not at the admission gate. To keep the returned `PriorityScore`
+ * shape consistent with downstream consumers, we fill those dimensions
+ * with neutral values: marketForce=1, entropyTax=0, calibration=1
+ * (or the configured calibration coefficient if supplied, for display).
+ *
+ * The `override` bypass is preserved at position 1: when the input has
+ * `override: true`, we return `composite = Infinity` without running
+ * the admission math — identical to the legacy PPA behaviour.
+ */
+import type { PriorityConfig, PriorityInput, PriorityScore } from '@ai-sdlc/reference';
+import type { AdmissionInput } from './admission-score.js';
+import { type AdmissionHumanCurveResult } from './admission-hc.js';
+/**
+ * Result of the admission composite — returns a `PriorityScore`
+ * (backward-compatible with `scoreIssueForAdmission` consumers) plus
+ * the admission-specific breakdown for auditability.
+ */
+export interface AdmissionComposite {
+    score: PriorityScore;
+    breakdown: {
+        soulAlignment: number;
+        rawDemandPressure: number;
+        defectRiskFactor: number;
+        demandPressureAdjusted: number;
+        baseExecutionReality: number;
+        autonomyFactor: number;
+        designSystemReadiness: number;
+        executionReality: number;
+        humanCurve: AdmissionHumanCurveResult;
+    };
+}
+export interface AdmissionCompositeOptions {
+    /**
+     * Optional override for the soulAlignment dimension — when present
+     * (typically a Phase 2b/2c/3 SA-1 from `scoreSoulAlignment`), it
+     * replaces the label-based heuristic. In Phase 2a shadow mode,
+     * callers pass undefined and the label-based fallback applies.
+     */
+    soulAlignmentOverride?: number;
+    /**
+     * Partial PriorityInput overrides applied AFTER `mapIssueToPriorityInput`.
+     * Used by non-GitHub trackers (e.g. Backlog.md adapter) to inject
+     * tracker-specific signals — `priority:p*` labels, AC-derived
+     * complexity, `qualityFlags` — that the GitHub-shaped mapper
+     * cannot extract. Only fields with defined values overwrite.
+     */
+    priorityInputOverrides?: Partial<PriorityInput>;
+}
+export declare function computeAdmissionComposite(input: AdmissionInput, config?: PriorityConfig, options?: AdmissionCompositeOptions): AdmissionComposite;
+//# sourceMappingURL=admission-composite.d.ts.map

package/dist/admission-composite.js

@@ -0,0 +1,158 @@
+/**
+ * Admission-subset composite (RFC-0008 §A.6).
+ *
+ * The admission gate uses a subset of the full PPA composite:
+ *
+ *   P_admission = SA × D-pi_adjusted × ER × (1 + HC)
+ *
+ * where:
+ *   SA             = soulAlignment               (0–1)
+ *   D-pi_adjusted  = rawDP × (1 − defectRiskFactor)
+ *   rawDP          = (demand + consensus + conviction + drift) / 4
+ *   ER             = min(baseER × autonomyFactor, designSystemReadiness)
+ *   baseER         = 1 − complexity / 10
+ *   HC             = tanh(weighted sum — see §A.6 Amendment 4)
+ *
+ * M-phi, E-tau, C-kappa are **deferred to runtime scoring** (§A.6 table):
+ * they apply once the issue is admitted and picked up by an executor,
+ * not at the admission gate. To keep the returned `PriorityScore`
+ * shape consistent with downstream consumers, we fill those dimensions
+ * with neutral values: marketForce=1, entropyTax=0, calibration=1
+ * (or the configured calibration coefficient if supplied, for display).
+ *
+ * The `override` bypass is preserved at position 1: when the input has
+ * `override: true`, we return `composite = Infinity` without running
+ * the admission math — identical to the legacy PPA behaviour.
+ */
+import { mapIssueToPriorityInput } from './admission-score.js';
+import { computeAutonomyFactor, computeDefectRiskFactor, computeReadinessFromDesignSystemContext, } from './admission-enrichment.js';
+import { computeAdmissionHumanCurve } from './admission-hc.js';
+import { computeConfidence } from './priority.js';
+const DEFAULT_SIGNAL = 0.5;
+export function computeAdmissionComposite(input, config, options) {
+    const timestamp = new Date().toISOString();
+    const baseInput = mapIssueToPriorityInput(input);
+    const priorityInput = options?.priorityInputOverrides
+        ? mergePriorityInputOverrides(baseInput, options.priorityInputOverrides)
+        : baseInput;
+    // ── Override path: position-1 bypass (§6 / AC #4) ─────────────
+    if (priorityInput.override) {
+        const score = {
+            composite: Infinity,
+            dimensions: {
+                soulAlignment: 1,
+                demandPressure: 1.5,
+                marketForce: 3.0,
+                executionReality: 1,
+                entropyTax: 0,
+                humanCurve: 1,
+                calibration: clampCalibration(config?.calibrationCoefficient),
+            },
+            confidence: 1,
+            timestamp,
+            override: {
+                reason: priorityInput.overrideReason ?? 'No reason provided',
+                expiry: priorityInput.overrideExpiry,
+            },
+        };
+        return {
+            score,
+            breakdown: {
+                soulAlignment: 1,
+                rawDemandPressure: 1,
+                defectRiskFactor: 0,
+                demandPressureAdjusted: 1,
+                baseExecutionReality: 1,
+                autonomyFactor: 1,
+                designSystemReadiness: 1,
+                executionReality: 1,
+                humanCurve: {
+                    hcExplicit: 0,
+                    hcConsensus: 0,
+                    hcDecision: 0,
+                    hcDesign: 0,
+                    hcRaw: 0,
+                    hcComposite: 1,
+                },
+            },
+        };
+    }
+    // ── SA (soul alignment) — SA-1 override (M5) or label-based fallback ──
+    const soulAlignment = clamp01(options?.soulAlignmentOverride ?? priorityInput.soulAlignment ?? DEFAULT_SIGNAL);
+    // ── D-pi_adjusted ─────────────────────────────────────────────
+    const demand = priorityInput.demandSignal ?? DEFAULT_SIGNAL;
+    const consensus = priorityInput.teamConsensus ?? DEFAULT_SIGNAL;
+    const conviction = priorityInput.builderConviction ?? DEFAULT_SIGNAL;
+    const drift = priorityInput.competitiveDrift ?? 0;
+    const rawDemandPressure = clamp01((demand + consensus + conviction + drift) / 4);
+    const defectRiskFactor = computeDefectRiskFactor(input.codeAreaQuality);
+    const demandPressureAdjusted = rawDemandPressure * (1 - defectRiskFactor);
+    // ── ER (execution reality) ─────────────────────────────────────
+    // baseER = 1 - complexity/10; complexity defaults to neutral midpoint.
+    const complexity = priorityInput.complexity ?? 5;
+    const baseExecutionReality = clamp01(1 - complexity / 10);
+    const autonomyFactor = computeAutonomyFactor(input.autonomyContext);
+    const designSystemReadiness = computeReadinessFromDesignSystemContext(input.designSystemContext);
+    const executionReality = Math.min(baseExecutionReality * autonomyFactor, designSystemReadiness);
+    // ── HC (tanh-compressed with HC_design) ───────────────────────
+    const humanCurve = computeAdmissionHumanCurve(input);
+    // ── §A.6 admission subset composite ───────────────────────────
+    const composite = soulAlignment * demandPressureAdjusted * executionReality * (1 + humanCurve.hcComposite);
+    const score = {
+        composite,
+        dimensions: {
+            soulAlignment,
+            demandPressure: demandPressureAdjusted,
+            // M-phi deferred to runtime — neutral for admission.
+            marketForce: 1,
+            executionReality,
+            // E-tau deferred to runtime — admission does not apply the
+            // entropy tax (competitiveDrift feeds rawDP instead).
+            entropyTax: 0,
+            humanCurve: humanCurve.hcComposite,
+            // C-kappa deferred to runtime — expose configured value for
+            // display continuity but do not multiply it into `composite`.
+            calibration: clampCalibration(config?.calibrationCoefficient),
+        },
+        confidence: computeConfidence(priorityInput),
+        timestamp,
+    };
+    return {
+        score,
+        breakdown: {
+            soulAlignment,
+            rawDemandPressure,
+            defectRiskFactor,
+            demandPressureAdjusted,
+            baseExecutionReality,
+            autonomyFactor,
+            designSystemReadiness,
+            executionReality,
+            humanCurve,
+        },
+    };
+}
+function clamp01(value) {
+    return Math.min(1, Math.max(0, value));
+}
+function clampCalibration(value) {
+    if (value === undefined)
+        return 1.0;
+    return Math.min(1.3, Math.max(0.7, value));
+}
+/**
+ * Apply non-GitHub tracker overrides on top of the GitHub-shaped
+ * `mapIssueToPriorityInput` output. A field's override wins iff it is
+ * not `undefined`; this preserves the GitHub mapper's defaults for
+ * any field the override does not specify.
+ */
+function mergePriorityInputOverrides(base, overrides) {
+    const merged = { ...base };
+    for (const [key, value] of Object.entries(overrides)) {
+        if (value !== undefined) {
+            merged[key] = value;
+        }
+    }
+    return merged;
+}
+//# sourceMappingURL=admission-composite.js.map

package/dist/admission-enrichment.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Bridge between stateless admission scoring and the stateful orchestrator
+ * (RFC-0008 Addendum A §A.2 – §A.5).
+ *
+ * `enrichAdmissionInput()` reads from the orchestrator's state store and
+ * resolved resources to populate the RFC-0008 context fields on
+ * `AdmissionInput`, then `computeDesignSystemReadiness()` produces the
+ * Eρ₄ scalar that feeds the admission composite in §A.6.
+ *
+ * Scope for AISDLC-43: implement C2 (Eρ₄) only. C3/C4/C5 are populated
+ * by later tasks (AISDLC-44/45/46).
+ */
+import type { AutonomyPolicy, DesignIntentDocument, DesignSystemBinding } from '@ai-sdlc/reference';
+import type { StateStore } from './state/store.js';
+import type { AdmissionInput, AutonomyContext, CodeAreaQuality, DesignAuthoritySignal, DesignSystemContext } from './admission-score.js';
+/**
+ * Minimum data points required before `code_area_metrics` is trusted
+ * enough to drive defect-risk penalties (RFC-0008 §7.4 Open Question 4).
+ */
+export declare const CODE_AREA_METRICS_MIN_DATA_POINTS = 10;
+export type LifecyclePhase = 'preDesignSystem' | 'catalogBootstrap' | 'postDesignSystem';
+export interface EnrichmentContext {
+    /** State store for reading visual baselines and code-area metrics. */
+    stateStore?: StateStore;
+    /** Resolved DesignSystemBinding referenced by the DID (absent ⇒ preDesignSystem). */
+    designSystemBinding?: DesignSystemBinding;
+    /** Resolved DesignIntentDocument. Unused in C2 but threaded through for future connections. */
+    designIntentDocument?: DesignIntentDocument;
+    /** ISO timestamp when the DSB was adopted — used for age-based lifecycle detection. */
+    dsbAdoptedAt?: string;
+    /** Catalog gaps supplied by a catalog-provider adapter (AISDLC-43 accepts these pre-computed). */
+    catalogGaps?: string[];
+    /** Code area for the issue (e.g. "orchestrator/src/priority"), used by C3. */
+    codeArea?: string;
+    /** Resolved AutonomyPolicy — used by C4. */
+    autonomyPolicy?: AutonomyPolicy;
+    /**
+     * Agent expected to handle the issue. Used to pick a specific entry
+     * from `autonomyPolicy.status.agents`. When absent, the most
+     * permissive currently-earned level across all agents is used.
+     */
+    agentName?: string;
+    /**
+     * Task complexity in [0, 10] for mapping to a required autonomy level.
+     * When omitted, C4 falls back to the most permissive level for the
+     * resolved agent (requiredLevel = currentEarnedLevel → gap = 0).
+     */
+    complexity?: number;
+    /**
+     * Compliance score for the issue's area in [0, 1]. When present,
+     * `designAuthorityWeight` is modulated by `(1.2 - areaComplianceScore)`.
+     * When absent, the base weight applies unmodulated.
+     */
+    areaComplianceScore?: number;
+    /** Clock injection for deterministic tests. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * Populate `designSystemContext` on the admission input using the
+ * resolved DSB and state store. Returns the input unchanged when no DSB
+ * is available (preDesignSystem phase — caller falls through to the
+ * stateless path).
+ */
+export declare function enrichAdmissionInput(input: AdmissionInput, ctx: EnrichmentContext): AdmissionInput;
+/**
+ * Compute the C3 defect-risk factor per §A.5. Returns 0 when
+ * `codeAreaQuality` is absent (insufficient data → no penalty).
+ *
+ *   !hasFrontendComponents  → 0.5×dd + 0.3×churn + 0.2×prRej
+ *   hasFrontendComponents
+ *     no designQuality      → same as pure code (no blend target)
+ *     with designQuality    → 0.7 × code + 0.3 × design
+ *                              where design = 0.4×(1-ciPass)
+ *                                           + 0.4×reviewRej
+ *                                           + 0.2×(1-usabPass)
+ *
+ * Final value is clamped to [0, 0.5].
+ */
+export declare function computeDefectRiskFactor(quality: CodeAreaQuality | undefined): number;
+/**
+ * Map task complexity to the required autonomy level per §A.4:
+ *   complexity ≤ 3  → level 1
+ *   complexity ≤ 6  → level 2
+ *   else            → level 3
+ */
+export declare function complexityToAutonomyLevel(complexity: number): number;
+/**
+ * Compute the C4 autonomy factor per §A.5:
+ *   gap = requiredLevel - currentEarnedLevel
+ *   gap > 0  → max(0.1, 1.0 - gap × 0.4)
+ *   gap ≤ 0  → 1.0
+ */
+export declare function computeAutonomyFactor(ctx: AutonomyContext | undefined): number;
+/**
+ * Compute the C5 design-authority weight per §A.5.
+ *
+ *   non-authority           → 0.0
+ *   authority + positive    → +0.6 × modulation
+ *   authority + negative    → -0.4 × modulation
+ *   authority + no type     → +0.3 × modulation
+ *
+ * where `modulation = 1.2 - areaComplianceScore` when the score is
+ * supplied, else `1.0` (unmodulated base weight).
+ */
+export declare function computeDesignAuthorityWeight(signal: DesignAuthoritySignal | undefined): number;
+/**
+ * Compute the C2 Eρ₄ design-system readiness scalar in [0, 1] per §A.5.
+ *
+ *   preDesignSystem:   1.0 (no DSB → no penalty)
+ *   catalogBootstrap:  max(0.3, 0.4×cat + 0.3×tok + 0.3×baseline)
+ *   postDesignSystem:  0.4×cat + 0.3×tok + 0.3×baseline
+ */
+export declare function computeDesignSystemReadiness(ctx: EnrichmentContext): number;
+/**
+ * Compute the C2 Eρ₄ scalar directly from the DesignSystemContext
+ * already populated on an `AdmissionInput` (no DSB/state lookups).
+ *
+ *   undefined (preDesignSystem) → 1.0
+ *   inBootstrapPhase            → max(0.3, computed)
+ *   else                        → computed
+ *
+ * Used by the admission composite (§A.6) to avoid re-reading the state
+ * store on every score call.
+ */
+export declare function computeReadinessFromDesignSystemContext(context: DesignSystemContext | undefined): number;
+export declare function detectLifecyclePhase(binding: DesignSystemBinding | undefined, normalizedCatalogCoverage: number, ageDays: number): LifecyclePhase;
+/**
+ * Days since the DSB was adopted. Returns 0 when no adoption timestamp
+ * is supplied — the conservative default (treats DSB as brand-new and
+ * favours the bootstrap floor).
+ */
+export declare function computeDsbAgeDays(adoptedAt: string | undefined, now?: () => number): number;
+/**
+ * Fraction of the UI under visual-regression monitoring for this binding,
+ * derived from approved baselines in `visual_regression_results`.
+ *
+ * Definition (§A.5 proxy): `approvedBaselines / totalBaselines`. Returns
+ * 0 when no history exists (bootstrap protection: avoids over-crediting
+ * readiness when the monitor hasn't run yet).
+ */
+export declare function computeBaselineCoverage(store: StateStore, bindingName: string): number;
+//# sourceMappingURL=admission-enrichment.d.ts.map