crickets token audit - alexherrero/crickets GitHub Wiki
Note
LAUNCHED (lifted 2026-06-24, AG Phase 3; originally approved 2026-06-23) ยท locked 2026-06-28 (final AG design sweep). child-design โ the token-audit capability (token-cost measurement + live metering โ the measurement slice of the efficient opinion). status: launched (lifted into tracked wiki/designs/ 2026-06-24, AG Phase 3). Points up at the crickets HLD.
token-audit measures what a session costs โ a deterministic cost breakdown after the fact and a live status-line meter during. It is the measurement half of the efficient opinion: the opinion sets the budget and the quality floor; this capability supplies the cost truth that budget is weighed against. It declares [token-audit] (โ [tokens] at v6.0).
The primitives, all delivered (+ one fold):
| Primitive | Kind | What it does |
|---|---|---|
/token-audit |
command | The cost breakdown โ reads the session JSONL, splits cached vs fresh, rolls up 5-hour windows, prices each. |
analyzer.py |
script | The streaming JSONL cost reader โ cache split, window roll-up, the always-load floor. |
pricing.py |
script | One pinned source of model rates โ the only place a price lives. |
status_line_meter.py |
script | The live status-line meter (folded in from status-line-meter). |
A deterministic cost analyzer (cache-split ยท 5-hour windows ยท the always-load floor) behind both the on-demand /token-audit breakdown and the passive live meter; pricing.py is the one pinned rate source. Designed (grey): on session-stop the analyzer auto-logs a per-model session-cost record to memory, which the dreaming pass reviews to surface an efficiency trend. It supplies the cost truth the efficient opinion weighs its budget against.
analyzer.py reads the session JSONL and computes cost mechanically โ no model in the loop. It splits cached vs fresh input (the cache discount is the dominant lever in the token-discipline routing), rolls usage into the 5-hour billing windows the plan caps on, and accounts for the always-loaded context floor. Same transcript โ same number, every run. pricing.py is the single pinned source of per-model rates, so a rate change touches one file.
/token-audit is the after-the-fact breakdown (where the tokens went, which window, cache hit-rate); status_line_meter.py is the live meter that keeps the current burn in view during a session. Both read the same analyzer: the meter is that one measurement, surfaced live during the session.
Today model-effort-routing's tier chart carries both the abstract policy (tier ร effort) and concrete model-id strings per host, bolted into one wiki table โ two things with different change cadences. This design specifies pulling the concrete half out into a versioned data file here, alongside pricing.py โ the same one-pinned-source shape, and the natural home: a routing decision and its price are read off the same transcript in the same breath, so they should never be able to disagree about how a model's name is spelled. model-effort-routing keeps the tier scale + effort ladder only; this file becomes the single place a current model id lives.
Rows are keyed by work-type (a superset of persona โ it also covers ad-hoc dispatch roles that carry no persona manifest at all: a /plan explorer, a /review adversarial or cross-model reviewer, a documenter, a verification clerk), each resolving to (tier, model-id, effort). Seeded from the Phase-R evidence: Sonnet 5 high validated for staging/tech-lead authoring and for T2-Author work that's transcription-shaped (the design reasoning is already settled elsewhere; the session is careful transcription + sequencing); Sonnet 5 medium for wiki/mechanical-plus work (gate-checked, no planning split needed). T2 ยท Author itself splits rather than resolving to one model: roadmap/architecture calls route to Opus 4.8, high; transcription-shaped authoring routes to Sonnet 5, high. The table's work-type granularity catches variance a single-tier-per-persona map can't express โ T1 Execute, for instance, covers both a heavy opusplan build stretch and flat-Sonnet mechanical-plus work, same tier, different concrete instantiation.
Two consumers read the table by name, one-way, never re-deriving it: crickets development-lifecycle's dispatch points (routing) and this capability's own routing-conformance report, below (measurement). Kept current by content-refresh, in the same pass as pricing.py โ a model release re-pins both files' id strings together, since they must never disagree about what a given string means.
The table, seeded (Phase-R evidence + the live pricing.py roster):
| Work-type | Tier | Model id | Effort |
|---|---|---|---|
| Research ยท adversarial audit | T4 ยท Deep | claude-opus-4-8 |
max (+ ultracode orchestration) |
| Roadmap ยท architecture ยท priority/board calls | T3 ยท Architect | claude-opus-4-8 |
max |
| T2-Author โ roadmap/architecture-shaped authoring | T2 ยท Author | claude-opus-4-8 |
high |
| T2-Author โ transcription-shaped authoring (staging, tech-lead) | T2 ยท Author | claude-sonnet-5 |
high |
Worker build (/work, /bugfix โ the autonomous stretch) |
T1 ยท Execute |
opusplan (plans on claude-opus-4-8, executes on claude-sonnet-5) |
medium |
| Wiki / mechanical-plus (gate-checked, no planning split) | T1 ยท Execute | claude-sonnet-5 |
medium |
| Mechanical edits ยท log-scraping ยท deterministic passes | T0 ยท Mechanical |
claude-sonnet-5 (or claude-haiku-4-5 for the most rote cases) |
low |
| (recognized, not routed) | โ | claude-fable-5 |
โ |
claude-fable-5 is a real, pinned model id (pricing.py, ~2ร Opus's per-MTok rate โ the single most expensive row in the table) that no work-type resolves to today; PROMPTS-NEXT.md's own standing rule for this program is "Fable is not used anywhere in this pack." It is named here explicitly, not omitted, for one reason: an INHERITED announcement (development-lifecycle's mandatory fan-out contract, below) that shows claude-fable-5 is then instantly recognizable as the Mythos failure shape โ silent inheritance of the most expensive model at fan-out scale โ sparing the operator a name lookup mid-incident.
Already-fired, not hypothetical: the agent-def frontmatter on worker.md / researcher.md / tech-lead.md still pins claude-sonnet-4-6, and every command's nudge text still names claude-sonnet-4-6 / claude-opus-4-8 โ both stale relative to pricing.py's claude-sonnet-5 row, added one day earlier in the same R0.7 repair pass. This is the content-refresh trigger this design already names, caught live rather than waited-for; PLAN-efficiency-automation should carry the roster bump as a concrete task, not just cite it as a future risk.
The table is only useful if something deterministic decides which row applies. classify_work_type is a small function, hosted alongside the table, that a dispatch point or a staging step calls to get back a work-type key (never a model โ that's the table's job, one step later):
-
Persona-bound dispatch. The sub-agent's agent-def already declares a tier (its
model:/effort:frontmatter, generalized per model-effort-routing'stier:axis). No classification needed โ the declaration is the answer. -
Ad-hoc dispatch role. Match the role name against the table's work-type keys (
explorer,adversarial-reviewer,cross-model-reviewer,documenter,verification-clerk, and the session-shaped keys above) โ an exact-match lookup, not a model making a judgment call. -
No match. Resolve to an explicit
UNCLASSIFIED-DEFAULTtier source โ never a silent fallback โ at a fixed safe default (T1 ยท Execute,claude-sonnet-5, medium; neverclaude-fable-5, never session-inherited). The mandatory fan-out announcement (development-lifecycle) namesUNCLASSIFIED-DEFAULTas its own tier-source value, distinct from table row / frontmatter /INHERITED, so a classification gap stays visible instead of being quietly absorbed into "it just worked."
The same function derives a staged plan's per-task tier hint at authoring time and powers the session-start suggestion to the operator โ one classifier, three call sites (sub-agent dispatch, plan staging, session-start nudge), never three copies of the same judgment.
Named honestly as a discoverability cost: an operator reading model-effort-routing's design now sees the tier structure but not which model is actually running for a given work-type โ they have to follow the pointer here. Mitigated by cross-linking both directions (References, below), not eliminated. The Claude-side table is the one built first; Gemini/Antigravity rows lag until that side of the portfolio needs its own consumption path โ named honestly, not claimed as symmetric on day one.
token-audit engages at four altitudes โ two delivered, two designed:
-
Passive (live) โ
status_line_meter.pykeeps the current burn in view throughout a session; nobody invokes it, it is always on. -
On-demand โ
/token-auditis operator-invoked: the detailed after-the-fact breakdown, run when you want to see where the tokens went. -
Ambient capture โ retargeted onto the observability ledger, 2026-07-07 (
PLAN-observability-ledger, Autonomy arc AA3) โ on session-stop, thesession-cost-captureStop hook (src/tokens/hooks/session-cost-capture/) runssession_cost_writer.pyover the closing transcript and appends onesession-costtelemetry event per model to a device-local, monthly-rotated JSONL event log (~/.agentm/telemetry/events-YYYYMM.jsonl,$AGENTM_TELEMETRY_DIR-overridable), tagged with{plan, task, arc, grade}attribution stamped from the worktree-local.harness/active-planmarker. Graceful no-op with an unwritable telemetry path โ never blocks session close.session_cost_reader.pyreads the log back for the pre-flight fan-out cost gate below, which now runs against real data instead of its fallback profile. No vault write survives this capability โ the priorkind: session-costmarkdown write via agentm'ssave_entry()bridge is retired, not duplicated; see the Autonomy arc's observability ledger and console design this move implements. -
Periodic review (designed, still gated) โ the memory engine's dreaming pass (its periodic reflection / consolidation cycle) reviews the accumulated
session-costrecords to surface an efficiency trend โ flagging when token use creeps up over time. This turns token-audit from a point-in-time lookup into a longitudinal signal on theefficientopinion, but it cannot build before the dreaming pass itself does. A correctly-gated stub shipped 2026-07-07 alongside the capture half (dreaming_trend_stub.py) โdreaming_pass_available()is hard-False, soreview_efficiency_trend()always returns a clean no-op; the trend-analysis logic itself stays[PENDING-IMPL], gated on Wave E's dreaming pass.
Four additions realize the operator's efficiency protocol (proven manually in the Mythos readiness run โ mythos-readiness-handoff/PROMPTS.md + PROMPTS-NEXT.md, now in the agentm vault project's completed/) as capability, not hand-discipline:
-
Budget readout on the status line.
status_line_meter.pyalready renders a per-session cost badge; this adds a 5-hour-window sum and a weekly sum against an operator-configured budget ceiling, degrading the same way the existing badge does โ missing config omits the readout, never an error. -
Pre-flight fan-out cost gate. Before any multi-agent dispatch, estimate spend = agent-count ร observed per-agent cost (drawn from this capability's own
session-costrecords viaanalyzer.py), compared against a configured share of the remaining 5h-window or weekly budget. Below threshold: proceed silently. Above it: confirm-or-block, and the output always states model ร agent-count ร estimated cost, so the spend is visible before it happens โ the direct fix for the Mythos failure mode (a 112-agent fleet that exhausted the session limit mid-run with no pre-flight estimate in front of the operator). Stated honestly: this is local, deterministic accounting from transcripts โ hooks cannot read Anthropic's actual remaining quota, so the gate estimates, it never guarantees. Advisory-only in unattended runs (2026-07-07 ruling, agentm-autonomy): confirm-or-block stays for interactive sessions where a human is present to answer; an unattended run gets announce-and-proceed โ the estimate is logged as a ledger event, never blocking. The subscription window's own rate limit is the accepted backstop for an unattended runaway, not this gate. -
/handoffcommand (as-built). Generalizes the MythosPROMPTS.mdpattern: snapshots an expensive session's outputs into a vault handoff directory alongside paste-ready prompts. Each prompt carries a machine-readable tier/model label alongside the hand-authored annotation, which lets a downstream consumer (including the/workescalation tripwire development-lifecycle's amendment adds) write entries in the same format instead of inventing its own. Since tokens 0.7.0 the command also offers each prompt as a one-click background-task chip where the host exposes one, so the handoff costs the operator a click rather than an open-a-session-and-paste; a host without a chip surface skips that step silently and keepsPROMPTS.mdas the fallback. A snapshotted note lands as akind: handoff-artifactrecord whatever it was, withprompts.json'ssnapshot_kindsnaming the original (tokens 0.8.1), so a copied tracker never reads as a second live head. The copy also dropsaliases:andslug:(tokens 0.8.2), so it never answers to the names of the note it copies. -
Routing-conformance report. A new section in
/token-auditoutput: a post-hoc read of model-used vs. work-type against this capability's own versioned table (above), plus a count of announcement-rule violations โ dispatches with no announced model โ cross-referencing the mandatory fan-out announcement development-lifecycle's amendment adds at the dispatch site.
PLAN-efficiency-automation stages the build; the fan-out gate and /handoff have since shipped from it, and the budget readout and routing-conformance report remain [PENDING-IMPL].
token-audit is the measurement half of efficient. The opinion is the judgment โ cheap as the job allows, above the quality floor; this capability is the deterministic cost truth that judgment needs to be real and not a vibe. The automation layer above (the fan-out gate, the conformance report) is more of the same arrow, not a new one: it makes the efficient judgment enforceable at the point of dispatch instead of only visible after the fact. The arrow stays one-way: efficient (and the model-routing discipline it backs) cites this capability's numbers; the capability never reaches up into the opinion. (Hardwired today; requesting efficient by name is the Phase-3/4 registry work โ the Opinions design.)
-
standalone โ
requires: []; ships alone. -
serves the
efficientopinion (agentm Opinions) โ the measurement slice; the budget + quality floor live in agentm. -
no longer couples to the agentm memory engine โ the auto-on-stop capture used to write a
kind: session-costmemory record; that vault write is retired (delivered 2026-07-07, see the ambient-capture bullet above). The dreaming-pass review remains designed, unchanged in its own gating on the dreaming pass. -
feeds the agentm-side observability ledger โ delivered 2026-07-07 โ this capability's writer/reader now target the device-local JSONL event log directly; agentm's
PLAN-observability-ledger(agentm half) hosts the runner job that folds the raw log into the ledger's SQLite rollup โ the fan-out gate here still reads the raw event log, not the rollup (the rollup is a downstream aggregate, not this capability's read path). -
(designed) hosts the versioned routing table that instantiates model-effort-routing's tier scale in concrete model ids โ the tier + effort structure is that design's policy; the concrete, refreshable "which real model" mapping lives here, colocated with
pricing.py's per-model rates since both must agree on spelling. -
(designed) enhances development-lifecycle โ a new
enhances:edge (declared on token-audit, per the composition convention) carrying the fan-out cost gate, the mandatory-announcement contract its dispatch points rely on, and the versioned routing table itself. -
(forward-referenced) the pricing-drift mitigation is the
content-refreshprimitive โ tentatively homed in maintenance as an optional scheduled task โ which would periodically re-pinpricing.pyand the routing table from source (post-review pass to confirm its home + author it). - Points up at the crickets HLD; the requires/enhances mechanics are in crickets-composition.
-
The
status-line-meterfold โstatus_line_meter.pymoves in; its standaloneenhances:edge dissolves and becomes internal. One capability owns measurement + metering. -
The v6.0 rename
token-auditโtokens(object-over-action); the group declares both names so existing references resolve (the composition rename mechanism). Theefficiencyrename was rejected โ it collides with theefficientopinion the capability's own tools request, and inverts the one-way rule (a capability naming itself after the opinion it serves). - Sibling audits, not a widened scope โ other efficiency dimensions (latency, memory) get their own audit tools; this one stays token-cost.
-
All shipping primitives delivered โ
/token-audit,analyzer.py,pricing.py,status_line_meter.py; the fold + rename are mechanical. Ambient capture is now delivered too (2026-07-07, above). The automation layer (budget readout, fan-out gate,/handoff, routing-conformance, the versioned routing table) and the periodic review remain the designed additions (above) โ note some automation-layer primitives (the fan-out gate,/handoff) have since shipped underPLAN-efficiency-automation; that plan's own doc reconciliation is tracked separately, out of scope here. -
Hosting the model-id table here, not in model-effort-routing, trades a policy/data split for a single source of truth. An operator has to follow a pointer from the tier chart to the concrete table; the alternative (keep them together) was rejected because it re-creates a second place a model id can drift from
pricing.py's spelling. -
The fan-out gate is an estimate, not a guarantee. Hooks cannot read Anthropic's real remaining quota; the gate's local accounting from
session-costrecords can drift from the true billed number, especially early (few records) or after a pricing change (see thepricing.py-drift risk below). State this honestly in the gate's own output, not just here. -
pricing.py(and now the routing table) drift against real rates โ a pinned table goes stale when a vendor reprices or renames a model; the single-source design keeps the fix to one file per concern, but the re-pin is manual today. The standing mitigation is thecontent-refreshprimitive โ tentatively homed in maintenance as an optional, scheduled task โ which would automate the re-pin of both files together; confirm its home + author it at the post-review pass. - The capture/review split was a coupled bet on timing; the capture side shipped as the wave pull-forward. The Stop-hook capture shipped independent of the dreaming pass (2026-07-07) โ useful on its own, since the fan-out gate needed it โ pulling forward implementation the roadmap had scoped later; that pull-forward is now shipped, not just proposed.
-
Re-audit triggers: stand up the content-refresh capability to automate the
pricing.py+ routing-table re-pin (manual re-pin until then); wire the dreaming-pass review when the memory engine's relevant wave ships; migrate the fan-out gate + conformance report from hardwired toopinion_request('efficient')when the Wave-B opinion registry lands; execute thestatus-line-meterfold + thetokensrename at v6.0; add Gemini/Antigravity rows to the routing table when that side of the portfolio needs its own consumption path; replace the local cost estimate with ground truth if a host ever exposes real per-session quota telemetry.
- crickets
src/token-audit/+src/status-line-meter/(the folding-in source) โ/token-auditยทanalyzer.pyยทpricing.pyยทstatus_line_meter.py; declares[token-audit](โ[tokens]) -
Up / serves: crickets HLD ยท composition ยท agentm Opinions (
efficient) - Hosts / enhances: model-effort-routing (the tier + effort policy this table instantiates in concrete model ids) ยท development-lifecycle (the fan-out gate + announcement contract + the table itself)
- Superseded (designed) by: agentm-autonomy โ the observability ledger the session-cost capture retargets to
-
Worked example:
<vault>/projects/agentm/completed/mythos-readiness-handoff/PROMPTS.md+PROMPTS-NEXT.mdโ the manual protocol this automates
2026-10-03 โ a pack's snapshots drop the names their notes answer to (tokens 0.8.2). agentm's vault growth audit (2026-10-03) found pixelton's four charter copies in desk/ each carrying slug: _index and the project's aliases, so a search that puts the note a query names first could put a stale copy there instead of the charter. as_snapshot now drops aliases: and slug: from every snapshotted Markdown note and records them in snapshot_kinds beside the kind it replaced; the title and the body stay. Why drop rather than rename them: the copy has no name of its own to answer to, and its title still says what it is. Re-audit if agentm starts reading a handoff pack by slug.
2026-09-29 โ a pack's snapshots are handoff-artifact records (tokens 0.8.1). build_handoff_pack copied each session output byte for byte, frontmatter included. pixelcity's six packs each carried task 001's tracker.md, still kind: tracker and status: active, into desk/, and agentm's check-tracker-schema failed every copy as a tracker outside a tracker's place; three carried the unregistered kind: backlog too, which failed check-vocabulary-membership --strict. A snapshotted Markdown note with a kind: or type: now lands as kind: handoff-artifact, the record kind agentm's storage rules register for pack contents, and prompts.json's snapshot_kinds names what each one was. A record carries kind: and never type:, so a snapshotted memory loses its type; the body is never touched. Why rewrite the copy rather than leave trackers out of a pack: the next session reads the tracker's state and next steps, which is the reason to snapshot it. Why not exempt desk/ in agentm's gate: a copy still saying kind: tracker reads as a live head to anything that finds trackers by kind, wherever it sits. Re-audit if agentm's storage rules retire or rename handoff-artifact.
2026-09-22 โ /handoff defaults to the project's desk/ (tokens 0.8.0; agentm-vault part 15, crickets task 100). The command told the agent to put a pack under the vault's harness directory, the place the projects migration dissolved. agentm's overnight job, whose pack followed the same precedent, recreated that directory on 2026-09-17. With no destination named, a pack now goes to <desk>/<handoff-slug>/: handoff_pack.default_destination, over scripts/project_homes.py home desk, names the project's own desk/ as agentm does. With no desk (agentm absent, or no vault for the project) there is no default, and the command asks. A named destination still wins. The Mythos precedent is cited where plan 10 moved it, the agentm project's completed/. agentm's own overnight writer is agentm's to move (task 172). Why desk/: the project skeleton keeps what the operator does not open there, and a pack is working material for the next sessions, not a record. Re-audit if packs start needing to outlive the tasks they hand off.
2026-09-18 โ /handoff-pack becomes /handoff, and every prompt is also offered as a one-click chip (tokens 0.7.0). The pack's residual cost to the operator was the one part it never removed: opening a fresh session and pasting a prompt into it. Where the host exposes mcp__ccd_session__spawn_task (Claude Code's desktop app), the command now spawns one background-task chip per manifest entry, so a downstream step starts with a click; a host with no chip surface skips the step silently and keeps PROMPTS.md as the unchanged fallback. The command's own name loses the -pack suffix, which named the artifact rather than the act the operator invokes. Why the label is written into the chip's prompt body as prose: spawn_task carries no model or effort parameter, so a chip's session inherits the host default โ precisely the silent frontier-tier inheritance the routing table exists to catch; prompts.json stays the machine-readable source, the prose line is what survives into a chip, and the close-out names which chips need their model switched on open. Why handoff_pack.py and build_handoff_pack() keep their names: agentm's scripts/control_plane/handoff.py loads that module by filename and returns None โ degrading to "skip the pack" โ when it is absent, so a module rename would silently stop the nightly N1 pack instead of failing loudly. Why no /handoff-pack alias, against the /open+/orient precedent: that pair exists because both words are natural names for one act, not for back-compat; here the old name is the one being retired, and keeping it alive preserves the friction the rename removes. Re-audit trigger: if Claude Code's gated sideSessions tools (start_session, hand_off_to_session) reach this account, revisit the chip step โ start_session takes model and effort directly, retiring both the prose-label workaround and the switch-on-open close-out line.
2026-07-07 โ the ambient capture retarget is delivered (AA3, PLAN-observability-ledger crickets half). Flips the prior "superseded by design, not yet migrated" note to as-built: session_cost_writer.py no longer bridges to agentm's save_entry() / the vault at all โ it appends session-cost telemetry events ({model, tokens_by_kind, cost_usd, tags}) to the device-local, monthly-rotated JSONL event log via the new event_log.py module, with attribution tags stamped from the worktree-local .harness/active-plan marker. session_cost_reader.py reads the same log back for the fan-out gate. No vault call site remains in src/tokens/ (grep-confirmed, task 4's own verification). agentm's PLAN-observability-ledger (agentm half) picks up from here: the runner-hosted aggregator that folds this log into the ledger's SQLite rollup, plus the doc-pointer flip on agentm's own agentm-memory-index.md. Re-audit trigger: none outstanding for this capability's own half โ the remaining ledger work (rollup, console, digests) lives entirely downstream in agentm's designs.
2026-07-07 โ the ambient capture is superseded by design, not yet migrated (AA2, agentm-side Autonomy arc). Operator review of the Autonomy arc's budget-governor draft dropped its enforcement machinery (a subscription plan has no surprise bill; the window rate limit is the accepted backstop) and moved the session-cost capture off the vault onto a device-local JSONL ledger โ see agentm-autonomy. The pre-flight fan-out gate is demoted to advisory-only for unattended runs (confirm-or-block stays for interactive sessions). Neither change is code yet โ session_cost_writer.py/session_cost_reader.py still target the vault as described below, and the gate still confirms-or-blocks everywhere, until agentm's PLAN-observability-ledger lands the retarget. Re-audit trigger: flip this capability's own capture description + gate behavior to as-built when that plan ships.
2026-07-07 โ ambient capture shipped + a correctly-gated periodic-review stub (PLAN-wave-d-tokens-and-privacy, crickets #166). session_cost_writer.py + the session-cost-capture Stop hook log a per-model session-cost record on session close (graceful no-op with no memory backend, never blocking close); session_cost_reader.py closes the read-side loop so the pre-flight fan-out cost gate now runs against real records instead of its DEFAULT_AGENT_USAGE_PROFILE fallback. dreaming_trend_stub.py stages the periodic-review half as a correctly-gated dark stub โ dreaming_pass_available() is hard-False (the dreaming pass is itself [PENDING-IMPL]), so no trend-analysis logic was written ahead of its own dependency. Also corrected a stale governs: frontmatter path (src/token-audit/ โ src/tokens/, the directory this doc's own Migrations section had already described as renamed). Re-audit trigger: wire the dreaming-pass review when the memory engine's relevant wave ships.
2026-07-06 โ the session-cost write target now exists (AG Wave B, agentm-side). session-cost is a reserved kind value in agentm's V6-11 metadata table, shipped 2026-07-06 (see agentm's memory index design) โ the "it only needs a place to write" half of the ambient-capture bullet is now literally true, not aspirational. PLAN-session-cost-capture (the actual hook) is unaffected by this โ still its own tracked plan.
2026-07-04 โ P11 v2: automate the efficiency protocol, home the versioned routing table here (operator pressure-test correction). Adds the single-home versioned routing table (work-type โ tier/model-id/effort, colocated with pricing.py), rendered here with real seed values, plus a classify_work_type classifier that resolves a dispatch or a staged plan to a table row (persona-declared tier โ ad-hoc role-name match โ an explicit UNCLASSIFIED-DEFAULT fallback, never a silent guess), splits the prior "ambient capture + periodic review" bullet into a capture half pulled forward now (flagged as a Wave-D pull-forward for the roadmap session to confirm, not decided here) and a review half unchanged and still gated on the dreaming pass, and adds the automation layer: a 5h-window + weekly budget readout on the status line, a pre-flight fan-out cost gate (deterministic local accounting, confirm-or-block, always stating model ร agent-count ร estimated cost), a /handoff-pack command carrying a machine-readable tier/model label per prompt, and a routing-conformance report counting announcement-rule violations. Also flags a live, already-fired instance of the content-refresh trigger this design names: the agent-def frontmatter + every command nudge still cite claude-sonnet-4-6 / claude-opus-4-8, one day stale against pricing.py's claude-sonnet-5 row (same R0.7 pass); and names claude-fable-5 explicitly as a recognized, deliberately-unrouted, premium-priced model id, so an INHERITED announcement naming it reads as the Mythos failure shape on sight. Why not home the table in model-effort-routing instead (the earlier draft's choice): that design already has to publish the tier scale as a stable, host-portable policy; pinning volatile model-id strings into the same table couples two things with different change cadences, and โ more concretely โ creates a second place a model-id string can be spelled, which has to stay byte-identical to pricing.py's spelling for the fan-out gate's cost math to be correct. Colocating removes that second copy entirely. Why not wait for the dreaming pass before building capture: the fan-out gate needs session-cost records now, and capture doesn't need a reader to be worth writing. Why not let the table itself double as the classifier (skip the separate function): the table answers "what does this work-type get," the classifier answers "which work-type is this" โ collapsing them would silently guess a work-type from a model choice instead of naming the unmatched case, exactly the failure mode UNCLASSIFIED-DEFAULT exists to surface. Re-audit triggers: roadmap session either confirms or reschedules the Wave-D pull-forward; wire the dreaming-pass review when its wave ships; replace the local cost estimate with ground truth if a host ever exposes real per-session quota telemetry; re-pin the table + pricing.py together on every model release via content-refresh; bump the agent-def + command-nudge roster to claude-sonnet-5 (tracked here, executed in PLAN-efficiency-automation).
2026-06-28 โ lock-down sweep (operator review). Converted the primitives mermaid to a house-style hand-SVG (diagrams/crickets-token-audit.svg); and restored the missing ## Amendment log heading (the design had none). Confirmed token-audit is the measurement half of the efficient opinion (/token-audit + the live meter over pricing.py's pinned rates; analyzer.py's cache split ยท 5h windows ยท floor), and that the session-cost โ dreaming โ efficiency-trend chain is designed. Locked as a v5โv8 guidepost.
2026-06-23 โ authored, reviewed, and finalized. Authored from the seeded stub and grounded against the live src/token-audit + src/status-line-meter plugins. token-audit is the measurement half of efficient โ a deterministic cost analyzer (cache split ยท 5-hour windows ยท the always-load floor; same transcript โ same number) behind two surfaces: the on-demand /token-audit breakdown and the passive live meter (folding in status_line_meter.py); pricing.py is the single pinned rate source. The ### Opinions arrow is one-way (the opinion cites the numbers; the capability never reaches up). Recorded the rejected efficiency rename and the v6.0 tokens target (resolver aliasing).
On review: added a How it's invoked subsection โ three altitudes (passive live meter ยท operator-invoked /token-audit ยท a designed auto-capture-on-session-stop that logs a per-model session-cost memory record, reviewed in the dreaming pass to surface an efficiency trend; [PENDING-IMPL]) โ and reframed the pricing.py-drift risk to forward-reference the content-refresh primitive (tentatively homed in maintenance as an optional scheduled task) as the standing re-pin mitigation. Re-audit: build the auto-capture + dreaming review; stand up content-refresh to automate the pricing.py re-pin; execute the status-line-meter fold + the tokens rename at v6.0.