sphica 0.3.0 → 0.5.0

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "sphica",
-  "version": "0.3.0",
-  "description": "Records conversations automatically and recalls past decisions, rejected options, constraints, and what was said.",
+  "version": "0.5.0",
+  "description": "Records Claude Code and Codex sessions on your machine and keeps past implementation and decisions, with their sources, for your agent to find.",
   "author": {
     "name": "iroha924",
     "email": "shunichi@hir4ta.com"

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "sphica",
-  "version": "0.3.0",
-  "description": "Records conversations automatically and recalls past decisions, rejected options, constraints, and what was said.",
+  "version": "0.5.0",
+  "description": "Records Claude Code and Codex sessions on your machine and keeps past implementation and decisions, with their sources, for your agent to find.",
   "author": {
     "name": "iroha924",
     "email": "shunichi@hir4ta.com"

package/README.md

@@ -9,20 +9,22 @@
 
 English | [日本語](https://github.com/iroha924/sphica/blob/main/README.ja.md)
 
-**Local memory of past decisions for Claude Code and Codex.**
-Sphica records your coding sessions and the decisions made in them.
-You or your agent can then look up what was decided, what was rejected, and why, before making the same call again.
+**Local memory of past implementation and decisions for Claude Code and Codex.**
+Sphica records your coding sessions, and keeps what was decided, rejected, deferred, and built, each record quoting the words it came from.
+Your agent finds those records when it searches, and sees the relevant ones on its own before it edits a file they apply to.
 The database is a single SQLite file on your machine.
 
 ## Features
 
-- **Look things up while you work.** The MCP tools `recall` and `read` let Claude Code and Codex search past decisions, rejected options, constraints, dead ends, and what you or others said in earlier sessions.
-- **Warnings before an edit (Claude Code).** Before the agent edits a file, a hook shows it the constraints recorded for that exact file and any technical debt that was deliberately left there.
-- **Automatic session recording.** Sphica keeps your prompts, the agent's final reply for each turn, and the paths of files changed by the agent's edit tools.
-- **Decision records on request.** `/sphica:trace` saves the decisions, rejected options, constraints, and dead ends of a session, plus where the work stands.
-- **Multi-perspective review.** `/sphica:review` runs a separate reviewer for each focus: correctness, security, and written conventions by default, plus redundancy and past decisions with `full`. When Codex is installed, it offers to repeat the review with Codex.
-- **GitHub and docs import.** `sphica harvest` imports pull requests, issues, and the repository's Markdown files.
+- **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).
+- **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, and a decision counts as adopted only when you said so.
+- **Pull requests too.** `/sphica:harvest <number>` keeps a GitHub pull request (body, comments, reviews, review comments, commits, and the issues 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.
+- **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.
+- **Shown when it matters (Claude Code).** At session start, the current work; before an edit, the active decisions anchored to that file; when your prompt names a recorded option or code symbol, that record.
+- **Search in Japanese and English.** Records carry search words in both languages, so a question in one finds a record written in the other.
+- **Reviews check past decisions.** `/sphica:review` runs a reviewer per focus (correctness, security, written conventions, and past decisions by default; redundancy with `full`), and checks the diff against the records it touches.
 
+Records are never rewritten: a correction is a new record that supersedes the old one, and the history stays.
 The agent is told to treat records as history, not instructions, and to trust the code when a record and the current code disagree.
 
 ## Requirements
@@ -30,11 +32,11 @@ The agent is told to treat records as history, not instructions, and to trust th
 - Node.js 24.15 or later
 - Claude Code or Codex, or both
 - `git`, to identify the repositories you register
-- For `sphica harvest` only: the GitHub CLI (`gh`), signed in with `gh auth login`
+- For `/sphica:harvest` and fetching GitHub sources in `/sphica:glean`: the GitHub CLI (`gh`), signed in with `gh auth login`
 
 ## Install
 
-The plugin ships the MCP server, hooks, and skills. The `sphica` CLI comes from npm and is installed separately. You need both.
+The plugin ships the MCP servers, hooks, and skills. The `sphica` CLI comes from npm and is installed separately. You need both.
 
 **1. Install the CLI**
 
@@ -67,7 +69,7 @@ cd ~/Projects/your-repo
 sphica init
 ```
 
-This creates `~/.sphica/sphica.db` and registers the repository. Running it again leaves both untouched. If the repository has no `origin` remote, give it a name: `sphica init --name <name>`. Add `--sync` to import its GitHub history and docs right away.
+This creates `~/.sphica/sphica.db` and registers the repository. Running it again leaves both untouched. If the repository has no `origin` remote, give it a name: `sphica init --name <name>`.
 
 **4. Check the setup**
 
@@ -75,36 +77,43 @@ This creates `~/.sphica/sphica.db` and registers the repository. Running it agai
 sphica doctor
 ```
 
-`doctor` checks Node.js, the CLI and plugin versions, the database, and the recording queue. Start here whenever something looks wrong.
+`doctor` checks Node.js, the CLI and plugin versions, the database, the recording queue, and the registered projects. Start here whenever something looks wrong.
 
 ## Quick start
 
-Sphica writes sessions to the database only for repositories you register. A registered repository is called a project; run `sphica init` in each repository you want recorded.
+Sphica records sessions only in repositories you register (projects); run `sphica init` in each one.
 
-Then work as usual in Claude Code or Codex. To bring back earlier decisions, ask the agent:
+Work as usual. At the end of a session with something worth keeping, run `/sphica:trace` (`$sphica:trace` in Codex).
+`/sphica:trace pending` lists earlier sessions not traced yet. To keep what a pull request decided, run `/sphica:harvest 123`.
+When you find evidence later ("the ops notes say…", "Kimura said the team agreed"), run `/sphica:glean` with what you found.
+
+To bring back earlier decisions, ask the agent:
 
 - "Did we already decide how to handle retries here?"
-- "Why did we choose this approach?"
-- "What did I say about the migration last week?"
-- "Let's continue where we left off."
+- "Why did we choose this approach, and what did we reject?"
+- "Did we try generating thumbnails in a worker before?"
 
-The agent searches with `recall` and opens full records with `read`. At the end of a session with decisions worth keeping, run `/sphica:trace`.
+### What the agent sees on its own
 
-To import GitHub history and Markdown docs:
+Without being asked, Sphica adds a few past records to what the agent sees, each marked as a past record rather than an instruction:
 
-```bash
-sphica harvest              # every project Sphica can find on this machine
-sphica harvest --cwd .      # only the current repository
-```
+- At session start: the current work and project-wide constraints.
+- On a prompt that names a recorded code symbol, file path, or option.
+- Before the agent reads or edits a file a decision applies to. A read shows each record once per session.
+- Before a review. When you run your own review command (any name containing `review`, or a name listed in the `SPHICA_REVIEW_COMMANDS`
+  environment variable, comma-separated), it gets the decisions your local change touches. `/sphica:review` checks them itself. Claude Code only.
+
+In Codex the same happens at session start, on a prompt, before an `apply_patch` edit, and before a shell command that names such a file.
+Edits made through shell commands are not covered, and there is no review hook: run `$sphica:review`.
 
-Without `--cwd`, Sphica looks for projects directly under `~/Projects` and for projects registered with `--name`. Use `--cwd` for a repository somewhere else.
-Docs are read from the default branch of `origin`, or from the local `HEAD` when there is no `origin`.
+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 not mistaken for "never decided".
 
 ## What gets recorded and where it goes
 
-- **Where.** The database is `~/.sphica/sphica.db`. Records wait in a local queue, `~/.sphica/spool`, until they are written to it. Each machine has its own database, and records are not shared between machines.
-- **What.** Your prompts, the agent's final reply for each turn, and the paths of edited files. Background-task notifications and messages from other agents are skipped when Sphica recognizes their format.
-- **Unregistered repositories.** Sessions in a repository you have not registered stay in the queue. They are written to the database after you register the repository. Held records are dropped after 30 days, and when more than 1,000 are waiting the oldest go first.
+- **Where.** The database is `~/.sphica/sphica.db`. Records wait in a local queue, `~/.sphica/spool`, until they are written to it. Each machine has its own database; nothing is shared between machines.
+- **What.** Your prompts, the agent's final reply for each turn, and the paths of changed files. Background-task notifications and messages from other agents are skipped when Sphica recognizes their format. Replies in the middle of a turn, and files created and deleted within one turn, are not seen.
+- **What was shown.** Each automatic delivery is logged by which records it showed, not their text.
+- **Unregistered repositories.** Sessions in a repository you have not registered stay in the queue and are written after you register it. Held records are dropped after 30 days, and when more than 1,000 are waiting the oldest go first.
 - **Secrets.** Only secrets with a recognizable shape are masked:
   - keys with known prefixes
   - `KEY=…` and `"password": …` assignments
@@ -113,12 +122,21 @@ Docs are read from the default branch of `origin`, or from the local `HEAD` when
   - `mysql -p`
 
   **Anything else is stored as typed, so do not paste secrets into a session.**
-- **Network.** Sphica has no account, no hosted service, and no telemetry, and makes no network connections itself. Two commands call other tools that may: `sphica harvest` runs `git fetch` and `gh api` with your credentials, and `sphica doctor` runs `npm` and `claude` to check installed versions.
-- **Text written by others.** Pull request and issue text imported by `harvest` may come from anyone. It is passed to the agent as data, and the MCP server cannot write to the database.
+- **Network.** Sphica has no account, no hosted service, and no telemetry, and makes no network connections itself. `/sphica:harvest` and `/sphica:glean` run `gh api` with your credentials to read pull requests and issues, and `sphica doctor` runs `npm` and `claude` to check installed versions.
+- **Text written by others.** Pull request and issue text may come from anyone. It is kept as a source and passed to the agent as data, never as instructions, and only the owner's or a maintainer's words can adopt a decision.
 
-To delete a project's data, run `sphica project forget <name>`, where `<name>` is shown by `sphica project list`. Without `--yes`, it only shows how many records would be deleted. It deletes records in the database only. Records still waiting in `~/.sphica/spool` stay there and can be imported again if you register the repository again.
+## Limits in 0.5.0
 
-Before you stop using a machine, run `sphica capture flush` until `sphica doctor` shows no records waiting to be sent. Each run writes up to 500 records. Records from unregistered repositories are not written, so register those repositories first if you want to keep them.
+- Structured records exist only for what you traced, harvested, or gleaned. Everything else is searchable only as captured text (`search` with `sources: true`).
+- In Codex, a shell command that names a file gets its decisions even when the command does not read it, and edits made through shell commands get none.
+- In Codex, `$sphica:trace`, `$sphica:harvest`, and `$sphica:glean` write only when Codex tells Sphica which directory the session is in. Codex 0.157.1 does, through an experimental MCP capability; if a later Codex stops, they stop with a message and write nothing.
+- Showing a record does not make the agent follow it. In our evaluation Codex received and found an earlier decision against a request, and still carried out the request as asked.
+- A code location in a record is checked against your working tree when it is read ("located", "moved", "missing"). A located symbol does not prove the decision still holds.
+
+## Upgrading from 0.4
+
+0.5.0 keeps records in a new format. A 0.4 database is refused and left unchanged; its records are not carried over.
+Move `~/.sphica/sphica.db` aside (keep it if you want the old data), then run `sphica init` again in each repository.
 
 ## Updating
 
@@ -142,47 +160,41 @@ codex plugin marketplace upgrade sphica
 codex plugin add sphica@sphica
 ```
 
-Restart open sessions afterwards. When a release changes the database schema, the CLI asks you to run `sphica db migrate`. Back up `~/.sphica/sphica.db` before you run it.
+Restart open sessions afterwards.
 
 ## Uninstalling
 
 ```bash
-npm uninstall -g sphica
+sphica uninstall
 ```
 
-Claude Code:
+This deletes `~/.sphica` (the database and the recording queue) after asking, and shows the commands that remove the rest:
 
 ```bash
-claude plugin uninstall sphica@sphica
-```
-
-Codex:
-
-```bash
-codex plugin remove sphica@sphica
+claude plugin uninstall sphica@sphica && claude plugin marketplace remove sphica
+codex plugin remove sphica@sphica && codex plugin marketplace remove sphica
+npm uninstall -g sphica
 ```
 
-Your records stay in `~/.sphica/` until you delete that directory yourself.
-
 ## Troubleshooting
 
 Run `sphica doctor` first. It shows which part is out of date or not working. Common cases:
 
 - **`sphica: command not found`.** The plugin does not put the CLI on your PATH. Run `npm i -g sphica`.
-- **Nothing is recorded.** Check that the repository is registered with `sphica project list`. In Codex, also check that the hooks are trusted in `/hooks`.
-- **The MCP server reports an older version.** Restart the session, or run `/reload-plugins` in Claude Code.
-- **A search finds nothing.** Search matches words. Try other words, English and Japanese, or shorter terms. An empty result doesn't mean nothing was recorded.
+- **Nothing is recorded.** Check that `sphica doctor` lists the repository under Projects. In Codex, also check that the hooks are trusted in `/hooks`.
+- **The MCP servers report an older version.** Restart the session, or run `/reload-plugins` in Claude Code.
+- **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.
+- **`doctor` says the full-text index is broken.** Run `sphica doctor --reindex`.
 
 ## Commands
 
 | Command | What it does |
 |---|---|
 | `sphica init` | Create the database and register the current repository |
-| `sphica doctor` | Check versions, the database, recording, and each project's last import |
-| `sphica harvest` | Import GitHub pull requests, issues, and Markdown docs |
-| `sphica advice` | See how often the edit hook showed constraints |
+| `sphica doctor` | Check versions, the database, recording, and each registered project |
+| `sphica uninstall` | Delete `~/.sphica` and show how to remove the plugin and the CLI |
 
-Run `sphica --help` for these, `sphica -H` for every command (managing projects and people, and the ones agents and maintenance use), and `sphica <command> --help` for each command's options.
+Everything else runs inside Claude Code and Codex, through the `/sphica:*` commands and Sphica's MCP tools.
 
 ## Security
 

package/THIRD_PARTY_NOTICES.md

@@ -68,7 +68,6 @@ This file is generated by `node scripts/third-party-notices.mjs`. Do not edit it
 | json-schema-traverse | 1.0.0 | MIT |
 | json-schema-typed | 8.0.2 | BSD-2-Clause |
 | kysely | 0.29.6 | MIT |
-| marked | 18.0.14 | MIT |
 | math-intrinsics | 1.1.0 | MIT |
 | media-typer | 1.1.1 | MIT |
 | merge-descriptors | 2.0.0 | MIT |
@@ -2092,58 +2091,6 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
-## marked 18.0.14
-
-SPDX: MIT
-Source: https://github.com/markedjs/marked
-
-```
-# License information
-
-## Contribution License Agreement
-
-If you contribute code to this project, you are implicitly allowing your code
-to be distributed under the MIT license. You are also implicitly verifying that
-all code is your original work. `</legalese>`
-
-## Marked
-
-Copyright (c) 2018+, MarkedJS (https://github.com/markedjs/)
-Copyright (c) 2011-2018, Christopher Jeffrey (https://github.com/chjj/)
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
-
-## Markdown
-
-Copyright © 2004, John Gruber
-http://daringfireball.net/
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
-
-* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
-* Neither the name “Markdown” nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
-
-This software is provided by the copyright holders and contributors “as is” and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the copyright owner or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.
-```
-
 ## math-intrinsics 1.1.0
 
 SPDX: MIT