greprag 5.22.0 → 5.22.2

package/skill/lore-advisor/SKILL.md

@@ -1,15 +1,17 @@
 ---
 name: lore-advisor
 description: |
-  Audit project lore for drift, mine episodic memory for emergent learnings,
-  promote project-agnostic lore to global. One-at-a-time conversational
+  Digest the smell queue (raw field signals → fix the broken mechanism + instantiate
+  durable lore), audit project lore for drift, mine episodic memory for emergent
+  learnings, promote project-agnostic lore to global. One-at-a-time conversational
   review — never bulk-prune.
 
-  Trigger phrases: "/lore-advisor", "/lore", "review my lore", "audit lore",
-  "lore is stale", "prune lore", "mine episodic for lore".
+  Trigger phrases: "/lore-advisor", "/lore", "digest smells", "drain the smell queue",
+  "any smells", "review my lore", "audit lore", "lore is stale", "prune lore",
+  "mine episodic for lore".
 metadata:
   author: travsteward
-  version: "1.1.0"
+  version: "1.2.0"
   repository: https://github.com/travsteward/greprag
 license: MIT
 ---
@@ -24,14 +26,17 @@ Lore is moving from a passive list toward **event-bound / semantic injection**
 
 The skill is **conversational**, not autonomous. Every prune / promote / edit / add decision goes through the operator one at a time. Bulk actions are forbidden.
 
+**Two feeds, one digestion.** Lore now has two supplies: the *deliberate* smell queue (`greprag lore smell`, raw field signals — `docs/lore-smell.md`) and the *automatic* episodic `learned` / `ruled_out` claims. Phase 0 drains the smell queue first; Phase B mines episodic. Both pass through the same durability gate — but a smell additionally asks whether a broken **mechanism** in the harness needs fixing (the fix ladder in Phase 0), not just whether a durable truth needs recording.
+
 ## Trigger phrases
 
-`/lore-advisor`, `/lore`, "review my lore", "audit lore", "lore is stale", "prune lore", "mine episodic for lore".
+`/lore-advisor`, `/lore`, "digest smells", "drain the smell queue", "any smells", "review my lore", "audit lore", "lore is stale", "prune lore", "mine episodic for lore".
 
 ## What it does
 
-Three phases, run in order. Operator may skip any phase. Each phase walks one entry at a time — never bulk-prune.
+Four phases, run in order (Phase 0 first). Operator may skip any phase. Each phase walks one entry at a time — never bulk-prune.
 
+- **Phase 0 — Smell digestion.** Drain the raw smell queue (`greprag lore smells`): per smell, fix the broken mechanism (hooks first, code second) and/or instantiate the durable truth, then retire it. Deliberate field signals outrank auto-mined claims, so this runs first.
 - **Phase A — Drift check.** Scan current lore for rot: stale file paths, conventions the codebase no longer follows (derived live, NOT from a static list), misfiled static-knowledge, age-based decay.
 - **Phase B — Episodic mining.** Mine episodic memory's `learned` / `ruled_out` claims; surface only candidates that pass the durability gate; offer to add.
 - **Phase C — Global promotion.** Identify project-agnostic lore that belongs in `~/.claude/docs/chip-spawn.md` as a universal rule.
