@sporhq/spor 0.2.3 → 0.2.6

package/.claude-plugin/plugin.json

@@ -2,6 +2,6 @@
   "name": "spor",
   "displayName": "Spor Context Compiler",
   "description": "Maintains a typed, versioned knowledge graph and compiles compact briefings from it: session-start injection, per-prompt relevance digests, capture at discovery, end-of-session distillation, decision queue.",
-  "version": "0.2.3",
+  "version": "0.2.6",
   "author": { "name": "losthammer" }
 }

package/README.md

@@ -64,13 +64,36 @@ For the per-host event mapping, fidelity notes, distiller backend, and the
 `AGENTS.md` fallback for hosts with no hook support, see
 [adapters/](adapters/).
 
-To start with a populated graph, ask your agent to run the bundled
-`spor-backfill` agent against your existing sources — in Claude Code:
-*"use the spor-backfill subagent to bootstrap a Spor graph for this repo."*
-It is a **subagent** (invoked through the Task tool, not a `/spor:` slash
-command), so it runs in its own context, mining git history, design docs, and
-issue trackers into a first graph. Or skip that and just work — distillation
-grows the graph one session at a time.
+To start with a populated graph, run `/spor:backfill` — the onboarding door. It
+dispatches the heavy mining (git history, design docs, issue trackers, edges
+first) to the bundled `spor-backfill` **subagent**, which runs in its own
+context, and then proposes how to group your repos into projects (re-run it as
+you add repos). Or skip it and just work — distillation grows the graph one
+session at a time.
+
+## Dispatching background agents
+
+`spor dispatch` hands a task to Claude Code's background-agent machinery
+(`claude --bg`) with a briefing already compiled in:
+
+```bash
+spor dispatch "wire up token rotation in the pipeline"   # free-text task, briefed
+spor dispatch issue-86                                    # a node id — briefs its neighborhood
+spor dispatch --from-queue                                # the top item from 'spor next'
+spor dispatch --backfill                                  # onboard this repo via /spor:backfill
+spor dispatch <task> --print                              # dry run: show dir, prompt, argv
+```
+
+It compiles the briefing (the same two-arm compiler the `/spor:brief` skill
+drives), prepends it to the prompt, and launches `claude --bg` **in the right
+repo**. Which directory that is comes from a per-machine slug→path map: the
+shared graph is path-free by design (every teammate clones to a different
+path), so the map is local, kept in the config cascade under `dispatch.repos`
+(`spor repos` to inspect; written to `$SPOR_HOME/config.json`). It self-learns
+as you open sessions, so by the time you dispatch a node from another repo,
+Spor already knows where that repo lives. Flags pass through to `claude`
+(`--model`, `--permission-mode`, `--agent`, `--name`); `--full` embeds the whole
+neighborhood and `--no-brief` skips the briefing.
 
 ## What your agent gets, and gives back
 
@@ -91,9 +114,10 @@ The loop runs without you having to drive it:
 You can also ask for any of this directly: an on-demand briefing for a task,
 a correction when a briefing was wrong, a capture of work you're deferring,
 and a ranked queue of what to do next. In Claude Code these surface as
-`/spor:brief`, `/spor:correct`, `/spor:defer`, and `/spor:next`. (Graph
-bootstrapping is separate: `spor-backfill` is a *subagent* you invoke by
-asking your agent to use it — it does not appear in the `/spor:` slash menu.)
+`/spor:brief`, `/spor:correct`, `/spor:defer`, and `/spor:next`, plus
+`/spor:backfill` to bootstrap/extend the graph and organize repos into projects.
+(`/spor:backfill` is the discoverable door; the heavy git-history mining still
+runs in the `spor-backfill` subagent it dispatches.)
 
 Corrections are durable. When a briefing includes something stale or misses
 something it should have known, you record the correction once, and every

package/bin/spor.js

@@ -57,6 +57,14 @@ Repo scoping
   brief <id>           compile a briefing for a node (alias: compile --root <id>)
   validate             lint the local graph (byte-identical)
 
+Dispatch (Claude Code background agents)
+  dispatch "<task>"    compile a briefing + launch 'claude --bg' in the repo.
+                       Also: dispatch <node-id> | --node <id> | --from-queue |
+                       --backfill. Flags: --dir P, --full, --no-brief, --model M,
+                       --permission-mode P, --agent A, --name N, --print
+  repos                show the local slug->repo-dir map used to pick the
+                       directory (repos add <slug> <path> | repos rm <slug>)
+
 Other
   cost [--since D]      LLM spend summary from journal/llm-calls (local)
   version              print version
@@ -905,6 +913,262 @@ async function cmdInstall(cfg, args) {
   return rc;
 }
 
