@multileaf/ai-workflow 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to this project are documented in this file. The format foll
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-10-20
+
+### Added
+
+- Standing-context benchmark: `aiw context-bench` measures the persistent context AI Workflow renders into every agent session (root context file, neutral resources under `.aiw/resources/`, `.aiw/context/` layers) per category, offline and deterministically. Byte and file counts are measured; tokens are estimated (characters/4) and labeled as such; a content hash pins the fixture and the report contains no timestamps. `--save` records a checkpoint under `.aiw/checkpoints/` and `--baseline=<path>` exits nonzero on any token regression, giving context changes a cost gate.
+- Task parity suite: `aiw parity [--tasks=directory]` runs YAML parity tasks (`.aiw/parity/` by default) that pin quality constraints on context assembly. Each task compares the full composed context against the just-in-time task-retrieval assembler and fails, naming the exact fact, when a critical fact or completion marker does not survive retrieval. Exit nonzero on any failure makes it a CI gate for context changes; estimated token cost is reported but never gates here. Inter-stage tasks load real artifacts via `sources` (project-relative paths into any layer) and enforce `required_patterns` — every extracted identifier (e.g. `REQ-\d+` from the approved specification) must survive assembly, guarding the identifiers traceability links depend on.
+- Usage sidecar: `aiw usage-sidecar record/report` maintains a versioned ledger at `.aiw/checkpoints/usage-sidecar.yml` with per-run tokens split into billing tiers (cache-read, fresh-input, cache-write, output), a `measured`/`estimated` label that propagates pessimistically to aggregates, and attribution by model and harness (with version). The report exposes `cache_hit_rate` (cache-read over billable input); dollar conversion is intentionally left out. `aiw scan` auto-records interpreter and embedding usage into the ledger with their real measurement label.
+- Cost attribution: `aiw cost-report` joins the usage sidecar with the traceability graph (`aiw trace`) to report tokens per verified requirement — the outcome-denominated cost metric — with attributed and unattributed tokens shown side by side. Sidecar entries accept `--requirement=REQ-###`, and `parseTraceabilityGraph` round-trips the serialized graph.
+- Model routing table: `aiw routing init|show|resolve --category=name` maintains a static, evidence-linked table at `.aiw/routing.yml`. Rules map task categories to models deterministically; each rule names its evidence, and the resolver reports its advisory level (`evidenced`, `unevidenced-rule`, `default-fallback`, `default-unset`). Routing is advisory only and never invokes a model.
+- Task-lifecycle token usage: `aiw task-usage [--workflow=id-or-ticket]` aggregates sidecar entries correlated by `--workflow` into one task's totals — input tokens (all billing tiers), output tokens, cache hit rate, per-stage breakdown with models, requirements touched, and harness attribution. Tokens are the model-invariant metric, so lifecycle totals stay comparable across model routing changes; `usage-sidecar record` accepts `--workflow` for correlation.
+
 ## [0.7.0] - 2026-10-13
 
 ### Added

package/dist/context-benchmark.d.ts

