APAW/.kilo/rules/gns-checkpoint-pruning.md

GNS-2 Checkpoint Pruning Protocol

Rules for minimizing context window usage through Gitea-centric checkpointing and agent context hygiene.

Core Principle: Gitea is the Single Source of Truth

No agent holds state in RAM that is not also in Gitea. Agents boot from checkpoint and write back before exit. Everything between is transient.

Checkpoint Schema v2 (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}
  current_task:
    title: "{short_title}"
    deliverable: "{one_sentence}"
    files: ["{path1}", "{path2}"]  # max 3
    priority: critical|high|medium|low
  agent_chain:                   # who did what, last 5 only
    - {agent, action, timestamp, result: pass|fail|blocked}

What Was REMOVED from checkpoint (moved to comments)

Field	Where it now lives	Why
Full history	## GNS-2 Checkpoint Archive comment	Only last 3 entries needed for resumption
Cascade logs	Agent result comments with GNS_EVENT footer	Machine-readable footer replaces cascade table
Test outputs	Gitea comment attachments (screenshots, logs)	Binary data never in checkpoint
Research links	## 🔍 Research Archive comment	Links don't need to be in context
Build artifacts	.kilo/logs/ files	Offloaded to filesystem

Agent Entry Protocol (Context Hygiene)

Every agent MUST execute on entry, in this order:

1. Read issue body → parse checkpoint YAML block ONLY
   • If checkpoint has > 10 top-level keys → log warning, use only required fields
2. Read last 3 issue comments → find previous agent's result
   • Page through comments with limit=3 and sort=desc
3. Read ONLY files in checkpoint.current_task.files (≤3 files)
4. Load ONLY 1 skill referenced by task type
5. Load ONLY 1 rule if task type requires it (e.g., sdet-engineer → sdet-engineer.md)
6. Everything else stays in Gitea. Fetch on demand via API with pagination.

What agents MUST NOT load into context

Source	Why not	Where it stays
Comments older than last 3	Outdated, action already taken	Gitea comment history
Full git diffs	Too large, irrelevant to current task	.kilo/logs/diffs/
Build logs (>50 lines)	Binary/text noise	Gitea attachments / .kilo/logs/
Previous agent's full output	Only result + verdict matters	Previous Gitea comment
Rules not referenced by task	Global rules are for orchestrator	.kilo/rules/ files
Multiple skills	1 skill per task type	.kilo/skills/ directory
capability-index.yaml full	Orchestrator uses this, not agents	Kept in orchestrator context only

Agent Exit Protocol (Checkpoint Write)

Before terminating, agent MUST:

1. Write result comment to Gitea issue with:
   • One-sentence summary
   • Verdict (✅/❌/🚫)
   • GNS_EVENT footer (machine-readable)
   • next_agent recommendation
2. Update checkpoint in issue body:
   • Increment consumed
   • Decrement remaining
   • Update last_agent, last_invocation
   • Truncate history_tail to 3 entries (append new, drop oldest)
   • Update current_task if changed
   • Set next_agent
3. If budget consumed > 80%:
   • Post archive comment with full history
   • Reset consumed/remaining for new phase
   • Mark checkpoint pruned: true

On-Demand Context Loading

Agents may fetch from Gitea ONLY when:

1. Missing field in checkpoint → GET /repos/{owner}/{repo}/issues/{number} for body
2. Need specific old comment → GET /issues/{number}/comments?page={n}&limit=3
3. Need attachment → GET /repos/{owner}/{repo}/issues/comments/{id}/assets
4. Never fetch full comment history or list all files in repo without filter

Pagination Rules

• Comments: limit=3, sort=desc
• Files changed: only files from checkpoint.current_task.files
• Commits: only last 3 via git log -3 --oneline
• Logs: last 20 lines only (tail -n 20)

Context Budget Tracking

Agent MUST calculate before loading:

context_estimate = len(checkpoint_yaml) + len(file_1) + len(file_2) + len(skill)
if context_estimate > available_context * 0.3:
    → Log warning to `.kilo/logs/context-overflow-warnings.jsonl`
    → Reduce files_loaded to 1
    → Request smaller task scope via Gitea comment

Token Budget per Task Size

Task	Max Load	Files	Skill	Rule	Comments
Tiny (<2k)	3,500	1	1	0	1
Small (<5k)	5,200	2	1	0	2
Medium (<10k)	8,800	3	1	1	2
Large (<20k)	18,500	3	1	1	3

Metrics

Log to .kilo/logs/context-budget.jsonl on every agent exit:

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

Recovery

If agent detects corrupted checkpoint:

1. Read issue body → verify YAML
2. If valid → resume with pruned state
3. If invalid → post ## 🔄 context-recovery-needed comment
4. Log to .kilo/logs/context-corruption-recovery.jsonl

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 multiple skills for a single task
• DO NOT estimate task without checking remaining context budget
• DO NOT skip checkpoint pruning when consumed > 80%
• DO NOT hold state in RAM without writing to Gitea
• DO NOT modify checkpoint version field