@sporhq/spor 0.3.1 → 0.4.1

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

package/GRAPH.md

@@ -336,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/bin/spor.js

@@ -925,27 +925,39 @@ function claudePluginInfo() {
   return p ? { version: p.version, scope: p.scope, enabled: p.enabled, installPath: p.installPath } : null;
 }
 
-// Best-effort: is a claude.ai Spor MCP connector bound on this box? A connector
-// added in claude.ai surfaces in Claude Code as the mcp__…_Spor__* tools
-// (art-cc-spor-connector-dual-host), i.e. a SECOND live write surface alongside
-// the local file graph. Claude Code records connected claude.ai connectors in
-// ~/.claude.json's `claudeAiMcpEverConnected` array (entries like
-// "claude.ai Spor"); we key the detection on a Spor-named entry there (matching
-// the pre-rename "Substrate" name too — the connector predates the rename and
-// the array keeps historical entries). This is the only discoverable signal a
-// plain Claude Code box exposes: there is no per-session "currently active"
-// manifest. FAIL-OPEN by contract — any missing/unreadable/unparseable file
-// returns false so `spor status` never emits a false split-brain warning or
-// crashes. SPOR_FAKE_CLAUDE_JSON overrides the path for tests.
+// Best-effort: is a claude.ai Spor MCP connector CURRENTLY bound on this box? A
+// connector added in claude.ai surfaces in Claude Code as the mcp__…_Spor__*
+// tools (art-cc-spor-connector-dual-host), i.e. a SECOND live write surface
+// alongside the local file graph. We read the LIVE set from `claude mcp list`
+// (mirroring claudePluginInfo's spawn) and look for a Spor-named connector —
+// matching the pre-rename "Substrate" name too. We deliberately do NOT key on
+// ~/.claude.json's `claudeAiMcpEverConnected`: that array is a sticky historical
+// "ever connected" list that never clears when a connector is disabled or
+// removed, so it warned forever after the user unbound the connector
+// (issue-spor-status-split-brain-warning-false-positive). FAIL-OPEN by contract:
+// claude absent / nonzero exit / timeout / empty output all return false, so
+// `spor status` never emits a false split-brain warning or hangs. The health
+// status (Connected / Needs authentication / Failed) is ignored — any current
+// binding is a configured second write surface. SPOR_FAKE_MCP_LIST injects
+// canned `claude mcp list` output for tests.
 function sporConnectorBound() {
   try {
-    const p = process.env.SPOR_FAKE_CLAUDE_JSON || path.join(homeDir(), ".claude.json");
-    const j = JSON.parse(fs.readFileSync(p, "utf8"));
-    const ever = j && j.claudeAiMcpEverConnected;
-    if (!Array.isArray(ever)) return false;
-    return ever.some((name) => typeof name === "string" && /\bspor\b|\bsubstrate\b/i.test(name));
+    let text = process.env.SPOR_FAKE_MCP_LIST;
+    if (text == null) {
+      const cmd = claudeCmd();
+      if (cmd === "claude" && !hasCmd("claude")) return false;
+      const r = spawnSync(cmd, ["mcp", "list"], { encoding: "utf8", timeout: 8000 });
+      if (r.status !== 0 || !r.stdout) return false;
+      text = r.stdout;
+    }
+    // Each connector is a line like "claude.ai Spor: <url> - <status>". Match the
+    // NAME segment (before the first colon) only, so a "spor" in a URL or status
+    // can't trip it; \b keeps "Spotify"/"Supabase" from matching "spor".
+    return text
+      .split("\n")
+      .some((line) => /\bspor\b|\bsubstrate\b/i.test(line.split(":")[0] || ""));
   } catch {
-    return false; // no file, unreadable, or malformed => assume no connector
+    return false; // claude missing, spawn error, or unparseable => assume none
   }
 }
 

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.1",
+  "version": "0.4.1",
   "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/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/references/authoring-schemas.md

@@ -36,7 +36,10 @@ functions**.
 
 - `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).
+- `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

package/skills/spor/references/concepts.md

@@ -18,14 +18,14 @@ the decision queue (QUEUE.md §4).
 | 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) |
+| 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 |
+| 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` |
@@ -64,6 +64,16 @@ are same-direction synonyms renamed at write time.
 - `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
@@ -99,8 +109,10 @@ 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:` on repo nodes;
-`roles:`/`queue_mute:` on person nodes) — see GRAPH.md for the complete list.
+`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.