greprag 5.6.1 → 5.7.1

package/skill/greprag/SKILL.md

@@ -41,12 +41,15 @@ Parse the JSON. The keys to check, in this order:
 
 For Claude Code, also check `hooks.session_start_recap`, `hooks.stop_store`, `hooks.post_tool_use_spawn_reminder`. (The legacy `user_prompt_submit_notify` hook was removed in v5.6.1 — live inbox delivery is now the Monitor watcher's job. Don't install it.)
 
-Also check the chip-coordination convention is installed in global CLAUDE.md (Step 3b):
+Also check the chip-spawn pointer is installed in global CLAUDE.md (Step 3b):
 ```bash
-if grep -q "greprag-conventions:start v3" ~/.claude/CLAUDE.md; then echo CONV_V3
+if grep -q "greprag-conventions:start v5" ~/.claude/CLAUDE.md; then echo CONV_V5
+elif grep -q "greprag-conventions:start v4" ~/.claude/CLAUDE.md; then echo CONV_V4_NEEDS_UPGRADE
+elif grep -q "greprag-conventions:start v3" ~/.claude/CLAUDE.md; then echo CONV_V3_NEEDS_UPGRADE
 elif grep -q "greprag-conventions:start v2" ~/.claude/CLAUDE.md; then echo CONV_V2_NEEDS_UPGRADE
 elif grep -q "greprag-conventions:start v1" ~/.claude/CLAUDE.md; then echo CONV_V1_NEEDS_UPGRADE
 else echo CONV_MISSING; fi
+test -f ~/.claude/docs/chip-spawn.md && echo DOC_OK || echo DOC_MISSING
 ```
 
 Also check the permission allowlist (Step 3c):
@@ -95,71 +98,54 @@ Edit `~/.claude/settings.json` to add the missing hook(s):
   ```json
   { "matcher": "", "hooks": [{ "type": "command", "command": "greprag-hook store", "timeout": 10000 }] }
   ```
-- **PostToolUse spawn-reminder** (under `hooks.PostToolUse`):
+- **PreToolUse pre-spawn-check** (under `hooks.PreToolUse`):
   ```json
-  { "matcher": "mcp__ccd_session__spawn_task", "hooks": [{ "type": "command", "command": "greprag-hook spawn-reminder", "timeout": 3000 }] }
+  { "matcher": "mcp__ccd_session__spawn_task", "hooks": [{ "type": "command", "command": "greprag-hook pre-spawn-check", "timeout": 3000 }] }
   ```
-  Fires after every `spawn_task` chip dispatch and tells the agent to arm a `Monitor` watcher on its own inbox in the same turn — so the chip's report-back doesn't sit invisible until the next user prompt. The convention itself lives in `~/.claude/docs/agent-coordination.md § Block 3`; this hook just makes it reflexive.
+  Fires BEFORE every `spawn_task` chip dispatch and validates the call against three machine-checkable rules from `~/.claude/CLAUDE.md § Chip Spawning`: title prefix `Chip: `, Block 1 (`git worktree add` in prompt), Block 2 (`greprag send` in prompt). Returns `permissionDecision: "deny"` with remediation when any rule fails; the agent re-composes the call.
 
 Append the missing entries to the existing arrays (create the arrays if absent). Don't overwrite existing hooks from other tools.
 
+**Removing the legacy PostToolUse spawn-reminder hook** (only on upgrade from v0.x → v0.12+): if `~/.claude/settings.json` `hooks.PostToolUse` contains an entry with `matcher: "mcp__ccd_session__spawn_task"` and `command: "greprag-hook spawn-reminder"`, delete that entry. The behavior it carried (arming a Monitor watcher) is now ambient — SessionStart auto-arms the watcher in every greprag-enabled session, so the PostToolUse reminder is vestigial and the underlying subcommand was removed in v0.12.
+
 ## Step 3b — Convention install (only if marker missing or out-of-date)
 
-The chip-spawning + agent-coordination convention is a one-time install into the user's global CLAUDE.md. Every project session reads it; without it, chips spawn without worktree isolation, inbox report-back, or reply-listening. Detect first:
+Two pieces install together:
+
+1. A single loud pointer line in `~/.claude/CLAUDE.md` — always loaded into every session's context.
+2. The actual chip-spawn protocol at `~/.claude/docs/chip-spawn.md` — read on demand by the agent when about to call `spawn_task`.
+
+The pointer is short by design: the body costs zero tokens per session that never spawns a chip, the agent reads the doc only when about to act. The PreToolUse `pre-spawn-check` hook enforces title + Block 1/2 at the tool boundary, so an agent that skips the doc still can't ship a bad chip.
 
