CHANGELOG.md

Changelog

1.0.8 — 2026-07-19 · OpenClaw — the sixth platform, and the tutor leaves the terminal

Engram now installs on OpenClaw, the self-hosted gateway that fronts an agent with Discord, Slack, Telegram, WhatsApp, iMessage, and Signal. Every claim below was verified against a live 2026.7.1-2 install on macOS, under an isolated OPENCLAW_STATE_DIR so nothing touched a real gateway or a real learning store.

This is the first platform where /review happens on a phone. The FSRS schedule has always booked reviews for moments you are not at a desk; until now the tool only existed at one.

• One command: openclaw plugins install engram --marketplace nagisanzenin/engram. OpenClaw reads engram's existing Claude-compatible marketplace.json straight from GitHub — no new manifest, no ClawHub publish. /learn, /review, and /coach register as slash commands on every OpenClaw surface.

• Packaging: the hooks key was aimed at a file, and the capability report hid it. OpenClaw matches .codex-plugin/plugin.json before every other marker, so engram is always a Codex bundle there — and for Codex bundles it reads the manifest's hooks value as a list of directories to scan for hook packs. Engram declared "hooks": "./hooks/hooks.json", so the scanner was pointed at a file, found no */HOOK.md, and loaded nothing — while plugins inspect still cheerfully reported hooks among the bundle capabilities. Declared-and-broken looked exactly like working. The key is now removed, which is also the more correct manifest: OpenAI documents that Codex auto-discovers ./hooks/hooks.json when no hooks entry is present, so the key was redundant on the platform it was written for. Both platforms now fall back to their own documented conventions and both find their hooks.

• The nudge, ported as a hook pack (hooks/engram-due/ — HOOK.md + handler.js). It binds to command:new and command:reset because those are the only two internal hook events whose event.messages OpenClaw routes back to the conversation; the session:* events exist but discard pushed output. Same contract as every other platform: forwards what engram.py session-start prints, composes nothing itself, and degrades to silence on missing python3, missing engine, non-zero exit, timeout, or oversized output.

• A silent-failure trap worth naming, because it is the kind that reads as success. OpenClaw skips internal hook discovery entirely until something opts in, and shipping a hook pack inside a plugin does not opt in. Without openclaw config set hooks.internal.enabled true, openclaw hooks list shows engram-due ✓ ready — correct events, requirements satisfied, green tick — and the hook never runs once. Proven both ways in the gateway loader log: zero internal handlers registered without the flag, Registered hook: engram-due -> command:new, command:reset with it. The install doc leads with this rather than burying it in troubleshooting.

• The assessor stays blind, structurally. No OpenClaw bundle format maps an agents/ directory into a usable registry — Claude-format bundles detect agents and explicitly decline to execute them — so engram's three agents are not registered here. They are spawned instead through sessions_spawn, whose default context: "isolated" starts the child with a clean transcript: it sees the task text and nothing else of the tutoring conversation. That is the assessor's blindness requirement met by construction rather than by politeness. New skills/_shared/subagents.md carries the contract — children read agents/<name>.md from the installed plugin rather than receiving an inlined copy, so there remains exactly one definition of each agent across all six platforms, and it states plainly that if sessions_spawn is absent under a narrow tool profile there is no degraded mode: engram does not let the tutor grade its own learner.

• The engine-resolution snippet was rewritten because a live model got it wrong. The first port added OpenClaw as a second line — [ -f "$ENGRAM" ] || ENGRAM="…" after the existing nested-default expression. A live /review then failed with Exec failed: python3 $HOME/.openclaw/extensions/engram/scripts/engram.py: the model had read two lines of shell and paraphrased them into one guessed path, and the guess was wrong under a non-default state dir. $OPENCLAW_STATE_DIR was verified present in the exec environment, so this was not a missing variable — it was a snippet that invited improvisation. All three skills now carry one copy-and-run for loop over the candidate roots, each guarded by an existence check, prefixed "RUN THIS BLOCK VERBATIM — do not substitute a path you guessed." This also hardens the other five platforms: the old form took the first set variable even when nothing was there, the new one takes the first root that actually exists. Verified identical across bash, zsh, and POSIX sh, and under each platform's env layout.

• And then that rewrite introduced its own regression, caught by a blind agent read. The first draft ended in : "${ENGRAM:?engram engine not found…}". In a dev clone — no plugin-root variable set, which is exactly how contributors run this repo — nothing matched, and :? aborts the shell, killing the rest of the block. The old code failed softer there and let the skill's prose fallback recover. Two fixes: $PWD and git rev-parse --show-toplevel are now the final candidates (so a dev clone resolves at all, which the old chain never did either), and the hard :? became a non-fatal warning on stderr. The finding came from handing the edited files to an uncontaminated agent and asking only "which mechanism applies to you, and does the block succeed?" — a question no test in this repo asks.

• Known ordering caveat, unchanged from previous releases and deliberately left alone: the Antigravity staging path is checked before $PWD, so on a machine carrying a stale Antigravity install, a dev clone will silently run the installed engine rather than the checkout. Reordering would change resolution behavior on a supported platform to fix a contributor-only papercut, which is the wrong trade in a release whose whole claim is "no regressions elsewhere."

• The cross-platform prose was made platform-agnostic after a pollution check. The first draft wrote "On OpenClaw, engram's agents are not registered — call sessions_spawn…" into all three shared skills, which every platform's agent reads. A blind agent test flagged the branch as stated in terms of two platforms with Claude Code's own Agent/Task tool never named, and noted the skills use bare agent names where that platform requires a namespaced engram:engram-assessor. Rewritten to describe the property — "a fresh-context child running that agent's definition" — and to name both mechanisms. Re-tested blind: correct tool, correct namespaced type, three separate spawns for the audit, and no ambiguity reported.

• Verified live, not merely wired. Driven against gpt-5.4 with ENGRAM_HOME pointed at a throwaway store: a model asked to name its learning skills answered coach/learn/review; /review and /coach produced real output end-to-end; the hook was observed on a live /new resolving the engine and pushing the 217-character nudge; and the assessor round-trip completed — an isolated child read agents/engram-assessor.md and returned a valid receipt (recalled/easy, rubric_notes quoting both criteria). The child's prompt was read out of the trajectory log and contained only the task text — the blindness claim is now evidence, not architecture. A negative case landed too: pointed at a missing instructions file the child returned {"status":"blocked"} and declined to grade rather than inventing a verdict.

• Still not claimed: delivery of the nudge into a real chat surface. The push onto event.messages is proven; routing needs a connected channel, and the CLI agent path has no conversation to reply into. /learn end-to-end and the artifact smith are also unverified. §5.6 discipline: the unverified list ships with the release.

• A testing note worth writing down, because it produced a false negative for three rounds. pkill -f "openclaw.mjs gateway run" matches nothing — the Gateway renames its process to openclaw-gateway. Three consecutive "the hook never fires" results were actually the original gateway still holding the port and serving a stale copy of the handler; the new instrumented process was exiting on Port already in use while its log scrolled past unread. The hook had been firing correctly the whole time. Stop it with openclaw gateway stop or by PID, and check that the port is free before concluding anything about a hook.

• Upstream discrepancy, reported here for the next reader: OpenClaw's own docs/plugins/bundles.md states native manifests win detection ("If a directory contains both, OpenClaw uses the native path"), but the shipped detectBundleManifestFormat checks .codex-plugin/plugin.json first and only reaches openclaw.plugin.json fourth. An openclaw.plugin.json was written, tested, observed to be inert, and deliberately not shipped — it would do nothing today and would silently change engram's plugin shape the day upstream makes the code match the docs.

• The adversarial pass found one of its own release's claims to be false. HOOK.md said "Every failure path degrades to silence" — but only the engine call was inside a try. Delivery was not: event.messages.push(...) throws if messages is frozen, absent, or not an array, and a thrown handler is not a silent one. Two mitigating facts, both verified in OpenClaw's shipped source: triggerInternalHook wraps every handler in try/catch and logs, so this could never break a session; and createInternalHookEvent always supplies a real extensible array, so the normal path cannot reach it. Severity is therefore low — but "the host catches my exception" is not silence, it is a line in an operator's error log, and a hook that advertises silence should not be relying on its host to keep that promise. Delivery is now guarded too, which makes the documented contract true unconditionally rather than by courtesy of the runtime. Found by attacking the handler with frozen/absent/non-array messages and a throwing push — cases the earlier unit test missed because it ran against an empty store, where the handler returns before ever reaching delivery. A negative test that exits early proves nothing about the code past the exit.

• Gates. Selftest 217/217 (unchanged — no engine behavior changed, so no new check was owed; §4.5 mutation-testing is therefore N/A this release). OpenCode suite 88/88. Fuzz gate re-run against the final commit across every read path enumerated from the dispatch table plus the read-only sub-actions the table cannot see: 0 crashes / 500 states / 2 seeds, the §4.7 target exactly. Live engine test green — s_after 3.71 → 29.55 across a day-11 review, momentum.recalled_7d matching reviews_7d (the v1.0.7 fix holding), retention carrying its grader_unvalidated, doctor ok=true.

• §5's read-only check needs an amendment, and it is not a v1.0.8 bug. Hashing ~/.claude/learning before and after every read path reports a mutation — traced to report, whose documented job is writing artifacts/dashboard.html. report is classified non-mutating in the dispatch table because it touches no learning state, so the protocol's own enumeration recipe hands it to a gate that then fails on it. Re-run with report excluded, every read path leaves the store byte-identical, and no state file is touched. The gate should exempt report (or compare state files only) — as written it cries wolf on every release, which is how a real read-path write would get waved through.

1.0.7 — 2026-07-19 · a flattering number, caught by the gate built for it

One engine fix, shipped hours after v1.0.6 because RELEASE_PROTOCOL §7.5 says a wrong number does not get to stand. The independent post-release reviewer — standing instruction: "find a number that is wrong, especially one that is wrong in the direction that reassures the learner" — found exactly one, and it is bug class #1:

• momentum.recalled_7d counted encode and pretest receipts as retrieval wins. The docstring's contract is "retrievals cleared, and genuine wins among them" — wins ⊆ retrievals — but the counter took ANY in-window receipt with grade: "recalled". Encodes and pretests carry that grade in normal use, so a learner who encoded three concepts and never came back once read recalled_7d: 3 beside reviews_7d: 0 — three "genuine wins" with zero retrievals. One-line fix: the counter now shares the same genuine-retrieval predicate as reviews_7d.
• And the embarrassing part, per protocol: the guarding selftest was theatre. The v1.0.6 check asserting recalled_7d == 1 could not fail — its encode fixtures were both out-of-window AND gradeless, so the inflating population never reached the counter under test. The fixture now carries an in-window grade: "recalled" encode AND pretest; the check fails by name when the fix is reverted (mutation-tested). That is the fourth §4.5 lesson in four releases: a check that cannot see the inflating population proves nothing about inflation.
• Blast radius, honestly: the prescribed /coach narration leads with stability_gained_7d / reviews_7d / most_durable (all correct) and never quotes recalled_7d; exposure was a narrator improvising off the JSON — which the docstring invited, by calling the field retrieval wins.
• Noted, unchanged: retained_total/state_counts label a node "retained" on FSRS graduation (before any retention test). That matches its docstring and the system-wide state convention, and the retention metric correctly excludes first exposures — a labeling convention to revisit, not a wrong number.
• Selftest count unchanged at 217/217 (an inert check was made real, none added). Re-fuzz after the fix: 0 crashes / 800 states.

1.0.6 — 2026-07-18 · Antigravity — the fifth platform

Engram now installs natively on Google Antigravity (agy CLI) — contributed by @mertso13 in #8, two review rounds, every claim below verified live against agy 1.1.4 with a sandboxed $HOME.