@@ -0,0 +1,52 @@
+import type { FileSystem } from "./types.js";
+/**
+ * Standing-context benchmark (deterministic, offline, zero API cost).
+ *
+ * Measures the persistent context AI Workflow renders into every agent
+ * session: the root context file for the active target, neutral resources
+ * under `.aiw/resources/`, and composed context layers under `.aiw/context/`.
+ *
+ * Honest-measurement rules (see docs/token-efficiency-study-notes.md):
+ * - byte and file counts are `measured`; token counts are `estimated`
+ *   (characters/4) and always labeled as such;
+ * - the bundle hash pins the exact fixture content behind every number;
+ * - output contains no timestamps or randomness, so reruns are
+ *   byte-identical for unchanged projects.
+ */
+export declare const CONTEXT_BENCH_SCHEMA = 1;
+export declare const ROOT_CONTEXT_FILES: readonly ["AGENTS.md", "CLAUDE.md", "GEMINI.md"];
+export declare const RESOURCE_CATEGORIES: readonly ["skills", "rules", "agents", "hooks", "templates"];
+export type ResourceCategory = (typeof RESOURCE_CATEGORIES)[number];
+export type ContextBenchCategory = ResourceCategory | "root-context" | "context-layers" | "other-resources";
+export declare const CONTEXT_BENCH_CATEGORIES: readonly ContextBenchCategory[];
+export type ContextBenchCategoryMetrics = {
+    name: ContextBenchCategory;
+    files: number;
+    characters: number;
+    estimatedTokens: number;
+    paths: string[];
+};
+export type ContextBenchReport = {
+    schema: number;
+    bundleHash: string;
+    totalCharacters: number;
+    totalEstimatedTokens: number;
+    categories: ContextBenchCategoryMetrics[];
+};
+/** Estimate tokens from characters. Always labeled `estimated`, never `measured`. */
+export declare function estimateTokens(text: string): number;
+/** Collect the standing-context report for a project. Deterministic: same files, same bytes, same report. */
+export declare function collectContextBench(root: string, fs: FileSystem): ContextBenchReport;
+export declare function serializeContextBench(report: ContextBenchReport): string;
+/** Parse a previously saved report for baseline comparison. */
+export declare function parseContextBench(content: string): ContextBenchReport;
+export type ContextBenchComparison = {
+    bundleChanged: boolean;
+    totalTokenDelta: number;
+    regressions: string[];
+};
+/**
+ * Compare a current report against a saved baseline.
+ * Follows the parity-harness rule: any token increase is a regression.
+ */
+export declare function compareContextBench(baseline: ContextBenchReport, current: ContextBenchReport): ContextBenchComparison;

package/dist/context-benchmark.js