+Detect first:
 ```bash
-if grep -q "greprag-conventions:start v3" ~/.claude/CLAUDE.md; then echo V3
+if grep -q "greprag-conventions:start v5" ~/.claude/CLAUDE.md; then echo V5
+elif grep -q "greprag-conventions:start v4" ~/.claude/CLAUDE.md; then echo V4_UPGRADE
+elif grep -q "greprag-conventions:start v3" ~/.claude/CLAUDE.md; then echo V3_UPGRADE
 elif grep -q "greprag-conventions:start v2" ~/.claude/CLAUDE.md; then echo V2_UPGRADE
 elif grep -q "greprag-conventions:start v1" ~/.claude/CLAUDE.md; then echo V1_UPGRADE
 else echo MISSING; fi
-test -f ~/.claude/docs/agent-coordination.md && echo DOC_OK || echo DOC_MISSING
+test -f ~/.claude/docs/chip-spawn.md && echo DOC_OK || echo DOC_MISSING
 ```
 
-**If `MISSING`**, insert the v3 block into `~/.claude/CLAUDE.md` immediately after the `## Inbox` section (use the Edit tool, marker comments verbatim):
+**If `MISSING`**, insert the v5 block into `~/.claude/CLAUDE.md` immediately after the `## Inbox` section (use the Edit tool, marker comments verbatim):
 
 ```markdown
-<!-- greprag-conventions:start v3 -->
-## Chip Spawning & Agent Coordination
-
-Delegating work — `spawn_task` chip vs `Agent` tool, two chip modes, the worktree-first + inbox-report + reply-listening convention. Full spec: `~/.claude/docs/agent-coordination.md`.
-
-**Two chip modes** — pick deliberately:
-- **Mode A (default) — ship chip.** Lands in a worktree, ships code, user-in-loop optional. The workhorse. A chip that dispatches its own `Agent` sub-tasks mid-work is still Mode A — that's a behavior, not a peer mode.
-- **Mode B — discussion chip.** Lands as a context-rich conversation partner. Reads code, proposes, iterates. Ships nothing without explicit go-ahead. Output is a decision or a scoped follow-up chip. Reach for B the moment you notice you're proposing architecture from partial grep reads.
-
-**Spawn primitives** (not modes — pick by what fits the work):
-- `spawn_task` — Mode A or B chip. Worktree, chip UI, persistence, optional cross-project via `cwd:`.
-- `Agent` — one-shot delegation, returns once to caller. No chip lifecycle. Pass `subagent_type` (Explore / Plan / general-purpose / code-reviewer) when a specialized shape fits.
-
-**Non-negotiables for every `spawn_task` chip prompt:** (0.5) project facts pulled from `greprag fact`, (1) worktree-first setup, (2) `greprag send` report-back, (3) `Monitor` on own inbox for follow-ups. Without them the chip pollutes the main checkout, has no return channel, or dies after one report. Copy the boilerplate verbatim from the deep doc.
-
-**Reply listening (any session, not just chips).** Any time you `greprag send` a message that could draw a directive in response, arm a `Monitor` watcher on your own inbox in the same turn. Use the bash-wrapper form so the watcher auto-restarts if the inner SSE process dies (network blip, supervisor bug, Cygwin fork failure):
-
-```bash
-while true; do greprag inbox watch --session <own-session-id> --json; echo "[wrapper] watcher exited, restarting in 1s" >&2; sleep 1; done
-```
-
-Run under `Monitor` with `persistent: true`. Get `<own-session-id>` from this session's SessionStart hook system-reminder ("Your greprag session id: `<8-hex>`") — every session gets one. The `--project <own-project>` form is a legacy backstop for sessions where SessionStart never fired and should fire essentially never; using it as a default broadcasts traffic to every sibling session in the project (observed cross-talk in production). The Stop hook only fires between user prompts; without Monitor, mid-task replies are invisible until the next stop boundary.
-
-For real-time chip reports, the parent arms the same wrapped watcher with `--session <parent-session-id>` (always available from the orchestrator's own SessionStart hook — substitute it before the chip prompt leaves your turn). The `--project <parent-project>` variant is for genuine multi-chip-campaign cases where you've fanned out N chips in parallel and want all reports on one stream; do not reach for it because you "forgot" your session id. Each stdout line = one notification. Do NOT use `Bash(run_in_background)` — it only fires on process completion, not per line; a watcher never exits, so the parent gets zero events. Do NOT use the bare `greprag inbox watch` without the `while true` wrapper — if the inner watcher dies you go silently deaf with no restart.
-<!-- greprag-conventions:end v3 -->
+<!-- greprag-conventions:start v5 -->
+**CHIP SPAWN METHOD** → before calling `spawn_task`, read `~/.claude/docs/chip-spawn.md`. Non-negotiable.
+<!-- greprag-conventions:end v5 -->
 ```
 