+// --- spor dispatch: kick off a Claude Code background agent --------------
+// (task-spor-cli-dispatch-background-agents) Compile a briefing for a task and
+// launch `claude --bg "<prompt>"` in the correct repo. The "correct repo" comes
+// from a per-machine slug->path map stored in the config cascade under
+// `dispatch.repos` (read via cfg.get; written to $SPOR_HOME/config.json) — the
+// shared graph is path-free by design (repo nodes carry slugs/fingerprints,
+// never a local path; teammates clone to different paths), so the map MUST be
+// local. It self-learns from session-start and from `--dir`/`spor repos`.
+
+// Read a single frontmatter scalar from raw node markdown (regex, like the
+// engines' parser — no YAML lib). `repo:` is the current stamp; `project:` legacy.
+function fmField(raw, key) {
+  const m = raw.match(new RegExp(`^${key}: *(.*)$`, "m"));
+  return m ? m[1].trim() : null;
+}
+
+// Resolve a node id to { id, raw, repo, title } or null if it doesn't exist.
+async function resolveNode(cfg, id) {
+  let raw = "";
+  if (cfg.mode() === "remote") {
+    const r = await remote.get(cfg, `/v1/nodes/${encodeURIComponent(id)}`, { timeoutMs: 6000 });
+    if (!r.ok) return null;
+    raw = (r.json && r.json.raw) || r.text || "";
+  } else {
+    try {
+      raw = fs.readFileSync(path.join(cfg.nodesDir(), `${id}.md`), "utf8");
+    } catch {
+      return null;
+    }
+  }
+  return { id, raw, repo: fmField(raw, "repo") || fmField(raw, "project"), title: fmField(raw, "title") || "" };
+}
+
+// Compile a briefing: a node id -> its neighborhood; free text -> a digest.
+// Mode-aware, reusing the primitives the /spor:brief skill drives. Default is
+// the compact digest; `full` emits the whole neighborhood. "" = graph had
+// nothing relevant (or the compile failed — fail-soft, dispatch still proceeds).
+async function compileBriefing(cfg, { nodeId, query, full, project }) {
+  if (cfg.mode() === "remote") {
+    if (nodeId) {
+      const r = await remote.get(cfg, `/v1/nodes/${encodeURIComponent(nodeId)}`, { timeoutMs: 8000 });
+      return r.ok && r.json ? r.json.raw || r.text || "" : "";
+    }
+    const r = await remote.post(cfg, "/v1/digest", project ? { query, project } : { query });
+    return r.ok && r.json && r.json.found !== false ? r.json.text || "" : "";
+  }
+  const args = nodeId ? ["--root", nodeId] : ["--query", query];
+  if (!full) args.push("--digest");
+  if (project) args.push("--project", project);
+  args.push("--quiet"); // suppress the stderr stats / no-graph lines
+  const r = spawnSync(process.execPath, [path.join(ROOT, "lib", "compile.js"), ...args], { encoding: "utf8" });
+  return (r.stdout || "").trim();
+}
+
+// The single highest-ranked open queue item (for --from-queue). Mode-aware,
+// fail-soft (null on any error/empty).
+async function topQueueItem(cfg, slug) {
+  if (cfg.mode() === "remote") {
+    const q = slug ? `?project=${encodeURIComponent(slug)}&limit=1` : "?limit=1";
+    const r = await remote.get(cfg, `/v1/queue${q}`, { timeoutMs: 6000 });
+    return r.ok && r.json ? (r.json.items || [])[0] || null : null;
+  }
+  try {
+    const g = require(path.join(ROOT, "lib", "graph.js")).loadGraph(cfg.nodesDir());
+    const { rankQueue } = require(path.join(ROOT, "lib", "queue.js"));
+    const r = rankQueue(g, slug ? { project: slug, limit: 1 } : { limit: 1 });
+    return (r.items || [])[0] || null;
+  } catch {
+    return null;
+  }
+}
+
+// Resolve the directory to launch in. --dir wins; else a known slug is looked up
+// in the map; else the cwd's repo root. { dir:null } means "slug unknown here".
+function resolveDir(cfg, { dir, slug }) {
+  if (dir) {
+    const abs = path.resolve(dir);
+    return { dir: abs, slug: slug || u.projectSlug(abs), source: "--dir" };
+  }
+  if (slug) {
+    const p = (cfg.get("dispatch.repos", {}) || {})[slug];
+    return p ? { dir: p, slug, source: "config" } : { dir: null, slug, source: "unknown" };
+  }
+  return { dir: repoRoot(), slug: safeSlug(), source: "cwd" };
+}
+
+// Quote an argv element for the --print display only (never used to spawn).
+function shellQuote(s) {
+  return /[^\w./:-]/.test(s) ? `'${String(s).replace(/'/g, "'\\''")}'` : s;
+}
+
+async function cmdDispatch(cfg, args) {
+  const dryRun = args.includes("--print") || args.includes("--dry-run");
+  const full = args.includes("--full");
+  const noBrief = args.includes("--no-brief");
+  const backfill = args.includes("--backfill");
+  const fromQueue = args.includes("--from-queue");
+  const dirOpt = optVal(args, "dir");
+  const model = optVal(args, "model");
+  const permMode = optVal(args, "permission-mode");
+  const agent = optVal(args, "agent");
+  let nodeId = optVal(args, "node");
+  let targetSlug = optVal(args, "slug");
+  let name = optVal(args, "name");
+
+  // Positional task text: everything that isn't a flag or a flag's value.
+  const VALUE_OPTS = new Set(["dir", "node", "slug", "model", "permission-mode", "agent", "name"]);
+  const pos = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith("--")) {
+      if (VALUE_OPTS.has(a.slice(2))) i++;
+      continue;
+    }
+    pos.push(a);
+  }
+  let taskText = pos.join(" ").trim();
+
+  let brief = "";
+  let instruction = "";
+
+  if (fromQueue) {
+    const top = await topQueueItem(cfg, targetSlug);
+    if (!top || !top.id) {
+      err("queue empty — nothing to dispatch");
+      return 1;
+    }
+    nodeId = top.id;
+    targetSlug = targetSlug || top.repo || top.project || null;
+  }
+
+  if (backfill) {
+    // Onboarding a (possibly thin) repo: dispatch the skill; no briefing to compile.
+    instruction = taskText ? `/spor:backfill\n\n${taskText}` : "/spor:backfill";
+    name = name || "spor-backfill";
+  } else if (!nodeId && pos.length === 1 && /^[a-z0-9]+(-[a-z0-9]+)+$/.test(pos[0])) {
+    // Auto-detect: a single hyphenated token that resolves to a node => node mode.
+    const maybe = await resolveNode(cfg, pos[0]);
+    if (maybe) {
+      nodeId = maybe.id;
+      taskText = "";
+    }
+  }
+
+  if (!backfill && nodeId) {
+    const node = await resolveNode(cfg, nodeId);
+    if (!node) {
+      err(`no such node: ${nodeId}`);
+      return 1;
+    }
+    targetSlug = targetSlug || node.repo || null;
+    if (!noBrief) brief = await compileBriefing(cfg, { nodeId, full, project: targetSlug });
+    instruction = `Work on ${nodeId}${node.title ? ` — ${node.title}` : ""}. The compiled Spor briefing above is your standing context.${taskText ? ` ${taskText}` : ""}`;
+    name = name || nodeId;
+  } else if (!backfill) {
+    if (!taskText) {
+      err('usage: spor dispatch "<task>" | --node <id> | --from-queue | --backfill');
+      return 1;
+    }
+    if (!noBrief) brief = await compileBriefing(cfg, { query: taskText, full, project: targetSlug });
+    instruction = taskText;
+    name = name || taskText.split(/\s+/).slice(0, 8).join(" ").slice(0, 60);
+  }
+
+  const res = resolveDir(cfg, { dir: dirOpt, slug: targetSlug });
+  if (!res.dir) {
+    err(`don't know where '${res.slug}' lives on this machine.`);
+    err(`  run 'spor dispatch' from inside that repo once (it self-registers), then re-run, or:`);
+    err(`  spor repos add ${res.slug} <path>`);
+    err(`  or pass --dir <path>.`);
+    return 1;
+  }
+  if (!fs.existsSync(res.dir)) {
+    err(`target dir does not exist: ${res.dir}`);
+    return 1;
+  }
+  // Learn the mapping from this CLI use too.
+  u.registerRepo(cfg.graphHome(), res.slug, res.dir);
+
+  const prompt = brief
+    ? `# Spor briefing (compiled for this task — your standing context)\n\n${brief}\n\n---\n\n# Task\n\n${instruction}\n`
+    : instruction;
+
+  const claudeBin = process.env.SPOR_CLAUDE_CMD || "claude";
+  const claudeArgs = ["--bg"];
+  if (name) claudeArgs.push("--name", name);
+  if (model) claudeArgs.push("--model", model);
+  if (permMode) claudeArgs.push("--permission-mode", permMode);
+  if (agent) claudeArgs.push("--agent", agent);
+  claudeArgs.push(prompt);
+
+  if (dryRun) {
+    out(`dir:    ${res.dir}  (slug: ${res.slug}, via ${res.source})`);
+    out(`brief:  ${brief ? `${brief.length} bytes` : "(none — graph had nothing relevant, or --no-brief/--backfill)"}`);
+    out(`run:    ${claudeBin} ${claudeArgs.slice(0, -1).map(shellQuote).join(" ")} <prompt>`);
+    out(`\n--- prompt ---\n${prompt}`);
+    return 0;
+  }
+
+  if (claudeBin === "claude" && !hasCmd("claude")) {
+    err("claude CLI not on PATH — install Claude Code, then re-run (or 'spor dispatch … --print' to see the prompt).");
+    return 1;
+  }
+  const r = spawnSync(claudeBin, claudeArgs, { cwd: res.dir, stdio: "inherit" });
+  if (r.error) {
+    err(`could not launch ${claudeBin}: ${r.error.message}`);
+    return 1;
+  }
+  return r.status == null ? 1 : r.status;
+}
+
+// --- spor repos: inspect/manage the local slug->path map -----------------
+function cmdRepos(cfg, args) {
+  const home = cfg.graphHome();
+  const sub = args[0];
+  if (!sub || sub === "list") {
+    // Resolved through the config cascade (dispatch.repos), so user, global, and
+    // any repo/env override layers compose; writes land in $SPOR_HOME/config.json.
+    const map = cfg.get("dispatch.repos", {}) || {};
+    const keys = Object.keys(map).sort();
+    if (!keys.length) {
+      out("no repos mapped yet — they self-register as you open sessions, or: spor repos add <slug> <path>");
+      return 0;
+    }
+    for (const k of keys) out(`${k}\t${map[k]}`);
+    return 0;
+  }
+  if (sub === "add" || sub === "set") {
+    const slug = args[1];
+    const p = args[2];
+    if (!slug || !p) {
+      err("usage: spor repos add <slug> <path>");
+      return 1;
+    }
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(slug)) {
+      err(`invalid slug '${slug}' — must match ^[a-z0-9][a-z0-9-]*$`);
+      return 1;
+    }
+    const abs = path.resolve(p);
+    u.registerRepo(home, slug, abs);
+    out(`mapped ${slug} -> ${abs}`);
+    return 0;
+  }
+  if (sub === "rm" || sub === "remove" || sub === "forget") {
+    const slug = args[1];
+    if (!slug) {
+      err("usage: spor repos rm <slug>");
+      return 1;
+    }
+    out(u.forgetRepo(home, slug) ? `forgot ${slug}` : `no mapping for ${slug}`);
+    return 0;
+  }
+  err("usage: spor repos [list] | spor repos add <slug> <path> | spor repos rm <slug>");
+  return 1;
+}
+
 function version() {
   try {
     return require(path.join(ROOT, "package.json")).version || "0.0.0";
@@ -967,6 +1231,11 @@ async function main() {
     case "compile":
     case "brief":
       return cmdCompile(cfg, verb, args);
+    case "dispatch":
+    case "bg":
+      return await cmdDispatch(cfg, args);
+    case "repos":
+      return cmdRepos(cfg, args);
     case "validate":
       return passthrough("validate.js", args);
     case "cost":

package/lib/config.js

@@ -46,7 +46,7 @@ const REPO_FORBIDDEN_KEYS = ["token"];
 // warning so a silently-ignored setting is visible rather than mysterious.
 const KNOWN_KEYS = new Set([
   "mode", "server", "token", "home", "nodes", "enabled",
-  "search", "distill", "nudge", "inferCommits",
+  "search", "distill", "nudge", "inferCommits", "dispatch",
 ]);
 
 // Map of env var (sans SPOR_/SUBSTRATE_ prefix) -> config key path. Only vars

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sporhq/spor",
-  "version": "0.2.3",
+  "version": "0.2.6",
   "description": "Spor — a shared memory substrate for teams and agents. Decisions, their reasons, and the traces they leave. Knowledge-graph context compiler: session-start briefings, per-prompt digests, capture at discovery, end-of-session distillation, decision queue.",
   "license": "Apache-2.0",
   "author": "Anthony Allen",

package/scripts/engines/session-start.js

@@ -100,6 +100,22 @@ async function sessionStart(input) {
     /* best effort */
   }
 
+  // Learn where this slug lives on THIS machine (slug -> checkout path), so
+  // `spor dispatch` can later launch `claude --bg` in the right repo without a
+  // path map in the shared graph (paths differ per teammate; repo nodes carry
+  // slugs/fingerprints, never a local path). inferenceRoot() is the same repo
+  // root projectSlug() derives the slug from, so path and slug stay consistent
+  // and a linked worktree resolves to its main checkout. Pure side effect: never
+  // alters this run's output; fail-open (registerRepo no-ops on a non-canonical
+  // slug or unchanged value). (task-spor-cli-dispatch-background-agents)
+  try {
+    if (cwd && fs.existsSync(cwd)) {
+      u.registerRepo(graph, slug, u.inferenceRoot(cwd) || cwd);
+    }
+  } catch {
+    /* best effort */
+  }
+
   // -------------------------------------------------------------------------
   // REMOTE MODE
   // -------------------------------------------------------------------------
@@ -160,7 +176,11 @@ async function sessionStart(input) {
       const item = (q.items || [])[0];
       if (item && item.id) {
         const why = item.why || "";
-        oline = `\nopen front: ${item.id} — ${item.title || ""}${why ? ` (${why})` : ""}`;
+        // Emitted phrasing is deliberately plain ("next up:", not the internal
+        // "open front" coinage) so it doesn't prime the agent to parrot jargon
+        // at the human (issue-cc-skill-queue-jargon-mode-theater). The concept
+        // is still the open front; only the user-facing words changed.
+        oline = `\nnext up: ${item.id} — ${item.title || ""}${why ? ` (${why})` : ""}`;
         if ((item.suggest || "do") === "close") oline += " — the queue suggests CLOSING it, not doing it";
         oline += ". Full queue: /spor:next.";
       }
@@ -328,7 +348,8 @@ ${body}`;
     const r = rankQueue(g, { project: slug, limit: 1 });
     const item = (r.items || [])[0];
     if (item && item.id) {
-      oline = `\nopen front: ${item.id} — ${item.title || ""}${item.why ? ` (${item.why})` : ""}`;
+      // Plain user-facing phrasing — mirror remote mode's "next up:" line.
+      oline = `\nnext up: ${item.id} — ${item.title || ""}${item.why ? ` (${item.why})` : ""}`;
       if (item.suggest === "close") oline += " — the queue suggests CLOSING it, not doing it";
       oline += ". Full queue: /spor:next.";
     }

package/scripts/engines/util.js

@@ -331,6 +331,71 @@ function ensureDir(dir) {
   }
 }
 
+// --- local repo map (slug -> checkout path) -------------------------------
+// Which directory a project slug lives in on THIS machine. Per-machine and
+// machine-specific: it is NEVER in the shared graph (every teammate clones to a
+// different path — repo nodes carry slugs/fingerprints, never a local path).
+// It lives in the client config cascade under `dispatch.repos`
+// (dec-spor-client-config-cascade), so it composes with the env/global/repo
+// override layers and is READ via Config.get('dispatch.repos'). Writes target
+// the USER config ($SPOR_HOME/config.json) — the same machine-local,
+// never-committed file that holds server/token — so they never land in a
+// committable repo .spor.json. Learned passively by session-start and written
+// explicitly by `spor repos`/`spor dispatch`; fail-open throughout.
+function userConfigPath(graphHomeDir) {
+  return path.join(graphHomeDir, "config.json");
+}
+// Read-modify-write $SPOR_HOME/config.json, applying `mutate(repos)` to the
+// nested dispatch.repos object. Preserves every other key. Returns true only
+// when it actually wrote. Refuses to clobber a present-but-malformed config
+// (returns false) so a syntax error never costs the user their settings.
+function editRepoMap(graphHomeDir, mutate) {
+  try {
+    const file = userConfigPath(graphHomeDir);
+    let raw = null;
+    try {
+      raw = fs.readFileSync(file, "utf8");
+    } catch {
+      raw = null; // absent — start fresh
+    }
+    let data = {};
+    if (raw != null) {
+      try {
+        data = JSON.parse(raw);
+      } catch {
+        return false; // malformed — do NOT overwrite
+      }
+      if (data == null || typeof data !== "object" || Array.isArray(data)) data = {};
+    }
+    if (data.dispatch == null || typeof data.dispatch !== "object" || Array.isArray(data.dispatch)) data.dispatch = {};
+    const d = data.dispatch;
+    if (d.repos == null || typeof d.repos !== "object" || Array.isArray(d.repos)) d.repos = {};
+    if (!mutate(d.repos)) return false; // unchanged — skip the write
+    if (!ensureDir(graphHomeDir)) return false;
+    fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n");
+    return true;
+  } catch {
+    return false;
+  }
+}
+// Record slug -> dir (last-writer-wins, so a re-clone or worktree updates it).
+// No-op when unchanged, to avoid rewriting config.json on every session.
+function registerRepo(graphHomeDir, slug, dir) {
+  if (!slug || !dir || !/^[a-z0-9][a-z0-9-]*$/.test(slug)) return false;
+  return editRepoMap(graphHomeDir, (repos) => {
+    if (repos[slug] === dir) return false;
+    repos[slug] = dir;
+    return true;
+  });
+}
+function forgetRepo(graphHomeDir, slug) {
+  return editRepoMap(graphHomeDir, (repos) => {
+    if (!(slug in repos)) return false;
+    delete repos[slug];
+    return true;
+  });
+}
+
 function appendLine(file, line) {
   try {
     fs.appendFileSync(file, line + "\n");
@@ -602,11 +667,14 @@ module.exports = {
   byteTail,
   wordCount,
   stripTrailingNewlines,
+  inferenceRoot,
   projectSlug,
   projectGrouping,
   repoFingerprints,
   git,
   ensureDir,
+  registerRepo,
+  forgetRepo,
   appendLine,
   makeLogger,
   loadGraphCached,

package/skills/backfill/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: backfill
+description: Bootstrap or extend a project's Spor graph and organize its repos into projects. Use to backfill a repo's history into the graph, to onboard a newly cloned repo, or to group repos ("organize my repos", "set up / pick a project for this repo", "what project does this repo belong to", "group these repos under a project"). Proposes project groupings from the repos already in the graph and writes nothing without confirmation.
+---
+
+# Backfill & organize
+
+Two onboarding jobs behind one door: get a repo's history INTO the graph, and
+organize the repos that are in it into `type: project` groupings. Both are
+re-runnable — run this again whenever you add a repo.
+
+## 1. Populate the graph (backfill), if the repo is thin
+
+If the current repo has little or no graph content yet, offer to backfill it:
+spawn the **spor-backfill subagent** (Task tool, `subagent_type:
+spor:spor-backfill`) pointed at this repo — it mines git history, design docs,
+and issue trackers into typed nodes, edges first. Skip this when the repo is
+already well represented (the enumeration in step 2 tells you what is present).
+The heavy mining always runs in the subagent, never inline in this session.
+
+## 2. Suggest project groupings
+
+A repo's home is a `type: project` grouping it sits under via a `grouped-under`
+edge (dec-cc-repo-project-membership-edge); project-scoped reads union every
+repo grouped-under one project. A freshly onboarded repo starts **ungrouped**,
+which is valid — repo-scoped reads work on its slug. This step proposes the
+single home for confirmation; it is the whole point of running this again as
+repos accumulate.
+
+### a. Enumerate what exists
+
+Gather every `type: repo` and `type: project` node, plus each repo's `slugs`,
+`fingerprints`, and current `grouped-under` edge (if any):
+
+- **With the Spor MCP tools** (Cowork, or Claude Code with the connector):
+  call `render_lens` with no `lens_id` to list the saved lenses, render the
+  project-breakdown one to see existing projects and their members, and
+  `query_graph` for repo nodes; `get_node` each repo to read its `fingerprints`.
+- **Local mode** (`SPOR_SERVER` unset): scan the graph home directly —
+  ```bash
+  SPOR_HOME="${SPOR_HOME:-$HOME/.spor}"; [ -d "$SPOR_HOME/nodes" ] || SPOR_HOME="$HOME/.substrate"
+  grep -lE '^type: (repo|project)$' "$SPOR_HOME"/nodes/*.md
+  ```
+  Read each match: repo nodes carry `slugs:` and `fingerprints:` and (if homed)
+  a `grouped-under` edge; project nodes are the groupings themselves.
+
+The repos with no `grouped-under` edge are the ones to home.
+
+**Bridge older backfills.** A repo backfilled before identity-node
+auto-registration (client ≤ 0.2.2) has `repo:`/`project:` stamps on its work
+nodes but no `type: repo` node — and a home edge has nothing to attach to
+without one. So before grouping, find the distinct stamp slugs that have no
+matching `type: repo` node (no `repo-<slug>` id and not in any `slugs:`
+register) and register an ungrouped identity node for each:
+
+- **Local:** write `$SPOR_HOME/nodes/repo-<slug>.md` — `type: repo`,
+  `title: <slug>`, `slugs: [<slug>]`, today's `date`, no edges — then validate
+  (plugin root resolved as in step d).
+- **Spor MCP tools:** `put_node` the same `type: repo` node.
+
+Register them with **slugs only** — fingerprints accrue automatically when a
+session next runs in each repo (session-start records them). The repo you are
+currently in usually already has its node, since session-start registers it on
+first sight; this step exists so a single `/spor:backfill` run can surface and
+home *all* of a user's already-backfilled repos, not just the current one.
+Announce which identity nodes you registered. (This is mechanical — the slugs
+demonstrably exist in the graph — so it does not need the per-grouping
+confirmation that step c does.)
+
+### b. Group the ungrouped repos by signal
+
+For each ungrouped repo, find its best home. Signals, strongest first:
+
+1. **Git remote org** — `fingerprints: [remote:github.com/<org>/<repo>]`. Repos
+   sharing an org almost always belong to one product (`sporhq/spor` +
+   `sporhq/spor-server` → one project). This is the primary signal.
+2. **Shared name stem** — `acme-web`, `acme-api`, `acme-mobile` → `acme`.
+3. **Cross-repo edges** — a repo whose nodes carry `derived-from`/`blocks`/
+   `relates-to` edges into another repo's nodes belongs with that repo.
+4. Shared people (contributors/stewards), then — weakest, last resort — topic
+   similarity across the repos' node text.
+
+### c. Propose — never auto-write
+
+Present each suggestion with its evidence and let the user confirm before any
+write:
+
+> - Group **repo-acme-api** under **proj-acme** (existing, ⊇ {repo-acme-web}) —
+>   shared org `github.com/acme`, shared stem `acme`.  [extend]
+> - Create **proj-acme-platform** ⊇ {repo-acme-api, repo-acme-jobs} — shared
+>   org + 3 cross-repo edges.  [new]
+
+Rules, from the two-layer identity model (dec-cc-repo-project-two-layer-identity):
+
+- **One home per repo.** Never propose a repo into two projects — suggestions
+  are mutually exclusive per repo.
+- **Co-ownership is banned.** A repo genuinely shared by two products gets its
+  OWN grouping, not membership in both; cross-cutting work stays at the work
+  layer as edges, not as duplicated groupings.
+- **Ungrouped is a fine outcome.** If there is no real signal, leave the repo
+  ungrouped and say so — don't invent a singleton project to fill the slot
+  unless the user asks for one.
+- Prefer **extending** an existing project over creating a near-duplicate.
+
+### d. Write the confirmed homes
+
+A grouping node's id is `proj-<stem>` (the `proj-` grouping prefix); it owns no
+slugs or fingerprints — those live on the repo nodes. The home is a
+`grouped-under` edge written ON the repo node, pointing TO the project.
+
+- **Spor MCP tools:** `put_node` the new `type: project` node (skip if it
+  exists), then for each member repo `add_edge {id: "repo-<slug>", type:
+  "grouped-under", to: "proj-<stem>"}`. To RE-HOME a repo later, remove the old
+  `grouped-under` edge and add the new one — still exactly one home.
+- **Local mode:** create `$SPOR_HOME/nodes/proj-<stem>.md` (`type: project`,
+  `title`, `summary`, today's `date`), and add a
+  `- {type: grouped-under, to: proj-<stem>}` line under each member repo node's
+  `edges:`. Then validate — resolve the plugin root the session-start hook
+  cached (issue-cc-skill-plugin-root-unsubstituted):
+  ```bash
+  SPOR_ROOT="$(cat "${SPOR_HOME:-$HOME/.spor}/cache/plugin-root" 2>/dev/null \
+    || cat "$HOME/.substrate/cache/plugin-root" 2>/dev/null)"
+  SPOR_ROOT="${SPOR_ROOT:-$CLAUDE_PLUGIN_ROOT}"
+  node "$SPOR_ROOT/lib/validate.js"
+  ```
+  Fix anything it flags, and commit the graph repo if it is one.
+
+Report what you grouped, and — just as important — what you left ungrouped and
+why.

package/skills/brief/SKILL.md

@@ -9,6 +9,13 @@ You are the distiller stage of the Spor context compiler. The traversal
 stage is mechanical; your job is to turn its neighborhood document into a
 briefing an agent (or human) can act on without reading anything else.
 
+**Resolve mode silently.** The Spor status line injected at session start tells
+you which mode you're in (`team graph: …` = remote, `A Spor knowledge graph is
+active: …` = local); use it, or test `[ -n "$SPOR_SERVER" ]` once if it isn't in
+context. Don't echo `SPOR_SERVER`/`SPOR_TOKEN`/`SPOR_HOME` or announce the mode
+to the user unless they ask, and run the local-mode resolution below without
+echoing `$SPOR_ROOT`.
+
 Steps:
 
 1. Run the traversal. `$ARGUMENTS` is either a node id (e.g. `issue-86`) or a

package/skills/correct/SKILL.md

@@ -8,6 +8,13 @@ description: Record a standing correction to a Spor briefing (pin/exclude nodes,
 Corrections are nodes. They persist in the graph and are applied at every
 future compile of their target — a context fix made once applies forever.
 
+**Resolve mode silently.** The Spor status line injected at session start tells
+you which mode you're in (`team graph: …` = remote, `A Spor knowledge graph is
+active: …` = local); use it, or test `[ -n "$SPOR_SERVER" ]` once if it isn't in
+context. Don't echo `SPOR_SERVER`/`SPOR_TOKEN`/`SPOR_HOME` or announce the mode
+to the user unless they ask, and run the local-mode resolution below without
+echoing `$SPOR_ROOT`.
+
 ## Remote mode (team graph) — when `SPOR_SERVER` is set
 
 (Env vars here are the `SPOR_*` family; the legacy `SUBSTRATE_*` names are

package/skills/defer/SKILL.md

@@ -14,6 +14,13 @@ Write 2-3 standalone sentences: WHAT the work is and WHY it was deferred
 concrete names (files, endpoints, node ids). Do not pick node types or ids —
 the server's ingestion model does that against the live schema registry.
 
+**Resolve mode silently.** The Spor status line injected at session start tells
+you which mode you're in (`team graph: …` = remote, `A Spor knowledge graph is
+active: …` = local); use it, or test `[ -n "$SPOR_SERVER" ]` once if it isn't in
+context. Don't echo `SPOR_SERVER`/`SPOR_TOKEN`/`SPOR_HOME` or announce the mode
+to the user unless they ask, and run the local-mode resolution below without
+echoing `$SPOR_ROOT`.
+
 ## Remote mode (team graph) — when `SPOR_SERVER` is set
 
 (Env vars here are the `SPOR_*` family; the legacy `SUBSTRATE_*` names are

package/skills/next/SKILL.md

@@ -11,6 +11,16 @@ unprocessed captures, org-defined types) ranked by an advisory blend — what th
 their neighborhood, age — plus any human-set `priority:`. High staleness
 (anchors superseded or gone) flips the suggestion to **close**, not do.
 
+## Mode — resolve it silently, never announce it
+
+You already know your mode: the Spor status line injected at session start says
+either `team graph: …` (remote — a `SPOR_SERVER` is set) or `A Spor knowledge
+graph is active: …` (local). Use that; if it isn't in context, test
+`[ -n "$SPOR_SERVER" ]` once. Either way, do **not** echo
+`SPOR_SERVER`/`SPOR_TOKEN`/`SPOR_HOME`, and do **not** tell the user which mode
+is running unless they ask — it's plumbing they don't need. Run the commands
+below quietly (no `echo` of `$SPOR_ROOT` or the slug).
+
 ## Remote mode (team graph) — when `SPOR_SERVER` is set
 
 (Env vars here are the `SPOR_*` family; the legacy `SUBSTRATE_*` names are
@@ -42,18 +52,30 @@ plugin root from the path the session-start hook cached
 SPOR_ROOT="$(cat "${SPOR_HOME:-$HOME/.spor}/cache/plugin-root" 2>/dev/null \
   || cat "$HOME/.substrate/cache/plugin-root" 2>/dev/null)"
 SPOR_ROOT="${SPOR_ROOT:-$CLAUDE_PLUGIN_ROOT}"
-node "$SPOR_ROOT/lib/queue.js"            # or --project <slug>, --json
+node "$SPOR_ROOT/lib/queue.js" --json      # or --project <slug>, --limit <n>
 ```
 
+Use `--json` and compose the human view from it — don't show the bare CLI
+listing, whose leading `[<score>]` is an internal ranking number, not something
+to surface (see Presenting).
+
 (No server means no activity feed, so heat is 0 locally; the other signals
 are identical.)
 
 ## Presenting and acting
 
-Show the ranked items with their `why` lines and any `suggest: close` flags —
-the signals are advisory; the human picks. If the result carries `muted` or
-`dormant` counts, mention them (hidden by the viewer's `queue_mute` /
-parked by a `wake:` date — never silently dropped). Then:
+Present in plain language — you are talking to a human who may be new to Spor.
+Lead with the top one or two items to pick up and a short, plain reason each is
+there ("the oldest still-open piece of work", "it blocks three other tasks",
+"nothing's touched it in months"). **Translate** the signals behind each `why`
+line into ordinary words; do **not** surface the raw `score` or internal
+coinages — *open front*, *heat*, *staleness*, *front* are ranking internals, not
+terms a newcomer knows. Honor `suggest: close` by framing the item as likely
+done/abandonable rather than work to start. The ranking is advisory; the human
+picks. If the result carries `muted` or `dormant` counts, mention them in
+passing (hidden by the viewer's `queue_mute` / parked by a `wake:` date — never
+silently dropped). Don't open with a glossary or re-explain Spor on every run —
+one plain sentence of "why this is first" is enough. Then:
 
 1. **Item picked to DO** → start pre-briefed: run a full root compile for it
    (/spor:brief `<item-id>`, or locally with `$SPOR_ROOT` resolved as above: