@ai-sdlc/orchestrator 0.9.0 → 0.13.0

package/dist/tessellation-drift.js

@@ -0,0 +1,250 @@
+/**
+ * RFC-0009 Phase 4.2 — Eτ_tessellation_drift detector (orchestrator-side).
+ *
+ * Detects design-coherence drift across tessellated souls per RFC-0009 §7.2
+ * (OQ-6 resolution: detection is orchestrator-side, not adapter-side).
+ *
+ * Three detection rules are specified in §7.2:
+ *
+ *   Rule #1 — AST scan for soul-name string literals in shared substrate
+ *             SHIPS HERE. Static scan over the substrate file set looking for
+ *             soul-slug string literals and `if (soul === '<slug>')` patterns
+ *             in modules that are NOT scoped to a single soul.
+ *
+ *   Rule #2 — Embedding distance between Soul DIDs over time
+ *             EXPLICITLY DEFERRED to RFC-0019 (Embedding Provider Adapter).
+ *             Not implemented here; would land in a separate detector once
+ *             `embedDocument(text)` is callable from the orchestrator.
+ *
+ *   Rule #3 — Cross-soul provenance audits
+ *             SHIPS HERE. Walks the supplied provenance records (RFC-0009 §8.3
+ *             ProvenanceRecord with `targetedSouls`, `substrateScoped`,
+ *             `tessellatedSoulRef`, all landed by AISDLC-315) and flags work
+ *             whose `targetedSouls` set crosses tessellation boundaries
+ *             without an amendment record; flags substrate work whose
+ *             downstream provenance shows soul-distinct outcomes diverge.
+ *
+ * Both shipped rules are gated on adopter opt-in via `enabled` (default
+ * `false`) per RFC-0009 §10 Phase 4 promotion convention ("All sub-dimension
+ * activations are gated on adopter opt-in initially").
+ *
+ * Detected drift events emit to `events.jsonl` (the RFC-0015 substrate) via
+ * the supplied `emit` callback. Callers wire this to
+ * `orchestrator/src/artifacts.appendEvent(artifactsDir, event)`.
+ *
+ * @see spec/rfcs/RFC-0009-tessellated-design-intent-documents.md §7.2 + §10
+ */
+export const DEFAULT_DIVERGENCE_THRESHOLD = 0.3;
+// ── Internal helpers ───────────────────────────────────────────────────
+/**
+ * Validate a soul slug. Mirrors `TessellationSoul.soulId` JSON-schema
+ * constraint: lowercase alphanumeric + dashes, 1-64 chars.
+ */
+function isValidSlug(slug) {
+    return /^[a-z0-9-]+$/.test(slug) && slug.length >= 1 && slug.length <= 64;
+}
+/**
+ * Escape a string for safe use inside a RegExp character class / pattern.
+ * The soul slug grammar already excludes regex metacharacters, but this
+ * stays defensive in case future schema changes admit more chars.
+ */
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Scan one substrate file for soul-leakage patterns.
+ *
+ * Detection strategy is deliberately textual rather than full-parser-AST.
+ * RFC-0009 §7.2 calls this "AST scan" but a regex pass over source files
+ * is the framework primitive that ships today and matches the rule's
+ * goal — surface soul-slug leakage in substrate code for operator review.
+ * False positives (e.g., the slug appearing inside a code comment) are
+ * accepted as part of the surface; operators triage and silence per-file
+ * via a tessellation amendment if needed.
+ *
+ * Two patterns are scanned, both line-by-line so we report 1-based line
+ * numbers in findings:
+ *
+ *   1. `'<slug>'` or `"<slug>"` — bare string-literal match.
+ *   2. `if (soul === '<slug>')` / `=== "<slug>"` — soul-discriminating branch.
+ *      Soul identifier is matched permissively (`soul`, `soulId`, `soul_id`).
+ */
+function scanSubstrateFile(file, soulSlugs) {
+    const findings = [];
+    if (file.contents.length === 0)
+        return findings;
+    // Pre-compile patterns per soul slug so we walk the file once per slug.
+    // Files are typically small (<5KB per substrate file in practice) so
+    // the O(N×S) walk is fine without further optimization.
+    const lines = file.contents.split('\n');
+    for (const slug of soulSlugs) {
+        if (!isValidSlug(slug))
+            continue;
+        const esc = escapeRegex(slug);
+        // Pattern 1: bare string literal (single or double quote, exact match).
+        const literalRe = new RegExp(`(['"])${esc}\\1`);
+        // Pattern 2: soul-discriminating conditional. Permissive on the soul
+        // identifier name so it catches `soul`, `soulId`, `soul_id`, etc.
+        const condRe = new RegExp(`(?:soul[A-Za-z_]*)\\s*===\\s*(['"])${esc}\\1`);
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            const condMatch = line.match(condRe);
+            if (condMatch) {
+                findings.push({
+                    filePath: file.path,
+                    soulSlug: slug,
+                    line: i + 1,
+                    pattern: 'soul-conditional',
+                    excerpt: line.trim().slice(0, 200),
+                });
+                // Don't double-report the same line as a bare literal.
+                continue;
+            }
+            if (literalRe.test(line)) {
+                findings.push({
+                    filePath: file.path,
+                    soulSlug: slug,
+                    line: i + 1,
+                    pattern: 'string-literal',
+                    excerpt: line.trim().slice(0, 200),
+                });
+            }
+        }
+    }
+    return findings;
+}
+/**
+ * Derive a short stable work-item reference from a provenance record's
+ * `promptHash` (16 hex chars is plenty for human-grep utility while still
+ * being unique enough across the audit window). Falls back to the
+ * timestamp when promptHash is empty.
+ */
+function deriveWorkItemRef(record) {
+    if (record.promptHash && record.promptHash.length > 0) {
+        return record.promptHash.slice(0, 16);
+    }
+    return record.timestamp;
+}
+/** Compute the max-min spread of an outcome map. Returns 0 for empty / 1-soul maps. */
+function outcomeSpread(outcomeBySoul) {
+    const values = Object.values(outcomeBySoul).filter((v) => typeof v === 'number');
+    if (values.length < 2)
+        return 0;
+    return Math.max(...values) - Math.min(...values);
+}
+// ── Public API ─────────────────────────────────────────────────────────
+/**
+ * Run Eτ_tessellation_drift detection against the supplied inputs.
+ *
+ * The detector is **read-only** — it does not mutate the tessellation,
+ * the provenance records, or the substrate files. It computes events and
+ * forwards each via the optional `emit` callback (callers wire this to
+ * `appendEvent(artifactsDir, ev)`).
+ *
+ * When `config.enabled !== true` the detector short-circuits immediately
+ * and returns `{ events: [], optedOut: true }`. This honors the RFC-0009
+ * §10 Phase 4 "adopter opt-in initially" convention; the detector exists
+ * in the surface but produces zero side effects until explicitly enabled.
+ *
+ * @param input  Detection inputs (tessellation + optional substrate + provenance).
+ * @param config Detector configuration (master `enabled` flag + per-rule toggles).
+ * @param emit   Optional event sink; called once per detected event. Errors
+ *               from `emit` are propagated to the caller (intentional — the
+ *               detector is sync-pure with respect to its inputs; the caller
+ *               decides how to handle event-stream failures).
+ */
+export async function detectTessellationDrift(input, config = {}, emit) {
+    // ── Master opt-out short-circuit ────────────────────────────────
+    if (config.enabled !== true) {
+        return { events: [], optedOut: true };
+    }
+    const events = [];
+    const now = new Date().toISOString();
+    const soulSlugs = input.tessellation.souls.map((s) => s.soulId).filter(isValidSlug);
+    const soulSlugSet = new Set(soulSlugs);
+    const rules = config.rules ?? {};
+    const runAstScan = rules.astScan !== false;
+    const runCrossSoulProvenance = rules.crossSoulProvenance !== false;
+    const divergenceThreshold = config.divergenceThreshold ?? DEFAULT_DIVERGENCE_THRESHOLD;
+    // ── Rule #1: AST scan for soul-name string literals in substrate ─
+    if (runAstScan && input.substrateFiles && input.substrateFiles.length > 0) {
+        const allFindings = [];
+        for (const file of input.substrateFiles) {
+            const findings = scanSubstrateFile(file, soulSlugs);
+            if (findings.length > 0)
+                allFindings.push(...findings);
+        }
+        if (allFindings.length > 0) {
+            const involved = new Set(allFindings.map((f) => f.soulSlug));
+            const ev = {
+                type: 'TessellationDriftDetected',
+                rule: 'ast-scan',
+                timestamp: now,
+                tessellatedDid: input.tessellatedDid,
+                involvedSouls: [...involved].sort(),
+                severity: 'warning',
+                message: `AST scan: ${allFindings.length} soul-name leakage hit(s) across ${involved.size} soul(s) in shared substrate`,
+                details: { rule: 'ast-scan', findings: allFindings },
+            };
+            events.push(ev);
+        }
+    }
+    // ── Rule #3: Cross-soul provenance audits ────────────────────────
+    if (runCrossSoulProvenance && input.provenance && input.provenance.length > 0) {
+        const findings = [];
+        for (const entry of input.provenance) {
+            const { record, amendmentRecorded, outcomeBySoul } = entry;
+            // Filter targetedSouls down to souls actually present in the
+            // tessellation — out-of-tessellation slugs are stale and not
+            // actionable as drift.
+            const valid = (record.targetedSouls ?? []).filter((s) => soulSlugSet.has(s));
+            // Detection A: provenance crosses tessellation boundary without amendment.
+            if (valid.length >= 2 && amendmentRecorded !== true) {
+                findings.push({
+                    kind: 'cross-boundary-no-amendment',
+                    workItemRef: deriveWorkItemRef(record),
+                    crossedSouls: [...valid].sort(),
+                    note: `work item targeted ${valid.length} souls without a recorded cross-tessellation amendment`,
+                });
+            }
+            // Detection B: substrate-scoped provenance with divergent
+            // soul-distinct outcomes.
+            if (record.substrateScoped === true &&
+                outcomeBySoul &&
+                Object.keys(outcomeBySoul).length >= 2) {
+                const spread = outcomeSpread(outcomeBySoul);
+                if (spread >= divergenceThreshold) {
+                    findings.push({
+                        kind: 'substrate-divergent-outcomes',
+                        workItemRef: deriveWorkItemRef(record),
+                        crossedSouls: Object.keys(outcomeBySoul).sort(),
+                        outcomeBySoul: { ...outcomeBySoul },
+                        note: `substrate provenance shows soul-distinct outcome spread ${spread.toFixed(3)} ≥ threshold ${divergenceThreshold}`,
+                    });
+                }
+            }
+        }
+        if (findings.length > 0) {
+            const involved = new Set(findings.flatMap((f) => f.crossedSouls));
+            const ev = {
+                type: 'TessellationDriftDetected',
+                rule: 'cross-soul-provenance',
+                timestamp: now,
+                tessellatedDid: input.tessellatedDid,
+                involvedSouls: [...involved].sort(),
+                severity: 'warning',
+                message: `Cross-soul provenance: ${findings.length} finding(s) across ${involved.size} soul(s)`,
+                details: { rule: 'cross-soul-provenance', findings },
+            };
+            events.push(ev);
+        }
+    }
+    // ── Emit ────────────────────────────────────────────────────────
+    if (emit) {
+        for (const ev of events) {
+            await emit(ev);
+        }
+    }
+    return { events, optedOut: false };
+}
+//# sourceMappingURL=tessellation-drift.js.map

