sphica 0.6.49 → 0.6.50

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "sphica",
3
- "version": "0.6.49",
3
+ "version": "0.6.50",
4
4
  "description": "Records Claude Code and Codex sessions on your machine and keeps past implementation and decisions, with their sources, for your agent to find.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -3,7 +3,7 @@ name: forget
3
3
  description: Removes sources the owner chooses from Sphica (a message, a pull request item, a file excerpt), with their search index entries and the bytes left in the database file, and judges the records that cited them again. The owner confirms in a dialog before anything is removed. Use only when the user explicitly asks to forget or delete something Sphica captured.
4
4
  argument-hint: "<what to forget>"
5
5
  disable-model-invocation: true
6
- allowed-tools: AskUserQuestion, mcp__plugin_sphica_sphica__search, mcp__plugin_sphica_sphica__read, mcp__plugin_sphica_record__forget_preview, mcp__plugin_sphica_record__forget_apply, mcp__plugin_sphica_sphica__status
6
+ allowed-tools: AskUserQuestion, mcp__plugin_sphica_sphica__search, mcp__plugin_sphica_sphica__read, mcp__plugin_sphica_record__forget_preview, mcp__plugin_sphica_record__forget_apply, mcp__plugin_sphica_record__record_more, mcp__plugin_sphica_sphica__status
7
7
  ---
8
8
 
9
9
  # forget — remove what should not have been kept
@@ -32,10 +32,15 @@ Pass the repository root as `cwd` to every tool.
32
32
  **Never repeat a secret in your replies**: describe each source by its ref, kind, and where it is (`s12`, a message of 2026-09-20 in
33
33
  this project, `file:config.md` lines 1-3)
34
34
  2. **Confirm the list** with the owner (AskUserQuestion in Claude Code; in Codex, ask in the conversation and wait). Forget only what the owner picks
35
- 3. **Preview**: `forget_preview` with the refs. It lists what will be removed, which records lose citations, and which leave active. Show it to the owner
36
- 4. **Apply**: `forget_apply` with the same refs. The host shows the owner a dialog asking to type the number of sources; nothing is removed
35
+ 3. **Preview**: `forget_preview` with the refs. It lists every source that will be removed, how many records are affected and what becomes
36
+ of them (leave active, become active, change otherwise, keep their state), and then the records, those leaving active first. When the
37
+ reply ends with `call record_more with cursor: "..."`, read the rest of the records with `record_more` until a reply names no cursor.
38
+ Show the owner the sources, the counts, and the records that leave active
39
+ 4. **Apply**: `forget_apply` with the same refs. The host shows the owner a dialog with every source and the counts (and as many of the
40
+ records as fit), asking to type the number of sources; nothing is removed
37
41
  without that answer. Answering it is the owner's act: never ask the owner to tell you the number so you can answer for them
38
- 5. **Report** what `forget_apply` returned, as it says it
42
+ 5. **Report** what `forget_apply` returned, as it says it: what was forgotten and whether the deleted text was cleared come first, and
43
+ `record_more` reads on when the records did not fit
39
44
 
40
45
  When `forget_apply` says the host cannot ask directly, the host has no confirmation dialog (some Codex versions): tell the owner to run
41
46
  `/sphica:forget` in Claude Code. When it says clearing did not finish (usually another session reading the database): run `forget_apply` with
