Feat: introduce gated learning capture and enhance documentation

CHANGELOG.md

@@ -8,6 +8,12 @@ Migration details for `/agent-memory update` live in [`skills/agent-memory/vendo
 
 ## [Unreleased]
 
+### Added
+
+- `/agent-memory learn [>topic] <clue>` — gated capture of one learning/pitfall into `learnings.md` or `learnings-<topic>.md` (confirm; no `--auto`); conflict/dirty guards, slug sanitizing, deterministic target routing, and duplicate-rule skip.
+- Topic-split convention for learnings (`learnings-<topic>.md`) with optional `when editing:` scope hints in `index.md` — normative match contract in `instructions.md` (_Always load_).
+- H2 learning/pitfall entry format (aligned with decisions), legacy one-liner kept valid, duplicate rule across formats, and writing guidance (generalize; prefer correct patterns).
+
 ### Security
 
 - OpenCode plugin: refuse symlink hook scripts, confine resolved paths under `.opencode/hooks`, and validate session/conversation binding IDs before env/stdin.
@@ -16,6 +22,7 @@ Migration details for `/agent-memory update` live in [`skills/agent-memory/vendo
 ### Changed
 
 - `instructions.md` slimmed for always-load: permission boundaries, numbered precedence, task-organized sections, observable turn closure, and formats linked to templates (`TEMPLATE.md`, `log.md`, `decisions.md`) instead of duplicated inventories.
+- Learning/pitfall format and topic-split / scope-hint policy documented in `instructions.md` and `index.md`; `bootstrap` / `sync` / `lint` / `consolidate` aligned.
 - CLI build publishes `bin/cli.js` without minify for supply-chain auditability.
 
 ## [0.1.0] - 2026-07-27

README.md

@@ -26,9 +26,9 @@ Memory lives at `.agents/memory/` and separates **canonical project sources** fr
 | `decisions.md`            | Decision **pointers** (or local fallback when no ADR system).      |
 | `log.md`                  | Recent **semantic** session deltas (append at the bottom).         |
 
-Optional on demand: `learnings.md` — evidenced learnings/pitfalls with no better source. Do **not** create parallel vision/architecture/patterns/domains copies; link the project's own docs instead.
+Optional on demand: `learnings.md` or `learnings-<topic>.md` — evidenced learnings/pitfalls with no better source; optional `when editing:` hints in `index.md`. Capture explicitly with `/agent-memory learn`. Do **not** create parallel vision/architecture/patterns/domains copies; link the project's own docs instead.
 
-**Workflow:** before a task, agents read `index.md`, `current.md`, and their branch's `active-work` file when it exists; **primary write** is in-turn (resume fields + semantic `log.md` outcomes); **catch-up** at checkpoints via `/agent-memory sync` (or follow the skill's `references/sync.md` without invoking the skill); periodically `/agent-memory consolidate` to promote useful facts and prune closed-session noise. Hooks store ephemeral path/session evidence in `.hook-sync-state` only — never Markdown.
+**Workflow:** before a task, agents read `index.md`, `current.md`, and their branch's `active-work` file when it exists (plus any recall file whose `when editing:` hint matches task paths — contract in `instructions.md`); **primary write** is in-turn (resume fields + semantic `log.md` outcomes); **catch-up** at checkpoints via `/agent-memory sync` (or follow the skill's `references/sync.md` without invoking the skill); `/agent-memory learn` to capture a gated learning now; periodically `/agent-memory consolidate` to promote useful facts and prune closed-session noise. Hooks store ephemeral path/session evidence in `.hook-sync-state` only — never Markdown.
 
 Full method: [`skills/agent-memory/vendor/README.md`](./skills/agent-memory/vendor/README.md) and [`instructions.md`](./skills/agent-memory/vendor/memory/instructions.md).
 
@@ -81,6 +81,7 @@ Use `init <harness>` when you already know the agent.
 | `/agent-memory bootstrap`     | Inventory canonical sources and gaps; populate pointers.         |
 | `/agent-memory sync`          | Refresh `current.md` / active-work / `log.md` / `index.md`.      |
 | `/agent-memory lint`          | Broken links, orphans, duplication, stale branches, consistency. |
