@sporhq/spor 0.16.0 → 0.18.0

package/.claude-plugin/plugin.json

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

package/GRAPH.md

@@ -109,7 +109,8 @@ Rules:
 | briefing   | `brief-`  | a compiled briefing (output of this system; never traversed) |
 | correction | `corr-`   | standing fix to a briefing: pin/exclude/guidance (never traversed) |
 | question   | `question-` | a routed ask the graph could not answer (queueable; status `open`/`answered`, gated) |
-| person     | `person-` | a member of the org — the identity anchor for `$viewer` binding and Tier-2 question routing (team mode; see "People, routing, and onboarding") |
+| person     | `person-` | a member of the org — mutable display name plus the identity anchor for `$viewer` binding and Tier-2 question routing (team mode; see "People, routing, and onboarding") |
+| organization | `org-` | a durable organization identity anchor; people connect with `member-of-org` for membership and `stewards` for org-admin authority (`org-root` remains the virtual graph-wide operator anchor) |
 | agent      | `agent-`  | a person-owned automation principal — a dispatched session's durable identity, owned by a person via an `owned-by` edge; its writes attribute "agent on behalf of person" (see "Agents") |
 | profile    | `profile-`| a reusable runtime+capability bundle an agent runs under: `harness`, `model`, `skills`/`plugins`/`mcp`. Its runtime fields ARE the dispatch satisfiability spec; `capturable: false` (see "The agent orchestration layer") |
 | routine    | `routine-`| owner-scoped trigger→action automation (`owned-by` a person): declarative `when → do` rules over graph events that dispatch only the owner's agents, AND-ed with org policy; `capturable: false` (see "The agent orchestration layer") |
@@ -571,14 +572,25 @@ date: 2026-06-13
 Team mode (API.md) adds people to the graph. A `person` node is the org
 member's identity anchor — every authenticated token's canonical subject is a
 `person-` node, and `{name, email}` attribution resolves *from that node at