-**If `V2_UPGRADE`**, replace the entire `<!-- greprag-conventions:start v2 -->` … `<!-- greprag-conventions:end v2 -->` block (inclusive of markers) with the v3 block above. Tell the user "Upgrading greprag-conventions v2 → v3 (collapses Mode B mission-commander into Mode A behavior; renames Mode C to Mode B = discussion chip)." Don't preserve any v2 content — v3 supersedes.
-
-**If `V1_UPGRADE`**, replace the entire `<!-- greprag-conventions:start v1 -->` … `<!-- greprag-conventions:end v1 -->` block (inclusive of markers) with the v3 block above. Tell the user "Upgrading greprag-conventions v1 → v3 (adds Block 3 reply-listening; reframes modes as ship chip + discussion chip)." Don't preserve any v1 content — v3 supersedes.
+**If `V4_UPGRADE`**, replace the entire `<!-- greprag-conventions:start v4 -->` … `<!-- greprag-conventions:end v4 -->` block (inclusive of markers) with the v5 single-line pointer above. Tell the user "Upgrading greprag-conventions v4 → v5 (moves the inline body to ~/.claude/docs/chip-spawn.md; CLAUDE.md now carries only a loud pointer read on demand)."
 
-**If `DOC_MISSING`**, copy the canonical content from the template shipped with this skill:
-```bash
-mkdir -p ~/.claude/docs && cp ~/.claude/skills/greprag/templates/agent-coordination.md ~/.claude/docs/agent-coordination.md
-```
+**If `V3_UPGRADE`, `V2_UPGRADE`, or `V1_UPGRADE`**, same replacement pattern: delete the old block (markers inclusive) and insert the v5 pointer above. Tell the user "Upgrading greprag-conventions v{1|2|3} → v5."
 
-If `DOC_OK` but you just upgraded from v1 or v2, overwrite the doc too (the v3 template carries the new mode framing + operating guidelines + detection signals):
+**Also on any upgrade from v1/v2/v3 → v5**, delete the legacy deep doc if it exists (its content lives at the new `chip-spawn.md` path now):
 ```bash
-cp ~/.claude/skills/greprag/templates/agent-coordination.md ~/.claude/docs/agent-coordination.md
+rm -f ~/.claude/docs/agent-coordination.md
 ```
 
-The deep doc covers Block 0.5 (project-facts pull), Block 1 (worktree-first), Block 2 (inbox report-back), Block 3 (reply-listening), parent-side watcher, Mode A operating guidelines + sub-Agent dispatch (3-layer chain when needed), Mode B detection signals + operating guidelines, and anti-patterns.
+**If `DOC_MISSING`**, the chip-spawn protocol doc must be installed at `~/.claude/docs/chip-spawn.md`. `greprag init` copies it from the npm package on install; if it's missing here, re-run `greprag init` (`init` is idempotent and will re-copy the template). The doc is the body the pointer line references — without it the agent has nothing to read.
 
 Re-run the grep to confirm install. Markers must stay verbatim — they're how subsequent `/greprag` runs detect "already installed" and skip this step.
 
@@ -625,9 +611,9 @@ Otherwise present verbatim:
 
 Do not rewrite or summarize. Present verbatim — the compactor already shaped it.
 
-## Step 6b — Seeding learnings (project-facts substrate)
+## Step 6b — Seeding lore (LEARNINGS substrate)
 
