@c-d-cc/reap 0.17.0 → 0.17.1

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.
 
-### Update Criteria
+### Memory Pruning Policy — mandatory in reflect phase
 
-**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
+During `reap run completion --phase reflect`, the AI **must** perform cleanup:
 
-**Midterm** (update when context changes):
-- Flow of large ongoing tasks
-- Multi-generation plans
-- Directions agreed with the user
+**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".
 
-**Longterm** (update only when lessons emerge):
-- Design lessons worth repeating
-- Background behind architecture decisions
-- Lessons from project transitions
+**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".
 
-**Do NOT write**:
-- Code change details (environment handles this)
-- Test numbers (artifact handles this)
-- Principles already in genome (no duplication)
+**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 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,7 +319,8 @@ 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)
 
@@ -381,6 +401,41 @@ If stale, you can request a re-index with `curl -X POST "http://127.0.0.1:17224/
 - **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
 
 REAP supports multiple AI clients via the `agentClient` field in `.reap/config.yml`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c-d-cc/reap",
-  "version": "0.17.0",
+  "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)",