Instructions-files budget — decision history¶
Lifted verbatim from the _doc field of data/instructions_files_budget.json on 2026-09-17 under the instructions-files-diet chore (GHI #921). The values enforced today are the files and globs entries in that JSON file — never a number quoted here. Reading convention, carried from the diary: each dated entry states the values true on its own date; the last entry is what is enforced today.
Head note¶
Per-file char budgets for instructions/memory files (GHI #373). AGENTS.md was tightened 40k→15k by OBPI-0.0.54-01 as a moderate-compromise target; OBPI-0.0.54-03 measured a ~31k transitional floor with the current monolithic template. The budget ceiling was Codex's 32768-byte project-doc cap until the operator ruling of 2026-07-06 DECOUPLED it (hexagonal: an adapter limit must not gate the core contract); the ceiling is now _PROJECT_DOC_BUDGET_CEILING_BYTES = 65536, enforced by tests.governance.test_agents_md_map_doctrine._budget_within_ceiling. The vendor cap itself is observed, not enforced, by the surface-delivery witness under gz validate --instructions-files-budget (GHI #712) — it reports byte distance to stderr and fail-closes only on survival-declaration drift.
2026-06-04¶
2026-06-04: OBPI-0.0.37-26 LANDED the interim #519 relief — the local splice (.gzkit/agents.local.md) was hand-compressed 9,306→4,997 bytes, dropping rendered root AGENTS.md to 28,342 bytes, under the then-30000 interim ceiling and ~4.4 KB under the Codex byte cap (genuine context reduction, not a budget-at-cap stopgap). This supersedes the transient budget-at-cap reading (32768) that only flipped the gate green without shrinking the surface. The committed rendition (renditions/agentcontract-codex-root-interim.md) is the durable payload OBPI-21/22's composer regenerates deterministically. The <15k destination remains GHI #533 / ADR-0.0.37.
2026-06-22¶
2026-06-22 (operator-ratified): AGENTS.md raised 30000→31000 to seat the corpus-faithful render of the full invariant-tier floor (all 45 entries verbatim render to 30,631 chars / 30,806 bytes). The prior 30000 ceiling could only be met by a rendition that DROPPED invariant entries — i.e. by drift — so the budget was holding the surface honest at the cost of the invariant floor. 31000 matches OBPI-0.0.54-03's measured transitional floor, fits the faithful render with headroom, and stays ~1.9 KB under the 32768 B Codex hard cap (no silent-truncation risk). The <15k destination via corpus splitting remains the durable goal (GHI #533 / ADR-0.0.37). CLAUDE.md 4000 and .claude/rules/*.md 15000 remain from OBPI-0.0.54 AS OF THIS ENTRY (each dated entry states the values true on its own date, never the current ones — read the LAST entry for what is enforced today).
2026-06-30¶
2026-06-30 (operator-directed, budget-tuning explicitly deferred — 'we will use that for tuning later, the mechanism to do so is now in place'): AGENTS.md raised 31000→31800 to seat the corpus-faithful render of 5 new invariant-tier guardrails captured from the 2026-06-30 insights report (pipeline-stage discipline, no --no-verify, narrow-scope discipline, defect/deferred-claim honesty, surface-blockers-upfront). Measured claude/root render = 31,569 bytes (invariant 9,612 / compressible 21,957); 31800 clears it whether counted as chars or bytes and holds ~968 B under the 32768 B Codex hard cap (no silent-truncation risk). This GROWS the surface against the <15k shrink goal (GHI #533 / ADR-0.0.37) — the operator booked that tension as later tuning, not a blocker; the corpus-splitting destination is unchanged.
2026-07-06¶
2026-07-06 (ceiling decoupled BY RULING; the three per-file BUDGETS were raised deliberately, but their rationale went unrecorded until 2026-07-28): the operator ruling 'that hard-coded value is noise, bump' DECOUPLED the ceiling from the Codex vendor cap (32768→65536; hexagonal — an adapter limit must not gate the core contract). In the same commit (219d23fd6, a gz git-sync chore bundle) three BUDGETS were raised: AGENTS.md 31800→50000, CLAUDE.md 4000→15000, .claude/rules/*.md 15000→30000. These are NOT drift — see the 2026-07-28 entry, which records the standing pre-1.0 posture they implement. What was genuinely missing was the WRITTEN RATIONALE: gz git-sync bundles DERIVED surface regeneration and its commit template carries no slot for 'why did this hand-tuned threshold change', so a deliberate posture arrived on disk looking indistinguishable from drift. That indistinguishability is the defect — not the number.
2026-07-28¶
2026-07-28 (operator ruling, verbatim: 'until we get gzkit stable, I want to relax limits. the cms system is meant to control this, but we don't have gzkit feature stable enough to be strict'): the loose budgets are a DELIBERATE PRE-1.0 RELAXATION, now on the record. Rationale: the corpus/CMS chain (gz content remember → gz content compose → land) is the intended control surface for per-turn size, and it is not feature-stable — ADR-0.35.0-canon-entry-corpus-landing is Draft at 0/9 OBPIs landed, with the corpus→candidate generator (OBPI-05) and the gz content land orchestrator (OBPI-07) both unbuilt. A gate whose satisfaction path does not exist does not force the work; it only blocks it, and then gets widened under pressure — precisely what the 2026-06-30 setting of 231 chars (0.7%) headroom demonstrated by being blown out within a week. Strictness is earned by the mechanism that discharges it. EXIT CONDITION: re-tighten toward the <15k destination (GHI #533 / ADR-0.0.37) when the CMS corpus-splitting path lands — not before. A retune to 33000/4000/19000 was made and REVERTED the same day under this ruling; measurements taken then, recorded for whoever re-tightens: AGENTS.md 32,023 chars / 32,208 B; CLAUDE.md 1,432 chars; largest rule file tests.md 17,851 chars (tests.md already exceeds the pre-2026-07-06 rules budget of 15000, so that value is not restorable without a diet pass on its rule-version-history preamble). Ceiling unchanged at 65536. Reading convention, which is what actually failed here: each dated entry states the values true ON ITS DATE; the LAST entry is what is enforced today.
2026-08-06¶
2026-08-06 (GHI #533 — dead-pointer sweep; BUDGETS UNCHANGED, destination repointed): the EXIT CONDITION above names ADR-0.0.37, which went terminal 2026-07-18 (§ Terminal Disposition, 'Split-and-Supersede') with its registry-spine OBPIs PERMANENTLY WITHDRAWN — no weight-halving work can land there, so that exit condition aimed whoever re-tightens at a destination that cannot accept the work. RESTATED EXIT CONDITION: re-tighten toward the <15k destination when ADR-0.35.0-canon-entry-corpus-landing § Decision 3 lands — sections declare corpus-owned or unowned, the generator materializes owned sections from the corpus, and the unowned byte total is held in a decrease-only ratchet; concretely, when its corpus→candidate generator (OBPI-05) and gz content land orchestrator (OBPI-07) exist. Not before — the 2026-07-28 ruling that strictness is earned by the mechanism that discharges it is unchanged, and repointing the destination does not make the mechanism exist. The four prior mentions of ADR-0.0.37 are left UNMODIFIED on purpose: each sits in a dated entry, that ADR was live on each of those dates, and rewriting them would falsify the record this file's own reading convention depends on. Same-sweep siblings: .gzkit/rules/agents-md-map-doctrine.md (v0.3.0, landed earlier under this GHI) and docs/governance/agents-md-doctrine.md § Budget targets. Superseded planning docs naming ADR-0.0.37 (ultraplan-brief.md, build-to-1.0-campaign-2026-06-10.md, return-to-health-plan-2026-05-30.md) each carry a SUPERSEDED/retained-for-audit banner and are deliberately untouched.
2026-08-17¶
2026-08-17 (operator ruling, verbatim: 'temporary stay of all control surface budget limits until version 1.0. I want to be warned, and we may lift the limits as needed, but no blockers.'): the per-file budgets are now ADVISORY. BUDGET VALUES ARE UNCHANGED — AGENTS.md 50000, CLAUDE.md 15000, .claude/rules/*.md 30000 — and the audit still measures every file and reports each overrun to stderr with its byte distance and the /gz-context-diet pointer; what is suspended is the CONSEQUENCE, never the observation. audit_instructions_files_budget returns no ValidationError and cannot change an exit code. This makes the two arms of gz validate --instructions-files-budget consistent: its scope-sibling surface_delivery_witness has been observe-only on the vendor cap since the 2026-07-06 decoupling ruling, so the scope previously fail-closed on the project's own budget while merely warning about the vendor cap that can actually TRUNCATE the surface — strict about the softer limit, advisory about the harder one. The scope still fail-closes through that sibling on survival-declaration drift, and the negative control was repointed there the same day (a control asserting enforcement that no longer happens is worse than no control). Measured at the ruling: AGENTS.md 33153 chars against a 50000 budget, so nothing was blocked by this gate at the time — the stay is a standing posture, not a workaround for a live block. EXIT CONDITION: restore fail-closed at 1.0, on the same 2026-07-28 ground that strictness is earned by the mechanism that discharges it — the corpus/CMS path is what makes an over-budget surface fixable, and ADR-0.35.0 § Decision 3 is where it lands. Reading convention unchanged: this is the LAST entry, so it states what is enforced today.
2026-08-17 (2)¶
2026-08-17 (second ruling, same day, verbatim: 'when we exceed vendor limits, ghi it so it doesn't block'): VENDOR-LIMIT EXCEEDANCES ROUTE TO A GHI, NEVER A BLOCK. This is a separate rule from the budget stay above and must not be collapsed into it. The budgets in files/globs are gzkit's OWN thresholds and are stayed to advisory until 1.0; a vendor delivery cap is a PHYSICAL truncation belonging to the consuming vendor, so no gzkit ruling can stay it and raising a budget cannot relieve it — bytes past the cap are simply not delivered. The surface_delivery_witness has reported vendor-cap distance without blocking since 2026-07-06; what this ruling adds is the TRACKING obligation, so an exceedance lands in a durable record instead of a stderr line that scrolls past. Live record: GHI #815 (AGENTS.md 33153 B against the codex cap 32768 B, 385 B over, with the must-survive section 'architectural-boundaries' straddling the boundary at bytes 32558-33153). The remedies are owned elsewhere and neither is a budget change: ADR-pool.render-order-truncation-survival (reorder must-survive sections ahead of the cap) and GHI #533 (shrink). Note the shape GHI #815 records — must-survive measured 21582 B cumulative against a 32768 B cap under GHI #580, so the declaration is satisfiable and it is the render ORDER that fails.
2026-08-17 (3)¶
2026-08-17 (third ruling, same day — TRACKING RECORD MOVED; budgets and both rulings above UNCHANGED): GHI #815 was CLOSED superseded into ADR-pool.render-order-truncation-survival, which now carries the measurement in its Intent and Decision (commit b20b210e4). The entry above names #815 as the 'Live record' — true on its date, and left unmodified per this file's reading convention, but it is no longer where the exceedance is tracked. The vendor-cap exceedance ITSELF IS STILL LIVE: AGENTS.md renders 34354 B against the codex cap 32768 B (1586 B over) and the must-survive section 'architectural-boundaries' begins at byte 33759, wholly past the cap rather than straddling it as it did at 385 B over. Re-measured the same day, the must-survive set (ranks 1-11) totals 23678 B with 9090 B of headroom under the cap, so the declaration is satisfiable with NO shrink and exactly one section falls outside — because it renders LAST. That is why the reorder half (ADR-pool.render-order-truncation-survival) is ranked FIRST as the delivery remedy and GHI #533 (shrink) is ranked second as the cure: a smaller surface in the same order still puts rank 11 last. The tracking obligation from the second ruling is unchanged — if an exceedance has no OPEN GHI, file one via /ghi-author; do not cite #815, resolve first. Note also that #533's own body names ADR-0.0.37 as its blocker, which is STALE: that ADR is Validated 15/15 and the dependency relocated to ADR-0.35.0 Decision 3, Pending at 0/10.
2026-08-17 (4)¶
2026-08-17 (fourth ruling, same day — #815 REOPENED and a CORRECTION to the entry above; budgets still UNCHANGED): the operator ruled the cap should carry an open tracker ('I wanted the codex cap to be GHI'd'), so GHI #815 was REOPENED rather than refiled — ghi-author Step 0 reopens a <=30-day close of the same root cause instead of duplicating it into a fresh number. The superseded routing to ADR-pool.render-order-truncation-survival STANDS; the reopen restores a tracker, not a reversal. CORRECTION: the entry above says shrink is 'ranked second as the cure: a smaller surface in the same order still puts rank 11 last.' That is OVERSTATED and the error is material. It holds only while the surface remains OVER the cap; compress AGENTS.md below 32768 B and every section renders inside it, architectural-boundaries included, so shrink IS a delivery fix. The honest axis is durability, not capability: reorder is growth-invariant (must-survive renders first whatever the total) while shrink restores delivery today and decays on the next corpus growth. They are complementary; reorder stays ranked first because its fix does not decay. The prior entry is left UNMODIFIED per this file's reading convention — a dated entry records what was believed on its date, and this correction is itself dated. VEHICLE: the shrink work is chore-shaped, and instructions-files-diet v2.0.0 (GHI #817) is now corpus-aware — it authors against .gzkit/corpus/AGENTS.md.jsonl, composes candidates, and STOPS at the Gate 5 attestation boundary rather than landing canon. v1.0.0 named AGENTS.md as a direct edit target and omitted gz validate --invariant-coherence from its acceptance set, so it could have edited a rendered surface and gone green.
2026-08-17 (5)¶
2026-08-17 (fifth ruling, same day — the EXIT CONDITION above is RETIRED, not merely restated; budgets and values still UNCHANGED): the 2026-07-28 ground was that 'strictness is earned by the mechanism that discharges it.' The mechanism now exists and it is a CADENCE, not a gate, which dissolves the exit condition rather than satisfying it. Operator verbatim: 'permit exceedances of accumulated render sources, then, let the chore handle overages. It keeps the management of control surface sizes trimmed and managed at a more realistic/manageable cadence'; 'let the chore manage the limits. let normal discovery and operations add to or suggest modifications to sources. then, the chore is what gets render surfaces back into shape. otherwise, we churn'; 'I accept that having limits on these control surfaces is a part of best practice for agent guidance, but I can't be stopping to trim them at every turn.' DIVISION OF LABOUR (binding): ordinary sessions ADD to sources via gz content remember and never resize a render surface; instructions-files-diet v3.0.0 is the only phase that trims, and it recommends rather than decides, consulting the operator before the first edit; operator-on-demand is a first-class trigger alongside the cadence. WHY A GATE HAS NOTHING TO BITE ON, structurally rather than as a concession: the per-turn surface is not live-rendered. sync_agents_md plays back a Gate-5-attested rendition verbatim from .gzkit/renditions/AGENTS.md/
2026-09-19¶
2026-09-19 (operator ruling, verbatim: 'make target 20k'): the doctrine DESTINATION for root AGENTS.md moves 15,000 → 20,000 chars. The ENFORCED budgets are UNCHANGED — AGENTS.md 50000, CLAUDE.md 15000, .claude/rules/*.md 30000 in data/instructions_files_budget.json, advisory until 1.0 under the 2026-08-17 ruling. The destination is recorded in docs/governance/agents-md-doctrine.md § Budget targets, which is edited in the same commit. Measured at the ruling: AGENTS.md 19,872 B, fully generated from the corpus, so the destination is MET on its date. Context: after the 2026-09-17/18 corpus rewrite (48,511 → 19,872 B) the remaining distance to 15,000 was held by ten scorecard rows gz validate --bullet-retention pins verbatim (handoff 20260918T112540Z, item 1), with about 2,400 B recoverable if freed and the file still landing near 17.4 KB — reaching 15,000 would have required trimming § Operator Doctrine and § Gate Covenant, which is operator-owned verbatim canon. OBPI-0.35.0-10 stands on its own merits (classification read from the live corpus entry); it is no longer owed for size. Earlier entries that name '<15k' state the destination true on their own dates. Program record: docs/governance/control-surface-overhaul.md.
2026-09-19 (2)¶
2026-09-19 (second ruling, same day — REFINES the entry above; enforced budgets still UNCHANGED): operator verbatim: 'state a range: 15K is ideal, 20K a ceiling'. The doctrine destination for root AGENTS.md is a RANGE, not one number: 15,000 chars is the ideal the diet works toward, 20,000 chars is the ceiling the surface does not pass. At 19,872 B the file is under the ceiling with 128 B of headroom and 4,872 B above the ideal, so the ceiling is met and the ideal is not. What this changes in practice: new canon cannot be added to root without removing or compressing something, and the distance to the ideal remains diet work — the rows gz validate --bullet-retention pins (OBPI-0.35.0-10) and the wording of § Operator Doctrine and § Gate Covenant, which is the operator's. Nothing mechanical reads the range yet: data/instructions_files_budget.json carries one number per file. Recorded in docs/governance/agents-md-doctrine.md § Budget targets in the same commit.
2026-09-19 (3)¶
2026-09-19 (third ruling, same day — the first change to an ENFORCED value since 2026-07-06; operator verbatim: 'make agents budget 20k'): root AGENTS.md's enforced per-file budget moves 50000 → 20000 chars in data/instructions_files_budget.json. This CLOSES the gap the second ruling of this day named in its own last sentence — 'Nothing mechanical reads the range yet: data/instructions_files_budget.json carries one number per file.' The doctrine ceiling and the enforced budget are now the same number, so the 20,000-char ceiling is mechanical rather than prose. Every prior entry in this file since 2026-07-28 moved a destination or a consequence; this one moves the number the audit actually reads. CLAUDE.md (15000) and .claude/rules/*.md (30000) are UNCHANGED and remain above their destinations — the ruling named AGENTS.md only.
MEASURED AT THE RULING: AGENTS.md 19,787 chars / 19,872 B. The audit counts CHARS, not bytes (len(target.read_text(encoding='utf-8')) in src/gzkit/governance/trust_audits/instructions_files_budget.py), so live headroom is 213 chars (1.07%), not the 128 B the byte figure suggests — the two diverge by 85 because of non-ASCII glyphs in the rendered surface. CLAUDE.md 2,006 chars against 15000; largest rule file tests.md 10,636 chars against 30000. Nothing is over budget at this entry and gz validate --instructions-files-budget passes. No packaged default, test, or other module carries the old 50000 — the JSON overlay is the only place it lived.
CONSEQUENCE UNCHANGED — STILL ADVISORY. The 2026-08-17 stay ('temporary stay of all control surface budget limits until version 1.0. I want to be warned, and we may lift the limits as needed, but no blockers.') is untouched: an overrun emits a WARNING to stderr carrying its char distance and the diet pointer, and cannot change an exit code. Tightening the number tightens WHEN the warning fires, never WHETHER it blocks. Restoring fail-closed at 1.0 remains the exit condition, on the unchanged 2026-07-28 ground that strictness is earned by the mechanism that discharges it.
PRECEDENT CONSIDERED, AND WHY IT DOES NOT TRANSFER: the 2026-07-28 entry records that the 2026-06-30 setting of 231 chars (0.7%) headroom was 'blown out within a week', and 213 chars is the same shape of margin. The failure mode that produced that outcome no longer exists. On 2026-06-30 the surface was hand-edited and any session could inflate it; since the 2026-08-17 fifth ruling the rendered surface is Gate-5-attested playback from .gzkit/renditions/AGENTS.md/<consumer>.md and CANNOT drift on its own — ordinary sessions append to the corpus and move no rendered byte, and only an attested content commit changes the build. A tight budget therefore fires at the moment a new rendition is landed, which is the moment the operator is already reviewing size, rather than at an arbitrary turn mid-week. That is the cadence the fifth ruling asked for, now with a number behind it. If the margin does prove too tight in practice, the 2026-08-17 stay is exactly what makes that recoverable without a block.
WHAT THIS MEANS IN PRACTICE: new canon cannot land in root AGENTS.md without removing or compressing something, and the audit now says so at the ceiling instead of 30,213 chars later. The distance to the 15,000-char ideal is unchanged and remains diet work — the rows gz validate --bullet-retention pins (OBPI-0.35.0-10) and the operator-owned wording of § Operator Doctrine and § Gate Covenant.
COUPLED SURFACE moved in the same commit: docs/governance/agents-md-doctrine.md § Budget targets stated that the live enforced values are 'currently higher than these targets'. That stays true for CLAUDE.md and the rules glob and is now FALSE for AGENTS.md, whose enforced budget equals its ceiling; the section, its table header, and its trailing note were repaired to say which rows are enforced and which remain destinations. Reading convention unchanged: this is the LAST entry, so it states what is enforced today.
2026-09-24¶
2026-09-24 (operator ruling, verbatim: 'D — hold under the stay'; enforced budgets UNCHANGED): root AGENTS.md stays over its 20,000-char budget under the 2026-08-17 advisory stay, and the overrun is closed by ADR-0.35.0-canon-entry-corpus-landing § Decision 3 (corpus-owned sections, decrease-only unowned-byte ratchet, 15,000-char destination) rather than by a trim, a re-tier or a budget change. Chosen over re-tiering named invariant entries to compressible, retiring or merging invariant canon, and raising the number.
MEASURED AT THE RULING: AGENTS.md 21,792 chars, 1,792 over the budget, warning and exit 0. It crossed the 2026-09-19 ceiling in the 2026-09-23 session (21,569 chars when the 2026-09-24 session opened); two attested invariant entries added on 2026-09-24 brought 223 more. The latest composition_candidate_emitted event reads invariant_bytes 20,984 and compressible_bytes 105 at setpoint lite: the invariant floor on its own exceeds the budget, so the instructions-files-diet chore cannot reach it (its § 2(c) stops at a gap larger than the compressible budget).
WHAT THIS REFINES: the second 2026-09-19 ruling set 20,000 chars as the ceiling the surface does not pass and said new canon cannot land without removing or compressing something. The surface now passes it, by attested canon. This ruling holds that state knowingly rather than restoring it by trimming: the ceiling remains the doctrine target, the audit keeps warning at every build, and nothing blocks until the stay ends at 1.0. New canon still lands only through the attested content chain, so the operator sees the growth at each landing.
OPEN AT THIS ENTRY: REQ-0.0.54-01-03 asserts the retired values 15000 / 4000 / 16000 against the live 20000 / 15000 / 30000; its escalation stands as a separate operator act. CLAUDE.md 2,167 chars against 15000 and the rule files are inside their budgets.
2026-09-24 (2) — stay-site census¶
A DATED RECORD, not a standing fact: the sites that apply the 2026-08-17 stay, swept by hand at 54bb8873b on 2026-09-24. Operator ruling on GHI #1087's shape, verbatim: 'C with the Movement D amendment'. Nothing re-runs this census. Sweep again, and add a dated entry, whenever a ruling books, lifts or retargets a control-surface budget stay. The mechanism that would make the sweep resolvable is Movement D's Rulings become first-class box in docs/governance/build-to-1.0-campaign-2026-09-20.md.
RULINGS IN SCOPE: four rulings in .gzkit/handoffs/rulings.jsonl relax a control-surface enforcement, and all four concern these budgets. They are the 2026-08-17 stay (booked 2026-08-22); 2026-08-29, which took the size and trim gates out of gz check; 2026-08-30, which kept the Codex delivery-cap breach advisory; and 2026-09-24 above ('D — hold under the stay'). Rows carry no ruling id, so each is named here by its date.
AUDIT LAYER, all four warn and return no findings:
| Site | State at 54bb8873b |
|---|---|
src/gzkit/governance/trust_audits/instructions_files_budget.py |
the overrun goes to stderr; return [] |
src/gzkit/governance/trust_audits/agents_md_map_conformance.py |
_check_budget warns and returns []; criteria (a)–(c) still fail closed |
src/gzkit/governance/trust_audits/surface_delivery_witness.py |
vendor-cap distance goes to stderr and never changes the exit code |
src/gzkit/governance/trust_audits/codex_delivery_witness.py |
always returns an empty list |
OBSERVED: with AGENTS.md at 21,792 chars against 20,000, gz validate --instructions-files-budget and gz validate --agents-md-map-conformance each print one WARNING and exit 0.
TEST LAYER: GHI #1086 found the stay missing from this layer. tests/governance/test_agents_md_map_doctrine.py (@covers("REQ-0.0.54-01-03")) now asserts the stay against the live tree. A grep of tests/ for size assertions against control surfaces finds no other ceiling. The live overrun has passed the unit suite in CI since cd33a7665.
DELIBERATELY STILL ENFORCING (a valid control, not a violation): the project-doc budget ceiling in the same test rejects a configured AGENTS.md budget above it. That ceiling guards against Codex's silent truncation (GHI #519), which the stay does not reach.
The escalation of REQ-0.0.54-01-03 that the entry above leaves open was set aside by the operator on 2026-09-24 (verbatim: 'set it aside'). The REQ's wording still states the retired values; its covering test asserts the stay.