-Whenever you waste tokens *discovering* something a future agent shouldn't have to re-discover, seed it as a project fact. Discovery is fine the first time — the failure mode is repeating it every time a chip spawns or a new session opens.
+Lore = what was learned. Project-specific emergent knowledge — gotchas, discovered constraints, drift-prone observations. Distinct from static project knowledge (which belongs in CLAUDE.md / docs / code structure). Whenever you waste tokens *discovering* something a future agent shouldn't have to re-discover, seed it as project lore. Discovery is fine the first time — the failure mode is repeating it every time a chip spawns or a new session opens.
 
 ### When to seed
 
@@ -640,51 +626,51 @@ Three signatures of discovery waste — if you see one in your own trace, seed t
 ### How to seed
 
 ```bash
-greprag fact add "<one-sentence fact, optionally with a file path>" --scope <scope> [--project <name>]
+greprag lore add "<one-sentence learning, optionally with a file path>" --scope <scope> [--project <name>]
 ```
 
 Examples:
 ```bash
-greprag fact add "Migrations live at repo root: migrations/<NNN>_<name>.sql. Apply with node scripts/apply-migration.cjs migrations/<file>.sql." --scope chip-startup
+greprag lore add "Migrations live at repo root: migrations/<NNN>_<name>.sql. Apply with node scripts/apply-migration.cjs migrations/<file>.sql." --scope chip-startup
 
-greprag fact add "Inbox storage uses JSONB metadata on nodes (store kind='inbox'). No inbox_messages table — dropped in migration 035. See packages/core/src/inbox.ts." --scope inbox-touch
+greprag lore add "Inbox storage uses JSONB metadata on nodes (store kind='inbox'). No inbox_messages table — dropped in migration 035. See packages/core/src/inbox.ts." --scope inbox-touch
 
-greprag fact add "Build everything from repo root: npm run build (Turborepo). Forced rebuild: npm run build -- --force." --scope general
+greprag lore add "Build everything from repo root: npm run build (Turborepo). Forced rebuild: npm run build -- --force." --scope general
 ```
 
 **Scope naming.** Free-form strings — there is no enum. Check what's already in use before inventing a new label:
 
 ```bash
-greprag fact scopes [--project <name>]
+greprag lore scopes [--project <name>]
 ```
 
 Conventional scopes:
 - `chip-startup` — what a freshly-spawned chip needs in its first 5 turns. Layout, build commands, test runners, key file paths.
 - `general` — applies to almost any session in this project.
-- `<subsystem>-touch` — facts that matter only when editing a specific subsystem (`inbox-touch`, `episodic-touch`, `enrichment-touch`).
+- `<subsystem>-touch` — lore that matters only when editing a specific subsystem (`inbox-touch`, `episodic-touch`, `enrichment-touch`).
 - `env` — environment / credentials / DB connection gotchas.
 
-Pick the narrowest scope that still applies. A fact about migration paths is `chip-startup` (every chip needs it); a fact about how the hourly compactor's prompt versioning works is `episodic-touch` (only relevant if you're editing that subsystem).
+Pick the narrowest scope that still applies. A lore entry about migration paths is `chip-startup` (every chip needs it); one about how the hourly compactor's prompt versioning works is `episodic-touch` (only relevant if you're editing that subsystem).
 
-### Reading facts back (pull pattern)
+### Reading lore back (pull pattern)
 
 ```bash
-greprag fact query --scope chip-startup --limit 10 --format markdown   # for inlining into a chip prompt
-greprag fact query --scope inbox-touch --query "session routing"        # lexical-rank within a scope
-greprag fact query --query "how do migrations apply" --limit 5          # cross-scope, lexical-rank only
-greprag fact list                                                       # human-review every fact, grouped by scope
-greprag fact delete <nodeId>                                            # prune stale fact (nodeId printed in list)
+greprag lore query --scope chip-startup --limit 10 --format markdown   # for inlining into a chip prompt
+greprag lore query --scope inbox-touch --query "session routing"        # lexical-rank within a scope
+greprag lore query --query "how do migrations apply" --limit 5          # cross-scope, lexical-rank only
+greprag lore list                                                       # human-review every entry, grouped by scope
+greprag lore delete <nodeId>                                            # prune stale entry (nodeId printed in list)
 ```
 