@@ -0,0 +1,170 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+/**
+ * Standing-context benchmark (deterministic, offline, zero API cost).
+ *
+ * Measures the persistent context AI Workflow renders into every agent
+ * session: the root context file for the active target, neutral resources
+ * under `.aiw/resources/`, and composed context layers under `.aiw/context/`.
+ *
+ * Honest-measurement rules (see docs/token-efficiency-study-notes.md):
+ * - byte and file counts are `measured`; token counts are `estimated`
+ *   (characters/4) and always labeled as such;
+ * - the bundle hash pins the exact fixture content behind every number;
+ * - output contains no timestamps or randomness, so reruns are
+ *   byte-identical for unchanged projects.
+ */
+export const CONTEXT_BENCH_SCHEMA = 1;
+export const ROOT_CONTEXT_FILES = ["AGENTS.md", "CLAUDE.md", "GEMINI.md"];
+export const RESOURCE_CATEGORIES = ["skills", "rules", "agents", "hooks", "templates"];
+export const CONTEXT_BENCH_CATEGORIES = [
+    "root-context",
+    ...RESOURCE_CATEGORIES,
+    "context-layers",
+    "other-resources",
+];
+/** Estimate tokens from characters. Always labeled `estimated`, never `measured`. */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+function hashBundle(entries) {
+    const hash = createHash("sha256");
+    for (const entry of entries.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)))
+        hash.update(`${entry.path}\0${Buffer.byteLength(entry.content, "utf8")}\0`);
+    return hash.digest("hex").slice(0, 16);
+}
+function emptyCategory(name) {
+    return { name, files: 0, characters: 0, estimatedTokens: 0, paths: [] };
+}
+function addFile(categories, name, path, content) {
+    const category = categories.get(name) ?? emptyCategory(name);
+    category.files += 1;
+    category.characters += content.length;
+    category.estimatedTokens += estimateTokens(content);
+    category.paths.push(path);
+    categories.set(name, category);
+}
+/** Collect the standing-context report for a project. Deterministic: same files, same bytes, same report. */
+export function collectContextBench(root, fs) {
+    const categories = new Map();
+    const bundle = [];
+    const record = (name, path, content) => {
+        addFile(categories, name, path, content);
+        bundle.push({ path, content });
+    };
+    for (const file of ROOT_CONTEXT_FILES) {
+        const path = join(root, file);
+        if (fs.pathType?.(path) === "file")
+            record("root-context", file, fs.read(path));
+    }
+    const resourceRoot = join(root, ".aiw/resources");
+    if (fs.pathType?.(resourceRoot) === "directory" && fs.listFiles) {
+        for (const relative of fs.listFiles(resourceRoot)) {
+            const absolute = join(resourceRoot, relative);
+            if (fs.pathType?.(absolute) !== "file")
+                continue;
+            const top = relative.split(/[\\/]/)[0];
+            const name = RESOURCE_CATEGORIES.includes(top)
+                ? top
+                : "other-resources";
+            record(name, `.aiw/resources/${relative.split("\\").join("/")}`, fs.read(absolute));
+        }
+    }
+    const contextRoot = join(root, ".aiw/context");
+    if (fs.pathType?.(contextRoot) === "directory") {
+        for (const file of (fs.list?.(contextRoot) ?? [])
+            .filter((name) => name.endsWith(".md"))
+            .sort()) {
+            const absolute = join(contextRoot, file);
+            if (fs.pathType?.(absolute) !== "file")
+                continue;
+            record("context-layers", `.aiw/context/${file}`, fs.read(absolute));
+        }
+    }
+    const ordered = CONTEXT_BENCH_CATEGORIES.map((name) => categories.get(name) ?? emptyCategory(name));
+    return {
+        schema: CONTEXT_BENCH_SCHEMA,
+        bundleHash: hashBundle(bundle),
+        totalCharacters: ordered.reduce((total, category) => total + category.characters, 0),
+        totalEstimatedTokens: ordered.reduce((total, category) => total + category.estimatedTokens, 0),
+        categories: ordered,
+    };
+}
+export function serializeContextBench(report) {
+    const lines = [
+        `schema: ${report.schema}`,
+        `bundle_hash: ${report.bundleHash}`,
+        `total_characters: ${report.totalCharacters}`,
+        `total_estimated_tokens: ${report.totalEstimatedTokens}`,
+        "token_estimate: characters/4 (estimated; byte counts are measured)",
+        "categories:",
+    ];
+    for (const category of report.categories) {
+        lines.push(`  - name: ${category.name}`, `    files: ${category.files}`, `    characters: ${category.characters}`, `    estimated_tokens: ${category.estimatedTokens}`);
+        if (category.paths.length) {
+            lines.push("    paths:");
+            lines.push(...category.paths.map((path) => `      - ${path}`));
+        }
+    }
+    return lines.join("\n") + "\n";
+}
+/** Parse a previously saved report for baseline comparison. */
+export function parseContextBench(content) {
+    const lines = content.split("\n");
+    if (lines[0]?.trim() !== `schema: ${CONTEXT_BENCH_SCHEMA}`)
+        throw new Error("Unrecognized context benchmark report schema.");
+    const report = {
+        schema: CONTEXT_BENCH_SCHEMA,
+        bundleHash: requiredValue(lines, "bundle_hash"),
+        totalCharacters: Number(requiredValue(lines, "total_characters")),
+        totalEstimatedTokens: Number(requiredValue(lines, "total_estimated_tokens")),
+        categories: [],
+    };
+    let current;
+    for (const line of lines.slice(1)) {
+        const category = line.match(/^ {2}- name: (.+)$/);
+        if (category) {
+            current = emptyCategory(category[1]);
+            report.categories.push(current);
+            continue;
+        }
+        const path = line.match(/^ {6}- (.+)$/);
+        if (path && current)
+            current.paths.push(path[1]);
+        const match = line.match(/^ {4}(files|characters|estimated_tokens): (\d+)$/);
+        if (match && current) {
+            const key = match[1] === "estimated_tokens" ? "estimatedTokens" : match[1];
+            current[key] = Number(match[2]);
+        }
+    }
+    if (!report.categories.length)
+        throw new Error("Context benchmark report has no categories.");
+    return report;
+}
+function requiredValue(lines, key) {
+    const value = lines.find((line) => line.startsWith(`${key}: `))?.slice(key.length + 2);
+    if (!value)
+        throw new Error(`Context benchmark report is missing ${key}.`);
+    return value;
+}
+/**
+ * Compare a current report against a saved baseline.
+ * Follows the parity-harness rule: any token increase is a regression.
+ */
+export function compareContextBench(baseline, current) {
+    const baselineByCategory = new Map(baseline.categories.map((category) => [category.name, category]));
+    const regressions = [];
+    for (const category of current.categories) {
+        const previous = baselineByCategory.get(category.name);
+        if (previous && category.estimatedTokens > previous.estimatedTokens)
+            regressions.push(`${category.name}: ${previous.estimatedTokens} -> ${category.estimatedTokens} estimated tokens`);
+    }
+    const totalTokenDelta = current.totalEstimatedTokens - baseline.totalEstimatedTokens;
+    if (totalTokenDelta > 0)
+        regressions.push(`total: ${baseline.totalEstimatedTokens} -> ${current.totalEstimatedTokens} estimated tokens`);
+    return {
+        bundleChanged: baseline.bundleHash !== current.bundleHash,
+        totalTokenDelta,
+        regressions,
+    };
+}

