APAW/.kilo/rules/context-window-budget.md

Context Window Budget Rules

Prevent context window overflow by offloading state to Gitea and loading only what an agent needs.

Problem

Agents routinely load:

• Full issue comment history (200+ comments = 15,000+ tokens)
• Previous agent output that is irrelevant to current subtask
• Git diffs, logs, and file listings that could be fetched on demand
• Duplicate rules content already in .kilo/rules/*

This pushes context windows to 80–90% before any work begins, leaving <10% for actual reasoning and tool calls.

Principle: Gitea is the Source of Truth

Every piece of state written to Gitea is excluded from agent context. Agents load only:

1. Current checkpoint YAML (last state from Gitea issue body)
2. Their own previous results if this is an iteration
3. Files relevant to the atomic task (≤3 files)
4. Rules/skills directly referenced by the task type

Context Budget per Task Size

Task Size	Max Context Tokens	Checkpoint Overhead	Available for Work
Tiny (<2k)	4,000	500 (checkpoint read)	3,500
Small (<5k)	6,000	800 (checkpoint + last comment)	5,200
Medium (<10k)	10,000	1,200 (checkpoint + 2 comments)	8,800
Large (<20k)	20,000	1,500 (checkpoint + full cascade log)	18,500

Checkpoint Pruning Protocol

What MUST be in checkpoint (minimal)

checkpoint:
  version: 2
  issue: {number}
  phase: {phase_name}
  depth: {current_depth}
  last_agent: {agent_name}
  last_invocation: {invocation_id}
  budget:
    total: {allocated}
    consumed: {used}
    remaining: {left}
  state:
    labels: [{active_labels_only}]
    assignee: {current_agent}
  history_tail:                # ONLY last 3 entries
    - {agent: name, action: brief_action, timestamp: ISO}
  next_agent: {agent_name}
  next_estimated_tokens: {number}
  created_at: {ISO8601}

What is REMOVED from checkpoint (stored in comments only)

• Full history array → truncated to history_tail (last 3 entries)
• Cascade logs older than last invocation → moved to dedicated comment
• Test output, screenshots, build logs → linked as Gitea comment attachments
• Research links and references → moved to dedicated research comment

Pruning Execution

Before any agent is spawned, orchestrator MUST:

1. Read issue body → extract checkpoint YAML
2. If checkpoint consumed > 80% of total:
   • Truncate history to history_tail
   • Move full history to new Gitea comment with ## GNS-2 Checkpoint Archive
   • Reset consumed counter for new phase (carryover: remaining / 2)
3. Patch issue body with pruned checkpoint
4. THEN spawn the agent with pruned checkpoint only

Agent Context Hygiene On Entry

Every agent MUST execute on entry:

1. Read issue body → parse checkpoint (only YAML block, skip all comments)
2. Read ONLY last 3 comments → find previous agent's result and cascade log
3. Read ONLY files referenced in the task prompt (≤3 files)
4. Load ONLY relevant skill (1 skill per task type)
5. Everything else stays in Gitea comments — fetch on demand via API if needed

What Agents MUST NOT Load

Category	Example	Where it stays
Old comments	Comments from 5 agents ago	Gitea timeline API
Build artifacts	npm test output, phpunit results	Gitea comment attachments
Full git history	git log --all output	.kilo/logs/ files
Screenshot dumps	Visual diff images	Gitea attachments
Repeated rules	global.md, docker.md if not task-relevant	.kilo/rules/ (loaded by skill reference only)
Previous agent's full output	Complete lead-developer result	Previous Gitea comment + file diffs

Context Loading Cost Budget

Before loading any content, agent estimates cost:

total_estimate = checkpoint_yaml + file_1 + file_2 + file_3 + skill
if total_estimate > available_context * 0.3:
  → Load fewer files or request slimmer task
  → Log to `.kilo/logs/context-overflow-warnings.jsonl`

Gitea API On-Demand Fetching

Agents may fetch from Gitea ONLY when:

1. Checkpoint is missing required field → GET /repos/{owner}/{repo}/issues/{number}
2. Need specific old comment → GET /issues/{number}/comments with page + limit=3
3. Need attachment/screenshot → GET /repos/{owner}/{repo}/issues/comments/{comment_id}/assets
4. Never fetch full comment history — always paginated with limit=3

Recovery from Context Corruption

If an agent detects its context is incomplete or corrupted:

1. STOP and do not proceed with the task
2. Read issue body checkpoint to verify depth/budget
3. If checkpoint is valid → resume with pruned state
4. If checkpoint is invalid → request orchestrator recovery via Gitea issue comment with ## 🔄 context-recovery-needed
5. Log failure to .kilo/logs/context-corruption-recovery.jsonl

Metrics

Track in .kilo/logs/context-budget.jsonl:

{"ts":"2026-05-16T13:20:00Z","agent":"lead-developer","issue":113,"context_loaded":4200,"context_available":10000,"context_ratio":0.42,"files_loaded":2,"checkpoint_entries":5,"pruned":true}

Prohibited Actions

• DO NOT load full issue comment history into context
• DO NOT include previous agent output unless iterating on same task
• DO NOT load rules that are not directly referenced by task type
• DO NOT estimate task without first checking remaining context budget
• DO NOT skip checkpoint pruning when consumed > 80%