-`--format markdown` returns a numbered list with no decoration — drop it straight into a `**Project Facts**` block when spawning a chip.
+`--format markdown` returns a numbered list with no decoration — drop it straight into a `**Project Lore**` block when spawning a chip.
 
-### Deliberate review
+### Deliberate review (via /lore-advisor)
 
-Periodically run `greprag fact list` against a project, especially after a refactor or a major rename. Facts decay as code moves; prune anything stale via `greprag fact delete <nodeId>`. The substrate trusts the seeding agent — there's no auto-dedup or expiry, so the human (or a periodic `/greprag` audit pass) keeps the signal clean.
+Lore decays as code moves — paths change, conventions die, "learned that X" stops being true. Run `/lore-advisor` periodically (especially after a refactor or rename) to audit drift, mine episodic memory for newly-emerged learnings, and promote project-agnostic entries to global rules.
 
 ### Chip-spawn pull pattern
 
-When you compose a `spawn_task` chip prompt, pull `chip-startup` facts into the prompt before dispatching. Full convention lives in `~/.claude/docs/agent-coordination.md` § Block 0.5; the one-liner is: `greprag fact query --scope chip-startup --project <project> --limit 10 --format markdown`, then wrap the output in a `**Project Facts**` block at the top of the prompt. Skip the block when the output is empty.
+When you compose a `spawn_task` chip prompt, pull `chip-startup` lore into the prompt before dispatching. Full convention lives in `~/.claude/docs/chip-spawn.md`; the one-liner is: `greprag lore query --scope chip-startup --project <project> --limit 10 --format markdown`, then wrap the output in a `**Project Lore**` block at the top of the prompt. Skip the block when the output is empty.
 
 ## Step 7 — Cross-project discovery (for advisor agents)
 

package/skill/lore-advisor/SKILL.md