package/dist/cost-attribution.d.ts

@@ -0,0 +1,65 @@
+import { type UsageLabel, type UsageSidecarEntry } from "./usage-sidecar.js";
+import type { TraceabilityGraph } from "./traceability.js";
+/**
+ * Cost attribution per verified requirement — the outcome-denominated cost
+ * metric (Uber's "cost per merged PR", adapted to AI Workflow's unit of
+ * value: a requirement with verification evidence).
+ *
+ * Honesty rules:
+ * - tokens attributed to requirements and unattributed tokens are reported
+ *   side by side, so the ratio cannot be gamed by leaving expensive work
+ *   unattributed;
+ * - the denominator counts only requirements the traceability graph marks
+ *   as verified (linked evidence present);
+ * - labels propagate pessimistically (any estimated entry poisons the total).
+ */
+export type RequirementCost = {
+    requirement: string;
+    tokens: number;
+    label: UsageLabel;
+    verified: boolean;
+};
+export type CostAttribution = {
+    attributed: RequirementCost[];
+    unattributedTokens: number;
+    unattributedLabel: UsageLabel;
+    verifiedRequirements: number;
+    unverifiedRequirements: number;
+    totalTokens: number;
+    totalLabel: UsageLabel;
+    /** Outcome-denominated metric: attributed tokens per verified requirement. */
+    tokensPerVerifiedRequirement?: number;
+};
+export declare function computeCostAttribution(entries: UsageSidecarEntry[], graph: TraceabilityGraph): CostAttribution;
+export declare function serializeCostAttribution(attribution: CostAttribution): string;
+/**
+ * Task-lifecycle usage: total tokens from task start to merged PR.
+ *
+ * Tokens — not dollars — are the model-invariant metric: switching between a
+ * frontier and an entry-level model changes the price per token but not the
+ * input/output consumption, so lifecycle token totals stay comparable across
+ * model routing changes and harness migrations. All input tiers count as
+ * input tokens processed (cached reads still consume tokens; they just bill
+ * less), and the tier split stays visible for cache-behavior analysis.
+ */
+export type TaskUsageStage = {
+    stage: string;
+    tokens: number;
+    label: UsageLabel;
+    models: string[];
+};
+export type TaskUsageSummary = {
+    workflow: string;
+    entries: number;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    label: UsageLabel;
+    cacheHitRate?: number;
+    stages: TaskUsageStage[];
+    requirements: string[];
+    models: string[];
+    harnesses: string[];
+};
+export declare function summarizeTaskUsage(entries: UsageSidecarEntry[], workflow: string): TaskUsageSummary;
+export declare function serializeTaskUsage(summary: TaskUsageSummary): string;

package/dist/cost-attribution.js