+| `/agent-memory learn`         | Capture one gated learning/pitfall (`learn [>topic] <clue>`).    |
 | `/agent-memory consolidate`   | Promote useful facts; prune closed-session noise (guided).       |
 
 ## Hooks

skills/README.md

@@ -6,6 +6,6 @@ Skills that operate the [Agent Memory](./agent-memory/vendor/README.md) method.
 
 Manual-only skill that orchestrates the local recall layer. See [`agent-memory/SKILL.md`](./agent-memory/SKILL.md) for routing and [`agent-memory/vendor/memory/instructions.md`](./agent-memory/vendor/memory/instructions.md) for the method.
 
-Commands: `init`, `install hooks`, `update`, `bootstrap`, `sync`, `lint`, `consolidate`, `help`.
+Commands: `init`, `install hooks`, `update`, `bootstrap`, `sync`, `lint`, `consolidate`, `learn`, `help`.
 
 `init` wires harness-native instruction files (`.cursor/rules/*.mdc`, `.github/instructions/*.instructions.md`, or `AGENTS.md` / `CLAUDE.md` / `GEMINI.md`). Hooks are user-installed separately.

skills/agent-memory/SKILL.md

@@ -19,8 +19,10 @@ description: >-
   (check the memory for broken links, orphans, duplication, and consistency;
   accepts `--fix` to also delete stale per-branch `active-work` files),
   `consolidate` (guided promotion/pruning of closed-session noise — no `--auto`),
-  or `help` (list the commands and how to use them). Never trigger automatically;
-  this skill must be invoked on demand only.
+  `learn` (capture one gated learning/pitfall into `learnings.md` or
+  `learnings-<topic>.md` — no `--auto`), or `help` (list the commands and how
+  to use them). Never trigger automatically; this skill must be invoked on
+  demand only.
 metadata:
   invocation: manual
   version: "0.1.0"
@@ -87,6 +89,7 @@ Read the subcommand from the invocation, load **only** the matching reference, a
 | `sync`          | Refresh `current.md` / active-work / `log.md` / `index.md` from repo state.                      | `references/sync.md`          |
 | `lint`          | Check the memory for structural and consistency problems.                                        | `references/lint.md`          |
 | `consolidate`   | Guided promotion/pruning of closed-session noise (confirm each diff; no `--auto`).               | `references/consolidate.md`   |
+| `learn`         | Capture one gated learning/pitfall into `learnings.md` or a topic split (confirm; no `--auto`).  | `references/learn.md`         |
 | `help`          | List the commands and how to use them.                                                           | _Help_ section below          |
 
 If no subcommand is given, or it is not one of those above, run `help` (below) and stop. Do not guess the user's intent.