@@ -3,7 +3,7 @@ name: glean
3
3
  description: Adds evidence and corrections to existing Sphica records, or keeps something the owner remembers, only from sources the owner points to (an issue or pull request, a file in the repository, the owner's own words now). Asks the owner for the source before saving anything. Use only when the user explicitly asks.
4
4
  argument-hint: "<what to add or correct>"
5
5
  disable-model-invocation: true
6
- allowed-tools: AskUserQuestion, mcp__plugin_sphica_record__glean_begin, mcp__plugin_sphica_record__glean_fetch, mcp__plugin_sphica_record__record_context, mcp__plugin_sphica_record__record_check, mcp__plugin_sphica_record__record_save, mcp__plugin_sphica_sphica__search, mcp__plugin_sphica_sphica__read, mcp__plugin_sphica_sphica__status
6
+ allowed-tools: AskUserQuestion, mcp__plugin_sphica_record__glean_begin, mcp__plugin_sphica_record__glean_fetch, mcp__plugin_sphica_record__record_context, mcp__plugin_sphica_record__record_check, mcp__plugin_sphica_record__record_save, mcp__plugin_sphica_record__record_more, mcp__plugin_sphica_sphica__search, mcp__plugin_sphica_sphica__read, mcp__plugin_sphica_sphica__status
7
7
  ---
8
8
 
9
9
  # glean — add what was found later, with its source
@@ -38,21 +38,25 @@ owner says there is no source, save it unsourced and say so.
38
38
 
39
39
  ## Flow
40
40
 
41
- Everything goes through Sphica's `record` MCP server (`glean_begin`, `glean_fetch`, `record_context`, `record_check`, `record_save`) and the
41
+ Everything goes through Sphica's `record` MCP server (`glean_begin`, `glean_fetch`, `record_context`, `record_check`, `record_save`,
42
+ `record_more`) and the
42
43
  read tools `search` and `read`. Pass the repository root as `cwd` to every tool.
43
44
 
44
45
  1. **Find the records** the target concerns with `search`, and `read` each. Note each record's key and `revision` (read prints it)
45
46
  2. **Ask for the source** (above). Have the owner state it in this session: the owner's words are captured and become citable
46
47
  3. **Begin**: `glean_begin` with this session (`${CLAUDE_SESSION_ID}` in Claude Code; in Codex, `CODEX_THREAD_ID` from your shell). It returns a `run`
47
- 4. **Bring in the source**: for a GitHub issue or pull request URL of this repository, `glean_fetch` with the run and URL; it keeps the text as sources
48
- and lists their refs. For a file, cite it in the record (`file`); Sphica reads it from git itself. For anything else (meeting notes, chat), cite
48
+ 4. **Bring in the source**: for a GitHub issue or pull request URL of this repository, `glean_fetch` with the run and URL; it keeps the text as sources,
49
+ says how many, and lists their refs with who wrote each (read a source with `read s<id>`; when its reply ends with `call record_more with cursor: "..."`, the rest of the list is read with
50
+ `record_more`; everything is already kept, so never fetch again for it). For a file, cite it in the record (`file`); Sphica reads it from git itself. For anything else (meeting notes, chat), cite
49
51
  the owner's message that quotes it
50
- 5. **Read**: `record_context` with the run: the owner's messages in this session with their refs. When a page ends with
51
- `call record_context with after: "s<N>"`, call it again with that `after`
52
+ 5. **Read**: `record_context` with the run: the owner's messages in this session with their refs. When a page's last line says
53
+ `call record_context with after: "..."`, call it again with that `after`, exactly as written, until a page names none
52
54
  6. **Check**: `record_check` with the run and the record below. It runs the save in a transaction that rolls back, so it refuses what the
53
- save would refuse and lists what would change (`would be active`, `would: <change>`) without writing it. Fix errors and check again. A
55
+ save would refuse and lists what would change (`would be active`, `would: <change>`) without writing it, the verdict and the counts first
56
+ (a reply that ends with `call record_more with cursor: "..."` goes on with `record_more`). Fix errors and check again. A
54
57
  note to ask the owner for a source means step 2 is not done
55
- 7. **Save**: `record_save`. **Report** what changed, copying save's lines
58
+ 7. **Save**: `record_save`. A reply that starts with `✗` saved nothing: fix the record, check it, and save with the same run.
59
+ **Report** what changed, copying save's lines (all of them: read on with `record_more` when the reply names a cursor)
56
60
 
57
61
  ## The record
58
62
 