@@ -0,0 +1,119 @@
+import { USAGE_TIERS } from "./usage-sidecar.js";
+const totalTokens = (entry) => USAGE_TIERS.reduce((total, tier) => total + entry.tiers[tier], 0);
+export function computeCostAttribution(entries, graph) {
+    const verifiedByRequirement = new Map(graph.links.map((link) => [link.requirement, link.evidence.length > 0]));
+    const byRequirement = new Map();
+    const unattributed = [];
+    for (const entry of entries) {
+        if (entry.requirement) {
+            const bucket = byRequirement.get(entry.requirement) ?? [];
+            bucket.push(entry);
+            byRequirement.set(entry.requirement, bucket);
+        }
+        else
+            unattributed.push(entry);
+    }
+    const labelOf = (group) => group.every((entry) => entry.label === "measured") ? "measured" : "estimated";
+    const attributed = [...byRequirement]
+        .map(([requirement, group]) => ({
+        requirement,
+        tokens: group.reduce((total, entry) => total + totalTokens(entry), 0),
+        label: labelOf(group),
+        verified: verifiedByRequirement.get(requirement) ?? false,
+    }))
+        .sort((a, b) => b.tokens - a.tokens || a.requirement.localeCompare(b.requirement));
+    const graphRequirements = new Set(graph.links.map((link) => link.requirement));
+    const verifiedRequirements = attributed.filter(({ verified }) => verified).length;
+    const unverifiedRequirements = attributed.filter(({ requirement }) => graphRequirements.has(requirement)).length -
+        verifiedRequirements;
+    const attributedToVerified = attributed
+        .filter(({ verified }) => verified)
+        .reduce((total, entry) => total + entry.tokens, 0);
+    return {
+        attributed,
+        unattributedTokens: unattributed.reduce((total, entry) => total + totalTokens(entry), 0),
+        unattributedLabel: labelOf(unattributed),
+        verifiedRequirements,
+        unverifiedRequirements,
+        totalTokens: entries.reduce((total, entry) => total + totalTokens(entry), 0),
+        totalLabel: labelOf(entries),
+        ...(verifiedRequirements > 0
+            ? { tokensPerVerifiedRequirement: Math.ceil(attributedToVerified / verifiedRequirements) }
+            : {}),
+    };
+}
+export function serializeCostAttribution(attribution) {
+    if (!attribution.attributed.length && !attribution.unattributedTokens)
+        return "No usage recorded against requirements yet. Record with `aiw usage-sidecar record --requirement=REQ-###`.";
+    const lines = [
+        `total_tokens: ${attribution.totalTokens.toLocaleString("en-US")} (${attribution.totalLabel})`,
+        `unattributed_tokens: ${attribution.unattributedTokens.toLocaleString("en-US")} (${attribution.unattributedLabel})`,
+        `verified_requirements: ${attribution.verifiedRequirements}`,
+        `unverified_requirements: ${attribution.unverifiedRequirements}`,
+        ...(attribution.tokensPerVerifiedRequirement === undefined
+            ? ["tokens_per_verified_requirement: n/a (no verified requirements yet)"]
+            : [
+                `tokens_per_verified_requirement: ${attribution.tokensPerVerifiedRequirement.toLocaleString("en-US")} (estimated; outcome-denominated)`,
+            ]),
+        "by requirement:",
+        ...attribution.attributed.map(({ requirement, tokens, label, verified }) => `  - ${requirement}: ${tokens.toLocaleString("en-US")} tokens (${label}, ${verified ? "verified" : "unverified"})`),
+    ];
+    return lines.join("\n");
+}
+export function summarizeTaskUsage(entries, workflow) {
+    const scoped = entries.filter((entry) => entry.workflow === workflow);
+    const labelOf = (group) => group.every((entry) => entry.label === "measured") ? "measured" : "estimated";
+    const inputTokens = scoped.reduce((total, entry) => total + entry.tiers["cache-read"] + entry.tiers["fresh-input"] + entry.tiers["cache-write"], 0);
+    const billableInput = scoped.reduce((total, entry) => total + entry.tiers["cache-read"] + entry.tiers["fresh-input"], 0);
+    const byCommand = new Map();
+    for (const entry of scoped) {
+        const bucket = byCommand.get(entry.command) ?? [];
+        bucket.push(entry);
+        byCommand.set(entry.command, bucket);
+    }
+    const stages = [...byCommand]
+        .map(([stage, group]) => ({
+        stage,
+        tokens: group.reduce((total, entry) => total + totalTokens(entry), 0),
+        label: labelOf(group),
+        models: [...new Set(group.map((entry) => entry.model ?? "unattributed"))].sort(),
+    }))
+        .sort((a, b) => b.tokens - a.tokens || a.stage.localeCompare(b.stage));
+    const uniqueSorted = (values) => [...new Set(values.filter((value) => value !== undefined))].sort();
+    return {
+        workflow,
+        entries: scoped.length,
+        inputTokens,
+        outputTokens: scoped.reduce((total, entry) => total + entry.tiers.output, 0),
+        totalTokens: scoped.reduce((total, entry) => total + totalTokens(entry), 0),
+        label: labelOf(scoped),
+        ...(billableInput > 0
+            ? {
+                cacheHitRate: scoped.reduce((total, entry) => total + entry.tiers["cache-read"], 0) / billableInput,
+            }
+            : {}),
+        stages,
+        requirements: uniqueSorted(scoped.map((entry) => entry.requirement)),
+        models: uniqueSorted(scoped.map((entry) => entry.model)),
+        harnesses: uniqueSorted(scoped.map((entry) => entry.harness)),
+    };
+}
+export function serializeTaskUsage(summary) {
+    if (!summary.entries)
+        return `No usage recorded for workflow ${summary.workflow}. Correlate runs with \`aiw usage-sidecar record --workflow=${summary.workflow}\`.`;
+    return [
+        `workflow: ${summary.workflow} (${summary.entries} entries, ${summary.label})`,
+        `input_tokens: ${summary.inputTokens.toLocaleString("en-US")} (cache-read + fresh-input + cache-write)`,
+        `output_tokens: ${summary.outputTokens.toLocaleString("en-US")}`,
+        `total_tokens: ${summary.totalTokens.toLocaleString("en-US")}`,
+        ...(summary.cacheHitRate === undefined
+            ? []
+            : [`cache_hit_rate: ${Math.round(summary.cacheHitRate * 100)}%`]),
+        ...(summary.models.length ? [`models: ${summary.models.join(", ")}`] : []),
+        ...(summary.harnesses.length ? [`harnesses: ${summary.harnesses.join(", ")}`] : []),
+        ...(summary.requirements.length ? [`requirements: ${summary.requirements.join(", ")}`] : []),
+        "by stage:",
+        ...summary.stages.map(({ stage, tokens, label, models }) => `  - ${stage}: ${tokens.toLocaleString("en-US")} tokens (${label}${models.length ? `; ${models.join(", ")}` : ""})`),
+        "metric: tokens are model-invariant — comparable across model routing changes and harness migrations.",
+    ].join("\n");
+}

