docs: memory capture rule after the noise gate

This commit is contained in:
bchanot committed 2026-11-04 13:05:04 +01:00
1 parent 2674bbd997
commit 6fb16a3636
5 files changed
+14 -9

No files matched your search

+1 -1
View File
@@ -114,7 +114,7 @@ Shared rules for every phase:
- Measured recall (5 real FR prompts, 22 relevant entries): BM25 full text 9/22, haiku rerank of lexical top-30 14/22 (~8.5k chars). Error 4-gram match on real errors: BLK-030/031/034 exact, no false positive; 5 of 7 real errors of 2026-10-23 had NO entry: capture is the weak link.
- **4b capture (mod).** Failure ledger: tool results with isError, deny or non-zero exit carrying a distinctive error line → normalized + verbatim + command, REDACTED at capture (rtk-rewrite redaction + gitleaks patterns), bounded ring per session in `$.store` (4 MiB cap), matched against the registry error index; unmatched = new failure modes. Milestones: feat/fix commit, `gitflow finish`, a suite red then green. `memory_pending` tool returns unmatched failures + milestones; /capitalize, /close and every CAPITALIZE step call it first; one context note at the next prompt after a milestone, never per turn, never at Stop. "Proactive capitalization" paragraph KEPT. Writing always = model draft + user approval + lib/memory.sh.
- Built 2026-11-04 on feature/memory-capture (f1d4f9d..HEAD): mod `mods/memory`, kit 100+ cases, consumers wired, noise measured (NOISE.md); merge pending (gates, review, user go)
- **4c read side — next.** Two channels only: intent recall at `prompt.submit` for classifier labels design/analysis or the first coding prompt after idle (BM25 top-30 over title + lesson + body → haiku keeps ≤3, bounded 3 s, fail open) and tool-error 4-gram match (PostToolUse; a classic hook is acceptable if the mod ledger is not needed). Session digest (open BLK via the status parser, actionable TODO, last journal line) in `hooks/session-start.sh` on `source: startup|compact|clear` (native matchers; the mod's `session.compact` only skips); a SubagentStart twin if sub-agents need it. Injection = ID + title + lesson line; superseded never injected; budget ~1.5k chars per turn; once per context. Deferred: Read path triggers, Bash command triggers, "critical → deny once", Tier 1, cross-repo scope=global index, `memory_search` tool.
- **4c read side (next).** Two channels only: intent recall at `prompt.submit` for classifier labels design/analysis or the first coding prompt after idle (BM25 top-30 over title + lesson + body → haiku keeps ≤3, bounded 3 s, fail open) and tool-error 4-gram match (PostToolUse; a classic hook is acceptable if the mod ledger is not needed). Session digest (open BLK via the status parser, actionable TODO, last journal line) in `hooks/session-start.sh` on `source: startup|compact|clear` (native matchers; the mod's `session.compact` only skips); a SubagentStart twin if sub-agents need it. Injection = ID + title + lesson line; superseded never injected; budget ~1.5k chars per turn; once per context. Deferred: Read path triggers, Bash command triggers, "critical → deny once", Tier 1, cross-repo scope=global index, `memory_search` tool.
- **4d feedback and promotion.** DEFERRED until a plain injection log (ID, trigger kind, turn, cited or not) shows misses or noise; then /prune-memory reads it and promotion to a mechanism follows BDR-100.
- Proof: recall precision on ≥20 real prompts and ≥10 real errors, target ≥ the 14/22 baseline; digest after a real compaction; redaction test on the ledger; `/context` delta; captured-failure demo: an error from session N recalled in session N+1.
@@ -88,3 +88,9 @@ the user decides (it amends gated answer 2, the capture rule):
attention on ~70 % noise per call.
`probe` alone is not worth its complexity (10 of 25 noise samples).
## Decision (2026-11-04)
Option A accepted by the user at the gate. Implemented as `ERRORISH` in
`failureLine` (`mods/memory/hooks/register.ts`): contract answer 2-amended
and criterion 15. `noise.py --tighten errorish` reproduces the shipped rule.
+1 -1
View File
@@ -9,7 +9,7 @@ Format follows [Keep a Changelog](https://keepachangelog.com/) and this project
### Added
- **Secure-by-default guardrails**: `rules/secure-by-default.md` (always on) makes six domains baseline on every project (the Supabase and cloud-function detail lives in the path rules `rules/supabase.md` and `rules/cloud-functions.md`), plus systematic API and access hygiene (auth on every route, CORS, secrets, passwords hashed with argon2id or bcrypt, never compared in clear, logged or hardcoded): hosting (rate limit, CDN and firewall, hard spend cap), Supabase (RLS on every table, owner-scoped policies, no service role key client-side), SMS and email (recorded consent, unsubscribe, STOP), cloud functions (no self-trigger, instance cap, budget stop), injection (bound values in raw escapes, `format()` for dynamic SQL, allowlisted filters, no shell into a DB tool), exposure (no data in the console, no production source map, no debug flag, no secret in hydrated state, data attributes, hidden fields or shipped comments). `/guardrails` audits them: a stdlib Python scanner (`skills/guardrails/scripts/scan.py`, FAIL / WARN / MANUAL, exit 1 on FAIL) then judgment, report in `.claude/audits/GUARDRAILS.md`. The security-auditor gate runs the scanner's `api` and `supabase` domains and blocks on FAIL. Items only a provider dashboard can set stay MANUAL, never claimed done. An optional read-only live probe (`skills/guardrails/scripts/probe.py`, `--live`) confirms a finding from outside on a target the user owns and names: anon-read, cross-user, no-auth route, CORS reflection and a capped rate-limit burst, verdicts OPEN / CLOSED / SKIPPED / ERROR. An `exposure` block in the plan adds three read-only probes, meant for a production build or a staging URL: a served or inline source map for the page's scripts, a stack trace in a 404 or a user-named error route, sensitive keys in a JSON response (identifier-shaped names printed, never values); a target the probe could not observe is SKIPPED or ERROR, never CLOSED, and every plan path must start with `/`. It sends GET, HEAD and OPTIONS only (one opt-in POST burst, capped at 25), requires `--authorized`, takes secrets from the environment never the command line, never follows a redirect to another host, and stops at a request budget. After the report, `/guardrails` proposes fixes (plan phase, so Fable when the router can switch), applies only the ones the user accepts through the `bugfixer` executor and the `lib/verify-secure-loop.md` gates, then re-scans: each accepted fix is a contract criterion whose oracle is the scanner (`--assert-absent RULE:path`, marker `GUARDRAILS-CLEAR`), and a full pass against the pre-fix baseline (`--baseline`, marker `GUARDRAILS-NO-NEW`) catches regressions; a live probe replays on the user's go; two rounds at most, residuals reported open; `--report-only` keeps the audit alone. Suites: `lib/tests/guardrails-scan.test.sh` (clean fixture plus one mutant per rule, check modes, `gates.sh` integration) and `lib/tests/guardrails-probe.test.sh` (probe logic against a localhost fixture server).
- **/a11y skill**: accessibility leaves `/guardrails` and becomes its own skill. Same A11Y-* rules (img alt, field label, click without keyboard, focus outline removed, positive tabindex) on the shared scan engine (`skills/guardrails/scripts/scanner.py`, a `Catalogue` per CLI; `skills/a11y/scripts/scan.py`, markers `A11Y-CLEAR` / `A11Y-NO-NEW`), a Tab-only walk of the main flow on `--live` through `/browse` (marked not done otherwise), report `.claude/audits/A11Y.md`, fixes proposed with the alt and label wording as the user's choice, applied through the bugfix circuit (`bugfixer`, verify-secure gates, `bugfix/a11y-<date>`), re-pass against a baseline. The keyboard, alt and label doctrine moves from `rules/secure-by-default.md` to the lazy `rules/a11y.md` (loads on UI files only; `rules/web-building.md` points at it). `/guardrails` scans `injection` (INJ-*) and `exposure` (EXP-*) instead, with per-language SQL patterns, shared `code_files` / `hits` / `dedupe_lines` / `client_reachable` helpers and a walker that lists files over 1 MB by path; `--domain a11y` is a usage error there. `/web-validate` keeps full WCAG conformance. Suite `lib/tests/a11y-scan.test.sh`; routing row `reflect`; a top-level skill in no pack, so on under every profile.
- **memory mod**: `mods/memory/`, a Claude Code mod, captures Bash failures (`Exit code N` with an error line, redacted at capture, sub-agent ones marked) and milestones (a `feat`/`fix` commit, a `gitflow.sh finish`, a `make test` red then green) in the plugin `$.store` (3 sessions per project, 50 failures each, 1 MiB). One context note at the first prompt after a milestone; the `mcp__memory__memory_pending` tool lists milestones and failures as `NEW` or `known <ID>` against the BLK/LRN entries, and `/capitalize`, `/close` and the CAPITALIZE steps call it first. It never writes a registry. Off with `{"enabled": false}` in `~/.claude/memory.json`. Residuals: concurrent sessions last writer wins, non-Bash failures not captured, noise 83 % measured (`NOISE.md`).
- **memory mod**: `mods/memory/`, a Claude Code mod, captures Bash failures (`Exit code N` whose last line is error-shaped (a word like error, fatal, cannot, denied, a shellcheck code), redacted at capture, sub-agent ones marked) and milestones (a `feat`/`fix` commit, a `gitflow.sh finish`, a `make test` red then green) in the plugin `$.store` (3 sessions per project, 50 failures each, 1 MiB). One context note at the first prompt after a milestone; the `mcp__memory__memory_pending` tool lists milestones and failures as `NEW` or `known <ID>` against the BLK/LRN entries, and `/capitalize`, `/close` and the CAPITALIZE steps call it first. It never writes a registry. Off with `{"enabled": false}` in `~/.claude/memory.json`. Residuals: concurrent sessions last writer wins, non-Bash failures not captured, noise 83 % measured before the filter, cut by two thirds (`NOISE.md`).
- **model-router mod**: `mods/model-router/`, a Claude Code mod (function-hooks plugin), routes every repo skill and agent from phase rows (`plan`, `reflect`, `orchestrate`, `escalate`, `judge`, `audit`, `implement`, `write`, `verify`, `explore`, `apply`, `mechanical`; built-ins Explore on sonnet/medium, Plan on opus/xhigh). A typed skill routes the main loop to its row, and a best-tier row holds across turns in a run slot until `/route clear`, `/route off`, a user `/model` or a typed skill on a non-best row. Agents get their row's model at spawn (within the tier, upward only) and its effort on every step; explicit Agent params win. Orchestrators declare their phases through the `mcp__model-router__route` tool. `ultrathink` in a prompt sets the turn's minimum effort and `/route effort=max` holds until `/route clear`; the built-in `/effort` is not a lever inside a run. `/route show` names the run slot (`main: run <phase>`), and a `null` row in the override drops a default row. The model gets a `route` tool and the user a `/route` command (`show|clear|off|on|reload|pending|ask on|off|forget <name|all|projects>|<phase>|model=<alias|id> effort=<level>|switch on|off|verbose on|off`). Optional per-machine config `~/.claude/model-router.json`, where `"enabled": false` turns it off on that machine. The spinner suffix and the status line show the route in force. It loads in every session through the tracked symlink `skills/model-router` (`model-router@skills-dir`). `make doctor` gains a Mods section; suite `make test suite=lib/tests/mods.test.sh`. Known limits: a main-loop switch (a `/model` hand pick excepted) runs only while the cold read it costs (the context minus what the target model's prompt cache holds) fits `upgradeMaxTokens` (200000) or `downgradeMaxTokens` (120000), and a downgrade also needs `mainModelSwitch` (on by default, off on any non-boolean value); the hooks send full model ids, so the `models` table has to follow new versions.
- **model-router first-use confirmation**: `mods/model-router/routing.json` (tracked) is the single source of the phase table and of every skill and agent row, and keeps the decisions: `confirmed`, `changed` (`from`/`to`), `projects` exceptions keyed by the origin remote reduced to `host/path` (credentials and local paths never stored), and `ask`. The first use of a rowed typed skill, a rowed agent spawn or a main-loop phase declared through the `route` tool opens a dialog with context: the skill's description (first sentence of its `SKILL.md` frontmatter) or the agent's, the phase with its `about` line (a new field on each of the 12 phases) and the model id and effort the next step really runs on. A row offers Later, Keep or Change; a main-loop phase Later or Keep. Change asks the model (fable, opus, sonnet, haiku with their tier), then the effort among those the phases of that model use (skipped when there is only one), then Everywhere or This project only; the pair maps to an existing phase (rows stay phase names, the same phase counts as Keep, a pair no phase offers is added by hand as a new phase). A skill-row change toasts the model and effort it now runs on, with the `/route switch on` hint when the main loop holds back a downgrade; a free-text answer counts as Later. One dialog at a time, never in headless (`-p`) runs or inside a sub-agent. Only a dialog answer, `/route ask on|off` or `/route forget` (which takes decisions back; a changed row returns to its shipped phase, the frontmatter floors stay yours to realign) writes the file (serialized, 64 KiB cap, never created when absent); each write asks you to commit it from the config repo. `/route pending` lists unconfirmed rows and phases. Layers: routing.json < `~/.claude/model-router.json` (its `ask` wins); a project's `.claude/model-router.json` is never read. Tests: `mods/model-router/hooks/register.test.ts`.
- **model-router `/model` scope**: a `/model <name>` typed in the composer, or a pick in the `/model` picker, with a model the table knows asks where it applies. The picker's switch is held first (PreModelSwitch deny; the engine prints that a hook blocked it); a pick while another dialog is open is refused with `answer the open dialog first`. This project writes the full id as `model` into the project's `.claude/settings.local.json` (created if absent, refused through a link) and sets a sticky model route. This conversation sets the sticky route only. Everywhere runs the native `/model` (user `settings.json`). Both non-native answers drop the run slot and keep a sticky effort. With the picker's Default, an unknown name, a headless run or another origin, the native command runs with no question. A model chosen in that dialog always switches: it bypasses the cold-read caps and the `mainUpgrade` / `mainModelSwitch` flags, and while it is marked down or outside a known window it waits and the automatic chain decides. A native switch or `/clear` drops it; `/route model=` keeps the caps. Known limits: the `/config` Model row still writes user `settings.json`; a dialog never answered has no timeout. Tests: `mods/model-router/hooks/register.test.ts`.
+3 -4
View File
@@ -156,14 +156,13 @@ Limits: a main-loop switch re-reads cold the part of the context the target mode
`mods/memory/` is a second Claude Code mod. It watches Bash failures and milestones so that `/capitalize` starts from what really happened, not from recollection. Writing a registry stays a model draft, your approval and `lib/memory.sh`; the mod never writes one.
- Records: a Bash result whose text starts `Exit code N` and whose last line (the first line, the rtk trailer and letterless lines dropped) is an error line. The entry is stored redacted: `KEY=value` secrets, Stripe, AWS, GitHub, Slack, SendGrid and Supabase keys, private key blocks, Bearer tokens and `user:pass@` URLs. Permission refusals, guard redirects and tool_use errors are never captured. A sub-agent failure is marked `(sub-agent)`.
- Milestones: a successful `feat` or `fix` commit (plain `-m` or heredoc form), a `gitflow.sh finish` (not `finish chore`), a `make test ...` command red then green.
- Records: a Bash result whose text starts `Exit code N` and whose last line (the first line, the rtk trailer and letterless lines dropped) is an error line. That line must also be error-shaped: it holds a word such as error, fatal, cannot, No such, denied, failed, unexpected, traceback, or a shellcheck code (SC1234); otherwise nothing is stored. The entry is stored redacted: `KEY=value` secrets, Stripe, AWS, GitHub, Slack, SendGrid and Supabase keys, private key blocks, Bearer tokens and `user:pass@` URLs. Permission refusals, guard redirects and tool_use errors are never captured. A sub-agent failure is marked `(sub-agent)`.
- Milestones: a successful `feat` or `fix` commit (plain `-m` or heredoc form), a `gitflow.sh finish` (not `finish chore`), a `make test ...` command red then green. Milestones are recorded on the main loop only: sub-agent commits and finishes are ignored.
- Store: the plugin's `$.store`, keyed by project root: the 3 most recent sessions per project, 50 failures per session, 2 KiB per entry, 1 MiB for the whole store. It survives `/clear`. The store is the plugin's JSON file under the Claude configuration directory; delete it to wipe the captures.
- Note: one context line, `memory: <kind> <label> — <n> new failure mode(s) this session; /capitalize when ready.`, at the first composer prompt after a milestone. Never per turn, never at Stop, never in a sub-agent.
- Tool: `mcp__memory__memory_pending` (deferred: a skill loads it once with `ToolSearch("select:mcp__memory__memory_pending")`). `/capitalize`, `/close` and the CAPITALIZE steps of `/feat`, `/bugfix`, `/hotfix`, `/ship-feature` and `/commit-change` call it first. It lists this session's milestones, then the failures as `NEW` or `known <ID>` (word 4-grams matched against the backticked spans of BLK and LRN entries, superseded ones excluded), earlier sessions marked. Every text it returns is data. It never writes a registry and never calls `lib/memory.sh`.
- Off switch: `{"enabled": false}` in `~/.claude/memory.json`, read at the first event of a session, so it applies at the next session or after `/reload-plugins`. Off, the tool answers `memory capture is off (~/.claude/memory.json)`.
- Residuals: cross-process writes are unverified (two concurrent sessions: last writer wins). Non-Bash failures are not captured. The superseded reader is lexical (header tag or last labelled status line). 40-hex Gitea tokens are kept by design, they look like SHAs, and `Authorization: token ...` is not caught. Noise measured at 83 % on the shipped rule over 14 days of this repo's transcripts, mostly sub-agent probes; a tightening is proposed at the merge gate (`.claude/tasks/plans/2026-11-03-memory-capture-spike/NOISE.md`).
- Residuals: cross-process writes are unverified (two concurrent sessions: last writer wins). Non-Bash failures are not captured. The superseded reader is lexical (header tag or last labelled status line). 40-hex Gitea tokens are kept by design, they look like SHAs, and `Authorization: token ...` is not caught. Measured at 83 % noise before the error-shaped filter over 14 days of this repo's transcripts; the filter keeps every useful sample and cuts captures by two thirds (`.claude/tasks/plans/2026-11-03-memory-capture-spike/NOISE.md`).
---
+3 -3
View File
@@ -206,13 +206,13 @@ La config par machine, optionnelle, vit dans `~/.claude/model-router.json` et pa
Le mod `mods/memory/` note les échecs Bash et les jalons de la session pour que `/capitalize` parte des faits. Il n'écrit jamais un registre : un brouillon du modèle, ton accord et `lib/memory.sh` restent la seule voie.
- Ce qu'il enregistre : un résultat Bash dont le texte commence par `Exit code N` et dont la dernière ligne (première ligne, trailer rtk et lignes sans lettre écartés) est une ligne d'erreur. Elle est stockée expurgée : secrets `CLE=valeur`, clés Stripe, AWS, GitHub, Slack, SendGrid et Supabase, blocs de clé privée, jetons Bearer, URL `user:pass@`. Refus de permission, redirections de garde et erreurs de tool_use ne sont jamais captés. Un échec de sous-agent est marqué `(sub-agent)`.
- Jalons : un commit `feat` ou `fix` réussi (`-m` simple ou heredoc), un `gitflow.sh finish` (pas `finish chore`), une commande `make test ...` rouge puis verte.
- Ce qu'il enregistre : un résultat Bash dont le texte commence par `Exit code N` et dont la dernière ligne (première ligne, trailer rtk et lignes sans lettre écartés) est une ligne d'erreur. Cette ligne doit aussi avoir une forme d'erreur : un mot comme error, fatal, cannot, No such, denied, failed, unexpected, traceback, ou un code shellcheck (SC1234), sinon rien n'est stocké. Elle est stockée expurgée : secrets `CLE=valeur`, clés Stripe, AWS, GitHub, Slack, SendGrid et Supabase, blocs de clé privée, jetons Bearer, URL `user:pass@`. Refus de permission, redirections de garde et erreurs de tool_use ne sont jamais captés. Un échec de sous-agent est marqué `(sub-agent)`.
- Jalons : un commit `feat` ou `fix` réussi (`-m` simple ou heredoc), un `gitflow.sh finish` (pas `finish chore`), une commande `make test ...` rouge puis verte. Les jalons ne sont notés que sur la boucle principale : commits et finish de sous-agents ignorés.
- Stockage : le `$.store` du plugin, par racine de projet : 3 sessions les plus récentes par projet, 50 échecs par session, 2 Kio par entrée, 1 Mio pour tout le store. Il survit à `/clear`. Le store est le fichier JSON du plugin sous le dossier de configuration de Claude ; le supprimer efface les captures.
- La note : une ligne de contexte, `memory: <kind> <label> — <n> new failure mode(s) this session; /capitalize when ready.`, au premier prompt tapé après un jalon. Jamais à chaque tour, jamais au Stop, jamais dans un sous-agent.
- L'outil : `mcp__memory__memory_pending` (différé : un skill le charge une fois avec `ToolSearch("select:mcp__memory__memory_pending")`). `/capitalize`, `/close` et les étapes CAPITALIZE de `/feat`, `/bugfix`, `/hotfix`, `/ship-feature` et `/commit-change` l'appellent en premier. Il liste les jalons de la session, puis les échecs `NEW` ou `known <ID>` (4-grammes de mots comparés aux passages entre accents graves des entrées BLK et LRN, les remplacées exclues), les sessions précédentes signalées. Chaque texte est une donnée. Il n'écrit aucun registre et n'appelle pas `lib/memory.sh`.
- Interrupteur : `{"enabled": false}` dans `~/.claude/memory.json`, lu au premier événement d'une session : effet à la session suivante ou après `/reload-plugins`. Coupé, l'outil répond `memory capture is off (~/.claude/memory.json)`.
- Limites connues : les écritures entre processus ne sont pas vérifiées (deux sessions simultanées : la dernière écrit). Les échecs hors Bash ne sont pas captés. Le lecteur « remplacé » est lexical (étiquette d'en-tête ou dernière ligne de statut étiquetée). Les jetons Gitea de 40 hex sont gardés volontairement (ils ressemblent à des SHA) et `Authorization: token ...` n'est pas attrapé. Bruit mesuré à 83 % avec la règle livrée sur 14 jours de transcripts de ce dépôt, surtout des sondes de sous-agents ; un resserrement est proposé à la porte de merge (`.claude/tasks/plans/2026-11-03-memory-capture-spike/NOISE.md`).
- Limites connues : les écritures entre processus ne sont pas vérifiées (deux sessions simultanées : la dernière écrit). Les échecs hors Bash ne sont pas captés. Le lecteur « remplacé » est lexical (étiquette d'en-tête ou dernière ligne de statut étiquetée). Les jetons Gitea de 40 hex sont gardés volontairement (ils ressemblent à des SHA) et `Authorization: token ...` n'est pas attrapé. Bruit mesuré à 83 % avant le filtre de forme d'erreur sur 14 jours de transcripts de ce dépôt ; le filtre garde tous les échantillons utiles et réduit les captures des deux tiers (`.claude/tasks/plans/2026-11-03-memory-capture-spike/NOISE.md`).
## Les plugins — décision rapide