Per-role context costs
ginee ships markdown that the host LLM reads as context. The cost of “framework alone” — before any of your project’s code, docs, or prompts — is auditable per role.
This page reports what each cardinal pays on first dispatch on the current main, measured by scripts/measure-role-context.ps1. A Pester test (tests/measure-role-context.Tests.ps1) gates per-role byte ceilings on every PR — context-economy regressions fail CI.
Current measurement
The table below is auto-generated. Refresh with:
pwsh -File scripts/measure-role-context.ps1 -UpdateDoc
A Pester test (tests/measure-role-context.Tests.ps1 § doc is current) fails CI if the table is stale.
Snapshot for ginee v0.26.0. Refresh with pwsh -File scripts/measure-role-context.ps1 -UpdateDoc.
Per-role load
| Role | Phases loaded | Files | Bytes | ~Tokens |
|---|---|---|---|---|
ai-engineer |
[] |
2 | 18,334 | ~4,584 |
qa-engineer |
[5, 6] |
4 | 30,742 | ~7,686 |
backend-engineer |
[2, 4, 5, 6] |
6 | 30,779 | ~7,695 |
frontend-engineer |
[2, 4, 5, 6] |
6 | 30,787 | ~7,697 |
devops-engineer |
[2, 4, 5, 6] |
6 | 34,735 | ~8,684 |
solution-architect |
[1, 2, 7] |
5 | 38,363 | ~9,591 |
team-lead |
[1..8] + dispatch.md |
11 | 65,917 | ~16,479 |
Per-role byte ceilings (CI gate)
Ceilings are defined in scripts/templates/role-context-ceilings.json — single source of truth for both the doc and the Pester test. Tighten over time as measurements stabilise; raising a ceiling without an ai-engineer optimization pass is a code-review concern.
| Role | Ceiling | Current | Headroom |
|---|---|---|---|
ai-engineer |
26,000 | 18,334 | ~29% |
qa-engineer |
38,000 | 30,742 | ~19% |
backend-engineer |
40,000 | 30,779 | ~23% |
frontend-engineer |
40,000 | 30,787 | ~23% |
devops-engineer |
46,000 | 34,735 | ~24% |
solution-architect |
53,000 | 38,363 | ~28% |
team-lead |
82,000 | 65,917 | ~20% |
Token estimate. bytes ÷ 4, the tiktoken English-markdown approximation. Useful for ranking + regression detection; not a substitute for real tokenisation when absolute counts matter.
What’s counted
Per role, “first-dispatch load” includes:
| File set | Why |
|---|---|
core/process.md |
Always-loaded common (Purpose · Reading order · principles · doc style · reporting · coordination · load-on-demand index). |
core/roles/<role>.md |
The role kernel itself. |
core/process/phase-<N>-*.md |
One per N in the kernel’s phase-participation: frontmatter — the D35-process-md-load-topology contract. |
core/process/dispatch.md |
Orchestration content — team-lead only. |
What’s NOT counted
| Excluded | Why |
|---|---|
core/roles/<role>.details.md |
Load-on-demand sidecar; only fetched when the kernel’s load triggers fire. |
core/protocols/*.md (iteration-protocol · doc-authoring-protocol · index-protocol · options-protocol) |
Load-on-demand specs; gated by activation cues per role. |
core/protocols/automatic-mode.md · core/protocols/delivery-modes.md · core/protocols/cross-domain-bugs.md · core/protocols/github-integration.md · core/protocols/triage-scoring.md · etc. |
Load-on-demand specs; not always-loaded. |
local/* |
Per-project state — out of scope for “framework alone” cost. |
| Citations inside the kernel body | Counted only if always-loaded (e.g., core/process.md); load-on-demand citations excluded. |
D35-process-md-load-topology contract — verifiable from the numbers
The split shipped in D35 (#89) makes role context cost proportional to role participation. Every cardinal except team-lead saves vs. a pre-D35 baseline where the full lifecycle spec was always loaded:
| Role | Phases loaded | Saved vs. always-load-everything |
|---|---|---|
ai-engineer |
none (between-phase optimizer) | largest saving — common only |
qa-engineer |
2 phases | large saving — fewest phases of any participating role |
backend / frontend / devops |
4 phases | medium saving |
solution-architect |
6 phases | smaller saving — design + reviews span the lifecycle |
team-lead |
8 phases + dispatch.md |
none (orchestrator legitimately needs the full pipeline) |
The Pester test enforces three invariants that mirror the D35 contract:
ai-engineeris the cheapest role (between-phase optimizer must stay light).team-leadis the most expensive role (orchestrator owns the full pipeline).qa-engineer≤ engineering cardinals (qa loads[5, 6]; engineers load[2, 4, 5, 6]— strict superset).
Run it yourself
From the repo root:
# Human-readable table
pwsh -File scripts/measure-role-context.ps1
# JSON (for tooling / dashboards)
pwsh -File scripts/measure-role-context.ps1 -Json | ConvertFrom-Json
Or run the gating test directly:
Invoke-Pester -Path tests/measure-role-context.Tests.ps1 -Output Detailed
When this page updates
This page snapshots the current main branch. Any PR that materially shifts per-role cost (extracts a spec · adds a phase file · slims core/process.md further) should update the table in the same PR — the D25-classical-architect user-docs co-update rule (per CLAUDE.md § Hard constraints) applies.
Relation to D21-context-economy-gates
D21 gates net-added bytes per file on every PR; this page reports total bytes per role on first dispatch. Both surfaces matter:
| Gate | Catches | Fails when |
|---|---|---|
| D21-context-economy-gates | Per-file growth | A single file grows past its tier threshold without an Optimized-By: ai-engineer trailer. |
| Per-role context test (this page) | Per-role aggregate growth | A role’s total load exceeds its ceiling — even if no single file tripped D21. |
The two gates are complementary. D21 catches local growth on a single edit; the per-role test catches accumulated growth across many small additions to the role’s load set.