Lesson index and cards¶
A registry with many lessons is hard to scan by reading every record. The
lesson index groups lessons by location.area, location.package and
location.module, and keeps a short card for each one. An agent reads the
groups, opens the group it needs, and fetches a full record only for the
lessons it decides to act on. The registry stays canonical: a card never
replaces a record, and failure-memory index --expand <ID> always returns
the record from the registry.
Turning it on¶
The index is controlled by one project-config key:
failure-memory init writes it for new projects. When it is set:
- generated node titles come from the record: the first clause of
root_cause, falling back tosymptom(and thenlocation.line_hint), capped at 85 characters at a word boundary, as"<ID>: <title>". Node IDs, tags, edges, routes and every other front-matter field stay the same; only thetitlefield and the body heading change; - the node body opens with a
## Summarysection (see Summarized lesson bodies); compilealso writeslesson_index.jsonandlesson_index.mdin the directory that holds the route index (paths.routes). They are not written beside the generated nodes, because AKMS reads every Markdown file under the local-nodes root as a node, andcompilerefuses a layout that would put them there.
A configuration without the key keeps line-hint titles, the original node
body and writes no index.
Its config fingerprint does not change, and the frozen consumer-contract
packs are such configurations. Adding the key to an existing project changes
its fingerprint once and recompiles every node title. Removing it again
makes check report the index files as stale and compile delete them.
refresh clean removes the two index files when the project marks
generated.lessons as disposable.
Summarized lesson bodies¶
AKMS loads a coactivated node (one reached through load_with) as a summary
taken from its ## Summary section, and loads a node without one in full.
With the key set, every generated lesson body therefore starts:
# L002: The scheduler iterated an unordered mapping
## Summary
- Mechanism: The scheduler iterated an unordered mapping.
- Prevention: tests/engine/test_scheduler_order.py asserts a deterministic enqueue order.
MechanismandPreventionare the first sentences ofroot_causeandprevention, by the same rule as the cards. A line whose field is empty is left out. When both are empty the section holds- Symptom:and the symptom's first sentence, or, with no symptom either,- Lesson:and the heading, so it is never empty.- Those sentences are not repeated.
### Root causeand### Preventionhold only the text after the first sentence, and a subsection with nothing left is omitted. - The
## Identityblock is dropped: the ID is in the heading and in the front matter. - Everything else (generated-warning and source-hash lines, Location, Discovery, Symptom, Fix, Timeline, References, Notes) is unchanged.
A full read is therefore no longer than before for a lesson whose root
cause or prevention is one sentence; a lesson where both run to several
sentences grows by a few characters (the ## Summary scaffolding is about
eight characters more than the removed Identity block).
lesson_index.json¶
The JSON file is the machine contract. It is a pure function of the
lessons, the annotations sidecar and the node namespace. It holds no
timestamps; groups are sorted by name (UTF-8 bytes), cards by lesson ID, and
the file is written with sorted keys and two-space indentation. Rebuilding
unchanged inputs gives the same bytes, so check stays clean.
{
"contract_version": "failure-lesson-index/v1",
"fingerprint": "<sha256 of the document without this field>",
"inputs": {
"source_schema_version": 1,
"source_sha256": "<registry digest>",
"annotations_sha256": "<sidecar sha256, or null>"
},
"counts": {"areas": 3, "packages": 4, "modules": 6, "lessons": 6},
"areas": [
{
"name": "src",
"lessons": 4,
"packages": [
{
"name": "engine",
"lessons": 3,
"modules": [
{
"name": "engine.scheduler",
"lessons": 1,
"cards": [
{
"id": "L002",
"node_id": "example-failure-l002",
"title": "The scheduler iterated an unordered mapping",
"trigger": "tests/engine/test_scheduler_order.py::test_stable_order",
"mechanism": "The scheduler iterated an unordered mapping.",
"prevention": "tests/engine/test_scheduler_order.py asserts a deterministic enqueue order.",
"references": {"plan": "docs/plans/scheduler.md"},
"related": ["L003"],
"categories": ["nondeterminism"],
"superseded_by": null
}
]
}
]
}
]
}
]
}
A card holds:
| Field | Source |
|---|---|
id, node_id |
The lesson ID and its generated node ID |
title |
First clause of root_cause, else symptom, else location.line_hint |
trigger |
found_by.trigger |
mechanism |
First sentence of root_cause |
prevention |
First sentence of prevention |
references |
The non-empty references fields (commit, issue, pr, plan) |
related |
The related lesson IDs |
categories, superseded_by |
The annotations sidecar; [] and null without one |
An empty area, package or module is a group named "".
lesson_index.md renders the same groups and cards for people. It starts
with the configured generated_warning and the index fingerprint.
Browsing: failure-memory index¶
failure-memory index [--config <path>] [--repo .]
failure-memory index [--area <area>] [--package <package>] [--module <module>] \
[--grep <regex>] [--config <path>] [--repo .]
failure-memory index --expand <ID> [--config <path>] [--repo .]
Like every other command it prints JSON. There are three levels:
- With no selector,
levelis"groups": the area, package and module names with lesson counts, and no cards. - With any of
--area,--package,--module(exact names) or--grep(a case-insensitive regular expression matched against card text, categories and reference IDs),levelis"cards": the matching groups with their cards, andmatches, the number of cards. Selectors combine. - With
--expand <ID>,levelis"record": the lesson'slocation, itscard, its full registryrecord, and itsannotations.--expandcannot be combined with a selector; an unknown ID fails withunknown_lesson.
So every lesson is two expansions from the root: a group to its cards, a card to its record.
The command is read-only. It takes no lock and writes nothing. It rebuilds
the index in memory from the registry and the annotations sidecar, so its
answer is current even before the next compile, and works without the
configuration key too. Every result has fingerprint (of the rebuilt index)
and sidecar, which gives the index path and one of these status values:
current: the published file equals the rebuilt index;stale: it differs, andcompilewill rewrite it;absent: it has not been written yet;disabled:lesson_index_versionis not set.
Changing the title cap¶
The cap is part of the compiler's output, not of the
failure-lesson-index/v1 contract: node IDs, tags, routes and the registry
digest do not depend on it. When it changes, a project already on the contract
sees the changed titles as drift, once:
failure-memory checkexits 1 with statusdrift, listing the node files and both index files whose titles changed;failure-memory refresh if-stalerecompiles them where[generated].lessonsisdisposable, so the hooks repair it without help;- where it is
committed,refresh if-staleskips lessons as it always does, socheckkeeps failing untilfailure-memory compileis run and its output committed.
Annotations sidecar¶
A reviewer's later judgement about a lesson does not go into the lesson record, whose schema is closed. It goes into a versioned sidecar next to the registry:
| Registry | Sidecar |
|---|---|
Schema 1 file, e.g. .knowledge/lessons.json |
.knowledge/lessons.annotations.json |
Schema 2 directory, e.g. .knowledge/lessons/ |
.knowledge/lessons/_annotations.json |
{
"schema_version": "failure-lesson-annotations/v1",
"categories": {
"nondeterminism": "Output depends on iteration or scheduling order."
},
"lessons": {
"L002": {
"categories": ["nondeterminism"],
"contradicts": ["L007"],
"exceptions": ["Insertion-ordered mappings are safe."],
"superseded_by": "L011",
"applicability": "Schedulers that fan work out to a pool."
}
}
}
All three top-level keys are required. categories declares the reviewed
failure-mechanism categories (lowercase, digits and hyphens) with a
description each. Every per-lesson field is optional:
categoriesmust name declared categories;contradictslists other lessons this one disagrees with;exceptionslists cases where the lesson does not hold, kept in the order written;superseded_bynames the lesson that replaces this one;applicabilitysays where the lesson applies.
The sidecar is validated by validate, compile, check and index.
A lesson ID that is not in the registry (as a key, in contradicts or in
superseded_by), a lesson naming itself, or a supersession cycle fails
with annotation_id. Any other shape problem fails with
annotations_schema, and an unreadable file with annotations_load.
The sidecar never changes a generated node or route. It is not part of the
registry digest, so annotating a lesson does not move any node's
source_sha256; the index records the sidecar's own digest in
inputs.annotations_sha256. Cards show categories and superseded_by;
--expand returns every field. registry migrate --to 2 copies a schema 1
sidecar into the new directory as _annotations.json, leaves the original
in place, and reports the copy as annotations in its result.