@multileaf/ai-workflow 0.7.0 → 0.9.0

package/dist/workflow.js

@@ -1,4 +1,5 @@
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { homedir } from "node:os";
 import { randomUUID } from "node:crypto";
 import { BASE_DIRECTORIES, WORKFLOW_DIRECTORY } from "./constants.js";
 import { detectTarget, isTarget, renderAiInit, describeResource, renderAiInitPath, renderResourcePath, } from "./adapter.js";
@@ -13,6 +14,20 @@ import { recommendCapabilities, rankRecommendations, resourcesForCapabilities, s
 import { selectRecommendations } from "./selection.js";
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
+async function readStdin() {
+    const terminal = createInterface({ input: stdin });
+    try {
+        return await new Promise((resolve, reject) => {
+            let data = "";
+            stdin.on("data", (chunk) => (data += chunk));
+            stdin.on("end", () => resolve(data));
+            stdin.on("error", reject);
+        });
+    }
+    finally {
+        terminal.close();
+    }
+}
 import { generateProjectResources } from "./generator.js";
 import { detectDrift } from "./drift.js";
 import { parseManifest, serializeManifest } from "./manifest.js";
@@ -37,6 +52,15 @@ import { createSummaryCache, isSummaryFresh, parseSummaryCache, serializeSummary
 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 { mergeImportedEvents, parseClaudeCodeTranscript, parseCodexSession, parseGeminiTranscript, parsePiSession, summarizeImport, } from "./usage-import.js";
+import { describeHeartbeatOutcome, emptyHeartbeatState, HEARTBEAT_STATE_PATH, HEARTBEAT_TTL_SECONDS, HEARTBEAT_WARN_SECONDS, parseHeartbeatState, recordBeat, serializeHeartbeatCheckpoint, serializeHeartbeatState, validateHeartbeatThresholds, } from "./heartbeat.js";
+import { installHeartbeatHooks, parseClaudeSettings, writeClaudeSettings, } from "./hook-installer.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";
@@ -530,6 +554,105 @@ 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." };
@@ -647,6 +770,28 @@ export async function runCommand(args, root, fs, services = {}) {
                         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,
@@ -1922,6 +2067,380 @@ 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 === "heartbeat") {
+            if (!fs.exists(join(aiw, "manifest.yml")))
+                return { exitCode: 1, error: "Run `aiw install` first." };
+            const parsed = parseNamedOptions(args.slice(1), ["session", "warn", "ttl"]);
+            if (!parsed)
+                return {
+                    exitCode: 1,
+                    error: "Usage: aiw heartbeat --session=id [--warn=seconds] [--ttl=seconds]",
+                };
+            const warnSeconds = parsed.warn === undefined ? HEARTBEAT_WARN_SECONDS : Number(parsed.warn);
+            const ttlSeconds = parsed.ttl === undefined ? HEARTBEAT_TTL_SECONDS : Number(parsed.ttl);
+            try {
+                validateHeartbeatThresholds(warnSeconds, ttlSeconds);
+            }
+            catch (error) {
+                return { exitCode: 1, error: error.message };
+            }
+            let session = parsed.session;
+            if (!session && !stdin.isTTY) {
+                // Claude Code hooks deliver a JSON payload with session_id on stdin.
+                try {
+                    const payload = JSON.parse(await readStdin());
+                    if (payload &&
+                        typeof payload === "object" &&
+                        typeof payload.session_id === "string")
+                        session = payload.session_id;
+                }
+                catch {
+                    // No parseable payload: fall through to the explicit error below.
+                }
+            }
+            if (!session)
+                return {
+                    exitCode: 1,
+                    error: "A session id is required: pass --session=id or pipe a harness hook JSON payload on stdin.",
+                };
+            const statePath = join(aiw, HEARTBEAT_STATE_PATH);
+            const state = fs.exists(statePath)
+                ? parseHeartbeatState(fs.read(statePath))
+                : emptyHeartbeatState();
+            const { state: nextState, outcome } = recordBeat(state, session, new Date(), warnSeconds, ttlSeconds);
+            fs.write(statePath, serializeHeartbeatState(nextState));
+            const lines = [describeHeartbeatOutcome(outcome)];
+            if (outcome.checkpoint) {
+                const checkpointPath = join(aiw, `checkpoints/heartbeat-${session}-${outcome.checkpoint.index}.yml`);
+                fs.write(checkpointPath, serializeHeartbeatCheckpoint(outcome.checkpoint, outcome.gapSeconds ?? 0, ttlSeconds));
+                lines.push(`checkpoint: ${relative(root, checkpointPath).split(sep).join("/")}`);
+            }
+            return { exitCode: 0, output: lines.join("\n") };
+        }
+        if (command === "hooks") {
+            if (!fs.exists(join(aiw, "manifest.yml")))
+                return { exitCode: 1, error: "Run `aiw install` first." };
+            const action = args[1];
+            if (action !== "install")
+                return {
+                    exitCode: 1,
+                    error: "Usage: aiw hooks install --target=claude-code (codex and gemini adapters follow the same command)",
+                };
+            const parsed = parseNamedOptions(args.slice(2), ["target"]);
+            if (!parsed?.target)
+                return { exitCode: 1, error: "Usage: aiw hooks install --target=claude-code" };
+            if (parsed.target !== "claude-code")
+                return {
+                    exitCode: 1,
+                    error: `Harness hook adapter not available yet for: ${parsed.target}. Claude Code is wired; codex and gemini follow the same pattern.`,
+                };
+            const settingsPath = join(root, ".claude/settings.json");
+            let settings;
+            try {
+                settings = parseClaudeSettings(fs.exists(settingsPath) ? fs.read(settingsPath) : "");
+            }
+            catch (error) {
+                return {
+                    exitCode: 1,
+                    error: `Existing .claude/settings.json is not a valid hooks file; fix or move it first: ${error.message}`,
+                };
+            }
+            const result = installHeartbeatHooks(settings);
+            if (fs.pathType?.(settingsPath) === "symlink")
+                return {
+                    exitCode: 1,
+                    error: ".claude/settings.json is a symbolic link; install hooks manually.",
+                };
+            writeClaudeSettings(fs, settingsPath, result.settings);
+            return {
+                exitCode: 0,
+                output: `Heartbeat hooks installed into .claude/settings.json (project-scoped):\n` +
+                    [...result.added, ...result.alreadyPresent]
+                        .map((event) => `- ${event}: ${result.added.includes(event) ? "added" : "already present"} → aiw heartbeat on every event`)
+                        .join("\n") +
+                    "\nSessions now record beats; idle gaps inside the warn window save a compact checkpoint while the cache is still warm.",
+            };
+        }
+        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 === "import") {
+                const parsed = parseNamedOptions(args.slice(2), ["from", "path"]);
+                const source = parsed?.from;
+                if (!parsed || !source || !["claude-code", "codex", "gemini", "pi"].includes(source))
+                    return {
+                        exitCode: 1,
+                        error: "Usage: aiw usage-sidecar import --from=claude-code|codex|gemini|pi [--path=logs-directory]",
+                    };
+                if (!fs.list)
+                    return { exitCode: 1, error: "The filesystem cannot enumerate harness logs." };
+                const home = homedir();
+                const defaultRoot = source === "claude-code"
+                    ? join(home, ".claude/projects", root.split("/").join("-"))
+                    : source === "codex"
+                        ? join(home, ".codex/sessions")
+                        : source === "pi"
+                            ? join(home, ".pi/agent/sessions")
+                            : join(home, ".gemini/antigravity-cli/brain");
+                const scanRoot = parsed.path ? resolve(parsed.path) : defaultRoot;
+                if (fs.pathType?.(scanRoot) !== "directory")
+                    return {
+                        exitCode: 1,
+                        error: `Harness log directory not found: ${scanRoot}. Pass --path to point at the ${source} logs.`,
+                    };
+                const wanted = (name) => source === "claude-code"
+                    ? name.endsWith(".jsonl")
+                    : source === "codex"
+                        ? /^rollout-.*\.jsonl$/.test(name)
+                        : name === "transcript_full.jsonl";
+                const files = [];
+                const listDirectory = fs.list;
+                if (source === "pi") {
+                    // Pi groups sessions into directories named after the project path.
+                    const munged = root.split("/").join("-");
+                    for (const name of listDirectory(scanRoot) ?? []) {
+                        if (!name.includes(munged))
+                            continue;
+                        const directory = join(scanRoot, name);
+                        if (fs.pathType?.(directory) !== "directory")
+                            continue;
+                        for (const file of listDirectory(directory) ?? [])
+                            if (file.endsWith(".jsonl") && fs.pathType?.(join(directory, file)) === "file")
+                                files.push(join(directory, file));
+                    }
+                }
+                else {
+                    const walk = (directory, depth) => {
+                        if (depth > 6)
+                            return;
+                        for (const name of listDirectory(directory) ?? []) {
+                            const absolute = join(directory, name);
+                            const type = fs.pathType?.(absolute);
+                            if (type === "directory")
+                                walk(absolute, depth + 1);
+                            else if (type === "file" && wanted(name))
+                                files.push(absolute);
+                        }
+                    };
+                    walk(scanRoot, 0);
+                }
+                files.sort();
+                const events = [];
+                for (const file of files) {
+                    const content = fs.read(file);
+                    if (source === "claude-code")
+                        events.push(...parseClaudeCodeTranscript(content));
+                    else if (source === "codex") {
+                        const parsedEvents = parseCodexSession(content, root);
+                        if (parsedEvents)
+                            events.push(...parsedEvents);
+                    }
+                    else if (source === "pi")
+                        events.push(...parsePiSession(content));
+                    else
+                        events.push(...parseGeminiTranscript(content));
+                }
+                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 merged = mergeImportedEvents(ledger, events);
+                fs.write(sidecarPath, serializeUsageSidecar(merged.ledger));
+                const result = {
+                    source,
+                    files: files.length,
+                    events: events.length,
+                    imported: merged.imported,
+                    skipped: merged.skipped,
+                };
+                return {
+                    exitCode: 0,
+                    output: summarizeImport(result) +
+                        (source === "gemini"
+                            ? "\nnote: Gemini transcripts do not record a working directory, so imports cannot be scoped to this project."
+                            : "") +
+                        `\nLedger: .aiw/${USAGE_SIDECAR_PATH} (rerun safely: already-imported events are skipped).`,
+                };
+            }
+            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)) : [];

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)