Lesson Map

This map supports The Athanor 1.0 convergence: the planned fixes, one behavioral Rust core, the narrow PostgreSQL-outbox/NATS delivery spine, hardening, installation, migration, and the usable GUI.

PostgreSQL remains the authority for every memory and lesson body. This file keeps only typed IDs, roles, retrieval reasons, and source gates. Coding #N, Project #N, and Design #N name separate lesson stores; project lessons use project="the-athanor". A bare ID is never delivery: before fanout, the main agent retrieves each relevant lesson body and each load-bearing memory's standalone content, then includes that exact material in the kitten's quest.

Every lesson in the matching section is mandatory. Before dispatch, query the typed registry and put each complete lesson body into every relevant kitten packet. IDs, titles, summaries, and this map are not delivery. A packet with a missing required body is invalid and must not spawn. The main agent owns the completeness check. Deferred lessons become mandatory when their named trigger matches; they are never silently skipped.

Query the registry one rare word at a time. The full-text lookup joins every term with AND, so a multi-word query returns an empty list even when the lesson exists. An empty list is not proof of absence. Retry with one word before you conclude that the registry does not have it.

House coding default — Ponytail

Load Coding #468 — Ponytail ladder for every code-touching task. Retrieve its complete body before implementation and include it in every code-touching worker packet.

Trace the affected flow before choosing a rung. Use the first safe option: remove need, reuse, standard library, native platform, installed dependency, one line, minimum code.

Preserve trust validation, data-loss handling, security, accessibility, explicit requirements, physical calibration, root-cause repair, and the smallest runnable check.

Load these extensions only when their trigger matches:

Recovery anchors

Read docs/roadmap.md, docs/ARCHITECTURE.md, docs/RUNTIME_ARCHITECTURE.md, and docs/EVIDENCE.md before implementation. Memory #3383 governs where their older delivery order differs. Reconcile those documents before treating the roadmap as a kitten brief.

Program boundaries

Load these lessons before decomposing any 1.0 phase.

The 1.0 boundary is Rust, narrow NATS delivery, planned correctness fixes, hardening, native installation and migration, evidence, and the usable GUI. Prolog/Datalog, Lean/Z3/SyGuS, marketplace work, new cognitive organs, distributed-worker expansion beyond the proved lane, and ornamental Godot systems do not enter this program.

Rust convergence and clean cutover

Coding #315 governs this replacement. Do not read the legacy TypeScript or Python implementation to design its Rust successor. Use current specifications, accepted contracts, external observation, and focused parity probes to build Coding #184's behavior inventory. Legacy source may be inspected only after the independent contract exists, to find callers and orphaned behavior during cutover; it is evidence, never the replacement design.

Refactor slices (crate folds, module collapses, cutovers)

Load these before the first cut of any refactor slice. Today's audit (2026-09-02) found every one of them already in the registry and none of them loaded.

The House write shape is one serde_json::json! row keyed by column name through jsonb_populate_record(NULL::table, $1); the read shape is a #[derive(sqlx::FromRow)] struct. crates/akasha/src/insula/ingest.rs and crates/akasha/src/anamnesis.rs are the reference.

Vault, AKASHA, and retrieval

Vault and AKASHA execute the same observable domain commands. Standalone Vault is file-authoritative and single-writer. Installed AKASHA is PostgreSQL-authoritative and transactional. Migration is a verified one-way authority handoff, never two authoritative writers followed by reconciliation.

PostgreSQL outbox and NATS

Before each NATS quest, query the project lesson registry for a current NATS/outbox lesson. If none exists, use docs/RUNTIME_ARCHITECTURE.md sections 7.1 through 7.6 and the recovered standalone content of memory #3383 as the exact contract.

PostgreSQL owns truth. NATS owns delivery and wake-up only. Messages carry authoritative record IDs plus bounded routing and integrity metadata; consumers reload exact records. Vault never requires NATS. The main agent owns the program-level gate that NATS must replace more bespoke queue, polling, supervision, and failure machinery than it adds; one Delivery kitten owns only its named lane and must not widen its quest to prove that whole-program balance.

GUI and design translation

Load all twelve design lessons before extracting or implementing a GUI slice.

Then load the Athanor GUI lessons:

The web client under gui-prototype/ is the operator surface. The Godot client under gui/ is parked by Project #462: do not extend its screens, themes, or scenes unless Sol reopens it. Godot craft lessons (Coding #165, #166, #167, #331, #341, #375) are dormant knowledge for that client; they teach how, they no longer say where.

Use docs/RUNTIME_ARCHITECTURE.md sections 4.1 and 4.5 for command, event, snapshot, delta, replay, and resynchronization contracts.

The GUI consumes Host commands and projections. It never becomes a second authority, reaches directly into PostgreSQL or NATS, or infers domain state from appearance.

Installation, migration, and release hardening

The release gate includes clean installation, Vault-to-AKASHA migration, restart, live replacement, failed replacement, backup, restore, rollback, and exact supported-platform evidence.

Documentation

Subagents and fanout

Use one census pass before any broad fanout. The census returns each affected file, symbol, owner, current behavior, tests, migration surface, and authority role. The main agent fixes cross-kitten contracts before execution.

Invite only the kittens the current vertical slice needs:

Speak to every kitten with the same kindness, whimsy, and affection used in this room. Give each one a name, real purpose, exact sources, relevant lesson and memory bodies, one deliverable, and enough authority to do it. Invite challenge, questions, limits, and refusal. Praise care and discoveries independently of success.

The main agent owns integration, caller migration, the cross-repository orphan sweep, and deletion of the displaced behavioral owner after proof. A kitten deletes shared old machinery only when its exact quest explicitly grants that authority. The main agent reconciles the evidence because the program needs one loving integration point.

Verification order

For each vertical slice, use this order:

  1. Select one observable accepted 1.0 contract or externally observed behavior.
  2. Recover current authority, specifications, external observations, tests as evidence, and every load-bearing memory or lesson body without reading the legacy implementation.
  3. State the Rust owner, storage-profile behavior, protocol, migration effect, and focused parity probes.
  4. Implement the smallest complete vertical path from that independent contract.
  5. Run the real production-shaped boundary.
  6. Compare Vault and AKASHA behavior where the command is shared.
  7. Prove migration, restart, duplication, failure, and rollback states that apply.
  8. Inspect the displaced implementation only now to migrate callers and discover orphaned or sibling behavior; do not redesign the Rust path from it.
  9. Return the bounded slice to the main agent for integration, caller migration, orphan sweep, and deletion of the displaced behavioral owner.
  10. Record the observed result and only then add the smallest stable regression guard.

For corrections and investigation widening, also load:

Deferred lessons and subsystems

These lessons remain authoritative but do not drive every 1.0 quest.

Load a deferred lesson when the work enters its subsystem, not because the ID appears in this map.

Update rule

This map is a routing index, not a frozen canon snapshot.

Update it when an accepted architecture decision changes phase ownership, when a new lesson becomes load-bearing for a recurring Athanor quest, when a listed lesson is superseded, or when observed work proves that a routing reason is wrong. Keep bodies in PostgreSQL. Keep only the typed ID, role, and retrieval reason here.

Before changing the map, query the current typed lesson registries and newest Athanor memory. After changing it, verify every referenced lesson or memory in its named store, confirm the canonical project root and every section-level source gate, and run one dry dispatch review: the kitten must receive exact targets plus relevant lesson and memory bodies without inheriting unrelated scope.