<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-04-17-2-charter-synthesizer-atomicity/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-04-17-2-charter-synthesizer-atomicity/</id>
  <title>Charter Synthesizer — Atomicity via Stage + Ordered Promote + Manifest-Last Commit</title>
  <updated>2026-04-17T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-04-17-2-charter-synthesizer-atomicity/"/>
  <summary>Synthesis writes into a staging tree, validates, then promotes files in a fixed order with the manifest last, so a crash cannot leave a half-promoted doctrine tree.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Phase 3 writes two separate directory trees during synthesis:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Content&lt;/strong&gt; under &lt;code dir=&quot;auto&quot;&gt;.kittify/doctrine/&lt;/code&gt; — directives, tactics, styleguides, project DRG graph. Consumed by &lt;code dir=&quot;auto&quot;&gt;DoctrineService&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_drg_helpers&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;DirectiveRepository&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;TacticRepository&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;StyleguideRepository&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Bookkeeping&lt;/strong&gt; under &lt;code dir=&quot;auto&quot;&gt;.kittify/charter/&lt;/code&gt; — per-artifact provenance sidecars, the synthesis manifest (commit-marker), and ephemeral staging.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;A partial write state — content without provenance, or provenance without the manifest — is worse than no synthesis at all: consumers see partial data and behave unpredictably. Crucially, any process that is interrupted (SIGKILL, disk full, machine crash) between the first file write and the final manifest write must leave the system in a recoverable state, not an inconsistent one.&lt;/p&gt;
