sphica 0.6.55 → 0.6.57

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.
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
3
3
  "name": "sphica",
4
- "version": "0.6.55",
4
+ "version": "0.6.57",
5
5
  "description": "Records Claude Code and Codex sessions on your machine and keeps past implementation and decisions, with their sources, for your agent to find.",
6
6
  "author": {
7
7
  "name": "iroha924",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "sphica",
3
- "version": "0.6.55",
3
+ "version": "0.6.57",
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
  "author": {
6
6
  "name": "iroha924",
package/README.md CHANGED
@@ -1,34 +1,40 @@
1
+ <div align="center">
2
+
1
3
  # Sphica
2
4
 
5
+ **Local memory of past implementation and decisions for Claude Code and Codex.**
6
+
7
+ English | [日本語](https://github.com/iroha924/sphica/blob/main/README.ja.md)
8
+
9
+ Sphica records your coding sessions, and keeps what was decided, rejected, deferred, and built, each record quoting the words it came from.
10
+ Your agent finds those records when it searches, and sees the relevant ones on its own when it reads or edits a file they apply to (in Codex, before a shell command that names the file and before `apply_patch`).
11
+ The database is a single SQLite file on your machine.
12
+
13
+ [![npm](https://img.shields.io/npm/v/sphica?logo=npm&label=sphica)](https://www.npmjs.com/package/sphica)
3
14
  [![License](https://img.shields.io/github/license/iroha924/sphica)](https://github.com/iroha924/sphica/blob/main/LICENSE)
4
- [![CI](https://github.com/iroha924/sphica/actions/workflows/check.yml/badge.svg)](https://github.com/iroha924/sphica/actions/workflows/check.yml)
5
15
  [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/iroha924/sphica/badge)](https://scorecard.dev/viewer/?uri=github.com/iroha924/sphica)
6
16
  [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14787/badge)](https://www.bestpractices.dev/projects/14787)
7
17
  [![SLSA Build L2](https://img.shields.io/badge/SLSA-Build%20L2-green)](https://www.npmjs.com/package/sphica#provenance)
8
- [![Dependabot: GitHub Actions](https://img.shields.io/badge/Dependabot-GitHub%20Actions-025E8C?logo=dependabot)](https://github.com/iroha924/sphica/blob/main/.github/dependabot.yml)
9
18
 
10
- What the badges cover: CI runs the checks in [Contributing](https://github.com/iroha924/sphica#contributing), and how each release is built and published is in [Security](https://github.com/iroha924/sphica#security). A passing badge does not mean the code is free of bugs or vulnerabilities.
19
+ <a href="https://github.com/iroha924/sphica#install"><img alt="Install Sphica for free" src="https://img.shields.io/badge/Sphica-Install_for_free-2ea44f?style=for-the-badge" height="44"></a>
11
20
 
12
- English | [日本語](https://github.com/iroha924/sphica/blob/main/README.ja.md)
21
+ <sub>What the badges cover: how each release is built and published is in [Security](https://github.com/iroha924/sphica#security). A badge does not mean the code is free of bugs or vulnerabilities.</sub>
13
22
 
14
- **Local memory of past implementation and decisions for Claude Code and Codex.**
15
- Sphica records your coding sessions, and keeps what was decided, rejected, deferred, and built, each record quoting the words it came from.
16
- Your agent finds those records when it searches, and sees the relevant ones on its own when it reads or edits a file they apply to (in Codex, before a shell command that names the file and before `apply_patch`).
17
- The database is a single SQLite file on your machine.
23
+ </div>
18
24
 
19
25
  ## Features
20
26
 
21
27
  - **Automatic recording.** Sphica keeps your prompts, the agent's final reply for each turn, and the paths of the files a turn changed (by the edit tools, or seen in `git status` at the turn's end).
22
28
  - **Records with their sources.** `/sphica:trace` turns a session into records: decisions with the options rejected and why, constraints, implementations, findings, dead ends, and open questions. Every record quotes the exact words it came from. A decision counts as adopted in two ways: you said so (your decision), or the agent decided it itself in that session and its reply says so (an AI's decision). An AI's decision is shown as one, never replaces yours, and is never used for public interfaces, security and permissions, releases, or forgetting.
23
- - **Traced without asking.** When you start a new session (an interactive one in Claude Code; one started from the terminal in Codex) and sessions from the last 14 days wait to be traced, the agent is asked to trace up to two of them, oldest first, after your request is done. Run `/sphica:trace` yourself to keep something right away, and `/sphica:trace pending` for older sessions. To turn the automatic trace off, set the plugin's `auto_trace` option to false in `/config` (Claude Code 2.1.269 or later), or set `"SPHICA_AUTO_TRACE": "off"` under `env` in Claude Code's `settings.json`; recording and your own `/sphica:trace` keep working. Either one off keeps it off, so to turn it back on, clear both. In Codex, set `SPHICA_AUTO_TRACE` to `off` in the environment Codex's background server starts with (see "What Sphica can't do yet" for when a value takes effect).
29
+ - **Traced without asking.** When you start a new session (an interactive one in Claude Code; one started from the terminal in Codex) and sessions from the last 14 days wait to be traced, the agent is asked to trace up to two of them, oldest first, after your request is done. Run `/sphica:trace` yourself to keep something right away, and `/sphica:trace pending` for older sessions. To turn the automatic trace off, see [Settings](https://github.com/iroha924/sphica#settings); recording and your own `/sphica:trace` keep working.
24
30
  - **Pull requests too.** `/sphica:harvest <number>` keeps a GitHub pull request (body, comments, reviews, review comments, commits, and up to five issues the body says it closes) and records what it decided. A reviewer's suggestion stays a proposal unless the owner or a maintainer adopted it; a merge alone adopts nothing.
25
31
  - **Evidence found later.** `/sphica:glean` adds evidence and corrections to existing records. It asks you for the source (an issue URL, the file and line, meeting notes) before saving; a claim without one is kept only as unsourced and never used as fact.
26
- - **Forget what should not have been kept.** `/sphica:forget` removes the messages, pull request items, or file excerpts you pick, with their search entries and the bytes left in the database file, after you confirm in a dialog (if another session is reading the database, it asks you to run it again to finish clearing the bytes). Records that cited them are judged again and leave active when nothing else supports them; a record's own text stays as it was.
27
- - **Shown when it matters.** At session start, the current work; before the agent reads or edits a file, or runs a shell command that names it, the decisions tied to that file; when your prompt names a recorded option or code symbol, that record. An AI's decision is marked as one, with a note that the agent may depart from it for a stated reason. Works in both Claude Code and Codex.
28
- - **Shown after a shell command changes a file (trial, off by default).** A script or command that rewrites a file without naming it gets past the delivery before the command. With the `shell_write_delivery` option on, Sphica compares the content of the files your decisions apply to before and after each shell command, and right after the command shows the decisions on the files whose content changed and that the agent has not seen in this conversation. Turn it on in `/config` (Claude Code 2.1.269 or later), or set `SPHICA_SHELL_WRITE_DELIVERY` to `on` in the environment the host starts from (either host; `off` turns it off whatever the option says). In Codex, trust the new hook in `/hooks` after updating. It keeps content hashes and one line per command in `~/.sphica/shell-state/`.
32
+ - **Forget what should not have been kept.** `/sphica:forget` removes the messages, pull request items, or file excerpts you pick, with their search entries and the bytes left in the database file, after you confirm in a dialog. Records that cited them are judged again and leave active when nothing else supports them; a record's own text stays as it was.
33
+ - **Shown when it matters.** At session start, the current work; before the agent reads or edits a file, or runs a shell command that names it, the decisions tied to that file; when your prompt names a recorded option or code symbol, that record. An AI's decision is marked as one, with a note that the agent may depart from it for a stated reason.
34
+ - **Shown after a shell command changes a file (trial, off by default).** A script or command that rewrites a file without naming it gets past the delivery before the command. With the `shell_write_delivery` setting on, Sphica compares the content of the files your decisions apply to before and after each shell command, and right after the command shows the decisions on the files whose content changed and that the agent has not seen in this conversation. [Settings](https://github.com/iroha924/sphica#settings) says how to turn it on.
29
35
  - **Search in Japanese and English.** Records are made with search words in both languages, so a question in either language is more likely to find them.
30
36
  - **Find what you asked before.** Ask the agent whether you asked something like this before: `search` with `asked: true` shows your earlier messages in other sessions, the records that quote them (with what replaced them), and says "no recorded decision" when none was recorded, including a matter you raised in several sessions.
31
- - **See how a decision changed, and what held at a past time.** Ask the agent how a decision came to be: `read` with `timeline: true` shows the decisions it replaced or was replaced by, when each change took effect and why, and the findings, dead ends, and questions saved by the same trace or harvest or tied to the same code, oldest first. It is an overview; the quoted words are in the full record. Ask what was decided as of a time: `search` with `as_of` (a time with its offset, such as `2026-10-01T09:00:00+09:00`) searches the records as Sphica held them then, by the states and replacements of that time, and names apart the ones saved later that match now (the first ten, then a count). The time is when Sphica saved a record, not when the words were said, so a session traced late or a pull request harvested late counts from the day it was saved.
37
+ - **See how a decision changed, and what held at a past time.** Ask the agent how a decision came to be: `read` with `timeline: true` shows the decisions it replaced or was replaced by, when each change took effect and why, and the findings, dead ends, and questions saved by the same trace or harvest or tied to the same code, oldest first. Ask what was decided as of a time: `search` with `as_of` (a time with its offset, such as `2026-10-01T09:00:00+09:00`) searches the records as Sphica held them then, by the states and replacements of that time, and names apart the ones saved later that match now (oldest first, up to ten, then a count). The time is when Sphica saved a record, not when the words were said, so a session traced late or a pull request harvested late counts from the day it was saved.
32
38
  - **See what is live, and what needs a look.** Ask for the overview: `view: "live"` lists every active decision and constraint by the directory it applies to; `view: "look"` lists records whose file is gone or whose symbol is not found, conditions you said would bring a rejected option back, and lines in your instruction files whose record was replaced. Nothing is expired or changed on its own.
33
39
  - **See what Sphica showed your agent.** Ask what Sphica has been showing: `view: "delivery"` (with `days`, 1 to 90, 7 by default) counts the deliveries the hooks logged by event and by main agent or subagent, lists the records shown most, and gives recent sessions with each record's key, so you can judge whether each helped. It says what the log leaves out, and marks a record "named later" only when a later reply wrote its key.
34
40
  - **Track your own fields on records (trial).** Say in a session which extra field to keep on records (the affected tenant, a p95 figure); trace then saves a value only when the conversation writes it, with the quote. `/sphica:fields` shows each field and how many records carry a value.
@@ -83,7 +89,7 @@ sphica init
83
89
 
84
90
  This creates `~/.sphica/sphica.db` and registers the repository. Running it again keeps the database and the registration as they are. If the repository has no `origin` remote, give it a name: `sphica init --name <name>`.
85
91
 
86
- If `gh` is signed in, init also binds that GitHub account as yours, so your words adopt a decision even in someone else's repository where you are only a contributor. This applies to pull requests harvested after binding; ones harvested before keep your words as a contributor's. Only the first account is bound: if `gh` is later signed in to another one, init says so and adds nothing, and there is no command to change it (move the database aside and run init again). Without `gh`, init still sets up and says why nothing was bound; `sphica doctor` shows the bound account.
92
+ If `gh` is signed in, init also binds that GitHub account as yours, so your words adopt a decision even in someone else's repository where you are only a contributor (in pull requests harvested after binding). Only the first account is bound, and there is no command to change it: move the database aside and run init again. Without `gh`, init still sets up and says why nothing was bound; `sphica doctor` shows the bound account.
87
93
 
88
94
  **4. Check the setup**
89
95
 
@@ -111,26 +117,35 @@ To bring back earlier decisions, ask the agent:
111
117
 
112
118
  Without being asked, Sphica adds a few past records to what the agent sees, each marked as a past record rather than an instruction:
113
119
 
114
- - At session start: the current work and project-wide constraints, and, when earlier sessions wait to be traced, a request to trace them after your request is done (in a new interactive Claude Code session, or a new Codex session started from the terminal).
120
+ - At session start: the current work and project-wide constraints, and, when earlier sessions wait to be traced, a request to trace them after your request is done.
115
121
  - On a prompt that names a recorded code symbol, file path, or option.
116
122
  - Before the agent reads or edits a file a decision applies to, and before a shell command that names such a file (naming it is not proof the command reads it). A read shows each record once per session.
117
- - After a shell command that changed the content of such a file, when the `shell_write_delivery` option is on (off by default): the decisions on it the agent has not seen in this conversation.
118
- - Before a review. When you run your own review command (any name containing `review`, or a name listed, comma-separated, in the plugin's
119
- `review_commands` option in `/config` (Claude Code 2.1.269 or later) or the `SPHICA_REVIEW_COMMANDS` environment variable), it gets the decisions your local
120
- change touches. When `review_commands` names any command, `SPHICA_REVIEW_COMMANDS` is not read. `/sphica:review` checks them itself.
123
+ - After a shell command that changed the content of such a file, when the `shell_write_delivery` setting is on (off by default): the decisions on it the agent has not seen in this conversation.
124
+ - Before a review. When you run your own review command (any name containing `review`, or a name listed in the review commands [setting](https://github.com/iroha924/sphica#settings)), it gets the decisions your local change touches. `/sphica:review` checks them itself.
121
125
 
122
- In Codex the same happens at session start, on a prompt, before an `apply_patch` edit, before a shell command that names such a file (Codex reads files through shell commands, so this covers reads), and, with the option on, after a shell command that changed one.
126
+ In Codex the same happens at session start, on a prompt, before an `apply_patch` edit, before a shell command that names such a file (Codex reads files through shell commands, so this covers reads), and, with the setting on, after a shell command that changed one.
123
127
  Before a review, Codex gets the same decisions in three cases: its built-in review (`/review`, `codex review`), a review skill you name in the prompt (`$my-review`), and a review skill the agent picks itself, when it prints the skill's file with one plain command such as `cat <path>/SKILL.md`. A skill is a review when its name contains `review` or is listed in `SPHICA_REVIEW_COMMANDS`. `$sphica:review` checks them itself.
124
128
 
125
129
  The agent searches with Sphica's `search` and opens full records with `read`. `status` tells it how much of the history has been traced, so an empty search is less likely to be mistaken for "never decided".
126
130
 
131
+ ## Settings
132
+
133
+ | Setting | Default | Claude Code option | Environment variable |
134
+ |---|---|---|---|
135
+ | Automatic trace | on | `auto_trace` | `SPHICA_AUTO_TRACE` (`off`) |
136
+ | Delivery after a shell command changes a file (trial) | off | `shell_write_delivery` | `SPHICA_SHELL_WRITE_DELIVERY` (`on` or `off`) |
137
+ | Your own review commands whose names do not contain `review`, comma-separated | none | `review_commands` | `SPHICA_REVIEW_COMMANDS` |
138
+
139
+ - **Claude Code.** Set the plugin's options in `/config` (Claude Code 2.1.269 or later), or set the variables in the environment Claude Code starts from; for the automatic trace, `"SPHICA_AUTO_TRACE": "off"` under `env` in `settings.json` works too. The automatic trace stays off when either the option or the variable says off, so to turn it back on, turn the option on and unset the variable. `SPHICA_SHELL_WRITE_DELIVERY` wins over the option, on or off. When `review_commands` names any command, `SPHICA_REVIEW_COMMANDS` is not read.
140
+ - **Codex.** Codex plugins have no options page, so the settings are the environment variables. In a session that runs through Codex's background server (the terminal does by default), Sphica's hooks see the environment that server started with, not the terminal you open later: a value you set afterwards takes effect the next time the server starts (`codex app-server daemon restart` starts it again; work running in Codex may be interrupted). `codex exec` does not use that server, so its hooks see the environment it was started from. A background server started from inside an agent's shell (for example `! codex` in Claude Code) keeps that agent's variables too: Sphica then takes every session that runs through it for that agent's child and records nothing until the server starts again.
141
+
127
142
  ## What gets recorded and where it goes
128
143
 
129
144
  - **Where.** The database is `~/.sphica/sphica.db`. Captured sessions wait in a local queue, `~/.sphica/spool`, until they are written to it. Each machine has its own database; nothing is shared between machines.
130
145
  - **What.** Your prompts, the agent's final reply for each turn, and the paths of changed files. In Codex, a session is recorded only when Codex's own session log shows the messages come from the session's own thread: what Codex's built-in review is asked (its instructions, the subject of the commit it names) is not recorded, and neither is a `codex exec --ephemeral` run, which keeps no log. When Sphica cannot confirm a session, it records nothing of it; Codex's terminal shows Sphica's notice once, and `codex exec` shows none. Background-task notifications and messages from other agents are skipped when Sphica recognizes their format. Replies in the middle of a turn are not kept, nor are files created and deleted within one turn without the edit tools.
131
- - **What was shown.** Each automatic delivery is logged by which records it showed, not their text.
146
+ - **What was shown.** Each automatic delivery is logged by which records it showed, not their text. With the delivery after a shell command on, Sphica also keeps content hashes and one line per command in `~/.sphica/shell-state/`.
132
147
  - **Unregistered repositories.** Sessions in a repository you have not registered stay in the queue and are written after you register it. Held sessions are dropped after 30 days, and when more than 1,000 are waiting the oldest go first.
133
- - **Secrets.** In your prompts, pull request text, and the file lines `/sphica:glean` cites, only secrets with a recognizable shape are masked (excerpts saved before 0.5.7 stay as they were until you forget them):
148
+ - **Secrets.** In your prompts, pull request text, and the file lines `/sphica:glean` cites, only secrets with a recognizable shape are masked:
134
149
  - keys with known prefixes
135
150
  - `KEY=…` and `"password": …` assignments
136
151
  - credentials in URLs
@@ -149,11 +164,9 @@ The agent searches with Sphica's `search` and opens full records with `read`. `s
149
164
  - In Codex, `$sphica:trace`, `$sphica:harvest`, and `$sphica:glean` can write only when Codex tells Sphica which directory the session is in. Current Codex does. When it does not, they write nothing and tell you why.
150
165
  - Showing a record does not make the agent follow it.
151
166
  - Whether the agent decided something itself is judged from what its reply says, so it can be wrong.
152
- - An AI's decision is adopted only when the trace runs in an interactive session: Claude Code's terminal, or a Codex turn a person started in the session's own thread. For Codex, Sphica reads what Codex reports with each tool call; this was measured with Codex's terminal, and another Codex client that reports the same is treated alike. In headless and SDK runs, `codex exec`, and a Codex child thread it stays a candidate, and once a Codex child thread has called one of Sphica's record tools, no reply of that session is adopted.
153
- - The automatic trace is a request the agent may skip. In Codex it goes only to new sessions started from the terminal; in other Codex clients and in `codex exec`, Codex tells you when sessions wait.
154
- - In Codex, Sphica's settings are environment variables (`SPHICA_AUTO_TRACE`, `SPHICA_SHELL_WRITE_DELIVERY`, `SPHICA_REVIEW_COMMANDS`; Codex plugins have no options page). In a session that runs through Codex's background server (the terminal does by default), Sphica's hooks see the environment that server started with, not the terminal you open later: a value you set afterwards takes effect the next time the server starts (`codex app-server daemon restart` starts it again; work running in Codex may be interrupted). `codex exec` does not use that server, so its hooks see the environment it was started from. A background server started from inside an agent's shell (for example `! codex` in Claude Code) keeps that agent's variables too: Sphica then takes every session that runs through it for that agent's child and records nothing until the server starts again.
155
- - When Sphica cannot tell which turn ran one of its record tools, every reply Claude Code's agent writes in that project from then on stays a candidate. If the hook only timed out, it keeps what it saw and the next recording sends it; from then on, replies of other turns can be adopted again (when the hook knew the turn), while the turn that ran the tool stays out. If the hook was turned off, the host sent no tool call id, or the call came before Sphica was installed, nothing can be sent later and the stop stays for good. Records already saved as candidates are not adopted afterwards. `sphica doctor` lists the calls behind a stop and since when. Your decisions are not affected.
156
- - The automatic trace uses your subscription's usage.
167
+ - An AI's decision is adopted only when the trace runs in an interactive session: Claude Code's terminal, or a Codex turn a person started in the session's own thread (measured with Codex's terminal). In headless and SDK runs, `codex exec`, and a Codex child thread it stays a candidate (recorded, but not adopted), and once a Codex child thread has called one of Sphica's record tools, no reply of that session is adopted.
168
+ - The automatic trace is a request the agent may skip, and it uses your subscription's usage. In Codex it goes only to new sessions started from the terminal; in other Codex clients and in `codex exec`, Codex tells you when sessions wait.
169
+ - When Sphica cannot tell which turn ran one of its record tools, every reply Claude Code's agent writes in that project from then on stays a candidate, and records already saved as candidates are not adopted afterwards. If the hook only timed out, replies of other turns can be adopted again once the next recording sends what the hook saw (when the hook knew the turn). If the hook was turned off, the host sent no tool call id, or the call came before Sphica was installed, the stop stays for good. `sphica doctor` lists the calls behind a stop and since when. Your decisions are not affected.
157
170
  - The agent never withdraws an AI's decision. When a later record contradicts it, the AI's decision is held back from being shown until you settle it, and so is the later record unless it is your decision.
158
171
  - A code location in a record is checked against your working tree when it is read. Finding the code name (a function name, say) the record points to does not mean the decision still holds.
159
172
 
@@ -179,7 +192,7 @@ codex plugin marketplace upgrade sphica
179
192
  codex plugin add sphica@sphica
180
193
  ```
181
194
 
182
- Restart open sessions afterwards. When an update changes the database (0.6.0 does), update the CLI first, then run `sphica init` once: it migrates the database in place and keeps your records. Until then Sphica says it is unavailable and tells you so. An older CLI cannot read the migrated database: if one still says to move it aside, update that CLI instead.
195
+ Restart open sessions afterwards. When an update changes the database, update the CLI first, then run `sphica init` once: it migrates the database in place and keeps your records. Until then Sphica is unavailable and tells you so. An older CLI cannot read the migrated database: if one still says to move it aside, update that CLI instead.
183
196
 
184
197
  ## Uninstalling
185
198
 
@@ -200,7 +213,7 @@ npm uninstall -g sphica
200
213
  Run `sphica doctor` first. It shows which part is out of date or not working. Common cases:
201
214
 
202
215
  - **`sphica: command not found`.** The plugin does not put the CLI on your PATH. Run `npm i -g sphica`.
203
- - **Nothing is recorded.** Check that `sphica doctor` lists the repository under Projects. In Codex, also check the "Codex hooks" line, or `/hooks`, for hooks that are not trusted.
216
+ - **Nothing is recorded.** Check that `sphica doctor` lists the repository under Projects. In Codex, also check the "Codex hooks" line, or `/hooks`, for hooks that are not trusted; if Codex was started from inside another agent's shell, see Codex under [Settings](https://github.com/iroha924/sphica#settings).
204
217
  - **The MCP servers report an older version.** Restart the session, or run `/reload-plugins` in Claude Code.
205
218
  - **A search finds nothing.** Search matches words. Try other words, the other language, an identifier, or fewer words. Ask the agent to check `status`: sessions not traced yet are searchable only as captured text.
206
219
  - **`doctor` says the full-text index is broken.** Run `sphica doctor --reindex`.
@@ -212,6 +225,7 @@ Run `sphica doctor` first. It shows which part is out of date or not working. Co
212
225
  |---|---|
213
226
  | `sphica init` | Create the database, bind the GitHub account `gh` is signed in to, and register the current repository |
214
227
  | `sphica doctor` | Check versions, the database, recording, and each registered project |
228
+ | `sphica doctor --reindex` | Rebuild the full-text index when `doctor` says it is broken |
215
229
  | `sphica doctor --audit-quotes` | List saved adoptions and reasons that rest on quoted words. It only reads: nothing is changed |
216
230
  | `sphica uninstall` | Delete `~/.sphica` and show how to remove the plugin and the CLI |
217
231
 
@@ -0,0 +1,61 @@
1
+ -- Copyright (c) 2026 iroha924 and contributors
2
+ -- SPDX-License-Identifier: MIT
3
+
4
+ -- Revision 12 → 13 of generation 2: a withdrawal an answer caused keeps the record that answered (unit_answer). Earlier withdrawals name
5
+ -- the answer only in their reason, so each is copied when exactly one record its run saved has the key the reason names; the others are
6
+ -- listed and left without a row. Every statement that stays is the same as in the schema at revision 13.
7
+
8
+ create temp table sphica_migration_note (rule text, item text, action text);
9
+
10
+ create table unit_answer (
11
+ state_id integer primary key not null references unit_state (id) on delete cascade,
12
+ answer_unit integer not null references unit (id) on delete cascade
13
+ ) strict;
14
+ create index unit_answer_unit on unit_answer (answer_unit);
15
+ create trigger unit_answer_check before insert on unit_answer begin
16
+ select raise(abort, 'an answer is written for the withdrawal of a question')
17
+ where not exists (select 1 from unit_state t join unit q on q.id = t.unit_id
18
+ where t.id = new.state_id and t.to_state = 'withdrawn' and q.kind = 'question');
19
+ select raise(abort, 'a question does not answer another')
20
+ where (select kind from unit where id = new.answer_unit) is 'question';
21
+ select raise(abort, 'answer and question belong to different projects')
22
+ where (select project_id from unit where id = new.answer_unit)
23
+ is not (select q.project_id from unit_state t join unit q on q.id = t.unit_id where t.id = new.state_id);
24
+ select raise(abort, 'a question is closed by a record the withdrawal''s own run saved')
25
+ where (select run_id from unit where id = new.answer_unit) is not (select run_id from unit_state where id = new.state_id);
26
+ end;
27
+ create trigger unit_answer_frozen before update on unit_answer begin
28
+ select raise(abort, 'an answer is never changed');
29
+ end;
30
+ create trigger unit_answer_no_delete before delete on unit_answer
31
+ when exists (select 1 from unit_state where id = old.state_id) and exists (select 1 from unit where id = old.answer_unit) begin
32
+ select raise(abort, 'an answer goes only with its withdrawal or its record');
33
+ end;
34
+ -- Made before the copy below, so each copied row raises the revision of its question and of its answer as a saved one does
35
+ create trigger unit_rev_answer_i after insert on unit_answer begin
36
+ update unit set revision = revision + 1
37
+ where id in (new.answer_unit, (select unit_id from unit_state where id = new.state_id));
38
+ end;
39
+
40
+ -- The reason is compared with whole keys, not cut at a separator: a key's own characters cannot end it early. substr, not like, since
41
+ -- a key's _ would match any character there. Only pairs the insert trigger accepts are picked, so the copy never stops the migration
42
+ insert into unit_answer (state_id, answer_unit)
43
+ select t.id, min(a.id)
44
+ from unit_state t
45
+ join unit q on q.id = t.unit_id
46
+ join unit a on a.project_id = q.project_id and a.run_id = t.run_id and a.kind <> 'question'
47
+ and (t.reason = 'answered by ' || a.key
48
+ or substr(t.reason, 1, length('answered by ' || a.key || ' (through ')) = 'answered by ' || a.key || ' (through ')
49
+ where t.to_state = 'withdrawn' and q.kind = 'question'
50
+ group by t.id
51
+ having count(*) = 1;
52
+
53
+ insert into sphica_migration_note
54
+ select 'a withdrawal whose reason names an answer, with no single record of its save to match', q.key || ' (state ' || t.id || ')',
55
+ 'left without its answer; a timeline of the answering record does not tell this withdrawal'
56
+ from unit_state t join unit q on q.id = t.unit_id
57
+ where t.to_state = 'withdrawn' and substr(t.reason, 1, 12) = 'answered by '
58
+ and not exists (select 1 from unit_answer w where w.state_id = t.id)
59
+ order by t.id;
60
+
61
+ pragma user_version = 13;
package/db/schema.sql CHANGED
@@ -8,7 +8,7 @@
8
8
  -- Four boundaries:
9
9
  -- captured sources session, source, artifact_link, edit_observation: what was said or written, never rewritten
10
10
  -- (the owner can forget chosen sources: forget_batch and source_forgotten keep what was removed, without its text)
11
- -- extracted units unit and its option, evidence, adoption, link, state, anchor, alias tables: what was decided or implemented
11
+ -- extracted units unit and its option, evidence, adoption, link, state, answer, anchor, alias tables: what was decided or implemented
12
12
  -- processing extraction_run, source_processing, harvest_run_source: what has been looked at and saved, so gaps are counted
13
13
  -- work and delivery work, delivery, delivery_unit: the current work status and what the hooks injected
14
14
  -- Every table is STRICT and every primary key is not null. Times are ISO 8601 UTC (`Date#toISOString()`); `strftime(...) is column` rejects others.
@@ -660,6 +660,33 @@ create trigger unit_state_apply after insert on unit_state begin
660
660
  update unit set lifecycle = new.to_state, revision = revision + 1 where id = new.unit_id;
661
661
  end;
662
662
 
663
+ -- Why a question was withdrawn: the record whose answer closed it, written with the withdrawal's state row. A withdrawal the owner
664
+ -- asked for has no row. The answering record is one the withdrawal's own run saved, so a save closes questions only with what it wrote.
665
+ create table unit_answer (
666
+ state_id integer primary key not null references unit_state (id) on delete cascade,
667
+ answer_unit integer not null references unit (id) on delete cascade
668
+ ) strict;
669
+ create index unit_answer_unit on unit_answer (answer_unit);
670
+ create trigger unit_answer_check before insert on unit_answer begin
671
+ select raise(abort, 'an answer is written for the withdrawal of a question')
672
+ where not exists (select 1 from unit_state t join unit q on q.id = t.unit_id
673
+ where t.id = new.state_id and t.to_state = 'withdrawn' and q.kind = 'question');
674
+ select raise(abort, 'a question does not answer another')
675
+ where (select kind from unit where id = new.answer_unit) is 'question';
676
+ select raise(abort, 'answer and question belong to different projects')
677
+ where (select project_id from unit where id = new.answer_unit)
678
+ is not (select q.project_id from unit_state t join unit q on q.id = t.unit_id where t.id = new.state_id);
679
+ select raise(abort, 'a question is closed by a record the withdrawal''s own run saved')
680
+ where (select run_id from unit where id = new.answer_unit) is not (select run_id from unit_state where id = new.state_id);
681
+ end;
682
+ create trigger unit_answer_frozen before update on unit_answer begin
683
+ select raise(abort, 'an answer is never changed');
684
+ end;
685
+ create trigger unit_answer_no_delete before delete on unit_answer
686
+ when exists (select 1 from unit_state where id = old.state_id) and exists (select 1 from unit where id = old.answer_unit) begin
687
+ select raise(abort, 'an answer goes only with its withdrawal or its record');
688
+ end;
689
+
663
690
  -- Where a unit applies in code, or code cited as evidence. Validated against the working tree when served, never cached here.
664
691
  create table unit_anchor (
665
692
  id integer primary key autoincrement not null,
@@ -1052,6 +1079,10 @@ end;
1052
1079
  create trigger unit_rev_link_u after update on unit_link begin
1053
1080
  update unit set revision = revision + 1 where id in (new.from_unit, new.to_unit);
1054
1081
  end;
1082
+ create trigger unit_rev_answer_i after insert on unit_answer begin
1083
+ update unit set revision = revision + 1
1084
+ where id in (new.answer_unit, (select unit_id from unit_state where id = new.state_id));
1085
+ end;
1055
1086
  create trigger unit_rev_anchor_i after insert on unit_anchor begin update unit set revision = revision + 1 where id = new.unit_id; end;
1056
1087
  create trigger unit_rev_anchor_u after update on unit_anchor begin update unit set revision = revision + 1 where id = new.unit_id; end;
1057
1088
  create trigger unit_rev_retirement_i after insert on unit_anchor_retirement begin
@@ -1270,4 +1301,4 @@ create trigger capture_delivery_prune_insert instead of insert on capture_delive
1270
1301
  order by d.at, d.id limit 200);
1271
1302
  end;
1272
1303
 
1273
- pragma user_version = 12;
1304
+ pragma user_version = 13;
package/dist/capture.js CHANGED
@@ -11587,7 +11587,7 @@ var HOST_MARKS = new Set([".orphaned_at", ".in_use"]);
11587
11587
 
11588
11588
  // server/src/sqlite.ts
11589
11589
  var SCHEMA_GENERATION = 2;
11590
- var SCHEMA_REVISION = 12;
11590
+ var SCHEMA_REVISION = 13;
11591
11591
  var sphicaHome = () => process.env.SPHICA_HOME || path4.join(os2.homedir(), ".sphica");
11592
11592
  var dbFile = () => process.env.SPHICA_DB || path4.join(sphicaHome(), "sphica.db");
11593
11593
  function requireRuntime() {
@@ -11795,6 +11795,7 @@ var INGEST_INSERTS = new Set([
11795
11795
  "unit_adoption",
11796
11796
  "unit_link",
11797
11797
  "unit_state",
11798
+ "unit_answer",
11798
11799
  "unit_replacement",
11799
11800
  "unit_anchor",
11800
11801
  "unit_anchor_retirement",
@@ -11836,6 +11837,7 @@ var INGEST_TRIGGER_WRITES = {
11836
11837
  "adoption_d",
11837
11838
  "link_i",
11838
11839
  "link_u",
11840
+ "answer_i",
11839
11841
  "replacement_i",
11840
11842
  "replacement_u",
11841
11843
  "anchor_i",
package/dist/cli.js CHANGED
@@ -4644,7 +4644,7 @@ function distributed(root, tracked) {
4644
4644
  function differingFiles(a2, b, { tracked = false } = {}) {
4645
4645
  const x = distributed(a2, tracked);
4646
4646
  const y2 = distributed(b, false);
4647
- return [...new Set([...x.keys(), ...y2.keys()])].filter((rel) => {
4647
+ return [...new Set([...x.keys(), ...y2.keys()])].filter((rel) => !(tracked && rel === "README.md")).filter((rel) => {
4648
4648
  const p = x.get(rel);
4649
4649
  const q = y2.get(rel);
4650
4650
  return !p || !q || !fs3.readFileSync(p).equals(fs3.readFileSync(q));
@@ -5082,7 +5082,7 @@ ${indent}${caution(note)}` : ""}`);
5082
5082
 
5083
5083
  // server/src/sqlite.ts
5084
5084
  var SCHEMA_GENERATION = 2;
5085
- var SCHEMA_REVISION = 12;
5085
+ var SCHEMA_REVISION = 13;
5086
5086
  var sphicaHome = () => process.env.SPHICA_HOME || path4.join(os3.homedir(), ".sphica");
5087
5087
  var dbFile = () => process.env.SPHICA_DB || path4.join(sphicaHome(), "sphica.db");
5088
5088
  function requireRuntime() {
@@ -16175,6 +16175,7 @@ var INGEST_INSERTS = new Set([
16175
16175
  "unit_adoption",
16176
16176
  "unit_link",
16177
16177
  "unit_state",
16178
+ "unit_answer",
16178
16179
  "unit_replacement",
16179
16180
  "unit_anchor",
16180
16181
  "unit_anchor_retirement",
@@ -16216,6 +16217,7 @@ var INGEST_TRIGGER_WRITES = {
16216
16217
  "adoption_d",
16217
16218
  "link_i",
16218
16219
  "link_u",
16220
+ "answer_i",
16219
16221
  "replacement_i",
16220
16222
  "replacement_u",
16221
16223
  "anchor_i",
@@ -17900,7 +17902,8 @@ function planOf(rows, asked) {
17900
17902
  const gone = ended.get(t2.unit);
17901
17903
  const reason2 = t2.from === null ? "first judged" : t2.to === "withdrawn" ? withdraw.get(t2.unit)?.reason ?? "withdrawn" : t2.to === "superseded" ? `superseded by ${keys.get(holder)}` : t2.from === "superseded" ? `${gone !== undefined ? keys.get(gone) : "its successor"} no longer replaces it` : t2.to === "active" ? hint?.reason ?? "support complete" : `${asked.because ?? "support lost"}: ${waitText(judged, t2.unit, loaded, intentOf.get(t2.unit))}`;
17902
17904
  const source = t2.to === "withdrawn" ? withdraw.get(t2.unit)?.source ?? null : t2.to === "superseded" ? asked.hints?.get(holder)?.source ?? null : hint?.source ?? null;
17903
- writes2.push({ op: "state", unit: t2.unit, from: t2.from, to: t2.to, reason: reason2, source });
17905
+ const answer = t2.to === "withdrawn" ? withdraw.get(t2.unit)?.answer ?? null : null;
17906
+ writes2.push({ op: "state", unit: t2.unit, from: t2.from, to: t2.to, reason: reason2, source, answer });
17904
17907
  }
17905
17908
  return { judged, loaded, writes: writes2, redundant, intentOf };
17906
17909
  }
package/dist/deliver.js CHANGED
@@ -11650,7 +11650,7 @@ var HOST_MARKS = new Set([".orphaned_at", ".in_use"]);
11650
11650
 
11651
11651
  // server/src/sqlite.ts
11652
11652
  var SCHEMA_GENERATION = 2;
11653
- var SCHEMA_REVISION = 12;
11653
+ var SCHEMA_REVISION = 13;
11654
11654
  var sphicaHome = () => process.env.SPHICA_HOME || path5.join(os2.homedir(), ".sphica");
11655
11655
  var dbFile = () => process.env.SPHICA_DB || path5.join(sphicaHome(), "sphica.db");
11656
11656
  function requireRuntime() {
@@ -11893,6 +11893,7 @@ var INGEST_INSERTS = new Set([
11893
11893
  "unit_adoption",
11894
11894
  "unit_link",
11895
11895
  "unit_state",
11896
+ "unit_answer",
11896
11897
  "unit_replacement",
11897
11898
  "unit_anchor",
11898
11899
  "unit_anchor_retirement",
@@ -11934,6 +11935,7 @@ var INGEST_TRIGGER_WRITES = {
11934
11935
  "adoption_d",
11935
11936
  "link_i",
11936
11937
  "link_u",
11938
+ "answer_i",
11937
11939
  "replacement_i",
11938
11940
  "replacement_u",
11939
11941
  "anchor_i",
@@ -46365,7 +46365,7 @@ var HOST_MARKS = new Set([".orphaned_at", ".in_use"]);
46365
46365
 
46366
46366
  // server/src/sqlite.ts
46367
46367
  var SCHEMA_GENERATION = 2;
46368
- var SCHEMA_REVISION = 12;
46368
+ var SCHEMA_REVISION = 13;
46369
46369
  var sphicaHome = () => process.env.SPHICA_HOME || path3.join(os2.homedir(), ".sphica");
46370
46370
  var dbFile = () => process.env.SPHICA_DB || path3.join(sphicaHome(), "sphica.db");
46371
46371
  function requireRuntime() {
@@ -46587,6 +46587,7 @@ var INGEST_INSERTS = new Set([
46587
46587
  "unit_adoption",
46588
46588
  "unit_link",
46589
46589
  "unit_state",
46590
+ "unit_answer",
46590
46591
  "unit_replacement",
46591
46592
  "unit_anchor",
46592
46593
  "unit_anchor_retirement",
@@ -46628,6 +46629,7 @@ var INGEST_TRIGGER_WRITES = {
46628
46629
  "adoption_d",
46629
46630
  "link_i",
46630
46631
  "link_u",
46632
+ "answer_i",
46631
46633
  "replacement_i",
46632
46634
  "replacement_u",
46633
46635
  "anchor_i",
@@ -48641,7 +48643,8 @@ function planOf(rows, asked) {
48641
48643
  const gone = ended.get(t.unit);
48642
48644
  const reason2 = t.from === null ? "first judged" : t.to === "withdrawn" ? withdraw.get(t.unit)?.reason ?? "withdrawn" : t.to === "superseded" ? `superseded by ${keys.get(holder)}` : t.from === "superseded" ? `${gone !== undefined ? keys.get(gone) : "its successor"} no longer replaces it` : t.to === "active" ? hint?.reason ?? "support complete" : `${asked.because ?? "support lost"}: ${waitText(judged, t.unit, loaded, intentOf.get(t.unit))}`;
48643
48645
  const source = t.to === "withdrawn" ? withdraw.get(t.unit)?.source ?? null : t.to === "superseded" ? asked.hints?.get(holder)?.source ?? null : hint?.source ?? null;
48644
- writes2.push({ op: "state", unit: t.unit, from: t.from, to: t.to, reason: reason2, source });
48646
+ const answer = t.to === "withdrawn" ? withdraw.get(t.unit)?.answer ?? null : null;
48647
+ writes2.push({ op: "state", unit: t.unit, from: t.from, to: t.to, reason: reason2, source, answer });
48645
48648
  }
48646
48649
  return { judged, loaded, writes: writes2, redundant, intentOf };
48647
48650
  }
@@ -48724,8 +48727,8 @@ async function reconcile(trx, seeds, cause, asked = {}) {
48724
48727
  await trx.updateTable("unit_replacement").set({ ended_at: sql`max(${at}, started_at)`, end_reason: w.reason, ...endBy }).where("from_unit", "=", w.from).where("to_unit", "=", w.to).where("ended_at", "is", null).execute();
48725
48728
  else if (w.op === "open")
48726
48729
  await trx.insertInto("unit_replacement").values({ from_unit: w.from, to_unit: w.to, ...by, started_at: at }).execute();
48727
- else
48728
- await trx.insertInto("unit_state").values({
48730
+ else {
48731
+ const state = await trx.insertInto("unit_state").values({
48729
48732
  unit_id: w.unit,
48730
48733
  from_state: w.from,
48731
48734
  to_state: w.to,
@@ -48733,7 +48736,10 @@ async function reconcile(trx, seeds, cause, asked = {}) {
48733
48736
  reason: w.reason,
48734
48737
  source_id: w.source,
48735
48738
  ...by
48736
- }).execute();
48739
+ }).returning("id").executeTakeFirstOrThrow();
48740
+ if (w.answer !== null)
48741
+ await trx.insertInto("unit_answer").values({ state_id: state.id, answer_unit: w.answer }).execute();
48742
+ }
48737
48743
  }
48738
48744
  proveSettled(await rowsOf(trx, ids));
48739
48745
  return settled(planned);
@@ -49482,6 +49488,7 @@ async function closeAnswered(trx, runId, units, saved) {
49482
49488
  const questions = new Map((await trx.selectFrom("unit").select(["id", "key", "lifecycle"]).where("id", "in", [...new Set(answering.flatMap((p) => p.answers))]).execute()).map((q) => [q.id, q]));
49483
49489
  const withdraw = new Map;
49484
49490
  const by = new Map;
49491
+ const written = new Map(saved.written.map((w) => [w.key, w.id]));
49485
49492
  const root = new Map;
49486
49493
  const left = new Map;
49487
49494
  for (const p of answering) {
@@ -49495,7 +49502,7 @@ async function closeAnswered(trx, runId, units, saved) {
49495
49502
  else if (why !== null || p.grounds === null)
49496
49503
  left.set(id, left.get(id) ?? `${q.key}: left open: ${why}`);
49497
49504
  else {
49498
- withdraw.set(id, { reason: `answered by ${p.key}`, source: p.grounds });
49505
+ withdraw.set(id, { reason: `answered by ${p.key}`, source: p.grounds, answer: written.get(p.key) });
49499
49506
  by.set(id, p.key);
49500
49507
  root.set(id, id);
49501
49508
  }
@@ -49520,7 +49527,8 @@ async function closeAnswered(trx, runId, units, saved) {
49520
49527
  const answer = by.get(l.from_unit);
49521
49528
  next.set(l.to_unit, {
49522
49529
  reason: `answered by ${answer} (through ${settled2.keys.get(l.from_unit)})`,
49523
- source: from.source
49530
+ source: from.source,
49531
+ answer: from.answer
49524
49532
  });
49525
49533
  by.set(l.to_unit, answer);
49526
49534
  through.set(l.to_unit, settled2.keys.get(l.from_unit) ?? `u${l.from_unit}`);
package/dist/mcp.js CHANGED
@@ -46269,7 +46269,7 @@ var HOST_MARKS = new Set([".orphaned_at", ".in_use"]);
46269
46269
 
46270
46270
  // server/src/sqlite.ts
46271
46271
  var SCHEMA_GENERATION = 2;
46272
- var SCHEMA_REVISION = 12;
46272
+ var SCHEMA_REVISION = 13;
46273
46273
  var sphicaHome = () => process.env.SPHICA_HOME || path3.join(os2.homedir(), ".sphica");
46274
46274
  var dbFile = () => process.env.SPHICA_DB || path3.join(sphicaHome(), "sphica.db");
46275
46275
  function requireRuntime() {
@@ -48993,7 +48993,7 @@ async function linesOf(db, projectId2, entry) {
48993
48993
  const units = await db.selectFrom("unit").select(["id", "key", "kind", "stance", "text", "why", "created_at", "run_id"]).where("project_id", "=", projectId2).where("id", "in", ids).execute();
48994
48994
  const unit = new Map(units.map((u) => [u.id, u]));
48995
48995
  const runs = [...new Set(units.map((u) => u.run_id))];
48996
- const [intents, rows, gaps, states, evidence, adoption, anchors, conflicts, sameRun, outside] = await Promise.all([
48996
+ const [intents, rows, gaps, states, evidence, adoption, anchors, conflicts, sameRun, answered] = await Promise.all([
48997
48997
  db.selectFrom("unit_link").select(["from_unit", "to_unit", "added_at"]).where("kind", "=", "supersedes").where("from_unit", "in", ids).where("to_unit", "in", ids).execute(),
48998
48998
  db.selectFrom("unit_replacement").select(["id", "from_unit", "to_unit", "started_at", "ended_at", "end_reason"]).where("from_unit", "in", ids).where("to_unit", "in", ids).execute(),
48999
48999
  db.selectFrom("unit_replacement_gap").select(["from_unit", "to_unit"]).where("from_unit", "in", ids).where("to_unit", "in", ids).execute(),
@@ -49046,10 +49046,7 @@ async function linesOf(db, projectId2, entry) {
49046
49046
  "b.key as to_key"
49047
49047
  ]).where("l.kind", "=", "conflicts").where((eb) => eb.or([eb("l.from_unit", "in", ids), eb("l.to_unit", "in", ids)])).execute(),
49048
49048
  db.selectFrom("unit").select(["id", "key", "kind", "text", "created_at"]).where("project_id", "=", projectId2).where("extraction", "=", "supported").where("kind", "in", ["finding", "dead_end", "question"]).where("run_id", "in", runs).where("id", "not in", ids).orderBy("created_at", "desc").orderBy("id", "desc").limit(RELATED_READ + 1).execute(),
49049
- db.selectFrom("unit_state as t").innerJoin("unit as o", "o.id", "t.unit_id").select(["t.id", "t.at", "t.to_state", "t.reason", "o.id as unit", "o.key"]).where("o.project_id", "=", projectId2).where("t.run_id", "in", runs).where("o.id", "not in", ids).where((eb) => eb.or([
49050
- eb("o.run_id", "<>", eb.ref("t.run_id")),
49051
- eb("t.to_state", "in", ["superseded", "withdrawn"])
49052
- ])).execute()
49049
+ db.selectFrom("unit_answer as w").innerJoin("unit_state as t", "t.id", "w.state_id").innerJoin("unit as o", "o.id", "t.unit_id").select(["t.id", "t.at", "t.to_state", "t.reason", "o.id as unit", "o.key"]).where("o.project_id", "=", projectId2).where("w.answer_unit", "in", ids).where("o.id", "not in", ids).execute()
49053
49050
  ]);
49054
49051
  const everyPlace = [
49055
49052
  ...new Map(anchors.filter((a) => a.retired_at === null).sort((a, b) => a.id - b.id).map((a) => [JSON.stringify([a.path, a.symbol]), a])).values()
@@ -49223,7 +49220,7 @@ async function linesOf(db, projectId2, entry) {
49223
49220
  text: `${pair}: resolved, ${cut2(c.resolution)}`
49224
49221
  });
49225
49222
  }
49226
- for (const o of outside)
49223
+ for (const o of answered)
49227
49224
  lines2.push({
49228
49225
  at: o.at,
49229
49226
  order: ORDER.state,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "sphica",
3
- "version": "0.6.55",
3
+ "version": "0.6.57",
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",