feat(evolve): explain stale sessions with observed bodies

[baleen37]

Summary

• Add observed_bodies diagnostics for evolve recent/skill indexes
• Filter top-level events to the current normalized SKILL.md body hash
• Document that observed_bodies is diagnostic only and add focused BATS coverage

Tests

• bats tests/me/evolve-build-index.bats

Notes

• markdownlint on plugins/me/skills/evolve/SKILL.md still reports pre-existing line-length/fence issues

Summary by CodeRabbit

• New Features

  • Enhanced skill indexing to track multiple skill versions and their usage patterns across sessions.
  • Improved event attribution to skills based on the specific skill version used.
  • Updated staleness detection to consider the current skill body state.

• Documentation

  • Added planning documentation for skill indexing evolution.
  • Updated guidance on skill evidence validation and session analysis.

• Tests

  • Added test coverage for multi-version skill tracking and freshness behavior.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 9c6f0152-559d-4032-80f8-c121a44798a9

📥 Commits

Reviewing files that changed from the base of the PR and between 0204192 and 56288fd.

📒 Files selected for processing (4)

• docs/superpowers/plans/2026-06-01-evolve-hash-clusters.md
• plugins/me/skills/evolve/SKILL.md
• plugins/me/skills/evolve/scripts/build-index.ts
• tests/me/evolve-build-index.bats

---

📝 Walkthrough

Walkthrough

This PR implements a plan to make skill freshness and event filtering depend on normalized SKILL.md body hashes rather than event presence. It introduces ObservedBody tracking, refactors event accumulation per body hash, updates staleness logic, revises skill documentation, and adds comprehensive tests.

Changes

Hash-based skill body tracking

Layer / File(s)	Summary
Plan specification and architecture docs/superpowers/plans/2026-06-01-evolve-hash-clusters.md	Defines five tasks: add hash/version metadata to skill invocations, refactor recent-index accumulator to group by body hash, update event attribution and staleness logic, add SKILL.md guidance rules, and add new test cases for observed-body tracking.
Type contracts and hash/version parsing plugins/me/skills/evolve/scripts/build-index.ts	Introduces ObservedBody interface and updates RecentSkill to track observed_bodies. Updates SkillInvocation to store computed version and hash. Adds shortHash and skillVersion helper functions to extract metadata from base directory.
Event accumulation and per-hash attribution plugins/me/skills/evolve/scripts/build-index.ts	Refactors per-skill accumulator to map body hash to versions, seen sessions, and events. Rewrites event attribution: skill events target only matching observed hashes for that skill in a session; non-skill events fan across all observed hashes for invoked skills.
Output construction and staleness determination plugins/me/skills/evolve/scripts/build-index.ts	Computes current on-disk body hash; marks stale and dropped based on presence in observed-hash buckets (not event count). Filters top-level events by current hash. Builds observed_bodies entries with per-body current, versions, seen_in, and signals. Updates sorting to break ties by name.
Skill instruction updates plugins/me/skills/evolve/SKILL.md	Clarifies that observed_bodies are diagnostic-only and staleness depends solely on normalized body-hash matching. Revises Phase 1 multi-session guidance: restrict evidence to top-level events, disallow current:false, require kind:"skill" attribution, and disambiguate shared non-skill events using session field.
Tests for observed-body tracking tests/me/evolve-build-index.bats	Adds three test cases: (1) same-body-different-version tracking with event filtering; (2) cache-only behavior marking newest version as current; (3) non-stale status with zero events when current body exists on disk.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• baleen37/bstack#669: Modifies build-index.ts and SKILL.md to implement /me:evolve --recent session-based hashing and stale/dropped event attribution.
• baleen37/bstack#664: Earlier evolution of /me/skills/evolve implementation introducing the core transcript-based design.
• baleen37/bstack#670: Related changes to build-index.ts staleness logic around normalized SKILL.md body hashes and session handling.

Poem

🐰 Hashing skills with care so keen,
Bodies tracked in every scene,
Events flow where hashes match,
Staleness caught by hash dispatch,
Observed bodies, gleaming bright,
Skills now indexed just right! ✨

✨ 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 witty-summit-kepler

---

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.}