@multileaf/ai-workflow 0.6.1 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,25 @@ 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
+
+- Ticket-driven task entry point: `aiw task start --ticket=TEAM-123 [--title=text]` starts an SDD session that records the ticket, and `aiw task status` reports the ticket, stage statuses, and the next pending step with ticket-aware guidance. `aiw spec --ticket=TEAM-123` links the specification scaffold to the ticket. A new `ticket` skill (recommended as the `ticket-driven-development` capability) drives the flow in the host agent, keeping the brainstorming skip an explicit human decision.
+- `aiw telemetry show` summarizes buffered events by command and outcome (fill level against the retention cap, per-command success/failure counts); `--verbose` adds each event verbatim. `telemetry status` keeps reporting configuration only.
+- Per-model token usage: `usage.yml` records carry model attribution (`stage|budget|used|model`; legacy three-column rows still parse) and `aiw token-usage` summarizes total consumption by model. The OpenAI-compatible provider reports the response usage block, so interpreter usage is measured (marked `(measured)`) when the endpoint provides it and estimated otherwise; `scan.embedding`, `scan.interpreter`, and `recommend.decision` all record their model.
+
 ## [0.6.1] - 2026-10-13
 
 ### Added

package/README.md

@@ -204,6 +204,13 @@ npx @multileaf/ai-workflow recommend --select=typescript-quality,verification
 
 # Track a feature from its first artifact through final human approval.
 npx @multileaf/ai-workflow workflow start
+
+# Or start directly from a ticket / already-clear requirement (no brainstorm needed).
+npx @multileaf/ai-workflow task start --ticket=PROJ-142 --title="Add export endpoint"
+npx @multileaf/ai-workflow task status
+# Record an accepted brainstorm skip, then link the specification to the ticket:
+npx @multileaf/ai-workflow skip brainstorming --reason="Requirement provided by ticket PROJ-142"
+npx @multileaf/ai-workflow spec --ticket=PROJ-142 --title="Add export endpoint"
 npx @multileaf/ai-workflow brainstorm --title="Feature name"
 npx @multileaf/ai-workflow gate brainstorming
 # Present evidence and wait for a human reply before each approve command.
@@ -343,7 +350,8 @@ The typed SDK is available from `@multileaf/ai-workflow/plugin-sdk`. It exports
 Telemetry is disabled by default and requires explicit consent — offered once during interactive installation with an explicit default of No. Each event contains only the command name and its outcome; never arguments, file paths, or file contents. When telemetry is enabled but no host transport is configured, events accumulate in a rotated local buffer (`.aiw/telemetry-buffer.jsonl`, 200-event cap) that `aiw telemetry status --verbose` can inspect and `aiw telemetry disable` purges.
 
 ```bash
-npx @multileaf/ai-workflow telemetry status --verbose
+npx @multileaf/ai-workflow telemetry show             # summarized by command and outcome
+npx @multileaf/ai-workflow telemetry show --verbose   # events verbatim
 npx @multileaf/ai-workflow telemetry enable
 npx @multileaf/ai-workflow telemetry disable
 ```

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/human-approval.d.ts

@@ -20,7 +20,10 @@ export type WorkflowSession = {
     status: "active" | "complete";
     startedAt: string;
     updatedAt: string;
+    ticket?: string;
+    title?: string;
 };
