<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/4.x/2026-10-31-1-charter-write-budget-for-repository-scale-projects/">
  <id>https://docs.spec-kitty.ai/adr/4.x/2026-10-31-1-charter-write-budget-for-repository-scale-projects/</id>
  <title>ADR: a charter-write budget for repository-scale projects, and why 2 s is not it</title>
  <updated>2026-10-31T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/4.x/2026-10-31-1-charter-write-budget-for-repository-scale-projects/"/>
  <summary>A charter write command is budgeted by a structural round-trip count and a ratio to the cost of reading the same project; the 2 s CLI budget stays for typical projects.</summary>
  <content type="html">&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-10-31&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; the mission’s own measurement and review; recorded for the operator to confirm or amend.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6506&quot;&gt;#6506&lt;/a&gt; — “charter activate/deactivate take 9-15 s on this repository, far over the 2 s CLI budget”. Mission &lt;code dir=&quot;auto&quot;&gt;charter-write-roundtrip-latency-01M68ZVK&lt;/code&gt;.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/charter/charter.md&lt;/code&gt; (“Performance and Scale”) sets a budget of &lt;strong&gt;under 2 seconds&lt;/strong&gt; for CLI operations, for &lt;em&gt;typical projects&lt;/em&gt;. On a project the size of this repository — a 165 KB,
