@multileaf/ai-workflow 0.6.1 → 0.8.0

package/dist/workflow.js

@@ -34,9 +34,15 @@ import { enforceOrganizationPolicy, parseOrganizationPolicy, serializeOrganizati
 import { composeContext, CONTEXT_LAYERS, readContextStore, writeContextLayer, } from "./context-store.js";
 import { loadContextDelta, retrieveTaskContext } from "./context-retrieval.js";
 import { createSummaryCache, isSummaryFresh, parseSummaryCache, serializeSummaryCache, } from "./context-cache.js";
-import { parseTokenUsage, recordTokenUsage, serializeTokenUsage } from "./token-usage.js";
-import { APPROVAL_STAGES, approveStage, beginStageApproval, createApprovalLedger, getUnresolvedPrerequisites, invalidateStageAndDescendants, parseApprovalLedger, parseWorkflowSession, rejectStage, serializeApprovalLedger, serializeWorkflowSession, skipOptionalStage, stageDefinition, stageFingerprint, } from "./human-approval.js";
+import { parseTokenUsage, recordTokenUsage, serializeTokenUsage, summarizeUsageByModel, } from "./token-usage.js";
+import { APPROVAL_STAGES, assertWorkflowId, validateTaskTicket, approveStage, beginStageApproval, createApprovalLedger, getUnresolvedPrerequisites, invalidateStageAndDescendants, parseApprovalLedger, parseWorkflowSession, rejectStage, serializeApprovalLedger, serializeWorkflowSession, skipOptionalStage, stageDefinition, stageFingerprint, } from "./human-approval.js";
 import { measureContextQuality, serializeContextQuality } from "./context-quality.js";
+import { collectContextBench, compareContextBench, parseContextBench, serializeContextBench, } from "./context-benchmark.js";
+import { materializeParityTask, parseParityTask, runParitySuite, serializeParitySuite, TASK_ASSEMBLER, } from "./task-parity.js";
+import { appendUsageSidecarEntry, parseUsageSidecar, serializeUsageSidecar, serializeUsageSidecarSummary, summarizeUsageSidecar, USAGE_SIDECAR_PATH, USAGE_TIERS, } from "./usage-sidecar.js";
+import { computeCostAttribution, serializeCostAttribution, serializeTaskUsage, summarizeTaskUsage, } from "./cost-attribution.js";
+import { defaultRoutingTable, parseRoutingTable, resolveRoute, ROUTING_TABLE_PATH, serializeResolvedRoute, serializeRoutingTable, } from "./model-routing.js";
+import { parseTraceabilityGraph } from "./traceability.js";
 import { serializeAdapterCapabilities } from "./adapter-contract.js";
 import { buildTraceabilityGraph, serializeTraceabilityGraph } from "./traceability.js";
 import { evaluateQualityGate } from "./quality-gates.js";
@@ -46,61 +52,122 @@ import { enforcePolicyGate, gitPolicyTracking } from "./policy-gate.js";
 import { DEFAULT_TELEMETRY_CONFIG, loadTelemetryConfig, offerTelemetryConsent, parseTelemetryConfig, purgeTelemetryBuffer, readTelemetryBuffer, serializeTelemetryMapping, TELEMETRY_BUFFER_CAP, TELEMETRY_BUFFER_FILE, } from "./telemetry.js";
 import { createPluginScaffold, validatePluginDirectory, writePluginScaffold, } from "./plugin-sdk.js";
 import { executeOrchestrationPlan, parseOrchestrationPlan, serializeOrchestrationPreview, serializeOrchestrationResults, validateOrchestrationParallelism, } from "./orchestration.js";
+function beginWorkflowSession(fs, aiw, options) {
+    const sessionPath = join(aiw, "workflow.yml");
+    const ledgerPath = join(aiw, "approvals.yml");
+    if (fs.exists(sessionPath)) {
+        const previous = parseWorkflowSession(fs.read(sessionPath));
+        if (previous.status === "active")
+            return {
+                exitCode: 1,
+                error: `Workflow ${previous.workflowId} is still active. Complete it before starting another.`,
+            };
+        if (!fs.exists(ledgerPath))
+            return { exitCode: 1, error: "Completed workflow is missing its approval ledger." };
+        const archive = join(aiw, `checkpoints/workflow-${previous.workflowId}-approvals.yml`);
+        if (fs.exists(archive))
+            return { exitCode: 1, error: `Workflow approval archive already exists: ${archive}` };
+        fs.mkdir(join(aiw, "checkpoints"));
+        fs.write(archive, fs.read(ledgerPath));
+    }
+    else if (fs.exists(ledgerPath)) {
+        return {
+            exitCode: 1,
+            error: "Approval ledger exists without a workflow session; run doctor.",
+        };
+    }
+    const workflowId = options.id ?? randomUUID();
+    const priorRun = join(aiw, `checkpoints/workflow-${workflowId}-approvals.yml`);
+    if (fs.exists(priorRun))
+        return {
+            exitCode: 1,
+            error: `Workflow ID has already been used: ${workflowId}. Choose a new ID.`,
+        };
+    const now = new Date().toISOString();
+    const session = {
+        schema: 1,
+        workflowId,
+        status: "active",
+        startedAt: now,
+        updatedAt: now,
+        ...(options.ticket ? { ticket: options.ticket } : {}),
+        ...(options.title ? { title: options.title } : {}),
+    };
+    const ledger = createApprovalLedger(workflowId);
+    fs.write(ledgerPath, serializeApprovalLedger(ledger));
+    fs.write(sessionPath, serializeWorkflowSession(session));
+    return { exitCode: 0, output: `Workflow started: ${workflowId}.` };
+}
 export async function runCommand(args, root, fs, services = {}) {
     const aiw = join(root, WORKFLOW_DIRECTORY);
     try {
         fs = withSafeProjectWrites(fs, root);
         const command = args[0] ?? "help";
+        if (command === "task") {
+            if (!fs.exists(join(aiw, "manifest.yml")))
+                return { exitCode: 1, error: "Run `aiw install` first." };
+            const usage = "Usage: aiw task start --ticket=TEAM-123 [--title=text] [--id=workflow-id] | aiw task status";
+            const action = args[1];
+            const sessionPath = join(aiw, "workflow.yml");
+            if (action === "start") {
+                const options = parseNamedOptions(args.slice(2), ["ticket", "title", "id"]);
+                if (!options?.ticket)
+                    return { exitCode: 1, error: usage };
+                validateTaskTicket(options.ticket);
+                if (options.id !== undefined) {
+                    try {
+                        assertWorkflowId(options.id);
+                    }
+                    catch {
+                        return { exitCode: 1, error: "Workflow ID must be a UUID." };
+                    }
+                }
+                const result = beginWorkflowSession(fs, aiw, {
+                    ...(options.id ? { id: options.id } : {}),
+                    ticket: options.ticket,
+                    ...(options.title ? { title: options.title } : {}),
+                });
+                if (result.exitCode !== 0)
+                    return result;
+                const title = options.title ? ` titled "${options.title}"` : "";
+                return {
+                    exitCode: 0,
+                    output: `Task started for ticket ${options.ticket}${title}: ${result.output}\n` +
+                        `Next steps: ask the user whether the requirement is clear enough to skip brainstorming (record an accepted skip with \`aiw skip brainstorming --reason="Requirement provided by ticket ${options.ticket}"\`), then create the specification with \`aiw spec --ticket=${options.ticket} --title=...\`.`,
+                };
+            }
+            if (action === "status") {
+                if (!fs.exists(sessionPath))
+                    return {
+                        exitCode: 0,
+                        output: "No SDD workflow is active. Start one with `aiw task start --ticket=TEAM-123`.",
+                    };
+                const { session, ledger } = readWorkflowState(aiw, fs, false);
+                const lines = [
+                    ...(session.ticket
+                        ? [`Ticket: ${session.ticket}${session.title ? ` — ${session.title}` : ""}`]
+                        : []),
+                    `Workflow: ${session.workflowId} (${session.status})`,
+                    "Stages:",
+                    ...APPROVAL_STAGES.map((stage) => `- ${stage}: ${ledger.stages[stage]?.status ?? "not-started"}`),
+                ];
+                const next = APPROVAL_STAGES.find((stage) => (ledger.stages[stage]?.status ?? "not-started") === "not-started");
+                if (session.status === "active" && next)
+                    lines.push(`Next: ${next === "brainstorming" && session.ticket ? `decide brainstorm or record an accepted skip (ticket ${session.ticket} already provides the requirement)` : `advance ${next} (gate, approval)`}.`);
+                return { exitCode: 0, output: lines.join("\n") };
+            }
+            return { exitCode: 1, error: usage };
+        }
         if (command === "workflow") {
             if (!fs.exists(join(aiw, "manifest.yml")))
                 return { exitCode: 1, error: "Run `aiw install` first." };
             const action = args[1];
             const sessionPath = join(aiw, "workflow.yml");
-            const ledgerPath = join(aiw, "approvals.yml");
             if (action === "start") {
                 const options = parseNamedOptions(args.slice(2), ["id"]);
                 if (!options)
                     return { exitCode: 1, error: "Usage: aiw workflow start [--id=workflow-id]" };
-                if (fs.exists(sessionPath)) {
-                    const previous = parseWorkflowSession(fs.read(sessionPath));
-                    if (previous.status === "active")
-                        return {
-                            exitCode: 1,
-                            error: `Workflow ${previous.workflowId} is still active. Complete it before starting another.`,
-                        };
-                    if (!fs.exists(ledgerPath))
-                        return { exitCode: 1, error: "Completed workflow is missing its approval ledger." };
-                    const archive = join(aiw, `checkpoints/workflow-${previous.workflowId}-approvals.yml`);
-                    if (fs.exists(archive))
-                        return { exitCode: 1, error: `Workflow approval archive already exists: ${archive}` };
-                    fs.mkdir(join(aiw, "checkpoints"));
-                    fs.write(archive, fs.read(ledgerPath));
-                }
-                else if (fs.exists(ledgerPath)) {
-                    return {
-                        exitCode: 1,
-                        error: "Approval ledger exists without a workflow session; run doctor.",
-                    };
-                }
-                const workflowId = options.id ?? randomUUID();
-                const priorRun = join(aiw, `checkpoints/workflow-${workflowId}-approvals.yml`);
-                if (fs.exists(priorRun))
-                    return {
-                        exitCode: 1,
-                        error: `Workflow ID has already been used: ${workflowId}. Choose a new ID.`,
-                    };
-                const now = new Date().toISOString();
-                const session = {
-                    schema: 1,
-                    workflowId,
-                    status: "active",
-                    startedAt: now,
-                    updatedAt: now,
-                };
-                const ledger = createApprovalLedger(workflowId);
-                fs.write(ledgerPath, serializeApprovalLedger(ledger));
-                fs.write(sessionPath, serializeWorkflowSession(session));
-                return { exitCode: 0, output: `Workflow started: ${workflowId}.` };
+                return beginWorkflowSession(fs, aiw, { id: options.id });
             }
             if (action === "status") {
                 if (!fs.exists(sessionPath))
@@ -359,13 +426,44 @@ export async function runCommand(args, root, fs, services = {}) {
         if (command === "telemetry") {
             if (!fs.exists(join(aiw, "manifest.yml")))
                 return { exitCode: 1, error: "Run `aiw install` first." };
-            const usage = "Usage: aiw telemetry <status|enable|disable> [--verbose] [--commands=include|exclude] [--outcomes=include|exclude]";
+            const usage = "Usage: aiw telemetry <status|show|enable|disable> [--verbose] [--commands=include|exclude] [--outcomes=include|exclude]";
             const action = args[1];
             if (!action)
                 return { exitCode: 1, error: usage };
             const telemetryConfig = loadTelemetryConfig(fs, aiw);
             const actionArgs = args.slice(2).filter((arg) => arg !== "--verbose");
             const verbose = args.includes("--verbose");
+            if (action === "show") {
+                if (actionArgs.length !== 0)
+                    return { exitCode: 1, error: usage };
+                const buffered = readTelemetryBuffer(fs, aiw);
+                const byCommand = new Map();
+                for (const event of buffered) {
+                    const key = event.command ?? "unknown";
+                    const entry = byCommand.get(key) ?? { success: 0, failure: 0 };
+                    if (event.outcome === "failure")
+                        entry.failure += 1;
+                    else
+                        entry.success += 1;
+                    byCommand.set(key, entry);
+                }
+                const lines = [
+                    `Telemetry is ${telemetryConfig.enabled ? "enabled" : "disabled"}.`,
+                    `Buffered events: ${buffered.length}/${TELEMETRY_BUFFER_CAP} (.aiw/${TELEMETRY_BUFFER_FILE}).`,
+                ];
+                if (buffered.length > 0) {
+                    lines.push("By command:");
+                    for (const [command, { success, failure }] of [...byCommand].sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+                        lines.push(`- ${command}: ${success} success, ${failure} failure`);
+                }
+                if (verbose && buffered.length > 0) {
+                    lines.push("Events:");
+                    lines.push(...buffered.map((event) => `- ${JSON.stringify(event)}`));
+                }
+                if (!telemetryConfig.enabled)
+                    lines.push("Note: telemetry is disabled, so no new events are recorded; the buffer keeps previously collected events until purged.");
+                return { exitCode: 0, output: lines.join("\n") };
+            }
             if (action === "status") {
                 if (actionArgs.length !== 0)
                     return { exitCode: 1, error: usage };
@@ -438,16 +536,120 @@ export async function runCommand(args, root, fs, services = {}) {
             }
             return { exitCode: 1, error: usage };
         }
+        if (command === "context-bench") {
+            if (!fs.exists(join(aiw, "manifest.yml")))
+                return { exitCode: 1, error: "Run `aiw install` first." };
+            const saveCount = args.filter((arg) => arg === "--save").length;
+            if (saveCount > 1)
+                return { exitCode: 1, error: "Usage: aiw context-bench [--baseline=path] [--save]" };
+            const save = saveCount === 1;
+            const parsed = parseNamedOptions(args.slice(1).filter((arg) => arg !== "--save"), ["baseline"]);
+            if (!parsed)
+                return { exitCode: 1, error: "Usage: aiw context-bench [--baseline=path] [--save]" };
+            const report = collectContextBench(root, fs);
+            const serialized = serializeContextBench(report);
+            const lines = [serialized.trimEnd()];
+            if (parsed.baseline) {
+                const baselinePath = safeProjectFile(root, parsed.baseline, fs);
+                if (!fs.exists(baselinePath))
+                    return { exitCode: 1, error: `Baseline not found: ${parsed.baseline}` };
+                const comparison = compareContextBench(parseContextBench(fs.read(baselinePath)), report);
+                lines.push(`Baseline: ${parsed.baseline} (bundle ${comparison.bundleChanged ? "changed" : "identical"}, token delta ${comparison.totalTokenDelta >= 0 ? "+" : ""}${comparison.totalTokenDelta})`);
+                if (comparison.regressions.length)
+                    return {
+                        exitCode: 1,
+                        error: `Standing context regressed against baseline:\n${comparison.regressions.map((regression) => `- ${regression}`).join("\n")}`,
+                        output: lines.join("\n"),
+                    };
+                lines.push("No regressions against baseline.");
+            }
+            if (save) {
+                const checkpoint = join(aiw, `checkpoints/context-bench-${report.bundleHash}.yml`);
+                if (!fs.createExclusive)
+                    return { exitCode: 1, error: "The filesystem does not support atomic checkpoints." };
+                if (!fs.createExclusive(checkpoint, serialized)) {
+                    if (fs.read(checkpoint) !== serialized)
+                        return {
+                            exitCode: 1,
+                            error: `Checkpoint already exists with different content: ${checkpoint}`,
+                        };
+                    lines.push(`Checkpoint already recorded: ${checkpoint}`);
+                }
+                else {
+                    lines.push(`Checkpoint saved: ${checkpoint}`);
+                }
+            }
+            return { exitCode: 0, output: lines.join("\n") };
+        }
+        if (command === "parity") {
+            if (!fs.exists(join(aiw, "manifest.yml")))
+                return { exitCode: 1, error: "Run `aiw install` first." };
+            const parsed = parseNamedOptions(args.slice(1), ["tasks"]);
+            if (!parsed)
+                return { exitCode: 1, error: "Usage: aiw parity [--tasks=directory]" };
+            const tasksPath = parsed.tasks;
+            if (tasksPath && (isAbsolute(tasksPath) || tasksPath.split(/[\\/]/).includes("..")))
+                return {
+                    exitCode: 1,
+                    error: "Parity tasks directory must be a safe project-relative path.",
+                };
+            const tasksDirectory = tasksPath ? join(root, tasksPath) : join(aiw, "parity");
+            if (fs.pathType?.(tasksDirectory) !== "directory" || !fs.list)
+                return {
+                    exitCode: 1,
+                    error: `Parity tasks directory not found: ${relative(root, tasksDirectory).split(sep).join("/")}. Add YAML tasks (see docs/token-efficiency.md).`,
+                };
+            const taskFiles = (fs.list(tasksDirectory) ?? [])
+                .filter((name) => name.endsWith(".yml"))
+                .sort();
+            if (!taskFiles.length)
+                return {
+                    exitCode: 1,
+                    error: `No parity tasks found in ${relative(root, tasksDirectory).split(sep).join("/")}. Each task is one YAML file with schema, id, layers, critical_facts, and completion_markers.`,
+                };
+            const tasks = taskFiles.map((name) => {
+                const path = join(tasksDirectory, name);
+                try {
+                    return materializeParityTask(parseParityTask(fs.read(path)), (source) => {
+                        const absolute = join(root, source);
+                        if (fs.pathType?.(absolute) !== "file")
+                            throw new Error("source is not a file");
+                        return fs.read(absolute);
+                    });
+                }
+                catch (error) {
+                    throw new Error(`${name}: ${error.message}`, { cause: error });
+                }
+            });
+            const suite = runParitySuite(tasks, TASK_ASSEMBLER);
+            const serialized = serializeParitySuite(suite);
+            if (suite.failed)
+                return {
+                    exitCode: 1,
+                    output: serialized.trimEnd(),
+                    error: `Task parity failed for ${suite.failed} of ${suite.total} task(s): critical facts or completion markers were lost by the ${TASK_ASSEMBLER.name} assembler. Fix context assembly or move the facts to a retrieved layer; do not delete the expectations.`,
+                };
+            return {
+                exitCode: 0,
+                output: serialized.trimEnd() +
+                    `\nTask parity passed: every critical fact survived the ${TASK_ASSEMBLER.name} assembler.`,
+            };
+        }
         if (command === "scan") {
             if (!fs.exists(join(aiw, "manifest.yml")))
                 return { exitCode: 1, error: "Run `aiw install` first." };
             const profile = await (services.profiler?.profile(root) ?? profileProject(root));
             let interpreter = services.interpreter;
             let interpreterModel;
+            let interpreterUsage;
             if (!interpreter) {
                 const aiConfig = loadAiProviderConfig(fs, aiw);
                 if (aiConfig?.enabled) {
-                    interpreter = createProjectInterpreter(root, services.aiProvider ?? createOpenAiCompatibleProvider(aiConfig));
+                    interpreter = createProjectInterpreter(root, services.aiProvider ?? createOpenAiCompatibleProvider(aiConfig), undefined, {
+                        onUsage: (usage) => {
+                            interpreterUsage = usage;
+                        },
+                    });
                     interpreterModel = aiConfig.model;
                 }
             }
@@ -477,6 +679,7 @@ export async function runCommand(args, root, fs, services = {}) {
                                     label: "embedding",
                                     tokens: Math.ceil(buildInterpreterQuery(profile).length / 4),
                                     detail: `${contextConfig.model} — scoped interpreter context to ${matches.length} semantic matches`,
+                                    model: contextConfig.model,
                                 });
                             }
                         }
@@ -488,10 +691,14 @@ export async function runCommand(args, root, fs, services = {}) {
                 const interpretationRequest = createInterpretationRequest(profile, scopedFiles, 4000, priorityFiles);
                 const inferred = await interpreter.interpret(interpretationRequest);
                 profile.facts = mergeFacts(profile.facts, inferred);
+                const actualTokens = interpreterUsage
+                    ? interpreterUsage.promptTokens + interpreterUsage.completionTokens
+                    : undefined;
                 modelUsage.push({
                     label: "interpreter",
-                    tokens: interpretationRequest.estimatedTokens,
-                    detail: `${interpreterModel} — ${inferred.length} facts from ${interpretationRequest.files.length} files`,
+                    tokens: actualTokens ?? interpretationRequest.estimatedTokens,
+                    detail: `${interpreterModel} — ${inferred.length} facts from ${interpretationRequest.files.length} files${actualTokens !== undefined ? " (measured)" : ""}`,
+                    model: interpreterModel ?? "unknown",
                 });
             }
             const overrides = readFactOverrides(fs, aiw);
@@ -530,6 +737,7 @@ export async function runCommand(args, root, fs, services = {}) {
                     label: "embedding",
                     tokens: Math.ceil(indexedChars / 4),
                     detail: `${semanticConfig.model} — indexed ${index.chunks.length} chunks in ${Math.ceil(index.chunks.length / 64)} batch requests`,
+                    model: semanticConfig.model,
                 });
             }
             if (modelUsage.length > 0) {
@@ -541,8 +749,31 @@ export async function runCommand(args, root, fs, services = {}) {
                         stage: `scan.${usage.label}`,
                         budget: usage.tokens,
                         used: usage.tokens,
+                        model: usage.model,
                     });
                 fs.write(usagePath, serializeTokenUsage(next));
+                const sidecarPath = join(aiw, USAGE_SIDECAR_PATH);
+                const ledger = fs.exists(sidecarPath) ? parseUsageSidecar(fs.read(sidecarPath)) : [];
+                let sidecar = ledger;
+                for (const usage of modelUsage) {
+                    const measured = usage.detail.includes("(measured)");
+                    const isInterpreter = usage.label === "interpreter" && measured && interpreterUsage;
+                    sidecar = appendUsageSidecarEntry(sidecar, {
+                        command: `scan.${usage.label}`,
+                        label: measured ? "measured" : "estimated",
+                        tiers: isInterpreter
+                            ? {
+                                "cache-read": 0,
+                                "fresh-input": interpreterUsage.promptTokens,
+                                "cache-write": 0,
+                                output: interpreterUsage.completionTokens,
+                            }
+                            : { "cache-read": 0, "fresh-input": usage.tokens, "cache-write": 0, output: 0 },
+                        model: usage.model,
+                        harness: "aiw-cli",
+                    });
+                }
+                fs.write(sidecarPath, serializeUsageSidecar(sidecar));
             }
             return {
                 exitCode: 0,
@@ -1076,6 +1307,7 @@ export async function runCommand(args, root, fs, services = {}) {
                     stage: "recommend.decision",
                     budget: decisionTokens,
                     used: decisionTokens,
+                    model: rankingConfig.model,
                 })));
                 ordered = ranked.items;
             }
