sphica 0.6.49 → 0.6.51

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.51",
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
 
@@ -86,7 +90,7 @@ Japanese corner brackets, backticks, apostrophes): quote more of the owner's own
86
90
  Check reads where the words sit, not what they mean: whether they settle this record is yours to judge.
87
91
 
88
92
  Every op carries the `revision` read printed; a record changed since is refused, so read it again. To correct what a record says, write a new
89
- record in `units` (trace's shape, keys saved as `glean:<key>`) with `supersedes` naming the old one (citing the owner's words, a maintainer's, or the owner's session, not other people's text: words that are in the source, and not only a
93
+ record in `units` (trace's shape without the keys `"work"`, `"answers"`, `"field_defs"`, and `"fields"`, and without evidence of the role `decides`, all of which only a trace takes; keys saved as `glean:<key>`) with `supersedes` naming the old one (citing the owner's words, a maintainer's, or the owner's session, not other people's text: words that are in the source, and not only a
90
94
  quotation there); records are never rewritten.
91
95
 
92
96
  ## When a source turns up for an unsourced record
@@ -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
- "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.
41
+ "The record"), without the keys `"work"`, `"answers"`, `"field_defs"`, and `"fields"`, and without evidence of the role `decides`: only a trace takes those. Keys are saved as `harvest:<number>/<key>`. As in trace, check runs the save in a transaction that
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
@@ -36,18 +36,23 @@ Everything goes through Sphica's `record` MCP server (its tools are `trace_pendi
36
36
  them, but they can still be traced. Trace one session at a time
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
- 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.
39
+ the edits observed, the work items there are, and the project's live records. `(traced before)` marks messages an earlier trace already looked at.
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, work items, 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
 
@@ -86,10 +91,15 @@ When Sphica's session-start notice in Claude Code says earlier sessions wait to
86
91
  "aliases": ["database", "storage", "SQLite", "Postgres", "server", "persistence", "..."]
87
92
  }
88
93
  ],
89
- "work": { "key": "storage", "title": "Pick the storage", "goal": "One file per user", "current": "Decided", "next": [], "status": "done" }
94
+ "work": [
95
+ { "key": "storage", "current": "Decided", "next": [], "status": "done" },
96
+ { "key": "csv-export", "title": "Rework the export", "goal": "Notes never leave in a CSV", "current": "Not started", "next": ["List the columns"], "status": "active" }
97
+ ]
90
98
  }
91
99
  ```
92
100
 
101
+ In this example `storage` is a work item context already lists, so only what changed is given; `csv-export` is new and gives every field.
102
+
93
103
  <!-- english-exempt: the aliases example has to show Japanese words -->
94
104
  The `"..."` stands for the other language's words: in this example, `"データベース", "保存先", "DB サーバー", "永続化"`.
95
105
 
@@ -106,12 +116,17 @@ The `"..."` stands for the other language's words: in this example, `"データ
106
116
  | `aliases` | 8 to 12 short search words in **both Japanese and English** a later reader might type: synonyms, the other language's words, abbreviations. Search only; never evidence. Not broad words that match everything (`code`, `fix`, `update`) |
107
117
  | `supersedes` | The key of a live record this one replaces (context lists them). The old one is marked superseded, never deleted |
108
118
  | `conflicts` | Keys of live records this one contradicts without replacing them. Until resolved, both are held back from automatic injection, except the owner's decision, which only another record the owner adopted holds back |
109
- | `work` | The current work status, optional. The same `key` updates it |
119
+ | `answers` | Keys of open questions (context lists them) this record answers, up to 5. Each is closed, withdrawn with this record named as the reason, once this record is active; a decision or constraint also needs the owner's or a maintainer's adoption, so an AI's own decision closes none. Only for a record that settles the question, never a proposal or something merely related. A closed question does not come back: save a new question if it is still open. Not on a question: one question replaces another with `supersedes` |
120
+ | `work` | Work items, optional: one, or a list of up to 10. Context lists the ones there are. For work it lists, reuse its `key` and give only the fields that change (`title`, `goal`, `current`, `next`, `status`): a field left out keeps what is saved, and `next: []` clears the next steps. A new key gives `title`, `goal`, `current`, and `status`. Finished work is `done`; work given up, or opened twice under two keys, is `abandoned`. Change only what the conversation shows: a similar title is no reason to close an item or fold two together. Save says what became of each: created, updated, confirmed with nothing changed, or left as it is because a newer session's trace already wrote it |
110
121
  | `field_defs` | Top level, beside `units`. Only when the owner said in this session to keep a field on records: `name` (a lowercase letter, then lowercase letters, digits, `_`; at most 40), `type` (`text`, `enum`, `integer`, `date`), `label`, `description`, `enum` (1 to 30 distinct allowed values, only for `enum`), `kinds` (the unit kinds it applies to; empty means every kind), and `quote` of **the owner's** words defining it (their own, not a quotation inside their message). A field context already lists cannot be defined again |
111
122
  | `fields` | On a unit, only for fields context lists or this record's `field_defs` defines: `name`, `value`, and `quote` of the words that say it. The value must be written in the quote as it is: an `integer` whole (not the `95` of `p95`, not the `1` of `1.5` or `1,000`; `1,000` is `1000`), a `date` as `YYYY-MM-DD`, an `enum` value exactly, and a date or enum value on its own (not the `no` of `not`). When no message says the value, leave the field out; never infer one |
112
123
 
113
124
  A field value that breaks these rules refuses the whole save, like a `reconsider_quote` not found: fix it or leave the field out.
114
125
 
126
+ When check or save refuses `answers` as an unknown key, a `work` list as not an object, or a work item whose key is already there for leaving
127
+ out a field, the record server is older than this Skill. Do not drop them and save without: ask the owner to reload it (`/reload-plugins` in Claude Code; reopen Codex), then
128
+ begin again, read context, and save.
129
+
115
130
  What becomes active: a decision or constraint with evidence and adoption (the owner's words, or the AI's own decision under the rules below); an implementation with code or commit evidence
116
131
  (an `evidence` anchor on a path this session edited counts); a finding, dead end, or question with evidence. Everything else stays a candidate,
117
132
  and a record whose quote is not in the message is quarantined. Neither is injected into later sessions.