@@ -55,6 +60,54 @@ This is the same gate the hourly compactor applies at write-time (greprag, 2026-
 
 ## Phases
 
+### Phase 0 — Smell digestion
+
+Smells are the *deliberate* lore feed: raw, undigested signals dropped from the field via `greprag lore smell` (`docs/lore-smell.md`). Unlike an episodic claim, a smell often names a **broken mechanism in the harness**, not just a fact. Digestion does two jobs per smell — **fix** the mechanism and **instantiate** the durable truth — and runs FIRST, because a deliberate signal outranks auto-mined claims.
+
+1. Pull the queue:
+   ```bash
+   greprag lore smells --format json
+   ```
+   Parse `smells[]` (`nodeId`, `text`, `createdAt`). Empty → say "No smells awaiting digestion." and move to Phase A.
+
+2. Walk one smell at a time. First **untangle** it — a single drop often conflates several mechanisms and truths (e.g. a dead-mailbox bug AND a "re-task ≠ launch a chip" insight). Separate them before triaging.
+
+3. For each, **investigate** (reproduce / read the relevant code or hooks to confirm it's real), then ask the two questions:
+
+   - **Is there a broken MECHANISM?** Fix it via the **fix ladder** — lowest rung that holds the fix:
+     1. **First pass — fix it in the hooks.** A PreToolUse guard, a UserPromptSubmit injection, a notification. Cheapest, reversible, and the same machinery as lore-triggers — ships as DATA, no deploy. Most mechanism smells resolve here.
+     2. **Second pass — fancier coding.** Only when a hook can't express the fix: server-side logic, a bounce, a schema or CLI change. The advisor does NOT implement code-tier fixes inline — spawn a chip (`spawn_task`, per `~/.claude/docs/chip-spawn.md`) or hand to the operator.
+
+     If the fix is architectural (a recurring failure class), route through `/root-cause` — fix the pattern that makes the bug possible, never slap a guard on today's trigger.
+
+   - **Is there a durable TRUTH?** Apply the durability gate (below). If it passes, instantiate as durable lore — and, once triggers ship, attach its injection rule (`docs/lore-triggers.md`):
+     ```bash
+     greprag lore add "<clean standing rule>" --scope <scope>
+     ```
+
+4. **Summarize + confirm before ANY action** — a smell is a brief, and the hard rule is the advisor never auto-acts on a brief. Present:
+   ```
+   SMELL [<nodeId>] (<date>)
+     "<text>"
+   Triage:
+     • mechanism: <...>  → fix: [hook|code|root-cause] <proposal>
+     • truth:     <...>  → lore: "<rule>"  scope=<s>
+   Action? (f)ix / (i)nstantiate / (b)oth / (s)kip / (n)oise
+   ```
+   - **fix** → apply the hook-tier fix (after confirm), or spawn the chip for a code-tier fix.
+   - **instantiate** → `greprag lore add "<rule>" --scope <scope>` with the durability-gated rule.
+   - **both** → fix and instantiate.
+   - **skip** → leave the smell in the queue for a later pass (no retire).
+   - **noise** → already-handled or not real; retire without action.
+
+5. **Retire** only once the smell's content is preserved — the fix landed, a durable lore entry captures the constraint, OR a chip/TODO owns the code-tier fix. Never retire a smell whose fix is merely *planned*. Retire = delete (interim, until a real `status` field exists):
+   ```bash
+   greprag lore delete <nodeId>
+   ```
+   Confirm by printing `Retired smell [<nodeId>].`
+
+6. Phase summary: `Phase 0: N smells. Fixed F (H hooks, C chips). Instantiated I. Skipped S. Noise X.`
+
 ### Phase A — Drift check
 
 1. Pull the current project's lore as JSON:
@@ -168,16 +221,17 @@ The richest lore source is the compactor's structured `learned` / `ruled_out` cl
 After all three phases, print one combined line:
 
 ```
-Reviewed N lore. Pruned X. Edited Y. Added Z from episodic. Promoted W to global.
+Digested D smells (fixed F, instantiated I). Reviewed N lore. Pruned X. Edited Y. Added Z from episodic. Promoted W to global.
 ```
 
 If any phase was skipped (operator pressed q / Ctrl-C / typed "skip phase"), include `(phase <X> skipped)` per skipped phase.
 
 ## When this skill should be invoked
 
-- Operator types `/lore-advisor` or `/lore`.
+- Operator types `/lore-advisor` or `/lore`, or says "digest smells," "drain the smell queue," "any smells."
+- The `⚠ N smells awaiting digestion` footer fires on a greprag command — the smell-queue nudge. Offer to run Phase 0.
 - Operator says "audit my lore," "lore is stale," "prune lore," "mine episodic for lore," "any new learnings worth saving?"
-- Proactively offer the skill at the end of a `/greprag` briefing if `greprag lore list` shows entries older than 90 days OR if the operator just finished a refactor / rename and lore drift is likely.
+- Proactively offer the skill at the end of a `/greprag` briefing if `greprag lore smells` is non-empty, if `greprag lore list` shows entries older than 90 days, OR if the operator just finished a refactor / rename and lore drift is likely.
 
 ## Notes