-read time* (API.md §4). Tier-2 question routing and `$viewer`-scoped views
-(your queue, your mutes, "what am I blocking") all key off the person node the
-caller's token is bound to.
+read time* (API.md §4). `name` is the mutable user-facing display label; clients
+render `name || title || email || id`, leaving the opaque `person-…` id as the
+stable machine reference for graph edges, URLs, filters, and token subjects.
+Tier-2 question routing and `$viewer`-scoped views (your queue, your mutes,
+"what am I blocking") all key off the person node the caller's token is bound
+to.
+
+On a shared identity front door, organization authority is also graph-native.
+Each org slug has a durable `organization` node (`org-<slug>`, carrying
+`slug: <slug>`). A person's `member-of-org -> org-<slug>` edge records membership;
+an additional `stewards -> org-<slug>` edge records org-admin authority.
+`stewards -> org-root` keeps its distinct graph-wide operator meaning. Provider
+roles, token bits, and email-domain mappings do not confer either relation.
 
 ```markdown
 ---
 id: person-anthony
 type: person
+name: Anthony Allen
 title: Anthony Allen
 summary: Maintainer; stewards the schema registry and the hook engines.
 email: losthammer@gmail.com
@@ -635,15 +647,19 @@ edges:
 Joining someone to a team graph is three deliberate steps — do all three or
 routing degrades quietly:
 
-1. **Author the `person-<name>` node** (frontmatter above), with `email` set to
-   the address the member commits and authenticates under.
+1. **Author the `person-…` node** (frontmatter above), using the stable canonical
+   subject chosen by the org. Prefer the CLI/admin minting paths, which default
+   new ids to opaque email-derived subjects instead of mutable display-name
+   slugs. Set `name` to the person's display label and `email` to the address
+   the member commits and authenticates under.
 2. **Add `stewards` edges** from that node to the areas/specs/norms they own.
    Without at least one steward in a topic's neighborhood, questions there route
    to no one and fall back to surfacing for everybody — answerable, but not
    *directed*.
-3. **Mint a token bound to the node:** an admin runs `spor-mint-token --person
-   person-<name>` on the server box, or `POST /v1/admin/tokens {person}` over
-   REST (admin-only; API.md §3/§4). The plaintext token is returned once.
+3. **Mint a token bound to the node:** an admin runs `spor invite --person
+   person-…` / `spor invite --name <name> --email <email>`, or
+   `POST /v1/admin/tokens {person}` over REST (admin-only; API.md §3/§4). The
+   plaintext token is returned once.
 
 If a member is reading and writing but **never receives routed questions, sees
 an empty personal queue, or has no mutes take effect**, their token did not bind
@@ -833,6 +849,7 @@ assign that work to a person.
 | `relates-to`     | 0.5    | weak association                                 |
 | `mentions`       | 0.5    | weakest association                              |
 | `stewards`       | 0.4    | this person stewards an area/spec/norm — the Tier-2 question-routing key |
+| `member-of-org`  | 0.3    | this person is a member of the target organization (inverse `has-org-member`); structural identity binding, not admin authority |
 | `grouped-under`  | 0.3    | this repo's home project grouping (inverse `groups`); structural membership, not work dependency |
 | `owned-by`       | 0.3    | this agent is owned by that person (inverse `owns`); structural identity binding, not work dependency |
 | `uses-profile`   | 0.3    | this agent's default profile (the runtime+capability bundle it dispatches under); structural config binding, overridable per assignment/dispatch |
@@ -841,11 +858,12 @@ assign that work to a person.
 | `compiled-for`   | —      | briefing → its task/query (provenance only)      |
 | `shaped-by`      | —      | briefing → corrections applied (provenance only) |
 
-`answers`, `assigned`, `stewards`, and `routed-to` are the person-graph
+`answers`, `assigned`, `stewards`, `member-of-org`, and `routed-to` are person-graph
 edges of Tier-2 question routing; they ship in the seed pack and are
 documented under "People, routing, and onboarding" above. `assigned` and
 `routed-to` point at a `person-` node; `stewards` points from a person to
-the area they own; `answers` points from any answer node back at the
+the area or organization they own; `member-of-org` points from a person to an
+`organization` identity anchor; `answers` points from any answer node back at the
 `question-` it resolves.
 
 `review-requested`, `reviewed-by`, and `changes-requested-by` are the

package/adapters/README.md

@@ -13,7 +13,7 @@ The Spor client is a portable core behind per-host adapters
 
 - **Core**: the four hook engines in `scripts/` (session-start briefing,
   prompt-context digest, post-tool journal, distill capture) and the
-  `bin/spor-hook` dispatcher that normalizes host payload quirks and
+  `bin/spor-hook.js` dispatcher that normalizes host payload quirks and
   envelope event names. All engines are fail-open: any failure injects
   nothing and exits 0.
 - **Universal surfaces**: the server's MCP endpoint (`/mcp`) and REST

package/adapters/codex/README.md

@@ -2,7 +2,7 @@
 
 Codex's hooks are a near-clone of Claude Code's (same JSON-over-stdin payload
 fields, same `hookSpecificOutput.additionalContext` envelope), so this adapter
-is just a manifest over `bin/spor-hook`.
+is just a manifest over `bin/spor-hook.js`.
 
 ## Install
 
@@ -18,8 +18,24 @@ is just a manifest over `bin/spor-hook`.
    (Or merge into an existing `~/.codex/hooks.json` / `[hooks]` table in
    `~/.codex/config.toml`. Per-repo installs go in `<repo>/.codex/hooks.json`.)
 
-3. Approve the hooks in Codex's `/hooks` trust prompt on first run.
-4. Environment (the same variables on every host):
+3. Add the backfill custom agent:
+
+   ```sh
+   mkdir -p ~/.codex/agents
+   {
+     printf 'name = "spor-backfill"\n'
+     printf 'description = "Populate or extend a project'\''s Spor graph (its nodes/ dir) from existing sources -- git history, issue/plan docs, specs, or external trackers (GitHub/Jira/Confluence via gh CLI or MCP tools). Use when bootstrapping a graph from scratch or importing a new source into an existing graph."\n'
+     printf 'developer_instructions = """\n'
+     awk 'BEGIN { n = 0 } /^---$/ { n++; next } n >= 2 { print }' "$SPOR_ROOT/agents/backfill.md"
+     printf '"""\n'
+   } > ~/.codex/agents/spor-backfill.toml
+   ```
+
+   `spor install codex` performs both steps automatically and keeps the custom
+   agent sourced from `agents/backfill.md`.
+
+4. Approve the hooks in Codex's `/hooks` trust prompt on first run.
+5. Environment (the same variables on every host):
 
    ```sh
    export SPOR_SERVER=https://spor.example.com   # remote mode