+export declare function validateTaskTicket(ticket: string): void;
 export type ApprovalStageDefinition = {
     optional: boolean;
     requiresQualityGate: boolean;
@@ -49,3 +52,4 @@ export declare function skipOptionalStage(ledger: ApprovalLedger, stage: HumanAp
 export declare function invalidateStageAndDescendants(ledger: ApprovalLedger, stage: HumanApprovalStage, updatedAt: string): ApprovalLedger;
 export declare function serializeApprovalLedger(ledger: ApprovalLedger): string;
 export declare function parseApprovalLedger(content: string): ApprovalLedger;
+export declare function assertWorkflowId(value: string): void;

package/dist/human-approval.js

@@ -2,6 +2,10 @@ import { createHash } from "node:crypto";
 import { parseDocument, stringify } from "yaml";
 import { HUMAN_APPROVAL_STAGES } from "./types.js";
 export const APPROVAL_STAGES = HUMAN_APPROVAL_STAGES;
+export function validateTaskTicket(ticket) {
+    if (!/^[A-Z][A-Z0-9_]*-\d+$/.test(ticket))
+        throw new Error("Task ticket must match TEAM-123, for example PROJ-142.");
+}
 const STAGE_DEFINITIONS = {
     brainstorming: { optional: true, requiresQualityGate: true },
     specification: { optional: false, requiresQualityGate: true },
@@ -22,7 +26,15 @@ const APPROVAL_RECORD_KEYS = new Set([
     "updatedAt",
 ]);
 const LEDGER_KEYS = new Set(["schema", "workflowId", "stages"]);
-const SESSION_KEYS = new Set(["schema", "workflowId", "status", "startedAt", "updatedAt"]);
+const SESSION_KEYS = new Set([
+    "schema",
+    "workflowId",
+    "status",
+    "startedAt",
+    "updatedAt",
+    "ticket",
+    "title",
+]);
 export function createApprovalLedger(workflowId) {
     assertWorkflowId(workflowId);
     return { schema: 1, workflowId, stages: {} };
@@ -47,12 +59,20 @@ export function parseWorkflowSession(content) {
         throw new Error("Workflow session status must be active or complete.");
     if (typeof value.startedAt !== "string" || typeof value.updatedAt !== "string")
         throw new Error("Workflow session requires start and update timestamps.");
+    if (value.ticket !== undefined && typeof value.ticket !== "string")
+        throw new Error("Workflow session ticket must be a string.");
+    if (value.title !== undefined && typeof value.title !== "string")
+        throw new Error("Workflow session title must be a string.");
+    if (typeof value.ticket === "string")
+        validateTaskTicket(value.ticket);
     const session = {
         schema: 1,
         workflowId: value.workflowId,
         status: value.status,
         startedAt: value.startedAt,
         updatedAt: value.updatedAt,
+        ...(value.ticket === undefined ? {} : { ticket: value.ticket }),
+        ...(value.title === undefined ? {} : { title: value.title }),
     };
     validateWorkflowSession(session);
     return session;
@@ -189,7 +209,7 @@ function assertTimestamp(value) {
         !Number.isFinite(Date.parse(value)))
         throw new Error("Approval timestamp must be a valid date-time.");
 }
-function assertWorkflowId(value) {
+export function assertWorkflowId(value) {
     if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(value))
         throw new Error("Workflow ID must be 1–64 characters using letters, numbers, dot, underscore, or hyphen.");
 }

package/dist/interpreter.d.ts

@@ -10,11 +10,16 @@ export type InterpretationRequest = {
 export type Interpreter = {
     interpret(request: InterpretationRequest): Promise<EvidenceFact[]>;
 };
+export type AiProviderUsage = {
+    promptTokens: number;
+    completionTokens: number;
+};
 export type AiProviderRequest = {
     system: string;
     prompt: string;
     maxTokens: number;
     responseFormat: "json";
+    onUsage?: (usage: AiProviderUsage) => void;
 };
 export type AiProvider = {
     generate(request: AiProviderRequest): Promise<string>;
@@ -35,5 +40,7 @@ export declare function buildInterpreterQuery(profile: ProjectProfile): string;
 type AiFetchLike = (url: string, init?: RequestInit) => Promise<Response>;
 export declare function loadAiProviderConfig(fs: FileSystem, aiwPath: string): AiProviderConfig | undefined;
 export declare function createOpenAiCompatibleProvider(config: AiProviderConfig, fetchImpl?: AiFetchLike, env?: Readonly<Record<string, string | undefined>>): AiProvider;
-export declare function createProjectInterpreter(root: string, provider: AiProvider, contextReader?: ContextReader): Interpreter;
+export declare function createProjectInterpreter(root: string, provider: AiProvider, contextReader?: ContextReader, options?: {
+    onUsage?: (usage: AiProviderUsage) => void;
+}): Interpreter;
 export {};

package/dist/interpreter.js

@@ -212,6 +212,12 @@ export function createOpenAiCompatibleProvider(config, fetchImpl = (url, init) =
             if (!response.ok)
                 throw new Error(`AI provider request failed for model ${config.model}: ${await response.text()}`);
             const body = (await response.json());
+            if (typeof body.usage?.prompt_tokens === "number" &&
+                typeof body.usage?.completion_tokens === "number")
+                request.onUsage?.({
+                    promptTokens: body.usage.prompt_tokens,
+                    completionTokens: body.usage.completion_tokens,
+                });
             const content = body.choices?.[0]?.message?.content;
             if (typeof content !== "string")
                 throw new Error(`AI provider ${config.model} returned no message content`);
@@ -219,7 +225,7 @@ export function createOpenAiCompatibleProvider(config, fetchImpl = (url, init) =
         },
     };
 }
-export function createProjectInterpreter(root, provider, contextReader = async (path) => new TextDecoder("utf-8", { fatal: true }).decode(await readFile(path))) {
+export function createProjectInterpreter(root, provider, contextReader = async (path) => new TextDecoder("utf-8", { fatal: true }).decode(await readFile(path)), options = {}) {
     const projectRoot = resolve(root);
     return {
         async interpret(request) {
@@ -261,6 +267,7 @@ export function createProjectInterpreter(root, provider, contextReader = async (
                 prompt: `Detected profile:\n${safeProfile}\n\nScoped project context:\n${sections.join("\n\n")}`,
                 maxTokens: scoped.maxTokens,
                 responseFormat: "json",
+                ...(options.onUsage ? { onUsage: options.onUsage } : {}),
             });
             return parseFacts(output, new Set(scoped.files));
         },

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;