@sporhq/spor 0.2.2 → 0.2.5

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.2",
+  "version": "0.2.5",
   "author": { "name": "losthammer" }
 }

package/README.md

@@ -64,10 +64,12 @@ 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, point the bundled `spor-backfill` agent at
-your existing sources: it mines 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.
 
 ## What your agent gets, and gives back
 
@@ -88,7 +90,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`.
+`/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sporhq/spor",
-  "version": "0.2.2",
+  "version": "0.2.5",
   "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

@@ -61,6 +61,25 @@ function nodeBody(raw) {
   return u.stripTrailingNewlines(u.byteHead(awkOut, 7000));
 }
 
+// Durable repo-identity node text (issue-spor-onboard-no-repo-identity-node),
+// mirroring the server's learnFingerprints registration so local and remote
+// produce the same shape. Ungrouped by default — no grouped-under edge; the
+// standing grouping suggester proposes the single home project.
+function repoNodeMarkdown(slug, fp, today) {
+  return `---
+id: repo-${slug}
+type: repo
+title: ${slug}
+summary: Git-repo identity for '${slug}', auto-registered from its fingerprints when the repo first appeared in the local graph. Ungrouped — no home project yet; the grouping suggester proposes a grouped-under home.
+slugs: [${slug}]
+fingerprints: [${fp.join(", ")}]
+date: ${today}
+---
+
+Auto-registered repo identity for \`${slug}\` (issue-spor-onboard-no-repo-identity-node). Created on first sight so the repo is a first-class node: the anchor for rename-healing fingerprint matching and for a \`grouped-under\` home. It starts UNGROUPED by default — repo-scoped reads work on the slug, and the standing grouping suggester proposes its single home project for confirmation. Slug aliases and fingerprints accumulate here across renames and re-clones.
+`;
+}
+
 async function sessionStart(input) {
   const graph = u.graphHome();
   const nodes = path.join(graph, "nodes");
@@ -141,7 +160,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.";
       }
@@ -309,7 +332,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.";
     }
@@ -412,6 +436,26 @@ ${pbody}`;
     /* fail open */
   }
 
+  // Ensure this repo has a durable identity node once it actually has content
+  // in the graph (issue-spor-onboard-no-repo-identity-node). Mirrors the
+  // server's learnFingerprints in remote mode: a backfilled/distilled repo with
+  // no `type: repo` node yet gets one registered from its git fingerprints, so
+  // it is a first-class node — the anchor for a grouped-under home and for
+  // rename-healing. Gated on projCount>0 (real graph content), no owning repo
+  // node yet, and fingerprints present, so a session in some unrelated checkout
+  // never spawns an identity node. Ungrouped by default; the grouping suggester
+  // proposes the home. Pure side effect, written AFTER the briefing is built so
+  // it never alters this run's output; fail-open — never blocks session-start.
+  try {
+    const fp = cwd && fs.existsSync(cwd) ? u.repoFingerprints(cwd) : [];
+    const repoFile = path.join(nodes, `repo-${slug}.md`);
+    if (!owner && projCount > 0 && fp.length && /^[a-z0-9][a-z0-9-]*$/.test(slug) && !fs.existsSync(repoFile)) {
+      fs.writeFileSync(repoFile, repoNodeMarkdown(slug, fp, new Date().toISOString().slice(0, 10)));
+    }
+  } catch {
+    /* best effort — never block session-start */
+  }
+
   return envelope(ctx);
 }
 

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: