docs(skill): scope inactive visibility to what a source can attest (#36)

`inactive` is populated only by Pi. The skill described it as a Pi
capability but never said what its absence means elsewhere, so an agent
querying a Claude Code session with `includeInactive: true` reads an empty
result as "nothing was abandoned here". Across 43 local Claude transcripts,
20 contained branches off the surviving path, so that reading is wrong far
more often than it is right.

Claude Code and Codex transcripts record no supersession event to attest
from; Kimi records one but the adapter drops those messages while indexing.
The added sentence covers all three without naming them, so it stays correct
if Kimi later marks retracted history instead of discarding it.
This commit is contained in:
Yuu
2026-08-05 00:15:48 +08:00
committed by GitHub
parent 2589384e68
commit 7c1b478e33
2 changed files with 5 additions and 2 deletions
+4 -1
View File
@@ -173,7 +173,10 @@ messages unless `includeMeta: true` is passed; `context()` and `trace()` preserv
the current causal chain and expose `is_meta` on returned rows.
Pi can preserve a branch that was tried and later superseded as
`visibility='inactive'`. Default helpers return only `visible` evidence. Pass
`visibility='inactive'`. Only Pi populates it: other sources either do not
record supersession in their transcripts or discard it while indexing, so an
empty inactive result never means nothing was abandoned -- only that this
source cannot say. Default helpers return only `visible` evidence. Pass
`includeInactive: true` to `search()`, `context()`, `trace()`, `thread()`,
`summaries()`, `raw()`, `fileHistory()`, or `failures()` only when the abandoned
path matters. Every returned message or evidence row is labeled with