@@ -107,21 +110,23 @@ For `/agent-memory help` (and for any empty or unknown invocation), output the f
 
 | Command                       | Does                                                                                                                                                              |
 | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/agent-memory help`          | Show this guide.                                                                                                                                                  |
 | `/agent-memory init`          | Create `.agents/memory/`; auto-detect harnesses and write the native instruction file (`.mdc`, `.instructions.md`, or agent `*.md`), or `init <harness>` for one. |
 | `/agent-memory install hooks` | Print how to install or refresh hooks for one harness — `cursor`, `claude`, `codex`, `opencode`, `copilot`, `gemini` (memory must exist).                         |
 | `/agent-memory bootstrap`     | Inventory canonical sources and gaps (up to 3 subagents); populate pointers — not doc copies.                                                                     |
 | `/agent-memory update`        | Migrate memory; refresh agent-memory block in harness instruction files; instruct hook refresh.                                                                   |
 | `/agent-memory sync`          | Refresh `current.md` / active-work / `log.md` / `index.md` from repo state. `--auto` applies all diffs without per-file prompts.                                  |
 | `/agent-memory lint`          | Check for broken links, orphans, duplication, stale branches, and consistency. `--fix` also deletes stale per-branch `active-work` files.                         |
 | `/agent-memory consolidate`   | Promote useful facts and prune closed-session noise (guided; confirm each diff; no `--auto`).                                                                     |
-| `/agent-memory help`          | Show this guide.                                                                                                                                                  |
+| `/agent-memory learn`         | Capture one gated learning/pitfall (`learn [>topic] <clue>`). Confirm before write; no `--auto`.                                                                  |
 
 **Getting started**
 
 - New project? Run `init` (or `init <harness>` — e.g. `init cursor` if you use Cursor and already have a `.cursor/` directory), then optionally `bootstrap` to index sources (not copy docs). Install hooks with the printed `npx` or shell command.
 - Memory exists but hooks missing or stale? Run `install hooks <harness>` for instructions, or re-run the installer from the release tag.
 - Keeping the memory current? Write resume fields + semantic `log.md` in the turn (primary); run `sync` at checkpoints for catch-up (or follow `references/sync.md` without invoking the skill). Use `sync --auto` for low-friction routine flushes.
 - Pruning noise? Run `consolidate` periodically (guided; never automatic).
+- Capture a lesson now? Run `learn [>topic] <clue>` (retention gate; confirm).
 - Already set up? Use `lint` to check health (`lint --fix` also removes stale per-branch files), `update` to upgrade memory scaffolding, then refresh hooks with the user-run installer if needed.
 
 Method & conventions: `.agents/memory/instructions.md`
@@ -130,7 +135,7 @@ Method & conventions: `.agents/memory/instructions.md`
 
 ## Shared rules (apply to every command)
 
-- **Never modify project memory content** — `current.md`, `active-work/*`, `decisions.md`, `log.md`, `learnings.md`, legacy `domains/*` / `features/*`, and other user-authored recall — unless a command explicitly says so, and only after the user confirms. Never edit project docs/ADRs outside `.agents/memory/`.
+- **Never modify project memory content** — `current.md`, `active-work/*`, `decisions.md`, `log.md`, `learnings.md`, `learnings-*.md`, legacy `domains/*` / `features/*`, and other user-authored recall — unless a command explicitly says so, and only after the user confirms. **Exception:** primary write in-turn and `bootstrap` follow `instructions.md` directly (gated learnings/decisions are written when discovered, without this skill's per-entry confirmation); per-diff confirmation applies to `/agent-memory learn`, `consolidate`, and `lint --fix` edits. Never edit project docs/ADRs outside `.agents/memory/`.
 - Run memory/orchestration steps inside the user's current agent. **Do not download, clone, or execute hook installers** — only print instructions for the user to run.
 - If the host ignores `allowed-tools` granularity: still **never** run `git clone`, `git fetch`, `git pull`, or any network fetch for this skill.
 - All paths are relative to the target project root unless stated otherwise (vendor paths are relative to this skill directory).

skills/agent-memory/references/bootstrap.md

@@ -15,22 +15,22 @@ Analyze the project and populate the memory as a **source inventory + gaps** —
 
 4. **Synthesize and write (inventory-first, skip empties).** Wait for all three, then fill memory **without copying docs**:
 
-   | Source       | Writes to                                                   |
-   | ------------ | ----------------------------------------------------------- |
-   | A (sources)  | `index.md` → _Canonical project sources_ (few entry points) |
-   | A (ADRs)     | `decisions.md` — optional single pointer to ADR index/dir   |
-   |              | when a decision system exists and is useful for continuity  |
-   | B + C (gaps) | `learnings.md` — **only** stable, evidenced, undocumented   |
-   |              | facts that pass the gate in `instructions.md`               |
-   | synthesis    | `log.md` — one bootstrap session entry                      |
+   | Source       | Writes to                                                     |
+   | ------------ | ------------------------------------------------------------- |
+   | A (sources)  | `index.md` → _Canonical project sources_ (few entry points)   |
+   | A (ADRs)     | `decisions.md` — optional single pointer to ADR index/dir     |
+   |              | when a decision system exists and is useful for continuity    |
+   | B + C (gaps) | `learnings.md` (or a clear `learnings-<topic>.md`) — **only** |
+   |              | stable, evidenced, undocumented facts that pass the gate      |
+   | synthesis    | `log.md` — one bootstrap session entry                        |
 
    Rules:
    - Do **not** create `vision.md`, `architecture.md`, `patterns.md`, `mistakes.md`, `known-issues.md`, `domains/*`, or `features/*`.
    - Do **not** invent product vision/scope. If purpose/scope is undocumented, report the gap — do not write a vision file.
    - Leave `current.md` with empty placeholders if there is no active work — do not invent milestones, Done lists, or roadmaps.
    - Leave `active-work/` with only its `TEMPLATE.md`.
    - Do **not** invent decisions — only point at an existing ADR index/dir when helpful, or leave `decisions.md` empty.
-   - Create `learnings.md` only when at least one fact passes the gate (reusable, undocumented, non-obvious, evidenced, no secrets). Use `[learning]` or `[pitfall]` tags per `instructions.md`. Mark facts that should become official docs with `pending-doc`. Link `learnings.md` from `index.md` when created.
+   - Create `learnings.md` (or a topic split) only when at least one fact passes the gate (reusable, undocumented, non-obvious, evidenced, no secrets). Use the H2 learning/pitfall format in `instructions.md`. Mark facts that should become official docs with `pending-doc`. Link every new learnings file from `index.md` (optional `when editing:` when paths are clear). Prefer one `learnings.md` on first bootstrap unless a single theme dominates.
    - Append to `log.md` using the per-session format in `instructions.md`, e.g. `## [YYYY-MM-DD] [docs] bootstrap source inventory` with bullets listing sources indexed / learnings created / gaps reported.
    - Keep every `index.md` source line to: link + what it owns + when to read.
 

skills/agent-memory/references/consolidate.md

@@ -37,22 +37,25 @@ Guided, conservative promotion and pruning of memory. Turns closed-session noise
 4. **Classify each candidate.** Propose one action per item:
    - **Reference** — replace body with a pointer to a canonical source; update `index.md` if needed.
    - **Decision** — add/replace pointer in `decisions.md` (or local fallback if no ADR system); mark superseded entries instead of deleting them.
-   - **Learning / pitfall** — promote to `learnings.md` with evidence + use trigger (+ `invalidate when` when useful).
+   - **Learning / pitfall** — promote to `learnings.md` or an existing `learnings-<topic>.md` using the H2 format in `instructions.md` (evidence + use when + verified + invalidate when). Prefer an existing topic split when the theme matches; otherwise `learnings.md`. Apply the duplicate rule from `instructions.md` — skip when the insight already exists in the target file (H2 or legacy one-liner).
+   - **Split** — when `learnings.md` is large or thematically clustered, propose moving entries into `learnings-<topic>.md` and updating `index.md` (optional `when editing:` hints). Convert moved entries to the H2 form as part of the move (do not move raw one-liners unless the user declines conversion). Confirm; never auto-split.
+   - **Merge** — when a topic split is tiny or redundant with another, propose merging back into `learnings.md` or a sibling split; same H2 conversion and duplicate rule (confirm).
    - **Current** — keep in `current.md` / active-work because still active.
    - **Discard** — remove because transient, reconstructible from Git, or duplicated (including legacy path bullets and empty headings).
    - **Defer** — preserve when unsure or waiting on external doc promotion (`pending-doc`).
 
 5. **Show the classification plan** to the user (table or grouped list). Do not write yet.
 
 6. **Apply in safe order** — confirm each diff (approve / skip / abort):
-   1. Additions/promotions first: `decisions.md`, `learnings.md`, `current.md` (shared blockers only if still active), `index.md`.
-   2. Only after a promotion is **approved**, propose removing its origin from `log.md` or a legacy file body. If promotion is declined, **keep** the origin.
+   1. Additions/promotions first: `decisions.md`, `learnings.md` / `learnings-*.md`, `current.md` (shared blockers only if still active), `index.md` (including new/updated learnings links and `when editing:` hints).
+   2. Only after a promotion is **approved**, propose removing its origin from `log.md` or a legacy file body. If promotion is declined, **keep** the origin. Apply approved split/merge moves only after the destination write is confirmed.
    3. Propose removal of legacy path-only bullets, empty closed-session headings, and legacy _Touched files_ sections (Git available; evidence reconstructible).
    4. Propose deleting stale `active-work/<branch>.md` one-by-one, or with an explicit "delete all stale" approval. Never delete `TEMPLATE.md`.
    5. For legacy mirrors: prefer converting to pointers / learnings over delete; deleting a legacy file is sensitive and must be confirmed.
 
 7. **Report.** Summarize separately:
    - **promoted** — decision or learning/pitfall bodies added;
+   - **split / merged** — learnings moved between `learnings.md` and topic splits;
    - **referenced** — pointers to canonical sources (no body copy);
    - **superseded** — prior decisions marked with `Superseded by:`;
    - **discarded** — transient / reconstructible / duplicated removed;