Build persistent memory for AI code agents to prevent repeat mistakes

Atlas Ledger is a companion to the atlas-contract skill that gives the Atlas series a project memory: when a drift is caught, it distills the lesson into a permanent WHEN/DON'T/INSTEAD clause and, after user confirmation, writes it to a project-local Atlas.md file. atlas-contract defends the goal within one conversation but starts from zero every time; this skill closes that gap so the defense line thickens with each caught mistake instead of resetting. Its six-step distillation: state the drift as observable facts rather than guessed motive; draft a clause abstracting the situation (WHEN) while keeping the wrong action (DON'T) and correct action (INSTEAD) concrete; run four acceptance gates, Actionability, Replay, Generalization, and Over-reach, recording nothing unless a candidate passes all four; record a first occurrence as a provisional Observation and only promote a repeat to a confirmed Clause, unless the drift is high-severity, such as mock data passed off as real, hiding a required feature, weakening tests, or data loss, which confirms on first occurrence; propose the clause and stop for explicit user confirmation before writing; and merge overlapping clauses rather than only appending, capping confirmed clauses at 15.

It runs automatically when atlas-contract's Final Audit records a hard deviation, and can also be triggered by a Post Review where the user says the result was wrong or mocked, a Phase Check catching a recurring error class, or an explicit "record this so it doesn't happen again." It does not run on clean completions, optimization requests, ordinary code review, style preferences, or general takeaways - there is nothing to enforce in those.

Atlas.md lives once at the workspace root; its machine keys (WHEN/DON'T/INSTEAD, clause IDs like L1/O1, severity, Source, RETIRED, and the Confirmed Clauses/Provisional Observations headers) always stay in English so atlas-contract can parse them reliably, while the clause content and every user-facing process label are written in the user's own language. Confirmed clauses can be retired by the user at any time, and a clause overridden by the user twice gets flagged review: stale for likely retirement - the ledger is designed to shrink and merge, not just grow.

The read-back half lives in atlas-contract itself: before building a new Goal Contract, it reads only the Confirmed Clauses, never raw Observations, carries in at most 5 most relevant ones, converts each into a Must-Not-Do plus a required response, and shows them under "Carried-in Ledger Clauses." Ledger clauses are explicitly project defaults, not law - the user's current instruction or a higher-priority safety rule always overrides a carried-in clause rather than the ledger silently enforcing it.

Teams running the Atlas contract-and-audit workflow who want a caught mistake to become a standing, project-specific guardrail instead of a one-off correction that has to be re-explained every session, with human confirmation on every write since a wrong clause would silently shape every future contract. The skill is run by the same model it is meant to govern, so it can mis-distill or miss a drift worth recording; it raises the project's floor over time rather than guaranteeing it, which is why user confirmation on each clause is part of the design, not a formality.