@sporhq/spor 0.3.0 → 0.4.0

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

package/API.md

@@ -402,6 +402,19 @@ SPOR_SERVER=https://spor.example.com
 SPOR_TOKEN=spor_pat_...                # per-user token (§4)
 ```
 
+**Opt-in activation.** Spor is opt-in per repo: with the plugin installed, the
+hooks are a full no-op (no context injected, nothing distilled) in any repo that
+has not opted in. A repo is active when its mode is not `off` AND either an
+`enabled` flag is set anywhere in the cascade (`enabled:true`/`false` in a config
+layer, `SPOR_ENABLED=1`/`0`, or a CLI `--enabled`) OR a repo-level `.spor` /
+`.spor.json` marker is present in the cwd ancestry — what `spor enable`, `spor
+link`, and `spor dispatch --backfill` write. An explicit flag wins over marker
+presence (so `enabled:false` forces a no-op even where a marker exists). The
+default — no flag, no marker — is OFF, including in remote mode: a globally
+configured `SPOR_SERVER` resolves the *mode* to remote but does not by itself
+*enable* an unrelated repo, so side projects never distill into the team graph.
+`spor status` / `spor-hook doctor` report whether the current repo is active.
+
 Failure policy: **fail open, never block** — a hook must never break a
 session; connection refused, timeout, 5xx, and auth failure all collapse to
 "the graph has nothing for you".

package/GRAPH.md

@@ -176,6 +176,153 @@ least two — the definition-of-done quorum gate.
   a proposed policy is inert until a *different* identity activates it (the
   native floor protects against self-amendment circularity).
 
+## Authoring a custom schema
+
+A team extends the ontology by writing a `type: schema` node into its graph (it
+overrides or extends the seed pack; QUEUE.md §2). This section assembles one
+end-to-end — the seed pack documents the JSON payload and the attached code
+separately, but never shows a complete custom type in one piece.
+
+**The constraint model is procedural, not declarative.** A schema's `json`
+payload declares only *registry knobs* — `node_type`, `prefix`, `queueable`,
+`traversable`, `always_on`, `capturable`, an edge `weight`, the
+`status.non_resolving` partition. There is **no declarative field list and no
+status enum.** Custom fields are free-form: any flat frontmatter key the
+regex parser accepts (simple `key: value` scalars, YAML-folded multi-line
+values, `pin:`/`exclude:` inline lists, `- {type: X, to: Y}` edges — and nothing
+fancier) is carried verbatim on the node. What a field MUST contain, and which
+status changes are legal, are enforced **in attached code** — two pure functions
+the server runs on the write path:
+
+- **`validate(node) -> string[]`** — the door. Runs on **every write (create
+  AND update)**. It receives the parsed proposed node and returns an array of
+  human-readable error strings; `[]` means accept. A non-empty array rejects the
+  write (`invalid_node`), each string surfaced to the writer as
+  `<schema-id> validate(): <your message>`. This is where required/typed custom
+  fields are enforced.
+- **`transitions(current, proposed, view) -> { allow, reason? }`** — the status
+  gate. Runs on **update only** (the create path is ungated, so a status-less or
+  any first write is always allowed). `current` is the stored node (or `null` if
+  its file is unparseable), `proposed` is the incoming node, and `view` is a
+  read-only join the server computes for the gate:
+  - `view.targets[id]` — `{ exists, type, status, superseded }` for each node
+    this one points an edge at (outbound);
+  - `view.resolvers` — live **inbound** `resolves`/`answers` edges pointing at
+    this node, each `{ id, type, status }`, already filtered to *resolving*
+    states (a withdrawn or in-review resolver is excluded). This is how a type
+    requires a durable outcome on the graph before going terminal (the resolver
+    gate the seed `task`/`issue` schemas use);
+  - `view.non_resolving_statuses` — the registry's resolving-status partition,
+    if the gate wants to judge resolver states itself;
+  - `view.actor` — `{ name, email, via }`, the authenticated writer (for
+    ownership/role gates);
+  - `view.approvals` — the node's review edges to `person` nodes joined to their
+    `roles` (the quorum-gate input; the writer's own self-approval is excluded).
+  Return `{ allow: true }` to permit, or `{ allow: false, reason: "…" }` to deny
+  with an actionable message.
+
+Both hooks are **sandboxed, pure, and fail-closed**: the server runs them in a
+QuickJS-in-wasm sandbox (`SPOR_SANDBOX=vm` is an ops-only escape hatch) across a
+strict JSON boundary — arguments arrive as plain guest data and only JSON-clonable
+return values cross back, so `require`, `process`, `eval`, the `Function`
+constructor, host prototypes, ambient time/IO, and unbounded loops are all
+unavailable (a runaway hits a fuel/memory interrupt). A hook that throws does not
+wave the write through — it **rejects** it. Write the functions accordingly: no
+external state, no side effects, decide only from the arguments. Two more
+attached exports are recognized: `queueSignals(node, ctx)` (a `{ name: number }`
+map blended into the decision-queue ranking) and named upgrade functions
+referenced from `payload.upgrades` (lazy, forward-only field migrations on a
+`schema_version` bump). The **client** half (hooks, the `spor` CLI, `lib/`) only
+*parses and indexes* this code for the registry knobs — it never executes it;
+the server is the sole executor.
+
+Resolution and rollout: a graph-resident schema always beats the seed pack, and
+within a source the higher CalVer `schema_version` wins, so an override must be
+bumped in lockstep with seed changes or it silently shadows them (`validateGraph`
+warns). A schema node goes through the same propose→activate flow it governs — a
+*different* identity must activate it (or a trusted admin git-writes it `active`);
+bump the CalVer and add an `upgrades` chain only when the change is not
+backward-readable.
+
+A complete worked example — a `escalation` type with a required `severity`
+field (enforced in `validate`) and an `open → mitigated → closed` status machine
+whose terminal `closed` demands a resolver (enforced in `transitions`):
+
+````markdown
+---
+id: schema-escalation
+type: schema
+kind: node-schema
+schema_version: 2026.06.16.1
+title: Custom schema for customer-escalation nodes
+summary: A customer escalation with a severity field and an open/mitigated/closed status machine; closing one requires a decision or artifact that resolves it.
+status: active
+date: 2026-06-16
+---
+
+Escalation nodes track a customer-facing incident from raise to close.
+`severity` is a free-form frontmatter field this schema makes mandatory and
+constrains in `validate()`; the status machine and the close-time resolver gate
+live in `transitions()`. Both are the same procedural model the seed types use —
+there is no declarative field or status enum to fill in.
+
+```json
+{
+  "node_type": "escalation",
+  "description": "a customer-facing escalation and its resolution lineage",
+  "prefix": ["esc-"],
+  "queueable": true
+}
+```
+
+```js
+// validate(node) — runs at the door on EVERY write (create and update). Returns
+// an array of error strings; [] accepts. Enforce the free-form custom field here:
+// the payload declares no field list, so a required/typed field is code.
+export function validate(node) {
+  const errors = [];
+  const VALID_SEVERITY = ["sev1", "sev2", "sev3"];
+  if (!node.severity) {
+    errors.push("escalation requires a severity field (sev1 | sev2 | sev3)");
+  } else if (VALID_SEVERITY.indexOf(String(node.severity)) === -1) {
+    errors.push("invalid severity '" + node.severity + "': use sev1, sev2, or sev3");
+  }
+  return errors;
+}
+
+// transitions(current, proposed, view) — runs on UPDATE only; returns
+// { allow, reason? }. Empty status (status-less = live) is always allowed.
+export function transitions(current, proposed, view) {
+  const VALID = ["open", "mitigated", "closed"];
+  const next = ((proposed && proposed.status) || "").toLowerCase();
+  if (next === "") return { allow: true };
+  if (VALID.indexOf(next) === -1) {
+    return {
+      allow: false,
+      reason: "invalid escalation status '" + next + "': valid statuses are " +
+        "open, mitigated, closed — or none, meaning live",
+    };
+  }
+  // closed must record a durable outcome on the graph: a decision or artifact
+  // that resolves this escalation (an inbound resolves edge). view.resolvers is
+  // already filtered to resolving states, so an in-review fix does not count.
+  if (next === "closed") {
+    const rs = (view && view.resolvers) || [];
+    const ok = rs.some((r) => r.type === "decision" || r.type === "artifact");
+    if (!ok) {
+      return {
+        allow: false,
+        reason: "closed requires a decision or artifact node that resolves this " +
+          "escalation (an inbound resolves edge) — record how it was handled on " +
+          "the graph so the neighborhood can surface it",
+      };
+    }
+  }
+  return { allow: true };
+}
+```
+````
+
 ## Norm ride-along
 
 A `norm` node (any `always_on` type) rides along on every compile — but the
@@ -189,6 +336,21 @@ their original order), so the briefing degrades by relevance rather than by the
 downstream 7KB session-start body truncation. A project-blind compile keeps
 every norm, exactly as before.
 
+Project scope resolves to the whole home-project **grouping union**, so a
+grouping that deliberately spans heterogeneous repos (a terraform IaC repo, a
+Go service, a Python service) would still cross-pollinate norms. A norm may
+**narrow** its ride-along with optional flat `applies_to_*` selectors, matched
+against the session's OWN repo (task-cc-norm-ride-along-repo-tag-scope):
+`applies_to_tags: [python]` (∩ the session repo node's `tags`, schema-repo),
+`applies_to_repos: [repo-x]` (the session repo), `applies_to_projects:
+[proj-y]` (a grouping the session repo belongs to). Matching is OR across axes,
+ANY within an axis — deliberately unlike the policy layer's `governs`
+(AND-across-axes). A norm that declares any `applies_to_*` and matches none is
+**excluded** (strict, including in a repo with no `tags` — repo tagging is the
+opt-in that turns scoped norms on); a norm with none keeps the project-scoped
+behavior above, so a graph using no `applies_to_*` is byte-identical
+(norm-cc-byte-identical-refactor).
+
 Because a norm rides along with no relevance gate and the team trust model lets
 every writer author one, the briefing renderer treats norm bodies as an
 **injection surface** (issue-cc-norm-always-on-injection): each is quoted as

package/README.md

@@ -275,12 +275,23 @@ add files only when you want them. A `.spor.json` (committable) is for
 settings the whole repo should share — never put a `token` there; it is
 honored only from the environment or your user/global config.
 
+**Spor is opt-in per repo.** Installing the plugin does not make every repo you
+open participate: a repo is a no-op (no context injected, nothing distilled into
+the shared graph) until it opts in — either it carries a `.spor`/`.spor.json`
+marker, or `enabled` is set anywhere in the cascade (`SPOR_ENABLED=1`, or
+`enabled:true` in user/global config to turn it on everywhere). `spor enable`
+writes the marker below for you; `spor dispatch --backfill` does it as part of
+onboarding. This keeps unrelated side projects out of your team graph even when
+a server is configured globally. Run `spor status` (or `spor-hook doctor`) in a
+repo to see whether it's active.
+
 ```jsonc
 // .spor.json — committed at a repo root
 {
-  "enabled": false,                 // make the plugin a no-op in this repo:
-                                    // unrelated side projects don't pollute
-                                    // the shared graph (default true)
+  "enabled": true,                  // opt this repo in (what `spor enable`
+                                    // writes). Spor is OFF in a repo with no
+                                    // marker; set false to force a no-op even
+                                    // where a marker would otherwise enable it
   "search": {
     "minSim": 0.10,                 // raise/lower the relevance gate
     "projects": {

package/bin/spor.js

@@ -111,7 +111,7 @@ async function cmdStatus(cfg) {
   const home = cfg.graphHome();
   const nodesDir = cfg.nodesDir();
   const slug = safeSlug();
-  out(`mode:     ${mode}${cfg.enabled() ? "" : "  (DISABLED here — plugin is a no-op)"}`);
+  out(`mode:     ${mode}${cfg.enabled() ? "" : "  (not enabled here — run 'spor enable' to opt in; hooks are a no-op)"}`);
   out(`project:  ${slug}`);
   if (mode === "remote") {
     const server = remote.base(cfg);
@@ -354,17 +354,125 @@ async function cmdLens(cfg, args) {
   return 0;
 }
 
-function cmdCompile(cfg, verb, args) {
+// compile / brief / validate are LOCAL-graph verbs: byte-identical passthrough
+// to lib/compile.js / lib/validate.js, which read $SPOR_HOME/nodes. In REMOTE
+// mode that dir is absent, so the old passthrough exited with a bare
+// "no Spor graph at ~/.spor/nodes" — reads like a broken install
+// (issue-spor-cli-remote-mode-local-verbs). So they branch on mode: dispatch to
+// the server where an equivalent exists (brief/compile, mirroring the
+// /spor:brief skill), fail fast naming the remote path where it does not
+// (validate, compile --skeleton). An explicit --nodes names a local checkout on
+// purpose, so it always takes the local path even under a configured server —
+// which also keeps local-mode output byte-identical (norm-cc-byte-identical-refactor).
+function namesLocalGraph(args) {
+  return args.includes("--nodes");
+}
+
+async function cmdCompile(cfg, verb, args) {
   // brief <id> is sugar for compile --root <id>.
+  let compileArgs = args;
   if (verb === "brief") {
     const id = args[0];
     if (!id) {
       err("usage: spor brief <id>");
       return 1;
     }
-    return passthrough("compile.js", ["--root", id, ...args.slice(1)]);
+    compileArgs = ["--root", id, ...args.slice(1)];
+  }
+  if (cfg.mode() === "remote" && !namesLocalGraph(compileArgs)) {
+    return await compileRemote(cfg, compileArgs);
+  }
+  return passthrough("compile.js", compileArgs);
+}
+
+// The remote arm of compile/brief. Mirrors the /spor:brief skill's remote
+// resolution: a node id -> the raw node plus a title/summary-seeded /v1/digest
+// for its neighborhood; free text -> POST /v1/digest. --skeleton has no server
+// equivalent (it writes a local briefing-node file), so it fails fast. Output
+// matches the local "nothing relevant" contract: exit 0 with empty stdout.
+async function compileRemote(cfg, args) {
+  const root = optVal(args, "root");
+  const query = optVal(args, "query");
+  const project = optVal(args, "project");
+  const outFile = optVal(args, "out");
+  const minSim = optVal(args, "min-sim");
+
+  if (args.includes("--skeleton")) {
+    err("compile --skeleton is local-only — it writes a briefing-node skeleton from a local graph.");
+    err("  in remote mode the server compiles; use 'spor brief <id>' for a node's briefing,");
+    err("  or run in local mode (unset SPOR_SERVER, or pass --nodes <dir>) against a checkout.");
+    return 1;
+  }
+  if (!root && !query) {
+    err('usage: spor compile (--root <id> | --query "text") [--digest] [--project <slug>]');
+    return 1;
+  }
+
+  let text = "";
+  if (root) {
+    const r = await remote.get(cfg, `/v1/nodes/${encodeURIComponent(root)}`, { timeoutMs: 8000 });
+    if (r.transport) {
+      err(`offline — could not reach server (${r.error})`);
+      return 1;
+    }
+    if (r.status === 404) {
+      err(`no such node: ${root}`);
+      return 1;
+    }
+    if (!r.ok) {
+      err(`error ${r.status}`);
+      return 1;
+    }
+    const raw = (r.json && r.json.raw) || r.text || "";
+    // Seed the neighborhood digest from the node's own title/summary, exactly as
+    // the /spor:brief skill does (the REST /v1/digest is query-mode only — root
+    // compile is not exposed over REST, only via the query_graph MCP tool).
+    const seed = (r.json && (r.json.title || r.json.summary)) || fmField(raw, "title") || fmField(raw, "summary") || root;
+    const d = await remote.post(cfg, "/v1/digest", project ? { query: seed, project } : { query: seed }, { timeoutMs: 8000 });
+    const neighborhood = d.ok && d.json && d.json.found !== false ? d.json.text || "" : "";
+    text = neighborhood ? `${raw}\n\n${neighborhood}` : raw;
+  } else {
+    const body = { query };
+    if (project) body.project = project;
+    if (minSim != null) body.min_sim = parseFloat(minSim);
+    const d = await remote.post(cfg, "/v1/digest", body, { timeoutMs: 8000 });
+    if (d.transport) {
+      err(`offline — could not reach server (${d.error})`);
+      return 1;
+    }
+    if (!d.ok) {
+      err(`digest error ${d.status}`);
+      return 1;
+    }
+    if (!d.json || d.json.found === false) return 0; // nothing relevant — mirror local empty
+    text = d.json.text || "";
+  }
+
+  if (!text) return 0;
+  if (outFile) {
+    try {
+      fs.writeFileSync(outFile, text);
+    } catch (e) {
+      err(`could not write ${outFile}: ${e.message}`);
+      return 1;
+    }
+  } else {
+    out(text);
   }
-  return passthrough("compile.js", args);
+  return 0;
+}
+
+// validate lints a LOCAL graph (lib/validate.js). Remote mode has no
+// whole-graph lint endpoint — the server validates every write per node — so
+// fail fast naming that, unless --nodes points at a local checkout to lint.
+function cmdValidate(cfg, args) {
+  if (cfg.mode() === "remote" && !namesLocalGraph(args)) {
+    err("validate lints a LOCAL graph; in remote mode the server validates every write,");
+    err("  so there is no whole-graph lint over the API. Point --nodes at a local checkout");
+    err("  to lint it, or unset SPOR_SERVER to validate the local graph home.");
+    return 1;
+  }
+  return passthrough("validate.js", args);
 }
 
 // --- spor add / capture -------------------------------------------------
@@ -730,7 +838,7 @@ function cmdScope(enabled) {
   data.enabled = enabled;
   fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n");
   out(`${enabled ? "enabled" : "disabled"} Spor for ${root}`);
-  out(`  ${file}${enabled ? "" : " — hooks are now a no-op here; commit it to share the setting"}`);
+  out(`  ${file} — hooks are now ${enabled ? "active" : "a no-op"} here; commit it to share the setting`);
   return 0;
 }
 
@@ -1845,8 +1953,8 @@ const COMMANDS = {
   },
   enable: {
     group: "Repo scoping", parse: "strict", args: "", options: {},
-    summary: "turn Spor back on for this repo (.spor.json)",
-    help: "Set { enabled: true } in this repo's committable .spor.json, undoing a prior\n'spor disable'.",
+    summary: "opt this repo in (.spor.json)",
+    help: "Set { enabled: true } in this repo's committable .spor.json. Spor is opt-in\nper repo — a repo with no .spor/.spor.json marker is a no-op — so this is how\nyou turn it on (and how you undo a prior 'spor disable'). Commit the file to\nshare the setting.",
     run: (cfg) => cmdScope(true),
   },
   link: {
@@ -1858,8 +1966,13 @@ const COMMANDS = {
   },
   compile: {
     group: "Repo scoping", parse: "raw", args: "<args>",
-    summary: "full neighborhood / digest (local; byte-identical)",
-    help: "Compile a node neighborhood or a prompt-time digest from the local graph.\nByte-identical passthrough to lib/compile.js (norm-cc-byte-identical-refactor).",
+    summary: "full neighborhood / digest (local byte-identical; remote via the server)",
+    help:
+      "Compile a node neighborhood or a prompt-time digest. In local mode this is a\n" +
+      "byte-identical passthrough to lib/compile.js (norm-cc-byte-identical-refactor).\n" +
+      "In remote mode it dispatches to the server (--root/--query mirror the\n" +
+      "/spor:brief skill: GET /v1/nodes then POST /v1/digest); --skeleton is local-\n" +
+      "only. An explicit --nodes always names a local checkout, even under a server.",
     options: {
       root: { type: "string", value: "id", desc: "compile a node's neighborhood" },
       query: { type: "string", value: "text", desc: "compile from free-text (query mode)" },
@@ -1877,16 +1990,16 @@ const COMMANDS = {
   brief: {
     group: "Repo scoping", parse: "raw", args: "<id>",
     summary: "compile a briefing for a node (sugar for compile --root <id>)",
-    help: "Compile a briefing for one node — sugar for 'compile --root <id>'. Byte-\nidentical passthrough to lib/compile.js.",
+    help: "Compile a briefing for one node — sugar for 'compile --root <id>'. Local mode\nis a byte-identical passthrough to lib/compile.js; remote mode dispatches to the\nserver (the raw node plus a /v1/digest neighborhood), like the /spor:brief skill.",
     examples: ["spor brief dec-cc-zero-dep-client"],
     run: (cfg, args) => cmdCompile(cfg, "brief", args),
   },
   validate: {
     group: "Repo scoping", parse: "raw", args: "",
     summary: "lint the local graph (byte-identical)",
-    help: "Lint the local graph and exit 1 on errors. Byte-identical passthrough to\nlib/validate.js.",
+    help: "Lint the local graph and exit 1 on errors. Byte-identical passthrough to\nlib/validate.js. Local-only — in remote mode the server validates every write,\nso this fails fast unless --nodes points at a local checkout.",
     options: { nodes: { type: "string", value: "dir", desc: "graph nodes dir to lint" } },
-    run: (cfg, args) => passthrough("validate.js", args),
+    run: (cfg, args) => cmdValidate(cfg, args),
   },
 
   // --- Dispatch ---

package/lib/config.js

@@ -34,7 +34,10 @@ const home = require("./shell/home.js");
 // fallback, keeping byte-identical behavior independent of this table.
 const DEFAULTS = {
   mode: "auto", // auto | local | remote | off
-  enabled: true, // per-repo no-op disable
+  // `enabled` is intentionally ABSENT from the defaults: the plugin is opt-IN
+  // per repo (task-spor-plugin-opt-in-default). Leaving it unset lets
+  // Config.enabled() tell "no one set this" (fall back to repo-marker presence)
+  // apart from an explicit true/false anywhere in the cascade. See enabled().
   search: { projects: { include: [], exclude: [], boost: {} } },
   // Local-mode `front` queue signal reconstructed from git history
   // (task-cc-local-front-productionize, dec-cc-queue-front-from-attribution):
@@ -66,6 +69,7 @@ const ENV_MAP = [
   ["TOKEN", "token"],
   ["HOME", "home"],
   ["NODES", "nodes"],
+  ["ENABLED", "enabled"], // SPOR_ENABLED=1 opts a repo in (=0 disables) via the cascade
   ["DISTILL_CMD", "distill.cmd"],
   ["DISTILL_MODEL", "distill.model"],
   ["DEBOUNCE", "distill.debounce"],
@@ -163,6 +167,26 @@ function repoConfigFiles(cwd) {
   return files.reverse(); // shallowest first
 }
 
+// True when a repo-level opt-in MARKER exists anywhere from cwd up to the
+// filesystem root: either a flat `.spor` identity marker or a `.spor.json`
+// config file. Presence is the opt-in signal Config.enabled() falls back to
+// when no explicit `enabled` flag is set anywhere in the cascade
+// (task-spor-plugin-opt-in-default) — it marks a repo that `spor enable`,
+// `spor link`, or `spor dispatch --backfill` has touched. Mirrors the
+// nearest-ancestor walks used for `.spor.json` config and the `.spor` graph
+// binding. Fail-open: existsSync never throws, so an unreadable level reads as
+// absent rather than erroring.
+function repoMarkerPresent(cwd) {
+  const seen = new Set();
+  for (let dir = cwd || ""; dir; dir = path.dirname(dir)) {
+    if (seen.has(dir)) break;
+    seen.add(dir);
+    if (fs.existsSync(path.join(dir, ".spor")) || fs.existsSync(path.join(dir, ".spor.json"))) return true;
+    if (dir === path.dirname(dir)) break; // hit fs root
+  }
+  return false;
+}
+
 // A per-repo `.spor` marker may bind this repo to a specific graph home via a
 // `graph: <path>` key (issue-cc-local-mode-graph-sharing-gap,
 // dec-spor-local-mode-sharing-boundary) — free local mode's async, git-shared
@@ -288,7 +312,12 @@ function loadConfig(opts = {}) {
     if (!KNOWN_KEYS.has(k)) warnings.push(`unknown config key '${k}' ignored`);
   }
 
-  return new Config(merged, { warnings, env, cwd, markerGraph });
+  // Opt-in marker presence (task-spor-plugin-opt-in-default): computed from the
+  // same cwd ancestry as the config/graph walks. enabled() uses it only when no
+  // explicit `enabled` flag was resolved above.
+  const repoMarker = repoMarkerPresent(cwd);
+
+  return new Config(merged, { warnings, env, cwd, markerGraph, repoMarker });
 }
 
 class Config {
@@ -298,6 +327,7 @@ class Config {
     this._env = meta.env;
     this._cwd = meta.cwd;
     this._markerGraph = meta.markerGraph || null;
+    this._repoMarker = !!meta.repoMarker;
   }
 
   // Raw resolved value at a dotted path, else fallback. Pass the caller's
@@ -370,9 +400,29 @@ class Config {
     if (m && m !== "auto") return m;
     return this.get("server", undefined) ? "remote" : "local";
   }
+  // Opt-in activation (task-spor-plugin-opt-in-default). Installing the npm
+  // package + Claude Code plugin must NOT make every repo you open participate:
+  // a markerless side project stays a full no-op so it never injects context or
+  // distills nodes into the shared graph just because you ran an agent there. A
+  // repo is active when, checked in order:
+  //   1. mode is not "off" (an explicit mode:off is the hard kill, unchanged); AND
+  //   2a. an `enabled` flag was resolved anywhere in the cascade — repo
+  //       `.spor.json`, user/global config.json, SPOR_ENABLED env, or a CLI
+  //       flag — honored verbatim (true activates, false disables); OR
+  //   2b. no explicit flag, in which case the repo is active iff a repo-level
+  //       opt-in marker (`.spor` or `.spor.json`) sits in the cwd ancestry,
+  //       i.e. `spor enable` / `spor link` / `spor dispatch --backfill` touched
+  //       it.
+  // Default — no flag, no marker — is OFF. This is a deliberate behavior change
+  // from the prior default-on (so the activation gate is NOT byte-identical);
+  // every other resolved value stays byte-identical (norm-cc-byte-identical-
+  // refactor).
   enabled() {
-    return this.get("mode", "auto") !== "off" && this.getBool("enabled", true);
+    if (this.get("mode", "auto") === "off") return false;
+    const explicit = this.get("enabled", undefined);
+    if (explicit !== undefined) return this.getBool("enabled", true);
+    return this._repoMarker;
   }
 }
 
-module.exports = { loadConfig, Config, DEFAULTS, ENV_MAP, repoMarkerGraph };
+module.exports = { loadConfig, Config, DEFAULTS, ENV_MAP, repoMarkerGraph, repoMarkerPresent };

package/lib/kernel/graph.js

@@ -89,13 +89,16 @@ const DEFAULT_MIN_SIM = 0.08;
 // Regex-based frontmatter parser (hard rule: no YAML library — zero deps).
 // Supports simple
 // key: value, YAML folded multi-line values (indented continuations),
-// pin:/exclude:/queue_mute:/commits:/slugs:/fingerprints:/roles: inline lists,
+// pin:/exclude:/queue_mute:/commits:/slugs:/fingerprints:/roles:/tags:/
+// applies_to_tags:/applies_to_repos:/applies_to_projects: inline lists,
 // and "- {type: X, to: Y}" edges. commits entries are repo-qualified shas
 // ("repo@sha", task-cc-commit-linking); slugs/fingerprints are the project
 // node's alias and repo-evidence registers (task-cc-project-identity-nodes);
 // roles is the person node's role-list register the org-defined policy layer's
-// quorum gate counts qualified approvals against (task-cc-policy-layer)
-// — flat strings, not objects, by parser design.
+// quorum gate counts qualified approvals against (task-cc-policy-layer); tags is
+// the repo node's free-form label register, and applies_to_* are a norm's
+// repo/tag-scope selectors matched against it (task-cc-norm-ride-along-repo-tag-
+// scope) — flat strings, not objects, by parser design.
 function parseFrontmatter(raw, file) {
   const m = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
   if (!m) throw new Error(`no frontmatter in ${file}`);
@@ -103,7 +106,7 @@ function parseFrontmatter(raw, file) {
   const node = { edges: [], pin: [], exclude: [], body: body.trim(), file };
   let lastKey = null; // for YAML folded scalars (indented continuation lines)
   for (const line of fm.split("\n")) {
-    const list = line.match(/^(pin|exclude|queue_mute|commits|slugs|fingerprints|roles):\s*\[([^\]]*)\]/);
+    const list = line.match(/^(pin|exclude|queue_mute|commits|slugs|fingerprints|roles|tags|applies_to_tags|applies_to_repos|applies_to_projects):\s*\[([^\]]*)\]/);
     if (list) { node[list[1]] = list[2].split(",").map((s) => s.trim()).filter(Boolean); lastKey = null; continue; }
     const kv = line.match(/^(\w[\w-]*):\s*(.*)$/);
     if (kv) {
@@ -606,8 +609,43 @@ function compile(graph, opts = {}) {
   // Project-blind compiles (sessionProject == null) keep every norm, so that
   // path stays byte-identical. Then cap the section to NORM_CAP, ordered by
   // topical relevance, so it degrades by relevance rather than byte truncation.
-  const normRidesAlong = (n) =>
-    sessionProject == null || !n.project || sameProject(n.id);
+  //
+  // Repo/tag-scoped ride-along (task-cc-norm-ride-along-repo-tag-scope): the
+  // project-scope above resolves to the GROUPING UNION (scopeFor expands the
+  // session repo slug to its whole home-project grouping), so a grouping that
+  // spans heterogeneous repos — a terraform IaC repo, a Go service, a Python
+  // service — cross-pollinates norms: a `uv` norm stamped to the Python repo
+  // rode along into the terraform and Go briefs. A norm may now NARROW itself
+  // with flat `applies_to_*` keys matched against the session's OWN repo (not
+  // the union): `applies_to_tags` ∩ the session repo node's `tags`,
+  // `applies_to_repos` = the session repo, `applies_to_projects` = a grouping
+  // the session repo belongs to. Semantics are OR across axes (inclusion union
+  // — "apply in these repos OR anything python-tagged"), ANY within an axis —
+  // deliberately UNLIKE the policy layer's `governs`, which is AND-across-axes
+  // (governance narrowing); do not "fix" this to match it. A norm that declares
+  // any `applies_to_*` and matches none is EXCLUDED (strict — the whole point
+  // is to stop the bleed), including in a repo with no `tags` at all, so repo
+  // tagging is the opt-in that turns scoped norms on. A norm with NO
+  // `applies_to_*` falls through to the project-scope behavior above unchanged,
+  // so a graph that uses no `applies_to_*` is byte-identical
+  // (norm-cc-byte-identical-refactor).
+  // Array-safe reads: a malformed scalar (e.g. `applies_to_tags: python` with
+  // no brackets parses to a string) is treated as ABSENT, so the norm falls
+  // through to project-scope rather than throwing on the un-wrapped kernel path
+  // — the mistake is surfaced as a validateGraphFiles warning, not a crash.
+  const arr = (v) => (Array.isArray(v) ? v : []);
+  const sessionRepoTags = new Set(arr(nodes[sessionProject]?.tags));
+  const hasAppliesTo = (n) =>
+    arr(n.applies_to_tags).length || arr(n.applies_to_repos).length || arr(n.applies_to_projects).length;
+  const appliesToHit = (n) =>
+    arr(n.applies_to_tags).some((t) => sessionRepoTags.has(t)) ||
+    arr(n.applies_to_repos).some((r) => resolveProject(graph, r) === sessionProject) ||
+    arr(n.applies_to_projects).some((p) => scopeFor(graph, p)?.has(sessionProject));
+  const normRidesAlong = (n) => {
+    if (sessionProject == null) return true;          // project-blind: unchanged
+    if (hasAppliesTo(n)) return appliesToHit(n);      // explicit scope wins
+    return !n.project || sameProject(n.id);           // current project-scope
+  };
   const normCandidates = Object.values(nodes).filter((n) =>
     reg.isAlwaysOn(n.type) && normRidesAlong(n) &&
     !structuralSet.has(n.id) && !contentSet.has(n.id) && !pinned.has(n.id) && !excluded.has(n.id));
@@ -937,6 +975,32 @@ function validateGraphFiles(files, seedSchemas = []) {
     }
   }
 
+  // Ride-along scoping fields (task-cc-norm-ride-along-repo-tag-scope): `tags`
+  // is consulted only on repo nodes; `applies_to_*` only narrows always_on
+  // norms. The compiler treats a misplaced or malformed (non-list) value as
+  // absent — fail-safe but silent — so surface the mistake here. (The lenient
+  // validate parser stores inline lists as raw strings, so well-formedness is
+  // checked against the raw text, like the slug claim above.)
+  const RIDE_KEYS = ["applies_to_tags", "applies_to_repos", "applies_to_projects"];
+  for (const n of fileNodes) {
+    const raw = files[n.file] ?? "";
+    const listed = (key) => new RegExp(`^${key}:\\s*\\[[^\\]]*\\]`, "m").test(raw);
+    const present = (key) => new RegExp(`^${key}:`, "m").test(raw);
+    if (n.type && n.type !== "repo" && present("tags")) {
+      warnings.push(`${n.file}: tags on non-repo type '${n.type}' is ignored (only repo nodes carry ride-along tags)`);
+    } else if (n.type === "repo" && present("tags") && !listed("tags")) {
+      warnings.push(`${n.file}: tags must be an inline list '[a, b]' — a scalar value is ignored`);
+    }
+    for (const key of RIDE_KEYS) {
+      if (!present(key)) continue;
+      if (!listed(key)) {
+        warnings.push(`${n.file}: ${key} must be an inline list '[a, b]' — a scalar value is ignored`);
+      } else if (n.type && reg.isKnownType(n.type) && !reg.isAlwaysOn(n.type)) {
+        warnings.push(`${n.file}: ${key} on non-always_on type '${n.type}' has no effect (only always_on norms ride along)`);
+      }
+    }
+  }
+
   for (const n of Object.values(nodes)) {
     for (const e of n.edges) {
       if (!reg.isKnownEdge(e.type)) warnings.push(`${n.file}: unknown edge type '${e.type}'`);

package/lib/seed/schema-norm.md

@@ -12,6 +12,30 @@ Seed schema for the `norm` node type, shipped with the plugin as a
 registry default (QUEUE.md §2). A `type: schema` node in the graph with
 `kind: node-schema` and the same `node_type` overrides this entry.
 
+A norm's `always_on` ride-along is project-scoped by default
+(issue-cc-norm-ride-along-unscoped-bloat), but "project" resolves to the whole
+home-project GROUPING union — so a grouping that spans heterogeneous repos
+(a terraform IaC repo, a Go service, a Python service) would still cross-
+pollinate norms. A norm may NARROW its ride-along with optional flat
+`applies_to_*` selectors, matched against the session's OWN repo
+(task-cc-norm-ride-along-repo-tag-scope):
+
+- `applies_to_tags: [python]` — rides along only into repos tagged `python`
+  (matched against the session repo node's `tags`, schema-repo). A `uv` norm
+  scoped this way stays out of a terraform or Go sibling.
+- `applies_to_repos: [repo-my-svc]` — rides along only in the named repo(s)
+  (slug or `repo-` id; resolved through the alias map).
+- `applies_to_projects: [proj-platform]` — rides along only when the session
+  repo belongs to the named project grouping.
+
+Matching is **OR across axes** (inclusion union — "apply in these repos OR
+anything python-tagged"), ANY within an axis — deliberately unlike the policy
+layer's `governs`, which is AND-across-axes. A norm that declares any
+`applies_to_*` and matches none is EXCLUDED (strict, including in a repo with
+no tags). A norm with no `applies_to_*` keeps today's project-scoped ride-along
+unchanged, so a graph that uses none is byte-identical. The selectors are flat
+inline-list strings (the frontmatter parser takes no nested maps).
+
 ```json
 {
   "node_type": "norm",

package/lib/seed/schema-repo.md

@@ -35,6 +35,19 @@ inline-list fields:
   the alias as a queue item for human confirmation. An accumulating set,
   not a derivation rule — no single fingerprint survives every rewrite.
 
+A repo may also carry an optional free-form `tags` register
+(task-cc-norm-ride-along-repo-tag-scope):
+
+- `tags: [python, backend]` — labels describing this repo, the matching key
+  for a norm's `applies_to_tags` ride-along selector (schema-norm). A norm
+  scoped `applies_to_tags: [python]` rides along into a session's briefing
+  only when this repo (the session's OWN repo) is tagged `python` — so a
+  `uv` norm stays out of a terraform or Go sibling under the same project
+  grouping. An untagged repo matches no tag-scoped norm (strict — repo
+  tagging is the opt-in that turns scoped norms on). Tags are flat strings,
+  consulted only on repo nodes; a graph with no `tags` behaves exactly as
+  before.
+
 An optional `status: archived` retires the whole repo at end-of-life
 (issue-cc-project-lifecycle-queue-pollution). One identity-level edit hides
 the repo's open tasks/questions from the decision queue for EVERY viewer —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sporhq/spor",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "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/doctor.js

@@ -96,7 +96,7 @@ async function doctor() {
   const kv = (label, value) => L.push(`  ${(label + ":").padEnd(13)}${value}`);
 
   L.push("spor doctor — client health");
-  kv("mode", `${mode}${enabled ? "" : "  (DISABLED here — plugin is a no-op for this repo)"}`);
+  kv("mode", `${mode}${enabled ? "" : "  (not enabled here — run 'spor enable' to opt in; hooks are a no-op for this repo)"}`);
   kv("graph home", graph);
 
   if (u.serverBase()) {

package/skills/correct/SKILL.md

@@ -67,6 +67,12 @@ still used when `~/.spor` is absent).
      `~/.spor/nodes/`; if the knowledge isn't a node yet, create that node
      first per the plugin's GRAPH.md, then pin it)
    - an irrelevant/stale node was included → `exclude: [that-id]`
+     - exception: if the irrelevant node is a **norm bleeding in across repos**
+       (e.g. a `uv` norm showing up in a terraform or Go brief under the same
+       project), the durable fix is to scope the norm at its source — add
+       `applies_to_tags:`/`applies_to_repos:`/`applies_to_projects:` to the norm
+       node and `tags:` to the repos (see GRAPH.md / concepts.md) — not a
+       per-briefing `exclude` you'd have to repeat everywhere it bleeds.
    - emphasis/framing was wrong → free-text guidance in the body
 
 3. Write `~/.spor/nodes/corr-<target>-<n>.md` (n = next free integer):

package/skills/spor/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: spor
+description: Load this skill whenever you work with Spor — a project-specific knowledge-graph tool your training does not cover — so you use the right CLI syntax, node and edge format, MCP tools, and REST API instead of rediscovering them each time. Read it before any Spor graph operation — querying or searching the graph, reading or writing nodes, adding edges, capturing or deferring work, running spor CLI commands or Spor MCP tools, working in local vs remote mode, or defining a new node/edge type or schema. Also use it for any conceptual question about Spor (what it is, how it works, the mental model of nodes and edges, what the auto-injected briefing is) and to choose among the /spor commands — defer, brief, next, correct, backfill. When unsure about anything Spor, consult this first rather than guessing.
+---
+
+# Orient yourself in Spor
+
+Spor is a typed, versioned **knowledge graph** that holds the durable
+outcomes of work — decisions (including the ones that were dismissed, and
+why), tasks, issues, norms, specs, questions — one fact per node, joined by
+typed edges. It exists because that knowledge otherwise dies in branches, PR
+threads, and chat scrollback: the next session starts cold and the team
+relitigates settled questions. Spor persists it across sessions and
+teammates, indexes it for relevance, **resurfaces deferred work** the moment
+a session touches its neighborhood, and keeps dismissed approaches — the "why
+we didn't" — retrievable.
+
+Much of the time you don't touch it by hand: in Claude Code, hooks compile a
+briefing at session start and a per-prompt digest automatically, and at session
+end a distiller writes new nodes back. But when you need to operate on the graph
+yourself — query or search it, read or write nodes and edges, run a `spor`
+command or a Spor MCP tool, or extend the schema — this skill is your standing
+reference, so you use the right syntax, formats, and tools instead of
+rediscovering them each time. It also explains the model when you (or the user)
+just need to understand Spor, and routes you to the action skills for specific
+operations.
+
+## The model in one minute
+
+- **Nodes** are markdown files, one fact each, with a `type` and a kebab-case
+  `id` that starts with the type's prefix (`dec-`, `task-`, `issue-`, `norm-`,
+  `spec-`/`art-`, `question-`, …). The `summary` line must stand on its own —
+  most consumers only ever see it.
+- **Edges** are typed and directional, written from the source node's
+  perspective: `supersedes`, `blocks`, `resolves`, `derived-from`,
+  `constrained-by`, `governed-by`, `decided-in`, `relates-to`, `mentions`, …
+  They carry the lineage a flat list can't — *why* a node exists and what it
+  depends on. An edge may point at an id that doesn't exist yet; the compiler
+  just skips it (a marker that the node is worth creating).
+- **The ontology is data you can extend.** Those type and edge tables aren't
+  fixed — each type is itself a `type: schema` node (QUEUE.md §2). The seed
+  pack shipped in `lib/seed/` is the default set; a schema node you add to a
+  graph overrides or extends it, so an org can shape its own ontology.
+
+For the full node-type and edge-type registries, the node file format, and the
+project-slug rule, read **`references/concepts.md`**.
+
+## Are you local or remote? (resolve it silently)
+
+Spor runs against your **personal** graph (local mode) or a **team server**
+(remote mode). Tell which from the status line injected at session start:
+`team graph: …` = remote, `A Spor knowledge graph is active: …` = local. If it
+isn't in context, run `spor status` (or test `[ -n "$SPOR_SERVER" ]`). Don't echo
+`SPOR_SERVER`/`SPOR_TOKEN`/`SPOR_HOME` or announce the mode unless the user
+asks — it's plumbing.
+
+What actually differs:
+
+| | local (`SPOR_SERVER` unset) | remote (`SPOR_SERVER` set) |
+|---|---|---|
+| **the graph** | files under `$SPOR_HOME/nodes/` (default `~/.spor/`) | lives on the server; client caches |
+| **writing** | you write the node markdown yourself; the distiller commits it | the server's ingestion model types raw text into nodes; writes are attributed to you |
+| **reading** | the `spor` CLI, against your local files | the `spor` CLI, the MCP tools, or their REST twins (API.md §3) |
+
+`spor status` prints the resolved mode, graph home, project, and identity if
+you need to confirm. Settings resolve through a cascade (CLI flag > env >
+repo `.spor.json` > user/global config > defaults), so when in doubt let
+`spor status` report the effective values rather than guessing.
+
+## Reading and writing the graph
+
+Work the graph in a loop: **ORIENT → TRAVERSE → COMMIT**. Find where to start,
+walk outward through edges until you have enough context, then write the
+outcome back so the next session inherits it.
+
+**The `spor` CLI** is the simplest surface. A few verbs work in either mode;
+the rest are mode-specific (`spor status` confirms which mode you're in):
+
+```bash
+# either mode
+spor status                    # resolved mode, graph, project, identity, health
+spor next [--project <slug>]   # the ranked decision queue — "what's next"
+spor get <id>                  # one node by id
+spor add "<2-3 sentences>"     # capture a node (typed file locally; /v1/capture remotely)
+
+# remote (team server) only
+spor lens [<id>]               # list saved views, or render one
+
+# dual-mode (local passthrough / remote dispatch to the server)
+spor compile --query "<text>"  # search → compiled neighborhood (--digest for compact)
+spor brief <id>                # a briefing for one node (compile --root <id>)
+
+# local (personal graph) only — fail fast with a redirect in remote mode
+spor validate                  # lint the local graph (server validates per-write remotely)
+spor compile --root <id> --skeleton   # writes a local briefing-node skeleton
+```
+
+`compile`/`brief` are mode-aware: local mode runs the in-repo compiler, remote
+mode dispatches to the server (mirroring `/spor:brief`). Much of this is what
+the session hooks already inject for you automatically; pulling one on demand
+with `spor brief`, `spor compile`, or `/spor:brief` is the same briefing.
+Passing `--nodes <dir>` always targets that local checkout, even under a server.
+
+**In Cowork (Anthropic's chat workspace) and Claude Code with the connector**
+there is no shell and no ambient injection — reach the graph through the
+**Spor MCP tools** instead:
+`query_graph` (ORIENT/TRAVERSE: free-text search, or `root_id` to compile one
+node's neighborhood), `get_node` (raw node + revision), `my_queue` (the ranked
+queue), `render_lens` (a saved board/table/lineage view; no id lists them),
+and to COMMIT: `capture` (raw prose → server types it — reach for this when
+unsure of the shape), or the precise writes `put_node` / `add_edge` /
+`set_status`. Close loops with edges: answer a question with a node carrying an
+`answers` edge; close work with a `resolves` edge from a `decision`/`artifact`.
+
+The deeper, mode-specific flows — the exact REST calls, and the rule that
+*completing* a task or issue needs a resolving node on the graph first — live
+in the action skills below; reach for those rather than reinventing them.
+
+## Adding a node or edge type
+
+Because schemas are themselves nodes, you extend the ontology by **writing a
+node**, not editing code: a `type: schema` node with `kind: node-schema` (or
+`edge-schema`), a CalVer `schema_version`, a fenced-JSON payload, and optional
+sandboxed `validate`/`transitions`/`queueSignals` functions. A resident schema
+overrides its seed equivalent; the server forces new schemas to `proposed` and
+a *different* identity must activate them (no self-approval).
+
+For an org-specific type, that schema node lives *in your graph* and overrides
+the seed default — you don't edit the plugin's source. It's still a contract
+change (every node of that type depends on it), so version it with CalVer and
+keep it backward-readable. Before doing it, read
+**`references/authoring-schemas.md`**.
+
+## Which skill do I use?
+
+This skill orients; these do the work. Route to them rather than improvising:
+
+| You want to… | Use | Trigger |
+|---|---|---|
+| File deferred / discovered work, a follow-up, a dismissed approach | **/spor:defer** | "remember / file / defer this", work postponed mid-session |
+| Get a briefing for a task or node before starting | **/spor:brief** | starting non-trivial work; `/spor:brief <query\|id>` |
+| See what to work on next | **/spor:next** | "what's next / my queue / the backlog", triage |
+| Fix a briefing that was wrong, missing, or stale | **/spor:correct** | "the briefing was wrong / missed / included junk" |
+| Bootstrap a repo's graph, or group repos into projects | **/spor:backfill** | onboarding a repo, "organize my repos" |
+| Read/write the team graph in Cowork (no hooks there) | **/spor:team-graph** | any graph work in Cowork |
+
+If a request is just "explain Spor" or "which Spor thing do I use for X",
+answer from this skill — in plain language for a newcomer, without dumping the
+whole ontology unless asked.
+
+## Read more
+
+- **`references/concepts.md`** — full node/edge registries, node file format,
+  project-slug convention.
+- **`references/authoring-schemas.md`** — how to add or change a schema.
+- **README.md** (architecture, roadmap), **GRAPH.md** (node format + seed
+  ontology), **QUEUE.md** (capture, queue, schema registry), **API.md** (the
+  MCP + REST contract). All at the plugin root.

package/skills/spor/references/authoring-schemas.md

@@ -0,0 +1,202 @@
+# Authoring and changing Spor schemas
+
+Node and edge types are **data, not code**. Each type is a `type: schema`
+node. The set Spor runs on is assembled at load time from two layers: the seed
+pack shipped in `lib/seed/` (the defaults) and any schema nodes resident in
+your graph, which override the seed entry of the same `node_type`/`edge_type`
+**wholesale**.
+
+So you extend or change the ontology by writing a node — usually a
+graph-resident schema node carrying an org-specific rule. That is deliberately
+easy mechanically and deliberately disciplined contractually. Read both halves
+below before you do it.
+
+## A schema node's shape
+
+Frontmatter: `id: schema-<type>` (or `schema-edge-<type>`), `type: schema`,
+`kind: node-schema` or `edge-schema`, a CalVer `schema_version`
+(`YYYY.MM.DD.MICRO`), a `title`, a stand-alone `summary`, and a `date`. The
+body holds prose, then a fenced **JSON payload**, then optional fenced **JS
+functions**.
+
+### Node schema — JSON payload keys
+
+```json
+{
+  "node_type": "task",
+  "description": "active or planned work",
+  "prefix": ["task-"],
+  "queueable": true,
+  "always_on": false,
+  "traversable": true,
+  "capturable": true,
+  "status": { "non_resolving": ["abandoned"] }
+}
+```
+
+- `node_type` / `prefix` — the type and its id prefix(es).
+- `queueable` — may appear in the decision queue.
+- `always_on` — rides along in every project-relevant compile (norms). A
+  norm INSTANCE can narrow that ride-along to specific repos with flat
+  `applies_to_tags:`/`applies_to_repos:`/`applies_to_projects:` frontmatter
+  keys (not schema flags) — see concepts.md "Ride-along flags".
+- `traversable: false` — excluded from lineage walks (briefings, corrections).
+- `capturable: false` — never produced by the capture/ingest path.
+- `status.non_resolving` — statuses that count as *not* resolving for the
+  completion gate (an `abandoned` task resolves nothing).
+
+Note what the payload does **not** hold: there is no field list and no status
+*enum*. Extra frontmatter fields are allowed as-is — a custom `severity:` line
+on your nodes just works, no declaration needed. To *require* a field or pin a
+status to a fixed set, enforce it in the attached functions below, not in JSON.
+
+### Edge schema — JSON payload keys
+
+```json
+{
+  "edge_type": "blocks",
+  "description": "target cannot proceed until this node does",
+  "weight": 0.7,
+  "inverse_label": "blocked-by",
+  "aliases": ["block"]
+}
+```
+
+- `weight` — decay across compile hops (1.0 structural → 0.3 weak).
+- `inverse_label` — how the edge reads from the target; inverse forms are
+  accepted on write and flipped onto the target.
+- `aliases` — same-direction synonyms normalized to the canonical spelling.
+
+### Attached behavior (optional JS)
+
+A schema may carry fenced `js` blocks exporting **pure** functions, run
+server-side in a sandbox (no I/O, no clock) at the JSON boundary. The one most
+types use:
+
+- `transitions(current, proposed, view)` — gate a status change; runs on
+  **update only** (the create path is ungated). Return `{allow: true}` or
+  `{allow: false, reason: "..."}`. Make the reason actionable: a writing agent
+  reads it and retries. This is also where you pin a type's legal status set —
+  reject any proposed status outside it. `current` is the stored node (`null` if
+  unparseable), `proposed` the incoming one, and `view` a read-only join the
+  server computes: `view.resolvers` (live inbound `resolves`/`answers` edges,
+  pre-filtered to resolving states), `view.targets`, `view.actor`,
+  `view.approvals`, `view.non_resolving_statuses`. (The task type's gate uses
+  `view.resolvers` to require a resolving `decision`/`artifact` before `done`.)
+
+Two more hooks are supported but unused by the seed types:
+
+- `validate(node)` — runs at the door on **every write (create and update)**.
+  Extra field checks beyond the base validator (e.g. "a `severity` is required
+  and must be one of …"). Return a list of error message strings, `[]` meaning
+  valid; the server prefixes each with `<schema-id> validate():`. The sandbox
+  passes only the node — there is no second argument.
+- `queueSignals(node, ctx)` — contribute a `{name: number}` map of ranking
+  signals to the decision queue.
+
+To read a real, current attached function, fetch a live schema:
+`spor get schema-task` shows a two-gate `transitions`. (The seed schemas also
+ship in the plugin's `lib/seed/` if you have a checkout.)
+
+### A complete example
+
+A custom `escalation` type — queueable, with an `open → mitigated → closed`
+status machine and a required `severity` — is one whole node. The outer fence
+is shown with four backticks only so the inner blocks display; in the file you
+write, use normal three-backtick fences.
+
+````markdown
+---
+id: schema-escalation
+type: schema
+kind: node-schema
+schema_version: 2026.06.16.0
+title: Customer escalation
+summary: A customer escalation tracked open -> mitigated -> closed, with a severity.
+date: 2026-06-16
+---
+
+Escalations as first-class, queueable nodes, so live ones surface in the queue
+and the mitigation history is kept.
+
+```json
+{
+  "node_type": "escalation",
+  "description": "a customer escalation and its mitigation lineage",
+  "prefix": ["esc-"],
+  "queueable": true,
+  "status": { "non_resolving": ["closed"] }
+}
+```
+
+```js
+const SEVERITIES = ["sev1", "sev2", "sev3"];
+const FLOW = { open: ["mitigated", "closed"], mitigated: ["closed", "open"], closed: ["open"] };
+
+export function validate(node) {
+  if (!node.severity) return ["escalation requires a severity"];
+  if (!SEVERITIES.includes(node.severity)) return [`severity must be one of: ${SEVERITIES.join(", ")}`];
+  return [];
+}
+
+export function transitions(current, proposed) {
+  const from = (current && current.status) || "";
+  const to = (proposed && proposed.status) || "";
+  if (!to || to === from) return { allow: true };
+  if ((FLOW[from] || []).includes(to)) return { allow: true };
+  return { allow: false, reason: `escalation can't go ${from || "(new)"} -> ${to}; allowed: ${(FLOW[from] || []).join(", ") || "(none)"}` };
+}
+```
+````
+
+An escalation node then just carries `severity: sev2` in its frontmatter and
+moves through the gated statuses. The `transitions` contract here is exactly
+what the seed `schema-task` uses (`spor get schema-task` to see a live one);
+`validate` follows the validator's usual error-list convention.
+
+## Activating a schema (remote)
+
+When you write a schema node through the server, it is forced to
+`status: proposed` (any payload status is discarded) and stays **inert** until
+a *different* identity flips it to `active` — there is no self-approval. It
+surfaces in the decision queue as a `suggest: approve` item; a human (or a
+second agent) reviews and runs `set_status schema-<type> active`. Locally
+there's no ingester, so you write the file yourself (e.g.
+`$SPOR_HOME/nodes/schema-escalation.md`) and it's live once it validates.
+
+## The discipline
+
+Changing a schema is a contract change — every node of that type, and every
+reader of them, depends on it. Treat it with care:
+
+1. **Prefer a graph-resident override to a seed edit.** If only your graph
+   needs a rule, write a schema node *in your graph* that overrides the seed
+   entry — don't fork the seed pack. The seed is the shared default for
+   everyone; your override is yours alone and travels with your graph.
+2. **Version honestly.** Bump `schema_version` (CalVer) with a migration only
+   when the change is **not** backward-readable. If existing nodes still parse
+   and mean the same thing — a new write-time gate, a new optional field —
+   it's backward-readable: no node-shape change, no migration needed. The seed
+   `schema-task` gates are written this way; each header notes whether it
+   needed an upgrade chain.
+3. **Keep the payload and any attached functions consistent.** A schema whose
+   `transitions()` rejects a status its own `description` advertises will
+   frustrate every writer. Test the change (below) before relying on it.
+
+(If you're *contributing to the plugin itself* by editing the seed pack rather
+than overriding it in your graph, more has to stay in step — the GRAPH.md docs,
+the distiller prompts, the bundled skills, and the test suite — and such
+refactors must stay byte-identical against a real graph. Most users never need
+this: an org rule belongs in a graph-resident schema, not a seed fork.)
+
+## Sanity checks
+
+```bash
+spor validate                    # lint the graph; fix anything it flags
+spor get schema-<type>           # read back the effective schema your graph will use
+spor compile --root <id>         # confirm a node of the new type compiles cleanly
+```
+
+If the automatic distiller starts emitting an edge variant you didn't define,
+that's a schema gap — add or adjust the edge schema rather than accepting the
+stray form.

package/skills/spor/references/concepts.md

@@ -0,0 +1,142 @@
+# Spor concepts reference
+
+The full ontology behind the orientation in SKILL.md. The seed pack
+(`lib/seed/`) is the source of truth; an org's graph-resident `type: schema`
+nodes override or extend it. Anything here may be overridden in a given graph
+— check the effective schema in your own graph (`spor get schema-<type>`) when
+exactness matters.
+
+## Node types
+
+One file per type at `lib/seed/schema-<type>.md`. "Queueable" = can appear in
+the decision queue (QUEUE.md §4).
+
+| type | id prefix | purpose | notes |
+|---|---|---|---|
+| decision | `dec-` | a choice that was made, with the why | status `active`/`superseded`/`rejected`; a **rejected** decision is a dismissed approach — keep the reason |
+| task | `task-` | active or planned work | status `open`/`active`/`done`/`abandoned`; queueable; `done` needs a resolving `decision`/`artifact` (see SKILL routing → /spor:next) |
+| issue | `issue-` | a defect and its resolution lineage | status `open`/`active`/`resolved`; queueable |
+| incident | `inc-` | something that went wrong in operation | queueable |
+| artifact | `art-`, `spec-` | a document, spec, module, or build product | optional delivery status `in-review`/`approved`/`merged`/`released` |
+| norm | `norm-` | a standing convention or constraint | `always_on: true` — rides along in every project-relevant compile (capped to the topically relevant subset); narrow it to specific repos with `applies_to_tags:`/`applies_to_repos:`/`applies_to_projects:` |
+| briefing | `brief-` | a compiled briefing (output of the system) | `traversable: false` (never walked) and `capturable: false` |
+| correction | `corr-` | a standing fix to a briefing (pin/exclude/guidance) | `traversable: false`; applied at every future compile of its target |
+| question | `question-` | a routed ask the graph couldn't answer | queueable; status `open`/`answered`; joins the queue until answered |
+| person | `person-` | an org member | anchor for `$viewer` binding and question routing |
+| capture-pending | `cap-` | raw captured text that fit no schema | born status-less; closes only as `merged` or `rejected` |
+| finding | `find-` | a gardener observation (stale anchor, cold work) | filed as a queue item |
+| repo | `repo-` | a durable git-repo identity | carries `slugs:` aliases + `fingerprints:`; heals renames at read time; optional `tags:` are the match key for a norm's `applies_to_tags` |
+| project | `proj-` | a stable grouping above repos | owns members via inbound `grouped-under` edges; owns no slugs/fingerprints itself |
+| workflow | `wf-` | a repeatable automation DAG | created `proposed`, inert until activated; queueable |
+| workflow-run | `run-` | one execution of a workflow | queueable when stuck; `capturable: false` |
+
+## Edge types
+
+One file per type at `lib/seed/schema-edge-<type>.md`. Written **source →
+target**. `weight` sets how much the edge decays across compile hops (high =
+structural). `inverse_label` is how the edge reads from the target's side;
+inverse forms are accepted on write and **flipped onto the target**. `aliases`
+are same-direction synonyms renamed at write time.
+
+| edge | weight | meaning (source → target) | inverse / aliases |
+|---|---|---|---|
+| supersedes | 1.0 | this replaces the target; target is stale | inverse `superseded-by`; alias `supercedes` |
+| constrained-by | 1.0 | the target limits what this may do | — |
+| governed-by | 0.95 | the target is the norm/policy this falls under | — |
+| derived-from | 0.9 | this was produced from the target | alias `derives-from` |
+| decided-in | 0.9 | the choice here was made in the target | — |
+| resolves | 0.9 | this fixes/closes the target | — |
+| triggered-by | 0.7 | this run was triggered by the target | — |
+| performs | 0.8 | this run is an execution of the target workflow | — |
+| blocks | 0.7 | the target can't proceed until this does | inverse `blocked-by` |
+| answers | 0.7 | this answers the target question | inverse `answered-by` |
+| assigned | 0.5 | work assigned to this person | — |
+| relates-to | 0.5 | weak association | alias `related-to` |
+| mentions | 0.5 | weakest association | — |
+| stewards | 0.4 | this person stewards the target area/spec/norm | question-routing key |
+| grouped-under | 0.3 | this repo's home project grouping (structural) | inverse `groups` |
+| routed-to | 0.3 | this question is routed to that person | — |
+| compiled-for | — | briefing → the task/query it was compiled for | provenance only |
+| shaped-by | — | briefing → the corrections that shaped it | provenance only |
+
+**Ride-along flags** (set in a schema's JSON payload):
+- `always_on: true` (norm) — injected into every project-relevant compile.
+- `traversable: false` (briefing, correction) — excluded from lineage walks.
+- `capturable: false` (briefing, workflow-run) — never produced by capture.
+
+An `always_on` norm rides along project-wide by default, but that scope is the
+whole home-project **grouping** — so under a project that spans heterogeneous
+repos (a terraform repo, a Go service, a Python service) a `uv` norm would bleed
+into all three. Narrow it with flat per-instance selectors on the norm node
+(not the schema): `applies_to_tags: [python]` (matched against the session
+repo's `tags:`), `applies_to_repos: [repo-x]`, `applies_to_projects: [proj-y]`.
+A norm that declares any `applies_to_*` and matches none is **excluded** —
+including in a repo with no `tags:` — so repo tagging is the opt-in. A norm with
+none keeps the default project-wide ride-along.
+
+Don't invent edge variants. The automatic distiller sometimes emits forms like
+`related-to`/`supercedes`/`derives-from`; those normalize to the canonical
+spelling on write — they're the *only* accepted non-canonical forms. A genuinely
+new relationship needs a new edge schema (see `authoring-schemas.md`).
+
+## Node file format
+
+A node is one markdown file; `id` = filename minus `.md`. The frontmatter
+parser is **regex-based, not a YAML library** — it supports simple
+`key: value`, YAML folded multi-line values (indented continuations),
+`pin:`/`exclude:` inline lists, and `- {type: X, to: Y}` edges. Don't use any
+other YAML construct.
+
+```markdown
+---
+id: dec-export-csv-format        # required; kebab-case, starts with the type prefix
+type: decision                   # required; a type in the registry
+project: meridian                # the repo/project slug (legacy spelling: repo:)
+title: Export defaults to CSV    # required; a one-line human title
+summary: One or two sentences that stand entirely on their own.  # required
+status: active                   # optional; the legal set is enforced by the type's schema, not listed here
+date: 2026-06-09                 # required; the EVENT date (not creation date), YYYY-MM-DD
+edges:
+  - {type: derived-from, to: spec-export-schema}
+  - {type: supersedes, to: dec-export-json-only}
+---
+
+The body — a few paragraphs at most. Shown at full resolution when the node
+scores high in a compile, so write for a reader with zero session context. If
+a load-bearing reason exists ("because the release is Friday"), record it here.
+One fact per node; if you're writing "and also…", split it.
+```
+
+Server-stamped fields you don't set by hand: `author`, `authored_via`. Other
+type-specific fields exist (`wake:` dormancy date; `commits:` linked git shas;
+`pin:`/`exclude:` on corrections; `slugs:`/`fingerprints:`/`tags:` on repo nodes;
+`applies_to_tags:`/`applies_to_repos:`/`applies_to_projects:` ride-along
+selectors on norms; `roles:`/`queue_mute:` on person nodes) — see GRAPH.md for
+the complete list.
+
+Validate any local node you write: `spor validate` (or
+`node lib/validate.js`), and fix what it flags.
+
+## Project slug convention
+
+A node's `project:` stamp and most reads are scoped by a **project slug**,
+derived from the session's cwd:
+
+1. A committed `.spor` marker file wins — `repo: <slug>` (legacy `project:`),
+   read from the nearest ancestor (cwd → repo root), so a monorepo subtree
+   marker can split one repo into distinct identities. The value must already
+   be canonical (`^[a-z0-9][a-z0-9-]*$`); a non-matching value is ignored.
+2. Otherwise: the kebab-cased basename of `git rev-parse --show-toplevel`
+   (lowercased, runs of non-alphanumerics → `-`, trimmed). `My_Repo` →
+   `my-repo`.
+3. A git **worktree** infers from its main repo's basename, so every worktree
+   of one repo shares one identity.
+
+The client and server compute the slug identically, so a slug derived locally
+always matches what the server expects (the canonical form is
+`^[a-z0-9][a-z0-9-]*$`). A repo's home is a `type: project` grouping it sits
+under via a `grouped-under` edge;
+project-scoped reads union every repo grouped under that project, and a bare
+repo slug resolves *up* to its grouping. Renaming a repo changes its slug;
+`type: project`/`type: repo` identity nodes with `slugs:` alias lists heal that
+at read time so old `project:` stamps still match.