greprag 5.6.2 → 5.8.1

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

@@ -1,14 +1,22 @@
 # 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.
+Hook-augmented spawn: the agent writes the minimal chip, the `pre-spawn-check` PreToolUse hook fills in the rest.
 
-**Before composing**: `greprag fact query --scope chip-startup --project <chip-project> --limit 10 --format markdown` — if non-empty, paste at the top of the prompt as `**Project Facts (do not re-discover):**`. Saves the chip 10-20 startup turns of layout rediscovery.
+**Agent writes:**
 
-**Every chip prompt:**
+1. **Title** `Chip: <verb-phrase>` (e.g. `Chip: Fix synthesis loop`). The `Chip: ` prefix is enforced.
+2. **Task body** — what the chip should do. Optional first line `mode: interactive` pauses for human reply in the chip UI; default is autonomous.
+3. **Optional** `cwd:` argument to land the chip in a different project root.
 
-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.
+**Hook auto-injects** (when the body contains neither `git worktree add` nor `greprag send` — "new-style"):
 
-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.
+- **Block 1** — escape-to-root (`main_root=$(git rev-parse --git-common-dir | xargs dirname)`) + `git worktree add .claude/worktrees/<slug>` + `cd` in. Slug derives from the title.
+- **Block 2** — `greprag send` report-back template with `<handle>` and `<parent-session-id>` substituted from the local identity cache and the parent's `session_id`. Cleanup discipline (no `git clean`, `git reset --hard`, `git worktree remove`, `git checkout <other>`, raw `rm -rf`) appended as a HARD RULE.
+
+**Pass-through:** if the prompt already includes `git worktree add` or `greprag send`, the hook leaves it alone — back-compat for hand-crafted prompts that want full control. Tier 1 placeholder substitution (`<parent-session-id>`, `<handle>`) still applies.
+
+**Before composing**: `greprag lore query --scope chip-startup --project <chip-project> --limit 10 --format markdown` — if non-empty, paste at the top of the task body as `**Project Lore (do not re-discover):**`. Saves 10-20 startup turns.
+
+**Example.** Agent calls `spawn_task` with `title: "Chip: Fix synthesis loop"` and `prompt: "Investigate src/foo.ts, fix the loop, ship it."`. The hook rewrites the prompt to: Block 1 (worktree setup with slug `fix-synthesis-loop`) → agent's body → Block 2 (greprag send with `travis@greprag.com/<parent-8hex>` substituted) + cleanup discipline.
+
+**Merge before testing globally (HARD RULE):** chips never `npm link` from the worktree. Worktree-rooted global symlinks dangle after `git worktree remove`, silently break the CLI everywhere, and chained the 2026-05-25 wipe. To test a built CLI globally: merge to main first via `/commit`, then `npm i -g <pkg>` from main.