package/dist/validate-config.js

@@ -41,10 +41,23 @@ export function validateConfigFiles(configDir, fileFilter) {
         try {
             const raw = readFileSync(resolve(dir, file), 'utf-8');
             const doc = parseYaml(raw);
+            // Skip non-resource YAML files (placeholder/commented-out YAMLs, review-exemplars, etc.)
+            // AI-SDLC resources always have apiVersion + kind fields.
+            // Mirrors the identical guard in config.ts:116 — keep both in sync.
+            if (!doc || typeof doc !== 'object' || !('apiVersion' in doc) || !('kind' in doc)) {
+                continue;
+            }
             const result = validateResource(doc);
             const kind = typeof doc === 'object' && doc !== null && 'kind' in doc
                 ? doc.kind
                 : null;
+            if (result.skipped) {
+                // Loader-private or adopter-extension kind — not in the AI-SDLC
+                // schema registry.  Skip silently so adopter pipelines that use
+                // kinds like `MaintainersList` or `SoulTrackMap` don't get
+                // false-positive warnings.  See docs/operations/schema-extensions.md.
+                continue;
+            }
             if (result.valid) {
                 results.push({ file, kind, valid: true, errors: [] });
             }

package/dist/validate-issue.js

@@ -16,7 +16,7 @@ function buildEvaluationContext(issue) {
             ? 1
             : 0
         : 0;
-    const complexityMatch = issue.description?.match(/### Complexity\s*\n+\s*(\d+)/i);
+    const complexityMatch = issue.description?.match(/### Complexity[ \t]*\n+[ \t]*(\d+)/i);
     const complexity = complexityMatch ? Number(complexityMatch[1]) : 0;
     return {
         authorType: 'ai-agent',
@@ -96,7 +96,7 @@ export async function validateIssueWithExtensions(issue, qualityGate, options) {
 export function parseComplexity(issueBody) {
     if (!issueBody)
         return 0;
-    const match = issueBody.match(/### Complexity\s*\n+\s*(\d+)/i);
+    const match = issueBody.match(/### Complexity[ \t]*\n+[ \t]*(\d+)/i);
     return match ? Number(match[1]) : 0;
 }
 //# sourceMappingURL=validate-issue.js.map

package/dist/variant/cardinality-activation.d.ts

@@ -0,0 +1,126 @@
+/**
+ * RFC-0017 Phase 5 — OQ-8 cardinality activation Decision wiring (AISDLC-438).
+ *
+ * Per OQ-8 resolution (2026-05-18):
+ *
+ *   "Future Decision in catalog; auto-promote on ≥2 adopter requests. Author's
+ *    threshold expressed through the Decision Catalog substrate. Each adopter
+ *    request → `Decision: variant-cardinality-activation-request` → Stage A
+ *    counter; at threshold, Decision auto-promotes to operator batch review with
+ *    'file follow-on RFC' recommendation."
+ *
+ * This module implements:
+ *
+ *   1. **Stage A counter** — tracks distinct adopter cardinality activation
+ *      requests. Each request emits `variant-cardinality-activation-request` to
+ *      the Decision Catalog substrate. Requests from the same adopter are
+ *      deduplicated (one signal per distinct adopter, per OQ-8 intent).
+ *
+ *   2. **Auto-promote at threshold** — when `distinctAdopterCount >= threshold`
+ *      (default 2), the result is marked `promotedToOperatorReview: true` with
+ *      a recommendation to file a follow-on RFC for cardinality activation.
+ *      This mirrors the RFC-0036 OQ-6 first-party-adapter graduation pattern.
+ *
+ *   3. **Operator runbook pointer** — the recommendation string references the
+ *      canonical runbook path for the "file follow-on RFC" path.
+ *
+ * All events route through RFC-0035 G0 (non-blocking pipeline contract).
+ * The cardinality `field` itself (`primary | secondary | experimental`) is
+ * RESERVED in the schema and ignored at runtime in v1.
+ *
+ * @see spec/rfcs/RFC-0017-in-soul-variant-pattern.md OQ-8 + §5.2
+ * @see spec/rfcs/RFC-0035-decision-catalog-operator-routing.md G0 §6.2
+ * @see docs/operations/variant-pattern-promotion.md — cardinality activation section
+ */
+/**
+ * Minimum number of distinct adopter requests before the cardinality
+ * activation Decision auto-promotes to operator batch review (OQ-8 threshold).
+ *
+ * Mirrors RFC-0036 OQ-6 first-party-adapter graduation threshold pattern.
+ * Two distinct adopters requesting the same capability is sufficient signal
+ * to bring the topic to operator attention for follow-on RFC consideration.
+ */
+export declare const DEFAULT_CARDINALITY_ACTIVATION_THRESHOLD = 2;
+/**
+ * A single adopter's request to activate the `cardinality` field
+ * (`primary | secondary | experimental`) on Soul Variants.
+ *
+ * Each request is a signal from an InternalAdopter or external operator that
+ * their use case requires lifecycle distinctions beyond the flat v1 schema.
+ */
+export interface CardinalityActivationRequest {
+    /** Adopter identifier (e.g. org slug, adopter name). Used for deduplication. */
+    requestedBy: string;
+    /** Soul the request pertains to (for context; not used in deduplication). */
+    soulId: string;
+    /** Variant the request pertains to (for context). */
+    variantId: string;
+    /**
+     * Free-text rationale for why cardinality activation would help this adopter.
+     * This text surfaces in the operator batch review when promoted.
+     */
+    rationale: string;
+    /** ISO 8601 timestamp of when the request was submitted. */
+    requestedAt: string;
+}
+/**
+ * Result of processing a batch of cardinality activation requests.
+ * Returned by `trackCardinalityActivationRequest()`.
+ */
+export interface CardinalityActivationResult {
+    /** Decision kind emitted to the catalog per OQ-8 resolution. */
+    decisionKind: 'variant-cardinality-activation-request';
+    /** Total number of raw requests processed (may include duplicates). */
+    totalRequests: number;
+    /** Number of distinct adopters (deduplicated by `requestedBy`). */
+    distinctAdopterCount: number;
+    /** The distinct adopter IDs contributing to this batch. */
+    distinctAdopters: string[];
+    /**
+     * Whether the threshold has been crossed and the Decision has been
+     * auto-promoted to operator batch review.
+     */
+    promotedToOperatorReview: boolean;
+    /**
+     * Human-readable recommendation surfaced in the operator batch review
+     * when `promotedToOperatorReview === true`. Undefined when below threshold.
+     */
+    recommendation?: string;
+    /**
+     * The activation threshold that was applied (default 2, per-org configurable).
+     */
+    threshold: number;
+    /**
+     * RFC-0035 G0: routing is non-blocking — the pipeline continues regardless
+     * of how many requests have been received. The operator batch review is
+     * informational, not a gate.
+     */
+    routing: {
+        blocking: false;
+        routingKind: 'decision-catalog-auto-promote';
+    };
+}
+/**
+ * Track a batch of cardinality activation requests and emit Stage A counter
+ * state per OQ-8 resolution.
+ *
+ * Deduplicates by `requestedBy` — multiple requests from the same adopter
+ * count as one distinct signal (preventing a single eager adopter from
+ * triggering the promotion threshold alone).
+ *
+ * When `distinctAdopterCount >= threshold`, marks `promotedToOperatorReview: true`
+ * and populates `recommendation` with the "file follow-on RFC" runbook pointer.
+ *
+ * @param requests  - One or more adopter cardinality activation requests.
+ * @param threshold - Override for the activation threshold (default: 2).
+ */
+export declare function trackCardinalityActivationRequest(requests: CardinalityActivationRequest[], threshold?: number): CardinalityActivationResult;
+/**
+ * Convenience predicate: returns true when the cardinality activation result
+ * should be surfaced to the operator in the next batch review cycle.
+ *
+ * This is a thin wrapper over `result.promotedToOperatorReview` for
+ * callers that need a typed boolean predicate.
+ */
+export declare function shouldPromoteToOperatorReview(result: CardinalityActivationResult): boolean;
+//# sourceMappingURL=cardinality-activation.d.ts.map

package/dist/variant/cardinality-activation.js

@@ -0,0 +1,101 @@
+/**
+ * RFC-0017 Phase 5 — OQ-8 cardinality activation Decision wiring (AISDLC-438).
+ *
+ * Per OQ-8 resolution (2026-05-18):
+ *
+ *   "Future Decision in catalog; auto-promote on ≥2 adopter requests. Author's
+ *    threshold expressed through the Decision Catalog substrate. Each adopter
+ *    request → `Decision: variant-cardinality-activation-request` → Stage A
+ *    counter; at threshold, Decision auto-promotes to operator batch review with
+ *    'file follow-on RFC' recommendation."
+ *
+ * This module implements:
+ *
+ *   1. **Stage A counter** — tracks distinct adopter cardinality activation
+ *      requests. Each request emits `variant-cardinality-activation-request` to
+ *      the Decision Catalog substrate. Requests from the same adopter are
+ *      deduplicated (one signal per distinct adopter, per OQ-8 intent).
+ *
+ *   2. **Auto-promote at threshold** — when `distinctAdopterCount >= threshold`
+ *      (default 2), the result is marked `promotedToOperatorReview: true` with
+ *      a recommendation to file a follow-on RFC for cardinality activation.
+ *      This mirrors the RFC-0036 OQ-6 first-party-adapter graduation pattern.
+ *
+ *   3. **Operator runbook pointer** — the recommendation string references the
+ *      canonical runbook path for the "file follow-on RFC" path.
+ *
+ * All events route through RFC-0035 G0 (non-blocking pipeline contract).
+ * The cardinality `field` itself (`primary | secondary | experimental`) is
+ * RESERVED in the schema and ignored at runtime in v1.
+ *
+ * @see spec/rfcs/RFC-0017-in-soul-variant-pattern.md OQ-8 + §5.2
+ * @see spec/rfcs/RFC-0035-decision-catalog-operator-routing.md G0 §6.2
+ * @see docs/operations/variant-pattern-promotion.md — cardinality activation section
+ */
+// ── Constants ─────────────────────────────────────────────────────────────────
+/**
+ * Minimum number of distinct adopter requests before the cardinality
+ * activation Decision auto-promotes to operator batch review (OQ-8 threshold).
+ *
+ * Mirrors RFC-0036 OQ-6 first-party-adapter graduation threshold pattern.
+ * Two distinct adopters requesting the same capability is sufficient signal
+ * to bring the topic to operator attention for follow-on RFC consideration.
+ */
+export const DEFAULT_CARDINALITY_ACTIVATION_THRESHOLD = 2;
+// ── Main function ─────────────────────────────────────────────────────────────
+/**
+ * Track a batch of cardinality activation requests and emit Stage A counter
+ * state per OQ-8 resolution.
+ *
+ * Deduplicates by `requestedBy` — multiple requests from the same adopter
+ * count as one distinct signal (preventing a single eager adopter from
+ * triggering the promotion threshold alone).
+ *
+ * When `distinctAdopterCount >= threshold`, marks `promotedToOperatorReview: true`
+ * and populates `recommendation` with the "file follow-on RFC" runbook pointer.
+ *
+ * @param requests  - One or more adopter cardinality activation requests.
+ * @param threshold - Override for the activation threshold (default: 2).
+ */
+export function trackCardinalityActivationRequest(requests, threshold = DEFAULT_CARDINALITY_ACTIVATION_THRESHOLD) {
+    const seenAdopters = new Set();
+    for (const req of requests) {
+        seenAdopters.add(req.requestedBy);
+    }
+    const distinctAdopterCount = seenAdopters.size;
+    const distinctAdopters = [...seenAdopters].sort();
+    const promotedToOperatorReview = distinctAdopterCount >= threshold;
+    const recommendation = promotedToOperatorReview
+        ? [
+            `Cardinality activation threshold reached (${distinctAdopterCount}/${threshold} distinct adopters).`,
+            `Operator action: file a follow-on RFC to activate 'cardinality: primary | secondary | experimental'`,
+            `on Soul Variants. See docs/operations/variant-pattern-promotion.md §Cardinality Activation`,
+            `for the "file follow-on RFC" runbook path.`,
+            `Requesting adopters: ${distinctAdopters.join(', ')}.`,
+        ].join(' ')
+        : undefined;
+    return {
+        decisionKind: 'variant-cardinality-activation-request',
+        totalRequests: requests.length,
+        distinctAdopterCount,
+        distinctAdopters,
+        promotedToOperatorReview,
+        recommendation,
+        threshold,
+        routing: {
+            blocking: false,
+            routingKind: 'decision-catalog-auto-promote',
+        },
+    };
+}
+/**
+ * Convenience predicate: returns true when the cardinality activation result
+ * should be surfaced to the operator in the next batch review cycle.
+ *
+ * This is a thin wrapper over `result.promotedToOperatorReview` for
+ * callers that need a typed boolean predicate.
+ */
+export function shouldPromoteToOperatorReview(result) {
+    return result.promotedToOperatorReview;
+}
+//# sourceMappingURL=cardinality-activation.js.map