package/adapters/codex/hooks.json

@@ -4,14 +4,14 @@
       {
         "matcher": "startup|resume",
         "hooks": [
-          { "type": "command", "command": "__SPOR_ROOT__/bin/spor-hook session-start --host codex", "timeout": 20, "statusMessage": "Loading Spor briefing" }
+          { "type": "command", "command": "node \"__SPOR_ROOT__/bin/spor-hook.js\" session-start --host codex", "timeout": 20, "statusMessage": "Loading Spor briefing" }
         ]
       }
     ],
     "UserPromptSubmit": [
       {
         "hooks": [
-          { "type": "command", "command": "__SPOR_ROOT__/bin/spor-hook prompt-context --host codex", "timeout": 15 }
+          { "type": "command", "command": "node \"__SPOR_ROOT__/bin/spor-hook.js\" prompt-context --host codex", "timeout": 15 }
         ]
       }
     ],
@@ -19,14 +19,14 @@
       {
         "matcher": "*",
         "hooks": [
-          { "type": "command", "command": "__SPOR_ROOT__/bin/spor-hook post-tool --host codex", "timeout": 10 }
+          { "type": "command", "command": "node \"__SPOR_ROOT__/bin/spor-hook.js\" post-tool --host codex", "timeout": 10 }
         ]
       }
     ],
     "Stop": [
       {
         "hooks": [
-          { "type": "command", "command": "__SPOR_ROOT__/bin/spor-hook distill --host codex --debounce 900", "timeout": 10 }
+          { "type": "command", "command": "node \"__SPOR_ROOT__/bin/spor-hook.js\" distill --host codex --debounce 900", "timeout": 10 }
         ]
       }
     ]

package/adapters/copilot/spor.json

@@ -2,13 +2,13 @@
   "version": 1,
   "hooks": {
     "sessionStart": [
-      { "type": "command", "command": "__SPOR_ROOT__/bin/spor-hook agents-md", "timeoutSec": 20 }
+      { "type": "command", "command": "node \"__SPOR_ROOT__/bin/spor-hook.js\" agents-md", "timeoutSec": 20 }
     ],
     "postToolUse": [
-      { "type": "command", "command": "__SPOR_ROOT__/bin/spor-hook post-tool --host copilot", "timeoutSec": 10 }
+      { "type": "command", "command": "node \"__SPOR_ROOT__/bin/spor-hook.js\" post-tool --host copilot", "timeoutSec": 10 }
     ],
     "agentStop": [
-      { "type": "command", "command": "__SPOR_ROOT__/bin/spor-hook distill --host copilot --debounce 900", "timeoutSec": 10 }
+      { "type": "command", "command": "node \"__SPOR_ROOT__/bin/spor-hook.js\" distill --host copilot --debounce 900", "timeoutSec": 10 }
     ]
   }
 }

package/adapters/cursor/hooks.json

@@ -2,13 +2,13 @@
   "version": 1,
   "hooks": {
     "sessionStart": [
-      { "command": "__SPOR_ROOT__/bin/spor-hook session-start --host cursor", "timeout": 20 }
+      { "command": "node \"__SPOR_ROOT__/bin/spor-hook.js\" session-start --host cursor", "timeout": 20 }
     ],
     "afterFileEdit": [
-      { "command": "__SPOR_ROOT__/bin/spor-hook post-tool --host cursor", "timeout": 10 }
+      { "command": "node \"__SPOR_ROOT__/bin/spor-hook.js\" post-tool --host cursor", "timeout": 10 }
     ],
     "sessionEnd": [
-      { "command": "__SPOR_ROOT__/bin/spor-hook distill --host cursor", "timeout": 300 }
+      { "command": "node \"__SPOR_ROOT__/bin/spor-hook.js\" distill --host cursor", "timeout": 300 }
     ]
   }
 }

