self-learn
A git-backed lesson ledger that decides its own queue. Lessons are captured
as one-record-per-file markdown under the ledger home (~/.self-learn, its
own git repo, independent of any code repo — doc 13) in skills/<name>/,
projects/<slug>/, and user/ buckets. The steward decides the
pending queue every night and the overseer examines its work every
week; both route lessons into canon — a skill's SKILL.md managed section,
CLAUDE.md, a references file, a deterministic guard hook, or a new skill —
and skills and hooks are written and activated without asking anyone. A
person steps in only by their own choice: /self-learn:review, the web
UI, or a veto. The few things that really need the user (a login, sudo,
spending money, a change to their system outside self-learn, writing into
another repo's git history, a conflict between two things they said,
self-learn broken past its own repair) wait in the inbox the tray icon
opens. Every change is still one attributed git commit (By: steward,
overseer, agent or human). Full architecture: docs/specs/self-learn/
(01–04, 13).
When to capture
When the user corrects wrong behavior, states a standing preference, or
names a gotcha that will recur — durable lessons only, never one-off
task instructions — compose and capture with self-learn teach; report the
id in one line only if the user is mid-conversation about it. Capture is
silent: no offer before, no echo of the wording, no confirmation round
after (the user, 2026-10-31: "capturing a lesson should happen quietly in
the background"). Several serious corrections in one session each get
their own capture. The capture lands in pending/; the steward decides its
placement the same night, and the user can see and overturn every decision
in the inbox. A --statement that teach records from your shell is stored
recorded_by: agent; the words stay the user's through the transcript line
it cites.
The steward and the overseer
Pending lessons are decided without a person in the loop. The steward
runs once a night, after the mine: it reads each candidate's brief and
decides it — a hook route and an always-loaded line included, both are its
own to decide — and parks only what it is genuinely unsure of, or what
would spread badly before the next examination, for the overseer,
which runs weekly, decides parked items in the user's stead,
re-examines a sample of the week's steward decisions, and writes a
short report. Neither ever treats its own reading of the user as something
the user said: a system-formed reading is marked provisional until a
presentation shows it to them, and silence is never read as agreement.
/self-learn:review and the web UI stay open to anyone who wants to step
in; the queue is the steward's either way.
When the user objects to a skill
Self-learn writes, renames and retires the skills it owns without asking;
never present one to the user or ask about one. When the user says, unasked,
that a skill's name is wrong or that it should go, do it: self-learn skill veto <name> [--rename-to <new>] bans the name for ever (the skill under it
is renamed by the next overseer run, or at once with --rename-to);
self-learn skill rename <old> <new> renames; self-learn skill retire <name> retires, or, while lessons still route into it, records a request
the next overseer run carries out. From your shell each runs under the
user's standing grant with --note "<why>" and is recorded By: agent.
Project notices at session start
In a session inside a project a live notice names, the SessionStart hook
prints one header — "self-learn notices for this project — yours to carry
out in this session (no sudo needed)" — and then each notice. A notice is
this session's agent's work, never a step for the user: carry it out (for
example, commit the file self-learn changed with the command the notice
gives), then run self-learn notice done <id>. Do not relay a notice to the
user as something waiting on them.
CLI surface
From an agent's shell every ledger-writing verb needs --note "<why>"
(recorded By: agent); route|reroute|replace|revise|reconsider also need
--by analyst|human|agent. Record your own act as agent, never as the
user's: --by agent, case record --actor agent, case observe --by agent, statement add --recorded-by agent (an agent's shell may not pass
human; the user's words stay theirs through the transcript ref).
| Verb |
Semantics (one line) |
status / list |
Pending overview / queued records; --json; list --include-deferred |
teach |
Capture ONE lesson into pending/ (scan-then-write). Scope: --skill <name> | --project | --user; type: --type behavior --trigger … --instruction … or --type knowledge --fact …; --context … (either type) is the background, written as ## Context and never loaded; --route [--dest …] resolves immediately. Capture-time grounding (optional, 11 §3): --verified [--verified-how …], --incident-cost …, --generality environment-specific|general-practice|uncertain, --env COMP=VER (repeatable) |
route <id> [--dest …] |
Compile the record into its destination (proposal or override), commit + push. Known-partial coverage: --follow-up <action> [--unblocks-on <gate>] [--follow-up-note …] rides the routing block |
followup done <id> [--note …] |
Clear a routed record's open follow-up into a dated follow_up_done block |
grant add --statement <stmt-…> [--note …] / grant list / grant revoke <grant-…> |
The user's standing grant, recorded from a statement they typed. While one is in force, an agent's shell runs person-only commands (host add|remove|rebind|set-mode, a tier-C config set|unset, skill write|rename|retire|veto) with --note "<why>", recorded By: agent and Grant: <stmt>; without it they refuse |
telemetry note <kind> [--reason …] |
Spool one telemetry event. Cache-only — no repo write, no commit. Since silent capture (2026-10-31) no surface logs offers with it |
telemetry flush |
Spool → tracked telemetry/ files in the ledger home (scan-at-flush; the flush commits them — every producer commits its own writes, H-5). Teach/import/resolution verbs flush automatically |
report [--json] |
Facts layer v1: lifecycle counts, open follow-ups, deferred aging, offer ledger (silent capture since 2026-10-31; the earlier capture rate is labeled a ceiling) |
reject <id> / defer <id> [--until D] / retire <id> --covered-by <surface> |
Resolve without routing: rejected / hidden until date (default +30 d) / woven into already-loaded canon, the surface named (graduate was removed on 2026-10-24) |
supersede <old> <new> |
Mark a lesson corrected by a newer one (metadata + recompile) |
route <survivor> --collapse <cluster-id> |
Collapse a worker-proposed duplicate cluster in ONE commit: evidence merged, sightings summed, losers superseded by the survivor |
confirm-recurrence <id> --event <nonce> [--tolerate --note …] |
A routed rule was sighted failing again: append the dated recurrence (facts copied from the telemetry event). Tolerate = the rule stays, with the why |
dismiss-suspect <id> --event <nonce> --why <reason> [--note …] |
A recurrence suspect was a matcher false-positive, not a real recurrence: append the dismissal (facts copied from the telemetry event, which is preserved untouched) |
confirm-held <id> |
A routed rule was seen working: stamp last_confirmed (the staleness metric is age-since-confirmation) |
link contradicts <id> <target> |
First-class contradiction edge to a record id or canon anchor |
hook activate <id> / hook deactivate <id> |
Place a routed hook's symlink, register it in ~/.claude/settings.json and verify it — all three steps, always / take it out again. From an agent's shell, with --note |
batch <sheet> |
Apply a decision sheet in one locked run — the review skill's one apply path; never hand-write a sequence of verb calls |
steward run [--dry-run] |
The steward's nightly run, by hand; --dry-run writes only its cache stage |
overseer open / overseer respond … / overseer run [--dry-run] |
The overseer's latest report and questions / record a reply / its weekly run, by hand |
attention [--json] / attention packet <item> --json |
The inbox in a terminal: what needs the user, and what was decided for them / one item's full context |
skill list / skill write|rename|retire|veto … |
The skills self-learn owns, and their state / change one (person-only; an agent under the grant with --note) |
premises check |
Run every premise probe now, read-only |
doctor invocation / doctor settings |
Read-only health views |
recompile / reconcile |
Re-derive every compiled target from the ledger / inspect or clear a transaction intent (--clear-intent <id> after inspecting) |
case … / statement add|list / user-model … |
The decision-case store, the user-statement store and the model of the user (02 §3a) |
host add|remove|rebind|set-mode / config get|set|unset |
Registered projects / settings (tier-C writes are person-only; an agent under the grant with --note) |
worker kick / worker run [--coalesce] |
Background pre-analysis: teach/import kick a coalescing window (flock + pidfile; no scheduler); the run writes proposals via a write-restricted claude -p (no Bash/Edit), validates + stamps them and logs a proposals event. It sends no popup |
mine run [--trigger …] [--since YYYY-MM-DD] |
Transcript miner (doc 12): read unread session transcripts one session per model call → land source: session candidates in pending (use-scaled cap, secret-scanned, origin-deduped; NEVER routes). The host process's nightly mine job (self-learn serve), the >24 h verb watchdog and a manual force all call this |
mine status [--json] |
The run journal: last run, staleness, and per-candidate outcomes (landed / folded / recurrence / dropped-and-why) |
status --fast |
Pending-only full record parse for the SessionStart hook (<500 ms): home and lock state, STOPPED intents, unreadable records, and project_notices when the working directory is inside a project a live notice names |
notice list [--all] [--json] | notice done <id> |
Project notices (S-106): one line about one project, shown at session start only in sessions inside it. It ends when done, or when its condition clears (a tracked file self-learn left changed is committed); a notice with a condition has no age limit, one without ends after 14 days. Cache only, never the ledger |
push |
Retry unpushed resolution commits (rebase-retry, never auto-resolve) |
sentinel hold|heartbeat|release |
Pause the repo's autosync during review batches (2 h mtime TTL) |
import --backlog <skill> | --memory DIR |
One-shot ETL: GOTCHAS journal / auto-memory topic files → pending records (idempotent, origin-deduped) (DIR or $SELF_LEARN_MEMORY_DIR; no default) |
prune-memory [--dry-run] DIR |
S-13 sweep: delete memory files whose records reached a terminal status (DIR or $SELF_LEARN_MEMORY_DIR; no default) |
proposal validate <id> |
Scan + schema-check + stamp a record's proposal sibling — REQUIRED after any direct edit of a pending record outside CLI verbs |
--selftest |
Loud install checks, thirteen rows, in this order: capture, compiler (dry-run), markers (02 §4), drift (a compiler-owned target hand-edited since its last compile), reach (every reference-routed record is reachable from a loaded surface), hooks (script intact/executable/byte-matched, incomplete supersession, dangling settings.json registrations), surface, hosts, owned_skills, sentinel, invocation, premises, steward-queue |
All record-body writes pass the secret scan: default refuse (span +
rule printed), --redact opt-in on capture surfaces, no bypass flag.
Skills agents can put under upkeep
When the user maintains a skill and it would benefit from self-learn's upkeep,
run self-learn skill register <name-or-path> --note "why". Any agent may register,
withdraw with skill unregister <name> --note "why", or file a request; no standing
grant is needed for those verbs. skill list shows registrations.
Registration permits prose, description and reference-file rewrites while preserving
user intent and voice; it never permits renaming or retiring the user's skill.
Installer-managed, upstream-tracked and foreign-repository skills are refused, with
the signal named. Loose user skills are backed up and adopted into the git skills root.
Ask the next overseer run for work:
self-learn skill request build --name <name> --lessons <id1>,<id2> --note "why"
self-learn skill request change <owned-or-registered-skill> --note "what and why"
self-learn skill request withdraw <id> --note "why no longer needed"
Each request gets a report answer: built, changed or declined with a reason. Failed
writes, drafts and missing or malformed answers remain open without blocking other work.
Notes are secret-scanned; refusal messages name the rule, never the match. See skill upkeep for
refusal signals, adoption and edit protection.
Slash commands
/self-learn:teach — extraction UX: compose trigger/instruction/evidence
from the live session, then call the CLI. Silent: it captures and asks
nothing.
/self-learn:review — an optional triage batch: the steward decides the
queue nightly anyway. The review agent decides what it can itself and
puts a record to the person only for a needs-you reason. Routing
doctrine: references/routing-doctrine.md.
/self-learn:overseer — open the overseer's latest report and its
questions, and record the user's replies. A stead ask carries the
default it already applied and waits on nobody; a needs you; meanwhile
ask waits for the user, and one with a plan is decided only by choosing
one of its options (an inbox click, or self-learn attention answer). Never a review session: nothing here approves a lesson.
The inbox (self-learn-ui-open --page /inbox, or self-learn attention
in a terminal) shows the same items with everything needed to decide them.
The web UI — the inbox and a review venue
The localhost web app (self-learn-ui-open) holds the inbox the tray
icon opens: each item that needs the user, or that was decided for them,
on one page with its question, the evidence, the recommendation, one-click
answers, a reply box and a read-only agent to ask about it. Pending lessons
can also be reviewed and routed there: keyboard-driven, one decision fully
explained per screen, with an agent pane ("iterate") for talking through a
lesson before routing it. Same CLI verbs underneath — a different venue,
not a second system. Install/launch/keymap/env vars are documented in the
product README's "G-3 surface" section; design is
docs/specs/self-learn/09-surface-spec.md + 10-surface-build-plan.md.
Environment & exit codes
SELF_LEARN_HOME — the ledger home (default ~/.self-learn).
SELF_LEARN_CLAUDE_DIR — where hook selfchecks read settings.json /
hooks/ (default ~/.claude; tests redirect it).
<home>/config.yaml — operator policy, COMMITTED in the ledger repo
(S-10 amendment 2026-07-16): one_motion_route: {hook: true, new-skill: true} enables teach --route --dest hook --hook-input <yaml> / --dest new-skill:<name>. Default (no file) = refuse and
keep the queued flow; parsing is fail-closed (only the YAML
boolean true enables). Enabled hook routes still validate, scan,
and replay the compile input pre-commit and PRINT the applied script;
the guard acts once self-learn hook activate <id> has placed,
registered and verified it (an agent runs it, with --note).
- Analyst (bare-terminal
teach --route): SELF_LEARN_ANALYST_MODEL
(default claude-sonnet-5), SELF_LEARN_ANALYST_TIMEOUT (default 120 s).
- Exit codes — verbs: 0 ok · 1 refusal (dirty target, scan hit,
replay/freshness abort on a hook route) · 3 push failed (commit
kept — run
self-learn push) · 4 rebase conflict · 64 usage/unknown
id. (All five destinations compile as of M3 — hook needs a validated
hook proposal, new-skill is --dest new-skill:<name>; the old exit-2
"unbuilt destination" is gone.) batch shares this contract plus one
new integer, · 8 batch partial (some sheet items applied, some
refused — the ledger DID change; batch returns 1 only when nothing
landed) — the review skill invokes batch as its one apply path,
never a hand-written sequence of verb calls.
proposal validate: 0 valid+stamped · 1 schema-invalid (file intact) ·
2 scan hit (wins). teach's own usage errors (bad/missing/conflicting
flags, caught before anything is written) are 64 too (A22, fold r1,
2026-09-04 — unified with the verbs' own 64 above; a bad home is
still 5, unchanged). --selftest (tri-state PASS/FAIL/UNMEASURED per
row, plus WARN, thirteen rows): 0 all measured and green · 1 any FAIL
(wins) · 9 no FAIL but at least one row UNMEASURED (a check that could
not measure anything, e.g. a missing prerequisite it cannot itself
supply — never read as a silent PASS).
Install, the S-15 capture line, and troubleshooting live in the plugin
README (plugins/self-learn/README.md).
1---2name: self-learn3description: Capture, triage, and route durable session lessons into canon. Use when the user corrects a mistake Claude made, states a rule or preference that should outlast the current task, names a gotcha that will recur, says "remember this" / "capture this lesson" / "teach", or wants to review, triage, or route pending lessons. Fronts the `self-learn` CLI (git-backed lesson ledger) and the /self-learn:teach and /self-learn:review commands.4metadata:5 source: https://skillmd.com/skills/alexk-notable/self-learn6---78# self-learn910A git-backed lesson ledger that decides its own queue. Lessons are captured11as one-record-per-file markdown under the ledger home (`~/.self-learn`, its12own git repo, independent of any code repo — doc 13) in `skills/<name>/`,13`projects/<slug>/`, and `user/` buckets. The **steward** decides the14pending queue every night and the **overseer** examines its work every15week; both route lessons into canon — a skill's SKILL.md managed section,16CLAUDE.md, a references file, a deterministic guard hook, or a new skill —17and skills and hooks are written and activated without asking anyone. A18person steps in only by their own choice: `/self-learn:review`, the web19UI, or a veto. The few things that really need the user (a login, sudo,20spending money, a change to their system outside self-learn, writing into21another repo's git history, a conflict between two things they said,22self-learn broken past its own repair) wait in the inbox the tray icon23opens. Every change is still one attributed git commit (`By: steward`,24`overseer`, `agent` or `human`). Full architecture: `docs/specs/self-learn/`25(01–04, 13).2627## When to capture2829When the user **corrects wrong behavior, states a standing preference, or30names a gotcha that will recur** — durable lessons only, never one-off31task instructions — compose and capture with `self-learn teach`; report the32id in one line only if the user is mid-conversation about it. Capture is33silent: no offer before, no echo of the wording, no confirmation round34after (the user, 2026-10-31: "capturing a lesson should happen quietly in35the background"). Several serious corrections in one session each get36their own capture. The capture lands in `pending/`; the steward decides its37placement the same night, and the user can see and overturn every decision38in the inbox. A `--statement` that teach records from your shell is stored39`recorded_by: agent`; the words stay the user's through the transcript line40it cites.4142## The steward and the overseer4344Pending lessons are decided without a person in the loop. The **steward**45runs once a night, after the mine: it reads each candidate's brief and46decides it — a hook route and an always-loaded line included, both are its47own to decide — and **parks** only what it is genuinely unsure of, or what48would spread badly before the next examination, for the **overseer**,49which runs weekly, decides parked items in the user's stead,50re-examines a sample of the week's steward decisions, and writes a51short report. Neither ever treats its own reading of the user as something52the user said: a system-formed reading is marked provisional until a53presentation shows it to them, and silence is never read as agreement.54`/self-learn:review` and the web UI stay open to anyone who wants to step55in; the queue is the steward's either way.5657## When the user objects to a skill5859Self-learn writes, renames and retires the skills it owns without asking;60never present one to the user or ask about one. When the user says, unasked,61that a skill's name is wrong or that it should go, do it: `self-learn skill62veto <name> [--rename-to <new>]` bans the name for ever (the skill under it63is renamed by the next overseer run, or at once with `--rename-to`);64`self-learn skill rename <old> <new>` renames; `self-learn skill retire65<name>` retires, or, while lessons still route into it, records a request66the next overseer run carries out. From your shell each runs under the67user's standing grant with `--note "<why>"` and is recorded `By: agent`.6869## Project notices at session start7071In a session inside a project a live notice names, the SessionStart hook72prints one header — "self-learn notices for this project — yours to carry73out in this session (no sudo needed)" — and then each notice. A notice is74this session's agent's work, never a step for the user: carry it out (for75example, commit the file self-learn changed with the command the notice76gives), then run `self-learn notice done <id>`. Do not relay a notice to the77user as something waiting on them.7879## CLI surface8081From an agent's shell every ledger-writing verb needs `--note "<why>"`82(recorded `By: agent`); `route|reroute|replace|revise|reconsider` also need83`--by analyst|human|agent`. Record your own act as `agent`, never as the84user's: `--by agent`, `case record --actor agent`, `case observe --by85agent`, `statement add --recorded-by agent` (an agent's shell may not pass86`human`; the user's words stay theirs through the transcript ref).8788| Verb | Semantics (one line) |89|---|---|90| `status` / `list` | Pending overview / queued records; `--json`; `list --include-deferred` |91| `teach` | Capture ONE lesson into `pending/` (scan-then-write). Scope: `--skill <name>` \| `--project` \| `--user`; type: `--type behavior --trigger … --instruction …` or `--type knowledge --fact …`; `--context …` (either type) is the background, written as `## Context` and never loaded; `--route [--dest …]` resolves immediately. Capture-time grounding (optional, 11 §3): `--verified [--verified-how …]`, `--incident-cost …`, `--generality environment-specific\|general-practice\|uncertain`, `--env COMP=VER` (repeatable) |92| `route <id> [--dest …]` | Compile the record into its destination (proposal or override), commit + push. Known-partial coverage: `--follow-up <action> [--unblocks-on <gate>] [--follow-up-note …]` rides the routing block |93| `followup done <id> [--note …]` | Clear a routed record's open follow-up into a dated `follow_up_done` block |94| `grant add --statement <stmt-…> [--note …]` / `grant list` / `grant revoke <grant-…>` | The user's standing grant, recorded from a statement they typed. While one is in force, an agent's shell runs person-only commands (`host add\|remove\|rebind\|set-mode`, a tier-C `config set\|unset`, `skill write\|rename\|retire\|veto`) with `--note "<why>"`, recorded `By: agent` and `Grant: <stmt>`; without it they refuse |95| `telemetry note <kind> [--reason …]` | Spool one telemetry event. Cache-only — no repo write, no commit. Since silent capture (2026-10-31) no surface logs offers with it |96| `telemetry flush` | Spool → tracked `telemetry/` files in the ledger home (scan-at-flush; the flush commits them — every producer commits its own writes, H-5). Teach/import/resolution verbs flush automatically |97| `report [--json]` | Facts layer v1: lifecycle counts, open follow-ups, deferred aging, offer ledger (silent capture since 2026-10-31; the earlier capture rate is labeled a ceiling) |98| `reject <id>` / `defer <id> [--until D]` / `retire <id> --covered-by <surface>` | Resolve without routing: rejected / hidden until date (default +30 d) / woven into already-loaded canon, the surface named (`graduate` was removed on 2026-10-24) |99| `supersede <old> <new>` | Mark a lesson corrected by a newer one (metadata + recompile) |100| `route <survivor> --collapse <cluster-id>` | Collapse a worker-proposed duplicate cluster in ONE commit: evidence merged, sightings summed, losers superseded by the survivor |101| `confirm-recurrence <id> --event <nonce> [--tolerate --note …]` | A routed rule was sighted failing again: append the dated recurrence (facts copied from the telemetry event). Tolerate = the rule stays, with the why |102| `dismiss-suspect <id> --event <nonce> --why <reason> [--note …]` | A recurrence suspect was a matcher false-positive, not a real recurrence: append the dismissal (facts copied from the telemetry event, which is preserved untouched) |103| `confirm-held <id>` | A routed rule was seen working: stamp `last_confirmed` (the staleness metric is age-since-confirmation) |104| `link contradicts <id> <target>` | First-class contradiction edge to a record id or canon anchor |105| `hook activate <id>` / `hook deactivate <id>` | Place a routed hook's symlink, register it in `~/.claude/settings.json` and verify it — all three steps, always / take it out again. From an agent's shell, with `--note` |106| `batch <sheet>` | Apply a decision sheet in one locked run — the review skill's one apply path; never hand-write a sequence of verb calls |107| `steward run [--dry-run]` | The steward's nightly run, by hand; `--dry-run` writes only its cache stage |108| `overseer open` / `overseer respond …` / `overseer run [--dry-run]` | The overseer's latest report and questions / record a reply / its weekly run, by hand |109| `attention [--json]` / `attention packet <item> --json` | The inbox in a terminal: what needs the user, and what was decided for them / one item's full context |110| `skill list` / `skill write\|rename\|retire\|veto …` | The skills self-learn owns, and their state / change one (person-only; an agent under the grant with `--note`) |111| `premises check` | Run every premise probe now, read-only |112| `doctor invocation` / `doctor settings` | Read-only health views |113| `recompile` / `reconcile` | Re-derive every compiled target from the ledger / inspect or clear a transaction intent (`--clear-intent <id>` after inspecting) |114| `case …` / `statement add\|list` / `user-model …` | The decision-case store, the user-statement store and the model of the user (02 §3a) |115| `host add\|remove\|rebind\|set-mode` / `config get\|set\|unset` | Registered projects / settings (tier-C writes are person-only; an agent under the grant with `--note`) |116| `worker kick` / `worker run [--coalesce]` | Background pre-analysis: teach/import kick a coalescing window (flock + pidfile; no scheduler); the run writes proposals via a write-restricted `claude -p` (no Bash/Edit), validates + stamps them and logs a `proposals` event. It sends no popup |117| `mine run [--trigger …] [--since YYYY-MM-DD]` | Transcript miner (doc 12): read unread session transcripts one session per model call → land `source: session` candidates in pending (use-scaled cap, secret-scanned, origin-deduped; NEVER routes). The host process's nightly mine job (`self-learn serve`), the >24 h verb watchdog and a manual force all call this |118| `mine status [--json]` | The run journal: last run, staleness, and per-candidate outcomes (landed / folded / recurrence / dropped-and-why) |119| `status --fast` | Pending-only full record parse for the SessionStart hook (<500 ms): home and lock state, STOPPED intents, unreadable records, and `project_notices` when the working directory is inside a project a live notice names |120| `notice list [--all] [--json]` \| `notice done <id>` | Project notices (S-106): one line about one project, shown at session start only in sessions inside it. It ends when done, or when its condition clears (a tracked file self-learn left changed is committed); a notice with a condition has no age limit, one without ends after 14 days. Cache only, never the ledger |121| `push` | Retry unpushed resolution commits (rebase-retry, never auto-resolve) |122| `sentinel hold\|heartbeat\|release` | Pause the repo's autosync during review batches (2 h mtime TTL) |123| `import --backlog <skill>` \| `--memory DIR` | One-shot ETL: GOTCHAS journal / auto-memory topic files → pending records (idempotent, origin-deduped) (DIR or `$SELF_LEARN_MEMORY_DIR`; no default) |124| `prune-memory [--dry-run] DIR` | S-13 sweep: delete memory files whose records reached a terminal status (DIR or `$SELF_LEARN_MEMORY_DIR`; no default) |125| `proposal validate <id>` | Scan + schema-check + stamp a record's proposal sibling — REQUIRED after any direct edit of a pending record outside CLI verbs |126| `--selftest` | Loud install checks, **thirteen rows, in this order**: `capture`, `compiler` (dry-run), `markers` (02 §4), `drift` (a compiler-owned target hand-edited since its last compile), `reach` (every `reference`-routed record is reachable from a loaded surface), `hooks` (script intact/executable/byte-matched, incomplete supersession, dangling settings.json registrations), `surface`, `hosts`, `owned_skills`, `sentinel`, `invocation`, `premises`, `steward-queue` |127128All record-body writes pass the secret scan: default **refuse** (span +129rule printed), `--redact` opt-in on capture surfaces, no bypass flag.130131## Skills agents can put under upkeep132133When the user maintains a skill and it would benefit from self-learn's upkeep,134run `self-learn skill register <name-or-path> --note "why"`. Any agent may register,135withdraw with `skill unregister <name> --note "why"`, or file a request; no standing136grant is needed for those verbs. `skill list` shows registrations.137138Registration permits prose, description and reference-file rewrites while preserving139user intent and voice; it never permits renaming or retiring the user's skill.140Installer-managed, upstream-tracked and foreign-repository skills are refused, with141the signal named. Loose user skills are backed up and adopted into the git skills root.142143Ask the next overseer run for work:144- `self-learn skill request build --name <name> --lessons <id1>,<id2> --note "why"`145- `self-learn skill request change <owned-or-registered-skill> --note "what and why"`146- `self-learn skill request withdraw <id> --note "why no longer needed"`147148Each request gets a report answer: built, changed or declined with a reason. Failed149writes, drafts and missing or malformed answers remain open without blocking other work.150Notes are secret-scanned; refusal messages name the rule, never the match. See [skill upkeep](references/skill-upkeep.md) for151refusal signals, adoption and edit protection.152153## Slash commands154155- `/self-learn:teach` — extraction UX: compose trigger/instruction/evidence156 from the live session, then call the CLI. Silent: it captures and asks157 nothing.158- `/self-learn:review` — an optional triage batch: the steward decides the159 queue nightly anyway. The review agent decides what it can itself and160 puts a record to the person only for a needs-you reason. Routing161 doctrine: `references/routing-doctrine.md`.162- `/self-learn:overseer` — open the overseer's latest report and its163 questions, and record the user's replies. A stead ask carries the164 default it already applied and waits on nobody; a `needs you; meanwhile`165 ask waits for the user, and one with a plan is decided only by choosing166 one of its options (an inbox click, or `self-learn attention answer`). Never a review session: nothing here approves a lesson.167 The inbox (`self-learn-ui-open --page /inbox`, or `self-learn attention`168 in a terminal) shows the same items with everything needed to decide them.169170## The web UI — the inbox and a review venue171172The localhost web app (`self-learn-ui-open`) holds the **inbox** the tray173icon opens: each item that needs the user, or that was decided for them,174on one page with its question, the evidence, the recommendation, one-click175answers, a reply box and a read-only agent to ask about it. Pending lessons176can also be reviewed and routed there: keyboard-driven, one decision fully177explained per screen, with an agent pane ("iterate") for talking through a178lesson before routing it. Same CLI verbs underneath — a different venue,179not a second system. Install/launch/keymap/env vars are documented in the180product README's "G-3 surface" section; design is181`docs/specs/self-learn/09-surface-spec.md` + `10-surface-build-plan.md`.182183## Environment & exit codes184185- `SELF_LEARN_HOME` — the ledger home (default `~/.self-learn`).186- `SELF_LEARN_CLAUDE_DIR` — where hook selfchecks read `settings.json` /187 `hooks/` (default `~/.claude`; tests redirect it).188- `<home>/config.yaml` — operator policy, COMMITTED in the ledger repo189 (S-10 amendment 2026-07-16): `one_motion_route: {hook: true,190 new-skill: true}` enables `teach --route --dest hook --hook-input191 <yaml>` / `--dest new-skill:<name>`. Default (no file) = refuse and192 keep the queued flow; parsing is fail-closed (only the YAML193 boolean `true` enables). Enabled hook routes still validate, scan,194 and replay the compile input pre-commit and PRINT the applied script;195 the guard acts once `self-learn hook activate <id>` has placed,196 registered and verified it (an agent runs it, with `--note`).197- Analyst (bare-terminal `teach --route`): `SELF_LEARN_ANALYST_MODEL`198 (default `claude-sonnet-5`), `SELF_LEARN_ANALYST_TIMEOUT` (default 120 s).199- Exit codes — verbs: 0 ok · 1 refusal (dirty target, scan hit,200 replay/freshness abort on a hook route) · 3 push failed (commit201 kept — run `self-learn push`) · 4 rebase conflict · 64 usage/unknown202 id. (All five destinations compile as of M3 — hook needs a validated203 hook proposal, new-skill is `--dest new-skill:<name>`; the old exit-2204 "unbuilt destination" is gone.) `batch` shares this contract plus one205 new integer, · 8 batch partial (some sheet items applied, some206 refused — the ledger DID change; `batch` returns 1 only when nothing207 landed) — the review skill invokes `batch` as its one apply path,208 never a hand-written sequence of verb calls.209 `proposal validate`: **0 valid+stamped · 1 schema-invalid (file intact) ·210 2 scan hit (wins)**. `teach`'s own usage errors (bad/missing/conflicting211 flags, caught before anything is written) are **64** too (A22, fold r1,212 2026-09-04 — unified with the verbs' own 64 above; a bad *home* is213 still 5, unchanged). `--selftest` (tri-state PASS/FAIL/UNMEASURED per214 row, plus WARN, thirteen rows): 0 all measured and green · 1 any FAIL215 (wins) · 9 no FAIL but at least one row UNMEASURED (a check that could216 not measure anything, e.g. a missing prerequisite it cannot itself217 supply — never read as a silent PASS).218219Install, the S-15 capture line, and troubleshooting live in the plugin220README (`plugins/self-learn/README.md`).