@@ -1409,8 +1641,11 @@ export async function runCommand(args, root, fs, services = {}) {
                 return { exitCode: 1, error: "Run `aiw install` first." };
             assertStageReady(aiw, fs, "specification");
             const title = args.find((arg) => arg.startsWith("--title="))?.slice(8) || "Untitled Specification";
+            const ticket = args.find((arg) => arg.startsWith("--ticket="))?.slice(9);
+            if (ticket !== undefined)
+                validateTaskTicket(ticket);
             const path = join(aiw, "generated/specs/specification.md");
-            fs.write(path, `# ${title}\n\n## Context\n\n## Requirements\n\n### REQ-001: Requirement title\n\n- **Description:**\n- **Acceptance criteria:**\n  - Given\n  - When\n  - Then\n\n## Non-functional Requirements\n\n## Constraints\n\n## Open Questions\n\n`);
+            fs.write(path, `# ${title}\n${ticket ? `\n> Ticket: ${ticket}\n` : ""}\n## Context\n\n## Requirements\n\n### REQ-001: Requirement title\n\n- **Description:**\n- **Acceptance criteria:**\n  - Given\n  - When\n  - Then\n\n## Non-functional Requirements\n\n## Constraints\n\n## Open Questions\n\n`);
             return { exitCode: 0, output: `Specification artifact created: ${path}` };
         }
         if (command === "adr") {
@@ -1814,6 +2049,183 @@ export async function runCommand(args, root, fs, services = {}) {
             fs.write(cachePath, serializeSummaryCache(createSummaryCache(context, summaryArg)));
             return { exitCode: 0, output: summaryArg };
         }
+        if (command === "routing") {
+            if (!fs.exists(join(aiw, "manifest.yml")))
+                return { exitCode: 1, error: "Run `aiw install` first." };
+            const usage = "Usage: aiw routing init | show | resolve --category=name";
+            const action = args[1];
+            const routingPath = join(aiw, ROUTING_TABLE_PATH);
+            if (action === "init") {
+                if (fs.exists(routingPath))
+                    return {
+                        exitCode: 1,
+                        error: `Routing table already exists: .aiw/${ROUTING_TABLE_PATH}. Edit it directly instead of re-initializing.`,
+                    };
+                fs.write(routingPath, serializeRoutingTable(defaultRoutingTable()) +
+                    "# Add one rule per task category (dot-separated kebab-case, e.g. scan.interpreter).\n" +
+                    "# Name the evidence behind every rule — a benchmark, parity run, or ADR — before trusting it.\n" +
+                    "# Routing is advisory: humans can always override the resolved model.\n");
+                return {
+                    exitCode: 0,
+                    output: `Routing table created: .aiw/${ROUTING_TABLE_PATH}. Add rules with named evidence, then resolve with \`aiw routing resolve --category=...\`.`,
+                };
+            }
+            if (action === "show") {
+                if (!fs.exists(routingPath))
+                    return {
+                        exitCode: 1,
+                        error: `No routing table found. Run \`aiw routing init\` to create .aiw/${ROUTING_TABLE_PATH}.`,
+                    };
+                return {
+                    exitCode: 0,
+                    output: serializeRoutingTable(parseRoutingTable(fs.read(routingPath))).trimEnd(),
+                };
+            }
+            if (action === "resolve") {
+                const category = args.find((arg) => arg.startsWith("--category="))?.slice(11);
+                if (!category)
+                    return { exitCode: 1, error: usage };
+                if (!fs.exists(routingPath))
+                    return {
+                        exitCode: 1,
+                        error: `No routing table found. Run \`aiw routing init\` first.`,
+                    };
+                let route;
+                try {
+                    route = resolveRoute(parseRoutingTable(fs.read(routingPath)), category);
+                }
+                catch (error) {
+                    throw new Error(`Routing failed: ${error.message}`, { cause: error });
+                }
+                return {
+                    exitCode: 0,
+                    output: serializeResolvedRoute(route) +
+                        "\noverride: advisory only — a human may choose a different model at any time.",
+                };
+            }
+            return { exitCode: 1, error: usage };
+        }
+        if (command === "task-usage") {
+            if (!fs.exists(join(aiw, "manifest.yml")))
+                return { exitCode: 1, error: "Run `aiw install` first." };
+            const parsed = parseNamedOptions(args.slice(1), ["workflow"]);
+            if (!parsed)
+                return { exitCode: 1, error: "Usage: aiw task-usage [--workflow=id-or-ticket]" };
+            const sidecarPath = join(aiw, USAGE_SIDECAR_PATH);
+            if (!fs.exists(sidecarPath))
+                return {
+                    exitCode: 1,
+                    error: "No usage sidecar recorded yet. Correlate runs with `aiw usage-sidecar record --workflow=<id-or-ticket>` or run `aiw scan`.",
+                };
+            const sessionPath = join(aiw, "workflow.yml");
+            const workflow = parsed.workflow ??
+                (fs.exists(sessionPath)
+                    ? (parseWorkflowSession(fs.read(sessionPath)).ticket ??
+                        parseWorkflowSession(fs.read(sessionPath)).workflowId)
+                    : undefined);
+            if (!workflow)
+                return {
+                    exitCode: 1,
+                    error: "No workflow specified and no active SDD task. Pass --workflow=<id-or-ticket>.",
+                };
+            const summary = summarizeTaskUsage(parseUsageSidecar(fs.read(sidecarPath)), workflow);
+            return {
+                exitCode: 0,
+                output: serializeTaskUsage(summary),
+            };
+        }
+        if (command === "cost-report") {
+            if (!fs.exists(join(aiw, "manifest.yml")))
+                return { exitCode: 1, error: "Run `aiw install` first." };
+            const sidecarPath = join(aiw, USAGE_SIDECAR_PATH);
+            if (!fs.exists(sidecarPath))
+                return {
+                    exitCode: 1,
+                    error: "No usage sidecar recorded yet. Record runs with `aiw usage-sidecar record` or run `aiw scan`.",
+                };
+            const tracePath = join(aiw, "generated/artifacts/traceability.yml");
+            if (!fs.exists(tracePath))
+                return {
+                    exitCode: 1,
+                    error: "Traceability graph is missing. Run `aiw trace` to build it from the approved specification and plan.",
+                };
+            const attribution = computeCostAttribution(parseUsageSidecar(fs.read(sidecarPath)), parseTraceabilityGraph(fs.read(tracePath)));
+            return {
+                exitCode: 0,
+                output: serializeCostAttribution(attribution) +
+                    "\nSources: .aiw/checkpoints/usage-sidecar.yml + .aiw/generated/artifacts/traceability.yml (verified = linked evidence present).",
+            };
+        }
+        if (command === "usage-sidecar") {
+            if (!fs.exists(join(aiw, "manifest.yml")))
+                return { exitCode: 1, error: "Run `aiw install` first." };
+            const usage = "Usage: aiw usage-sidecar record --command=name (--cache-read=N | --fresh-input=N | --cache-write=N | --output=N) [--model=name] [--harness=name] [--harness-version=text] [--estimated] | aiw usage-sidecar report";
+            const action = args[1];
+            const sidecarPath = join(aiw, USAGE_SIDECAR_PATH);
+            if (action === "report") {
+                const entries = fs.exists(sidecarPath) ? parseUsageSidecar(fs.read(sidecarPath)) : [];
+                return {
+                    exitCode: 0,
+                    output: serializeUsageSidecarSummary(summarizeUsageSidecar(entries)) +
+                        (entries.length
+                            ? `\nLedger: .aiw/${USAGE_SIDECAR_PATH} (${entries.length} entries, sequence-ordered, no timestamps)`
+                            : ""),
+                };
+            }
+            if (action === "record") {
+                const recordArgs = args.slice(2).filter((arg) => arg !== "--estimated");
+                if (recordArgs.some((arg) => arg !== "--estimated" && !arg.startsWith("--")))
+                    return { exitCode: 1, error: usage };
+                const parsed = parseNamedOptions(recordArgs, [
+                    "command",
+                    "model",
+                    "harness",
+                    "harness-version",
+                    "requirement",
+                    "workflow",
+                    ...USAGE_TIERS,
+                ]);
+                if (!parsed?.command)
+                    return { exitCode: 1, error: usage };
+                const tierValues = USAGE_TIERS.map((tier) => [tier, parsed[tier]]).filter(([, value]) => value !== undefined);
+                if (!tierValues.length)
+                    return {
+                        exitCode: 1,
+                        error: "At least one token tier is required: --cache-read, --fresh-input, --cache-write, or --output.",
+                    };
+                for (const [, value] of tierValues)
+                    if (!/^\d+$/.test(value))
+                        return { exitCode: 1, error: "Token tiers must be non-negative integers." };
+                const entry = {
+                    command: parsed.command,
+                    label: (args.includes("--estimated") ? "estimated" : "measured"),
+                    tiers: Object.fromEntries(USAGE_TIERS.map((tier) => [tier, Number(parsed[tier] ?? 0)])),
+                    ...(parsed.model ? { model: parsed.model } : {}),
+                    ...(parsed.harness ? { harness: parsed.harness } : {}),
+                    ...(parsed["harness-version"] ? { harnessVersion: parsed["harness-version"] } : {}),
+                    ...(parsed.requirement ? { requirement: parsed.requirement } : {}),
+                    ...(parsed.workflow ? { workflow: parsed.workflow } : {}),
+                };
+                let ledger;
+                try {
+                    ledger = fs.exists(sidecarPath) ? parseUsageSidecar(fs.read(sidecarPath)) : [];
+                }
+                catch (error) {
+                    throw new Error(`Usage sidecar is unreadable: ${error.message}`, {
+                        cause: error,
+                    });
+                }
+                const next = appendUsageSidecarEntry(ledger, entry);
+                fs.write(sidecarPath, serializeUsageSidecar(next));
+                return {
+                    exitCode: 0,
+                    output: `Usage recorded (seq ${next[next.length - 1].seq}, ${entry.label}): ${entry.command} — ${USAGE_TIERS.filter((tier) => entry.tiers[tier] > 0)
+                        .map((tier) => `${tier} ${entry.tiers[tier].toLocaleString("en-US")}`)
+                        .join(", ")}`,
+                };
+            }
+            return { exitCode: 1, error: usage };
+        }
         if (command === "token-usage") {
             const usagePath = join(aiw, "usage.yml");
             const entries = fs.exists(usagePath) ? parseTokenUsage(fs.read(usagePath)) : [];
@@ -1834,7 +2246,15 @@ export async function runCommand(args, root, fs, services = {}) {
                 fs.write(usagePath, serializeTokenUsage(next));
                 return { exitCode: 0, output: `Token usage recorded: ${stage} (${used}/${budget})` };
             }
-            return { exitCode: 0, output: serializeTokenUsage(entries) };
+            if (entries.length === 0)
+                return { exitCode: 0, output: "No token usage recorded yet." };
+            const summary = summarizeUsageByModel(entries);
+            return {
+                exitCode: 0,
+                output: `Token usage by model:\n${summary
+                    .map((entry) => `- ${entry.model}: ${entry.tokens.toLocaleString("en-US")} tokens (${entry.stages.join(", ")})`)
+                    .join("\n")}\n\nRaw records:\n${serializeTokenUsage(entries)}`,
+            };
         }
         if (command === "context-quality") {
             const metrics = measureContextQuality(readContextStore(root, fs));
@@ -1880,7 +2300,7 @@ export async function runCommand(args, root, fs, services = {}) {
         }
         return {
             exitCode: 0,
-            output: "aiw install [--target target] | workflow <start|status|complete> [--id=id] | approve <stage> | reject <stage> --reason=text | skip <optional-stage> --reason=text | ui [--port=number] | orchestrate --plan=path [--execute] [--max-parallel=number] | telemetry <status|enable|disable> [privacy options] | plugin <create|validate> [options] | scan | semantic <status|query> | decision <status|triage> | self-validate --ticket=TYPE-000 | organization-policy --file=path [--replace] | policy-check --package=path [--package=path] | preset --file=path [--replace] | context | context-summary | context-quality | capabilities [--target=target] | token-usage [--stage=name --budget=number --used=number] | registry [--search=query] [--private=name] | registry configure --file=path [--replace] | skills <search|inspect|install|check|update> [options] | audit-package --package=path | verify-package --package=path --checksum=sha256 | brainstorm [--title=title] | spec [--title=title] | adr [--id=id --title=title] | plan [--title=title] | verify | trace | gate <stage> | recommend [--select=id,id] | status | doctor | repair | uninstall [--dry-run] | target <target> | rollback | confirm | resolve --package=path | update --package=path --target=target | validate [--package=path]",
+            output: "aiw install [--target target] | workflow <start|status|complete> [--id=id] | task <start|status> --ticket=TEAM-123 [--title=text] | approve <stage> | reject <stage> --reason=text | skip <optional-stage> --reason=text | ui [--port=number] | orchestrate --plan=path [--execute] [--max-parallel=number] | telemetry <status|show|enable|disable> [privacy options] | plugin <create|validate> [options] | scan | semantic <status|query> | decision <status|triage> | self-validate --ticket=TYPE-000 | organization-policy --file=path [--replace] | policy-check --package=path [--package=path] | preset --file=path [--replace] | context | context-summary | context-quality | capabilities [--target=target] | token-usage [--stage=name --budget=number --used=number] | registry [--search=query] [--private=name] | registry configure --file=path [--replace] | skills <search|inspect|install|check|update> [options] | audit-package --package=path | verify-package --package=path --checksum=sha256 | brainstorm [--title=title] | spec [--title=title] | adr [--id=id --title=title] | plan [--title=title] | verify | trace | gate <stage> | recommend [--select=id,id] | status | doctor | repair | uninstall [--dry-run] | target <target> | rollback | confirm | resolve --package=path | update --package=path --target=target | validate [--package=path]",
         };
     }
     catch (error) {

package/docs/README.md

@@ -12,6 +12,8 @@ AI Workflow is a portable, spec-driven development system for AI coding agents.
 - [Security and trust](security.md)
 - [Quality and testing](quality.md)
 - [Token efficiency](token-efficiency.md)
+- [Token efficiency research](token-efficiency-research.md)
+- [Token efficiency study notes](token-efficiency-study-notes.md)
 - [Project intelligence](project-intelligence.md)
 - [Semantic mapping](semantic-mapping.md)
 - [Decision model evaluation](decision-model-evaluation.md)