• One command: agy plugin install https://github.com/nagisanzenin/engram. Root plugin.json is schema-minimal on purpose — the official antigravity.google/schemas/v1/plugin.json allows exactly name + description (additionalProperties: false); everything else is directory-crawled. The manifest is inert on the other four platforms (Claude Code reads .claude-plugin/, Codex .codex-plugin/, OpenCode npm/.opencode/, Hermes skills.external_dirs).
• The bug that made it possible was ours, not theirs. agy plugin install stats every file it copies — and died on .opencode/skills/{learn,coach,review}/SKILL.md, whose symlinks have been self-referential loops since f3ccc76 (../../ where three levels were needed: from .opencode/skills/<n>/, ../../skills/<n>/SKILL.md resolves to itself). Nobody noticed for four releases because npm packs exclude symlinks and OpenCode's loader never stats them. Retargeted to ../../../; git-clone OpenCode installs get real links out of it too.
• Engine resolution gains the AG default — the skills' chain is now OPENCODE_PLUGIN_ROOT → CLAUDE_PLUGIN_ROOT → CODEX_PLUGIN_ROOT → ENGRAM_ROOT → ~/.gemini/config/plugins/engram (agy sets no plugin-root variable at all; the staging path is deterministic, so it rides last as the default).
• And the embarrassing part, per protocol — this time the reviewer's. The first review round's fix sketch replaced $ENGRAM_ROOT with the AG path while its prose said "before $ENGRAM_ROOT". The contributor implemented the sketch faithfully — which would have broken Hermes, the platform shipped one release ago, whose entire engine resolution runs through ENGRAM_ROOT (INSTALL-HERMES.md sets no plugin-root var). Caught in the second round by evaluating the installed chain side-by-side under ENGRAM_ROOT=/fake/dev/clone: new chain ignored it, old chain honored it. The lesson is §4.6's, inverted: a reviewer's sketch is a diff too, and it gets the same scrutiny.
• Known limits, stated in the README footnote: agy 1.1.4 silently drops any agent whose frontmatter carries a tools: field (any value — Claude names and snake_case both tested), so engram-curriculum-architect and engram-artifact-smith don't register on AG; only engram-assessor does. agy plugin validate still reports "3 agents processed" — validate ≠ install ≠ register. The due-review session nudge isn't ported (AG hooks use a different mechanism). Stripping tools: was rejected deliberately: it would grant those agents all tools on Claude Code, trading a real restriction for a cosmetic registration.
• Engine: three shipped read-path bricks, found by this release's own fuzz gate (§4.7: 800 randomized garbage states × 24 read paths — the 24 include every read-only sub-action, per the amendment). All three predate this release; all three are the same lesson again:
  • artifact list crashed on an unhashable entry in order — because it hand-rolled the walk instead of using graph_order, the helper whose docstring names this exact crash. The checklist line "grep for the N+1th call site (cmd_artifact was the one missed)" was written about this command in v1.0.1. It was still the one missed.
  • misconception list crashed on a None entry (it.get) — reads now degrade past non-dict entries; mutators still refuse an unusable file outright (a lossy "repair" a mutator then saved would be data loss wearing a hard hat).
  • report crashed rendering an int-typed misconception field (escape(123)) — the dashboard, the one surface a human actually looks at, bricked by a hand-edited file. Fixed at the gate: _open_misconceptions now coerces narrator-facing fields to text.
  • Each fix carries a selftest check that asserts the behavior (the real entry survives the garbage beside it), and each check was mutation-tested: revert the fix, that specific check goes red. Selftest 214 → 217. Re-fuzz after the fixes: 0 crashes.

1.0.5 — 2026-07-18 · Hermes — the fourth platform, and the README stops being misread

Engram now runs on Nous Research's Hermes Agent (requested in #9), and the README finally says out loud what too many people had to ask: this is a learning system for the human, not an agent-memory plugin.