@@ -0,0 +1,183 @@
+---
+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
+  review — never bulk-prune.
+
+  Trigger phrases: "/lore-advisor", "/lore", "review my lore", "audit lore",
+  "lore is stale", "prune lore", "mine episodic for lore".
+metadata:
+  author: travsteward
+  version: "1.0.0"
+  repository: https://github.com/travsteward/greprag
+license: MIT
+---
+
+# Lore Advisor
+
+Project lore = LEARNINGS (emergent, drift-prone observations seeded via `greprag lore add`). Distinct from static project knowledge (CLAUDE.md, docs, code structure). Lore decays — paths change, conventions die, "learned that X" stops being true. This skill keeps the substrate healthy.
+
+The skill is **conversational**, not autonomous. Every prune / promote / edit decision goes through the operator one at a time. Bulk actions are forbidden.
+
+## Trigger phrases
+
+`/lore-advisor`, `/lore`, "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.
+
+- **Phase A — Drift check.** Heuristic scan of current lore for stale file paths, references to killed conventions, age-based decay.
+- **Phase B — Episodic mining.** Scan recent daily summaries for sentences signalling new learnings; offer to promote to lore.
+- **Phase C — Global promotion.** Identify project-agnostic lore that belongs in `~/.claude/docs/chip-spawn.md` as a universal rule.
+
+## Forbidden practices (HARD RULES)
+
+- **Never delete lore without explicit operator confirmation.** Each delete is its own y/n.
+- **Never edit `~/.claude/docs/chip-spawn.md` without explicit operator confirmation.** Global rules are sticky.
+- **Never bulk-prune.** Walk one at a time. If the operator says "just prune all the obvious ones," confirm the list aloud first ("I'd delete: A, B, C — confirm?") before any action.
+- **Never modify lore from a different project.** The skill only operates on the current project (resolved via `greprag lore list`).
+
+## Phases
+
+### Phase A — Drift check
+
+1. Pull the current project's lore as JSON:
+   ```bash
+   greprag lore list --format json
+   ```
+   Parse `lore[]`. Each entry has `nodeId`, `text`, `scope`, `createdAt`.
+
+2. For each entry, run three heuristic checks:
+
+   - **File-path check.** Extract any path matching `packages/<...>/<file.ext>`, `~/.claude/<...>`, `adr/<...>`, `docs/<...>`, `migrations/<...>`, `scripts/<...>`, `tests/<...>`. For each, verify the file exists relative to the project root:
+     ```bash
+     test -f <path> && echo OK || echo MISSING
+     ```
+     If MISSING → flag with `reason: "file-not-found:<path>"`.
+
+   - **Killed-convention check.** Match the lore text against this drift list:
+     - `Block 3` / `Block-3` (the old 3-block chip protocol)
+     - `<email>/<project>/<session-id>` or `/<email>/<project>/<session>` (legacy 3-segment address grammar — replaced by 1-segment in v0.11)
+     - `spawn-reminder` (PostToolUse hook removed in v0.12)
+     - `cp $main_root/.env` or `cp .env` from main into worktree (replaced by inline `set -a; source`)
+     - `agent-coordination.md` (deep doc deleted in v5.6.0; replaced by `chip-spawn.md`)
+     - `inline-conventions` / `greprag-conventions:start v1`, `v2`, `v3`, `v4` (superseded by v5 pointer)
+     - `MEMORY_HOOK_ENABLED` legacy boolean (now ambient)
+     - `greprag fact` (renamed to `greprag lore` in v5.7.0 — the alias is removed in v5.8.0)
+
+     Any match → flag with `reason: "dead-convention:<which>"`.
+
+   - **Age check.** If `createdAt` is older than 90 days from today AND no other heuristic fired, flag with `reason: "age-90d:<days>"`. Not automatically stale — just worth re-verifying.
+
+3. Surface each flagged entry one at a time. Format:
+   ```
+   [<nodeId>] scope=<scope> reason=<reason>
+   Text: <text>
+   Action? (k)eep / (e)dit / (d)elete / (s)kip
+   ```
+   - **keep** → no-op, move to next entry.
+   - **edit** → ask for the new text, then:
+     ```bash
+     greprag lore delete <nodeId>
+     greprag lore add "<new-text>" --scope <scope>
+     ```
+   - **delete** → `greprag lore delete <nodeId>`. Confirm by printing `Deleted [<nodeId>].`
+   - **skip** → no-op, move to next entry.
+
+4. Phase summary: `Phase A: reviewed N. Kept K. Edited E. Deleted D. Skipped S.`
+
+### Phase B — Episodic mining
+
+1. Resolve the current project's `projectId`:
+   ```bash
+   greprag project-id
+   ```
+
+2. Pull the last 30 days of daily summaries:
+   ```bash
+   FROM=$(date -u -d '30 days ago' +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -v-30d +%Y-%m-%dT%H:%M:%SZ)
+   TO=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+   curl -sf "https://api.greprag.com/v1/memory/by-period?projectId=<projectId>&type=daily&from=$FROM&to=$TO&limit=30" \
+     -H "Authorization: Bearer $GREPRAG_API_KEY"
+   ```
+   Parse `rows[]`. Each row has `created_at`, `body`.
+
+3. For each daily summary, scan the body for sentences containing any of these marker phrases (case-insensitive):
+   - `learned that`
+   - `the gotcha is`
+   - `won't work because`
+   - `had to`
+   - `discovered that`
+   - `turns out`
+   - `surprised that`
+
+   Extract the full sentence containing the marker (sentence boundary = `. ` / `! ` / `? ` or newline). Skip sentences shorter than 30 chars or longer than 300 chars.
+
+4. Present candidates one at a time:
+   ```
+   Daily summary from <YYYY-MM-DD> contains:
+     "<sentence>"
+   Promote to lore? (k)eep / (e)dit / (s)kip
+   ```
+   - **keep** → ask for the scope (suggest `chip-startup` if the sentence mentions paths/build/test; `general` otherwise; `env` if it mentions env vars / credentials). Then:
+     ```bash
+     greprag lore add "<sentence>" --scope <scope>
+     ```
+   - **edit** → ask for the polished text, then add with chosen scope.
+   - **skip** → no-op.
+
+5. Phase summary: `Phase B: scanned N daily summaries, found M candidates. Added A to lore. Skipped S.`
+
+### Phase C — Global promotion
+
+1. Re-pull current lore (`greprag lore list --format json`).
+
+2. For each entry, classify as **project-specific** or **project-agnostic** by these heuristics:
+   - **Project-specific** (skip): mentions a project-specific path (`packages/`, `migrations/`, `adr/`, project-specific module names), a project-specific table/column, an internal service name.
+   - **Project-agnostic** (candidate): mentions only universal concepts — `worktree`, `npm`, `git`, `node_modules`, `Claude Code`, `hook`, `~/.claude/`, `npm link`, `npm publish`, env var names that are obviously generic (`PATH`, `HOME`, `NODE_ENV`).
+
+3. For each agnostic candidate, before showing it, verify `~/.claude/docs/chip-spawn.md` and `packages/cli/skill/templates/chip-spawn.md` (in the current repo if it's the `greprag` repo, otherwise fetch from `npm show greprag` or skip) are in sync:
+   ```bash
+   diff ~/.claude/docs/chip-spawn.md <(npm exec --package=greprag -- cat ../skill/templates/chip-spawn.md 2>/dev/null || echo MISSING)
+   ```
+   If they DIFFER, stop Phase C and tell the operator:
+   > `chip-spawn.md drift detected between ~/.claude/docs/chip-spawn.md and the template. Resolve manually before promoting any lore.`
+
+4. Present each candidate:
+   ```
+   [<nodeId>] This lore mentions only universal concepts:
+     "<text>"
+   Promote to ~/.claude/docs/chip-spawn.md as a global rule? (y)es / (n)o / (e)dit
+   ```
+   - **yes** →
+     1. Append to BOTH `~/.claude/docs/chip-spawn.md` AND (when in the greprag repo) `packages/cli/skill/templates/chip-spawn.md`. The append goes under the numbered "Every chip prompt:" list as the next item, preserving HARD-RULE styling when appropriate.
+     2. Delete the per-project entry: `greprag lore delete <nodeId>`.
+     3. Confirm: `Promoted [<nodeId>] → global chip-spawn rule.`
+   - **edit** → ask for polished text, then yes-path with the new text.
+   - **no** → no-op, move to next entry.
+
+5. Phase summary: `Phase C: evaluated N. Promoted P to global. Skipped S.`
+
+## Report
+
+After all three phases, print one combined line:
+
+```
+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 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.
+
+## Notes
+
+- This skill is operator-driven. Each phase pauses for input. Don't batch decisions — that defeats the purpose.
+- For new lore added in Phase B, prefer the original sentence verbatim unless it's awkward. The compactor already polished it.
+- For Phase C promotions, prefer the original phrasing too — but rewrite if the lore embeds a project-specific noun that needs generalizing.

package/skill/templates/chip-spawn.md

@@ -0,0 +1,15 @@
+# Chip Spawn Method
+
+Chips are scoped: ship-code root-cause fix, or design discussion. Same blocks either way. Add `mode: interactive` to the prompt body when the chip should pause for human reply in the chip UI; default is autonomous.
+
+**Before composing**: `greprag lore query --scope chip-startup --project <chip-project> --limit 10 --format markdown` — if non-empty, paste at the top of the prompt as `**Project Lore (do not re-discover):**`. Saves the chip 10-20 startup turns of layout rediscovery.
+
+**Every chip prompt:**
+
+1. **Title** `Chip: <verb-phrase>`. Distinguishes chip-spawned sessions from IDE/human sessions in FleetView.
+2. **Worktree**: `git worktree add .claude/worktrees/<slug> -b chip/<slug>` then `cd` in.
+3. **Report**: `greprag send "<status>: <commit> on chip/<slug>" --to <handle>@greprag.com/<parent-session-id> --from-session <own-session-id> --artifact commit:<hash>` — substitute `<parent-session-id>` from your SessionStart hook ("Your greprag session id: `<8-hex>`").
+4. **Cleanup discipline (HARD RULE)**: chip prompts forbid `git clean`, `git reset --hard`, `git worktree remove`, `git checkout <other>`, raw `rm -rf` outside worktree's tracked files. Use `git rm` for tracked deletions.
+5. **Merge before testing globally (HARD RULE)**: chips never `npm link` from the worktree. A worktree-rooted global symlink dangles after `git worktree remove`, silently breaks the CLI everywhere, and chains destruction into shared `node_modules` (the 2026-05-25 wipe). To test a built CLI globally: merge to main first via `/commit`, then `npm i -g <pkg>` from main.
+
+A `greprag-hook pre-spawn-check` PreToolUse validator enforces title prefix + Block 1/2 presence at the `spawn_task` boundary — rule violations return `permissionDecision: deny` with a remediation message before the call goes through.