@c-d-cc/reap 0.16.6 → 0.17.1

package/dist/templates/agents/reap-evaluate.md

@@ -152,6 +152,27 @@ You evaluate the evolve agent's work, not your own. If asked to assess your own
    - Pattern consistency with existing codebase
    - No unintended side effects
 4. Verify artifact completeness (all stages filled, no placeholders)
+5. **Impact analysis via daemon (when `config.daemon: true`)** — for each
+   changed file in the diff, query the daemon's impact endpoint to
+   surface dependent files the builder may not have re-validated:
+
+   ```bash
+   curl -sf http://127.0.0.1:17224/health || exit 0   # skip if down
+   PROJECT_ID=$(curl -s http://127.0.0.1:17224/projects \
+     | jq -r --arg p "$PWD" '.data[] | select(.path==$p) | .id')
+   git diff --name-only HEAD~1..HEAD | while read f; do
+     curl -s "http://127.0.0.1:17224/projects/$PROJECT_ID/impact?file=$f"
+   done
+   ```
+
+   Cross-reference the daemon's `directFiles` / `indirectFiles` against
+   the validation artifact's test coverage. If indirect-impacted files
+   were not exercised by the test run, surface this as a concern.
+   Index staleness: check `lastIndexedCommit` from
+   `/projects/$PROJECT_ID/status` against `git rev-parse HEAD` —
+   trigger a re-index (`POST /projects/$PROJECT_ID/index`) if they
+   differ before relying on impact output. Daemon-down or
+   daemon-opted-out projects skip this step silently.
 
 ### Phase 3: Fitness Assessment
 

package/dist/templates/agents/reap-evolve.md

