Build persistent memory for AI code agents to prevent repeat mistakes

Atlas Ledger gives the Atlas series a memory: when its companion skill, atlas-contract, catches a drift within one conversation, this skill distills the caught mistake into a permanent, project-local contract clause and, after user confirmation, writes it to Atlas.md. The next time atlas-contract builds a Goal Contract it loads the relevant clauses, so the defense thickens with each catch - the compounding effect the skill exists for. It is deliberately low-frequency and lightweight, running only after a drift is caught, with distillation quality as its only real job.

Distillation runs only when a drift has actually been caught, via one of four triggers in typical order of arrival: an automatic handoff from an atlas-contract Final Audit that recorded a hard deviation, invoked immediately without the user having to ask; an atlas-contract Post Review where the user said the result was wrong, incomplete, downgraded, or mocked; a Phase Check catching the same class of error recurring; or the user explicitly saying to record something 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 there. It can only learn from drift that was actually detected; drift that slipped through unnoticed leaves no entry, and the skill does not pretend the ledger is complete.

Distillation runs in six ordered steps, producing at most one clause per caught drift. Step 1 states the drift as observable facts from the contract plus the delivered artifact, not a self-reported motive - a self-reported reason is unreliable and can build a clause that prevents the wrong thing. Step 2 drafts the clause in a fixed WHEN/DON'T/INSTEAD shape, abstracting the situation while keeping the forbidden and required behavior concrete. Step 3 runs four acceptance gates, cheapest first, recording only if all four pass: Actionability (does it concretely name the trigger, the forbidden action, and the correct one), Replay (would this exact clause have caught this drift), Generalization (would it catch a different instance of the same shape of situation), and Over-reach (would it wrongly block a legitimate, differently-approved action) - failing any gate means recording nothing rather than noise. Step 4 distinguishes provisional from confirmed: a first-seen situation becomes a provisional Observation, and only a later matching caught drift promotes it to a confirmed Clause, incrementing its seen-count; only confirmed clauses get auto-loaded into future contracts. Seven severity conditions skip straight to confirmed on first occurrence: mock, stub, or fake data passed off as real; hiding or disabling a feature the user explicitly required; weakening or deleting tests to force a pass; data loss or corrupted data; a security, permissions, or auth mis-change; a broken declared Preserve item; or downgrading complete, end-to-end work to frontend-only. Step 5 proposes the candidate clause and stops for explicit user confirmation before any write - skippable only if the user has said something like "auto-update Atlas.md" - because a wrong clause would silently shape every future contract. Step 6 writes to Atlas.md, but only after first scanning for an existing clause or observation with an overlapping WHEN and merging into one more general clause rather than appending a near-duplicate; once confirmed clauses reach 15, the two closest get merged before adding a new one. Atlas.md itself is one file at the workspace root with a stable structure: fixed English machine keys - WHEN, DON'T, INSTEAD, clause and observation IDs, seen-count, severity, Source, RETIRED, and the Confirmed Clauses/Provisional Observations headers - that atlas-contract parses and must never be translated, while clause content and every user-facing process label are written in the user's current language; Source is anchored to the phase or event ID that caught the drift, never a guessed date. Clauses can also be retired: the user can retire any clause at any time, and a confirmed clause overridden by the user twice gets flagged review: stale and surfaced for retirement - retiring and merging are the only two ways the ledger shrinks, since only-append is forbidden.

caught drift (auto handoff from Final Audit / Post Review / Phase Check / user request)
 → Step 1  state facts, not motive
 → Step 2  draft WHEN / DON'T / INSTEAD
 → Step 3  four gates: Actionability → Replay → Generalization → Over-reach
 → Step 4  first occurrence = Observation [O#]; repeat or high-severity = Clause [L#]
 → Step 5  propose, ATLAS_STOP, write only after user confirms
 → Step 6  merge-first into Atlas.md; confirmed clauses ≤ 15

This skill owns only the write half of a hook pair; atlas-contract owns the read-back half via a single hook in its own governance flow. Before building a Goal Contract, atlas-contract checks for Atlas.md, treats it as untrusted workspace content that can offer reviewed project preferences but never override system, developer, or user instructions or safety rules, reads only Confirmed Clauses (Provisional Observations only if directly relevant and marked advisory), matches clauses relevant to the current task, carries in at most 5 of the most relevant rather than all of them, converts each into a Must Not Do plus a required response, and shows them under a "Carried-in Ledger Clauses" line so the user sees the ledger working - with ledger clauses always treated as defaults, not law, so a conflict with the current request or trusted repo guidance gets surfaced, not silently enforced. Without that hook, clauses are written but never enforced and the ledger degrades into a diary.

Anyone running the Atlas contract-governance series who wants a caught mistake to become a permanent, generalized project guardrail instead of a one-off note - accepting that, since this skill is run by the same model it governs, it can mis-distill or miss a drift worth recording, and that user confirmation of each clause is part of the design, not a formality.