1,937-line &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt; with 264 &lt;code dir=&quot;auto&quot;&gt;catalog.references&lt;/code&gt; — &lt;code dir=&quot;auto&quot;&gt;charter activate&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;charter deactivate&lt;/code&gt;
took 16-18 s (issue #6506). The issue asks for one of two things: bring them under 2 s, or &lt;strong&gt;record a
justified budget for repositories of this size&lt;/strong&gt;.&lt;/p&gt;
&lt;p&gt;The 2 s number cannot be met here, and the reason is arithmetic rather than a missing optimization:&lt;/p&gt;





















&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Operation&lt;/th&gt;&lt;th&gt;Measured median&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;charter list&lt;/code&gt; — a pure read that writes nothing and compiles nothing&lt;/td&gt;&lt;td&gt;&lt;strong&gt;2.62-2.77 s&lt;/strong&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;charter deactivate&lt;/code&gt; before this mission&lt;/td&gt;&lt;td&gt;16.65 s&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;charter deactivate&lt;/code&gt; after this mission&lt;/td&gt;&lt;td&gt;10.39 s&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;A pure read already costs more than the entire 2 s budget at this scale. No command that reads the
compiled charter can reach 2 s here; the read floor is the floor.&lt;/p&gt;
&lt;h2 id=&quot;where-the-time-went-and-what-this-mission-removed&quot;&gt;Where the time went, and what this mission removed&lt;/h2&gt;
&lt;p&gt;Wall-clock attribution of one &lt;code dir=&quot;auto&quot;&gt;deactivate&lt;/code&gt; run before the change (inclusive times, so rows nest):&lt;/p&gt;



































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Cost centre&lt;/th&gt;&lt;th&gt;Before&lt;/th&gt;&lt;th&gt;After&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;Compiled-charter write path (&lt;code dir=&quot;auto&quot;&gt;write_compiled_charter&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;9.14 s&lt;/td&gt;&lt;td&gt;&lt;strong&gt;2.79 s&lt;/strong&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;… owned-section prepare cycles per refresh&lt;/td&gt;&lt;td&gt;2&lt;/td&gt;&lt;td&gt;&lt;strong&gt;1&lt;/strong&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;… whole-document comparisons (&lt;code dir=&quot;auto&quot;&gt;yaml_documents_equal&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;≈3.4 s (2 × ≈1.2 s per render)&lt;/td&gt;&lt;td&gt;&lt;strong&gt;3 ms&lt;/strong&gt; for 19 calls&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Compiler pass (&lt;code dir=&quot;auto&quot;&gt;compile_charter&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;2.4-2.5 s&lt;/td&gt;&lt;td&gt;2.4-2.5 s (unchanged, out of scope)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Read floor (start-up, project load, charter read)&lt;/td&gt;&lt;td&gt;≈2.6 s&lt;/td&gt;&lt;td&gt;≈2.7 s (unchanged)&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;Two causes, both structural rather than “this repository is big”:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;write_compiled_charter&lt;/code&gt; refreshed the two derived sections (&lt;code dir=&quot;auto&quot;&gt;catalog&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;metadata&lt;/code&gt;) with two
sequential single-section writes, each of which observed, loaded, rendered and verified the whole
document. One recompile therefore paid the whole cycle twice.&lt;/li&gt;
&lt;li&gt;The document-equality check, which the writer uses to return the original bytes unchanged and to
guard against a lossy render, serialised the entire value and re-parsed it whenever &lt;code dir=&quot;auto&quot;&gt;==&lt;/code&gt; failed —
about 1.2 s per comparison on this document, twice per render.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Both are fixed: one prepared write carries every owned section, and the equality check walks the two
values structurally, round-tripping only the values that genuinely differ. Measured whole-document
comparison cost fell from 1,189 ms to 1.0-3.7 ms with no change of verdict.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Interleaved before/after measurement&lt;/strong&gt; (one frozen checkout per side, same launcher, five rounds,
alternating order, project seeded from this repository’s own &lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt;):&lt;/p&gt;























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;&lt;/th&gt;&lt;th&gt;floor (&lt;code dir=&quot;auto&quot;&gt;charter list&lt;/code&gt;)&lt;/th&gt;&lt;th&gt;command (&lt;code dir=&quot;auto&quot;&gt;charter deactivate&lt;/code&gt;)&lt;/th&gt;&lt;th&gt;ratio&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;before&lt;/td&gt;&lt;td&gt;2.62 s&lt;/td&gt;&lt;td&gt;16.65 s&lt;/td&gt;&lt;td&gt;6.35&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;after&lt;/td&gt;&lt;td&gt;2.77 s&lt;/td&gt;&lt;td&gt;10.39 s&lt;/td&gt;&lt;td&gt;3.75&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;The command improved &lt;strong&gt;1.60×&lt;/strong&gt;; the floor did not move, as expected — it does not touch the write path.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;For repositories of this size, a command that recompiles and rewrites the compiled charter is
budgeted by two things, in this order of authority:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;A structural budget: at most 6 whole-document round trips of the governed charter per recompile,
ratchet-only-down.&lt;/strong&gt; This is exact, deterministic, load-independent, and it runs on every pull
request (&lt;code dir=&quot;auto&quot;&gt;tests/charter/activation/test_charter_write_roundtrips.py&lt;/code&gt;). It is the regression gate.
The pre-mission shape measured 18 on the same fixture; 6 is what one merged write cycle needs, and
the first two of the six read identical bytes, so a future change can lower the number and should.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A runaway guard: at most 8× the cost of reading the same project&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;charter list&lt;/code&gt;), measured
interleaved in the same run (&lt;code dir=&quot;auto&quot;&gt;tests/performance/test_charter_write_repo_scale_timing.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;CHARTER_WRITE_RATIO_LIMIT&lt;/code&gt;). Observed 3.4-4.6. This limit deliberately does &lt;strong&gt;not&lt;/strong&gt; try to
discriminate the 1.6× improvement: at 4-6× its own floor the command’s variance dominates the
ratio instead of cancelling against it, and the measured pre-fix (3.5-6.8) and post-fix (3.4-4.6)
ranges overlap across series taken under different machine load. A tighter limit would false-red on
the clean tail — the failure mode ADR
&lt;a href=&quot;/adr/4.x/2026-10-05-2-runner-relative-performance-budgets/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-10-05-2&lt;/code&gt;&lt;/a&gt; exists to stop, and the
reason #3787 retired its own ceiling after four ratchets.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The charter’s &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C; 2 s&lt;/code&gt; budget is &lt;strong&gt;not&lt;/strong&gt; changed: it is correct for typical projects, and renegotiating
it is the operator’s call, not a mission’s.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Reaching 2 s here would require&lt;/strong&gt; an incremental catalog update instead of a full recompile. The
changelog entry for #4785 already accepted “~2.4-2.5 s” for the single-authority &lt;code dir=&quot;auto&quot;&gt;compile_charter&lt;/code&gt;
resolution — deliberately, over a competing minimal writer that the charter’s single-canonical-authority
principle forbids — so the compiler is not cheap to trim without re-architecting it. That work is
explicitly out of scope for this mission and would be its own decision record.&lt;/p&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Record a structural budget plus a runaway ratio (chosen).&lt;/strong&gt; The exact measure gates; the coarse
measure bounds catastrophe; the wall clock is recorded as a measurement, not asserted.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Delete the two whole-document equality checks&lt;/strong&gt; (the largest single term). Rejected: one is what
makes a no-op recompile return the original bytes, the other is the “cannot preserve YAML aliases
or section boundaries” guard. Removing either trades a governed invariant for speed.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Raise the charter’s 2 s budget.&lt;/strong&gt; Rejected: it is an operator-owned governance statement, correct
for typical projects. This record adds a budget for a different size band; it does not replace one.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Assert an absolute seconds budget at repository scale.&lt;/strong&gt; Rejected by ADR &lt;code dir=&quot;auto&quot;&gt;2026-10-05-2&lt;/code&gt;, on
evidence: a bare &lt;code dir=&quot;auto&quot;&gt;--help&lt;/code&gt; moved 1.14 s → 1.95 s between nightly runs with no product change.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Make the repository-scale timing test the regression gate.&lt;/strong&gt; Rejected on measurement, not
preference: see the overlapping ranges above. A gate that cannot separate the states it exists to
separate is noise with a red light.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Incremental catalog update (re-architect the compiler).&lt;/strong&gt; Rejected as out of scope; it is the
only path to 2 s, and it needs its own mission and its own decision record.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;A charter write command at this scale now costs about 10 s where it cost about 17 s. &lt;code dir=&quot;auto&quot;&gt;charter generate&lt;/code&gt;, skill rendering and skill installation share the cheaper document comparison and get the
same reduction for free.&lt;/li&gt;
&lt;li&gt;The exact gate is a &lt;strong&gt;count&lt;/strong&gt;, so it runs on every pull request and cannot be flaked by other work
on a shared runner. A change that adds a document round trip fails immediately and names the count.&lt;/li&gt;
&lt;li&gt;The ratio guard catches a pathologically slow but structurally unchanged write path — a class the
count cannot see — and records the floor and command medians in its failure message.&lt;/li&gt;
&lt;li&gt;A regression that slows the read floor and the write path alike is invisible to the ratio; the count
covers the write path, and nothing here covers start-up (the existing start-up tests do).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The 6 is a ratchet on today’s structure, not a theoretical floor.&lt;/strong&gt; Lowering it is a improvement;
raising it needs a measurement recorded here first.&lt;/li&gt;
&lt;li&gt;The budget is stated per repository size band. A project with a much smaller &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt; will be
far closer to the 2 s line, and the count budget applies unchanged.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;calibration&quot;&gt;Calibration&lt;/h3&gt;
&lt;p&gt;Machine: a shared development VM with up to twenty concurrent agent runs, Python 3.11.15. Fixture: a
scratch git project holding a copy of this repository’s own &lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt; (165,004-byte
&lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt;, 264 references) plus &lt;code dir=&quot;auto&quot;&gt;packs/&lt;/code&gt;. Method: one frozen checkout per side, the same launcher
for both, &lt;code dir=&quot;auto&quot;&gt;--repo-root&lt;/code&gt; so the working directory cannot change the work, &lt;code dir=&quot;auto&quot;&gt;XDG_CACHE_HOME&lt;/code&gt; isolated,
rounds alternating base/head order.&lt;/p&gt;



































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Series&lt;/th&gt;&lt;th&gt;Floor median&lt;/th&gt;&lt;th&gt;Command median&lt;/th&gt;&lt;th&gt;Ratio&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;before, 5 rounds interleaved&lt;/td&gt;&lt;td&gt;2.62 s&lt;/td&gt;&lt;td&gt;16.65 s&lt;/td&gt;&lt;td&gt;6.35&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;after, 5 rounds interleaved&lt;/td&gt;&lt;td&gt;2.77 s&lt;/td&gt;&lt;td&gt;10.39 s&lt;/td&gt;&lt;td&gt;3.75&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;after, 3 rounds (heavier concurrent load)&lt;/td&gt;&lt;td&gt;2.76 s&lt;/td&gt;&lt;td&gt;12.67 s&lt;/td&gt;&lt;td&gt;4.58&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;before, 2 rounds (lighter load)&lt;/td&gt;&lt;td&gt;2.95-3.19 s&lt;/td&gt;&lt;td&gt;11.15-13.09 s&lt;/td&gt;&lt;td&gt;3.5-4.4&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;The load sensitivity in the last two rows is the evidence for decision 5: the same code produces
ratios from 3.4 to 6.8 depending on what else the machine is doing.&lt;/p&gt;
&lt;h2 id=&quot;questions-this-record-leaves-to-the-operator&quot;&gt;Questions this record leaves to the operator&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Is 8× the read floor the right runaway bound, or should it be tighter now that the count carries the
real gate?&lt;/li&gt;
&lt;li&gt;Should the incremental-catalog-update work (the only route to 2 s at this scale) be chartered as its
own mission?&lt;/li&gt;
&lt;/ol&gt;</content>
</entry>