@@ -74,3 +74,52 @@ When REAP creates any file (artifacts, backlog, etc.) with template sections (`<
 - Do NOT create backlog during adapt phase.
 - Do NOT return to the parent agent before generation completion — handle user interactions within this session.
 - tests/ is a git submodule — commit inside submodule first if modified.
+
+## Code Intelligence (Daemon) — opt-in
+
+REAP optionally integrates with a local code-intelligence daemon
+(`localhost:17224`) that maintains a Tree-sitter symbol graph for the
+project. When `config.daemon: true` is set, REAP auto-indexes at key
+lifecycle moments (start, learning, implementation complete, completion
+commit) and the daemon protocol section appears in your subagent prompt
+and the SessionStart context. Use it to make exploration and impact
+analysis faster.
+
+### When to use the daemon
+
+- **Learning stage** — find existing implementations by name before
+  reading source. Symbol search (`GET /projects/{id}/symbols?q=`)
+  returns file:line positions you can `Read` directly. Faster than
+  Grep for symbol-shaped queries (function/class/type names).
+- **Implementation stage** — before editing a function, query its
+  callers (`GET /projects/{id}/symbols/{id}/callers`) to understand
+  the change's blast radius. Helps avoid breaking out-of-sight call
+  sites.
+- **Validation stage** — for each changed file in your diff, query
+  `GET /projects/{id}/impact?file=<path>` to enumerate dependent
+  files. Cross-reference with your validation evidence.
+
+### Protocol
+
+Always probe first — daemon may be down or the user may not have
+opted in:
+
+```bash
+curl -sf http://127.0.0.1:17224/health || true   # silent skip if down
+```
+
+If healthy, look up the current project's ID once, then reuse it:
+
+```bash
+PROJECT_ID=$(curl -s http://127.0.0.1:17224/projects \
+  | jq -r --arg p "$PWD" '.data[] | select(.path==$p) | .id')
+```
+
+See `~/.reap/reap-guide.md` § Code Intelligence (Daemon) for the full
+query reference and staleness check protocol.
+
+### Fallback behaviour
+
+- Daemon down or `config.daemon !== true` → continue with normal
+  Read/Grep/Glob tools. The daemon is an accelerator, not a
+  requirement. Never block the lifecycle on a daemon problem.

package/dist/templates/migration/v0.17.1.md

@@ -0,0 +1,56 @@
+# v0.17.1 — Vision Memory Content-Type Reorganization
+
+## What changed
+
+Up through v0.17.0, REAP's vision memory tiers (`.reap/vision/memory/{shortterm,midterm,longterm}.md`) were classified by **lifespan** — "how long will this live?" That heuristic forced the AI to predict the future and led to repeated misclassification + bloat.
+
+Starting with v0.17.1, tiers are classified by **content-type** — "what is this content for?" The decision is now mechanical and bloat-resistant.
+
+| File | Role (new) | 1-line decision rule |
+|------|------------|----------------------|
+| `shortterm.md` | **Session handoff** — immediate context for the next session | "Is this needed right now?" |
+| `midterm.md`   | **Ongoing tracks** — multi-generation work in progress | "Is this an incomplete large track?" |
+| `longterm.md`  | **Design lessons** — recurring lessons worth re-reading | "Does this lesson prevent the next generation from making the same mistake?" |
+
+A mandatory **reflect-phase pruning policy** was also added: shortterm is replaced (not appended) every generation, midterm sections get deleted on track completion (key decisions promoted to longterm), and longterm gets periodic dedup vs genome.
+
+See `~/.reap/reap-guide.md` § Memory and `.reap/genome/evolution.md` § Vision 활용 원칙 for the full rules.
+
+## Required actions for the AI agent
+
+Apply these in order. Do **not** treat this as a code change — it is an artifact reorganization. No source code is touched.
+
+1. **Read** the current state of all three memory files:
+   - `.reap/vision/memory/shortterm.md`
+   - `.reap/vision/memory/midterm.md`
+   - `.reap/vision/memory/longterm.md`
+
+2. **Reclassify each entry** using the new decision tree (apply top-to-bottom):
+   ```
+   1. Is this needed in the next session immediately?     → shortterm.md
+   2. Is this an ongoing, incomplete track or plan?       → midterm.md
+   3. Is this a finished design lesson worth preserving?  → longterm.md
+   4. Finished, no special lesson?                        → DELETE (lineage + git history preserve it)
+   ```
+
+3. **Move misclassified entries** to the correct tier. Typical patterns to fix:
+   - "Will be useful eventually" / "background context" sitting in `longterm.md` but not driving any current behavior → delete
+   - Completed track summaries in `midterm.md` without a next step → delete (promote one-line lessons to `longterm.md` only if they prevent future mistakes)
+   - Stale session handoffs from earlier generations in `shortterm.md` → delete (shortterm is **replaced** every generation, not appended)
+
+4. **Apply the size-bloat heuristics**:
+   - `longterm.md` should stay under ~30–50 lines. Over that = pruning was skipped.
+   - `midterm.md` should stay under ~50–70 lines. Over that = completed tracks weren't removed.
+   - `shortterm.md` should contain only the most recent 1–2 generations' handoff.
+
+5. **Do NOT add new entries** during this migration. Goal is reorganization of what already exists. New lessons land in the next generation's normal reflect.
+
+6. **Verify** the new classification by re-applying the decision tree to each entry one more time. If you can't justify keeping an entry under any of branches 1–3, delete it.
+
+7. **Run** `reap update --mark-migrated` to record completion. This sets `lastMigratedVersion: 0.17.1` in `.reap/config.yml` so this instruction stops surfacing in subsequent SessionStart loads and `reap update` runs.
+
+## Reference
+
+- `~/.reap/reap-guide.md` § Memory — the canonical 3-tier definition + decision tree + pruning policy
+- `.reap/genome/evolution.md` § Vision 활용 원칙 — same content in Korean (when project language is Korean)
+- REAP gen-070 lineage entry — the generation that established this convention, with worked examples of compression (255 → 49 lines in this very project's longterm)

package/dist/templates/reap-guide.md

@@ -22,53 +22,72 @@ REAP consists of four interconnected layers:
 
 ## Memory
 
-Memory is a free-form recording system under `.reap/vision/memory/` where AI can persist context across sessions and generations. Unlike Genome (which has modification constraints) or Lineage (which gets compressed), Memory is always accessible and freely writable.
+Memory is a free-form recording system under `.reap/vision/memory/` where AI can persist project context across sessions and generations. Unlike Genome (which has modification constraints) or Lineage (which gets compressed), Memory is always accessible and freely writable.
 
-### 3-Tier Structure
+### 3-Tier Structure — content-type based
 
-| Tier | File | Lifespan | Purpose |
-|------|------|----------|---------|
-| **Longterm** | `longterm.md` | Project lifetime | Lessons that bear repeating, recurring patterns, decision rationale, architecture choice reasons |
-| **Midterm** | `midterm.md` | Multiple generations | Ongoing large task context, multi-generation plans, progress tracking |
-| **Shortterm** | `shortterm.md` | 1-2 sessions | Next session handoff, immediate context to pass forward, unfinished discussions |
+Tiers are classified by **what the content is for** (content-type), NOT by how long it will live (lifespan). Lifespan requires predicting the future, which the AI can't reliably do — that judgment burden has historically led to misclassification and bloat.
 
-### Rules
+| File | Role | 1-line decision rule |
+|------|------|----------------------|
+| `shortterm.md` | **Session handoff** — immediate context to pass to the next session | "Is this needed right now?" |
+| `midterm.md` | **Ongoing tracks** — multi-generation work in progress | "Is this an incomplete large track?" |
+| `longterm.md` | **Design lessons** — recurring lessons worth re-reading | "Does this lesson prevent the next generation from making the same mistake?" |
 
-- **Free access**: Read and write at any time — no permission needed, no phase restriction
-- **AI discretion**: Content and timing are the AI's judgment. No mandatory updates
-- **Tier fitness**: Place content in the tier matching its expected lifespan. Promote/demote between tiers as relevance changes
-- **Keep concise**: Memory should be scannable, not exhaustive. Prefer bullet points over paragraphs
-- **Empty is normal**: Memory files may be empty — this is a valid state
-- **Git-committed**: Memory is committed with the project, accessible to any AI agent
+### Memory Classification Decision Tree (mandatory for AI)
 
-### When to Update
+When you have something to write to memory, apply top-to-bottom:
 
-- **Reflect phase**: Natural moment to update memory (prompted but not forced)
-- **Any time**: Memory can be updated during any stage if useful context arises
-- **Shortterm cleanup**: Clear shortterm items that have been acted on
+```
+1. Is this needed in the next session immediately?
+   → Yes: shortterm.md
+
+2. Is this an ongoing, incomplete track or plan?
+   → Yes: midterm.md
+
+3. Is this a finished design lesson worth preserving?
+   → Yes: longterm.md
+
+4. Is this finished with no special lesson?
+   → Do NOT record (memory keeps no junk; lineage/git history preserves it)
+```
+
+**Important**: Do not stash "might-be-useful" notes in longterm. If it disappears, it's still in lineage and git history.
+
+### Memory Pruning Policy — mandatory in reflect phase
 
-### Update Criteria
+During `reap run completion --phase reflect`, the AI **must** perform cleanup:
 
-**Shortterm** (update every generation — mandatory):
-- Summary of what was done in this generation
-- Context to hand off to the next session
-- Undecided matters, ongoing discussions
-- Current backlog state snapshot
+**Shortterm — every generation, mandatory**:
+- Delete previous handoff items that are "already acted on"
+- **Replace** (overwrite) with the new generation's handoff. No accumulation.
+- Result: shortterm.md stays within "last 1~2 generations of content".
 
-**Midterm** (update when context changes):
-- Flow of large ongoing tasks
-- Multi-generation plans
-- Directions agreed with the user
+**Midterm — at track completion**:
+- When a track completes, **promote** its key decisions to longterm and **delete** the section from midterm
+- Decision rule: "Does this track have a next step?" — No → delete
+- Result: midterm.md stays within "tracks that are alive right now".
 
-**Longterm** (update only when lessons emerge):
-- Design lessons worth repeating
-- Background behind architecture decisions
-- Lessons from project transitions
+**Longterm — periodic (every ~10 generations or when bloat is detected in reflect)**:
+- If a section is already documented in genome (application.md / evolution.md), it's a **duplicate → delete**
+- If early project transition context (e.g., v0.X → v0.Y differences) is no longer a behavioral guide → **delete**
+- Decision rule: "Without this lesson, would the next agent make the same mistake?" — No → delete
+- Result: longterm.md stays within "lessons that still drive behavior today".
 
-**Do NOT write**:
-- Code change details (environment handles this)
-- Test numbers (artifact handles this)
-- Principles already in genome (no duplication)
+### Do NOT write to memory
+
+- Code change details (`environment/summary.md` handles this)
+- Test numbers, run logs (artifact handles this)
+- Principles already stated in genome (no duplication)
+- Generation-specific debug logs (lineage preserves them; don't crowd memory)
+
+### Memory Usage — freedom with responsibility
+
+- **Free access**: Read and write at any time — no permission needed
+- **Cross-tier promotion/demotion is encouraged**: a shortterm note that evolves into a track moves to midterm; a midterm track that completes leaves only its lesson in longterm
+- **Architecture changes must propagate**: when adding new features/structure, update evolution.md / application.md / memory together
+- **Bloat is a failure signal**: if longterm exceeds ~30~50 lines or midterm exceeds ~50~70 lines, pruning was skipped. Clean up in the next reflect.
+- **Empty is normal**: any memory file may be empty — that is a valid state
 
 ## .reap/ Structure
 
@@ -300,8 +319,122 @@ All REAP interactions go through `/reap.*` slash commands. These are the primary
 - `reap make backlog --type <type> --title <title> [--body <body>] [--priority <priority>]` — Create backlog item (type: genome-change, environment-change, task)
 - `reap make hook --event <event> --name <name> [--type md|sh] [--condition <condition>] [--order <order>]` — Create hook file with correct naming and frontmatter
 - `reap cruise <count>` — Set cruise mode (pre-approve N generations for autonomous execution)
-- `reap update` — Update project structure to match current REAP version (v0.15 migrate, v0.16 sync)
+- `reap update` — Update project structure to match current REAP version (v0.15 migrate, v0.16 sync). When the project's `lastMigratedVersion` lags behind the installed package, pending per-version migration notes are surfaced in `context.pendingMigrations` (see § Migration Instruction Layer).
+- `reap update --mark-migrated` — Mark this project as having applied all pending migration notes up to the current package version (gen-071 migration layer).
 - `reap dump-state [--stdout] [--silent]` — Dump dynamic REAP context to `.reap/.session-state.md` (used by OpenCode plugin; useful for any external tool that needs current generation state)
+- `reap daemon status|stop|index|query` — Inspect or control the local code-intelligence daemon (see § Code Intelligence below)
+
+## Code Intelligence (Daemon)
+
+REAP ships with a local code-intelligence daemon (`@c-d-cc/reap-daemon`) that runs on `localhost:17224`. It maintains a Tree-sitter–backed symbol graph (functions, classes, types, calls, imports) persisted to SQLite, supports incremental updates, and exposes a small HTTP API for symbol search, caller/callee lookup, and change-impact analysis.
+
+### Opt-in
+
+Daemon integration is opt-in via `.reap/config.yml`:
+
+```yaml
+daemon: true
+```
+
+When opted in, REAP lifecycle commands (`start`, `learning`, `implementation complete`, `completion commit`) automatically register the project and trigger indexing. When omitted or `false`, daemon-related CLI behaviour is a no-op — byte-identical to projects that have never enabled it.
+
+### Auto-trigger points
+
+| Lifecycle moment | What runs |
+|---|---|
+| `reap run start` (generation created) | `ensureRegistered` + full `triggerIndexing` |
+| `reap run learning` (work phase) | `ensureRegistered` + `triggerIndexing` (keeps graph fresh before exploration) |
+| `reap run implementation` (complete phase) | `triggerIndexing` (so validation/evaluator see the just-written code) |
+| `reap run completion` (commit phase, post-archive) | `triggerIndexing` (graph reflects the committed state for the next generation) |
+
+All four call sites silent-fail when the daemon process is unreachable. The CLI lifecycle is never blocked by a daemon problem.
+
+### Querying the daemon
+
+Always verify the daemon is alive before querying — otherwise skip silently:
+
+```bash
+curl -sf http://127.0.0.1:17224/health || echo "daemon down"
+```
+
+Look up the current project's ID (set `CWD` to your project path):
+
+```bash
+PROJECT_ID=$(curl -s http://127.0.0.1:17224/projects \
+  | jq -r --arg p "$CWD" '.data[] | select(.path==$p) | .id')
+```
+
+Common queries:
+
+```bash
+# Symbol search by name (function, class, type, etc.)
+curl -s "http://127.0.0.1:17224/projects/$PROJECT_ID/symbols?q=consumeBacklog"
+
+# Callers of a specific symbol
+curl -s "http://127.0.0.1:17224/projects/$PROJECT_ID/symbols/<symbol-id>/callers"
+
+# Callees of a specific symbol
+curl -s "http://127.0.0.1:17224/projects/$PROJECT_ID/symbols/<symbol-id>/callees"
+
+# Impact (blast radius) of a file change
+curl -s "http://127.0.0.1:17224/projects/$PROJECT_ID/impact?file=src/core/lifecycle.ts"
+
+# Project status — includes lastIndexedAt and lastIndexedCommit (gen-068)
+curl -s "http://127.0.0.1:17224/projects/$PROJECT_ID/status"
+```
+
+### Index staleness
+
+`/projects/:id/status` returns `lastIndexedCommit` — the `git rev-parse HEAD` at the moment of the most recent successful indexing. To check whether the index is stale before a query:
+
+```bash
+INDEXED=$(curl -s "http://127.0.0.1:17224/projects/$PROJECT_ID/status" | jq -r '.data.lastIndexedCommit // "none"')
+HEAD=$(git rev-parse HEAD)
+[ "$INDEXED" = "$HEAD" ] && echo "fresh" || echo "stale — trigger reindex"
+```
+
+If stale, you can request a re-index with `curl -X POST "http://127.0.0.1:17224/projects/$PROJECT_ID/index"`. The lifecycle auto-triggers above usually keep the index fresh; manual re-index is only needed for between-stage tweaks or out-of-band edits.
+
+### When to use daemon vs filesystem search
+
+- **Daemon-first**: symbol definition lookup, caller/callee traversal, multi-file impact analysis.
+- **Filesystem-first (Grep/Glob)**: literal string search, comment search, files with no parser support, daemon down.
+- The two are complementary — symbol-graph queries return file:line positions you can `Read` immediately.
+
+## Migration Instruction Layer
+
+When REAP itself evolves (e.g. memory tier semantics change in v0.17.1), existing user projects need to reorganize their artifacts to match the new conventions. The migration instruction layer (gen-071) closes this gap.
+
+### How it works
+
+1. Each REAP release that requires user-side reorganization ships a `vX.Y.Z.md` note at `src/templates/migration/` (bundled to `dist/templates/migration/` on install).
+2. `config.yml` carries `lastMigratedVersion: "X.Y.Z"` — the most recent REAP version this project has acknowledged.
+3. On every `reap update` and on every SessionStart (`reap load-context`), REAP compares `lastMigratedVersion` against the installed package version. Any `vX.Y.Z.md` file whose version falls in the gap (`lastMigratedVersion < v <= packageVersion`) is surfaced to the agent.
+4. After the agent applies the listed reorganizations, it runs `reap update --mark-migrated`. This sets `lastMigratedVersion` to the current package version and the notes stop surfacing.
+
+### Where pending migrations appear
+
+- `reap update` output: `context.pendingMigrations: [{ version, instructions }, ...]` + a summary line in `message`.
+- SessionStart context: a `# Pending Migrations` section in the additionalContext (Claude Code hookSpecificOutput / OpenCode instructions).
+- `.reap/.session-state.md` sync dump (written by lifecycle commands): same section, byte-identical.
+
+When `lastMigratedVersion >= packageVersion`, no section is added and output is byte-identical to pre-gen-071 behavior.
+
+### Agent behavior
+
+When you see a `# Pending Migrations` section:
+
+1. Read each `## vX.Y.Z` subsection in order.
+2. Apply the listed actions to the project's artifacts (memory, backlog, env, etc. — never to source code unless the note explicitly says so).
+3. Once **all** pending migrations are applied, run `reap update --mark-migrated`. Do not call this halfway through — it marks every gap version as done.
+4. Migration is best-effort and non-blocking. If you cannot apply a step (missing file, ambiguous instruction), record the partial state in the next reflect and skip `--mark-migrated` so the note re-surfaces in the next session.
+
+### Authoring migration notes (REAP maintainers)
+
+- File: `src/templates/migration/vX.Y.Z.md` (must match `^v\d+\.\d+\.\d+\.md$`).
+- Audience: an AI agent that has *not* yet read the new REAP version's guide. Be explicit about what to read, what to change, and how to verify.
+- Scope: artifact reorganization only by default. Source-code migrations belong in a separate generation, not in a migration note.
+- Build is automatic — `scripts/build.sh` copies `src/templates/` wholesale to `dist/templates/`. No additional sync step.
 
 ## AI Client Support
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c-d-cc/reap",
-  "version": "0.16.6",
+  "version": "0.17.1",
   "description": "Recursive Evolutionary Autonomous Pipeline — AI and humans evolve software across generations",
   "license": "MIT",
   "author": "HyeonIL Choi <hichoi@c-d.cc> (C to D)",