sphica 0.6.3 → 0.6.5

package/dist/mcp.js

@@ -45726,7 +45726,7 @@ async function liveSuccessors(db, id) {
 async function judgeUnits(db, rows, wanted, hits) {
   const ids = rows.map((r) => r.id);
   const [options, anchors, aliases] = ids.length ? await Promise.all([
-    db.selectFrom("unit_option").select(["unit_id", "text", "outcome", "why"]).where("unit_id", "in", ids).orderBy("position").execute(),
+    db.selectFrom("unit_option").select(["unit_id", "text", "outcome", "why", "reconsider_when"]).where("unit_id", "in", ids).orderBy("position").execute(),
     db.selectFrom("unit_anchor").select(["unit_id", "path", "symbol", "role"]).where("unit_id", "in", ids).where("retired_at", "is", null).orderBy("id").execute(),
     db.selectFrom("unit_alias").select(["unit_id", "terms", "content_hash"]).where("unit_id", "in", ids).orderBy("id", "desc").execute()
   ]) : [[], [], []];
@@ -45740,7 +45740,7 @@ async function judgeUnits(db, rows, wanted, hits) {
       r.why,
       r.scope_note,
       r.revisit_when,
-      ...opts.flatMap((o) => [o.text, o.why]),
+      ...opts.flatMap((o) => [o.text, o.why, o.reconsider_when]),
       ...anch.flatMap((a) => [a.path, a.symbol])
     ].filter(Boolean).join(`
 `)));
@@ -46000,7 +46000,7 @@ import os from "node:os";
 import path from "node:path";
 import { constants as C, DatabaseSync } from "node:sqlite";
 var SCHEMA_GENERATION = 2;