package/dist/model-routing.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Static model routing table — advisory, versioned, evidence-linked.
+ *
+ * Research consensus (docs/token-efficiency-study-notes.md §1 and §5):
+ * optimal routing is usually static — per-request dynamism mostly adds
+ * failure modes. Rules follow the ModelFit discipline: every recommendation
+ * names the evidence behind it, execution is advisory only, and humans can
+ * always override. The table never invokes a model; it answers "which model
+ * should this category use, and why".
+ */
+export declare const ROUTING_TABLE_SCHEMA = 1;
+export declare const ROUTING_TABLE_PATH = "routing.yml";
+export declare const ROUTING_DEFAULT_UNSET = "unset";
+export type RoutingRule = {
+    category: string;
+    model: string;
+    /** Named evidence (benchmark, parity run, ADR) backing this rule. Empty means unevidenced. */
+    evidence: string;
+};
+export type RoutingTable = {
+    schema: number;
+    default: string;
+    rules: RoutingRule[];
+};
+export type ResolvedRoute = {
+    category: string;
+    model: string;
+    matchedRule: boolean;
+    evidence?: string;
+    advisory: "evidenced" | "unevidenced-rule" | "default-fallback" | "default-unset";
+};
+export declare function validateRoutingTable(table: RoutingTable): RoutingTable;
+export declare function defaultRoutingTable(): RoutingTable;
+export declare function parseRoutingTable(content: string): RoutingTable;
+export declare function serializeRoutingTable(table: RoutingTable): string;
+/** Resolve a category to a model. Deterministic: same table, same category, same answer. */
+export declare function resolveRoute(table: RoutingTable, category: string): ResolvedRoute;
+export declare function serializeResolvedRoute(route: ResolvedRoute): string;

