@ai-sdlc/orchestrator 0.6.0 → 0.10.0

package/dist/sa-scoring/layer1-deterministic.js

@@ -0,0 +1,298 @@
+/**
+ * Layer 1 — Deterministic SA scorer (RFC-0008 Addendum B §B.4).
+ *
+ * Consumes a `CompiledDid` + issue text + state store metrics and
+ * produces a fully-deterministic scoring result. Layer 1 never makes
+ * network or LLM calls *except* for the dep-parse sidecar (for
+ * requirement-construction detection).
+ *
+ * A `core` out-of-scope match is a **hard gate** — downstream SA-1
+ * scoring must treat `hardGated=true` as SA-1 = 0.0 regardless of
+ * Layer 2/3 output. Evolving matches surface as warnings but do not
+ * gate admission.
+ */
+import { DepparseError } from './depparse-client.js';
+// ── Tokenization / matching ──────────────────────────────────────────
+function lower(s) {
+    return s.toLowerCase();
+}
+function includesWhole(haystack, needle) {
+    if (!needle)
+        return false;
+    // Whole-word-ish match: bounds on non-alphanumeric.
+    const re = new RegExp(`(^|[^a-z0-9])${escapeRegex(lower(needle))}($|[^a-z0-9])`, 'i');
+    return re.test(haystack);
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+// ── Scope gate ───────────────────────────────────────────────────────
+export function checkScopeGate(issueText, compiled) {
+    const text = lower(issueText);
+    const inHits = [];
+    const outHits = [];
+    const warnings = [];
+    let hardGated = false;
+    for (const entry of compiled.scopeLists.inScope) {
+        const all = [entry.label, ...entry.synonyms];
+        for (const term of all) {
+            if (includesWhole(text, term)) {
+                inHits.push({
+                    label: entry.label,
+                    synonym: term === entry.label ? undefined : term,
+                    identityClass: entry.identityClass,
+                    matchedText: term,
+                });
+                break;
+            }
+        }
+    }
+    for (const entry of compiled.scopeLists.outOfScope) {
+        const all = [entry.label, ...entry.synonyms];
+        for (const term of all) {
+            if (includesWhole(text, term)) {
+                outHits.push({
+                    label: entry.label,
+                    synonym: term === entry.label ? undefined : term,
+                    identityClass: entry.identityClass,
+                    matchedText: term,
+                });
+                if (entry.identityClass === 'core') {
+                    hardGated = true;
+                }
+                else {
+                    warnings.push(`Evolving out-of-scope match: "${entry.label}" via "${term}"`);
+                }
+                break;
+            }
+        }
+    }
+    return { inScopeHits: inHits, outOfScopeHits: outHits, hardGated, warnings };
+}
+// ── Constraint violations (via depparse sidecar) ─────────────────────
+export async function detectConstraintViolations(issueText, compiled, client) {
+    const violations = [];
+    let depparseSkipped = false;
+    for (const rule of compiled.constraintRules) {
+        // Only enforce `must-not-require` / `must-not-include` via depparse;
+        // `must-require` / `must-include` are positive constraints (enforced
+        // downstream as signal requirements, not as violation checks).
+        if (rule.relationship !== 'must-not-require' && rule.relationship !== 'must-not-include') {
+            continue;
+        }
+        let response;
+        try {
+            response = await client.match({
+                text: issueText,
+                patterns: rule.detectionPatterns,
+            });
+        }
+        catch (err) {
+            if (err instanceof DepparseError &&
+                (err.kind === 'model-unavailable' || err.kind === 'network' || err.kind === 'timeout')) {
+                depparseSkipped = true;
+                continue;
+            }
+            throw err;
+        }
+        for (const match of response.matches) {
+            violations.push(buildViolation(rule, match));
+        }
+    }
+    return { violations, depparseSkipped };
+}
+function buildViolation(rule, match) {
+    return {
+        constraintId: rule.id,
+        concept: rule.concept,
+        relationship: rule.relationship,
+        pattern: match.pattern,
+        matchedText: match.matchedText,
+        construction: match.construction,
+        depPath: match.depPath,
+        identityClass: rule.identityClass,
+    };
+}
+// ── Anti-pattern matching ────────────────────────────────────────────
+function matchAntiPatterns(text, list, scope, principleId) {
+    const hits = [];
+    for (const ap of list) {
+        for (const pattern of ap.detectionPatterns) {
+            if (includesWhole(text, pattern)) {
+                hits.push({
+                    id: ap.id,
+                    label: ap.label,
+                    pattern,
+                    matchedText: pattern,
+                    identityClass: ap.identityClass,
+                    scope,
+                    ...(principleId ? { principleId } : {}),
+                });
+            }
+        }
+    }
+    return hits;
+}
+export function detectAntiPatterns(issueText, compiled) {
+    const text = lower(issueText);
+    const productHits = matchAntiPatterns(text, compiled.antiPatternLists.product, 'product');
+    const designHits = [];
+    for (const [principleId, list] of Object.entries(compiled.antiPatternLists.perPrinciple)) {
+        designHits.push(...matchAntiPatterns(text, list, 'design-principle', principleId));
+    }
+    designHits.push(...matchAntiPatterns(text, compiled.antiPatternLists.voice, 'voice'));
+    designHits.push(...matchAntiPatterns(text, compiled.antiPatternLists.visual, 'visual'));
+    return {
+        product: { hits: productHits },
+        design: { hits: designHits },
+    };
+}
+// ── Measurable signal checks ─────────────────────────────────────────
+export function checkMeasurableSignals(observed, compiled) {
+    const checks = [];
+    let coreFailureCount = 0;
+    for (const signal of compiled.measurableSignals) {
+        const value = observed[signal.metric];
+        let status;
+        if (value === undefined || Number.isNaN(value)) {
+            status = 'missing';
+        }
+        else {
+            status = evaluateOperator(value, signal.threshold, signal.operator) ? 'pass' : 'fail';
+        }
+        checks.push({
+            id: signal.id,
+            metric: signal.metric,
+            threshold: signal.threshold,
+            operator: signal.operator,
+            observedValue: value,
+            status,
+            identityClass: signal.identityClass,
+        });
+        if (status === 'fail' && signal.identityClass === 'core')
+            coreFailureCount++;
+    }
+    return { checks, coreFailureCount };
+}
+function evaluateOperator(value, threshold, operator) {
+    switch (operator) {
+        case 'gte':
+            return value >= threshold;
+        case 'lte':
+            return value <= threshold;
+        case 'gt':
+            return value > threshold;
+        case 'lt':
+            return value < threshold;
+        case 'eq':
+            return value === threshold;
+        case 'neq':
+            return value !== threshold;
+        default:
+            return false;
+    }
+}
+export async function runLayer1(input) {
+    const { issueText, compiled, depparse, observedMetrics = {} } = input;
+    const scopeGate = checkScopeGate(issueText, compiled);
+    const constraintViolations = await detectConstraintViolations(issueText, compiled, depparse);
+    const { product, design } = detectAntiPatterns(issueText, compiled);
+    const measurable = checkMeasurableSignals(observedMetrics, compiled);
+    // Count core vs evolving violations across all dimensions.
+    let coreViolationCount = 0;
+    let evolvingViolationCount = 0;
+    const bump = (ic) => {
+        if (ic === 'core')
+            coreViolationCount++;
+        else
+            evolvingViolationCount++;
+    };
+    for (const hit of scopeGate.outOfScopeHits)
+        bump(hit.identityClass);
+    for (const v of constraintViolations.violations)
+        bump(v.identityClass);
+    for (const h of product.hits)
+        bump(h.identityClass);
+    for (const h of design.hits)
+        bump(h.identityClass);
+    coreViolationCount += measurable.coreFailureCount;
+    const hardGated = scopeGate.hardGated;
+    const preVerifiedSummary = renderPreVerifiedSummary({
+        scopeGate,
+        constraintViolations,
+        product,
+        design,
+        measurable,
+        hardGated,
+        coreViolationCount,
+        evolvingViolationCount,
+    });
+    return {
+        scopeGate,
+        constraintViolations,
+        antiPatternHits: product,
+        designAntiPatternHits: design,
+        measurableSignalChecks: measurable,
+        hardGated,
+        coreViolationCount,
+        evolvingViolationCount,
+        preVerifiedSummary,
+    };
+}
+export function renderPreVerifiedSummary(input) {
+    const lines = [];
+    lines.push('## Deterministic verification');
+    lines.push('');
+    lines.push(`- Hard gated: ${input.hardGated ? 'yes' : 'no'}`);
+    lines.push(`- Core violations: ${input.coreViolationCount}`);
+    lines.push(`- Evolving violations: ${input.evolvingViolationCount}`);
+    lines.push('');
+    lines.push('### Scope gate');
+    if (input.scopeGate.outOfScopeHits.length === 0) {
+        lines.push('- No out-of-scope hits');
+    }
+    else {
+        for (const hit of input.scopeGate.outOfScopeHits) {
+            lines.push(`- ${hit.identityClass} OUT — "${hit.label}"` +
+                (hit.synonym ? ` via "${hit.synonym}"` : ''));
+        }
+    }
+    lines.push('');
+    lines.push('### Constraint violations');
+    if (input.constraintViolations.violations.length === 0) {
+        lines.push('- None detected');
+        if (input.constraintViolations.depparseSkipped) {
+            lines.push('- (depparse sidecar unavailable — skipped)');
+        }
+    }
+    else {
+        for (const v of input.constraintViolations.violations) {
+            lines.push(`- ${v.identityClass} ${v.constraintId} (${v.relationship} ${v.concept}) — "${v.matchedText}"` +
+                (v.construction ? ` via ${v.construction}` : ''));
+        }
+    }
+    lines.push('');
+    lines.push('### Anti-pattern hits');
+    const allAntiHits = [...input.product.hits, ...input.design.hits];
+    if (allAntiHits.length === 0) {
+        lines.push('- None detected');
+    }
+    else {
+        for (const h of allAntiHits) {
+            lines.push(`- ${h.identityClass} [${h.scope}${h.principleId ? `:${h.principleId}` : ''}] ${h.label} — "${h.matchedText}"`);
+        }
+    }
+    lines.push('');
+    lines.push('### Measurable signals');
+    const failures = input.measurable.checks.filter((c) => c.status === 'fail');
+    if (failures.length === 0) {
+        lines.push('- No failing signals');
+    }
+    else {
+        for (const c of failures) {
+            lines.push(`- ${c.identityClass} ${c.id} (${c.metric} ${c.operator} ${c.threshold}) — observed ${c.observedValue ?? 'n/a'}`);
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=layer1-deterministic.js.map

package/dist/sa-scoring/layer2-structural.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Layer 2 — Structural BM25 scorer (RFC-0008 Addendum B §B.5).
+ *
+ *   computeDomainRelevance(issueText, bm25Corpus)   → SA-1 [0, 1]
+ *   computePrincipleCoverage(issueText, principleCorpora) → SA-2 vector
+ *
+ * Uses a minimal in-process BM25 implementation — no external index
+ * library needed. The corpus is tokenized at compile time
+ * (`did-compiler.ts`), so scoring is O(|query| × |corpus|) per call.
+ *
+ * Determinism: pure functions, no randomness, arithmetic-only. Same
+ * inputs → bit-exact outputs.
+ */
+import type { Bm25Corpus, PrincipleCorpora } from './did-compiler.js';
+interface Bm25Index {
+    /** The weighted-document list — each carries its own TF map + length. */
+    docs: Array<{
+        id: string;
+        weight: number;
+        length: number;
+        termFreq: Map<string, number>;
+    }>;
+    /** Number of documents that contain each term (for IDF). */
+    docFreq: Map<string, number>;
+    /** Average document length (weighted). */
+    avgDocLength: number;
+}
+declare function buildIndex(corpus: Bm25Corpus): Bm25Index;
+declare function idf(term: string, index: Bm25Index): number;
+declare function scoreDoc(queryTokens: readonly string[], doc: Bm25Index['docs'][number], index: Bm25Index): {
+    score: number;
+    termContributions: Map<string, number>;
+};
+declare function normalizeScore(rawScore: number): number;
+declare function topTerms(contributions: Map<string, number>, limit: number): ContributingTerm[];
+export interface ContributingTerm {
+    term: string;
+    score: number;
+}
+export interface DomainRelevanceResult {
+    /** Normalized relevance in [0, 1]. */
+    score: number;
+    /** Raw BM25 sum before normalization (for debugging / calibration). */
+    rawScore: number;
+    /** Top contributing terms, sorted by contribution score. */
+    contributingTerms: ContributingTerm[];
+    /** Number of query tokens after stopword stripping. */
+    queryLength: number;
+}
+export interface PrincipleCoverageEntry {
+    principleId: string;
+    coverage: number;
+    identityClass: 'core' | 'evolving';
+    contributingTerms: ContributingTerm[];
+}
+export interface PrincipleCoverageVector {
+    principles: PrincipleCoverageEntry[];
+    /** Weighted mean — core principles count twice, evolving once. */
+    overallCoverage: number;
+}
+export declare function computeDomainRelevance(issueText: string, corpus: Bm25Corpus): DomainRelevanceResult;
+export declare function computePrincipleCoverage(issueText: string, principleCorpora: PrincipleCorpora): PrincipleCoverageVector;
+export declare const __internals: {
+    buildIndex: typeof buildIndex;
+    idf: typeof idf;
+    scoreDoc: typeof scoreDoc;
+    normalizeScore: typeof normalizeScore;
+    topTerms: typeof topTerms;
+};
+export {};
+//# sourceMappingURL=layer2-structural.d.ts.map

package/dist/sa-scoring/layer2-structural.js

@@ -0,0 +1,151 @@
+/**
+ * Layer 2 — Structural BM25 scorer (RFC-0008 Addendum B §B.5).
+ *
+ *   computeDomainRelevance(issueText, bm25Corpus)   → SA-1 [0, 1]
+ *   computePrincipleCoverage(issueText, principleCorpora) → SA-2 vector
+ *
+ * Uses a minimal in-process BM25 implementation — no external index
+ * library needed. The corpus is tokenized at compile time
+ * (`did-compiler.ts`), so scoring is O(|query| × |corpus|) per call.
+ *
+ * Determinism: pure functions, no randomness, arithmetic-only. Same
+ * inputs → bit-exact outputs.
+ */
+import { tokenize } from './did-compiler.js';
+// ── BM25 hyper-parameters ────────────────────────────────────────────
+const K1 = 1.2;
+const B = 0.75;
+/** Used to squash raw BM25 score into [0, 1). */
+const NORMALIZE_ALPHA = 5.0;
+const CONTRIBUTING_TERMS_LIMIT = 10;
+function buildIndex(corpus) {
+    const docs = corpus.documents.map((doc) => {
+        const termFreq = new Map();
+        for (const tok of doc.tokens)
+            termFreq.set(tok, (termFreq.get(tok) ?? 0) + 1);
+        return {
+            id: doc.id,
+            weight: doc.weight,
+            length: doc.tokens.length * doc.weight,
+            termFreq,
+        };
+    });
+    const docFreq = new Map();
+    for (const doc of docs) {
+        for (const term of doc.termFreq.keys()) {
+            docFreq.set(term, (docFreq.get(term) ?? 0) + 1);
+        }
+    }
+    const totalLength = docs.reduce((sum, d) => sum + d.length, 0);
+    const avgDocLength = docs.length === 0 ? 0 : totalLength / docs.length;
+    return { docs, docFreq, avgDocLength };
+}
+function idf(term, index) {
+    const n = index.docFreq.get(term) ?? 0;
+    const N = index.docs.length;
+    // Smoothed BM25 IDF (non-negative even for common terms)
+    return Math.log((N - n + 0.5) / (n + 0.5) + 1);
+}
+function scoreDoc(queryTokens, doc, index) {
+    let score = 0;
+    const contributions = new Map();
+    const lengthNorm = index.avgDocLength === 0 ? 1 : 1 - B + B * (doc.length / index.avgDocLength);
+    for (const term of queryTokens) {
+        const rawTf = doc.termFreq.get(term);
+        if (!rawTf)
+            continue;
+        const tf = rawTf * doc.weight;
+        const termIdf = idf(term, index);
+        const contribution = (termIdf * (tf * (K1 + 1))) / (tf + K1 * lengthNorm);
+        score += contribution;
+        contributions.set(term, (contributions.get(term) ?? 0) + contribution);
+    }
+    return { score, termContributions: contributions };
+}
+function normalizeScore(rawScore) {
+    if (rawScore <= 0)
+        return 0;
+    // Monotonic squash into [0, 1) — `tanh(score / α)` is smooth and
+    // deterministic. Tune α to taste (higher = slower saturation).
+    return Math.tanh(rawScore / NORMALIZE_ALPHA);
+}
+function topTerms(contributions, limit) {
+    return Array.from(contributions.entries())
+        .map(([term, score]) => ({ term, score }))
+        .sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        // Tie-break alphabetically for determinism.
+        return a.term < b.term ? -1 : a.term > b.term ? 1 : 0;
+    })
+        .slice(0, limit);
+}
+// ── Public API ───────────────────────────────────────────────────────
+export function computeDomainRelevance(issueText, corpus) {
+    const queryTokens = tokenize(issueText);
+    if (queryTokens.length === 0 || corpus.documents.length === 0) {
+        return {
+            score: 0,
+            rawScore: 0,
+            contributingTerms: [],
+            queryLength: queryTokens.length,
+        };
+    }
+    const index = buildIndex(corpus);
+    const aggregateContributions = new Map();
+    let totalScore = 0;
+    let maxDocScore = 0;
+    for (const doc of index.docs) {
+        const { score, termContributions } = scoreDoc(queryTokens, doc, index);
+        totalScore += score;
+        if (score > maxDocScore)
+            maxDocScore = score;
+        for (const [term, v] of termContributions) {
+            aggregateContributions.set(term, (aggregateContributions.get(term) ?? 0) + v);
+        }
+    }
+    // For domainRelevance, use the MAX doc score (the best-matching doc).
+    // This avoids diluting a tight match in the mission doc by a long
+    // irrelevant experientialTargets doc.
+    const rawScore = maxDocScore;
+    void totalScore;
+    return {
+        score: normalizeScore(rawScore),
+        rawScore,
+        contributingTerms: topTerms(aggregateContributions, CONTRIBUTING_TERMS_LIMIT),
+        queryLength: queryTokens.length,
+    };
+}
+export function computePrincipleCoverage(issueText, principleCorpora) {
+    const entries = [];
+    for (const principleId of Object.keys(principleCorpora).sort()) {
+        const corpus = principleCorpora[principleId];
+        const relevance = computeDomainRelevance(issueText, corpus);
+        const firstDoc = corpus.documents[0];
+        const identityClass = firstDoc && firstDoc.weight === 2 ? 'core' : 'evolving';
+        entries.push({
+            principleId,
+            coverage: relevance.score,
+            identityClass,
+            contributingTerms: relevance.contributingTerms,
+        });
+    }
+    // Weighted mean: core = 2, evolving = 1.
+    const weighted = entries.reduce((acc, e) => {
+        const w = e.identityClass === 'core' ? 2 : 1;
+        acc.sum += e.coverage * w;
+        acc.weight += w;
+        return acc;
+    }, { sum: 0, weight: 0 });
+    const overallCoverage = weighted.weight === 0 ? 0 : weighted.sum / weighted.weight;
+    return { principles: entries, overallCoverage };
+}
+// ── Exported internals for testing ───────────────────────────────────
+export const __internals = {
+    buildIndex,
+    idf,
+    scoreDoc,
+    normalizeScore,
+    topTerms,
+};
+//# sourceMappingURL=layer2-structural.js.map

package/dist/sa-scoring/layer3-llm.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Layer 3 — LLM structured assessment (RFC-0008 Addendum B §B.6).
+ *
+ * Builds SA-1 (domain-intent) and SA-2 (principle-alignment) prompts
+ * with the Layer 1 preVerifiedSummary injected as a "CI-Boundary"
+ * block — the LLM is explicitly told NOT to re-assess scope /
+ * constraints / anti-patterns / signals (deterministically verified).
+ * Parses structured JSON output and applies a confidence filter:
+ * findings with `confidence < 0.5` are suppressed.
+ *
+ * Amendment 2 (v4 §5.2): the SA-2 prompt MUST NOT include
+ * `tokenCompliance` or `catalogHealth` — those are covered by the C1
+ * computable half of SA-2 and re-including them double-counts.
+ */
+import type { DesignIntentDocument, DesignSystemBinding } from '@ai-sdlc/reference';
+export interface LLMClient {
+    complete(prompt: string): Promise<string>;
+}
+/** Deterministic fake for tests — no network calls. */
+export declare class RecordedLLMClient implements LLMClient {
+    private responseByPrompt;
+    private fallbackResponse?;
+    readonly promptLog: string[];
+    setResponse(promptSubstring: string, response: string): void;
+    setFallbackResponse(response: string): void;
+    complete(prompt: string): Promise<string>;
+}
+export interface SubtleConflict {
+    description: string;
+    severity: 'low' | 'medium' | 'high';
+    confidence: number;
+}
+export interface SubtleDesignConflict extends SubtleConflict {
+    /** Principle this conflict relates to (optional). */
+    principleId?: string;
+}
+export interface LLMScoringResult {
+    /** SA-1 domain-intent score in [0, 1], 0 if below confidence filter. */
+    domainIntent: number;
+    domainIntentConfidence: number;
+    subtleConflicts: SubtleConflict[];
+    /** SA-2 principle-alignment score in [0, 1]. */
+    principleAlignment: number;
+    principleAlignmentConfidence: number;
+    subtleDesignConflicts: SubtleDesignConflict[];
+    /** Always true — signals the CI boundary block was applied. */
+    preVerifiedBoundaryApplied: true;
+    /** Count of findings dropped by the confidence filter (<0.5). */
+    suppressedFindings: number;
+}
+export type LayerLlmErrorKind = 'malformed-json' | 'missing-field' | 'invalid-range';
+export declare class LayerLlmError extends Error {
+    readonly kind: LayerLlmErrorKind;
+    readonly raw?: string;
+    constructor(kind: LayerLlmErrorKind, message: string, raw?: string);
+}
+export declare const CONFIDENCE_THRESHOLD = 0.5;
+export declare const CI_BOUNDARY_HEADER = "## CI-Boundary: pre-verified (do not re-assess)";
+/** Guidance line that MUST appear verbatim in both SA-1 and SA-2 prompts. */
+export declare const SCOPE_GUIDANCE = "Do not re-assess scope, constraints, anti-patterns, or measurable signals \u2014 they have been deterministically verified above.";
+/**
+ * Wraps user-controlled issue text in a tagged block so the model
+ * treats its contents as data, not instructions. Defends against
+ * prompt-injection attempts that try to override the CI-Boundary
+ * block (e.g. issue bodies starting with `## Task` or `## CI-Boundary`).
+ */
+export declare const UNTRUSTED_CONTENT_GUIDANCE: string;
+export interface PromptContext {
+    issueText: string;
+    did: DesignIntentDocument;
+    dsb?: DesignSystemBinding;
+    preVerifiedSummary: string;
+}
+export declare function buildSa1Prompt(ctx: PromptContext): string;
+export declare function buildSa2Prompt(ctx: PromptContext): string;
+/** Extract the first JSON object from a raw LLM reply. */
+export declare function extractJson(raw: string): unknown;
+export interface Layer3Input {
+    issueText: string;
+    did: DesignIntentDocument;
+    dsb?: DesignSystemBinding;
+    preVerifiedSummary: string;
+    llm: LLMClient;
+}
+export declare function runLayer3(input: Layer3Input): Promise<LLMScoringResult>;
+//# sourceMappingURL=layer3-llm.d.ts.map