Finops Usage Extractor

finops-usage-extractor

Purpose

Read-only extraction of runtime token spend from local Claude Code session transcripts into the operator-local usage store defined by core/schemas/finops-usage-store-schema.md. It sums each session's exact message.usage token dimensions (input / output / cache-write with tier split / cache-read) plus tool-use request counts and the cost-determining service_tier, and normalizes them into a versioned JSONL derived cache. Exact source counts are authoritative; the context-budget-auditor skill's ceil(words/0.75) heuristic is the fallback for records that lack message.usage.

This skill measures runtime session spend — distinct from context-budget-auditor, which measures static corpus footprint. It reuses that skill's estimation method (the word→token fallback), not its scanner.

Scope

Four phases over one source (the local session store), one skill:

• Extraction + normalization (C1). extract-usage.sh parses local Claude Code session transcripts into the v1.2.0 store (meta / session / subagent record kinds; provider reserved-optional). Per the data-minimization control at v1.2.0, the session record persists worktree — the working-directory basename — and never the full absolute path. Exact message.usage counts are primary; the word→token heuristic is the usage-less fallback. v1.2.0 also adds five session-grain analysis sub-aggregates the intelligence layer slices on — by_skill / by_mcp / by_model / tool_calls / stop_reason — plus dimension_coverage. Each token-bearing map reuses the identical four-leaf session.tokens shape (so "which skill's cache-reads?" is answerable) and carries an always-present reserved "unknown" bucket holding the uncovered remainder, which is what makes Σ by_X.*.tokens == session.tokens hold even where the source population is partial. by_skill / by_mcp are best-effort and MUST be rendered with their dimension_coverage label; by_model / tool_calls / stop_reason are exact by construction and deliberately carry no coverage entry. by_model is a true per-turn partition that supersedes the dominant/last session.model for cost-splitting a mixed-model session; tool_calls (client-side invocations by name) is a distinct sibling of tool_use (server-side requests) and is never folded into it.
• Attribution + roll-up (C2). rollup-attribution.sh reads that store and writes the additive rollup + coverage records (record kinds introduced at v1.1.0): it resolves each session to its owning work item, rolls per-session spend up to that work item (honoring the summation invariant), and emits a run-level attribution-health coverage record. The session→work-item mapping ALGORITHM — the ordered LOCAL-ONLY resolver (issue-event key → release/chore branch → hub-state lineage → unattributed, plus an opt-in network PR-resolve) — lives in core/standards/finops-attribution-convention.md; the record SHAPES live in the store schema. Milestone-grain is reliable from local data alone; issue-grain is best-effort (a decision-event key, or the opt-in --resolve-prs resolve); everything unresolved lands in an explicit unattributed bucket, fail-visible. Reliable issue-grain and a hub-vs-spoke role split need a hub-emitted spawn-ledger marker, which the store's v1.2.0 analysis dimensions did NOT deliver — it remains an open enhancement on the Agent-FinOps parent epic, and until it lands neither is available. The v1.2.0 by_skill dimension is a weaker, best-effort substitute for the skill question only; it does not separate hub from spoke.
• Reporting + trends (C4). report-usage.sh reads that store and renders an operator-facing spend report over a date window — sliced by work item, worktree, skill, MCP server and model — plus a period-bucketed trend view. It writes nothing at all: the report prints to stdout, so no artifact exists that could be committed. Four rules are structural rather than conventional, and each is enforced at a single code site: (1) the windowed join — rollup rows are whole-store aggregates with no time bounds, so a windowed figure inverts rollup.session_ids[] into a session→work-item map, filters session records on started_utc and re-sums, rather than reading rollup.tokens; (2) coverage-label honesty — the coverage clause is concatenated into the section header in the one renderer both output shapes consume, so an unlabelled best-effort slice is unrepresentable, and the reserved "unknown" bucket renders as an explicit uncovered remainder rather than a dimension value; (3) provenance — the marker rides the numeral (12,340 exact, ~12,340 not), so it survives a paste that drops the tag column; (4) the trend-characterization gate — a direction is emitted only for an exact-grade dimension, because on a best-effort one a coverage change is not separable from a spend change. Availability is detected per field on the windowed records, never from meta.schema_version, and the "a roll-up has run" predicate is the presence of the coverage record. Full contract — the join algorithm, the rejected alternatives, the bucketing rules and the self-test map — in references/reporting-contract.md.
• Estimation (C3). estimate-usage.sh reads that store and produces a token-cost estimate for a PLANNED work item from historical comparables, with a stated basis and confidence. The store carries no work-item size / type / scope field, so every matcher is a join out of the store; the default join is LOCAL and in-repo — a rollup row keyed milestone:vX.Y joins release/releases/RELEASE_LOG.md's governed **Velocity:** field for (planned points, release class), so milestone-grain matching needs no network call. Issue-grain matching needs GitHub labels and is therefore opt-in (--resolve-labels), exactly as --resolve-prs is. The matching ladder is ordered and first-match-wins with a terminal fail-visible tier: E1 explicit (--like) → E2 class + points (default) → E3 pooled tokens-per-point rate → [opt-in] E-LBL issue labels → E4 DECLINE. Four rules are structural: (1) N_min = 3 is a HARD floor — below three comparables no estimate is emitted, because at n=2 the median is the mean (the outlier-robustness it was chosen for silently evaporates) and at n=1 dispersion is zero, so every confidence signal reads maximally tight; a decline is an answer, exit 0. (2) Median, never the mean — token spend is right-skewed; the mean renders only as a labelled not-used contrast so the skew stays visible. (3) Confidence is a total, ordered function of (n, rMAD), capped down by evidence quality (best-effort token fraction, admitted non-reproducible rows, the pooled-rate tier, the network tier) — the label itself moves, it is not merely annotated; the 0.25 / 0.50 band edges are reused from this skill's own coverage.health bands so the estimator and the roll-up speak one vocabulary. (4) $ fires only on the presence of a provider record, whose sole producer is the OFF-by-default connector that ships with no live endpoint — so volume is the only reachable mode today and the header says so, and the rate, when it exists, is derived from the record's own cost/token pair rather than any price table. --delta adds a leave-one-out re-derivation: rebuild a closed item's comparable set with that item excluded, run the identical estimator, and report estimate → actual with the signed delta and percentage error — zero writes, zero new records, zero schema surface. The roll-up-has-run predicate is the presence of the coverage record, never meta.schema_version. The band→telemetry cutover this phase feeds is governed at quota-budget-protocol.md § 5.1, with the substrate decision at ADR-102.