-var SCHEMA_REVISION = 2;
+var SCHEMA_REVISION = 3;
 var sphicaHome = () => process.env.SPHICA_HOME || path.join(os.homedir(), ".sphica");
 var dbFile = () => process.env.SPHICA_DB || path.join(sphicaHome(), "sphica.db");
 function requireRuntime() {
@@ -46122,54 +46122,74 @@ var LIFECYCLES = ["candidate", "active", "superseded", "withdrawn"];
 var HOSTS = ["claude-code", "codex"];
 var sessionId = (projectId, host, externalId) => uuidFrom(String(projectId), host, externalId);
 
-// server/src/plugin.ts
-import fs2 from "node:fs";
-import path2 from "node:path";
-import { fileURLToPath } from "node:url";
-var MANIFEST = path2.join(".claude-plugin", "plugin.json");
-function versionAt(root) {
-  try {
-    const m = JSON.parse(fs2.readFileSync(path2.join(root, MANIFEST), "utf8"));
-    return m.name === "sphica" && typeof m.version === "string" ? m.version : null;
-  } catch {
-    return null;
-  }
-}
-var here = path2.dirname(fileURLToPath(import.meta.url));
-var ROOT = [path2.join(here, ".."), path2.join(here, "..", "..", "plugin")].find((r) => versionAt(r) !== null) ?? path2.join(here, "..");
-var HOST_MARKS = new Set([".orphaned_at", ".in_use"]);
-
-// server/src/project.ts
-import { execFileSync } from "node:child_process";
-import fs4 from "node:fs";
+// server/src/overview.ts
 import path4 from "node:path";
 
 // server/src/anchors.ts
-import fs3 from "node:fs";
-import path3 from "node:path";
+import fs2 from "node:fs";
+import path2 from "node:path";
 var MAX_BYTES = 2 * 1024 * 1024;
-var leaves = (rel) => rel === ".." || rel.startsWith(`..${path3.sep}`) || path3.isAbsolute(rel);
+var leaves = (rel) => rel === ".." || rel.startsWith(`..${path2.sep}`) || path2.isAbsolute(rel);
 var literal3 = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 function readText(root, rel) {
-  const abs = path3.join(root, rel);
-  if (leaves(path3.relative(root, abs)))
+  const abs = path2.join(root, rel);
+  if (leaves(path2.relative(root, abs)))
     return;
-  const st = fs3.lstatSync(abs, { throwIfNoEntry: false });
+  const st = fs2.lstatSync(abs, { throwIfNoEntry: false });
   if (!st)
     return null;
   if (!st.isFile() || st.size > MAX_BYTES)
     return;
-  const inside = path3.relative(fs3.realpathSync(root), fs3.realpathSync(abs));
-  if (leaves(inside))
+  try {
+    const inside = path2.relative(fs2.realpathSync(root), fs2.realpathSync(abs));
+    if (leaves(inside))
+      return;
+    const buf = fs2.readFileSync(abs);
+    return buf.includes(0) ? undefined : buf.toString("utf8");
+  } catch {
     return;
-  const buf = fs3.readFileSync(abs);
-  return buf.includes(0) ? undefined : buf.toString("utf8");
+  }
 }
 function findSymbol(text, symbol2) {
   const re = new RegExp(`(?<![\\w$])${literal3(symbol2)}(?![\\w$])`);
   const lines = text.split(/\r?\n/);
   return { lines, i: lines.findIndex((l) => re.test(l)) };
 }
+function fileState(root, rel) {
+  if (!root)
+    return "unknown";
+  if (leaves(path2.relative(root, path2.join(root, rel))))
+    return "unknown";
+  let realRoot;
+  try {
+    realRoot = fs2.realpathSync(root);
+  } catch {
+    return "unknown";
+  }
+  let at = root;
+  for (const part of rel.split("/")) {
+    at = path2.join(at, part);
+    let st;
+    try {
+      st = fs2.lstatSync(at, { throwIfNoEntry: false });
+    } catch (e) {
+      if (e.code === "ENOTDIR")
+        return "gone";
+      return "unknown";
+    }
+    if (!st)
+      return "gone";
+    if (st.isSymbolicLink()) {
+      try {
+        if (leaves(path2.relative(realRoot, fs2.realpathSync(at))))
+          return "unknown";
+      } catch {
+        return "unknown";
+      }
+    }
+  }
+  return "present";
+}
 function checkAnchor(root, a) {
   if (!root)
     return { state: "unknown", line: null };
@@ -46189,91 +46209,21 @@ function checkAnchor(root, a) {
   };
 }
 
-// server/src/project.ts
-var localFile = () => path4.join(sphicaHome(), "projects.json");
-var LOCAL_KEY = /^[a-z0-9][a-z0-9._-]*$/;
-function normalizeRemote(url2) {
-  const raw = String(url2 ?? "").trim();
-  if (!raw)
-    return null;
-  const scp = raw.match(/^(?:[^@/]+@)?([^:/]+):(?!\/)(.+?)(?:\.git)?$/);
-  if (scp)
-    return `${scp[1]}/${scp[2]}`;
-  try {
-    const u = new URL(raw);
-    if (!u.hostname)
-      return null;
-    const p = u.pathname.replace(/\.git$/, "").replace(/^\/+|\/+$/g, "");
-    return p ? `${u.hostname}/${p}` : u.hostname;
-  } catch {
-    return null;
-  }
-}
-var git = (dir, ...args) => {
-  try {
-    return execFileSync("git", ["-C", dir, ...args], {
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"],
-      timeout: 5000
-    }).trim();
-  } catch {
-    return null;
-  }
-};
-function localMap() {
-  let raw;
-  try {
-    raw = fs4.readFileSync(localFile(), "utf8");
-  } catch (e) {
-    if (e.code === "ENOENT")
-      return {};
-    throw e;
-  }
-  let m;
-  try {
-    m = JSON.parse(raw);
-  } catch {
-    m = null;
-  }
-  if (!m || typeof m !== "object" || Array.isArray(m) || Object.entries(m).some(([root, name]) => !path4.isAbsolute(root) || typeof name !== "string" || !LOCAL_KEY.test(name)))
-    throw new Error(`${localFile()} is not a valid JSON project table. Fix or delete it, then name the project again.`);
-  return m;
-}
-function identify(dir) {
-  const given = path4.resolve(dir);
-  const top = git(given, "rev-parse", "--show-toplevel");
-  const root = top || given;
-  const remote = top ? normalizeRemote(git(root, "remote", "get-url", "origin")) : null;
-  if (remote)
-    return { key: `git:${remote}`, root, name: remote.split("/").slice(1).join("/") || remote };
-  const map3 = localMap();
-  for (let d = root;; d = path4.dirname(d)) {
-    const local = map3[d];
-    if (local && LOCAL_KEY.test(local))
-      return { key: `local:${local}`, root: d, name: local };
-    if (top || path4.dirname(d) === d)
-      return null;
-  }
-}
-async function projectId(db, key) {
-  const r = await db.selectFrom("project").select("id").where("key", "=", key).executeTakeFirst();
-  return r?.id ?? null;
-}
-
 // server/src/read.ts
+var UNSUPPORTED = "unsupported: its owner quote was retracted or forgotten, so it is not the owner's condition";
 var cut = (text, start, end) => Buffer.from(text, "utf8").subarray(start, end).toString("utf8");
 var speaker = (s) => s.author_kind === "owner" ? "the owner" : s.author_kind === "assistant" ? "the assistant" : `${s.author_login ?? "someone"} (${s.author_association ?? s.author_kind})`;
-async function readUnit(db, projectId2, ref, root, asOf) {
+async function readUnit(db, projectId, ref, root, asOf) {
   const byId = /^u([1-9][0-9]{0,15})$/.exec(ref);
-  const u = await db.selectFrom("unit").selectAll().where("project_id", "=", projectId2).where(byId ? "id" : "key", "=", byId ? Number(byId[1]) : ref).executeTakeFirst();
-  const bare = u ?? (byId ? undefined : await db.selectFrom("unit").selectAll().where("project_id", "=", projectId2).where("key", "in", ["trace:", "harvest:", "glean:"].map((o) => o + ref)).execute().then((rows) => rows.length === 1 ? rows[0] : undefined));
+  const u = await db.selectFrom("unit").selectAll().where("project_id", "=", projectId).where(byId ? "id" : "key", "=", byId ? Number(byId[1]) : ref).executeTakeFirst();
+  const bare = u ?? (byId ? undefined : await db.selectFrom("unit").selectAll().where("project_id", "=", projectId).where("key", "in", ["trace:", "harvest:", "glean:"].map((o) => o + ref)).execute().then((rows) => rows.length === 1 ? rows[0] : undefined));
   if (!bare || asOf && bare.created_at > asOf)
     return null;
   return describe3(db, bare, root, asOf);
 }
 async function describe3(db, u, root, asOf) {
   const [options, evidence, adoption, anchors, links, states] = await Promise.all([
-    db.selectFrom("unit_option").select(["id", "text", "outcome", "why"]).where("unit_id", "=", u.id).orderBy("position").execute(),
+    db.selectFrom("unit_option").select(["id", "text", "outcome", "why", "reconsider_when"]).where("unit_id", "=", u.id).orderBy("position").execute(),
     db.selectFrom("unit_evidence as e").innerJoin("source as s", "s.id", "e.source_id").where("e.unit_id", "=", u.id).where("e.added_at", "<=", asOf ?? "9999").select([
       "e.option_id",
       "e.role",
@@ -46343,6 +46293,10 @@ async function describe3(db, u, root, asOf) {
     out.push("Options:");
     for (const o of options) {
       out.push(`- ${o.text}: ${o.outcome}${o.why ? `, because ${o.why}` : ""}`);
+      if (o.reconsider_when) {
+        const stands = evidence.some((e) => e.option_id === o.id && e.role === "reconsiders" && !e.retracted_at);
+        out.push(`  Reconsider when: ${inline(o.reconsider_when)}${stands ? " (the owner's words are quoted below)" : ` [${UNSUPPORTED}]`}`);
+      }
       for (const e of evidence.filter((x) => x.option_id === o.id))
         out.push(quote(e));
     }
@@ -46375,11 +46329,11 @@ async function describe3(db, u, root, asOf) {
   return out.join(`
 `);
 }
-async function readSource(db, projectId2, ref) {
+async function readSource(db, projectId, ref) {
   const m = /^s([1-9][0-9]{0,15})(?:@(\d{1,9}))?$/.exec(ref);
   if (!m)
     return null;
-  const s = await db.selectFrom("source").selectAll().where("project_id", "=", projectId2).where("id", "=", Number(m[1])).executeTakeFirst();
+  const s = await db.selectFrom("source").selectAll().where("project_id", "=", projectId).where("id", "=", Number(m[1])).executeTakeFirst();
   if (!s)
     return null;
   return [
@@ -46399,6 +46353,405 @@ function part(id, text, from) {
   return end < all.length ? [shown, `(${all.length - end} more bytes; read s${id}@${end} for the rest)`] : [shown];
 }
 
+// server/src/rule-files.ts
+import fs3 from "node:fs";
+import path3 from "node:path";
+
+// server/src/git.ts
+import { execFileSync } from "node:child_process";
+function cleanGit(root, args, max = 1024 * 1024) {
+  const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => !k.startsWith("GIT_")));
+  return execFileSync("git", ["-C", root, ...args], {
+    env,
+    maxBuffer: max,
+    stdio: ["ignore", "pipe", "ignore"],
+    timeout: 1e4
+  });
+}
+
+// server/src/rule-files.ts
+var RULE_LIMITS = { files: 200, bytes: 256 * 1024, depth: 8, entries: 5000 };
+var NAMES = new Set(["CLAUDE.md", "AGENTS.md", "AGENTS.override.md"]);
+var PATHSPECS = [...NAMES, ".claude/rules/**/*.md"].map((p) => `:(glob)**/${p}`);
+function isRuleFile(rel) {
+  const parts = rel.split("/");
+  const name = parts.at(-1) ?? "";
+  if (NAMES.has(name))
+    return true;
+  const i = parts.findIndex((p, k) => p === ".claude" && parts[k + 1] === "rules");
+  return i >= 0 && parts.length > i + 2 && name.endsWith(".md");
+}
+function ruleFiles(root) {
+  const listed = gitList(root) ?? walk(root);
+  const out = { files: [], skipped: 0, incomplete: listed.incomplete };
+  const realRoot = fs3.realpathSync(root);
+  for (const [i, rel] of [...new Set(listed.paths)].sort().entries()) {
+    if (i >= RULE_LIMITS.files) {
+      out.skipped++;
+      continue;
+    }
+    const text = readBounded(root, realRoot, rel);
+    if (text === null)
+      continue;
+    if (text === undefined)
+      out.skipped++;
+    else
+      out.files.push({ path: rel, text });
+  }
+  return out;
+}
+function readBounded(root, realRoot, rel) {
+  const abs = path3.join(root, rel);
+  if (leaves(path3.relative(root, abs)))
+    return;
+  try {
+    const st = fs3.lstatSync(abs, { throwIfNoEntry: false });
+    if (!st)
+      return null;
+    if (!st.isFile() || st.size > RULE_LIMITS.bytes)
+      return;
+    if (leaves(path3.relative(realRoot, fs3.realpathSync(abs))))
+      return;
+    const buf = fs3.readFileSync(abs);
+    return buf.length > RULE_LIMITS.bytes || buf.includes(0) ? undefined : buf.toString("utf8");
+  } catch {
+    return;
+  }
+}
+function gitList(root) {
+  try {
+    if (cleanGit(root, ["rev-parse", "--is-inside-work-tree"]).toString("utf8").trim() !== "true")
+      return null;
+  } catch {
+    return null;
+  }
+  try {
+    const out = cleanGit(root, ["ls-files", "--cached", "--others", "--exclude-standard", "-z", "--", ...PATHSPECS], 16 * 1024 * 1024);
+    return { paths: out.toString("utf8").split("\x00").filter(isRuleFile), incomplete: null };
+  } catch {
+    return { paths: [], incomplete: "git could not list the files" };
+  }
+}
+function walk(root) {
+  const paths = [];
+  let entries = 0;
+  let unread = 0;
+  let tooDeep = false;
+  let stopped = false;
+  const visit2 = (rel, depth) => {
+    if (stopped)
+      return;
+    let list;
+    try {
+      list = fs3.readdirSync(path3.join(root, rel), { withFileTypes: true });
+    } catch {
+      unread++;
+      return;
+    }
+    for (const d of list) {
+      if (++entries > RULE_LIMITS.entries) {
+        stopped = true;
+        return;
+      }
+      const child = rel ? `${rel}/${d.name}` : d.name;
+      if ((d.isFile() || d.isSymbolicLink()) && isRuleFile(child))
+        paths.push(child);
+      else if (d.isDirectory() && d.name !== "node_modules" && (!d.name.startsWith(".") || d.name === ".claude")) {
+        if (depth >= RULE_LIMITS.depth)
+          tooDeep = true;
+        else
+          visit2(child, depth + 1);
+      }
+    }
+  };
+  visit2("", 1);
+  const why = [
+    ...stopped ? [`stopped after ${RULE_LIMITS.entries} directory entries`] : [],
+    ...tooDeep ? [`did not look deeper than ${RULE_LIMITS.depth} directories`] : [],
+    ...unread ? [`could not read ${unread} director${unread === 1 ? "y" : "ies"}`] : []
+  ];
+  return { paths, incomplete: why.length ? why.join("; ") : null };
+}
+
+// server/src/overview.ts
+var OVERVIEW_LIMITS = { records: 50, key: 200, text: 300, paths: 520, heading: 120 };
+var PROJECT_WIDE = "Project-wide (no code location)";
+function pathList(paths) {
+  const all = paths.map(inline);
+  const out = [];
+  let used = 0;
+  for (const p of all) {
+    if (used + Buffer.byteLength(p) + 2 > OVERVIEW_LIMITS.paths)
+      break;
+    out.push(p);
+    used += Buffer.byteLength(p) + 2;
+  }
+  if (!out.length)
+    out.push(head(all[0] ?? "", OVERVIEW_LIMITS.paths));
+  return `${out.join(", ")}${all.length > out.length ? ` (+${all.length - out.length} more)` : ""}`;
+}
+async function liveOverview(db, projectId, after) {
+  const live = db.selectFrom("unit").where("project_id", "=", projectId).where("lifecycle", "=", "active").where("kind", "in", ["decision", "constraint"]);
+  const [total, rows] = await Promise.all([
+    live.select((eb) => eb.fn.countAll().as("n")).executeTakeFirst(),
+    live.select(["id", "key", "kind", "stance", "text"]).where("id", ">", after ?? 0).orderBy("id").limit(OVERVIEW_LIMITS.records + 1).execute()
+  ]);
+  const anchors = rows.length ? await db.selectFrom("unit_anchor").select(["unit_id", "path"]).where("unit_id", "in", rows.map((r) => r.id)).where("role", "=", "applies_to").where("retired_at", "is", null).orderBy("id").execute() : [];
+  const shown = [];
+  for (const r of rows.slice(0, OVERVIEW_LIMITS.records)) {
+    const paths = [...new Set(anchors.filter((a) => a.unit_id === r.id).map((a) => a.path))];
+    const first = paths[0];
+    const dir = first === undefined ? null : path4.posix.dirname(first);
+    const line = `- ${head(inline(r.key), OVERVIEW_LIMITS.key)} (u${r.id}, ${r.kind}${r.stance ? ` ${r.stance}` : ""}): ${head(inline(r.text), OVERVIEW_LIMITS.text)}${paths.length ? ` [${pathList(paths)}]` : ""}`;
+    shown.push({
+      id: r.id,
+      group: dir === null ? PROJECT_WIDE : dir === "." ? "(repository root)" : `${dir}/`,
+      line
+    });
+  }
+  const n = Number(total?.n ?? 0);
+  if (!shown.length)
+    return after === null ? "No active decision or constraint is recorded for this project. status says whether sessions are still untraced." : `No active decision or constraint after id ${after}. ${n} in all.`;
+  const groups = [...new Set(shown.map((s) => s.group))].sort((a, b) => a === PROJECT_WIDE ? 1 : b === PROJECT_WIDE ? -1 : a.localeCompare(b));
+  const last = shown.at(-1)?.id ?? 0;
+  const more = rows.length > shown.length;
+  return [
+    ...groups.flatMap((g) => [
+      `## ${head(inline(g), OVERVIEW_LIMITS.heading)}`,
+      ...shown.filter((s) => s.group === g).map((s) => s.line),
+      ""
+    ]),
+    `${shown.length} shown of ${n} active decisions and constraints${after === null ? "" : ` (ids after ${after})`}.`,
+    more ? `More follow: call overview again with after: ${last}. Pages are read at different times: a record that became active in between, with a lower id, is not on a later page.` : "That is the end of the list.",
+    "Read a record by its key or u<id> before relying on it."
+  ].join(`
+`);
+}
+var LOOK_LIMITS = { anchors: 2000, lines: 50, line: 2200, bytes: 56 * 1024 };
+var MARKER = /<!--\s*sphica:\s*((?:trace|harvest|glean):[^\s>]{1,1000})\s*-->/g;
+async function lookOverview(db, projectId, root) {
+  const notChecked = [];
+  const sections = [];
+  let used = 0;
+  const section = (title, lines, empty) => {
+    const shown = [];
+    for (const line of lines.slice(0, LOOK_LIMITS.lines).map((l) => head(l, LOOK_LIMITS.line))) {
+      if (used + bytes(line) + 1 > LOOK_LIMITS.bytes)
+        break;
+      used += bytes(line) + 1;
+      shown.push(line);
+    }
+    sections.push([
+      `## ${title}`,
+      ...shown.length || lines.length ? shown : [empty],
+      ...lines.length > shown.length ? [`(${lines.length - shown.length} more not shown: deal with these first, then ask again)`] : []
+    ].join(`
+`));
+  };
+  const live = db.selectFrom("unit_anchor as a").innerJoin("unit as u", "u.id", "a.unit_id").where("u.project_id", "=", projectId).where("u.lifecycle", "=", "active").where("a.retired_at", "is", null);
+  const [anchors, total] = await Promise.all([
+    live.select(["u.key", "u.kind", "a.path", "a.symbol", "a.line_start", "a.role"]).orderBy("a.id").limit(LOOK_LIMITS.anchors).execute(),
+    live.select((eb) => eb.fn.countAll().as("n")).executeTakeFirst()
+  ]);
+  const gone = [];
+  const lost = [];
+  if (!root)
+    notChecked.push("code locations: no working tree for this project here");
+  else {
+    let unknown3 = 0;
+    let unscanned = 0;
+    for (const a of anchors) {
+      const where = `- ${inline(a.key)} (${a.kind}): ${inline(a.path)} (${a.role})`;
+      const file2 = fileState(root, a.path);
+      if (file2 === "gone")
+        gone.push(where);
+      else if (file2 === "unknown")
+        unknown3++;
+      else if (a.symbol) {
+        const state = checkAnchor(root, a).state;
+        if (state === "missing")
+          lost.push(`- ${inline(a.key)} (${a.kind}): ${inline(a.symbol)} in ${inline(a.path)} (${a.role})`);
+        else if (state === "unknown")
+          unscanned++;
+      }
+    }
+    if (unknown3)
+      notChecked.push(`${unknown3} code locations that lead outside the repository or cannot be followed`);
+    if (unscanned)
+      notChecked.push(`${unscanned} code locations whose file could not be scanned for the symbol (too large, binary, or unreadable)`);
+    const past = Number(total?.n ?? 0) - anchors.length;
+    if (past > 0)
+      notChecked.push(`${past} code locations past the first ${LOOK_LIMITS.anchors} (by age)`);
+  }
+  section("Files gone", gone, root ? "none" : "not checked");
+  section("Symbol not found (the file is still there)", lost, root ? "none" : "not checked");
+  const [options, deferred] = await Promise.all([
+    db.selectFrom("unit_option as o").innerJoin("unit as u", "u.id", "o.unit_id").where("u.project_id", "=", projectId).where("u.lifecycle", "=", "active").where("o.reconsider_when", "is not", null).select((eb) => [
+      "u.key",
+      "o.text",
+      "o.reconsider_when",
+      eb.exists(eb.selectFrom("unit_evidence as e").innerJoin("source as s", "s.id", "e.source_id").whereRef("e.option_id", "=", "o.id").where("e.role", "=", "reconsiders").where("e.retracted_at", "is", null).where("s.author_kind", "=", "owner").select("e.id")).as("stands")
+    ]).orderBy("o.id").execute(),
+    db.selectFrom("unit").where("project_id", "=", projectId).where("lifecycle", "=", "active").where("revisit_when", "is not", null).select(["key", "text", "revisit_when"]).orderBy("id").execute()
+  ]);
+  section("Conditions to reconsider (judge whether one has come about; nothing here is decided)", [
+    ...options.map((o) => `- ${inline(o.key)}: rejected option ${inline(head(o.text, 120))}, reconsider when: ${inline(head(o.reconsider_when ?? "", 300))}${o.stands ? "" : ` [${UNSUPPORTED}]`}`),
+    ...deferred.map((d) => `- ${inline(d.key)}: deferred ${inline(head(d.text, 120))}, revisit when: ${inline(head(d.revisit_when ?? "", 300))}`)
+  ], "none");
+  const marked = [];
+  if (!root)
+    notChecked.push("instruction files: no working tree for this project here");
+  else {
+    const scan = ruleFiles(root);
+    const found = [];
+    for (const f of scan.files)
+      for (const [i, text] of f.text.split(/\r?\n/).entries())
+        for (const m of text.matchAll(MARKER))
+          found.push({ file: f.path, line: i + 1, key: m[1] ?? "" });
+    const keys = [...new Set(found.map((f) => f.key))];
+    const units = new Map;
+    for (let i = 0;i < keys.length; i += 500)
+      for (const u of await db.selectFrom("unit").select(["id", "key", "lifecycle"]).where("project_id", "=", projectId).where("key", "in", keys.slice(i, i + 500)).execute())
+        units.set(u.key, u);
+    const chains = new Map;
+    for (const f of found) {
+      const u = units.get(f.key);
+      const where = `- ${inline(f.file)}:${f.line}: ${inline(f.key)}`;
+      if (!u)
+        marked.push(`${where} is not a record of this project`);
+      else if (u.lifecycle === "withdrawn")
+        marked.push(`${where} was withdrawn`);
+      else if (u.lifecycle === "superseded") {
+        let next = chains.get(u.id);
+        if (next === undefined) {
+          next = await successor(db, u.id);
+          chains.set(u.id, next);
+        }
+        marked.push(`${where} was superseded${next ? ` by ${inline(next.key)}${next.lifecycle === "active" ? "" : `, which is ${next.lifecycle} too`}` : ""}`);
+      }
+    }
+    if (scan.skipped)
+      notChecked.push(`${scan.skipped} instruction files not read (over the caps, not regular files, or outside the repository)`);
+    if (scan.incomplete)
+      notChecked.push(`instruction files: the listing ${scan.incomplete}`);
+  }
+  section("Rule markers whose record changed", marked, root ? "none" : "not checked");
+  return [
+    ...sections,
+    `## Not checked
+${notChecked.length ? notChecked.map((n) => `- ${n}`).join(`
+`) : "nothing: every place above was checked"}`,
+    "Read a record by its key before acting on it. Change a record only through /sphica:trace, with the owner's words."
+  ].join(`
+
+`);
+}
+async function successor(db, id) {
+  let end = null;
+  let at = id;
+  for (;; ) {
+    const next = await db.selectFrom("unit_link as l").innerJoin("unit as u", "u.id", "l.from_unit").where("l.to_unit", "=", at).where("l.kind", "=", "supersedes").select(["u.id", "u.key", "u.lifecycle"]).executeTakeFirst();
+    if (!next)
+      break;
+    end = { key: next.key, lifecycle: next.lifecycle };
+    if (next.lifecycle !== "superseded")
+      break;
+    at = next.id;
+  }
+  return end;
+}
+
+// server/src/plugin.ts
+import fs4 from "node:fs";
+import path5 from "node:path";
+import { fileURLToPath } from "node:url";
+var MANIFEST = path5.join(".claude-plugin", "plugin.json");
+function versionAt(root) {
+  try {
+    const m = JSON.parse(fs4.readFileSync(path5.join(root, MANIFEST), "utf8"));
+    return m.name === "sphica" && typeof m.version === "string" ? m.version : null;
+  } catch {
+    return null;
+  }
+}
+var here = path5.dirname(fileURLToPath(import.meta.url));
+var ROOT = [path5.join(here, ".."), path5.join(here, "..", "..", "plugin")].find((r) => versionAt(r) !== null) ?? path5.join(here, "..");
+var HOST_MARKS = new Set([".orphaned_at", ".in_use"]);
+
+// server/src/project.ts
+import { execFileSync as execFileSync2 } from "node:child_process";
+import fs5 from "node:fs";
+import path6 from "node:path";
+var localFile = () => path6.join(sphicaHome(), "projects.json");
+var LOCAL_KEY = /^[a-z0-9][a-z0-9._-]*$/;
+function normalizeRemote(url2) {
+  const raw = String(url2 ?? "").trim();
+  if (!raw)
+    return null;
+  const scp = raw.match(/^(?:[^@/]+@)?([^:/]+):(?!\/)(.+?)(?:\.git)?$/);
+  if (scp)
+    return `${scp[1]}/${scp[2]}`;
+  try {
+    const u = new URL(raw);
+    if (!u.hostname)
+      return null;
+    const p = u.pathname.replace(/\.git$/, "").replace(/^\/+|\/+$/g, "");
+    return p ? `${u.hostname}/${p}` : u.hostname;
+  } catch {
+    return null;
+  }
+}
+var git = (dir, ...args) => {
+  try {
+    return execFileSync2("git", ["-C", dir, ...args], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5000
+    }).trim();
+  } catch {
+    return null;
+  }
+};
+function localMap() {
+  let raw;
+  try {
+    raw = fs5.readFileSync(localFile(), "utf8");
+  } catch (e) {
+    if (e.code === "ENOENT")
+      return {};
+    throw e;
+  }
+  let m;
+  try {
+    m = JSON.parse(raw);
+  } catch {
+    m = null;
+  }
+  if (!m || typeof m !== "object" || Array.isArray(m) || Object.entries(m).some(([root, name]) => !path6.isAbsolute(root) || typeof name !== "string" || !LOCAL_KEY.test(name)))
+    throw new Error(`${localFile()} is not a valid JSON project table. Fix or delete it, then name the project again.`);
+  return m;
+}
+function identify(dir) {
+  const given = path6.resolve(dir);
+  const top = git(given, "rev-parse", "--show-toplevel");
+  const root = top || given;
+  const remote = top ? normalizeRemote(git(root, "remote", "get-url", "origin")) : null;
+  if (remote)
+    return { key: `git:${remote}`, root, name: remote.split("/").slice(1).join("/") || remote };
+  const map3 = localMap();
+  for (let d = root;; d = path6.dirname(d)) {
+    const local = map3[d];
+    if (local && LOCAL_KEY.test(local))
+      return { key: `local:${local}`, root: d, name: local };
+    if (top || path6.dirname(d) === d)
+      return null;
+  }
+}
+async function projectId(db, key) {
+  const r = await db.selectFrom("project").select("id").where("key", "=", key).executeTakeFirst();
+  return r?.id ?? null;
+}
+
 // server/src/review.ts
 var ESCAPES = { a: 7, b: 8, t: 9, n: 10, v: 11, f: 12, r: 13, '"': 34, "\\": 92 };
 function gitPath(token, prefix) {
@@ -46428,11 +46781,11 @@ function gitPath(token, prefix) {
 }
 function parseDiff(text) {
   const files = [];
-  const at = (path5) => {
-    const found = files.find((f2) => f2.path === path5);
+  const at = (path7) => {
+    const found = files.find((f2) => f2.path === path7);
     if (found)
       return found;
-    const f = { path: path5, added: [], lines: [] };
+    const f = { path: path7, added: [], lines: [] };
     files.push(f);
     return f;
   };
@@ -46579,19 +46932,37 @@ async function checkFindings(db, projectId2, files, raw) {
   return problems;
 }
 
+// server/src/trace.ts
+var PENDING_DAYS = 30;
+var pendingCutoff = (now) => new Date(now.getTime() - PENDING_DAYS * 86400000).toISOString();
+var untracedOwner = (eb) => eb.selectFrom("source as m").whereRef("m.session_id", "=", "s.id").where("m.author_kind", "=", "owner").where(({ not, exists, selectFrom }) => not(exists(selectFrom("source_processing as p").whereRef("p.source_id", "=", "m.id").select(sql`1`.as("x")))));
+var untracedSessions = (db, projectId2) => db.selectFrom("session as s").where("s.project_id", "=", projectId2).where((eb) => eb.exists(untracedOwner(eb).select(sql`1`.as("x")))).select((eb) => [
+  "s.id",
+  "s.host",
+  "s.started_at",
+  "s.branch",
+  eb.selectFrom("source as o").whereRef("o.session_id", "=", "s.id").where("o.author_kind", "=", "owner").select((o) => o.fn.max("o.created_at").as("last")).as("last"),
+  untracedOwner(eb).select((m) => m.fn.countAll().as("waiting")).as("waiting"),
+  untracedOwner(eb).select((m) => m.fn.min("m.id").as("first")).as("first")
+]);
+
 // server/src/status.ts
-async function pendingCount(db, projectId2) {
-  const r = await db.selectFrom("session as s").where("s.project_id", "=", projectId2).where((eb) => eb.exists(eb.selectFrom("source as m").whereRef("m.session_id", "=", "s.id").where("m.author_kind", "=", "owner").where((eb2) => eb2.not(eb2.exists(eb2.selectFrom("source_processing as p").whereRef("p.source_id", "=", "m.id").select(sql`1`.as("x"))))).select(sql`1`.as("x")))).select((eb) => eb.fn.countAll().as("n")).executeTakeFirst();
-  return Number(r?.n ?? 0);
-}
-async function coverage(db, projectId2) {
+async function pendingCount(db, projectId2, now = new Date) {
+  const cutoff = pendingCutoff(now);
+  const r = await db.selectFrom(untracedSessions(db, projectId2).as("w")).select([
+    sql`count(case when w.last >= ${cutoff} then 1 end)`.as("recent"),
+    sql`count(case when w.last < ${cutoff} then 1 end)`.as("older")
+  ]).executeTakeFirst();
+  return { recent: Number(r?.recent ?? 0), older: Number(r?.older ?? 0) };
+}
+async function coverage(db, projectId2, now) {
   const count = async (q) => Number((await q)?.n ?? 0);
   const units = (where) => count(where(unitBase()).select((eb) => eb.fn.countAll().as("n")).executeTakeFirst());
   const unitBase = () => db.selectFrom("unit").where("project_id", "=", projectId2);
   const processed = (outcome) => db.selectFrom("source_processing as p").innerJoin("source as m", "m.id", "p.source_id").where("m.project_id", "=", projectId2).where("p.outcome", "=", outcome).where("m.session_id", "is not", null).select("m.session_id");
-  const [sessions, pendingSessions, emptySessions, sources, active, candidates, quarantined, work] = await Promise.all([
+  const [sessions, pending, emptySessions, sources, active, candidates, quarantined, work] = await Promise.all([
     count(db.selectFrom("session").where("project_id", "=", projectId2).select((eb) => eb.fn.countAll().as("n")).executeTakeFirst()),
-    pendingCount(db, projectId2),
+    pendingCount(db, projectId2, now),
     count(db.selectFrom("session").where("id", "in", processed("no_unit")).where("id", "not in", processed("units")).select((eb) => eb.fn.countAll().as("n")).executeTakeFirst()),
     count(db.selectFrom("source").where("project_id", "=", projectId2).select((eb) => eb.fn.countAll().as("n")).executeTakeFirst()),
     units((q) => q.where("lifecycle", "=", "active")),
@@ -46599,15 +46970,21 @@ async function coverage(db, projectId2) {
     units((q) => q.where("extraction", "=", "quarantined")),
     db.selectFrom("work").where("project_id", "=", projectId2).where("status", "in", ["active", "blocked", "paused"]).orderBy("updated_at", "desc").select(["title", "current", "status"]).limit(5).execute()
   ]);
-  return { sessions, pendingSessions, emptySessions, sources, active, candidates, quarantined, work };
+  return { sessions, pending, emptySessions, sources, active, candidates, quarantined, work };
 }
-async function status(db, projectId2, name) {
-  const c = await coverage(db, projectId2);
+async function status(db, projectId2, name, now = new Date) {
+  const c = await coverage(db, projectId2, now);
   const lines = [
     `${name}`,
     `Captured: ${plural2(c.sessions, "session")}, ${plural2(c.sources, "source")}.`,
     `Extracted: ${plural2(c.active, "active record")}, ${plural2(c.candidates, "candidate")} not active yet (waiting for adoption or evidence), ${plural2(c.quarantined, "quarantined record")}.`,
-    c.pendingSessions ? `${plural2(c.pendingSessions, "session")} not traced yet: their decisions exist only as captured text (run /sphica:trace pending).` : "Every captured session has been traced.",
+    ...c.pending.recent ? [
+      `${plural2(c.pending.recent, "session")} not traced yet: their decisions exist only as captured text (run /sphica:trace pending).`
+    ] : [],
+    ...c.pending.older ? [
+      `${c.pending.older} older ${c.pending.older === 1 ? "session" : "sessions"} (last owner message over ${PENDING_DAYS} days ago) not traced; /sphica:trace pending lists them.`
+    ] : [],
+    ...c.pending.recent || c.pending.older ? [] : ["Every captured session has been traced."],
     ...c.emptySessions ? [`${plural2(c.emptySessions, "session")} traced with nothing to record.`] : [],
     c.work.length ? `Work in progress:
 ${framed(c.work.map((w) => `- ${head(inline(w.title), 200)} (${w.status}): ${head(inline(w.current), 500)}`).join(`
@@ -46775,6 +47152,25 @@ server.registerTool("read", {
 });
 var DIFF = exports_external.string().min(1).max(2000000).describe("The change under review as a unified diff (git diff output)");
 var notChecked = (e) => text(`Decision lane: not checked. Sphica unavailable: ${head(reason(e), 300)}. Report the decision check as not run, not as passed.`, true);
+server.registerTool("overview", {
+  title: "Live decisions, and records that need a look",
+  description: "On request, not before every change. view live lists every active decision and constraint of the project, grouped by the directory it " + "applies to, a page at a time (pass after from the previous page). view look lists live records whose code file is gone or whose symbol " + "is not found, written conditions for reconsidering an option (for you to judge, never applied), and lines in CLAUDE.md, AGENTS.md, or " + ".claude/rules marked <!-- sphica: key --> whose record was replaced or withdrawn. Read a record by its key before relying on it.",
+  inputSchema: {
+    view: exports_external.enum(["live", "look"]).describe("live: every active decision and constraint; look: records that need a look"),
+    after: exports_external.number().int().min(0).optional().describe("With live: the id the previous page said to continue after"),
+    cwd: CWD
+  },
+  annotations: READ_ONLY
+}, async (a) => {
+  try {
+    const p = await projectOf(a.cwd);
+    if (typeof p === "string")
+      return text(p);
+    return text(framed(a.view === "live" ? await liveOverview(db, p.id, a.after ?? null) : await lookOverview(db, p.id, p.root)));
+  } catch (e) {
+    return text(`Sphica unavailable: ${head(reason(e), 300)}`, true);
+  }
+});
 server.registerTool("review_select", {
   title: "Past decisions a change touches",
   description: "For a code review: the active decisions, constraints, and implementation records this diff touches (records anchored to a changed path, " + "and records with no code location that forbid or defer an option an added line names). Judge each against the diff, then check the verdicts with review_check.",