---
name: Arco Token Totter
version: 1.0.1
status: active
owner: Stoirm Arnold
last_updated: 30-Sep-2026
---

# Arco Token Totter

## Purpose

Token Totter is Arco's token-efficiency audit Function.

It reviews maintained operating files and their routing paths to identify unnecessary context cost, proposes the smallest changes that preserve Arco's purpose and safeguards, and re-measures every changed file after approved updates.

Token Totter optimises what an AI must load to work accurately. It does not treat the total size of a well-routed repository as though every file were always active context.

## Boundary

Token Totter may inspect:

- first-hop routers and frequently read operating files;
- routing instructions and realistic task-specific read paths;
- duplicated or stale operating content;
- changelog and historical-commentary growth;
- distinctions between runtime reads and maintenance/inheritance dependencies;
- progressive disclosure into modules, Functions, Development records, templates and other supporting sources.

Token Totter does not:

- remove content merely because it is long;
- weaken Governance, approval, archive, validation or source-of-truth controls;
- collapse healthy modular files into a single master instruction;
- make architectural changes without the normal approval and Dry Run process;
- treat Archive, reports or human artifacts as routine runtime context;
- replace Defrag. Defrag checks overall architecture coherence; Token Totter is specifically responsible for context and token efficiency.

## Trigger and scope

Run Token Totter when explicitly requested, when a frequently read file or route has grown materially, or when repeated work appears to load irrelevant context.

Resolve the audit scope before scanning. Prefer a bounded route, subsystem or set of canonical files. A full-Core audit is appropriate only when requested or when the cause cannot be isolated safely.

Do not use archived files as current authority. Consult them only when release history is needed to interpret a proposed cleanup.

## Measurement method

Use an exact tokenizer appropriate to the intended model when reliably available. Otherwise use one consistent documented estimate for both baseline and re-measurement, such as characters divided by four, rounded sensibly.

Always label estimated values as estimates. The comparison is useful only when before and after use the same method.

Measure two different things:

1. **File weight** — the size of each maintained file in scope.
2. **Route weight** — the combined context likely to be loaded for a realistic task through the intended routing path.

Do not present the sum of every repository file as the normal per-task cost unless routing actually loads them all.

## Audit process

1. **Ground the architecture.** Read the current router and only the canonical files required to understand the scoped route.
2. **Define realistic scenarios.** State which ordinary tasks and maintenance tasks the route must support.
3. **Create the baseline.** Record file weight, route weight, when each file is loaded and the measurement method.
4. **Find context tax.** Look for over-broad routing, duplicated rules, promoted work left in Development, maintenance dependencies mistaken for runtime dependencies, stale commentary, oversized examples, and changelogs that crowd out current operating content.
5. **Protect the operating purpose.** Identify behaviour, authority, safety, traceability and rationale that must remain intact before proposing reduction.
6. **Propose the smallest correction.** Name the owning file, the exact type of reduction or routing change, expected saving, preserved behaviour, risk and required approval/validation.
7. **Stop at the applicable approval boundary.** An audit may recommend changes, but implementation follows the System Manual, Governance and user authority.
8. **Implement approved changes.** Archive outgoing minor/major releases, update versions and changelogs, and run required Dry Runs.
9. **Re-read saved files.** Fetch or open every changed canonical file after the write; do not measure an unsaved draft as the final state.
10. **Repeat the same measurements and scenarios.** Confirm the intended routes still produce complete, correct behaviour and no required control disappeared.
11. **Report the result.** Show concise before/after token estimates and any remaining concern.

## Proposal test

A Token Totter proposal is valid only when it can answer:

- What routine context cost is being reduced?
- Why is the material unnecessary on that route?
- Which canonical owner retains the required behaviour or rationale?
- What could be lost or misread?
- How will the changed route be tested?

If the answer depends on inventing new architecture, route the issue to Development rather than treating it as a token cleanup.

## Reporting

Start an audit report with a compact baseline table:

| File or route | Approx. tokens | Loaded when | Assessment |
|---|---:|---|---|
| `<file or route>` | `<estimate>` | `<trigger>` | `<concise finding>` |

After approved updates, show the re-measured result:

| File or route | Before | After | Change | Behaviour check |
|---|---:|---:|---:|---|
| `<file or route>` | `<estimate>` | `<estimate>` | `<delta and %>` | `PASS / FAIL` |

Keep the report decision-focused. Include:

- measurement method;
- largest material context costs;
- approved changes made or proposals awaiting approval;
- before/after table;
- routing/behaviour validation result;
- any unresolved architecture routed to Development.

## Core principles

- Optimise loaded context, not file count.
- Progressive disclosure is the default architecture.
- Frequently read routers should be small and selective.
- One responsibility and one source of truth reduce both drift and tokens.
- Historical state belongs in release archives; durable architectural rationale belongs in Design only where it explains a current choice.
- Changelogs remain traceable but follow the current-major rollover standard.
- A token saving is not an improvement if it makes Arco less accurate, less governable or harder to maintain.
- Re-measurement and behaviour validation complete the work; a shorter draft alone does not.


## Canonical references

[arco-system-manual.md](https://drive.google.com/file/d/1doS7QXRtShzT45wHC13Vx0zxputK50l-/view), [arco-governance.md](https://drive.google.com/file/d/1JmdNUNPVJLxFbNQKYS3cJTnDPJ6hRvxb/view), [arco-dry-runs.md](https://drive.google.com/file/d/1Fe2PJd-IGIE5UlZmOlr0d3mThRkKbhX7/view).

## Changelog

| Date | Version | Change | Approved by | Changed by |
|---|---|---|---|---|
| 30-Sep-2026 | 1.0.1 | Restored canonical provider-link references. | Stoirm Arnold — Defrag invocation | Codex Work |
| 19-Sep-2026 | 1.0.0 | Created Token Totter as the Core Function for scoped token/context audits, smallest-safe proposals, approval-aware implementation, saved-file re-review and concise before/after measurement. | Stoirm Arnold | Codex desktop |