&lt;p&gt;A naive sequential-write approach (“write content files, then write provenance, then write manifest”) cannot guarantee this. We need an atomicity model that:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Validates everything before touching the live tree.&lt;/li&gt;
&lt;li&gt;Promotes with minimal window for partial live-tree state.&lt;/li&gt;
&lt;li&gt;Provides a canonical “this bundle is committed and valid” marker.&lt;/li&gt;
&lt;li&gt;Preserves diagnostic state for operator recovery after any failure.&lt;/li&gt;
&lt;/ol&gt;
&lt;hr&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Zero partial writes under &lt;code dir=&quot;auto&quot;&gt;.kittify/doctrine/&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;.kittify/charter/&lt;/code&gt; — any failure must leave the live tree either as-before or fully promoted (C-002, FR-005, NFR-008).&lt;/li&gt;
&lt;li&gt;Fail-closed: validation failures (schema, DRG, path-guard) produce no live-tree mutations (FR-008, NFR-004).&lt;/li&gt;
&lt;li&gt;Interrupted-run recovery: operator should be able to diagnose what went wrong without re-running from scratch (EC-5).&lt;/li&gt;
&lt;li&gt;Idempotent re-run: running synthesis again on unchanged inputs produces byte-identical output (FR-014, NFR-006).&lt;/li&gt;
&lt;li&gt;Performance: fail-closed from detection to return &amp;#x3C; 5s (NFR-004). This is a correctness problem at kilobyte scale, not a throughput problem.&lt;/li&gt;
&lt;li&gt;Cross-platform: &lt;code dir=&quot;auto&quot;&gt;os.replace&lt;/code&gt; is atomic-on-POSIX, atomic-rename-on-Windows (per Python docs) — acceptable for our scale.&lt;/li&gt;
&lt;/ul&gt;
&lt;hr&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;h3 id=&quot;option-a--pure-in-memory-staging-then-sequential-write-rejected&quot;&gt;Option A — Pure in-memory staging, then sequential write (rejected)&lt;/h3&gt;
&lt;p&gt;Stage all artifacts in memory. Validate. Then write sequentially: content files, provenance sidecars, manifest.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Rejected&lt;/strong&gt;: No recovery story for SIGKILL or disk-full mid-write. A partially written set of content files under &lt;code dir=&quot;auto&quot;&gt;.kittify/doctrine/&lt;/code&gt; that lacks a manifest is a silently broken bundle that consumers may partly load.&lt;/p&gt;
&lt;h3 id=&quot;option-b--journal--replay-rejected&quot;&gt;Option B — Journal + replay (rejected)&lt;/h3&gt;
&lt;p&gt;Write a WAL (write-ahead log) recording intended operations. On failure, replay journal on next run to reach committed state. On success, delete journal.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Rejected&lt;/strong&gt;: Correct but over-engineered for kilobyte-scale writes. Dragged significant complexity into Phase 3 (journal schema, replay logic, journal GC) without buying meaningful recovery benefit over Option C. Flagged as a future path if write scale grows by orders of magnitude.&lt;/p&gt;
&lt;h3 id=&quot;option-c--stage--ordered-promote--manifest-last-chosen&quot;&gt;Option C — Stage + ordered promote + manifest-last (chosen)&lt;/h3&gt;
&lt;p&gt;Every synthesis run stages &lt;strong&gt;all&lt;/strong&gt; writes inside a single staging root at &lt;code dir=&quot;auto&quot;&gt;.kittify/charter/.staging/&amp;#x3C;runid&gt;/&lt;/code&gt;. The staging dir mirrors the final layout with internal &lt;code dir=&quot;auto&quot;&gt;doctrine/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;charter/&lt;/code&gt; subtrees. Full validation (schema, DRG, path-guard) runs against the staged tree. Only on pass does the promote step begin.&lt;/p&gt;
&lt;p&gt;Promote uses ordered &lt;code dir=&quot;auto&quot;&gt;os.replace&lt;/code&gt; calls:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Content files to &lt;code dir=&quot;auto&quot;&gt;.kittify/doctrine/&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Provenance sidecars to &lt;code dir=&quot;auto&quot;&gt;.kittify/charter/provenance/&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Synthesis manifest to &lt;code dir=&quot;auto&quot;&gt;.kittify/charter/synthesis-manifest.yaml&lt;/code&gt; — &lt;strong&gt;last&lt;/strong&gt;.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The manifest is the authoritative commit marker. A reader that encounters a missing or internally inconsistent manifest treats the synthesized content as partial-and-rerunable, not authoritative.&lt;/p&gt;
&lt;p&gt;On success: staging dir wiped.
On failure at any stage: staging dir preserved as &lt;code dir=&quot;auto&quot;&gt;.staging/&amp;#x3C;runid&gt;.failed/&lt;/code&gt; with a &lt;code dir=&quot;auto&quot;&gt;cause.yaml&lt;/code&gt; diagnostic. Operator runs &lt;code dir=&quot;auto&quot;&gt;charter synthesize&lt;/code&gt; again to produce a fresh staging dir and promote.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option: C — Stage + ordered promote + manifest-last.&lt;/strong&gt;&lt;/p&gt;
&lt;h3 id=&quot;run-lifecycle&quot;&gt;Run lifecycle&lt;/h3&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;plaintext&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;CREATED  ──▶  STAGING  ──▶  VALIDATING  ──▶  PROMOTING  ──▶  COMMITTED&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;   &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│              │               │               │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;   &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│              ▼               ▼               ▼&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;   &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│           FAILED          FAILED          FAILED&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;   &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│         (adapter/       (schema/         (os.replace&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;   &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│          schema)         DRG/path-        or manifest&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;   &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│                          guard)           error)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;   &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;▼&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;ABORTED&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;CREATED&lt;/code&gt; → new staging dir opened, no writes yet.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;STAGING&lt;/code&gt; → writes inside staging only (never in live tree; path guard enforces this).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;VALIDATING&lt;/code&gt; → schema + DRG + path-guard + cross-checks on staged tree. Any failure → &lt;code dir=&quot;auto&quot;&gt;FAILED&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;PROMOTING&lt;/code&gt; → ordered &lt;code dir=&quot;auto&quot;&gt;os.replace&lt;/code&gt; of artifact + provenance files; finally manifest.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;COMMITTED&lt;/code&gt; → manifest written; staging dir wiped.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;FAILED&lt;/code&gt; → staging dir preserved as &lt;code dir=&quot;auto&quot;&gt;.staging/&amp;#x3C;runid&gt;.failed/&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;cause.yaml&lt;/code&gt; for operator diagnosis.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;resynthesis-lifecycle&quot;&gt;Resynthesis lifecycle&lt;/h3&gt;
&lt;p&gt;Identical to run lifecycle above, but &lt;code dir=&quot;auto&quot;&gt;STAGING&lt;/code&gt; stages only the targeted artifacts. &lt;code dir=&quot;auto&quot;&gt;PROMOTING&lt;/code&gt; replaces only those files. Manifest is &lt;strong&gt;rewritten&lt;/strong&gt; (not appended) with the new &lt;code dir=&quot;auto&quot;&gt;run_id&lt;/code&gt; and updated entries for regenerated artifacts; untouched artifacts retain prior &lt;code dir=&quot;auto&quot;&gt;content_hash&lt;/code&gt; in the manifest.&lt;/p&gt;
&lt;h3 id=&quot;manifest-authority-rule&quot;&gt;Manifest authority rule&lt;/h3&gt;
&lt;p&gt;The live tree is authoritative IFF:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/charter/synthesis-manifest.yaml&lt;/code&gt; exists, AND&lt;/li&gt;
&lt;li&gt;Every &lt;code dir=&quot;auto&quot;&gt;content_hash&lt;/code&gt; listed in the manifest matches the SHA-256 of the file at &lt;code dir=&quot;auto&quot;&gt;path&lt;/code&gt;.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Readers that do not verify condition (2) before trusting the live tree are violating this contract.&lt;/p&gt;
&lt;h3 id=&quot;path-guard-integration&quot;&gt;Path-guard integration&lt;/h3&gt;
&lt;p&gt;All staging writes go through &lt;code dir=&quot;auto&quot;&gt;PathGuard&lt;/code&gt;. The staging dir (&lt;code dir=&quot;auto&quot;&gt;.kittify/charter/.staging/&amp;#x3C;runid&gt;/&lt;/code&gt;) is under &lt;code dir=&quot;auto&quot;&gt;.kittify/charter/&lt;/code&gt; — already in the default allowlist. Promote writes go through &lt;code dir=&quot;auto&quot;&gt;PathGuard.replace()&lt;/code&gt; which verifies both src and dst before calling &lt;code dir=&quot;auto&quot;&gt;os.replace&lt;/code&gt;. No live-tree write can bypass the guard.&lt;/p&gt;
&lt;h3 id=&quot;failed-directory-preservation&quot;&gt;.failed directory preservation&lt;/h3&gt;
&lt;p&gt;On any FAILED transition, the staging dir is renamed to &lt;code dir=&quot;auto&quot;&gt;.staging/&amp;#x3C;runid&gt;.failed/&lt;/code&gt; (not deleted). A &lt;code dir=&quot;auto&quot;&gt;cause.yaml&lt;/code&gt; diagnostic is written into the failed dir recording the exception class, message, and traceback. Operators can inspect, repair, and rerun. The &lt;code dir=&quot;auto&quot;&gt;.staging/&lt;/code&gt; subtree is in &lt;code dir=&quot;auto&quot;&gt;.gitignore&lt;/code&gt; so failed dirs are never accidentally committed.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;h3 id=&quot;positive&quot;&gt;Positive&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Manifest-last provides a single, checkable “committed” signal that consumers and &lt;code dir=&quot;auto&quot;&gt;bundle validate&lt;/code&gt; can rely on without walking the content tree.&lt;/li&gt;
&lt;li&gt;Staging under &lt;code dir=&quot;auto&quot;&gt;.kittify/charter/.staging/&lt;/code&gt; means content files under &lt;code dir=&quot;auto&quot;&gt;.kittify/doctrine/&lt;/code&gt; are never touched during failed runs. Legacy projects and consuming tools are never exposed to partial content.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;os.replace&lt;/code&gt; is atomic at the OS level on POSIX and Windows — the promote window is O(file_count) individual atomic renames, not a database transaction. At kilobyte scale and tens of files, this is acceptable.&lt;/li&gt;
&lt;li&gt;Preserved &lt;code dir=&quot;auto&quot;&gt;.failed/&lt;/code&gt; dirs give operators diagnostic information without requiring a re-run to reproduce the failure.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;negative&quot;&gt;Negative&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;A SIGKILL during the PROMOTING phase after some &lt;code dir=&quot;auto&quot;&gt;os.replace&lt;/code&gt; calls have succeeded but before the manifest is written leaves the live tree in a partial state. The manifest is absent → readers treat the bundle as partial-and-rerunable. Operator must re-run synthesis. This is acceptable given the write scale.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;.failed/&lt;/code&gt; dirs accumulate if synthesis fails repeatedly without manual cleanup. Mitigated by a &lt;code dir=&quot;auto&quot;&gt;charter doctor&lt;/code&gt; extension (flagged as follow-up, out of scope for this mission) and a staging-dir size warning in &lt;code dir=&quot;auto&quot;&gt;bundle validate&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;neutral&quot;&gt;Neutral&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;StagingPromoteError&lt;/code&gt; is raised when an &lt;code dir=&quot;auto&quot;&gt;os.replace&lt;/code&gt; or manifest write fails during promote; orchestration preserves the failed dir before raising. The CLI surfaces this error with the failed-dir path for diagnosis.&lt;/li&gt;
&lt;/ul&gt;
&lt;hr&gt;
&lt;h2 id=&quot;path-guard-implementation-note&quot;&gt;Path Guard Implementation Note&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;src/charter/synthesizer/path_guard.py&lt;/code&gt; wraps every filesystem write method used by the synthesizer (&lt;code dir=&quot;auto&quot;&gt;write_text&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;write_bytes&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;replace&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;mkdir&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;rmtree&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;rename&lt;/code&gt;). A lint-style test (&lt;code dir=&quot;auto&quot;&gt;test_path_guard.py&lt;/code&gt;) greps &lt;code dir=&quot;auto&quot;&gt;src/charter/synthesizer/&lt;/code&gt; for direct write primitives (&lt;code dir=&quot;auto&quot;&gt;open(..., &apos;w&apos;)&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;Path.write_text&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;Path.write_bytes&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;shutil.move&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;os.replace&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;os.rename&lt;/code&gt;) outside &lt;code dir=&quot;auto&quot;&gt;path_guard.py&lt;/code&gt; and fails if any are found. This makes path-guard bypass a CI regression (R-10).&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;related-decisions&quot;&gt;Related Decisions&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;ADR-2026-04-17-1&lt;/strong&gt; — Adapter seam and fixture keying.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;KD-5&lt;/strong&gt; — Fail-closed path guard integrated at write seam.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;KD-2&lt;/strong&gt; — Atomicity model (this ADR documents the implementation of KD-2).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;DIRECTIVE_003&lt;/strong&gt; — Decision documentation policy.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Plan: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/phase-3-charter-synthesizer-pipeline-01KPE222/plan.md&lt;/code&gt; §KD-2, §Risks &amp;#x26; Premortem R-7&lt;/li&gt;
&lt;li&gt;Data model: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/phase-3-charter-synthesizer-pipeline-01KPE222/data-model.md&lt;/code&gt; §E-6, §E-9&lt;/li&gt;
&lt;li&gt;Spec: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/phase-3-charter-synthesizer-pipeline-01KPE222/spec.md&lt;/code&gt; §FR-005, §FR-008, §FR-014, §FR-016, §NFR-006, §NFR-008, §US-5, §EC-5&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;amendment-2026-10-30-preserved-failed-dirs-are-bounded-to-the-newest-three-6723&quot;&gt;Amendment 2026-10-30: preserved &lt;code dir=&quot;auto&quot;&gt;.failed&lt;/code&gt; dirs are bounded to the newest three (#6723)&lt;/h2&gt;
&lt;p&gt;The &lt;code dir=&quot;auto&quot;&gt;.failed&lt;/code&gt; preservation above kept every failed run, so a repeatedly-refused project accumulated one directory per attempt (#4226 counted 15, then 16, on one repository). Now, after the current run’s failure is written, only the newest three preserved &lt;code dir=&quot;auto&quot;&gt;.staging/*.failed/&lt;/code&gt; directories are kept (&lt;code dir=&quot;auto&quot;&gt;DEFAULT_KEEP_FAILED_RUNS&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;charter.activation.synthesizer.staging&lt;/code&gt;) and the older ones are removed through &lt;code dir=&quot;auto&quot;&gt;PathGuard.rmtree&lt;/code&gt;. Ordering is newest-first by directory modification time with the name as a tiebreak. The run being reported is never removed, a live &lt;code dir=&quot;auto&quot;&gt;.staging/&amp;#x3C;runid&gt;/&lt;/code&gt; is never a candidate, and a symbolic link named &lt;code dir=&quot;auto&quot;&gt;*.failed&lt;/code&gt; is never followed or removed. The diagnostic value under Consequences is unchanged for the latest refusals, and the disk cost of repeated refusals is bounded.&lt;/p&gt;</content>
</entry>