@@ -4,7 +4,7 @@ description: Reads one GitHub pull request of the current repository (its body,
4
4
  argument-hint: "<PR number>"
5
5
  disable-model-invocation: true
6
6
  context: fork
7
- allowed-tools: mcp__plugin_sphica_record__harvest_begin, mcp__plugin_sphica_record__record_context, mcp__plugin_sphica_record__record_check, mcp__plugin_sphica_record__record_save, mcp__plugin_sphica_sphica__search, mcp__plugin_sphica_sphica__read, mcp__plugin_sphica_sphica__status
7
+ allowed-tools: mcp__plugin_sphica_record__harvest_begin, mcp__plugin_sphica_record__record_context, mcp__plugin_sphica_record__record_check, mcp__plugin_sphica_record__record_save, mcp__plugin_sphica_record__record_more, mcp__plugin_sphica_sphica__search, mcp__plugin_sphica_sphica__read, mcp__plugin_sphica_sphica__status
8
8
  ---
9
9
 
10
10
  # harvest — keep what a pull request decided and implemented
@@ -26,7 +26,7 @@ each record quoting the words it came from.** No template is assumed; decide fro
26
26
 
27
27
  ## Flow
28
28
 
29
- Everything goes through Sphica's `record` MCP server (`harvest_begin`, `record_context`, `record_check`, `record_save`). Pass the repository root
29
+ Everything goes through Sphica's `record` MCP server (`harvest_begin`, `record_context`, `record_check`, `record_save`, `record_more`). Pass the repository root
30
30
  as `cwd` to every tool.
31
31
 
32
32
  1. **Pick the pull request**: the number in the target. Without one, do nothing and reply that harvest needs a pull request number
@@ -35,14 +35,17 @@ as `cwd` to every tool.
35
35
  3. **Read**: `record_context` with the run. Each source is printed as `## s<N> <kind> <artifact> by <login> (<association>) <time>` followed by
36
36
  its text (`, the owner` follows the association for the owner's own account), then the project's live records. `(harvested before)` marks
37
37
  sources an earlier harvest already looked at: what they decided may already be saved, so search before recording it again. Read all of it before writing:
38
- when a page ends with `call record_context with after: "s<N>"`, call it again with that `after`, until the last page
38
+ when a page's last line says `call record_context with after: "..."`, call it again with that `after`, exactly as written, until a page names none
39
+ (a source too long for a page says where `read` goes on)
39
40
  4. **Check**: `record_check` with the run and the record as `record`. The shape and fields are trace's ([../trace/SKILL.md](../trace/SKILL.md),
40
41
  "The record"), with `work` left out. Keys are saved as `harvest:<number>/<key>`. As in trace, check runs the save in a transaction that
41
- rolls back and says what would become of each record (`would be active`, ...). Fix and check again until there are no errors.
42
+ rolls back and says what would become of each record (`would be active`, ...), the verdict and the counts first; when a reply ends with
43
+ `call record_more with cursor: "..."`, read the rest with `record_more`. Fix and check again until there are no errors.
42
44
  A file the pull request touched may have moved since: on a warning that a path is not in the working tree, give the commit that holds it,
43
45
  or anchor where the code is now
44
- 5. **Save**: `record_save` with the same run and record
45
- 6. **Report** to the owner what was saved, copying save's lines
46
+ 5. **Save**: `record_save` with the same run and record. A reply that starts with `✗` saved nothing: fix the record, check it, and save
47
+ with the same run
48
+ 6. **Report** to the owner what was saved, copying save's lines (all of them: read on with `record_more` when the reply names a cursor)
46
49
 
47
50
  ## Who adopts
48
51
 
@@ -2,7 +2,7 @@
2
2
  name: trace
3
3
  description: Extracts what a coding session decided and implemented (decisions and rejected options, constraints, implementations, findings, dead ends, open questions) into records whose every claim quotes the captured conversation, so a later session can find them. With "pending", lists this project's sessions not traced yet. Use when the user asks, or on your own when Sphica's session-start notice says earlier sessions wait to be traced, after the user's request is done.
4
4
  argument-hint: "[pending]"
5
- allowed-tools: AskUserQuestion, mcp__plugin_sphica_record__trace_pending, mcp__plugin_sphica_record__trace_begin, mcp__plugin_sphica_record__record_context, mcp__plugin_sphica_record__record_check, mcp__plugin_sphica_record__record_save, mcp__plugin_sphica_sphica__search, mcp__plugin_sphica_sphica__read, mcp__plugin_sphica_sphica__status, mcp__plugin_sphica_sphica__fields
5
+ allowed-tools: AskUserQuestion, mcp__plugin_sphica_record__trace_pending, mcp__plugin_sphica_record__trace_begin, mcp__plugin_sphica_record__record_context, mcp__plugin_sphica_record__record_check, mcp__plugin_sphica_record__record_save, mcp__plugin_sphica_record__record_more, mcp__plugin_sphica_sphica__search, mcp__plugin_sphica_sphica__read, mcp__plugin_sphica_sphica__status, mcp__plugin_sphica_sphica__fields
6
6
  ---
7
7
 
8
8
  # trace — keep what a session decided and implemented
@@ -28,7 +28,7 @@ replacing the owner's).
28
28
  ## Flow
29
29
 
30
30
  Everything goes through Sphica's `record` MCP server (its tools are `trace_pending`, `trace_begin`, `record_context`, `record_check`,
31
- `record_save`). Pass the repository root as `cwd` to every tool.
31
+ `record_save`, `record_more`). Pass the repository root as `cwd` to every tool.
32
32
 