Usage

bash core/skills/finops-usage-extractor/scripts/extract-usage.sh [--rebuild | --incremental] [--self-test]

• --rebuild (DEFAULT): truncate + rewrite the entire store from source (idempotent by construction — deterministic record order, byte-identical across runs over unchanged source; atomic tmp-then-mv).
• --incremental (opt-in): mtime-gated optimization — upsert only sessions whose transcript changed since the last extraction; one record per session_id, newest-wins.
• --self-test: run the built-in assertions (heuristic estimator, cache-tier invariant, idempotence, the value oracle, and the v1.2.0 analysis-dimension invariants — reserved-bucket presence, Σ by_X.*.tokens == session.tokens, Σ stop_reason.* == turns, and the dimension_coverage projection) against the synthetic fixtures in test-fixtures/ — no source or store access required.

The optional plan-gated provider connector (scripts/provider-usage-connector.sh) is OFF by default and never on the critical path — extraction completes fully from local session data alone.

Roll-up + attribution (run after extraction):

bash core/skills/finops-usage-extractor/scripts/rollup-attribution.sh [--emit] [--resolve-prs] [--self-test]

• --emit (DEFAULT): resolve every session to its work item and write the rollup + coverage records into the store (strip any prior ones, append fresh, bump meta.schema_version to 1.2.0). LOCAL-ONLY — no network, no gh. A store predating v1.2.0 (session records carrying cwd, not worktree) is refused with exit 3 naming the rebuild command, rather than silently rolled up into an empty result. Idempotent over an unchanged store (byte-identical body modulo the rolled_up_utc metadata); session/subagent lines untouched.
• --resolve-prs (OPT-IN): additionally resolve fix/* / feat/* branches via a read-only gh PR→closing-issue query (network; non-reproducible). Absent → those sessions degrade to unattributed. Every resulting row is stamped attribution_tier: pr-resolved + reproducible: false.
• --self-test: run the ground-truth labeled-fixture attribution check (CIAC-1 primary), the conservation identity (secondary), coverage + health, multi-branch bucketing, idempotence, and the pre-v1.2.0 store-shape preflight (a legacy cwd-carrying store must be refused with exit 3) against the synthetic test-fixtures/rollup/ set — no operator-store or network access.

Reporting + trends (run after extraction, and after roll-up for the work-item slice):

bash core/skills/finops-usage-extractor/scripts/report-usage.sh [--window N[d] | --since YYYY-MM-DD --until YYYY-MM-DD] [--by work-item|worktree|skill|mcp|model|all] [--trend] [--period day|week|month] [--json] [--self-test]

• --window N[d] (DEFAULT 30): the last N calendar days, inclusive of today. Mutually exclusive with --since / --until.
• --since / --until YYYY-MM-DD: the absolute window a retro or quarter close needs; both bounds are inclusive of the named day. Bucketed on session.started_utc (UTC).
• --by (DEFAULT all): the slice dimension. work-item, worktree and model are exact; skill and mcp are best-effort and always render their coverage label. There is deliberately no project dimension — the store carries no PMO-project field, and --by project exits 2 saying so. worktree is the session's working-directory basename: a filesystem directory name, NOT a PMO project.
• --trend / --period (DEFAULT week): the period-bucketed view. Weeks are Monday-start UTC weeks labelled by start date; the bucket set is dense, so an empty period renders as an explicit row rather than being omitted, and the period containing today renders tagged (partial …). Both are shown and both are excluded from trend direction. A boundary-spanning session is assigned wholly to its started_utc bucket — no proration. Direction requires ≥3 non-empty complete periods; below that the table renders and the characterization is withheld. A dimension absent from every session in the window is gated, not zeroed: it renders available: false with its reason and an empty row set — so an exactness tag is unrepresentable rather than merely forbidden — and a non-empty period whose sessions all lack the field renders measurable: false / figure "—". 0 [SOURCE: exact message.usage] would make "we cannot measure this" indistinguishable from "we measured zero". The gate reuses the same predicate the slice sections use, so the two surfaces cannot drift.
• --json: the machine shape. Coverage, grade and provenance are sibling required keys on the same objects the markdown path renders — there is no second emit path that could drop them.
• --self-test: run the built-in assertions against the synthetic test-fixtures/report/ set — no operator-store or network access. Every assertion fails closed: a render that aborts or emits nothing is a FAIL, and each negative assertion carries a positive control so an empty search space cannot read as a pass. Assertion map in references/reporting-contract.md §8.
• An aborted render never exits 0. The renderer's status is captured, so a jq abort (a truncated store line, a malformed tokens value, a malformed session.started_utc) exits 3 with a named FATAL on stderr, and a zero status with empty stdout is fatal too. rc=0 + empty stdout is byte-identical to the empty-window answer — and the empty-window answer is a full report saying so, never silence.

Estimation (run after extraction and roll-up — the comparable set is built from rollup rows):

bash core/skills/finops-usage-extractor/scripts/estimate-usage.sh [--class C --points N | --size XS|S|M|L|XL | --like WI[,WI...]] [--type T] [--tolerance N] [--include-nonreproducible] [--resolve-labels] [--delta WI] [--json] [--verbose] [--self-test]

• --class C + --points N (the default path): match milestone-grain comparables on (release class, planned points ± tolerance), read from the release log's **Velocity:** field. LOCAL — no network.
• --size XS|S|M|L|XL: translated through the canonical point scale (XS=1 / S=2 / M=4 / L=8 / XL=16), which is cited by role from bundle-composition-doctrine.md § 3 Step 5, never redefined here. Mutually exclusive with --points. An out-of-set size is a source-integrity violation → exit 2, never coerced to a nearest bucket.
• --like WI,…: name the comparables explicitly (tier E1). The one path that works against a thin store on day one, and deterministic. Mutually exclusive with --class / --points / --size.
• --tolerance N (DEFAULT max(2, round(0.5 × points))): the points-band half-width. The floor of 2 is the point value of size:S, so the band is never narrower than one bucket step; the proportional half-width bands a 4-pt item and a 20-pt release equally well, which a fixed ±N does not. [RECOMMENDED], printed inline.
• --include-nonreproducible: admit pr-resolved comparables (excluded by default). Caps confidence at LOW and stamps the whole output reproducible: false — a non-reproducible figure must never be read as a stable calibration datum.
• --resolve-labels (OPT-IN / NETWORK / non-reproducible): resolve issue-grain size: / type: labels via gh. Off by default, exactly as --resolve-prs is; caps confidence at LOW. A gh failure degrades to the local path rather than fabricating a thinner-but-plausible population.
• --delta WI: leave-one-out re-derivation for a closed work item already in the store — rebuild its own comparable set with it excluded, run the identical estimator, and report estimate → actual, the signed delta, the percentage error, and the estimate's basis + confidence. Writes nothing; the store is a derived cache and the estimator a pure function of it, so the counterfactual is exactly reproducible. This is the instrument that measures the estimator's accuracy (as opposed to its self-consistency) and the one that calibrates quota-budget-protocol.md § 5.1's cutover predicate. Two hard preconditions, both fail-closed: (1) the target must carry a rollup row (its measured actual) — a target with no rollup row, the default for any work item predating the store's coverage window, is refused with exit 3 on stderr and renders nothing, never an unrequested forward estimate under prose asserting a back-test ran; and (2) when the point estimate is suppressed (below N_min, or above the rMAD ceiling) the signed delta and % error are suppressed with it, because either one recovers the withheld figure from actual in a single arithmetic step (estimate = actual + delta). A figure the estimator explicitly declined to emit must not be recoverable by arithmetic from the same output.
• --verbose: additionally list every excluded row with its named exclusion reason, so an unexpectedly thin population is diagnosable rather than mysterious.
• --json: the machine shape. Basis rows and the confidence label are produced by the same functions the markdown path uses, so an estimate without its basis is unrepresentable in either surface.
• --self-test: run the built-in assertions against the synthetic test-fixtures/estimate/ set — no operator-store or network access. Every assertion fails closed, and each negative carries a positive control (the coverage-gate check pins meta.schema_version to 1.2.0 on purpose, so a version-based gate could not pass it).

Dependencies

• jq (REQUIRED) — the extractor parses session JSONL with jq throughout. Missing jq is a hard preflight failure (exit 5). Note: context-budget-auditor is pure-bash; jq is a genuinely new runtime dependency here, hence the explicit declaration + preflight.
• git (REQUIRED) — the fail-closed store guard uses git check-ignore to refuse writing a store path that is inside a repository but not git-ignored. Missing git fails the same preflight (exit 5).
• bash — bash-3.2-safe integer arithmetic (the reused context-budget-auditor heuristic is already bash-3.2-safe).

Read-only posture

The extractor never writes to ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/projects (the source transcripts). It writes exactly one path: <resolved-store>/usage.jsonl (via an atomic usage.jsonl.tmp → mv). The store path resolves from config (operator.toml [paths].operator_instance_finops_store_path, default ${CLAUDE_WORKSPACE_ROOT}/pmo-instance/finops) — no hardcoded operator path.

The reporting phase writes nothing at all — it reads the resolved store and prints to stdout. The estimation phase writes nothing at all either — it reads the resolved store and the in-repo release log and prints to stdout; --delta persists no estimate record, because the leave-one-out re-derivation obtains the same comparison from a pure function of the existing store. Read-only on the source transcripts and on the store. That is a deliberate data-hygiene posture, not an omission: with no output file there is no artifact that could be accidentally staged and committed. For the same reason the report never prints the resolved store path value (an operator home path) — only the resolution chain, which is what makes a figure reproducible.

Exit codes

Domain-Specific Failure Modes

Double-counting sidechain subagents — PROC

• Signature (observable signal): a work-item or session total that is visibly inflated — the store's session.tokens plus the session's subagent.tokens both counted, so a roll-up reads roughly double the true spend for any session that has sidechains.
• Conditional: do NOT add subagent.tokens on top of session.tokens when computing a session or work-item total, because session.tokens is already the whole-file total (inclusive of every in-transcript sidechain) and subagent records are a drill-down, not an additional summand.
• Root cause: the two record kinds look additive (both carry a tokens object of the same shape), so a summation that filters .record=="session" or .record=="subagent" silently double-counts sidechain spend.
• Mitigation: sum session.tokens ONLY (the four leaf integers input + output + cache_creation.total + cache_read); treat subagent records purely as an attribution drill-down. The schema's summation invariant states this; the --self-test idempotence check guards the per-session digest.
• Principal response vs. junior response: a principal reads the schema's summation invariant before writing any aggregation and encodes "session-only" once; a junior writes an intuitive select(.record=="session" or .record=="subagent") sum and ships a doubled total that only surfaces on sessions that happen to have sidechains.

Dropping legacy null-gitBranch sessions — INPUT

• Signature (observable signal): the store's session count is lower than the source session-file count, and older sessions are silently absent — total spend under-reports because pre-attribution sessions were skipped.
• Conditional: do NOT skip or discard a session record when its git_branch is null, because a null branch is a legacy pre-field-introduction session whose spend is still real and must land in the store (attribution to a work item is C2's unattributed bucket, not a C1 drop condition).
• Root cause: conflating "cannot attribute to a work item" (a C2 concern) with "cannot extract" (a C1 concern) — the extractor treats a missing attribution key as a reason to skip rather than capturing null and deferring attribution.
• Mitigation: capture git_branch: null where the source lacks it; extract the session's tokens regardless; leave attribution entirely to C2. Never gate extraction on the presence of an attribution surface.
• Principal response vs. junior response: a principal separates extraction from attribution by contract and captures null fail-visibly; a junior filters select(.gitBranch!=null) at read time and silently loses every legacy session's spend.

Presenting heuristic figures as exact — OUT

• Signature (observable signal): a downstream cost figure carries no provenance, so a ±25% heuristic estimate is indistinguishable from an exact provider count in the store and in any report built on it.
• Conditional: do NOT emit a session/subagent record without setting token_source (and heuristic_turns) when any turn was estimated via the fallback, because a consumer cannot otherwise exclude or flag heuristic-derived totals and will treat an approximation as an exact cost.
• Root cause: the fallback estimator produces integers in the same fields as the exact path, so without an explicit provenance flag the two are byte-identical downstream.
• Mitigation: always set token_source to exact / heuristic / mixed and record heuristic_turns; the fallback fires only for records lacking message.usage, and exact source counts are always primary when present.
• Principal response vs. junior response: a principal makes provenance a first-class field so a consumer can exclude heuristic totals; a junior lets the fallback fill the same fields silently and ships a store where approximate and exact cost cannot be told apart.

Mis-parsing a harness-auto branch as a work item — INPUT

• Signature (observable signal): a rollup row books real spend to a milestone:* or #N the session never worked on, because a harness-auto claude/<adjective-noun> / agent-* branch name was force-parsed into a work item.
• Conditional: do NOT parse a git_branch into a work item unless it matches a reliable release-branch form — the slug-primary release/<milestone-slug> (T2s) or the version-form release/vX.Y-* / chore/vX.Y-* prefix (T2) — or the opt-in fix/* / feat/* PR path (T-PR), because a harness-auto worktree branch is an adjective-noun-hash with no work-item content, and coercing it fabricates an attribution. A slug-keyed chore/<slug>-<suffix> is NOT parseable either: no delimiter separates the slug from the stage suffix, so a parse there manufactures a key rather than reading one, and it correctly lands in unattributed.
• Root cause: conflating "the session has a branch" with "the branch names a work item" — the harness auto-branch class carries no work-item signal at all. The mirror-image error is treating one spelling of a real work-item branch as the only one: run keys have been slug-primary since ADR-092, so a predicate written for the version form alone drops the branch every content spoke actually builds on.
• Mitigation: only the T2 / T2s / T-PR forms parse from the branch string, and the slug arm is restricted to release/ and ordered strictly BELOW the hub-state tier so a parsed guess can never override an authored key; the issue-event key (T1) and hub-state lineage (T3) resolve from local hub-state instead; everything else → unattributed with the reason recorded in attribution_basis.
• Principal response vs. junior response: a principal enumerates the branch classes (per git-workflow.md) and parses only the ones that encode a work item; a junior regexes a version out of any branch and silently mis-attributes every auto-worktree session.

Silently collapsing a branch-switching session onto one branch — PROC

• Signature (observable signal): a session that spanned two branches (e.g. release/vX.Y-a then fix/b) has its ENTIRE token total booked to one milestone, over-crediting that work item and starving the other.
• Conditional: do NOT run a session through the branch tiers when branch_switch == true, because the store collapses git_branch to a single value and attributing the whole session to it mis-allocates the spend that belonged to the other branch(es).
• Root cause: the single-valued session.git_branch hides that the source records spanned multiple branches; a resolver reading only the collapsed value cannot see the switch.
• Mitigation: the multi-branch guard sits ABOVE the resolver — branch_switch == true routes the session to a distinct multi-branch bucket carrying git_branches[], never to a single milestone; coverage.multi_branch_token_fraction surfaces the volume for review.
• Principal response vs. junior response: a principal treats branch attribution as unsafe whenever the branch is not single-valued and buckets it honestly; a junior attributes to whichever branch the extractor happened to keep.

Presenting heuristic / network-derived attribution as authoritative — OUT

• Signature (observable signal): a downstream report cannot tell a deterministic branch-milestone attribution from a fuzzy issue-event-keyed one or a non-reproducible pr-resolved one, so a best-effort guess is consumed as ground truth.
• Conditional: do NOT emit a rollup row without its attribution_tier and reproducible provenance, and do NOT put the --resolve-prs network resolve on a path that must be reproducible, because a network PR-resolve is time-varying and a fuzzy event-key match is not id-equality — a consumer must be able to weight or exclude them.
• Root cause: every tier produces a #N / milestone:* in the same field, so without an explicit provenance tag a strong and a weak attribution are byte-identical downstream.
• Mitigation: every row carries attribution_tier (the 5-value enum) and reproducible; the default path is LOCAL-ONLY and reproducible; pr-resolved rows are reproducible: false and recorded in coverage.pr_resolved_present; the health threshold + tier_distribution let the downstream calibration slice tune the mix.
• Principal response vs. junior response: a principal makes provenance first-class so a consumer can exclude weak tiers; a junior ships a roll-up where a deterministic milestone and a network-guessed issue look identical.

Rendering a best-effort dimension without its coverage label — OUT

• Signature (observable signal): a by-skill or by-MCP spend slice reads as a complete census — the rows sum to a plausible total and carry no caveat — so a planning or efficiency decision is made on a fraction of the corpus believed to be all of it.
• Conditional: do NOT render a by_skill / by_mcp slice without its dimension_coverage entry, because those dimensions are partially populated by construction (the source attributes only some turns), and an unlabelled slice is indistinguishable from an exact one.
• Root cause: a best-effort sub-aggregate and an exact one are byte-identical in shape — same {turns, tokens} wrapper, same four leaves — so partiality is invisible to a renderer unless a separate field carries it. The reserved "unknown" bucket keeps the arithmetic honest but says nothing about confidence; a renderer that drops the "unknown" row (as a "not a real skill" filter reasonably might) removes the only in-band signal.
• Mitigation: session.dimension_coverage is a stored projection carried per session, present for exactly the two best-effort dimensions and deliberately absent for the exact three; the always-present "unknown" bucket preserves Σ by_X.*.tokens == session.tokens; the extractor --self-test asserts label-and-bucket agree. When a slice aggregates several sessions, the label must aggregate with it — a per-session fraction collapsed to one unlabelled number is the same defect one level up.
• Principal response vs. junior response: a principal treats the coverage label as part of the datum and refuses to emit the slice without it; a junior renders the map because it is well-formed, and reports 17% of the spend as if it were 100%.

Folding a client-side tool count into the frozen server-side tool_use — PROC

• Signature (observable signal): tool_use.web_search_requests climbs far above the provider's billed search count, or a consumer pinned to the v1.0.0 tool_use shape starts reading unexpected keys — the two tool dimensions have been merged into one field.
• Conditional: do NOT extend or nest the new tool_calls map inside tool_use when adding the client-side tool dimension, because tool_use is a frozen v1.0.0 field with a fixed two-key shape sourced from message.usage.server_tool_use, and reshaping it is a breaking frozen-kind change that the v1.2.0 versioning exemption does not cover (that exemption is claimed for exactly one field replacement, and is re-tested from scratch per change).
• Root cause: the names read as synonyms — both are "tools" — but they count different events from different sources: tool_use counts server-side requests the provider bills for; tool_calls counts client-side invocations by name from the turn content. Summing or nesting them produces a number that answers neither question.
• Mitigation: tool_calls ships as a new sibling field, never an extension; the schema's field notes state the distinction adjacently so the next author meets it at the point of temptation; CIAC-1's byte-unchanged predicate over the frozen kinds is the gate that catches a fold at review time.
• Principal response vs. junior response: a principal checks which record kinds are frozen and what the live exemption actually covers before touching an adjacent field, and pays one new field for it; a junior sees a tool_use object already present, nests the map inside it "to keep tools together", and silently breaks every pinned consumer plus the versioning claim.

Reading rollup.tokens for a date window — PROC

• Signature (observable signal): every window reports the same total regardless of --since / --until — a one-week report and a one-year report agree to the token, and the figures match the store's lifetime spend.
• Conditional: do NOT read rollup.tokens (or rollup.session_count) to answer a date-range question, because rollup rows are whole-store aggregates carrying no time bounds — their only timestamp, rolled_up_utc, is the roll-up computation time and is identical across every row of one run, so filtering on it is all-or-nothing rather than a window.
• Root cause: the rollup record looks like the answer — it is already grouped by work item and already carries a tokens object — so the shape invites a select(.record=="rollup") + date filter that has nothing to filter on. The time anchor lives one record kind away, on session.started_utc.
• Mitigation: invert rollup.session_ids[] into a session_id → {work_item, work_item_kind, attribution_tier, reproducible} map, filter session records on started_utc, and re-sum over the filtered set; the provenance travels through the join unchanged, and a windowed session absent from every rollup row lands in an explicit (not-rolled-up) bucket rather than being dropped. The self-test reconciles Σ rendered rows against Σ session.tokens over the window.
• Principal response vs. junior response: a principal checks which record kind carries a data timestamp before designing the window and finds rollup has none; a junior groups by the record that is already grouped, ships a report whose window control does nothing, and the error is invisible because every number is individually correct.

Rendering a best-effort slice without its coverage label — OUT

• Signature (observable signal): a by-skill or by-MCP table read as the complete skill breakdown — the rows sum to a plausible total, carry no caveat, and a planning or efficiency decision is made on a fraction of the spend believed to be all of it.
• Conditional: do NOT emit a by_skill / by_mcp slice without its dimension_coverage indicator, because those dimensions are partially populated by construction and an unlabelled partial slice mis-attributes the whole window's spend to whichever skills happened to be captured.
• Root cause: a best-effort sub-aggregate and an exact one are byte-identical in shape, so partiality is invisible to a renderer unless a separate field carries it — and a label emitted as a second statement after the header is one refactor away from being dropped, because nothing structurally binds the two.
• Mitigation: the coverage clause is concatenated into the section-header string inside a single section_header function, called from a single emit_dim_table that both the markdown and the JSON path consume — so a best-effort header without coverage: is unrepresentable, not merely forbidden. An absent coverage field renders unknown (coverage field absent — treat as 0% verified), never 100% and never nothing; per-period trend rows carry that period's coverage, since a whole-window figure would hide period-to-period capture drift.
• Principal response vs. junior response: a principal makes the label structurally inseparable from the figure and proves it with a test that counts best-effort headers and fails when the count of labelled ones differs; a junior adds a caveat line under the table, and the next person who reorders the emitter ships an unlabelled census.

Characterizing a trend over a partially-populated dimension — OUT

• Signature (observable signal): a confident claim like "skill X's spend tripled" when what actually tripled was the capture rate — the underlying dimension was populated on 10% of sessions in the first period and 30% in the last.
• Conditional: do NOT emit a direction, arrow or percentage delta for a best-effort dimension, because a change in coverage is not separable from a change in spend without a coverage-stable baseline that the source does not provide.
• Root cause: a per-period series is arithmetically well-formed whether or not the population behind it is stable, so the trend math succeeds silently; the invalidity lives in the sampling, which the numbers do not expose.
• Mitigation: the trend gate keys on the same registry entry that drives the coverage label — direction is emitted only where grade == "exact", so a direction claim and a completeness claim share one enforcement point and there is no threshold to mis-tune. Best-effort dimensions render per-period volume and per-period coverage, plus an explicit COVERAGE-DRIFT note when the spread exceeds the [RECOMMENDED] 10-percentage-point band, so the coverage jump sits on the same line as the volume jump.
• Principal response vs. junior response: a principal asks what the denominator did before reading the numerator and withholds the claim the data cannot support; a junior computes a delta because the series is there, and reports a capture-rate artifact as a spend trend.

Rendering an unmeasurable dimension as a measured zero — OUT

• Signature (observable signal): a slice or trend table of clean 0s carrying [SOURCE: exact message.usage] — the tool's strongest provenance claim — for a dimension the store does not contain at all. The operator reads "we spent nothing on MCP servers" from a store that simply never captured MCP attribution.
• Conditional: do NOT render a figure — least of all a provenanced 0 — for a dimension absent from every record in the window, because summing an absent field yields 0 with no error and no exit code, so "we cannot measure this" and "we measured zero" become the same output.
• Root cause: absence and zero are the same value after aggregation. [] | add // 0 is 0, and the provenance tag is computed from the session's turn counts, which are exact regardless of whether the dimension exists — so the strongest possible tag rides the weakest possible datum. The defect is invisible in review because the table looks perfectly well-formed.
• Mitigation: an availability gate (unavail()), applied at both grains — whole dimension and single period — and shared by the slice and trend renderers so the two surfaces cannot drift on what "present" means. When it fires the row set is emptied rather than zero-filled, which makes an exactness tag unrepresentable rather than merely forbidden; the reason is rendered in its place. The self-test asserts it against a fixture that deliberately carries sessions but zero carriers of the field, and pairs it with a positive leg proving a present dimension still renders — a gate that suppresses everything is not a gate.
• Principal response vs. junior response: a principal asks whether the denominator exists before reporting the numerator, and distinguishes no data from no spend in the artifact itself; a junior ships the zero because the query returned one, and the operator budgets against a dimension that was never captured.

Disclosing a suppressed figure through its derived fields — OUT

• Signature (observable signal): an output that says (suppressed) where the estimate should be, and one line later prints a signed delta and a percentage error against a known actual — so the withheld figure

…(truncated)