package/dist/model-routing.js

@@ -0,0 +1,116 @@
+import { parseDocument } from "yaml";
+/**
+ * Static model routing table — advisory, versioned, evidence-linked.
+ *
+ * Research consensus (docs/token-efficiency-study-notes.md §1 and §5):
+ * optimal routing is usually static — per-request dynamism mostly adds
+ * failure modes. Rules follow the ModelFit discipline: every recommendation
+ * names the evidence behind it, execution is advisory only, and humans can
+ * always override. The table never invokes a model; it answers "which model
+ * should this category use, and why".
+ */
+export const ROUTING_TABLE_SCHEMA = 1;
+export const ROUTING_TABLE_PATH = "routing.yml";
+export const ROUTING_DEFAULT_UNSET = "unset";
+const CATEGORY_PATTERN = /^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)*$/;
+function validateRule(rule) {
+    if (!CATEGORY_PATTERN.test(rule.category))
+        throw new Error(`Routing category must be dot-separated kebab-case: ${rule.category}.`);
+    if (!rule.model.trim())
+        throw new Error(`Routing rule for ${rule.category} needs a model.`);
+}
+export function validateRoutingTable(table) {
+    if (table.schema !== ROUTING_TABLE_SCHEMA)
+        throw new Error(`Routing table schema must be version ${ROUTING_TABLE_SCHEMA}.`);
+    if (!table.default.trim())
+        throw new Error("Routing table default model must not be empty.");
+    table.rules.forEach(validateRule);
+    const categories = table.rules.map((rule) => rule.category);
+    if (new Set(categories).size !== categories.length)
+        throw new Error("Routing table categories must be unique.");
+    return table;
+}
+export function defaultRoutingTable() {
+    return validateRoutingTable({
+        schema: ROUTING_TABLE_SCHEMA,
+        default: ROUTING_DEFAULT_UNSET,
+        rules: [],
+    });
+}
+export function parseRoutingTable(content) {
+    const document = parseDocument(content);
+    if (document.errors.length)
+        throw new Error("Routing table is not valid YAML.");
+    const schema = document.get("schema");
+    if (schema !== ROUTING_TABLE_SCHEMA)
+        throw new Error(`Routing table schema must be version ${ROUTING_TABLE_SCHEMA}.`);
+    const pick = (key) => document.get(key);
+    const rulesNode = pick("rules");
+    const rules = [];
+    if (rulesNode !== null && rulesNode !== undefined) {
+        const items = Array.isArray(rulesNode)
+            ? rulesNode
+            : typeof rulesNode.items === "object"
+                ? rulesNode.items
+                : undefined;
+        if (items === undefined)
+            throw new Error("Routing table rules must be a list.");
+        for (const raw of items) {
+            const read = (key) => typeof raw.get === "function"
+                ? raw.get(key)
+                : raw[key];
+            rules.push({
+                category: String(read("category")),
+                model: String(read("model")),
+                evidence: read("evidence") === null || read("evidence") === undefined
+                    ? ""
+                    : String(read("evidence")),
+            });
+        }
+    }
+    return validateRoutingTable({
+        schema: ROUTING_TABLE_SCHEMA,
+        default: String(pick("default") ?? ""),
+        rules,
+    });
+}
+export function serializeRoutingTable(table) {
+    validateRoutingTable(table);
+    const lines = [`schema: ${table.schema}`, `default: ${table.default}`, "rules:"];
+    if (!table.rules.length)
+        lines.push("  []");
+    for (const rule of table.rules) {
+        lines.push(`  - category: ${rule.category}`, `    model: ${rule.model}`, `    evidence: ${rule.evidence ? JSON.stringify(rule.evidence) : '""'}`);
+    }
+    return lines.join("\n") + "\n";
+}
+/** Resolve a category to a model. Deterministic: same table, same category, same answer. */
+export function resolveRoute(table, category) {
+    if (!CATEGORY_PATTERN.test(category))
+        throw new Error(`Routing category must be dot-separated kebab-case: ${category}.`);
+    const rule = table.rules.find((candidate) => candidate.category === category);
+    if (rule)
+        return {
+            category,
+            model: rule.model,
+            matchedRule: true,
+            ...(rule.evidence ? { evidence: rule.evidence } : {}),
+            advisory: rule.evidence ? "evidenced" : "unevidenced-rule",
+        };
+    if (table.default === ROUTING_DEFAULT_UNSET)
+        return { category, model: table.default, matchedRule: false, advisory: "default-unset" };
+    return { category, model: table.default, matchedRule: false, advisory: "default-fallback" };
+}
+export function serializeResolvedRoute(route) {
+    const advisoryText = {
+        evidenced: `advisory: rule is evidence-backed (${route.evidence})`,
+        "unevidenced-rule": "advisory: rule has no named evidence; benchmark it before trusting the routing",
+        "default-fallback": "advisory: no rule for this category; fell back to the table default",
+        "default-unset": "advisory: no rule for this category and the default is unset; a human must choose the model",
+    };
+    return [
+        `category: ${route.category}`,
+        `model: ${route.model}`,
+        advisoryText[route.advisory],
+    ].join("\n");
+}

