@sanity/ailf 0.1.0

package/dist/pipeline/readiness-report.js

@@ -0,0 +1,205 @@
+/**
+ * pipeline/readiness-report.ts
+ *
+ * Pure computation module for launch readiness reports.
+ *
+ * Combines threshold evaluation, ceiling decomposition, and gap analysis
+ * into a single actionable readiness checklist for a given feature area.
+ *
+ * This module has NO side effects — no file I/O, no process.argv, no env vars.
+ * Callers (command handlers, orchestration steps) handle I/O and pass data in.
+ *
+ * Exports pure functions:
+ *   - generateReadinessReport()  — builds the structured report
+ *   - formatReadinessMarkdown()  — renders the report as markdown
+ *
+ * @see docs/exec-plans/completed/scenario-matrix-implementation/phase-5-readiness-thresholds.md
+ * @see docs/exec-plans/active/eliminate-lib-layer.md
+ */
+import { evaluateThresholds } from "./thresholds.js";
+// ---------------------------------------------------------------------------
+// Pure functions (exported for testing)
+// ---------------------------------------------------------------------------
+/**
+ * Format a readiness report as markdown.
+ *
+ * Pure function — takes a structured report and returns a markdown string.
+ */
+export function formatReadinessMarkdown(report) {
+    const lines = [];
+    const areaLabel = formatAreaLabel(report.area);
+    // Header
+    const statusEmoji = report.pass ? "✅" : "❌";
+    const statusLabel = report.pass ? "READY" : "NOT READY";
+    lines.push(`## 🚀 Launch Readiness: ${areaLabel}`);
+    lines.push("");
+    lines.push(`**Overall:** ${statusEmoji} ${statusLabel} (${fmt(report.score)}/100, threshold: ${report.threshold})`);
+    lines.push("");
+    // Dimension Checklist
+    lines.push("### Dimension Checklist");
+    lines.push("");
+    lines.push("| Dimension | Score | Threshold | Status |");
+    lines.push("|---|---|---|---|");
+    for (const dim of report.dimensions) {
+        const status = dim.pass ? "✅ Meets threshold" : "❌ Below threshold";
+        lines.push(`| ${dim.dimension} | ${fmt(dim.score)} | ${fmt(dim.threshold)} | ${status} |`);
+    }
+    lines.push("");
+    // Ceiling Analysis
+    lines.push("### Ceiling Analysis");
+    lines.push("");
+    lines.push("| Metric | Value | Assessment |");
+    lines.push("|---|---|---|");
+    const ceilingAssessment = report.ceiling.ceilingScore >= 60
+        ? "✅ Docs enable reasonable performance"
+        : "⚠️ Below 60 — docs need improvement";
+    lines.push(`| Ceiling Score | ${fmt(report.ceiling.ceilingScore)} | ${ceilingAssessment} |`);
+    const floorAssessment = report.ceiling.floorScore >= 30
+        ? "Model has moderate baseline knowledge"
+        : "Model has limited baseline knowledge";
+    lines.push(`| Floor Score | ${fmt(report.ceiling.floorScore)} | ${floorAssessment} |`);
+    const liftSign = report.ceiling.docLift >= 0 ? "+" : "";
+    const liftAssessment = report.ceiling.docLift < 0
+        ? "❌ Docs are hurting performance"
+        : report.ceiling.docLift >= 10
+            ? "✅ Docs add significant value"
+            : "⚠️ Docs add minimal value";
+    lines.push(`| Doc Lift | ${liftSign}${fmt(report.ceiling.docLift)} | ${liftAssessment} |`);
+    lines.push(`| Doc Quality Gap | ${fmt(report.ceiling.docQualityGap)} | ${report.ceiling.docQualityGap > 30 ? "Room for improvement via documentation" : "✅ Docs are high quality"} |`);
+    lines.push("");
+    // Failing Criteria (only shown when there are violations)
+    if (report.violations.length > 0) {
+        lines.push("### Failing Criteria");
+        for (let i = 0; i < report.violations.length; i++) {
+            const v = report.violations[i];
+            lines.push(`${i + 1}. **${v.description}**`);
+        }
+        lines.push("");
+        lines.push("### Recommendation");
+        const count = report.violations.length;
+        const itemWord = count === 1 ? "item" : "items";
+        lines.push(`Fix the ${count} ${itemWord} above and re-evaluate.`);
+        lines.push("");
+    }
+    // Gap Analysis (if available)
+    if (report.gaps.length > 0) {
+        lines.push("### Gap Analysis");
+        lines.push("");
+        lines.push("| Failure Mode | Est. Lift | Confidence | Remediation |");
+        lines.push("|---|---|---|---|");
+        for (const gap of report.gaps) {
+            const confIcon = gap.confidence === "high"
+                ? "🟢"
+                : gap.confidence === "medium"
+                    ? "🟡"
+                    : "🔴";
+            lines.push(`| ${gap.failureMode} | +${gap.estimatedLift.toFixed(1)} | ${confIcon} ${gap.confidence} | ${gap.remediation} |`);
+        }
+        lines.push("");
+    }
+    // Historical Progress (if available)
+    if (report.history.length > 0) {
+        lines.push("### Historical Progress");
+        lines.push("");
+        lines.push("| Date | Score | Tag |");
+        lines.push("|---|---|---|");
+        for (const entry of report.history) {
+            const date = entry.timestamp.slice(0, 10);
+            const tag = entry.tag ?? "—";
+            lines.push(`| ${date} | ${fmt(entry.score)} | ${tag} |`);
+        }
+        // Show current score as the last row
+        lines.push(`| ${new Date().toISOString().slice(0, 10)} | ${fmt(report.score)} | *current* |`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/**
+ * Generate a structured readiness report for a given feature area.
+ *
+ * This is a pure function — it takes all data as parameters and produces
+ * a structured report. No I/O.
+ */
+export function generateReadinessReport(opts) {
+    const { area, gapAnalysis, history = [], scoreSummary, thresholdConfig, } = opts;
+    // Find the area's scores
+    const areaScore = scoreSummary.scores.find((s) => s.feature === area);
+    if (!areaScore) {
+        throw new Error(`Area "${area}" not found in score summary. Available areas: ${scoreSummary.scores.map((s) => s.feature).join(", ")}`);
+    }
+    // Evaluate thresholds for the full summary (to get violations)
+    const thresholdEvaluation = evaluateThresholds(scoreSummary, thresholdConfig);
+    // Filter violations to only this area
+    const areaViolations = thresholdEvaluation.violations.filter((v) => v.area === area);
+    // Resolve per-area thresholds (with defaults)
+    const areaOverrides = thresholdConfig.areas?.[area];
+    const compositeThreshold = areaOverrides?.composite ?? thresholdConfig.defaults.composite;
+    const dimDefaults = thresholdConfig.defaults.dimensions ?? {};
+    const dimOverrides = areaOverrides?.dimensions ?? {};
+    // Build dimension checks
+    const dimensions = [
+        {
+            dimension: "Task Completion",
+            pass: areaScore.taskCompletion >=
+                (dimOverrides["task-completion"] ??
+                    dimDefaults["task-completion"] ??
+                    0),
+            score: areaScore.taskCompletion,
+            threshold: dimOverrides["task-completion"] ?? dimDefaults["task-completion"] ?? 0,
+        },
+        {
+            dimension: "Code Correctness",
+            pass: areaScore.codeCorrectness >=
+                (dimOverrides["code-correctness"] ??
+                    dimDefaults["code-correctness"] ??
+                    0),
+            score: areaScore.codeCorrectness,
+            threshold: dimOverrides["code-correctness"] ??
+                dimDefaults["code-correctness"] ??
+                0,
+        },
+        {
+            dimension: "Doc Coverage",
+            pass: areaScore.docCoverage >=
+                (dimOverrides["doc-coverage"] ?? dimDefaults["doc-coverage"] ?? 0),
+            score: areaScore.docCoverage,
+            threshold: dimOverrides["doc-coverage"] ?? dimDefaults["doc-coverage"] ?? 0,
+        },
+    ];
+    // Filter gap analysis to this area
+    const areaGaps = gapAnalysis?.gaps.filter((g) => g.area === area) ?? [];
+    // Ceiling decomposition
+    const ceiling = {
+        ceilingScore: areaScore.ceilingScore,
+        docLift: areaScore.docLift,
+        docQualityGap: areaScore.docQualityGap,
+        floorScore: areaScore.floorScore,
+    };
+    const pass = areaViolations.length === 0;
+    return {
+        area,
+        ceiling,
+        dimensions,
+        gaps: areaGaps,
+        history,
+        pass,
+        score: areaScore.totalScore,
+        threshold: compositeThreshold,
+        thresholdEvaluation,
+        violations: areaViolations,
+    };
+}
+// ---------------------------------------------------------------------------
+// Formatting helpers (private)
+// ---------------------------------------------------------------------------
+/** Format a score for display (round to nearest integer) */
+function fmt(n) {
+    return String(Math.round(n));
+}
+/** Convert kebab-case area name to title case */
+function formatAreaLabel(area) {
+    return area
+        .split("-")
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(" ");
+}

package/dist/pipeline/release-classification.d.ts

@@ -0,0 +1,54 @@
+/**
+ * pipeline/release-classification.ts
+ *
+ * Classifies documents in a content release for evaluation tier assignment.
+ *
+ * Phase 4a of the Scenario Matrix implementation.
+ *
+ * Given a ReleaseImpact (added/modified/removed/unchanged) and the task
+ * mappings, this module classifies each document as:
+ *
+ * - **Tier A**: New document in an area that has existing evaluation tasks.
+ *   The document can be injected into existing task contexts and evaluated.
+ * - **Tier B**: New document in an area with no evaluation tasks.
+ *   Only a directional probe is possible (no scored evaluation).
+ * - **not-applicable**: Updated, removed, or unchanged documents (these
+ *   follow the standard before/after comparison flow from Phase 2).
+ *
+ * @see docs/exec-plans/completed/scenario-matrix-implementation/phase-4-content-release-integration.md
+ */
+import type { ClassifiedReleaseDocument, ProductFeature, ReleaseClassification } from "./types.js";
+import type { ReverseMapping } from "./reverse-mapping.js";
+/**
+ * Classify all documents in a content release for evaluation.
+ *
+ * @param releaseImpact - Added/modified/removed/unchanged slugs from the release
+ * @param reverseMapping - Slug → affected area/task mapping
+ * @param featureAreas - Set of area names that have task files
+ * @param features - Product feature registry (optional, for section-based area inference)
+ * @returns Release classification with per-document tier assignment
+ */
+export declare function classifyRelease(releaseImpact: {
+    added: string[];
+    modified: string[];
+    removed: string[];
+    unchanged?: string[];
+}, reverseMapping: ReverseMapping, featureAreas: Set<string>, features?: ProductFeature[]): ReleaseClassification;
+/**
+ * Format a release classification for console output.
+ */
+export declare function formatReleaseClassificationConsole(classification: ReleaseClassification): string;
+/**
+ * Format a release classification as markdown for PR comments.
+ */
+export declare function formatReleaseClassificationMarkdown(classification: ReleaseClassification): string;
+/**
+ * Extract Tier A documents — new documents that can be injected into
+ * existing task contexts for evaluation.
+ */
+export declare function getTierADocuments(classification: ReleaseClassification): ClassifiedReleaseDocument[];
+/**
+ * Extract Tier B documents — new documents in areas without tasks,
+ * suitable for directional probes only.
+ */
+export declare function getTierBDocuments(classification: ReleaseClassification): ClassifiedReleaseDocument[];

package/dist/pipeline/release-classification.js

@@ -0,0 +1,238 @@
+/**
+ * pipeline/release-classification.ts
+ *
+ * Classifies documents in a content release for evaluation tier assignment.
+ *
+ * Phase 4a of the Scenario Matrix implementation.
+ *
+ * Given a ReleaseImpact (added/modified/removed/unchanged) and the task
+ * mappings, this module classifies each document as:
+ *
+ * - **Tier A**: New document in an area that has existing evaluation tasks.
+ *   The document can be injected into existing task contexts and evaluated.
+ * - **Tier B**: New document in an area with no evaluation tasks.
+ *   Only a directional probe is possible (no scored evaluation).
+ * - **not-applicable**: Updated, removed, or unchanged documents (these
+ *   follow the standard before/after comparison flow from Phase 2).
+ *
+ * @see docs/exec-plans/completed/scenario-matrix-implementation/phase-4-content-release-integration.md
+ */
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Classify all documents in a content release for evaluation.
+ *
+ * @param releaseImpact - Added/modified/removed/unchanged slugs from the release
+ * @param reverseMapping - Slug → affected area/task mapping
+ * @param featureAreas - Set of area names that have task files
+ * @param features - Product feature registry (optional, for section-based area inference)
+ * @returns Release classification with per-document tier assignment
+ */
+export function classifyRelease(releaseImpact, reverseMapping, featureAreas, features) {
+    const documents = [];
+    // Build a section → area lookup from features registry
+    const sectionToAreas = buildSectionMapping(features);
+    // Classify added documents (new in the release)
+    for (const slug of releaseImpact.added) {
+        const doc = classifyDocument(slug, "new", reverseMapping, featureAreas, sectionToAreas);
+        documents.push(doc);
+    }
+    // Classify modified documents (updated in the release)
+    for (const slug of releaseImpact.modified) {
+        const doc = classifyDocument(slug, "updated", reverseMapping, featureAreas, sectionToAreas);
+        documents.push(doc);
+    }
+    // Classify removed documents
+    for (const slug of releaseImpact.removed) {
+        const doc = classifyDocument(slug, "removed", reverseMapping, featureAreas, sectionToAreas);
+        documents.push(doc);
+    }
+    // Compute summary
+    const tierA = documents.filter((d) => d.tier === "A").length;
+    const tierB = documents.filter((d) => d.tier === "B").length;
+    const tracked = documents.filter((d) => d.tracked).length;
+    const updated = documents.filter((d) => d.changeType === "updated").length;
+    const untracked = documents.filter((d) => !d.tracked).length;
+    return {
+        documents,
+        generatedAt: new Date().toISOString(),
+        summary: {
+            tierA,
+            tierB,
+            total: documents.length,
+            tracked,
+            untracked,
+            updated,
+        },
+    };
+}
+/**
+ * Format a release classification for console output.
+ */
+export function formatReleaseClassificationConsole(classification) {
+    const lines = [];
+    const { summary } = classification;
+    lines.push("📦 RELEASE DOCUMENT CLASSIFICATION");
+    lines.push("");
+    lines.push(`  ${summary.total} documents: ${summary.tracked} tracked, ${summary.untracked} untracked`);
+    if (summary.tierA > 0 || summary.tierB > 0) {
+        lines.push(`  New documents: ${summary.tierA} Tier A (evaluable), ${summary.tierB} Tier B (probe only)`);
+    }
+    lines.push("");
+    // Group by change type
+    const byType = groupByChangeType(classification.documents);
+    if (byType.new.length > 0) {
+        lines.push("  NEW DOCUMENTS:");
+        for (const doc of byType.new) {
+            const tierLabel = doc.tier === "A" ? "Tier A" : "Tier B";
+            const areas = doc.affectedAreas.length > 0
+                ? doc.affectedAreas.join(", ")
+                : "(no matching area)";
+            lines.push(`    ${tierIcon(doc.tier)} ${doc.slug} → ${tierLabel} [${areas}]`);
+        }
+        lines.push("");
+    }
+    if (byType.updated.length > 0) {
+        lines.push("  UPDATED DOCUMENTS:");
+        for (const doc of byType.updated) {
+            const tracked = doc.tracked ? "tracked" : "untracked";
+            const areas = doc.affectedAreas.length > 0
+                ? doc.affectedAreas.join(", ")
+                : "(no tasks)";
+            lines.push(`    📝 ${doc.slug} → ${tracked} [${areas}]`);
+        }
+        lines.push("");
+    }
+    if (byType.removed.length > 0) {
+        lines.push("  REMOVED DOCUMENTS:");
+        for (const doc of byType.removed) {
+            lines.push(`    🗑️  ${doc.slug}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/**
+ * Format a release classification as markdown for PR comments.
+ */
+export function formatReleaseClassificationMarkdown(classification) {
+    const lines = [];
+    const { summary } = classification;
+    lines.push("### 📦 Release Document Classification");
+    lines.push("");
+    lines.push(`**${summary.total} documents**: ${summary.tracked} tracked, ${summary.untracked} untracked`);
+    lines.push("");
+    if (classification.documents.length > 0) {
+        lines.push("| Document | Change | Tier | Areas |");
+        lines.push("|----------|--------|------|-------|");
+        for (const doc of classification.documents) {
+            const tierLabel = doc.tier === "A" ? "🟢 A" : doc.tier === "B" ? "🟡 B" : "—";
+            const areas = doc.affectedAreas.length > 0 ? doc.affectedAreas.join(", ") : "—";
+            lines.push(`| \`${doc.slug}\` | ${doc.changeType} | ${tierLabel} | ${areas} |`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+/**
+ * Extract Tier A documents — new documents that can be injected into
+ * existing task contexts for evaluation.
+ */
+export function getTierADocuments(classification) {
+    return classification.documents.filter((d) => d.tier === "A");
+}
+/**
+ * Extract Tier B documents — new documents in areas without tasks,
+ * suitable for directional probes only.
+ */
+export function getTierBDocuments(classification) {
+    return classification.documents.filter((d) => d.tier === "B");
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/** Build a section → area names lookup from the feature registry */
+function buildSectionMapping(features) {
+    const mapping = new Map();
+    if (!features)
+        return mapping;
+    for (const feature of features) {
+        if (feature.status !== "covered" || !feature.area)
+            continue;
+        for (const section of feature.sections) {
+            const existing = mapping.get(section) ?? [];
+            if (!existing.includes(feature.area)) {
+                existing.push(feature.area);
+            }
+            mapping.set(section, existing);
+        }
+    }
+    return mapping;
+}
+/** Classify a single document */
+function classifyDocument(slug, changeType, reverseMapping, featureAreas, _sectionToAreas) {
+    const targets = reverseMapping.get(slug) ?? [];
+    const affectedAreas = [...new Set(targets.map((t) => t.area))].sort();
+    const tracked = targets.length > 0;
+    // Determine tier for new documents
+    let tier = "not-applicable";
+    if (changeType === "new") {
+        if (affectedAreas.length > 0) {
+            // New doc matches existing tasks → Tier A
+            tier = "A";
+        }
+        else {
+            // Check if any feature area exists for this document
+            // Try to infer area from slug prefix
+            const inferredArea = inferAreaFromSlug(slug, featureAreas);
+            if (inferredArea) {
+                tier = "A";
+                affectedAreas.push(inferredArea);
+            }
+            else {
+                tier = "B";
+            }
+        }
+    }
+    return {
+        affectedAreas,
+        changeType,
+        slug,
+        tier,
+        tracked,
+    };
+}
+/** Group documents by change type */
+function groupByChangeType(docs) {
+    return {
+        new: docs.filter((d) => d.changeType === "new"),
+        removed: docs.filter((d) => d.changeType === "removed"),
+        updated: docs.filter((d) => d.changeType === "updated"),
+    };
+}
+/** Try to infer a feature area from a document slug prefix */
+function inferAreaFromSlug(slug, featureAreas) {
+    // Try progressively shorter prefixes of the slug
+    const parts = slug.split("-");
+    for (let i = parts.length; i >= 1; i--) {
+        const candidate = parts.slice(0, i).join("-");
+        if (featureAreas.has(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/** Get icon for a tier */
+function tierIcon(tier) {
+    switch (tier) {
+        case "A":
+            return "🟢";
+        case "B":
+            return "🟡";
+        case "not-applicable":
+            return "⚪";
+    }
+}

package/dist/pipeline/release-report.d.ts

@@ -0,0 +1,37 @@
+/**
+ * pipeline/release-report.ts
+ *
+ * Cross-area release impact reports.
+ *
+ * Phase 4c of the Scenario Matrix implementation.
+ *
+ * Consolidates impact data from multi-area content releases into a single
+ * report that combines document classification (4a), before/after deltas (2b),
+ * attribution (2c), and probe results (4b) into the document × area × task
+ * impact matrix specified by Scenario 2.4.
+ *
+ * @see docs/exec-plans/completed/scenario-matrix-implementation/phase-4-content-release-integration.md
+ */
+import type { AttributionReport, ComparisonReport, ProbeResult, ReleaseClassification, ReleaseImpactReport } from "./types.js";
+/**
+ * Build a cross-area release impact report.
+ *
+ * Combines classification, comparison, attribution, and probe data into
+ * a single consolidated report.
+ *
+ * @param classification - Document classification from Phase 4a
+ * @param comparison - Before/after comparison (if available)
+ * @param attribution - Per-document attribution (if available)
+ * @param probes - Tier B probe results (if any)
+ * @param noiseThreshold - Threshold for "unchanged" classification
+ * @returns Consolidated release impact report
+ */
+export declare function buildReleaseImpactReport(classification: ReleaseClassification, comparison?: ComparisonReport, attribution?: AttributionReport, probes?: ProbeResult[], noiseThreshold?: number): ReleaseImpactReport;
+/**
+ * Format a release impact report for console output.
+ */
+export declare function formatReleaseImpactConsole(report: ReleaseImpactReport): string;
+/**
+ * Format a release impact report as markdown.
+ */
+export declare function formatReleaseImpactMarkdown(report: ReleaseImpactReport): string;