docs(evolve): clarify exit 2 and multi-session event attribution

[baleen37]

Summary

evolve 스킬에 --recent [N] 멀티세션 검토 모드를 추가합니다. 최근 N개 세션(기본 10)의 transcript를 모아 skill별로 개선 신호를 집계하되, 세션 호출 이후 본문이 이미 바뀐 skill(stale)은 본문 내용 해시 비교로 가려 제외합니다. 이미 진화한/구버전 skill을 옛 신호로 다시 건드리는 헛수고를 막습니다.

핵심: stale 판정은 버전 번호가 아니라 SKILL.md 본문 내용의 해시로 합니다 — 버전만 오르고 내용은 그대로인 경우는 stale이 아닙니다. transcript에 보존된 호출시점 본문과 현재 디스크 본문을 비교하므로 git/버전 의존이 없고 repo/캐시 skill에 동일하게 작동합니다.

Changes

• build-index.ts: --recent [N] 플래그 파싱(+--session/path 모순 거부), loadTurns가 skill 호출시점 주입 본문(isMeta) 캡처, 본문 정규화+sha256 해시 헬퍼, buildRecentIndex(세션 선정·skill별 events 귀속·stale 판정·dropped 처리), 진입점 분기
• bodyHash는 trim()으로 선행/후행 공백 정규화 — stripFrontmatter가 남기는 선행 개행 때문에 멀쩡한 skill이 false-positive stale로 떨어지던 버그 수정
• 단일세션 동작은 출력 형태·top-level 키 모두 불변 (하위 호환)
• SKILL.md: --recent CLI, 멀티세션 인덱스 스키마, stale 규칙 문서화
• 설계/구현 계획 문서 추가 (docs/superpowers/)

Tests

• BATS 22/22 통과 (기존 16 + --recent 파싱/모순 2 + skills[] 노출 1 + stale 3분기 3)
• version-agnostic 테스트: frontmatter만 다르고 본문 동일 → stale:false (내용 기반 판정 입증)
• 실전 검증: 11개 세션 누적 디렉터리에서 --recent 11 실행 → 현역 skill 8개 events 보존, 구버전 캐시(17.16.2)에서 호출된 ship/create-pr 2개만 stale-dropped, 호출시점≠현재 본문 해시 차이로 true-positive 입증

Summary by CodeRabbit

• New Features

  • Added --recent [N] flag for analyzing skills across multiple recent sessions (defaults to 10).
  • Implemented stale skill detection that marks skills when their content no longer matches previous invocations.
  • Added session attribution to events for disambiguation across sessions.

• Documentation

  • Updated skill documentation with new multi-session flag behavior and stale skill rules.

• Tests

  • Added test coverage for multi-session indexing and stale skill detection scenarios.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: d68e1b57-53f7-4115-aec3-f9dca094ec46

📥 Commits

Reviewing files that changed from the base of the PR and between 8cd9cc1 and bd8c863.

📒 Files selected for processing (6)

• docs/superpowers/plans/2026-05-31-evolve-recent-multisession.md
• docs/superpowers/specs/2026-05-31-evolve-recent-multisession-design.md
• plugins/me/skills/evolve/SKILL.md
• plugins/me/skills/evolve/scripts/build-index.ts
• tests/fixtures/evolve/skill-invocation-session.jsonl
• tests/me/evolve-build-index.bats

---

📝 Walkthrough

Walkthrough

This PR adds --recent [N] multi-session indexing to the /me:evolve skill development tool, enabling analysis across the most recent N transcript sessions while automatically filtering out skills that have become stale (content-mismatched with their invocation record).

Changes

Multi-session Skill Evolution

Layer / File(s)	Summary
Design & implementation plan docs/superpowers/specs/2026-05-31-evolve-recent-multisession-design.md, docs/superpowers/plans/2026-05-31-evolve-recent-multisession.md	Design specification defining stale skill judgment via normalized content hashing, CLI --recent [N] semantics (default 10, mutually exclusive with --session and transcript path), multi-session output shape with session-attributed events, and Phase 1/2 behavioral expectations. Implementation plan breaks the work into 8 concrete tasks covering types, transcript loading, hashing, CLI parsing, fixtures, and tests.
Data model & transcript processing plugins/me/skills/evolve/scripts/build-index.ts	New type definitions (RecentSkill, RecentIndex, SkillInvocation) model the multi-session output and track invocation metadata. Event gains optional session field for attribution. loadTurns is extended to detect and extract skill invocation metadata from injected meta user messages ("Base directory for this skill"), populating skillInvocations[]. Hash normalization utilities strip the injected base-dir line and YAML frontmatter to enable deterministic comparison.
Multi-session aggregation & CLI wiring plugins/me/skills/evolve/scripts/build-index.ts	buildRecentIndex aggregates events across multiple sessions, tags each with its session identifier, computes each skill's stale/dropped status by comparing current SKILL.md body hash against recorded invocation hashes, and returns a filtered summary excluding events for dropped skills. recentSessionPaths locates the N most-recent transcript JSONL files by mtime. CLI argument parsing adds --recent [N] (defaulting to 10) with conflict detection, and entry point conditionally dispatches to buildRecentIndex or legacy buildIndex.
Test fixture, validation & staleness tests tests/fixtures/evolve/skill-invocation-session.jsonl, tests/me/evolve-build-index.bats	New JSONL fixture contains a complete skill invocation session (tool call + meta context + result). New BATS tests validate CLI argument conflicts (rejecting --recent with --session or positional path), basic --recent integration (verifying mode:recent and skill presence), and three staleness outcomes: matching body (stale:false), changed body (stale:true, dropped:true, empty events), and missing body (stale:true).
User documentation plugins/me/skills/evolve/SKILL.md	Documented /me:evolve --recent [N] invocation syntax. Expanded Phase 0 instructions with exit-code expectations, multi-session output shape (keyed by skills[] with stale/dropped metadata), stale detection rules (body-content hash comparison, version/frontmatter ignored), and flag constraints. Added Phase 1 guidance for mode:recent consumption: analyze each skill's events, avoid proposing dropped skills, use session field for evidence attribution and deduplication.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• baleen37/bstack#667: Both PRs update /me:evolve CLI flag guidance in plugins/me/skills/evolve/SKILL.md around --session semantics and mutual exclusivity with the new --recent mode.
• baleen37/bstack#665: Main PR's evolve/scripts/build-index.ts changes (adding --recent multi-session indexing, new output shape, and staleness hashing) extend the retrieved PR's refactor of the same build-index.ts index/output schema.
• baleen37/bstack#664: The retrieved PR introduces the initial /me:evolve transcript indexer (build-index.ts), and the main PR extends that same indexer with --recent multi-session mode plus invocation hashing/stale filtering logic.

Poem

A rabbit hops through sessions old,

with hashes that reveal what's stale as told,

--recent brings fresh skill review,

stripped of frontmatter, honed and true,

now staleness shows, and stale ones fold! 🐰✨

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch lucky-voyage-lovelace

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}