package/dist/task-parity.d.ts

@@ -0,0 +1,67 @@
+import { type ContextLayer, type ContextStore } from "./context-store.js";
+/**
+ * Task parity suite (deterministic, offline, zero API cost).
+ *
+ * Each parity task pins a quality constraint on context assembly: the
+ * critical facts and completion markers a task needs must survive the
+ * just-in-time assembly path (`retrieveTaskContext`), not only the full
+ * composed context. If a fact only exists in a layer that retrieval drops,
+ * the task fails — that is a true-positive detection of context loss, not
+ * a benchmark artifact (see docs/token-efficiency-study-notes.md, step 2).
+ *
+ * Cost is reported (estimated, characters/4) but never gates: this suite is
+ * the quality gate; the cost gate is `aiw context-bench`.
+ */
+export declare const PARITY_TASK_SCHEMA = 1;
+export type ParityTask = {
+    schema: number;
+    id: string;
+    description: string;
+    layers: Partial<Record<ContextLayer, string>>;
+    criticalFacts: string[];
+    completionMarkers: string[];
+    /** Project-relative artifact paths loaded into layers before assembly (inter-stage parity). */
+    sources?: Partial<Record<ContextLayer, string>>;
+    /** Every literal match of these patterns in the loaded sources must survive assembly. */
+    requiredPatterns?: string[];
+};
+export type ParityAssembler = {
+    name: string;
+    assemble(store: ContextStore): string;
+};
+/** The default just-in-time assembly path under test. */
+export declare const TASK_ASSEMBLER: ParityAssembler;
+/** The full-context baseline every assembler is compared against. */
+export declare const FULL_ASSEMBLER: ParityAssembler;
+export type ParityTaskResult = {
+    id: string;
+    passed: boolean;
+    factsTotal: number;
+    factsRetained: number;
+    missingFacts: string[];
+    missingMarkers: string[];
+    missingPatterns: string[];
+    baselineTokens: number;
+    assembledTokens: number;
+    tokenDelta: number;
+};
+export type ParitySuiteResult = {
+    schema: number;
+    assembler: string;
+    total: number;
+    passed: number;
+    failed: number;
+    totalBaselineTokens: number;
+    totalAssembledTokens: number;
+    results: ParityTaskResult[];
+};
+export declare function parseParityTask(content: string): ParityTask;
+/**
+ * Load declared artifact sources into their layers (inter-stage parity).
+ * Source content is appended after any declared layer content.
+ */
+export declare function materializeParityTask(task: ParityTask, readSource: (path: string) => string): ParityTask;
+/** Run one task: baseline (full context) vs the assembler under test. Exits are pass/fail only. */
+export declare function runParityTask(task: ParityTask, assembler?: ParityAssembler): ParityTaskResult;
+export declare function runParitySuite(tasks: ParityTask[], assembler?: ParityAssembler): ParitySuiteResult;
+export declare function serializeParitySuite(result: ParitySuiteResult): string;