sphica 0.6.50 → 0.6.52
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/.claude-plugin/plugin.json +1 -1
- package/.codex-plugin/plugin.json +1 -1
- package/README.md +6 -4
- package/dist/deliver.js +42 -4
- package/dist/mcp-record.js +190 -39
- package/dist/mcp.js +7 -6
- package/package.json +1 -1
- package/skills/glean/SKILL.md +1 -1
- package/skills/harvest/SKILL.md +1 -1
- package/skills/trace/SKILL.md +21 -10
|
@@ -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.
|
|
4
|
+
"version": "0.6.52",
|
|
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",
|
package/README.md
CHANGED
|
@@ -20,7 +20,7 @@ The database is a single SQLite file on your machine.
|
|
|
20
20
|
|
|
21
21
|
- **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
22
|
- **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
|
|
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).
|
|
24
24
|
- **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
25
|
- **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
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.
|
|
@@ -96,7 +96,7 @@ sphica doctor
|
|
|
96
96
|
|
|
97
97
|
Only sessions in repositories you register (projects) go into Sphica's database; run `sphica init` in each one.
|
|
98
98
|
|
|
99
|
-
Work as usual.
|
|
99
|
+
Work as usual. A new session asks the agent to trace earlier sessions on its own (in Codex, a session started from the terminal). To keep something right away, run `/sphica:trace` (`$sphica:trace` in Codex).
|
|
100
100
|
`/sphica:trace pending` lists earlier sessions not traced yet. To keep what a pull request decided, run `/sphica:harvest 123`.
|
|
101
101
|
When you find evidence later ("the ops notes say…", "Kimura said the team agreed"), run `/sphica:glean` with what you found.
|
|
102
102
|
|
|
@@ -110,7 +110,7 @@ To bring back earlier decisions, ask the agent:
|
|
|
110
110
|
|
|
111
111
|
Without being asked, Sphica adds a few past records to what the agent sees, each marked as a past record rather than an instruction:
|
|
112
112
|
|
|
113
|
-
- At session start: the current work and project-wide constraints, and
|
|
113
|
+
- 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).
|
|
114
114
|
- On a prompt that names a recorded code symbol, file path, or option.
|
|
115
115
|
- 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.
|
|
116
116
|
- 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.
|
|
@@ -147,7 +147,9 @@ The agent searches with Sphica's `search` and opens full records with `read`. `s
|
|
|
147
147
|
- 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.
|
|
148
148
|
- Showing a record does not make the agent follow it.
|
|
149
149
|
- Whether the agent decided something itself is judged from what its reply says, so it can be wrong.
|
|
150
|
-
- An AI's decision is adopted only when the trace runs in an interactive Claude Code session. In headless and SDK runs and
|
|
150
|
+
- 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.
|
|
151
|
+
- 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.
|
|
152
|
+
- In Codex, Sphica's settings are environment variables (`SPHICA_AUTO_TRACE`, `SPHICA_SHELL_WRITE_DELIVERY`; 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.
|
|
151
153
|
- 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.
|
|
152
154
|
- The automatic trace uses your subscription's usage.
|
|
153
155
|
- 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.
|
package/dist/deliver.js
CHANGED
|
@@ -4,6 +4,7 @@
|
|
|
4
4
|
import fs9 from "node:fs";
|
|
5
5
|
import os3 from "node:os";
|
|
6
6
|
import path10 from "node:path";
|
|
7
|
+
import { fileURLToPath as fileURLToPath2 } from "node:url";
|
|
7
8
|
|
|
8
9
|
// server/node_modules/kysely/dist/util/object-utils.js
|
|
9
10
|
function isUndefined(obj) {
|
|
@@ -13820,7 +13821,37 @@ function rotateTrial(dir2, file) {
|
|
|
13820
13821
|
} catch {}
|
|
13821
13822
|
}
|
|
13822
13823
|
var AUTO_TRACE_OFF = new Set(["off", "0", "false", "no"]);
|
|
13823
|
-
var AUTO_TRACE = (n) => `- ${n} earlier session${n === 1 ? "" : "s"} of this project ${n === 1 ? "waits" : "wait"} to be traced. After the user's request is done, run the trace Skill on your own for the oldest (at most 2), as its "On your own" section says, without asking the user.`;
|
|
13824
|
+
var AUTO_TRACE = (n, skill) => `- ${n} earlier session${n === 1 ? "" : "s"} of this project ${n === 1 ? "waits" : "wait"} to be traced. After the user's request is done, ${skill ? `read \`${skill}\` and run it` : "run the trace Skill"} on your own for the oldest (at most 2), as its "On your own" section says, without asking the user.`;
|
|
13825
|
+
var SESSION_META_BYTES = 256 * 1024;
|
|
13826
|
+
function codexInteractive(input) {
|
|
13827
|
+
const file = input.transcript_path;
|
|
13828
|
+
if (!input.session_id || typeof file !== "string" || !path10.isAbsolute(file))
|
|
13829
|
+
return false;
|
|
13830
|
+
let fd;
|
|
13831
|
+
try {
|
|
13832
|
+
if (!fs9.lstatSync(file).isFile())
|
|
13833
|
+
return false;
|
|
13834
|
+
fd = fs9.openSync(file, "r");
|
|
13835
|
+
const buffer = Buffer.alloc(SESSION_META_BYTES);
|
|
13836
|
+
const read = fs9.readSync(fd, buffer, 0, SESSION_META_BYTES, 0);
|
|
13837
|
+
const end = buffer.subarray(0, read).indexOf(10);
|
|
13838
|
+
if (end < 0)
|
|
13839
|
+
return false;
|
|
13840
|
+
const line2 = JSON.parse(buffer.subarray(0, end).toString("utf8"));
|
|
13841
|
+
const payload = line2?.payload;
|
|
13842
|
+
return line2?.type === "session_meta" && payload?.id === input.session_id && payload.originator === "codex-tui" && payload.thread_source === "user";
|
|
13843
|
+
} catch {
|
|
13844
|
+
return false;
|
|
13845
|
+
} finally {
|
|
13846
|
+
if (fd !== undefined)
|
|
13847
|
+
fs9.closeSync(fd);
|
|
13848
|
+
}
|
|
13849
|
+
}
|
|
13850
|
+
var namable = (file) => Buffer.byteLength(file) <= 1000 && !/[\p{Cc}`]/u.test(file) ? file : null;
|
|
13851
|
+
function traceSkill(here2 = path10.dirname(fileURLToPath2(import.meta.url))) {
|
|
13852
|
+
const file = [path10.join(here2, ".."), path10.join(here2, "..", "..", "plugin")].map((root) => path10.join(root, "skills", "trace", "SKILL.md")).find((f) => fs9.existsSync(f));
|
|
13853
|
+
return file ? namable(file) : null;
|
|
13854
|
+
}
|
|
13824
13855
|
async function waiting(db, projectId2, place) {
|
|
13825
13856
|
if (!place.owner)
|
|
13826
13857
|
return "";
|
|
@@ -13833,7 +13864,7 @@ async function waiting(db, projectId2, place) {
|
|
|
13833
13864
|
return "";
|
|
13834
13865
|
if (!markOnce("auto-trace", `${path10.resolve(place.file)}\x00${place.key}\x00${place.host}\x00${place.auto}`))
|
|
13835
13866
|
return "";
|
|
13836
|
-
return AUTO_TRACE(total);
|
|
13867
|
+
return AUTO_TRACE(total, place.skill);
|
|
13837
13868
|
}
|
|
13838
13869
|
const n = (await pendingCount(db, projectId2)).recent;
|
|
13839
13870
|
if (!n)
|
|
@@ -14123,13 +14154,17 @@ async function deliver(input, host = "claude-code", file = dbFile()) {
|
|
|
14123
14154
|
}
|
|
14124
14155
|
const reader = db;
|
|
14125
14156
|
const session = input.session_id;
|
|
14157
|
+
const asksToTrace = name === "SessionStart" && input.source === "startup" && ![process.env.CLAUDE_PLUGIN_OPTION_AUTO_TRACE, process.env.SPHICA_AUTO_TRACE].some((v) => AUTO_TRACE_OFF.has((v ?? "").trim().toLowerCase()));
|
|
14158
|
+
const skill = asksToTrace && host === "codex" && codexInteractive(input) ? traceSkill() : null;
|
|
14159
|
+
const newInteractive = asksToTrace && (host === "claude-code" ? process.env.CLAUDE_CODE_ENTRYPOINT === "cli" : skill !== null);
|
|
14126
14160
|
const make = async () => event === "pre_edit" ? await beforeEdit(reader, pid, rels) : event === "pre_read" ? await beforeRead(reader, pid, rels, sessionId(pid, host, session), agentOf(input), shell ? "named" : "reading") : event === "prompt" ? await onPrompt(reader, pid, place.root, input.prompt ?? "") : call ? await beforeReview(reader, pid, place.root, call) : {
|
|
14127
14161
|
...await atStart(reader, pid, branchOf(place.root), {
|
|
14128
14162
|
file,
|
|
14129
14163
|
key: place.key,
|
|
14130
14164
|
host,
|
|
14131
14165
|
subagent: name === "SubagentStart",
|
|
14132
|
-
auto:
|
|
14166
|
+
auto: newInteractive ? session : null,
|
|
14167
|
+
...skill ? { skill } : {},
|
|
14133
14168
|
owner: name !== "SubagentStart" && isOwnerTurn(input, undefined, undefined, host === "codex" ? process.env.CODEX_THREAD_ID : undefined)
|
|
14134
14169
|
}),
|
|
14135
14170
|
reason: name === "SubagentStart" ? "subagent" : input.source && START_SOURCES.has(input.source) ? input.source : null
|
|
@@ -14178,10 +14213,13 @@ export {
|
|
|
14178
14213
|
CONFIRM,
|
|
14179
14214
|
CONFIRM_GOLD,
|
|
14180
14215
|
anchoredRules,
|
|
14216
|
+
codexInteractive,
|
|
14181
14217
|
deliver,
|
|
14182
14218
|
deliverableIds,
|
|
14183
14219
|
deliverablePaths,
|
|
14184
14220
|
leadFor,
|
|
14221
|
+
namable,
|
|
14185
14222
|
namedRecords,
|
|
14186
|
-
recordLines
|
|
14223
|
+
recordLines,
|
|
14224
|
+
traceSkill
|
|
14187
14225
|
};
|
package/dist/mcp-record.js
CHANGED
|
@@ -34726,14 +34726,17 @@ var record3 = (v) => v !== null && typeof v === "object" && !Array.isArray(v) ?
|
|
|
34726
34726
|
function callerOf(meta3, env = process.env) {
|
|
34727
34727
|
const codex = record3(record3(meta3)?.["x-codex-turn-metadata"]);
|
|
34728
34728
|
if (codex) {
|
|
34729
|
+
const session2 = text(codex.session_id);
|
|
34730
|
+
const source = text(codex.thread_source);
|
|
34729
34731
|
const trigger = text(codex.turn_trigger);
|
|
34732
|
+
const own2 = session2 !== null && session2 === text(codex.thread_id) && source === "user";
|
|
34730
34733
|
return {
|
|
34731
34734
|
host: "codex",
|
|
34732
|
-
session:
|
|
34733
|
-
turn: text(codex.turn_id),
|
|
34735
|
+
session: session2,
|
|
34736
|
+
turn: own2 ? text(codex.turn_id) : null,
|
|
34734
34737
|
toolUseId: null,
|
|
34735
|
-
mode: trigger === "exec" ? "headless" : "unknown",
|
|
34736
|
-
raw: trigger
|
|
34738
|
+
mode: trigger === "exec" ? "headless" : own2 && trigger === "user" ? "interactive" : "unknown",
|
|
34739
|
+
raw: own2 || trigger === null && source === null ? trigger : text(`${trigger ?? "none"}:${source ?? "none"}`)
|
|
34737
34740
|
};
|
|
34738
34741
|
}
|
|
34739
34742
|
const toolUseId = text(record3(meta3)?.["claudecode/toolUseId"]);
|
|
@@ -48875,6 +48878,7 @@ var Unit = exports_external.object({
|
|
|
48875
48878
|
aliases: exports_external.array(exports_external.string()).max(12).default([]),
|
|
48876
48879
|
supersedes: exports_external.string().min(1).optional(),
|
|
48877
48880
|
conflicts: exports_external.array(exports_external.string().min(1)).max(5).default([]),
|
|
48881
|
+
answers: exports_external.array(exports_external.string().min(1)).max(5).default([]),
|
|
48878
48882
|
fields: exports_external.array(exports_external.object({
|
|
48879
48883
|
name: exports_external.string().regex(FIELD_NAME2, "a defined field name"),
|
|
48880
48884
|
value: text3(200),
|
|
@@ -48892,16 +48896,16 @@ var FieldDef = exports_external.object({
|
|
|
48892
48896
|
}).strict();
|
|
48893
48897
|
var Work = exports_external.object({
|
|
48894
48898
|
key: exports_external.string().regex(KEY),
|
|
48895
|
-
title: text3(200),
|
|
48896
|
-
goal: text3(1000),
|
|
48897
|
-
current: text3(2000),
|
|
48898
|
-
next: exports_external.array(text3(500)).max(10).
|
|
48899
|
-
status: exports_external.enum(WORK_STATUSES)
|
|
48899
|
+
title: text3(200).optional(),
|
|
48900
|
+
goal: text3(1000).optional(),
|
|
48901
|
+
current: text3(2000).optional(),
|
|
48902
|
+
next: exports_external.array(text3(500)).max(10).optional(),
|
|
48903
|
+
status: exports_external.enum(WORK_STATUSES).optional()
|
|
48900
48904
|
}).strict();
|
|
48901
48905
|
var Record = exports_external.object({
|
|
48902
48906
|
field_defs: exports_external.array(FieldDef).max(10).default([]),
|
|
48903
48907
|
units: exports_external.array(Unit).max(50),
|
|
48904
|
-
work: Work.optional()
|
|
48908
|
+
work: exports_external.preprocess((w) => w === undefined || Array.isArray(w) ? w : [w], exports_external.array(Work).min(1).max(10).optional())
|
|
48905
48909
|
}).strict();
|
|
48906
48910
|
var cited = (body, quote) => quote.trim() ? locate(body, quote) : null;
|
|
48907
48911
|
function anchorProblem(facts, a) {
|
|
@@ -48958,7 +48962,7 @@ async function checkRecord(db, target, raw, facts = prepareRecord(target.root, r
|
|
|
48958
48962
|
errors: parsed.error.issues.map((i) => `${preview(i.path.join(".") || "record", 300)}: ${preview(i.message, 600)}`),
|
|
48959
48963
|
problems,
|
|
48960
48964
|
units: [],
|
|
48961
|
-
work:
|
|
48965
|
+
work: [],
|
|
48962
48966
|
fieldDefs: [],
|
|
48963
48967
|
facts
|
|
48964
48968
|
};
|
|
@@ -49050,7 +49054,7 @@ async function checkRecord(db, target, raw, facts = prepareRecord(target.root, r
|
|
|
49050
49054
|
for (const n of new Set(names.filter((n2, i) => names.indexOf(n2) !== i)))
|
|
49051
49055
|
errors3.push(`field_defs ${n}: defined twice in this record`);
|
|
49052
49056
|
const linked = [
|
|
49053
|
-
...new Set(record4.units.flatMap((u) => [...u.supersedes ? [u.supersedes] : [], ...u.conflicts]))
|
|
49057
|
+
...new Set(record4.units.flatMap((u) => [...u.supersedes ? [u.supersedes] : [], ...u.conflicts, ...u.answers]))
|
|
49054
49058
|
];
|
|
49055
49059
|
const others = new Map((linked.length ? await db.selectFrom("unit as o").select(["o.id", "o.key", "o.kind", "o.lifecycle"]).where("o.project_id", "=", target.projectId).where("o.key", "in", linked).execute() : []).map((u) => [u.key, u]));
|
|
49056
49060
|
const units = [];
|
|
@@ -49216,6 +49220,16 @@ async function checkRecord(db, target, raw, facts = prepareRecord(target.root, r
|
|
|
49216
49220
|
errors3.push(`${key}: conflicts with ${k}, which is not a record of this project`);
|
|
49217
49221
|
return other ? [other.id] : [];
|
|
49218
49222
|
});
|
|
49223
|
+
if (u.answers.length && u.kind === "question")
|
|
49224
|
+
errors3.push(`${key}: a question does not answer another; one that replaces it supersedes it`);
|
|
49225
|
+
const answers = [...new Set(u.answers)].flatMap((k) => {
|
|
49226
|
+
const other = others.get(k);
|
|
49227
|
+
if (!other)
|
|
49228
|
+
errors3.push(`${key}: answers ${k}, which is not a record of this project`);
|
|
49229
|
+
else if (other.kind !== "question")
|
|
49230
|
+
errors3.push(`${key}: answers ${k}, a ${other.kind}; only a question is answered`);
|
|
49231
|
+
return other?.kind === "question" ? [other.id] : [];
|
|
49232
|
+
});
|
|
49219
49233
|
for (const x of adoption.filter((x2) => x2.route === "agent")) {
|
|
49220
49234
|
const why = await agentRefusal(db, u, x, sources.get(x.source), evidence, anchors);
|
|
49221
49235
|
if (!why)
|
|
@@ -49223,6 +49237,7 @@ async function checkRecord(db, target, raw, facts = prepareRecord(target.root, r
|
|
|
49223
49237
|
problems.push(`${key}: the AI's adoption in s${x.source} left out, so it stays a candidate: ${why}`);
|
|
49224
49238
|
adoption.splice(adoption.indexOf(x), 1);
|
|
49225
49239
|
}
|
|
49240
|
+
const grounds = (["decision", "constraint"].includes(u.kind) ? adoption.find((x) => x.route !== "agent") : evidence[0])?.source ?? null;
|
|
49226
49241
|
const fields = [];
|
|
49227
49242
|
for (const f of u.fields) {
|
|
49228
49243
|
const at = `${key}: field ${f.name}`;
|
|
@@ -49271,12 +49286,24 @@ async function checkRecord(db, target, raw, facts = prepareRecord(target.root, r
|
|
|
49271
49286
|
aliases: aliases.filter((a) => !bad.includes(a)),
|
|
49272
49287
|
supersedes,
|
|
49273
49288
|
conflicts,
|
|
49289
|
+
answers,
|
|
49290
|
+
grounds,
|
|
49274
49291
|
fields
|
|
49275
49292
|
});
|
|
49276
49293
|
}
|
|
49277
|
-
if (
|
|
49294
|
+
if (target.origin !== "trace" && record4.units.some((u) => u.answers.length))
|
|
49295
|
+
errors3.push("answers: only trace closes a question");
|
|
49296
|
+
const work = record4.work ?? [];
|
|
49297
|
+
if (work.length && target.origin !== "trace")
|
|
49278
49298
|
errors3.push("work: only trace records work");
|
|
49279
|
-
|
|
49299
|
+
const named = work.map((w) => w.key);
|
|
49300
|
+
for (const k of new Set(named.filter((k2, i) => named.indexOf(k2) !== i)))
|
|
49301
|
+
errors3.push(`work ${k}: the key appears twice`);
|
|
49302
|
+
const known = new Set((work.length ? await db.selectFrom("work").select("key").where("project_id", "=", target.projectId).where("key", "in", named).execute() : []).map((w) => w.key));
|
|
49303
|
+
for (const w of work)
|
|
49304
|
+
if (!known.has(w.key) && [w.title, w.goal, w.current, w.status].includes(undefined))
|
|
49305
|
+
errors3.push(`work ${w.key}: a new key needs title, goal, current, and status`);
|
|
49306
|
+
return { errors: errors3, problems, units, work, fieldDefs, facts };
|
|
49280
49307
|
}
|
|
49281
49308
|
function fieldTypeError(type, values, v) {
|
|
49282
49309
|
if (type === "integer" && !/^-?[0-9]+$/.test(v))
|
|
@@ -49370,6 +49397,115 @@ async function settleSaved(trx, runId, saved, more = {}) {
|
|
|
49370
49397
|
saved.superseded.push(c.key);
|
|
49371
49398
|
return settled2;
|
|
49372
49399
|
}
|
|
49400
|
+
var OLDER_QUESTIONS = 10;
|
|
49401
|
+
async function closeAnswered(trx, runId, units, saved) {
|
|
49402
|
+
const answering = units.filter((p) => p.answers.length);
|
|
49403
|
+
if (!answering.length)
|
|
49404
|
+
return;
|
|
49405
|
+
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]));
|
|
49406
|
+
const withdraw = new Map;
|
|
49407
|
+
const by = new Map;
|
|
49408
|
+
const root = new Map;
|
|
49409
|
+
const left = new Map;
|
|
49410
|
+
for (const p of answering) {
|
|
49411
|
+
const why = !saved.active.includes(p.key) ? `${p.key} did not become active` : p.grounds !== null ? null : `${p.key} is an AI's decision, and a question closes only on the owner's or a maintainer's adoption`;
|
|
49412
|
+
for (const id of p.answers) {
|
|
49413
|
+
const q = questions.get(id);
|
|
49414
|
+
if (!q || withdraw.has(id))
|
|
49415
|
+
continue;
|
|
49416
|
+
if (q.lifecycle !== "active" && q.lifecycle !== "candidate")
|
|
49417
|
+
left.set(id, `${q.key}: already ${q.lifecycle}, so ${p.key} closes nothing there`);
|
|
49418
|
+
else if (why !== null || p.grounds === null)
|
|
49419
|
+
left.set(id, left.get(id) ?? `${q.key}: left open: ${why}`);
|
|
49420
|
+
else {
|
|
49421
|
+
withdraw.set(id, { reason: `answered by ${p.key}`, source: p.grounds });
|
|
49422
|
+
by.set(id, p.key);
|
|
49423
|
+
root.set(id, id);
|
|
49424
|
+
}
|
|
49425
|
+
}
|
|
49426
|
+
}
|
|
49427
|
+
const moved = new Map;
|
|
49428
|
+
const through = new Map;
|
|
49429
|
+
let asked = new Map(withdraw);
|
|
49430
|
+
for (let round = 0;asked.size; round++) {
|
|
49431
|
+
if (round > OLDER_QUESTIONS) {
|
|
49432
|
+
const named = root.get([...asked.keys()][0]);
|
|
49433
|
+
throw new SaveRefused(`${by.get(named)}: answering ${questions.get(named)?.key} would close more than ${OLDER_QUESTIONS} older questions it replaced; leave it out of answers, and the owner can withdraw them`);
|
|
49434
|
+
}
|
|
49435
|
+
const settled2 = await reconcile(trx, [...asked.keys()], { runId }, { withdraw: asked });
|
|
49436
|
+
for (const c of settled2.changes)
|
|
49437
|
+
moved.set(c.id, { key: c.key, before: moved.get(c.id)?.before ?? c.before, after: c.after });
|
|
49438
|
+
const back = settled2.changes.filter((c) => c.before === "superseded" && c.after !== "superseded");
|
|
49439
|
+
const older = back.length ? await trx.selectFrom("unit_link").select(["from_unit", "to_unit"]).where("kind", "=", "supersedes").where("from_unit", "in", [...asked.keys()]).where("to_unit", "in", back.map((c) => c.id)).orderBy("to_unit").orderBy("from_unit").execute() : [];
|
|
49440
|
+
const next = new Map;
|
|
49441
|
+
for (const l of older) {
|
|
49442
|
+
const from = asked.get(l.from_unit);
|
|
49443
|
+
const answer = by.get(l.from_unit);
|
|
49444
|
+
next.set(l.to_unit, {
|
|
49445
|
+
reason: `answered by ${answer} (through ${settled2.keys.get(l.from_unit)})`,
|
|
49446
|
+
source: from.source
|
|
49447
|
+
});
|
|
49448
|
+
by.set(l.to_unit, answer);
|
|
49449
|
+
through.set(l.to_unit, settled2.keys.get(l.from_unit) ?? `u${l.from_unit}`);
|
|
49450
|
+
root.set(l.to_unit, root.get(l.from_unit));
|
|
49451
|
+
}
|
|
49452
|
+
asked = next;
|
|
49453
|
+
}
|
|
49454
|
+
for (const [id, answer] of by) {
|
|
49455
|
+
const m = moved.get(id);
|
|
49456
|
+
if (m?.after === "withdrawn")
|
|
49457
|
+
saved.closed.push(`${m.key}: withdrawn, answered by ${answer}${through.has(id) ? ` through ${through.get(id)}` : ""}`);
|
|
49458
|
+
}
|
|
49459
|
+
for (const [id, m] of moved)
|
|
49460
|
+
if (!(by.has(id) && m.after === "withdrawn") && m.after !== m.before)
|
|
49461
|
+
saved.closed.push(`${m.key}: now ${m.after} (was ${m.before})`);
|
|
49462
|
+
for (const [id, note] of left)
|
|
49463
|
+
if (moved.get(id)?.after !== "withdrawn")
|
|
49464
|
+
saved.notes.push(note);
|
|
49465
|
+
}
|
|
49466
|
+
async function saveWork(trx, target, runId, items, now, saved) {
|
|
49467
|
+
if (!items.length)
|
|
49468
|
+
return;
|
|
49469
|
+
const traced = target.sessionId ? await trx.selectFrom("session").select(["started_at", "branch"]).where("id", "=", target.sessionId).executeTakeFirst() : undefined;
|
|
49470
|
+
const stamp = { branch: traced?.branch ?? null, run_id: runId, updated_at: now };
|
|
49471
|
+
for (const w of items) {
|
|
49472
|
+
const held = await trx.selectFrom("work as w").leftJoin("extraction_run as r", "r.id", "w.run_id").leftJoin("session as s", "s.id", "r.session_id").select(["w.id", "w.title", "w.goal", "w.current", "w.next", "w.status", "s.started_at"]).where("w.project_id", "=", target.projectId).where("w.key", "=", w.key).executeTakeFirst();
|
|
49473
|
+
if (!held) {
|
|
49474
|
+
await trx.insertInto("work").values({
|
|
49475
|
+
project_id: target.projectId,
|
|
49476
|
+
key: w.key,
|
|
49477
|
+
title: w.title,
|
|
49478
|
+
goal: w.goal,
|
|
49479
|
+
current: w.current,
|
|
49480
|
+
next: JSON.stringify(w.next ?? []),
|
|
49481
|
+
status: w.status,
|
|
49482
|
+
...stamp
|
|
49483
|
+
}).execute();
|
|
49484
|
+
saved.work.push(`work ${w.key}: created`);
|
|
49485
|
+
continue;
|
|
49486
|
+
}
|
|
49487
|
+
if ([w.title, w.goal, w.current, w.next, w.status].every((v) => v === undefined)) {
|
|
49488
|
+
saved.notes.push(`work ${w.key}: nothing to change: only its key was given`);
|
|
49489
|
+
continue;
|
|
49490
|
+
}
|
|
49491
|
+
const mine = traced?.started_at;
|
|
49492
|
+
if (held.started_at && mine && held.started_at > mine) {
|
|
49493
|
+
saved.notes.push(`work ${w.key}: left as it is: a newer session's state is already saved`);
|
|
49494
|
+
continue;
|
|
49495
|
+
}
|
|
49496
|
+
const stored = typeof held.next === "string" ? held.next : JSON.stringify(held.next);
|
|
49497
|
+
const row = {
|
|
49498
|
+
title: w.title ?? held.title,
|
|
49499
|
+
goal: w.goal ?? held.goal,
|
|
49500
|
+
current: w.current ?? held.current,
|
|
49501
|
+
next: w.next ? JSON.stringify(w.next) : stored,
|
|
49502
|
+
status: w.status ?? held.status
|
|
49503
|
+
};
|
|
49504
|
+
const same = row.title === held.title && row.goal === held.goal && row.current === held.current && row.next === stored && row.status === held.status;
|
|
49505
|
+
await trx.updateTable("work").set(same ? { run_id: runId } : { ...row, ...stamp }).where("id", "=", held.id).execute();
|
|
49506
|
+
saved.work.push(`work ${w.key}: ${same ? "confirmed, nothing changed" : "updated"}`);
|
|
49507
|
+
}
|
|
49508
|
+
}
|
|
49373
49509
|
async function saveRecord(trx, target, runId, checked, looked, { settle: settle2 = true } = {}) {
|
|
49374
49510
|
if (checked.errors.length)
|
|
49375
49511
|
throw new Error(`The record is not valid:
|
|
@@ -49382,6 +49518,9 @@ ${checked.errors.map((e) => ` ${e}`).join(`
|
|
|
49382
49518
|
quarantined: [],
|
|
49383
49519
|
superseded: [],
|
|
49384
49520
|
anchorProblems: [],
|
|
49521
|
+
closed: [],
|
|
49522
|
+
notes: [],
|
|
49523
|
+
work: [],
|
|
49385
49524
|
written: []
|
|
49386
49525
|
};
|
|
49387
49526
|
const cited2 = new Set;
|
|
@@ -49534,26 +49673,11 @@ ${checked.errors.map((e) => ` ${e}`).join(`
|
|
|
49534
49673
|
}
|
|
49535
49674
|
});
|
|
49536
49675
|
}
|
|
49537
|
-
if (settle2)
|
|
49676
|
+
if (settle2) {
|
|
49538
49677
|
await settleSaved(trx, runId, saved);
|
|
49539
|
-
|
|
49540
|
-
const w = checked.work;
|
|
49541
|
-
const traced = target.sessionId ? await trx.selectFrom("session").select(["started_at", "branch"]).where("id", "=", target.sessionId).executeTakeFirst() : undefined;
|
|
49542
|
-
const row = {
|
|
49543
|
-
title: w.title,
|
|
49544
|
-
goal: w.goal,
|
|
49545
|
-
current: w.current,
|
|
49546
|
-
next: JSON.stringify(w.next),
|
|
49547
|
-
status: w.status,
|
|
49548
|
-
branch: traced?.branch ?? null,
|
|
49549
|
-
run_id: runId,
|
|
49550
|
-
updated_at: now
|
|
49551
|
-
};
|
|
49552
|
-
const held = await trx.selectFrom("work as w").leftJoin("extraction_run as r", "r.id", "w.run_id").leftJoin("session as s", "s.id", "r.session_id").select("s.started_at").where("w.project_id", "=", target.projectId).where("w.key", "=", w.key).executeTakeFirst();
|
|
49553
|
-
const mine = traced?.started_at;
|
|
49554
|
-
if (!(held?.started_at && mine && held.started_at > mine))
|
|
49555
|
-
await trx.insertInto("work").values({ project_id: target.projectId, key: w.key, ...row }).onConflict((oc) => oc.columns(["project_id", "key"]).doUpdateSet(row)).execute();
|
|
49678
|
+
await closeAnswered(trx, runId, checked.units, saved);
|
|
49556
49679
|
}
|
|
49680
|
+
await saveWork(trx, target, runId, checked.work, now, saved);
|
|
49557
49681
|
for (const s of new Set(looked))
|
|
49558
49682
|
await trx.insertInto("source_processing").values({ source_id: s, run_id: runId, outcome: cited2.has(s) ? "units" : "no_unit" }).onConflict((oc) => oc.doNothing()).execute();
|
|
49559
49683
|
return saved;
|
|
@@ -49741,7 +49865,7 @@ async function checkGlean(db, target, raw, facts = prepareGlean(target.root, raw
|
|
|
49741
49865
|
errors: [],
|
|
49742
49866
|
problems: [],
|
|
49743
49867
|
units: [],
|
|
49744
|
-
work:
|
|
49868
|
+
work: [],
|
|
49745
49869
|
fieldDefs: [],
|
|
49746
49870
|
facts
|
|
49747
49871
|
},
|
|
@@ -50404,6 +50528,13 @@ async function sessionSources(db, sessionId2) {
|
|
|
50404
50528
|
async function sessionEdits(db, sessionId2) {
|
|
50405
50529
|
return db.selectFrom("edit_observation").where("session_id", "=", sessionId2).select(["path", "via", "turn_id"]).orderBy("id").execute();
|
|
50406
50530
|
}
|
|
50531
|
+
async function workItems(db, projectId2, closed = 10) {
|
|
50532
|
+
const items = db.selectFrom("work").where("project_id", "=", projectId2).select(["key", "title", "goal", "current", "next", "status", "updated_at"]).orderBy("updated_at", "desc").orderBy("id", "desc");
|
|
50533
|
+
return {
|
|
50534
|
+
open: await items.where("status", "in", ["active", "blocked", "paused"]).execute(),
|
|
50535
|
+
closed: await items.where("status", "in", ["done", "abandoned"]).limit(closed).execute()
|
|
50536
|
+
};
|
|
50537
|
+
}
|
|
50407
50538
|
async function liveUnits(db, projectId2, limit = 40) {
|
|
50408
50539
|
return db.selectFrom("unit").where("project_id", "=", projectId2).where("lifecycle", "in", ["active", "candidate"]).where("extraction", "=", "supported").select(["id", "key", "kind", "stance", "lifecycle", "text"]).orderBy("id", "desc").limit(limit).execute();
|
|
50409
50540
|
}
|
|
@@ -50742,6 +50873,8 @@ ${body}` : body;
|
|
|
50742
50873
|
const live = await liveUnits(db, projectId2);
|
|
50743
50874
|
const whose = await authorityOf(db, live.map((u) => u.id));
|
|
50744
50875
|
const fields = scope.target.origin === "trace" ? await db.selectFrom("field_def").select(["name", "type", "label", "description", "enum_values", "kinds"]).where("project_id", "=", projectId2).orderBy("id").execute() : [];
|
|
50876
|
+
const work = scope.target.origin === "trace" ? await workItems(db, projectId2) : { open: [], closed: [] };
|
|
50877
|
+
const item2 = (w) => `- ${w.key} (${w.status}, updated ${w.updated_at.slice(0, 10)}) ${inline(w.title)}`;
|
|
50745
50878
|
const keys = live.map((u) => keyShown(u.key, u.id));
|
|
50746
50879
|
let tailId = "";
|
|
50747
50880
|
do
|
|
@@ -50759,10 +50892,23 @@ ${body}` : body;
|
|
|
50759
50892
|
return `- ${f.name} (${f.type}${values}; ${kinds.length ? kinds.join(", ") : "every kind"}) ${inline(f.label)}: ${inline(f.description)}`;
|
|
50760
50893
|
})
|
|
50761
50894
|
] : [],
|
|
50762
|
-
|
|
50895
|
+
...work.open.length ? [
|
|
50896
|
+
"Work in progress (to update one, give its key and only the fields that change; the same work keeps its key):",
|
|
50897
|
+
...work.open.flatMap((w) => [
|
|
50898
|
+
item2(w),
|
|
50899
|
+
` goal: ${inline(w.goal)}`,
|
|
50900
|
+
` current: ${inline(w.current)}`,
|
|
50901
|
+
` next: ${w.next.map(inline).join(" | ") || "none"}`
|
|
50902
|
+
])
|
|
50903
|
+
] : [],
|
|
50904
|
+
...work.closed.length ? [
|
|
50905
|
+
"Closed work, newest first (a key here is taken: work that goes on keeps it):",
|
|
50906
|
+
...work.closed.map(item2)
|
|
50907
|
+
] : [],
|
|
50908
|
+
`Live records of this project (${scope.target.origin === "trace" ? "supersedes, conflicts, and answers" : "supersedes and conflicts"} take these keys):`,
|
|
50763
50909
|
...live.length ? live.map((u, i) => `- ${keys[i]} (${u.kind}${u.stance ? ` ${u.stance}` : ""}, ${u.lifecycle}${["decision", "constraint"].includes(u.kind) ? `, ${AUTHORITY[whose.get(u.id) ?? "none"]}` : ""}) ${preview(u.text, 480)}`) : ["None."],
|
|
50764
50910
|
...keys.some((k, i) => k !== inline(live[i]?.key ?? "")) ? [
|
|
50765
|
-
"A key marked [key cut] is not whole: read that u<id> and take the key from there before using it
|
|
50911
|
+
"A key marked [key cut] is not whole: read that u<id> and take the key from there before using it."
|
|
50766
50912
|
] : []
|
|
50767
50913
|
].flatMap(pieces)
|
|
50768
50914
|
};
|
|
@@ -50809,7 +50955,7 @@ function contextOnly(id, items, c) {
|
|
|
50809
50955
|
return [
|
|
50810
50956
|
...c.units.filter((u) => [...u.evidence, ...u.options.flatMap((o) => o.evidence), ...u.adoption].every((x) => old.has(x.source))).map((u) => `${u.key}: quotes only messages earlier runs already looked at; an automatic run's record quotes at least one message it traces`),
|
|
50811
50957
|
...c.fieldDefs.filter((d) => old.has(d.source)).map((d) => `field_defs ${d.name}: an automatic run defines a field only from a message it traces`),
|
|
50812
|
-
...c.work && !c.units.length ? ["work: an automatic run updates work only beside a record of the messages it traces"] : []
|
|
50958
|
+
...c.work.length && !c.units.length ? ["work: an automatic run updates work only beside a record of the messages it traces"] : []
|
|
50813
50959
|
];
|
|
50814
50960
|
}
|
|
50815
50961
|
async function prepare2(db, id, projectId2, root, record4, probe, call) {
|
|
@@ -50860,7 +51006,7 @@ async function validate2(trx, id, projectId2, root, record4, prepared, call) {
|
|
|
50860
51006
|
...checked.fieldDefs
|
|
50861
51007
|
].map((q) => q.source));
|
|
50862
51008
|
const saved = await saveRecord(w, scope.target, run2.id, checked, scope.looked.filter((s) => shown.has(s) || cited2.has(s)));
|
|
50863
|
-
return { saved, changed: [] };
|
|
51009
|
+
return { saved, changed: [...saved.closed, ...saved.work] };
|
|
50864
51010
|
}
|
|
50865
51011
|
};
|
|
50866
51012
|
}
|
|
@@ -50889,6 +51035,7 @@ async function checkText(db, id, projectId2, root, record4, call, probe) {
|
|
|
50889
51035
|
...done.saved.superseded.map((k) => `✓ would be superseded: ${k}`),
|
|
50890
51036
|
...done.saved.candidates.map((c) => `△ would stay a candidate: ${c.key}: ${c.why}`),
|
|
50891
51037
|
...done.saved.quarantined.map((q) => `△ would be quarantined: ${q}`),
|
|
51038
|
+
...done.saved.notes.map((n) => `△ ${n}`),
|
|
50892
51039
|
...[...new Set(done.saved.anchorProblems)].filter((a) => !v.problems.some((p) => p === a || p.endsWith(` ${a}`))).map((a) => `△ ${a}`),
|
|
50893
51040
|
...done.changed.map((c) => `✓ would: ${c}`)
|
|
50894
51041
|
] : v.quarantine.map((q) => `△ ${q}`)
|
|
@@ -50941,6 +51088,7 @@ async function saveText(db, id, projectId2, root, record4, probe, call) {
|
|
|
50941
51088
|
const warnings = [
|
|
50942
51089
|
...new Set([
|
|
50943
51090
|
...saved.anchorProblems.map((a) => `△ ${a}`),
|
|
51091
|
+
...saved.notes.map((n) => `△ ${n}`),
|
|
50944
51092
|
...v.ops === null ? v.problems.map((n) => `△ ${n}`) : []
|
|
50945
51093
|
])
|
|
50946
51094
|
];
|
|
@@ -51213,7 +51361,8 @@ async function projectOf(cwd, meta3) {
|
|
|
51213
51361
|
}
|
|
51214
51362
|
async function called(name, cwd, meta3) {
|
|
51215
51363
|
const p = await projectOf(cwd, meta3);
|
|
51216
|
-
|
|
51364
|
+
const by = callerOf(meta3);
|
|
51365
|
+
return { p, by, call: await logCall(conn(), p.projectId, name, by) };
|
|
51217
51366
|
}
|
|
51218
51367
|
var tool = (fn) => fn().then((t) => reply(t), (e) => reply(e instanceof RecordRefused ? e.message : `Sphica: ${head(reason(e), 2000)}`, true));
|
|
51219
51368
|
var server = new McpServer({ name: "sphica-record", version: versionAt(ROOT) ?? "unknown" }, {
|
|
@@ -51237,7 +51386,9 @@ server.registerTool("trace_pending", {
|
|
|
51237
51386
|
inputSchema: exports_external.object({ auto: AUTO, cwd: CWD }).strict(),
|
|
51238
51387
|
annotations: READ
|
|
51239
51388
|
}, async (a, extra) => tool(async () => {
|
|
51240
|
-
const { p, call } = await called("trace_pending", a.cwd, extra._meta);
|
|
51389
|
+
const { p, by, call } = await called("trace_pending", a.cwd, extra._meta);
|
|
51390
|
+
if (a.auto && by.host === "codex" && by.mode !== "interactive")
|
|
51391
|
+
return "Sphica did not see a person start this Codex turn in the session's own thread (a child thread, codex exec, or a client it does not know), so the automatic trace does nothing this time.";
|
|
51241
51392
|
const skip = a.auto ? await callSession(conn(), call) : undefined;
|
|
51242
51393
|
return pendingText(conn(), p.projectId, undefined, { auto: a.auto, skip });
|
|
51243
51394
|
}));
|
package/dist/mcp.js
CHANGED
|
@@ -46674,6 +46674,7 @@ var Unit = exports_external.object({
|
|
|
46674
46674
|
aliases: exports_external.array(exports_external.string()).max(12).default([]),
|
|
46675
46675
|
supersedes: exports_external.string().min(1).optional(),
|
|
46676
46676
|
conflicts: exports_external.array(exports_external.string().min(1)).max(5).default([]),
|
|
46677
|
+
answers: exports_external.array(exports_external.string().min(1)).max(5).default([]),
|
|
46677
46678
|
fields: exports_external.array(exports_external.object({
|
|
46678
46679
|
name: exports_external.string().regex(FIELD_NAME, "a defined field name"),
|
|
46679
46680
|
value: text2(200),
|
|
@@ -46691,16 +46692,16 @@ var FieldDef = exports_external.object({
|
|
|
46691
46692
|
}).strict();
|
|
46692
46693
|
var Work = exports_external.object({
|
|
46693
46694
|
key: exports_external.string().regex(KEY),
|
|
46694
|
-
title: text2(200),
|
|
46695
|
-
goal: text2(1000),
|
|
46696
|
-
current: text2(2000),
|
|
46697
|
-
next: exports_external.array(text2(500)).max(10).
|
|
46698
|
-
status: exports_external.enum(WORK_STATUSES)
|
|
46695
|
+
title: text2(200).optional(),
|
|
46696
|
+
goal: text2(1000).optional(),
|
|
46697
|
+
current: text2(2000).optional(),
|
|
46698
|
+
next: exports_external.array(text2(500)).max(10).optional(),
|
|
46699
|
+
status: exports_external.enum(WORK_STATUSES).optional()
|
|
46699
46700
|
}).strict();
|
|
46700
46701
|
var Record = exports_external.object({
|
|
46701
46702
|
field_defs: exports_external.array(FieldDef).max(10).default([]),
|
|
46702
46703
|
units: exports_external.array(Unit).max(50),
|
|
46703
|
-
work: Work.optional()
|
|
46704
|
+
work: exports_external.preprocess((w) => w === undefined || Array.isArray(w) ? w : [w], exports_external.array(Work).min(1).max(10).optional())
|
|
46704
46705
|
}).strict();
|
|
46705
46706
|
function repoPath(p) {
|
|
46706
46707
|
const s = p.trim().replace(/^\.\//, "");
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "sphica",
|
|
3
|
-
"version": "0.6.
|
|
3
|
+
"version": "0.6.52",
|
|
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",
|
package/skills/glean/SKILL.md
CHANGED
|
@@ -90,7 +90,7 @@ Japanese corner brackets, backticks, apostrophes): quote more of the owner's own
|
|
|
90
90
|
Check reads where the words sit, not what they mean: whether they settle this record is yours to judge.
|
|
91
91
|
|
|
92
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
|
|
93
|
-
record in `units` (trace's shape
|
|
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
|
|
94
94
|
quotation there); records are never rewritten.
|
|
95
95
|
|
|
96
96
|
## When a source turns up for an unsourced record
|
package/skills/harvest/SKILL.md
CHANGED
|
@@ -38,7 +38,7 @@ as `cwd` to every tool.
|
|
|
38
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
39
|
(a source too long for a page says where `read` goes on)
|
|
40
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),
|
|
41
|
-
"The record"),
|
|
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
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
43
|
`call record_more with cursor: "..."`, read the rest with `record_more`. Fix and check again until there are no errors.
|
|
44
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,
|
package/skills/trace/SKILL.md
CHANGED
|
@@ -36,9 +36,9 @@ 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.
|
|
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
40
|
It comes in pages: when a page's last line says `call record_context with after: "..."`, call it again with that `after`, exactly as written
|
|
41
|
-
(`s<N>` while messages follow, then `t<id>.<line>` while the edits, fields, and live records go on), until a page names no `after`.
|
|
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
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
43
|
Saving marks as looked at only the messages you were shown and those you quote; the rest stay pending.
|
|
44
44
|
Use `search` and `read` to look at older records this session may replace
|
|
@@ -58,10 +58,11 @@ A session with nothing worth keeping is saved with `"units": []`: it is marked a
|
|
|
58
58
|
|
|
59
59
|
## On your own
|
|
60
60
|
|
|
61
|
-
When Sphica's session-start notice
|
|
61
|
+
When Sphica's session-start notice says earlier sessions wait to be traced, run this after the user's request is done, without asking them. The notice comes in a new interactive Claude Code session, and in a new Codex session started from the terminal, where it names this file (Codex otherwise starts this Skill only when the user asks).
|
|
62
62
|
|
|
63
63
|
1. `trace_pending` with `auto: true`. It lists sessions other than this one, oldest first. Take the first one or two; never this session.
|
|
64
|
-
If it says it cannot tell which session called,
|
|
64
|
+
If it says the automatic trace does nothing this time (it cannot tell which session called, or in Codex the call did not come from a
|
|
65
|
+
turn a person started in the session's own thread), stop: do nothing this time
|
|
65
66
|
2. `trace_begin` with that session, then `record_context` with `auto: true`. It starts with a few earlier messages for context (marked as
|
|
66
67
|
such), then the messages still waiting. When it says the automatic run stops here, save what you read; the rest waits for the next run
|
|
67
68
|
3. Check and save as above. Do not ask the owner which session or record to keep, and add no owner adoption the conversation does not have
|
|
@@ -91,10 +92,15 @@ When Sphica's session-start notice in Claude Code says earlier sessions wait to
|
|
|
91
92
|
"aliases": ["database", "storage", "SQLite", "Postgres", "server", "persistence", "..."]
|
|
92
93
|
}
|
|
93
94
|
],
|
|
94
|
-
"work":
|
|
95
|
+
"work": [
|
|
96
|
+
{ "key": "storage", "current": "Decided", "next": [], "status": "done" },
|
|
97
|
+
{ "key": "csv-export", "title": "Rework the export", "goal": "Notes never leave in a CSV", "current": "Not started", "next": ["List the columns"], "status": "active" }
|
|
98
|
+
]
|
|
95
99
|
}
|
|
96
100
|
```
|
|
97
101
|
|
|
102
|
+
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.
|
|
103
|
+
|
|
98
104
|
<!-- english-exempt: the aliases example has to show Japanese words -->
|
|
99
105
|
The `"..."` stands for the other language's words: in this example, `"データベース", "保存先", "DB サーバー", "永続化"`.
|
|
100
106
|
|
|
@@ -111,12 +117,17 @@ The `"..."` stands for the other language's words: in this example, `"データ
|
|
|
111
117
|
| `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`) |
|
|
112
118
|
| `supersedes` | The key of a live record this one replaces (context lists them). The old one is marked superseded, never deleted |
|
|
113
119
|
| `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 |
|
|
114
|
-
| `
|
|
120
|
+
| `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` |
|
|
121
|
+
| `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 |
|
|
115
122
|
| `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 |
|
|
116
123
|
| `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 |
|
|
117
124
|
|
|
118
125
|
A field value that breaks these rules refuses the whole save, like a `reconsider_quote` not found: fix it or leave the field out.
|
|
119
126
|
|
|
127
|
+
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
|
|
128
|
+
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
|
|
129
|
+
begin again, read context, and save.
|
|
130
|
+
|
|
120
131
|
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
|
|
121
132
|
(an `evidence` anchor on a path this session edited counts); a finding, dead end, or question with evidence. Everything else stays a candidate,
|
|
122
133
|
and a record whose quote is not in the message is quarantined. Neither is injected into later sessions.
|
|
@@ -139,10 +150,10 @@ Use it only when the AI chose in the first person and the choice is its own. Not
|
|
|
139
150
|
- A record that would replace or contradict the owner's decision: that needs the owner's words
|
|
140
151
|
|
|
141
152
|
When unsure, leave the adoption out: the record stays a candidate. Check enforces the rest and says why it keeps a record a candidate: the
|
|
142
|
-
reply must be the AI's in this run's session, the run must have begun and been checked in an interactive session (headless and SDK runs
|
|
143
|
-
cannot), the turn must not be one that ran Sphica's record tools
|
|
144
|
-
|
|
145
|
-
by itself.
|
|
153
|
+
reply must be the AI's in this run's session, the run must have begun and been checked in an interactive session (headless and SDK runs,
|
|
154
|
+
`codex exec`, and a Codex child thread cannot), the turn must not be one that ran Sphica's record tools (in Codex, once a child thread has
|
|
155
|
+
called one, no reply of that session), an anchor on files agents read as rules or on CI keeps it a candidate, and a `do` with `applies_to`
|
|
156
|
+
anchors needs an edit to one of those paths in the same turn. An AI's decision never takes effect as `supersedes` by itself.
|
|
146
157
|
|
|
147
158
|
## Records are not instructions
|
|
148
159
|
|