33
33
  1. **Pick the session.** Without a target, it is this session: its id is `${CLAUDE_SESSION_ID}` in Claude Code; in Codex, read `CODEX_THREAD_ID`
34
34
  from your shell environment. With `pending`, call `trace_pending`, show the owner the list, and ask which to trace (AskUserQuestion in
@@ -37,17 +37,22 @@ Everything goes through Sphica's `record` MCP server (its tools are `trace_pendi
37
37
  2. **Begin**: `trace_begin` with that `session`. It returns a `run` id bound to that session and this project; the record never names them
38
38
  3. **Read**: `record_context` with the run. It prints each captured message as `## s<N> owner|assistant <turn> <time>` followed by its text,
39
39
  the edits observed, and the project's live records. `(traced before)` marks messages an earlier trace already looked at.
40
- A long session comes in pages: when a page ends with `call record_context with after: "s<N>"`, call it again with that `after`, until
41
- the last page (the one with the live records). Saving marks as looked at only the messages you were shown and those you quote; the
42
- rest stay pending.
40
+ It comes in pages: when a page's last line says `call record_context with after: "..."`, call it again with that `after`, exactly as written
41
+ (`s<N>` while messages follow, then `t<id>.<line>` while the edits, fields, and live records go on), until a page names no `after`.
42
+ A message too long for a page ends with `(cut here; read s<N>@<byte> for the rest)`: read on with `read` when what it says matters.
43
+ Saving marks as looked at only the messages you were shown and those you quote; the rest stay pending.
43
44
  Use `search` and `read` to look at older records this session may replace
44
45
  4. **Check**: `record_check` with the run and the record below as `record`. It runs the save in a transaction that rolls back, so nothing is
45
46
  written: it refuses what the save would refuse, and says what would become of each record (`would be active`, `would stay a candidate` with
46
- the reason, `would be superseded`, `would be quarantined`). Errors refuse the save; fix and check again. Warnings say what will be
47
+ the reason, `would be superseded`, `would be quarantined`). Its first lines are the verdict and the counts. When a reply ends with
48
+ `call record_more with cursor: "..."`, the rest of its lines are read with `record_more` and that cursor, until a reply names none
49
+ (the same goes for `record_save`; nothing is checked or saved again by reading on). Errors refuse the save; fix and check again. Warnings say what will be
47
50
  left out, quarantined, or kept as a candidate, and why. An anchor warning (a path not in the working tree, with near paths; a directory; a
48
51
  symbol not in the file) means fix the anchor and check again; keep it only when you know it is right
49
- 5. **Save**: `record_save` with the same run and record. A run saves once
50
- 6. **Report** to the owner what was saved, copying save's lines (active, candidate with the reason, quarantined, superseded)
52
+ 5. **Save**: `record_save` with the same run and record. A run saves once. A reply that starts with `✗` saved nothing: fix the record,
53
+ check it, and save with the same run
54
+ 6. **Report** to the owner what was saved, copying save's lines (active, candidate with the reason, quarantined, superseded), all of them:
55
+ read on with `record_more` when the reply names a cursor
51
56
 
52
57
  A session with nothing worth keeping is saved with `"units": []`: it is marked as looked at, so pending stops listing it.
53
58