• Hermes support, verified live — not speculated. Every claim in INSTALL-HERMES.md was exercised against a real Hermes v0.18.2 install: external-dir discovery of all three skills (_shared/ correctly ignored), /review and /coach slash registration, full SKILL.md injection on invocation (11.5 KB /review, 17.9 KB via a /study bundle), and the ambient nudge landing in the composed user message at the wire level (request dump inspected).
• The install route is clone + skills.external_dirs, deliberately. Hermes' hub installer copies only files referenced inside each skill folder, which would sever the skills from the shared scripts/engram.py engine. The doc says so and says why.
• The /learn collision, handled honestly. /learn is Hermes' own built-in (it authors new agent skills). Hermes detects the clash and skips auto-registering engram's learn, printing the escape hatch we document: /skill learn — or the optional one-line /study bundle. The new Hermes nudge rewrites its own "/learn to continue" line accordingly.
• New hooks/session-start-hermes.sh — a pre_llm_call port of the SessionStart re-anchor: same self-resolution, same degrade-to-silence contract, plus once-per-session dedupe keyed on Hermes' session_id. The engine is untouched (state still shared across every platform via ~/.claude/learning).
• README rework. Leads with the disambiguation (agent memory vs. human learning — the most common misread), then a five-platform matrix: Claude Code (born here), Codex, OpenCode, Hermes, Antigravity (in review, #8). New first FAQ entry for the same confusion. INSTALL-CODEX.md omni-repo line updated.
• Known limits, stated in the doc: headless hermes chat -q does not expand slash-skills (interactive CLI/TUI/gateway only); the delegate_task assessor flow and gateway/cron delivery are recipe-documented but not yet driven end-to-end with a capable model. Engine selftest unchanged at 214/214; no engine code changed (ENGRAM_VERSION pin only).
• And the embarrassing part, per protocol. The pre-release review (28 agents, 10 confirmed findings) caught the brand-new hook failing open two independent ways — an empty session_id bypassed the once-per-session guard entirely, and a misplaced 2>/dev/null meant an unwritable TMPDIR both leaked bash errors to stderr and re-nudged on every LLM call. The hook whose one-line contract is "ambient, never nagging" shipped to review as a per-call nagger under exactly two failure modes its author had tested around. Both fixed (dedupe now fails closed to a per-process key; unwritable marker → silence), plus a 9-case failure battery including both reviewer repros. The same review caught the install doc omitting the ENGRAM_ROOT export the skills' engine resolution depends on, the cron recipe delivering the un-rewritten /learn it warns about two sections earlier (the hook is now dual-mode: JSON for pre_llm_call, plain rewritten text on empty stdin for cron), a missed package-lock.json bump, and five README cross-consistency slips (the nudge exists on OpenCode too; "five platforms" counted one still in review; the Codex install cell was missing its second command; the OpenCode global-path and pin-to-source details had been dropped; the /learn onboarding example sat unscoped under a matrix that includes Hermes).

1.0.4 — 2026-07-17 · updates that only speak when something changed

The OpenCode update flow gets honest and inspectable, and its last shell command is gone.

• Content-aware diff. diffCategory now compares files byte-for-byte (Buffer.equals) instead of by existence. Identical files are silently ignored, new files ride the copyMissing extract, and only genuinely modified files reach the skipped list — so a metadata-only version bump produces no manifest, no pseudo-command, no notification. Unreadable files fail safe into skipped.
• Unified diff viewer. A version bump with real changes now also writes .engram-update.diff (standard ---/+++/@@ format), and /engram-update grows a "View changes" option — the model reads the diff and summarizes what changed before the user decides. Cleaned up alongside the manifest in every resolution mode.
• Zero Bash in the update template. A new cleanup mode on the engram_update tool replaces the template's last rm -f, and an isWithinTarget path-traversal guard validates every resolved path in auto and per_file modes — defense in depth against tampered manifests. Uses path.sep, so the guard holds on Windows.
• Verification. Vitest 51 → 88 (new diffLines suite incl. an insertion trailing-context regression test, tampered-manifest traversal tests, cleanup-mode tests). Engine selftest unchanged at 214/214.

Contributed by @luanweslley77 (#6), one review round.

1.0.3 — 2026-07-16 · OpenCode — the third platform

Engram now runs on OpenCode, alongside Claude Code and Codex. Same skills, same engram.py engine, same receipts — the port is a thin TypeScript adapter that satisfies OpenCode's plugin contract and shells out to the unchanged Python core.

• Self-extract bridge. OpenCode loads plugins from its npm cache, which is not a config directory, so native discovery never sees the plugin's skills/agents. On first run the config hook extracts skills/ agents/ scripts/ into the OpenCode config dir (~/.config/opencode/ or the project's .opencode/) behind a copyMissing guard that never overwrites a user's edits; a first-session cfg.* bridge registers everything immediately, and disk discovery takes over thereafter.
• Deterministic update tool. /engram-update appears on a version bump and applies refreshes through the engram_update custom tool — deletes go through unlinkSync with every path validated against the manifest allowlist. No bash, no interpolation.
• Hooks. shell.env exports OPENCODE_PLUGIN_ROOT; experimental.chat.system.transform carries the review-due nudge; a session.idle toast announces available updates.
• Verification. New vitest suite (67 tests) covering extract, the manifest state machine, and the update tool's path validation; .github/workflows/test.yml runs vitest + tsc --noEmit + engram.py selftest on every push. Engine selftest unchanged at 214/214.

Contributed by @luanweslley77 (#5), hardened across four review rounds.

1.0.2 — 2026-07-11 · a regression my own fix caused

The v1.0.1 verification review confirmed both headline fixes hold (the export leak is closed; the power floor is unbuyable) — and found that v1.0.1's finding-#4 fix introduced a new crash.

Switching compute_modality to the shared _outcome predicate was correct — but _outcome returns None on a hand-edited un-scoreable receipt, and 0.0 += None is a TypeError that bricked stats, and therefore /coach. The same release fixed this exact bug class in settle (finding #5) and did not carry the guard one function over. The test gap mirrored the code gap: there was a settle-degradation check and no modality one, so 213/213 stayed green over a live brick.

• Fixed: modality drops the un-scoreable datum, like every other read path. Reads degrade, they never brick.
• The fuzz fixture now includes an un-scoreable FIRST review, so this class cannot hide again — the gate missed it because no fixture gave a node a None-outcome first review, which is the only shape that reaches modality's per-node first-review logic.

Selftest 213 → 214.

1.0.1 — 2026-07-11 · TWO post-release reviews, and the leak the whole project exists to prevent

Two independent reviewers read shipped code — v1.0.0 (the Commons) and the still-in-main v0.9.0 (the Method). Between them, one critical leak and one severe measurement bug, plus five more. Selftest 207 → 213.

⚠⚠ CRITICAL — export leaked free text verbatim. The v1.0 headline was false.

arm and stratum were strings on the whitelist — and a whitelist that admits a free-text field is a hole in the whitelist. stratify_by: ["claim"] routed every node's claim text, verbatim, into the export's stratum field — while the file's own stripped list swore claim was removed. The learner-authored arm label leaked on every experiment. A hand-forged grader string left uncapped.

LEAKED into the "attributed, text-stripped" export:
  CLAIM-CANARY: 4   ARCHITECT-SECRET-CANARY: 4   ARM-CANARY-LEAK: 1   stigmatized: 4

Fixed: arm, stratum, and grader now leave as hashes (arm_hash, stratum_hash, grader_hash). The only strings that leave un-hashed are kind/grade/rating — closed enums the engine validates, not text a human wrote. A whitelist that admits a free-text field strips nothing.

And the reviewer named exactly why the gate missed it: the leak-test never started an experiment, so arm/stratum were always None in the fixture. It asserted the whitelist keys were clean by never populating them. The test now stuffs the canary into every authored surface — the experiment arm, a stratum pointed at a node's claim, an arbitrary architect field — which is the exact path the reviewer used.

⚠ SEVERE — the power floor could be bought down with one payload field

experiment settle gated powered on the design's own min_per_arm. A trial declaring min_per_arm: 6 — the underpowered v0.8 default this release exists to kill — certified as powered: true and read "suggestive" on six data points per arm. And the shipped skill promised the opposite: "the settle will read underpowered, and it will be right." It did not.

Fixed: powered gates on max(design, EXPERIMENT_MIN_PER_ARM). A design may set a higher bar; it can never buy the engine's floor down. A power gate you can lower with a payload field is not a power gate.

And five more, all in shipped code

• Optional stopping. settle had no status guard — re-settling as data arrived kept only the last verdict and roughly tripled the false-positive rate (0.04 → 0.117). Peek-and-re-settle until the coin lands is the exact fallacy pre-registration forbids. Now: an experiment is analysed once. start already refused a second active experiment; settle now refuses a second analysis of the same one.
• A broken bootstrap CI. It percentile-bootstrapped max(mean) − min(mean), a non-negative extreme-order statistic — so for 3+ arms the "95% CI" excluded its own point estimate (three identical arms, spread 0.000, CI [0.033, 0.367]). It manufactured a strategy separation that was not there. Now: a signed two-arm difference CI (which has no such floor), and None for k > 2 with the read saying so. Refusing to draw a bad CI is more honest than drawing one.
• first_review_recall meant two different numbers. stats.modality scored a partial as a full 1.0; the experiment engine, on the identically-named metric, scored it 0.5. Same name, same engine, same data, two answers — and modality's was the lenient one. Both now use _outcome, the shared predicate. (§4.8 Q1: the engine's commands must agree.)
• settle bricked (not degraded) on a hand-edited receipt whose rating was a truthy non-rating with no grade — sum([1.0, None]) → TypeError, and status had greenlit the settle first. Now it drops the un-scoreable data point, like every other read path.
• The no-network guarantee, made honest about its limit. The AST scan is a strong regression guard, not an impossibility proof (__import__, importlib, ctypes, exec would pass it). So the engine also contains none of those dynamic-import primitives, checked by a new selftest — the two checks together support "no network code AND no way to smuggle one in dynamically," which a single import-scan cannot claim alone.
• grader_qwk on each receipt now ships with a qwk_note stating plainly that it is the grader's validity at export time, stamped on every receipt regardless of when it was graded — the best available estimate, not a per-receipt measurement.

Everything the two reviewers checked and found clean is on the record: the randomization-test p-value (valid under unequal n, false-positive rate at/below nominal), block randomization (stable, balanced, reproducible), the modality floor move, and every v0.8.1 fix still holds after the merge.

1.0.0 — 2026-07-11 · THE COMMONS — the first learning system that is also an experiment the whole field can read

The evidence base of learning science is built on undergraduates, word pairs, and 20-minute retention intervals. Almost nothing tests self-directed adults, on hard conceptual material, at 30–90 day horizons, with blind-graded free recall.

That is not a gap anyone chose. It is a gap because, until roughly 2026, grading free recall at scale was impossible. You needed a human to read every answer.

Engram produces exactly that data as a byproduct of being useful — and, since v0.7, with a measured oracle behind every grade. The open question is sitting right there: an AI tutor built on this exact dialogue grammar produced ~2× the learning gains of an active-learning classroom (Kestin et al., Harvard, Scientific Reports, 2025) — measured on an immediate post-test. Nobody has ever measured whether AI-tutoring gains survive to thirty days.

Selftest 201 → 207.

export — a file, not a request

python3 scripts/engram.py export --contributor "@you"

leaves	never leaves
grades, ratings, confidence	your productions — every word you wrote
timings, stability, intervals, retrievability	probes, claims, rubrics
kind, artifact, arm, stratum	goals, interests, misconception text
grader and its measured QWK	topic names and node ids — hashed, not carried

• The payload is a WHITELIST. Every field is constructed by name. There is no code path by which a production could arrive — not "we remembered to delete it." A blacklist is a promise you must keep every release; a whitelist is one you keep by construction. (Same lesson gold taught in v0.7, and the reason both are built the same way.) A property-based selftest puts a canary string in every field the schema has — and some it doesn't — and asserts not one character survives.
• The stripped list ships INSIDE the file, so the promise is verifiable by the person making it rather than merely asserted at them.
• The hash caveat, stated out loud: a hash of a common topic name (transformers) is recoverable by dictionary attack in seconds. It hides the topic from a casual reader, not from someone who wants it — and the export is attributed anyway. export --topic T exists so you can choose. An honest caveat beats a fake guarantee.

v0.7 GATES v1.0 — and it is a refusal, not a warning

export refuses if your assessor has not passed its audit:

REFUSING TO EXPORT: the grader behind every one of these grades is unaudited.
A finding aggregated from unaudited oracles is not a finding — it is noise with a schema,
and publishing it would put a number into the world that nobody can stand behind.

Every shared receipt carries its grader's measured QWK, and the bundle carries the gold set's own circularity limit (gold_adjudication: "authored"). A number you cannot stand behind should not enter the world with your name on it.

THE ENGINE HAS NO NETWORK CODE — and that is now structural, permanent, and mutation-tested

Not "no network by default." None.

⚠ THE ENGINE HAS NO NETWORK CODE — structural, permanent, and never to be deleted
⚠ …and it never SHELLS OUT (no subprocess, no os.system/popen/exec/spawn)

• The check parses the engine's own AST — it does not grep. The first draft grepped its own source for the word curl and found it, in its own comment and inside its own regex literal. It failed on itself. The AST cannot see a comment or a string; it reports only what the interpreter will actually execute. If a structural guarantee can be defeated by a comment, it was never structural.
• And it is mutation-tested by INTRODUCING the thing — four mutations add a real import socket, a real import urllib.request, a real import subprocess, and a real os.system("curl …"), and all four go red. For an absence check, nulling the detector proves nothing — it just makes the check vacuously true, which is exactly what it already is on a clean codebase. (Now written into the protocol.)

export writes a file and stops. The agent posts — via gh, which is already installed, already authenticated, and already trusted with the whole machine. That is not a loophole; it is the correct place to put the boundary, because the thing the 100% local badge is about is engram.py, and engram.py will never grow a socket.

It is ATTRIBUTED, and we are not going to lie to you about it

gh posts from your account. A "salted anonymous hash" riding inside a signed envelope would be theatre the moment the envelope is signed. You cannot have one-keystroke upload and anonymity. Pick one, and say which out loud.

Attribution is also the stronger science. A retention study lives on longitudinal linkage — following the same learner across months is the question. Attributed, linkable series at n=100 are worth more than anonymous one-shot dumps at n=500. It also buys dedup, fabrication detection, the ability to ask a follow-up, and the ability to credit you — the only honest incentive on offer.

This is not telemetry. It is a consenting, named, informed participant in an open study, which is what every good study has always had.

/coach contribute — and degrading to silence is what makes the consent real

Shows you the file. Names the exact handle it will post under, before it asks. Posts only on an explicit yes.

No gh, not authenticated, offline, any failure at all → print the path, one line, stop. No error. No retry. No nag. The file is still yours.

gh is a convenience, never a dependency — and declining must cost the learner nothing, or the consent is not real. A person who feels a cost in saying no has not consented. They have complied.

Also

• CONTRIBUTING-DATA.md — a real informed-consent document, not a privacy policy. What leaves, what never does, that it is public and attributed, and how to withdraw (it is a GitHub post — delete it; that is the entire mechanism, deliberately).
• ENGRAM_VERSION — the engine finally knows its own version, pinned against the plugin manifest by a selftest so it cannot drift. A corpus of receipts from unknown engine versions is not a corpus.
• exports/ created on init. Exports are append-only, like receipts and audits.

0.9.0 — 2026-07-11 · THE METHOD — the experiment machinery was not sound enough to support the claims it exists to make

Article 7 ("adapt on evidence, never taxonomy") is the article that replaces learning styles with real n-of-1 measurement. Four defects, all in shipped code, and the last one is the worst thing in this repository's history:

#	the defect	what it means
1	arm = arms[len(assignments) % len(arms)]	ROUND-ROBIN, not randomized. Perfectly predictable.
2	unstratified	Explorables are routed to the hardest concepts on purpose, so the comparison carried the material as well as the medium. docs/06 open-Q2 disclosed that confound honestly — and never fixed it.
3	min_per_arm: 6	The SCED alternating-treatments literature puts sufficient power at ~28–30 observations. Six per arm is underpowered by ~2.5× (docs/07 §9).
4	exp["verdict"] = args.verdict	THE MODEL COMPUTED THE VERDICT. A payload said "derivation-first won" and the engine wrote it down. A direct violation of invariant #2 — the engine owns every number — in the one command whose entire purpose is a number nobody is allowed to make up.

A confounded, unpowered, round-robin trial settled by narration is not evidence. It is a vibe with a JSON file.

Selftest 191 → 201 (this release merges the v0.8.1 fixes).

What it is now

• Randomized, and reproducible. Balanced block randomization keyed on (seed, stratum): within each block the order is random, and every arm appears exactly once. Not random.choice (which randomizes and never balances — a 20-node run could land 14/6 and the effect would be measured over an arm that barely exists). Not round-robin (which balances and never randomizes — which is what shipped). The seed is recorded, so every assignment is recomputable by anyone who holds it. An assignment nobody can reproduce is not an assignment; it is an anecdote.
• Stratified — and this is the part that kills the confound. Randomize the medium within one affordance class and the material stops riding along with it. docs/06's open question 2 is finally answerable instead of merely disclosed.
• Pre-registered. The design file is the pre-registration: question, arms, metric, seed, strata, power, analysis — written before a single datum exists. An unknown metric dies: the engine will not guess which number you meant and then report it as fact.
• Powered. min_per_arm defaults to 15 (~30 observations). You may set it lower — the engine records a power_note saying you chose to, and the settle reads underpowered, and it is right.
• THE ENGINE COMPUTES THE VERDICT. settle --verdict is now refused, loudly. The engine returns per-arm n and means, the effect, an exact randomization test p-value (shuffle the arm labels — valid by construction, because the engine randomized them itself), a bootstrap 95% CI, and the per-stratum balance. The model narrates it. It does not make it up.
• experiment status — progress against the power floor, so nobody settles early by accident.
• p is never 0. Add-one correction: with 10,000 permutations the floor is 1/10,001. A p-value of exactly zero is a claim no finite test can make, and this engine does not make claims it cannot.

stats.modality's floor moved with it — and that SUPPRESSES a number some learners can see today

MODALITY_MIN_N was 6, inherited from the same underpowered convention, and docs/10 predicted this exactly: "stats.modality's identical ≥6 floor inherits the same defect and moves with it." It is now 15.

This means some existing learners will lose a number their dashboard used to show. That is correct. The number was never earned. Suppressing an unearned number is not a regression — it is the product.

The §4.7 rule that found the bug had a hole, and the hole was the same shape

The protocol says: enumerate the read paths from the dispatch table, not from memory. But experiment lives in mutating (start/assign/settle write) — so its read sub-actions (status, list) were invisible to the enumeration and had never been fuzzed. The first time they were: 72 crashes in 600 states. arms as an int, arms absent, arms holding a dict (unhashable, and it poisoned the dict it was used as a key in).

A command with sub-actions has a read path PER SUB-ACTION. Fixed at one gate (_exp_arms), and the rule is amended.

as_number let infinity through — the numeric gate for the entire engine

Infinity and NaN are not valid JSON — and Python's json module parses them anyway. An inf sailed through every isinstance(x, float) check and then died on the first int() (OverflowError), and a NaN compares False to everything, including itself, so it poisons every comparison it touches without raising anything at all.

Three crashes in decay and experiment status, in code with no other flaw. Fixed at the gate — as_number is the funnel for every scheduler leaf, every metric, every threshold in the engine. One line here; forty at the call sites, and the forty-first is the one that ships.

Fuzz: 0 crashes / 13,500 invocations across 18 read paths.

0.8.1 — 2026-07-11 · THE RULER WAS NEVER TESTED, ONLY THE SUBJECT

The post-release review (§7.5) found 11 defects in shipped v0.8.0, and the two worst are the same failure the release was written to end.

Selftest 180 → 191.

⚠ #1 — The capstone's transfer receipt was DEAD DATA

The learner builds the capstone, passes it, and stats.transfer reads "NO CAPABILITY HAS EVER BEEN MEASURED" — while the receipt sits on disk. Two independent causes:

• The capstone is built once, so its transfer receipt is its first receipt — and the v0.6.1 rule ("a node's first receipt is its encoding event") swallowed it. But a capstone has no encoding phase at all. The build is the event.
• The census skipped it anyway: it is minted with transfer_probe: None ("the capstone IS the transfer probe"), and the census required a non-empty one.

A FAILED capstone was discarded entirely — the single most diagnostic event in the whole system ("I could not actually use this topic"), silently dropped.

This is v0.8's own thesis — "transfer_probe was authored since v0.1 and read by NOTHING" — reproduced one level up, on the most important node in the graph. Receipts now carry a capstone stamp (written at grading time, like the artifact medium stamp), and the census asks has_transfer_question(), which the capstone answers yes to.

⚠ #2 — The headline ranked a learner who LOST every capability ABOVE one who MASTERED every one

node.transfer.state was deliberately latest-evidence, with a docstring saying "a capability that fired in June and failed in September is not currently owned, and pretending otherwise would be a wrong number in the flattering direction."

They fixed it in state and shipped it in rate_fired — which pooled the entire lifetime log and was order-blind. It is the number /coach leads with and the dashboard's first chip:

learner	history	owns now	v0.8.0 headline
IMPROVING	failed all 5 twice, then mastered all 5	applied: 5	"FIRED on 33%"
DECLINING	passed all 5 twice, then lost all 5	applied: 0	"FIRED on 67%"

The learner with zero current capability scored exactly double the one who owned all five — and the dashboard rendered fired 67% and owned 0 as adjacent chips. That is not a lenient ruler. It is a negative one, and every number downstream had its sign flipped.

Two numbers, two names: owned_rate (THE HEADLINE — of the capabilities you have probed, how many do you own right now; order-aware, exactly as state is) and probe_fire_rate (the lifetime probe-level history, order-blind by construction, named as history so it can never be mistaken for the headline again).

And the part that matters most. The shipped §5.5 instrument gate missed this because it varied the bar (recalled / partial / lapsed, on one node, with one receipt) and never varied the population. It tested the subject, not the ruler — the exact lesson v0.7 was written to teach, repeated one release later, in the gate written to teach it.

⚠ #4 — A failed transfer probe destroyed 97% of the memory's durability

v0.8 separated the three populations in the metrics and pooled them in the scheduler. On a mature node — the only kind the system ever probes — one failed probe did this:

s: 443.5 → 12.3      (97% of the memory's durability, deleted)
state: review → learning     lapses: 0 → 1     due: 2027-03-01 → 2026-03-17

…and dropped the node below the transfer bar, so it could never be re-probed. Answering a HARDER question wrong demolished the schedule for the ORIGINAL concept. It contradicted three separate sentences the same release shipped, including _transfer_ready's own docstring warning about "a lapse the schedule then punishes — a fabricated setback." The maturity gate was built to prevent exactly that, and only ever guarded immature nodes.

A transfer lapse now leaves fsrs completely untouched — and the receipt records s_before == s_after plus a schedule_unchanged note, so the evidence is honest about the fact that nothing moved. A transfer success still strengthens the memory, because applying an idea is a retrieval, and a strong one.

And seven more, all in shipped code

3. add-topic --replace destroyed a completed capstone's schedule. The payload never contains a capstone, so _has_capstone was always false on a replace and it was always re-minted state: new — after the carry-forward loop, making it the one surviving node never carried forward. And it flattered: the reset removed the rotting capstone from retention.unmeasured, so "1 concept past due and unretrieved" became "30-day recall 100%". Survivorship bias, through a new door.
4. --replace wiped node.transfer and never rebuilt it (unlike artifact, which is recomputed from evidence). Graph said None; stats still said applied: 1. Two sources, two truths.
5. No maturity gate at INGEST — only at selection. A bare CLI rate --kind transfer certified applied on a node encoded yesterday, while transfer itself returned zero candidates: the engine refused to probe the very node it had just certified. (§4.8 Q5: the skills pass what the engine expects; the CLI is the door nobody guards.)
6. calibration_encode was a RESIDUAL bucket (not in review_ids), so transfer receipts fell straight into a bucket whose own docstring calls it "first-exposure (encode) guesses." Transfer is precisely where a learner is most overconfident — they know the concept, the capability doesn't fire — so that overconfidence was misattributed to their encoding self-assessment, and /coach would diagnose the wrong faculty and prescribe the wrong fix. A residual bucket silently absorbs every kind you add later. Now named: calibration_transfer.
7. A payload node named capstone was silently destroyed — and the minted capstone then listed itself in requires, so it could never be served, while next cheerfully reported "this topic is finished." Now refused, like cmd_capstone already did.
8. stats.transfer had no minimum-n floor. Every sibling has one (calibration 10, modality 15, the grader audit 30). One probe read "FIRED on 100%" and chipped it on the dashboard while calibration correctly said insufficient-data on the same state. Floor: 5. Counts are facts and are always shown; a rate a single datum can swing by 20 points is not a rate.
9. reps >= 3 counted the ENCODE, so an advertised "3+ retrievals" delivered 2. Maturity now counts retrievals from the receipt log — the engine's own doctrine is that the first receipt is the encoding event, not a retrieval.
10. An UNDATED receipt became the LATEST transfer evidence. _sort_key deliberately sorts a garbage-ts receipt last (so it can never win day-0) — and taking ts[-1] therefore handed it the crown. A hand-edited undated recalled flipped a node to applied over a real, dated lapsed. The v0.6 fix and the v0.8 rule collided, and they collided in the flattering direction.

Also

• as_number let Infinity and NaN through — not valid JSON, and Python's json module parses them anyway. An inf sailed through every isinstance(x, float) check and died on the first int(); a NaN compares False to everything, including itself, and never raises at all. Fixed at the numeric gate for the entire engine. Fuzz: 0 crashes / 12,750 invocations.

0.8.0 — 2026-07-11 · THE CLAIM — Engram measured memory and claimed capability. Now it measures both.

transfer_probe has been authored by the curriculum architect since v0.1, stored by the engine, and read by nothing. On the founder's own graph, 12 of 13 nodes carry one, and grep transfer_probe scripts/engram.py found exactly one line: a setdefault. Zero transfer receipts existed anywhere, ever.

skills/learn §5 said of the capstone: "this is the point of the whole topic — do not let it silently not happen." It silently did not happen, every single time, because it was a line of prose in a skill file — and a tutor running low on context drops a suggestion. It does not drop a DAG.

Engram has been a very good memory system wearing a capability system's marketing.

Selftest 167 → 180.

The three populations — because there are now genuinely three questions

v0.6.4's bug was four implementations of one rule, three of them wrong, and the fix was one shared predicate. The temptation now is to bolt transfer onto that predicate — which is the same bug from the other end: one definition covering three questions, and therefore answering none.

population	the question it answers	who reads it
_review_receipts	does the memory survive N days?	retention (the north star), recall_by_stability, calibration, modality, adherence
_transfer_receipts	does the capability fire in new clothes?	stats.transfer, node.transfer
_retrieval_receipts	how much durability was actually grown?	momentum

Never pooled. Retention pooled with transfer would drag the north star down with a harder question and answer neither. Momentum without transfer would understate real growth — a transfer probe advances the FSRS schedule like any other rating, and undercounting a learner's real progress is its own dishonesty, in the direction that quietly tells them their work did not land.

Engine

• transfer [--topic T] — the mature concepts ready for the harder question. Eligible = stability over 21 days across 3+ retrievals, a non-null transfer_probe, and not probed in the last 30 days (it is a tool, not a quiz show). Untested first, then coldest.
• node.transfer — untested → probed → applied. Engine-owned, written only by a transfer receipt, derived from the append-only log. Computed from the LATEST evidence, not from "ever": a capability that fired in June and failed in September is not currently owned, and pretending otherwise would be a wrong number in the flattering direction.
• stats.transfer — reported beside retention and never inside it.
• capstone --topic T — materialize the build as a real node in the DAG (idempotent: twice → one node). New topics get one from add-topic automatically. It requires every other concept, so it unlocks exactly when the frontier empties and then arrives in next like anything else. It cannot silently not happen, because it is in the graph.
• The capstone gets NO provisional credit. An ordinary node advances on a stashed-but-ungraded prerequisite (so the tutor can keep teaching while the assessor works). The capstone does not — it is the claim that the learner can now use the topic, and serving it on mastery the assessor has not confirmed is exactly the unearned claim the constitution forbids. Found by an existing check breaking the moment the capstone entered the DAG.
• A payload can no longer claim a transfer state or mint its own capstone (invariant #4: state advances only through receipts).
• due now carries transfer_ready + transfer_probe, so /review serves the harder question without a second engine call.

§4.8 Q1 caught a two-bar bug before the gate even ran

The first cut reported a single rate counting anything not-lapsed — so a node whose only transfer receipt was partial read rate: 1.0 while its own state read probed, because state: applied requires recalled. Two numbers, one state, two silently different definitions of success — and the looser one was the flattering one.

Now rate_fired (recalled only — the bar state: applied uses) is the headline, because "is this capability mine?" is a yes/no question and a half-application is not a yes. rate_any (recalled-or-partial) ships beside it, because that is the same bar retention uses and the two numbers are only comparable if they are measured the same way. There is no bare rate key.

The new protocol gates, applied to the release that wrote them

• §5.5 THE INSTRUMENT GATE — earned in v0.7.1, where a gold set built to catch a lenient grader turned out to be rewarding leniency. stats.transfer certifies ("this capability is yours"), so a deliberately WRONG subject must score WORSE: a learner who fails every transfer probe now provably reads below one whose capability fires. A ruler that ranks failure above success is not a lenient ruler; it is a negative one, and every number downstream has its sign flipped.
• §4.8 Q4 — open the dashboard. stats.transfer renders on the HTML page, and "NO CAPABILITY HAS EVER BEEN MEASURED" appears there in red — not only in the JSON that just a test ever opens. That is the rule v0.7 shipped a bug to learn.
• §4.7 — enumerate the read paths from the dispatch table, not from memory. It caught transfer missing from the fuzzer immediately. Fuzz: 0 crashes / 9,600 invocations, 16 read paths.

0.7.1 — 2026-07-11 · THE GOLD SET FAILED BEFORE THE GRADER DID

Shipped within the hour of v0.7.0, because the post-release review (§7.5) found that the instrument built to catch a lenient grader was itself rewarding leniency. Everything below was found in shipped code, by a reviewer who was not the author.

The finding, and it is more important than any number here

The reviewer ran the one test nobody had thought to run: it graded the gold set with a correct grader and with a deliberately fooled one.

grader	QWK
says lapsed on g_009 (correct — 0 of 3 rubric criteria met)	0.990
says partial on g_009 (fooled by a fluent-but-empty production)	1.000

The fooled grader scored higher. The gold set was ranking leniency above correctness. The instrument was inverted.

The cause: five lenient adjudications by the gold set's own author, every one the same species — crediting an adjacent fact as partial credit. Majority is not intersection (g_034). Consonance is not pitch-set arithmetic (g_038). The history of a theory is not its mechanism (g_009). "It's ambiguous, break the tie" is not "the vectors assert concurrency" (g_039). "You don't need inference any more" is not "the likelihood dominates" (g_032).

The grader had caught all five, three runs out of three — including on a fluent-but-empty item, which means the author was fooled by fluency in the very category built to catch being fooled by fluency.

What that does to the number

Correcting them moves agreement 0.889 → 0.965 and QWK 0.93 → 0.978.

That rise is not evidence the grader got better. It is evidence that the instrument had been measuring the AUTHOR'S inconsistency, not the grader's validity.

And the corrections were prompted by the grader's own disagreements — so the QWK that follows is circular. An authored gold set cannot validate a grader from the same model family: when the two disagree and the author concedes, the agreement that follows measures only the author's willingness to concede.

• The engine now says this on every audit (gold_adjudication: "authored", and the caveat rides in the read string), until someone who is not the author adjudicates the set.
• The QWK badge is gone. Replaced by grader never inflates · 0/198 — the one claim that survives, and that the correction made stronger: every authoring error was LENIENT, so fixing them moved the bar down, giving the grader more room to be caught inflating. Across 198 blind judgments it still graded UP exactly zero times. That is a safety property, and it does not depend on the gold being perfectly calibrated.
• One genuine disagreement (g_054) is deliberately KEPT. The reviewer read both readings and judged the gold's defensible. Correcting an item to match the grader when an independent party says the gold was right is exactly the fitting that turns a measurement into a mirror. An instrument with no disagreement left in it measures nothing.
• Every corrected item carries a disputed record with its original grade, so the correction is auditable rather than laundered.
• by_case_type["fluent-but-empty"] — the canary v0.7.0 told v0.8 to watch for harshness drift — was reading 90% / −0.10 when the truth was 100% / +0.00. A maintainer could have "fixed" a harshness that did not exist by loosening the grader on precisely the case the separation of powers exists to protect.

And three more, all in shipped code

1. A pass threw away its own caveats — and pass is the ONE verdict where the teeth are off. The pass branch built a fresh read and never joined reasons; grader-health never returned the key at all, though skills/coach is told to "read reasons aloud." So three copy-pasted runs produced identical_runs: true, the engine wrote "test-retest measures nothing here" to disk — and then printed "test-retest 1.00" as a validated figure. The most reassuring number in the payload, quoted as evidence, by the branch that had just discarded the note explaining it was evidence of nothing. Bug class #4 — a guard nobody reads — reproduced inside the release built to catch it. And the selftest was complicit: it asserted reasons contained the caveat, which proves nothing about whether any surface ever reads it. A field is not a narrator.
2. grader_unvalidated was believed from the file instead of derived from the verdict. An audit carrying "verdict": "fail" with "grader_unvalidated": false silenced the teeth completely — no stamp, no red on the dashboard, retention reading a clean "30-day recall 100%" — in the one function whose docstring swears it "fails toward 'we don't know', never toward 'it's fine'." It is now a function of the verdict, not an input.
3. cmd_artifact set|clear was the last mutator reading a raw node value — TypeError on a corrupt node. Worse than an ordinary crash: doctor recommends artifact clear as the fix for a corrupt artifact field, so the repair the tool told you to run was the thing that blew up.

0.7.0 — 2026-07-11 · THE ORACLE — the grader that writes every receipt has now itself been graded

The blind assessor's verdict drives mastery, retention, calibration, and the schedule. Its agreement with any ground truth had never been measured. The constitution says "the oracle is never a vibe"; it had been one — an excellent one, unaudited — and the hole sat directly under the foundation, because if the grader is lenient, every number Engram has ever printed is inflated and nothing in the system could discover it.

Selftest 129 → 152.

The result — and we publish it whatever it says

Ran the real assessor against the new gold set, three independent times, blind:

QWK 0.93	vs. a 0.70 conventional bar, 0.60 floor
leniency bias −0.11	signed, + = inflating. It is harsh, not lenient
0 of 198 judgments graded UP	66 items × 3 runs. It has never once inflated a grade
test–retest 0.97	consistency — which the engine deliberately refuses to accept as validity
verdict pass	so retention figures are not stamped grader_unvalidated

The bug class this whole release was built to catch — a lenient oracle quietly inflating every retention number — does not exist in this grader. It errs only in the safe direction. That was worth finding out, and it was not knowable before today.

Weakest case type: right-answer-wrong-reason — 52% agreement, bias −0.48. On productions that reach the correct conclusion through a broken derivation, the grader is harsher than our adjudication. Whether the grader or the gold set is right there is honestly open, and it ships written down rather than smoothed away.

The caveat that matters most: the gold adjudications are authored, not independently human-adjudicated. Every item carries a written rationale you can dispute, and a dispute is a first-class contribution (gold/local-gold.jsonl overrides ours by sid). But an authored gold set is a weaker instrument than a human-adjudicated one, and saying otherwise would be the exact dishonesty this feature exists to kill.

Engine

• gold — the 66-item gold set, 88% adversarial (fluent-but-empty, terse-but-correct, confident-and-wrong, right-answer-wrong-reason, paraphrase, partial-credit boundary), emitted as a bare array shaped exactly like stash list and stripped of the answer by construction. The strip is a whitelist, not a blacklist: a field added to the gold schema later cannot leak by being forgotten in a delete-list.
• assessor-audit --file F — QWK (the headline), raw agreement (never quoted alone — it overstates chance-corrected agreement by 34–41 points), signed leniency bias, test–retest over ≥3 runs, confusion matrix, per-case-type breakdown. Writes audits/<date>-NN.json.
• grader-health — the latest audit's verdict. stats embeds it.
• THE TEETH — qwk < 0.60, leniency_bias > +0.15, or the paradox → grader_unvalidated: true on every retention figure, and the stamp goes into the read string the narrator actually speaks, not a nested key only a test ever opens. An unaudited grader is unvalidated too: it fails toward "we don't know", never toward "it's fine".
• The consistency–bias paradox gate. Engram's assessor is prompted to be a skeptic, so it will be extremely self-consistent — and the literature's central warning is that a judge can hit test–retest 0.992 with bias 0.192: perfectly reproducible, systematically wrong. So consistency may never certify. Above 0.95 test–retest the engine demands leniency strictly under the ceiling, and fewer than three runs cannot pass at all (insufficient-runs).
• ONE denominator for every number in the audit — the gold items graded in every run. A grader that silently drops 20 of 66 sids and nails the rest reports incomplete, never a flattering QWK 1.00 pass. (That is issue #3's bug class aimed at the audit itself.)
• The contamination guard. If the grader's output carries gold_grade, it was shown gold_grade — the audit dies rather than certify. A test that hands the subject the answer is not a test, and v0.6 shipped a dead feature because a dogfood did exactly that.
• Receipts carry grader when the assessor states it, and the engine never invents one. A model naming its own weights is fabricated data; an omitted grader stays honestly null.

The pre-existing crash class this release also fixes — 447 crashes, in shipped code

The v0.7 fuzz gate ran the read paths that v0.6's fuzz list had never included — and found 447 crashes in 300 garbage states on main. Every one in next and topic-status: nodes as a string, order holding a dict (an unhashable key), a node that is a list.

next is the command /learn calls at the start of every session — the hottest path in the product. A hand-edited graph could take it down mid-lesson, and it could have done so since v0.1.

The cause has exactly the shape of the original bug: v0.6 put a shape gate in iter_graphs — which every aggregate read funnels through — and load_graph, the gate every single-topic command funnels through, never got one. The v0.6 fuzz list was written from the /coach surface and simply forgot the /learn surface. The list you write is the list you already thought of.

• load_graph now refuses an unusable graph with a fix path, instead of half-reading it. It drops and rewrites nothing — mutators save what they read, so a lossy "repair" here would be a data-loss bug wearing a hard hat.
• graph_nodes / graph_order — the read views that tolerate partial garbage.
• apply_item refuses to advance a schedule into a corrupt node rather than write FSRS state on top of garbage (receipts are append-only; bad evidence could never be taken back).
• reps and lapses were the last two raw arithmetic leaves in the scheduler — every other one already went through as_number, and these two did fsrs.get("reps", 0) + 1 straight. A hand-edited "reps": "many" raised TypeError on the mutator path too, so it took rate down, not just decay.
• Fuzz: 891 → 0 crashes across 750 states × 13 read paths (9,750 invocations, 3 seeds).

The three selftests that turned out to be theatre

§4.5 (mutation-test every new check) caught three of this release's own checks faking it — the same rate as v0.6, which is the honest news here: writing a fake check is the default, and only the mutation test finds it.

1. "QWK weights are QUADRATIC" asserted only that a 2-step error hurts more than a 1-step one — which linear weights satisfy just as happily. Reverting the fix left it green. (And a balanced confusion matrix is no good either: with equal marginals the two schemes normalize to the same kappa and prove nothing.) Now pinned to a hand-computed value on an unbalanced matrix carrying both error distances: quadratic → 0.383, linear → 0.407.
2. "raw agreement is a liar" did not isolate the QWK floor — its always-says-recalled grader trips the bias ceiling too, so reverting the floor left it green. Now paired with a noisy but perfectly unbiased grader (bias exactly 0.00) that only the floor can catch.
3. "a grader that drops sids" used three identical runs — so the union and the intersection of graded sids were the same set, and swapping the honest denominator for the flattering one changed nothing. Now each run drops a different five.

The mutation run also surfaced a latent crash: the pass read formatted test_retest with %.2f, and the only thing between it and a TypeError on None was a branch three ifs up the ladder — a landmine for whoever next edits the verdict order.

And the check harness itself got fixed: a check that raises now fails BY NAME instead of taking the whole suite down. Every mutation of a crash-guard used to report "the selftest crashed" — true, unmissable, and useless for locating which guard you just reverted.

What the independent reviewer found — 8 defects behind 155 green checks

Every gate above is run by the person who wrote the code, on the code they believe is right. That is their structural limit. §4.6 found eight more, and the worst of them is the one this release was supposedly about.

1. THE TEETH NEVER REACHED THE HTML DASHBOARD. retention.read was the only carrier of the grader stamp, and cmd_report rendered it exclusively in the branch that fires when there is no retention data. On the happy path it drew the bars and threw the stamp away. So a grader that inflated every second item produced a full-width green bar reading 100%, with nothing anywhere on the page to say the grade behind it had failed its own audit — grep -ci 'grader\|unvalidated\|qwk' dashboard.html → 0. That is bug class #1 and #4, on the single surface where a number is most believed. compute_retention's own comment claimed the dashboard was covered; the dashboard funnelled through the function and discarded the result. The live test, the fuzz, the numbers audit and the user session all walked straight past it — because every one of them reads JSON. The dashboard now renders the read unconditionally, stamps it, and carries a full grader block (QWK · leniency · graded-UP).
2. gold_source — the §4.8 Q5 fix — asserted a provenance that was FALSE. gold/local-gold.jsonl overrides bundled adjudications by sid, on the default path, no flag required. A local file that re-grades the set to agree with the grader turns fail (QWK 0.55, leniency +0.64) into pass (QWK 1.00) — and the audit still wrote "bundled:gold/assessor-gold.jsonl" into the file. A provenance field that lies is worse than no provenance field, because it is believed. Now load_gold counts overrides and additions, gold_source names them, and a pass against a modified gold set is stamped as such on every retention figure.
3. A grader could mark its own homework twice and keep the better score. _run_grades was last-wins, so a grader that got 12 items wrong and re-emitted those sids later in the array — exactly what an LLM self-correcting mid-array produces — turned fail (QWK 0.00, leniency +0.67) into pass (QWK 1.00), silently, with n intact. The mirror image of the dropped-sid bug the coverage guard already caught: same class, opposite mechanism. First verdict stands; duplicates are a coverage failure.
4. Three copy-pasted runs are indistinguishable from three independent ones. test_retest: 1.00 then asserts a reproducibility figure nobody measured — and MIN_AUDIT_RUNS and the paradox gate, which exist precisely to prevent that, are both satisfied by copy-paste. The engine cannot prove independence, so it now refuses to claim it: identical runs are flagged and named in the read.
5. The new corrupt-node refusal tore a receipt batch in half. The cmd_receipt pre-flight promised "confirm every node exists before applying ANY, so a bad item can't half-apply the batch" — and checked existence, not shape. v0.7 added a die() inside apply_item that the pre-flight didn't screen for, so a 3-item batch with a corrupt middle node wrote item 1's receipt and then died. Receipts are append-only. A new refusal must be hoisted into the pre-flight, or it is not a refusal — it is a tear.
6. Audit 99 shadowed audit 100. sorted() on 2026-07-11-100.json puts it before -99.json, so the 100th audit of a day — a fail — would be overruled by the 99th, a pass. Improbable and flattering, which is the worst pair. Now sorted numerically.
7. The contamination guard falsely accused innocent graders. It died on any output key named rationale — the single most natural key for a grader to invent unprompted — accusing it of having been shown the answer and making the audit unrunnable. Narrowed to gold_grade and case_type, the two keys that could only come from the gold schema.
8. leniency_bias is measured on an 88%-adversarial set, so it bounds how far the grader can be pushed; it is not an unbiased estimate of its bias on ordinary productions. The read presented it as the latter. Now says so, in the payload.

The reviewer also independently verified the QWK math against a closed-form variance implementation over 4,000 random matrices (max diff 6.7e-16), confirmed the GRADES/GOLD_SCORE ordinal trap is not hit, reproduced the crash-class fix (506 → 0 on its own fuzzer), and read all 24 recalled and all 9 right-answer-wrong-reason gold items, finding no adjudication error in the lenient direction.

Behavior

• /coach reports the oracle before any number it produced. unaudited → one calm line, once, and the dashboard still runs. fail → said first, plainly, with every retention figure named as unearned until it is fixed. Raw agreement never travels without its QWK.
• /coach audit — runs the real assessor on the gold set, three independent times, and narrates the engine's verdict. The assessor is never told it is being audited: a subject that knows it is being tested is not the subject.
• The §5.6 user session, run against the founder's own state, killed a line before it shipped. It read: "[grader unaudited — QWK unknown; run /coach audit] insufficient-data (no reviews yet)" — a caveat on a number that does not exist, stacked as a second reproach on top of "THE LOOP HAS NEVER CLOSED". That is the wall of debt, and the wall of debt is the churn trigger, not the cure (docs/05 P14). The flag stays true in the payload; the narrator is no longer handed a disclaimer for a measurement nobody made. No selftest could have found it. A person had to look at the screen.

Also

• audits/ and gold/ created on init. The bundled gold set is not copied into the state dir — a copy would shadow the plugin's set forever, so a future gold item would never reach an existing learner. The plugin's file is the source of truth; gold/local-gold.jsonl is additive and wins on a sid collision, because a human who disputed an adjudication outranks ours.
• Audits are append-only, like receipts. A same-day re-audit writes -02, never overwrites. (docs/09 §3.4 specified <date>.json; destroying evidence to keep a filename tidy is not a trade this project makes.)
• A corrupt latest audit reads unreadable and never falls back to an older, rosier one. A stale pass is worse than no pass.
• Codex parity: codex/agents/engram-assessor.toml carries grader, in lockstep.

0.6.4 — 2026-07-11 · one definition of "review", and the denominator on the label

Found by running §7.5 (post-release review) and §4.8 (the numbers audit) of the release protocol on the release that added them. Both are cross-command disagreements: the engine telling one story in one place and a different story in another, on the same state.

1. Four implementations of one rule, three of them wrong

v0.6.1 established the principle — a node's first receipt is its ENCODING event, whatever it is labelled — and fixed it in _by_node, which feeds adherence and retention. It left stats.reviews, compute_momentum, compute_modality and the calibration split filtering on kind == "review" directly.

rate --kind defaults to "review", so a bare CLI rate on a never-encoded node produced this, on one state:

adherence.loop_closure : 0 reviews     ← correct
retention.coverage     : 0 reviews     ← correct
stats.reviews          : 1             ← wrong
modality.dialogue.n    : 1             ← wrong, and it CORRUPTS the medium telemetry:
                                          an ENCODING receipt became a node's "first review",
                                          which is the exact comparison docs/06 exists to make
calibration.n          : 1             ← wrong pool (it is an encode, not a retrieval)

Two commands, same state, contradictory answers. Fixed: one predicate, _review_receipts(), shared by every counter. adherence, retention, stats, momentum, modality and both calibration pools now agree by construction.

(The three selftests that broke on this fix were themselves the tell: they passed synthetic receipts carrying no topic/node at all — fixtures that had never been shaped like real data. They were rewritten as real receipt streams.)

2. The denominator was not on the label

Three surfaces reported "current recall" and meant different populations:

retention.unmeasured.projected_recall_now : 56%   over the PAST-DUE nodes
session hook ("those N sit at ~X%")       : 56%   over the PAST-DUE nodes
decay.now.mean_recall                     : 66%   over ALL ENCODED nodes

Neither number was lying. The labels were. Both are correct for what they measure, and a learner comparing them could not possibly tell which to believe. decay now ships mean_recall_due beside mean_recall, with a population string naming each denominator — and the three surfaces reconcile exactly.

Engine (selftest 127 → 129)

Both fixes selftested and mutation-tested. A new check asserts the cross-command agreement directly, so the four counters can never drift apart again.

No schema change, no migration.

0.6.3 — 2026-07-11 · what a real session found

The release protocol gained a gate it never had — §5.6, the user session: stop testing, be a learner, and write down how it felt. This is the first release to pass through it, and it found three things that 126 selftests, a fuzzer, two adversarial reviews and an agent dogfood all walked straight past — because none of them reads the sentence as a human.

Full report: docs/user-sessions/v0.6.2.md.

The seven-minute silence

The curriculum architect took ~7 minutes of completely silent terminal before the first question. No spinner, no "this takes a minute", nothing. That silence lands before the learner has seen a single thing this product does well — and it is, by a distance, the most likely moment a first-time user closes the tab. A stranger will not stare at a blank screen for seven minutes on faith.

/learn now sets the expectation before it spawns the architect. One line of prose, and it is the highest-value change in this release.

decay told you reviewing was pointless

With nothing yet due, decay reported:

"1 concept encoded; 0.4 expected to survive 30 days untouched, 0.4 if reviewed today (0 minutes) — a difference of 0.0"

Arithmetically correct — nothing is due, so there is nothing to review today. Rhetorically the exact opposite of the truth: a learner reads "a difference of 0.0" and concludes reviewing buys nothing. This is the same bug class v0.6.1/v0.6.2 are named for — a number that misleads — simply pointing the other way. It now says:

"1 concept encoded, none due yet — nothing to save today. The schedule brings each one back just before it fades; 0.6 of 1 are expected to survive the next 30 days on that schedule."

Two adjacent sections both called "Retention"

The dashboard put "Retention — recall by days since you first learned it" directly above "Retention by memory strength", and a user cannot tell which is the real number. The older view is renamed and demoted.

Engine (selftest 126 → 127)

• decay with an empty due queue emits an honest read instead of a discouraging zero. Selftest added and mutation-tested.

• The dashboard could be killed by a hand-edited state. cmd_report tested st not in STATE_DOTS without coercing first — an unhashable value (state: {}) raises TypeError and takes /coach's HTML down. state_counts() was guarded for exactly this and cmd_report was not. Caught by the §4.7 fuzz gate on its first run under the new protocol — 35 crashes / 500 states, from a generator shape the previous sweep never produced. Now 0 / 900 across 3 seeds, with an unhashable-state fixture added to the read-path check.

  (And the first version of that check was itself theatre — the fixture's order didn't list the new nodes, so cmd_report never visited them. §4.5 caught it. The gates catch the gates.)

Release protocol

RELEASE_PROTOCOL.md substantially rewritten around what actually caught bugs across v0.5–v0.6:

• The bug classes this repo cannot ship — led by a number wrong in the flattering direction, because a crash gets fixed and a flattering number gets believed.
• §4.5 mutation-test every new check — three of ours were theatre (one asserted a constant; one had a fixture where the old and new definitions agreed by coincidence).
• §4.7 the fuzz gate — 0 crashes / 500 type-corrupt states. Read paths degrade; doctor reports corruption and must never die of what it exists to find.
• §4.8 the numbers audit — five questions, answered in writing, for every number a release adds. Question 1 is "do the engine's own commands agree with each other?" — retention once said 100% while decay said 56%, and nobody had ever run them side by side.
• §5.5 the dogfood must be UNCONTAMINATED — give each agent exactly what the real skill gives it. Ours once certified a dead feature because the prompt handed the assessor the answer.
• §5.6 the user session — the gate this release is named for. Its verdict is binding: if you would not hand it to a stranger, it does not ship, however green the tests are.
• §7.5 the post-release review — because the two worst v0.6 bugs were found in shipped code.

No schema change, no migration.

0.6.2 — 2026-07-11 · the honest denominator was not honest

Four defects in released v0.6.0/v0.6.1, found by an independent reviewer working from the shipped code — none of them in the nine the pre-release review caught. Two are the same failure mode this release was written to eliminate, hiding inside the machinery written to eliminate it.

1. HIGH — the honest denominator exempted anyone who reviewed once, ever

retention.unmeasured counted concepts that came due and were never reviewed. So a node was exempted the moment it was retrieved even once — forever after.

Reproduced on shipped code: encode ten concepts, review all ten at day 7 (all recalled), then vanish for 200 days.

retention.read   : "measured over 10 retrievals"      buckets: 7d n=10, rate 1.0
unmeasured       : 0
coverage         : complete
loop_closure     : "the loop is closing"

the engine's OWN decay command, on the same state:
  10 concepts due · mean current recall 56%

The dashboard reported 100% recall, nothing unmeasured, loop closing while ten concepts sat at 56% and falling. That is "survivorship bias with a progress bar" — this block's own docstring — reproduced inside the block written to prevent it. The coverage guard could not see it either: coverage counts reviews, and every review here bucketed perfectly.

Fixed. The denominator is now everything past due right now (past_due_now), with never_reviewed kept as a sub-count. A node past due now has, by definition, not been retrieved since it came due — whatever its history. And the debt now reaches the narrator, not just a nested key: every read string carries it, because a read of "measured over 10 retrievals" while ten concepts rot is precisely the lie.

2. HIGH — the normal settle path destroyed a second, ungraded production

v0.6.0 fixed drop_stash(topic, node) on the rare idempotent no-op branch and left it live on the branch that runs on every single settle. stash add appends without deduping on node, so a node can legitimately hold two productions (a re-attempt, a park-and-resume, a slow assessor). Settling the first drained both:

stash before : [P1, P2 — second attempt, never graded]
settle P1    -> stash after: []          P2 is gone. Never assessed, never a receipt.

The exact data loss that was fixed on the rare path, still live on the common one. Fixed: a settle drains only its own sid; the legacy sid-less rate path keeps its self-drain.

3. MEDIUM — kind was unvalidated, and the two entry points disagreed on its default

rate --kind defaulted to "review"; cmd_receipt defaulted to "encode"; neither validated it. Every v0.6 metric keys off the exact literal "review", so a typo'd or invented kind is permanently invisible to loop_closure, every retention bucket, calibration and stats.reviews — and unfixable, because receipts are append-only. This was also the root cause of v0.6.1. Fixed: a KINDS constant, choices= on the flag, and validation in validate_item, so a bad batch dies before any write.

4. LOW

• A backward clock step could stamp a negative days_since_encode into an append-only receipt, permanently. Clamped to ≥ 0.
• commit --clear --cue X --action Y silently cleared (the elif made the set-branch unreachable). Now refused.

Engine (selftest 120 → 126)

Six new checks, every one mutation-tested — reverted to the broken behaviour to confirm it actually fails. Verified against the founder's real state: all numbers unchanged and now mutually consistent (retention and decay both report 70%), state byte-identical.

No schema migration. retention.unmeasured.past_due_never_reviewed is replaced by past_due_now + never_reviewed; nothing outside this repo consumed it (v0.6 is hours old).

0.6.1 — 2026-07-11 · loop_closure could lie in the one direction that matters

A defect in v0.6.0, found by an independent reviewer after release. It is small, it is narrow, and it is exactly the kind this release cannot tolerate — the metric built to say "you never came back" could say the opposite.

rate's --kind argparse default is "review". The skills always pass an explicit --kind, so the documented flows are unaffected — but a bare CLI rate --topic t --node a --rating good writes that node's only receipt as kind: review. _by_node then treated that single receipt as both the node's day-0 encoding event and a retention test, so:

loop_closure:  1 of 1  ·  rate 1.0  ·  "the loop is closing"

…for a learner who had never come back once. retention likewise counted it as a day-0 retrieval.

The fix is a principle, not a patch: a node's FIRST receipt is its encoding event, whatever it happens to be labelled. There was no prior memory to retain, so a first exposure cannot be a retention test and must never count toward loop_closure or a retention bucket. A genuine second retrieval still closes the loop, exactly as before.

Wrong numbers are the only bug class this project is not allowed to ship. A number that is wrong in the flattering direction — telling a learner their loop is closing when they have abandoned it — is the worst instance of it.

Engine (selftest 119 → 120)

• _by_node: the first receipt is never appended to a node's reviews list. Covered by a selftest that asserts both directions (a once-touched node reads NEVER CLOSED; a real second retrieval reads 1.0), and mutation-tested to confirm it fails without the fix.

No schema change, no migration, no default change.

0.6.0 — 2026-07-11 · the loop closes

Engram has been an excellent encoding machine bolted to a retention machine that never ran. This release is about the second half.

The finding that forced it, found by reading the author's own state: on 2026-07-05 he ran a 45-minute /learn on transformer internals. The architect built a 13-node DAG, the tutor ran generation-first dialogue, the smith built an explorable, the blind assessor graded six productions and honestly rounded most down to partial. Seven concepts encoded, seven review dates booked. Then nobody came back. Six days later: zero reviews, zero streak, seven items overdue, one session in the log — ever. Meanwhile 501 people starred the repo.

Run Engram's own FSRS curve over Engram's own state and it says: those seven decay to 2.7 of 7 over the next 30 days untouched, or hold at 5.6 of 7 if the four-minute review happens — a difference of 2.9 concepts. The engine could always compute both numbers. Its entire ambient surface, on the sixth day of a memory dying on schedule, was [engram] 7 reviews due.

This is not a story about a lazy user. It is the product's own failure mode executing perfectly on the person most invested in it, which makes it architectural rather than personal.

Three gaps, each confirmed by reading the code rather than the docs:

• The north star was never implemented. docs/04 named "7-day and 30-day retention on scheduled reviews" the north star in Phase 0. grep found no such metric. stats bucketed by memory strength, never elapsed time. Naming a metric is not measuring it.
• Adherence was invisible. No signal anywhere for "was this encoded concept ever reviewed?" The system could not see its own binding constraint.
• receipt --file was not idempotent (issue #3) — a crash-retry between receipt and stash clear double-counted reps permanently.

Engine (selftest 86 → 119)

• adherence — the funnel Engram never looked at: loop_closure (encoded → came due → actually reviewed), return (session cadence, days since last), funnel (topic → encoded → due → reviewed → retained@30d). Pure read over data already on disk; no schema change. loop_closure is the binding-constraint number: the value a learning system produces is Return × Encoding × Retention × Transfer, and those terms multiply — a perfect encoder with zero return is worth exactly zero.
• retention — the north star, finally computed. Recall bucketed by each review's own days-since-first-encode, in windows that partition [0, ∞) so no review is ever dropped: early 0–3 (still re-encoding — reported, never pooled into a retention claim) · 7d 4–14 · 30d 15–59 (the headline) · 90d 60–179 · 180d+. Ships two honesty guards:
  • unmeasured — the concepts that came due and were never reviewed. Their recall is unknown, not absent, and FSRS projects it. A retention figure computed only over completed reviews silently drops exactly the concepts the learner abandoned — survivorship bias with a progress bar. The engine refuses to report one without the other.
  • coverage — reviews_bucketed / reviews_total, which must be 1.0. This exists because the first cut of this feature used disjoint windows (5–10 / 25–40 / 80–110) and the live test caught a real day-11 review falling into a gap and vanishing — retention cheerfully reported "no reviews yet" with a review sitting on disk. Under real FSRS intervals (~4d, ~12d, ~30d, ~70d) most reviews would have landed in those holes and the north star would have been computed on an arbitrary subset of the evidence. A metric that quietly discards data is worse than no metric. Now selftested by sweeping 19 elapsed-day values across the full range.
• decay — what is dying and what N minutes would save, in real FSRS numbers. Both arms measured over the same future window, so it is a comparison rather than a rhetorical device. The due payload now carries last, so current recall is computed from the learner's actual last retrieval rather than reconstructed from interval_for(s, 0.90) + overdue — a reconstruction that silently breaks for anyone who moved desired_retention (measured: 3.3 percentage points of overstated decay at 0.97) and breaks in the one direction an honesty feature is not permitted to err in: alarming the learner.
• commit — the learner's implementation intention, in their own words (Gollwitzer & Sheeran 2006: 94 tests, N > 8,000, d = 0.65, robust to publication-bias correction). Stored because they said it, shown back at the moment it names, never enforced.
• sid — receipts are idempotent (closes #3). The stash id rides stash → assessor → receipt; apply_item refuses one already on disk. Additive: a receipt without a sid applies exactly as in v0.5.
• days_since_encode stamped on every receipt — makes the north star a one-pass query.
• Fixed a latent race, present since v0.5: report and doctor called load_model(), which persists a self-heal — while holding no lock. An unlocked read could flush a stale snapshot over a concurrent locked mutator, silently reverting a refit. New read_model() heals in memory and never writes. Covered by a selftest that fails without it.
• Receipt log is cached per process, keyed by absolute path. A batch settle re-read the whole topic log once per item — measured at 1.85s for a 60-item settle against a 10k-line log, now 0.19s. The cache is keyed by path (never by topic alone, or a second ENGRAM_HOME would read the first one's receipts) and kept in sync on append, so a duplicate sid appearing later in the same batch is still caught. Both properties have selftests.
• Read paths now degrade instead of bricking — a whole class of crashes, several pre-existing. Fuzzing 3,000 randomized garbage states found 259 unhandled crashes in the first 300. A hand-edited state file can be perfectly valid JSON with the wrong types: nodes as a string, fsrs as a list, an unhashable topic, a rating that is a dict — and every one of those raised TypeError/AttributeError and took stats down with it, and therefore /coach. Several predate this release (compute_momentum since v0.4, due_items and compute_streak since v0.1, _outcome since v0.3, compute_modality since v0.5); v0.6 widened the blast radius by making stats call adherence and retention too. The fix is one gate, not twenty patches: iter_graphs now validates the graph's shape and skips what is structurally unusable, because every read path funnels through it. doctor still reads graphs raw — it is the thing that reports corruption, and it must never die of what it is there to find. Now 0 crashes / 3,000 states, locked in by a selftest that feeds every read path a deliberately type-corrupt state and demands they all return.

What the adversarial review caught that the tests, the live test, and the dogfood all missed

Protocol step 4.5 earned its place again. Nine defects behind a green selftest, an exhaustive live test, and a passing agent dogfood — and the worst of them was one the dogfood had actively certified:

• Issue #3 was not actually fixed. The sid never survived the assessor, because agents/engram-assessor.md declares a strict output schema that never mentioned it. The guard was dead code in the shipped pipeline. The dogfood "passed" only because the prompt written for it told the assessor to pass the field through — an instruction the real /learn skill never gives. A test that hands the subject the answer is not a test. The sid is now part of the assessor's contract (Claude and Codex ports), /learn step 4 checks it came back before applying, and the round-trip has been re-verified with the real agent and no hint.
• The idempotent "no-op" was a data-loss bug. It called drop_stash(topic, node), which drains every stash entry for that node — so a crash-retry would silently destroy a second, newer, never-graded production. The guard written to prevent corruption would have corrupted. Now drops only its own sid.
• decay --topic <unknown> returned a confident false all-clear ("nothing to lose") instead of erroring. From a command whose entire job is honest accounting, that is the worst available failure mode. It now refuses.
• decay overstated its own headline. The benefit arm simulated reviewing every encoded node while pricing minutes from the due queue only. The not-yet-due nodes now keep their own curve in both arms — you are quoted exactly what those minutes buy.
• The coverage guard was inert. It was computed, stored in a nested key, and read by nobody — so the anti-data-loss check could not actually prevent the regression it existed for. An incomplete partition now hijacks read with UNTRUSTWORTHY in the one field a narrator is guaranteed to see.
• Two contradictory definitions of "retained at 30 days" shipped in the same payload — funnel.nodes_retained_30d used >= 25 days while retention's 30d bucket is [15, 59]. One definition now, from one source.
• A receipt with a missing ts sorted first and became a node's day-0 anchor, poisoning every elapsed-day metric downstream. Broken timestamps now sort last.
• median_gap_days was not a median (it took the upper element on even-length lists).
• The dashboard never showed any of it. /coach's HTML still headlined a strength-bucketed retention with no unmeasured denominator. It now opens with loop_closure and states the concepts that came due and were never reviewed.

Each has a selftest, and each selftest was mutation-tested — reverted to the broken behavior to confirm it actually fails. Two first drafts turned out to be theatre (one asserted a constant instead of a behavior; one had a fixture where the old and new definitions coincided by coincidence) and were rebuilt until the regression is genuinely caught.

Behavior

• The ambient hook now says what the decay costs — but only as a return event: it fires on a never-closed loop or after a real absence, never per-session. "Those 7 sit at ~70% recall and still falling · 4 min now is the difference between keeping them and re-learning them." Information, never pressure (docs/05 P13). No should, no scold, and settings.decay_notice = "off" silences it entirely.
• /review states the honest number once on return — after amnesty, before the capped offer. The order is: nothing is owed → here is what it costs → here is a two-minute path. Reversed, it is a debt collector.
• /learn books the return — one plain question at the close, their words, stored via commit, never enforced, never asked twice.
• /coach reports loop_closure FIRST. When it is zero it says so plainly and stops: there is no point narrating calibration over a loop that has never run.

Docs

• docs/07-the-measured-loop.md — the frontier audit. Learning rate is close to a category error (Koedinger 2023 PNAS, replicated EDM 2024: intercept variance dwarfs slope variance — you cannot make people climb faster, only give them more climbs; the 2026 re-analysis contesting the magnitude is recorded too). LLM-as-judge is "reliability without validity" (κ ≈ 0.38–0.51 vs humans; raw agreement overstates chance-corrected κ by 34–41 points; high self-consistency + high bias is the documented failure mode — precisely what a skeptic-prompted assessor selects for). Pan & Rickard 2018: retrieval transfers at d = 0.40, but d = 0.28 when the response format differs vs d = 0.58 when it matches — a quantified critique of verbal-only review for doing-goals. The n-of-1 machinery is underpowered ~2.5×.
• docs/08-vision.md — the objective function, which metrics are traps (confidence and joy both are), and the final state: Tutor → Instrument → Commons. Adds Article 11: the system's success is measured by what the learner can do without it.
• docs/09-target-architecture.md · docs/10-roadmap-to-1.0.md — schemas, invariants, and v0.6 → v1.0 as executable work orders.
• docs/04 marked complete and superseded.

Migration

None. Every field is additive and self-heals: a v0.5 (or v0.3) learner model gains commitment: null and decay_notice: "on" on next load and behaves exactly as before. Receipts without a sid apply as they always did. Nothing to migrate, nothing to delete.

0.5.2 — 2026-07-11 · confidence before the verdict, not after

Reported from real use (#4 — thank you, @kosh-jelly): at VERIFY the tutor praised the answer — "that's a complete, well-integrated answer…" — and then fired the confidence picker. A sureness collected after the learner has been told they nailed it is not sureness; it is an echo of the verdict. Confidence-before-feedback exists to measure calibration and to catch high-confidence errors for hypercorrection — both die the instant any signal of correctness reaches the learner first.

The intent was never in doubt: the picker itself asks "before I show the answer." The prose had a seam. The gate was worded around the reveal ("before you reveal or grade", "no canonical answer until confidence"), and /learn's VERIFY step granted "immediate content feedback is yours to give" right beside it. So the model did what a careful reading allowed — withheld the canonical answer, kept the picker's framing honest, and let the evaluation through. The pretest step one screen up already had the tight wording ("before saying anything about correctness"); VERIFY did not.

Behavior (prose only; selftest unchanged, 86 → 86)

• /learn VERIFY (skills/learn/SKILL.md): the pick fires first, gated on "before you say a word about correctness," with the exact failure banned by example ("that's complete," "close," "nice"). "Immediate content feedback is yours to give" moved to after the pick; the pick is now also stated to precede the stash (its value is a stash field, so it cannot come later).
• Confidence-integrity rule (skills/_shared/dialogue-grammar.md): "feedback" redefined as any signal of correctness — approving tone included — not just the shown answer.
• Anti-sycophancy oath (same file, hard rules): the gate broadened from "no canonical answer until confidence" to "no verdict — not even a bare 'that's right' — until confidence is collected."
• Terse-production move (same file): at VERIFY the "credit what's there" step now waits until after the confidence pick — closing the one path (a fragment answer) where the sharpened rule would otherwise still leak a correctness signal first. Found by this release's own adversarial review, not in the wild.

No engine touched: whether the tutor asks in the right order is a dialogue property, provable only by a live VERIFY, not a selftest. The old order didn't merely mis-sequence the question — it recorded a corrupted "Certain" as real calibration data. Putting the pick first is the fix; there is no unit test that can stand in for using it.

0.5.1 — 2026-07-10 · the modality confound, said out loud

Found by doing what the release protocol asks and 0.5.0 skipped: a real /learn session, driven end to end with the actual agents. The pipeline held up — the curriculum architect tagged every node's visual affordance, the artifact-smith built a Contract-v2 explorable for the threshold node and registered it unprompted, the blind assessor rounded a shaky production down to partial, and the receipt carried its medium stamp. But the session exposed something no code review could: the medium comparison in stats.modality is confounded by construction.

Explorables are routed to threshold and high-affordance concepts on purpose — that is the whole content rule. So the dialogue arm fills with the remaining material, and the two arms never differ only in medium. Under threshold-only the explorable arm is exactly the topic's hardest, portal concepts. A lower explorable-arm recall may mean nothing more than that explorables were spent on the hard things.

The number was already labeled suggestive. That was not enough: a coach narrating from the JSON could report it as a clean result. So the caveat now travels with the data.

Engine (selftest 85 → 86)

• stats.modality gains a caveat field, present in every read state (insufficient-data included), stating that the arms are not randomized and the comparison carries medium and material. Covered by a new selftest — a narrator reading only this JSON cannot see the verdict without seeing why it is soft.
• The dashboard's "Encoding medium" section prints the caveat beside the bars, so a learner reading the HTML alone gets the same warning.

Behavior

• /coach must voice the caveat whenever it reports the medium yield, and is explicitly forbidden from presenting the number as proof the medium works or fails. Sample narration updated to model the honest version.

Theory

• docs/06-visual-encoding.md open question 2 now documents the confound in full, including why it cannot be fixed by randomizing arms without violating the content rule the document itself establishes — and names the honest form of the question (a randomized experiment within one affordance class; future work).

Examples

• examples/pid-error-feedback-loop.html — the explorable the artifact-smith actually generated in that session (drone altitude hold; a wind gust drives the error, the throttle answers), now hosted next to the hand-authored reference implementation. Its header says which is which, because "the kind of thing Engram builds" and "the thing Engram built" are not the same claim.

No schema change, no default change, nothing to migrate.

0.5.0 — 2026-07-10 · the visual-encoding layer — explorables audited, adaptive, and measured

The explorable engine grows up. Until now, interactive explorables fired only on threshold nodes — which conflated importance with visualizability — the graph never recorded which artifacts existed (the smith wrote files nothing tracked), and nothing measured whether the medium actually works for a given learner. v0.5 fixes all three, under a new adversarially-verified evidence base.

Theory

• New: docs/06-visual-encoding.md — the visual-encoding audit, built the same way as docs/05: a fan-out research pass (27 primary sources, 135 claims extracted, the 25 load-bearing ones each verified by three refute-first voters; 23 survived, 2 killed). Adds Pillar 15 — the guided manipulable: manipulable models carry the largest verified interactivity effect (simulations g+ = 0.62), but guidance inside the artifact is the active ingredient (scaffolded versions of the same simulation g+ = 0.60; learner control per se g = 0.05 ≈ nothing; unassisted discovery loses, d = −0.38), the payoff concentrates where the dynamics ARE the content (representational d = 0.40 vs decorative ≈ −0.05), and expertise reversal is a confirmed disordinal crossover (+0.505 novices / −0.428 knowledgeable, Tetzlaff 2025). Two refuted claims are recorded as do-not-build-on; four areas that produced no verifiable evidence (visual retrieval formats, n-of-1 medium methodology, preference-engagement value, LLM-artifact efficacy) are stated as open questions with deliberately conservative design stances.
• Explorable Contract v2 (same seven clauses, sharpened by the audit): the manipulable is now explicitly guided — predict → act → explain micro-cycle (self-explanation g = 0.46), content-relevant degrees of freedom only, a worked drive gates the model at novice scaffold (worked examples g = 0.48; "provide assistance when in doubt"); no text over motion; learner advances between segments, dynamics run themselves within one; registration is part of clause 7. New widget: feature-space navigator (several sliders, each a dimension; one holistic output morphing live — the founder's draggable-face moment, now in the vocabulary).

Engine (scripts/engram.py) — selftest 70 → 85

• artifact set|clear|list — explorable registration is now engine-owned like fsrs/state: the file must exist, paths under the state dir are stored home-relative, payload-supplied artifact values are stripped at add-topic, and registrations survive --replace alongside the schedule. (Fixes a real gap: built artifacts were invisible to the graph, so regeneration tracking and Contract clause 7 had no data trail.)
• Medium-stamped receipts — every rate/receipt stamps whether the node had a registered explorable at grading time, so evidence of the encoding medium can never be rewritten retroactively.
• stats.modality — the honest per-learner answer to "do explorables work for ME": first-review recall of explorable-encoded vs dialogue-only nodes, one datum per node, ≥6 per arm (the n-of-1 experiment floor) before any verdict; reads explorable-encoded ahead / dialogue-encoded ahead / indistinguishable / insufficient-data. Also rendered as an "Encoding medium" dashboard section. This is the instrument the Phase-2 exit criterion (docs/04) always called for.
• visuals eager|threshold|off|status — the discoverable dial over settings.artifacts, sibling to focus. eager extends explorables beyond threshold nodes to any node whose content declares high visual affordance. Default remains threshold-only: existing users see zero behavior change.
• viz node field — the curriculum architect now declares each node's visual affordance (affordance high|some|none, kind, one-line manipulation hook); the engine stores it opaquely (object kept, garbage dropped with a warning).
• due payload now carries an artifact presence flag (review's re-encode path reads it); doctor notes unregistered artifact files with the exact fix command (non-failing) and fails dangling registrations.

Behavior (skills + agents; defaults unchanged)

• /learn: explorables are now content-triggered and learner-dialed — threshold nodes as before; at visuals eager, also viz.affordance: high nodes; an explicit "make it visual" builds for any node at any level (autonomy override, same shape as "just tell me"). One ask-once-per-topic offer when a high-affordance node meets the default setting (arrow-key; "always" sets visuals eager with consent echoed back). The smith now runs in the background while the dialogue beats continue, registers what it builds, and hand-off is an arrow-key choice (open it now / homework — homework is the Sprint default; the two-minute floor outranks the medium).
• /review: the second-lapse re-encode move now knows whether an explorable already exists (regenerate it differently) or not (offer to build one) — background spawn, hand-off at the close, never mid-queue.
• /coach: narrates the medium comparison when it has a verdict, with its n and the explicit honesty that n-of-1 medium measurement is suggestive telemetry, not settled methodology; offers the matching visuals move arrow-key style, applied only on yes.
• curriculum-architect (both platforms): declares viz per node with an evidence leash — a false high is worse than a false none, because decorative interactivity reverses the effect (≈ −0.05).
• artifact-smith (both platforms): consumes viz.kind/viz.hook, applies the novice worked-drive gate, registers after writing, echoes the registration JSON in its report.

Hardening (adversarial review before release — 10 confirmed findings, all fixed)

• State mutex. Every state-mutating command now serializes on an advisory lockfile (.engram.lock; stale locks broken after 60s). The new background artifact-smith registering while the tutor rates on the same topic was a last-writer-wins race on the whole-file graph write — it could silently revert a just-graded node's schedule or drop a fresh registration.
• The valid_artifact gate. Receipt stamping, the due-payload flag, and --replace carry-forward now all require a non-empty string whose file exists. v0.4's add-topic silently kept payload-supplied artifact strings; without the gate those phantoms would stamp append-only receipts into the wrong modality arm forever. Registration also now survives a corrupt fsrs on restructure (it was being destroyed), and phantoms die at --replace instead of living on.
• doctor reports all artifact problems (unregistered, dangling, garbage-typed) as notes with pasteable shell-quoted fix commands — an upgrade must not flip doctor red for v0.4's own leniency.
• Input hardening: artifact list degrades gracefully on nodeless graphs and lists registrations on nodes outside order; visuals status reports a hand-edited non-string setting instead of crashing; add-topic rejects a non-object node with a clean error.
• README's visuals CLI row described the levels in swapped order (taught eager = default) — fixed. Selftest 79 → 85 across the fixes.

Packaging

• Version 0.5.0 everywhere (plugin.json ×2, badges); README: science point 6, visual FAQ entry, CLI table rows for visuals/artifact, docs table row for docs/06, Discord community badge (discord.gg/temm1e); INSTALL-CODEX selftest count 85/85.

Existing users: claude plugin marketplace update engram && claude plugin update engram@engram, then restart Claude Code. A v0.4 learner model self-heals; nothing about your schedule, receipts, or defaults changes until you touch the visuals dial. Optional one-time heal: doctor will point out any explorable built before 0.5 so you can register it (artifact set …) and start counting it in the medium comparison.

0.4.4 — 2026-07-09 · fix the confidence picker not firing (contradiction in the oath)

0.4.3 added the imperative picker instruction but a stale line survived in the most-obeyed section — the anti-sycophancy oath still read "Confidence in the same breath as the probe", which tells the tutor to ask for a number inline (the "Answer + 0-100" a user saw on 0.4.3). It overrode the new rule. The ⚠ section and beats were updated in 0.4.2/0.4.3; this oath line was missed.

Behavior (dialogue grammar; no engine change)

• The oath line is replaced with "Confidence is a picker, never a typed number", and the reveal is now gated on it: no canonical answer until confidence is collected via AskUserQuestion (or a volunteered number, or dismissed → null). Gating on the reveal — an action the tutor always performs — is the most reliable way to make the tool call fire, versus a standalone "please call the picker".
• Removed every remaining "answer + 0–100 / gut number" cue from probe-prompt guidance.

0.4.3 — 2026-07-09 · make the confidence picker actually fire

0.4.2 described the confidence picker but left the instruction too soft and framed it as a fallback after a text ask — so the tutor kept asking for a typed number instead of showing the arrow-key box. Fixed by adopting the production-grade pattern: an imperative MUST, the explicit AskUserQuestion(...) call inlined in the dialogue grammar, and no "give a number" wording left in any probe prompt.

Behavior (grammar + skills; no engine change)

• The four-band Confidence picker (Certain 90 / Pretty sure 70 / Half unsure 50 / Just guessing 25) is now the primary, mandatory way confidence is collected — before the reveal, every item — with the tool's built-in "Other" for an exact number or skip (→ null). The tutor only skips the picker if the learner volunteered a number unprompted. Applied to /learn encode, the pretest, and /review.
• Verified live: the picker renders and a selection round-trips to its number.

0.4.2 — 2026-07-09 · confidence UX — pick, don't type

Collecting the 0–100 gut-confidence (which powers calibration and hypercorrection — kept, because it earns its place) used to force the learner to type a number every item, then nagged with a text re-ask if they skipped it. Friction the data can't afford.

Behavior (dialogue grammar + skills; no engine change)

• Confidence is now a one-tap pick, not a typed number. It's offered as an optional add-on in the same breath as the probe (type …, about 70 if you like). If you give no number, a picker (AskUserQuestion) appears before the reveal with four bands — Certain (90) / Pretty sure (70) / Half unsure (50) / Just guessing (25), plus Other for an exact number or skip. Dismiss → null, still never estimated.
• Guardrails made explicit so the convenience stays honest and bugless: the picker fires before feedback every time (confidence-after-answer is discarded as null); a picked band is the learner's own stated confidence, not an invented one; and confidence is metadata, not knowledge, so a menu is allowed there while the probe stays open free-recall. Applied consistently across /learn encode, the pretest, and /review.

0.4.1 — 2026-07-09 · discoverable Focus mode + release hygiene

Follow-up to 0.4.0: the ADHD Focus profile shipped but was undiscoverable (no README, no clean command), and one toggle path was buggy.

Engine

• focus on|off|status command — a first-class, discoverable wrapper over model --set settings.profile=.... Turning it on flips the ADHD profile (Sprint default, competence growth surfaced every review, always-on amnesty); status reports without changing anything.
• Bug fix: model --set <key>=null now clears to real None, not the string "null" — so turning Focus (or any nullable setting) off actually works. null/none (any case) are recognized alongside the existing int/float/bool casts.
• Selftests 68 -> 70 (the focus on/off round-trip; the =null clear).

Docs

• README now documents Focus mode (FAQ entry + CLI table row) with both activation paths: say "I have ADHD, turn on focus mode" in /learn//coach, or run focus on. This omission is what prompted the fix — a shipped feature nobody can find isn't shipped.
• RELEASE_PROTOCOL.md added at root: the repeatable release checklist (version-bump locations, selftest gate, a live dogfood test, and the merge → tag → gh release steps), written after v0.4.0 shipped with its files bumped but no git tag / release cut.
• INSTALL-CODEX.md selftest count corrected (68 -> 70).

0.4.0 — 2026-07-09 · the affective layers (motivation + wisdom)

Two new layers around the unchanged engine, for the part the first four pillars implied but never voiced: why the learner returns tomorrow, and how a wise tutor carries them through the part where learning is supposed to hurt. Every load-bearing claim was assembled by an adversarial research pass (100+ searches, primary sources fetched, each number verified by a voter told to refute it) and is cited in the new theory doc. The design rule throughout: surface what is already true; invent nothing.

Theory

• docs/05-affective-layers.md — the constitution extension. Two new pillars: P13 Competence salience (making real progress visible is a reward without gamification's risks — Harkin 2016 d=0.40; Deci/Koestner/Ryan 1999 competence feedback d=+0.33 for adults, but d=−0.78 when controlling) and P14 The mentor stance (struggle-as-encoding, absolve-don't-pity, self-generated relevance, return-after-absence amnesty — Silverman & Barasch 2023; D'Mello 2014; Graham 1984). Includes the adversarial backbone (why not to gamify: Sailer & Homner 2020; Hanus & Fox 2015; over-helpful AI harms — Bastani 2025) and the ADHD resolution.

Engine (additive, default-safe — the FSRS core is untouched)

• stats.momentum — the deterministic core (never the model — Article 10) now computes a weekly competence-growth block from real receipts: reviews cleared, days of durability added (stability_gained_7d), genuine recalls, and the most-durable memory now. Purely additive to the stats JSON; ignored safely if unused.
• Two self-healed settings keys: settings.momentum (on/off) and settings.profile (null/adhd). A pre-0.4 model missing them is repaired on load (as every settings key already is) — behavior is byte-for-byte v0.3 with momentum off.
• Selftests 63 → 68 (durability arithmetic in isolation, in-window filtering, the no-negative-growth rule, the momentum block in stats, and the settings self-heal).

Behavior (skills & dialogue grammar — prose, no new commands)

• Naming real growth (/learn, /review): on a genuine stability gain, one flat informational line from the engine's own s_before → s_after ("holds ~9 days now, up from ~2") — never a score, streak, or should-statement; silent when settings.momentum=off or the gain isn't real.
• The mentor register (dialogue grammar): a bounded stance fired only at specific moments (difficulty, lapse, return-after-absence, sagging motivation), silence by default. Two new lines in the anti-sycophancy oath: encouragement is information, never pressure; after a lapse, absolve — never pity.
• Return-after-absence amnesty (/review): a large post-gap queue is met with amnesty + load renegotiation and a capped catch-up choice — the highest-evidence Layer-2 move — instead of dumping the debt.
• Momentum in the coach (/coach): the check-in opens by reporting real progress (the intervention itself — Harkin 2016), honestly saying so when nothing grew.
• ADHD Focus profile (settings.profile=adhd): turns up dials the skills already read (Sprint default, immediate growth surfacing, earlier boredom response, optional if-then plan, always-on amnesty). No new pedagogy, no game; a declared need, honored.
• README: v0.4 science paragraph, new pillar #5, docs table entry, version → 0.4.0.

0.3.0 — 2026-07-06 · bulletproof-foundation hardening + Codex support

A deep hardening pass before new features: every reported bug fixed, plus a full adversarial sweep of the boundary where LLM/human text enters the deterministic core. Two independent security audits, two code reviews, and a QA pass fed this; every fix is locked by a selftest (33 → 63 checks) and re-verified live.

Fixes for the reported issues (#1, #2)

• FSRS-4.5 difficulty anchor corrected. next_difficulty mean-reverted toward D0(4) (the FSRS-5 rule) under an otherwise-4.5 engine, inflating interval growth ~21% and silently undershooting the 90% retention target. Now reverts toward D0(3), per the open-spaced-repetition reference. Pinned by a fixed-point selftest. (#1)
• Evidence before state. apply_item now appends the receipt before saving the graph, so a crash (or a bad-type confidence that made make_receipt throw) can only ever cost a harmless re-review — never advance mastery with no receipt. (#1)
• refit --force on empty data no longer divides by zero. (#1)
• Corrupt state is quarantined, not discarded. A malformed JSON file is renamed to <file>.corrupt.<date> and surfaced by doctor, instead of being silently overwritten with defaults. (#1)
• Calibration scores partial credit correctly. It now reads the assessor grade (recalled=1.0 / partial=0.5 / lapsed=0.0), not the scheduler rating — a hard/partial answer was being scored as a total miss, flipping the verdict to "maximally overconfident". Confidence is clamped to 0–100; a min-n floor (10) replaces definitive verdicts on thin data with insufficient-data; encode-time confidences are split into their own pool instead of polluting review calibration. (#2)
• next is stash-aware. It skips a node whose production is already stashed, and treats a stashed-but-ungraded prerequisite as provisionally met — so the batch-graded /learn flow keeps advancing instead of re-serving one node or dead-ending on a chain. Payload now carries pending_verify and provisional_requires. (#2)
• --add-goal writes the previously orphan goals field; long productions carry a production_truncated marker instead of clipping silently. (#2)

Hardening (found in the sweep)

• Path-traversal / arbitrary-write closed. Topic slugs and node ids are validated at every ingress (add-topic, receipt, --topic), and all state writes are confined to the state dir (report --out too, unless --allow-outside); appends refuse to follow symlinks. An absolute/.. topic could previously write attacker-controlled JSON anywhere — including a malicious ~/.claude/settings.json.
• Shell-injection channel removed. The skills now pass learner text through a file or stdin (stash add --file, rate --production-file, --json -) and never inline it into a command; a hard rule was added to the dialogue grammar. A production (or a document being taught) containing ' or $(…) can no longer execute.
• add-topic no longer trusts LLM-supplied mastery. Payload state/fsrs are ignored (the engine owns scheduling — no mastery without receipts); --replace now preserves surviving nodes' schedule and writes a .bak instead of wiping it; order is deduped and requires-cycles are flagged.
• model --set can't brick the install — it refuses to overwrite an object with a scalar and clamps known numerics (a bad desired_retention no longer crashes every rate); the learner model self-heals a deleted/mistyped subtree on load.
• Batch receipts are atomic — every item is validated (and every node confirmed to exist) before any is applied; the stash self-drains as receipts land.
• Crash-proofing: malformed dates, unknown node states, ghost order ids, and one corrupt graph no longer brick topics/stats/report/due/session-start; the session hook only ever echoes validated slugs (closing an indirect prompt-injection vector) and degrades to silence on any failure.
• Report XSS closed — every interpolated field (incl. due/lapses) is escaped.
• Portability: dropped the hardcoded personal fallback path; cross-platform dashboard open (open/xdg-open/explorer.exe); scoped the "nothing leaves your machine" claim (the engine never egresses; the curriculum architect uses web search on the topic/goal). doctor gained checks for bad states, unparseable dates, and quarantined files.

Codex support (omni-repo)

• Engram now runs on OpenAI Codex from the same repo — skills/ and scripts/engram.py are shared verbatim. Added .codex-plugin/plugin.json, .agents/plugins/marketplace.json, TOML ports of the three subagents (codex/agents/*.toml), a self-resolving SessionStart hook, scripts/install-codex.sh, and INSTALL-CODEX.md. The Claude Code path is unchanged.

Known limitation

• Re-running the exact same receipt --file twice still double-applies (the settle flow clears the stash after, so the documented path is safe; batch atomicity is fixed). Full cross-invocation idempotence is deferred — it needs a stash-id threaded through the assessor contract.

0.2.0 — 2026-07-05 · release-hardening after first live dogfood

Every change below traces to something observed in a real /learn session.

Integrity

• Confidence is never invented. The dialogue grammar and assessor now hard-require: ask in the same breath as the probe, one casual retry, then record null. Calibration counts only numbers the learner actually said. (Found: the tutor had estimated confidences during the first session, silently poisoning calibration.)
• Pending-verification stash (engram.py stash add|list|count|clear): learner productions are persisted to disk the moment they exist. A crashed or compacted session can no longer lose ungraded work; the session-start hook surfaces leftover items. (Found: the tutor was hand-maintaining scratch files.)

New capabilities

• engram.py report — deterministic, self-contained HTML dashboard (per-topic mastery maps with progress bars, retention-by-strength vs. the 85% band, honest calibration, open misconceptions, next-7-days forecast; light+dark, no network, no JS). /coach dashboard now uses it.
• engram.py refit — coarse per-user schedule fit (v1): compares predicted vs. observed recall over ≥50 review receipts and rescales intervals via a clamped multiplier along the FSRS forgetting curve. Guarded and honest about thin data; full FSRS parameter optimization remains future work.
• engram.py doctor — state/environment diagnostics for troubleshooting installs.

Bug fixes

• model --add-interest dropped all but the last value when passed multiple times in one call (argparse append missing). Now keeps every value.
• Streak computation returned 0 when yesterday had activity but today didn't (broken grace-day loop). Rewritten and tested.
• Receipt ids could collide within a fast batch (millisecond timestamps). Now suffixed with a monotonic sequence.

UX

• topic-status renders a progress bar and plain-language legend ("retained / learning / untouched").
• Session ticket and receipt-strip display formats standardized in the dialogue grammar; per-item progress markers in /review ([3/6]).
• Park-and-resume protocol: mid-session subject changes are parked cleanly; re-anchoring is always from disk.
• Pretest capped at 3 probes (a diagnostic, not an exam); unanswered probes stay untouched without nagging.
• Session-start nudge now also surfaces ungraded pending work.

Packaging

• MIT LICENSE (swap if you prefer another).
• ENGRAM_ROOT env var respected as a dev-clone fallback path in all skills.
• Selftest grown from 18 → 33 checks (stash, refit direction+guard+persistence, report self-containment, doctor, streak cases, id uniqueness, interest append, interval multiplier).

0.1.0 — 2026-07-05

Initial build: FSRS-4.5 deterministic core (engram.py, 18-check selftest), three skills (/learn, /review, /coach), three agents (curriculum-architect, assessor, artifact-smith), SessionStart hook, theory docs (foundations, prior art, architecture, roadmap), Explorable Contract.