package/adapters/gemini/README.md

@@ -3,7 +3,7 @@
 Gemini CLI's hooks use the same JSON-over-stdin payloads and the same
 `hookSpecificOutput.additionalContext` envelope as Claude Code (it even ships
 a `CLAUDE_PROJECT_DIR` compatibility alias), so this adapter is a manifest
-over `bin/spor-hook`. The only real differences: the per-prompt event is
+over `bin/spor-hook.js`. The only real differences: the per-prompt event is
 called `BeforeAgent` (the dispatcher echoes that name back in the envelope),
 the post-tool event is `AfterTool`, and timeouts are in milliseconds.
 
@@ -51,7 +51,7 @@ export SPOR_NUDGE_CMD='gemini --model gemini-2.5-flash'
 
 - Gemini transcripts are not Claude's JSONL shape; the distiller falls back
   to a generic extractor (every nested `.text` string).
-- Hook stdout must be pure JSON on Gemini; `bin/spor-hook` already
+- Hook stdout must be pure JSON on Gemini; `bin/spor-hook.js` already
   discards engine stderr and emits either one JSON object or nothing.
 - For on-demand graph access, add the Spor MCP server to settings:
 
@@ -60,4 +60,4 @@ export SPOR_NUDGE_CMD='gemini --model gemini-2.5-flash'
   ```
 
 - `GEMINI.md` users: point `contextFileName` at `AGENTS.md` and run
-  `bin/spor-hook agents-md` to get the standing briefing without hooks.
+  `spor-hook agents-md` to get the standing briefing without hooks.

package/adapters/gemini/hooks/hooks.json

@@ -3,14 +3,14 @@
     "SessionStart": [
       {
         "hooks": [
-          { "name": "spor-session-start", "type": "command", "command": "__SPOR_ROOT__/bin/spor-hook session-start --host gemini", "timeout": 20000 }
+          { "name": "spor-session-start", "type": "command", "command": "node \"__SPOR_ROOT__/bin/spor-hook.js\" session-start --host gemini", "timeout": 20000 }
         ]
       }
     ],
     "BeforeAgent": [
       {
         "hooks": [
-          { "name": "spor-prompt-context", "type": "command", "command": "__SPOR_ROOT__/bin/spor-hook prompt-context --host gemini", "timeout": 15000 }
+          { "name": "spor-prompt-context", "type": "command", "command": "node \"__SPOR_ROOT__/bin/spor-hook.js\" prompt-context --host gemini", "timeout": 15000 }
         ]
       }
     ],
@@ -18,14 +18,14 @@
       {
         "matcher": "write_file|replace",
         "hooks": [
-          { "name": "spor-post-tool", "type": "command", "command": "__SPOR_ROOT__/bin/spor-hook post-tool --host gemini", "timeout": 10000 }
+          { "name": "spor-post-tool", "type": "command", "command": "node \"__SPOR_ROOT__/bin/spor-hook.js\" post-tool --host gemini", "timeout": 10000 }
         ]
       }
     ],
     "SessionEnd": [
       {
         "hooks": [
-          { "name": "spor-distill", "type": "command", "command": "__SPOR_ROOT__/bin/spor-hook distill --host gemini", "timeout": 300000 }
+          { "name": "spor-distill", "type": "command", "command": "node \"__SPOR_ROOT__/bin/spor-hook.js\" distill --host gemini", "timeout": 300000 }
         ]
       }
     ]

package/adapters/opencode/README.md

@@ -1,8 +1,8 @@
 # OpenCode adapter
 
 OpenCode has no command-hook system — plugins are in-process JS — so this
-adapter is a single zero-dependency plugin file (`spor.js`) that shells
-out to `bin/spor-hook` with Claude-shaped payloads. Same core, same
+adapter is a single zero-dependency plugin file (`spor.js`) that launches
+`bin/spor-hook.js` with Claude-shaped payloads. Same core, same
 fail-open behavior as every other host.
 
 ## Install

package/adapters/opencode/spor.js

@@ -2,8 +2,8 @@
 //
 // OpenCode has no command-hook system; plugins are in-process JS. This one
 // stays a thin shim over the same portable core every other host uses: each
-// hook synthesizes a Claude-shaped payload and shells out to
-// bin/spor-hook, so briefing/digest/journal/distill behavior is
+// hook synthesizes a Claude-shaped payload and launches the Node dispatcher
+// (bin/spor-hook.js), so briefing/digest/journal/distill behavior is
 // identical across hosts.
 //
 //   chat.message        -> session-start briefing (first message of a session)
@@ -18,7 +18,7 @@
 // nothing. Zero dependencies: node builtins only.
 //
 // Install: symlink this file into ~/.config/opencode/plugins/ (the symlink is
-// resolved to find bin/spor-hook), or copy it and set SPOR_ROOT (legacy
+// resolved to find bin/spor-hook.js), or copy it and set SPOR_ROOT (legacy
 // SUBSTRATE_ROOT still read).
 
 import { spawn } from "node:child_process"
@@ -36,18 +36,20 @@ const GRAPH =
     ? join(homedir(), ".spor")
     : join(homedir(), ".substrate"))
 const DEBOUNCE = process.env.SPOR_DEBOUNCE || process.env.SUBSTRATE_DEBOUNCE || "900"
+const EMBEDDED_ROOT = "__SPOR_ROOT__"
 
 function findDispatcher() {
   const candidates = []
-  const root = process.env.SPOR_ROOT || process.env.SUBSTRATE_ROOT
+  const root =
+    process.env.SPOR_ROOT ||
+    process.env.SUBSTRATE_ROOT ||
+    (EMBEDDED_ROOT !== "__SPOR_ROOT__" ? EMBEDDED_ROOT : "")
   if (root) {
-    candidates.push(join(root, "bin", "spor-hook"))
-    candidates.push(join(root, "bin", "substrate-hook"))
+    candidates.push(join(root, "bin", "spor-hook.js"))
   }
   try {
     const here = dirname(realpathSync(fileURLToPath(import.meta.url)))
-    candidates.push(join(here, "..", "..", "bin", "spor-hook"))
-    candidates.push(join(here, "..", "..", "bin", "substrate-hook"))
+    candidates.push(join(here, "..", "..", "bin", "spor-hook.js"))
   } catch {}
   return candidates.find((c) => existsSync(c)) || null
 }
@@ -59,7 +61,7 @@ function run(bin, args, payload, timeoutMs) {
     let done = false
     const finish = (out) => { if (!done) { done = true; resolve(out) } }
     try {
-      const child = spawn("bash", [bin, ...args], { stdio: ["pipe", "pipe", "ignore"] })
+      const child = spawn(process.execPath, [bin, ...args], { stdio: ["pipe", "pipe", "ignore"] })
       let out = ""
       const timer = setTimeout(() => { try { child.kill("SIGKILL") } catch {}; finish("") }, timeoutMs)
       child.stdout.on("data", (d) => { out += d })

package/bin/spor-hook.cmd

@@ -1,3 +1,4 @@
 @echo off
+where node >nul 2>nul || exit /b 0
 node "%~dp0spor-hook.js" %*
 exit /b 0

package/bin/spor-hook.js

@@ -248,7 +248,9 @@ function logCrash(err) {
 if (require.main === module) {
   main()
     .catch((err) => logCrash(err))
-    .finally(() => process.exit(0));
+    .finally(() => {
+      process.exitCode = 0;
+    });
 }
 
-module.exports = { logCrash };
+module.exports = { logCrash, main };

package/bin/spor.cmd

@@ -1,3 +1,4 @@
 @echo off
+where node >nul 2>nul || exit /b 0
 node "%~dp0spor.js" %*
 exit /b %errorlevel%