@sporhq/spor 0.4.2 → 0.5.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.4.2",
+  "version": "0.5.0",
   "author": { "name": "losthammer" }
 }

package/bin/spor.js

@@ -106,6 +106,38 @@ function cmdInit(cfg) {
   return 0;
 }
 
+// Detect the dead-mute condition for `spor status` (issue-spor-local-mode-queue-
+// mute-noop): the local graph carries a `queue_mute` on at least one person node,
+// but this box's git identity binds to NO matching person node, or to one that
+// holds no mute — so the mutes silently do nothing for this viewer. Returns a
+// one-line note, or null when there's nothing to warn about (no mutes anywhere,
+// or the viewer's own mute IS active). Fail-open: any load / git failure returns
+// null (status must never crash). The graph dir is the same nodesDir cmdStatus
+// already resolved; the git identity is read from the dir that holds the nodes,
+// matching lib/queue.js's gitFront/viewerFor wiring.
+function localMuteNoOp(nodesDir) {
+  try {
+    if (!fs.existsSync(nodesDir)) return null;
+    const graphLib = require(path.join(ROOT, "lib", "graph.js"));
+    const queueLib = require(path.join(ROOT, "lib", "queue.js"));
+    const g = graphLib.loadGraph(nodesDir);
+    // Any person node carrying a non-empty queue_mute register?
+    const muters = Object.values(g.nodes).filter(
+      (n) => n.type === "person" && Array.isArray(n.queue_mute) && n.queue_mute.length);
+    if (!muters.length) return null; // no mutes set anywhere — nothing to warn about
+    const email = queueLib.gitIdentityEmail(path.dirname(nodesDir));
+    const viewer = queueLib.viewerFor(g, email);
+    // The viewer resolves to a person who actually carries a mute -> mutes are
+    // live for this box; no note. (Even an all-expired register counts as wired —
+    // the rot is the validator's/kernel's concern, not a binding failure.)
+    if (viewer && Array.isArray(viewer.queue_mute) && viewer.queue_mute.length) return null;
+    const who = email || "unset";
+    return `queue_mute is set on a person node but your git identity (${who}) resolves to ${viewer ? "a person node without a queue_mute" : "no matching person node"} — mutes are inactive`;
+  } catch {
+    return null; // fail-open: never break status on a graph/git error
+  }
+}
+
 async function cmdStatus(cfg) {
   const mode = cfg.mode();
   const home = cfg.graphHome();
@@ -146,6 +178,15 @@ async function cmdStatus(cfg) {
       out(`  remote). Pick one surface: set SPOR_SERVER/SPOR_TOKEN to go fully remote,`);
       out(`  or disable the claude.ai Spor connector to stay fully local.`);
     }
+    // Dead-mute observability (issue-spor-local-mode-queue-mute-noop). Per-viewer
+    // queue_mute is wired locally now (lib/queue.js viewerFor binds the git
+    // identity to its person node), but it is still a no-op when the graph carries
+    // a queue_mute somewhere yet THIS box's git identity resolves to no matching
+    // person node (or a person node that holds no mute) — exactly the silent half
+    // of the issue. Surface it so the condition is observable instead of mystifying.
+    // Best-effort + fail-open: any load/git error skips the note (never crashes status).
+    const muteNote = localMuteNoOp(nodesDir);
+    if (muteNote) out(`note: ${muteNote}`);
   }
   // The Node prerequisite (issue-spor-onboarding-no-node-silent-fail-open).
   // Always surfaced so a box where the hooks silently no-op has a greppable
@@ -192,9 +233,18 @@ async function cmdWhoami(cfg) {
 }
 
 async function cmdNext(cfg, args) {
+  // Default queue scope (task-spor-queue-default-project-config): a
+  // `queue.project` cascade key pins the default --project in BOTH modes, fixing
+  // the asymmetry where remote defaulted to the cwd slug and local to global. An
+  // explicit --project always wins; `pinned` only fills the gap when no flag was
+  // given. Unset => byte-identical to before (remote keeps the cwd default, local
+  // keeps the global default — no safeSlug() injected locally).
+  const pi = args.indexOf("--project");
+  const explicit = pi >= 0 && args[pi + 1] ? args[pi + 1] : null;
+  const pinned = cfg.get("queue.project", null);
+
   if (cfg.mode() === "remote") {
-    const pi = args.indexOf("--project");
-    const slug = pi >= 0 && args[pi + 1] ? args[pi + 1] : safeSlug();
+    const slug = explicit ?? pinned ?? safeSlug();
     const r = await remote.get(cfg, `/v1/queue?project=${encodeURIComponent(slug)}&limit=10`, { timeoutMs: 6000 });
     if (r.transport) {
       err(`offline — could not reach server (${r.error})`);
@@ -204,6 +254,16 @@ async function cmdNext(cfg, args) {
       err(`queue error ${r.status}`);
       return 1;
     }
+    // Best-effort zero-match note (issue-spor-next-project-token-not-roundtrippable):
+    // unknown-token detection is authoritative only locally (where we hold the
+    // graph); remotely we can only observe an empty result for a SCOPED read and
+    // softly say so on stderr. The cwd-default firehose (no explicit/pinned scope)
+    // is deliberately not flagged — an empty default queue is normal, not a typo.
+    const scoped = explicit ?? pinned;
+    const count = (r.json && (r.json.count ?? (Array.isArray(r.json.items) ? r.json.items.length : null)));
+    if (scoped && count === 0) {
+      err(`project '${scoped}' returned an empty queue — check the slug / grouping id (the server scoped to it and found nothing)`);
+    }
     if (args.includes("--json")) {
       out(JSON.stringify(r.json));
       return 0;
@@ -211,7 +271,12 @@ async function cmdNext(cfg, args) {
     renderQueue(r.json);
     return 0;
   }
-  return passthrough("queue.js", args); // local: byte-identical
+  // local: byte-identical passthrough. When no --project was given but a default
+  // is pinned, inject it so the local read inherits the same default scope as
+  // remote; otherwise pass args untouched (preserving the local->global default —
+  // we never inject safeSlug() locally).
+  const localArgs = !explicit && pinned ? [...args, "--project", pinned] : args;
+  return passthrough("queue.js", localArgs);
 }
 
 function renderQueue(q) {
@@ -475,6 +540,21 @@ function cmdValidate(cfg, args) {
   return passthrough("validate.js", args);
 }
 
+// query enumerates a LOCAL graph (lib/query.js) — the structured node/edge
+// list that `get`/`next`/`compile --query` are not (task-spor-local-graph-query-
+// verb). It is the local-mode primitive under remote mode's saved render_lens
+// views, so like validate it is local-only: in remote mode there is no local
+// loadGraph, so fail fast naming that unless --nodes points at a local checkout.
+function cmdQuery(cfg, args) {
+  if (cfg.mode() === "remote" && !namesLocalGraph(args)) {
+    err("query enumerates a LOCAL graph; in remote mode the server holds the graph,");
+    err("  so use a saved view instead (spor lens). Point --nodes at a local checkout");
+    err("  to query it, or unset SPOR_SERVER to query the local graph home.");
+    return 1;
+  }
+  return passthrough("query.js", args);
+}
+
 // --- spor add / capture -------------------------------------------------
 // Local: write a well-formed node so a user never has to learn the frontmatter
 // (issue-cc-local-mode-capture-queue-surfacing-gap). Remote: POST /v1/capture,
@@ -1926,9 +2006,9 @@ const COMMANDS = {
   next: {
     group: "Graph", parse: "raw", args: "[--project S]", aliases: ["queue"],
     summary: "the decision queue (local: lib/queue; remote: /v1/queue)",
-    help: "Show the ranked decision queue. Remote mode reads /v1/queue; local mode is a\nbyte-identical passthrough to lib/queue.js, so it also accepts that script's\nflags (--days, --no-front, --limit, --name-only, --nodes).",
+    help: "Show the ranked decision queue. Remote mode reads /v1/queue; local mode is a\nbyte-identical passthrough to lib/queue.js, so it also accepts that script's\nflags (--days, --no-front, --limit, --name-only, --nodes).\n\n--project accepts a repo slug (-> its home-project grouping union), a repo-<slug>\nnode id (-> that single repo), or a grouping id (-> the grouping union); an\nunknown token warns and yields an empty queue. Pin a default scope for both modes\nwith the queue.project config key (SPOR_QUEUE_PROJECT or .spor.json\n{\"queue\":{\"project\":\"...\"}}); an explicit --project still wins.",
     options: {
-      project: { type: "string", value: "S", desc: "scope to a project slug (default: inferred)" },
+      project: { type: "string", value: "S", desc: "scope to a project slug (default: queue.project config, else inferred)" },
       json: { type: "boolean", desc: "machine-readable JSON output" },
     },
     examples: ["spor next", "spor next --project spor --json"],
@@ -1955,6 +2035,39 @@ const COMMANDS = {
     examples: ["spor lens", "spor lens lens-roadmap", "spor lens lens-roadmap --project spor"],
     run: (cfg, args) => cmdLens(cfg, args),
   },
+  query: {
+    group: "Graph", parse: "raw", args: "[--type T] [--where k=v] [--edges]",
+    summary: "filterable node/edge enumeration (local)",
+    help:
+      "Deterministic, filterable enumeration over the local graph — the structured\n" +
+      "list that `get` (one node), `next` (the ranked queue) and `compile --query`\n" +
+      "(semantic search) are not. Pure, no LLM. Local-only — it reads the local nodes\n" +
+      "dir; in remote mode use the server's saved `render_lens` views instead (point\n" +
+      "--nodes at a local checkout to query one under a server).\n" +
+      "\n" +
+      "Node selection (AND across distinct flags):\n" +
+      "  --type <T>        nodes of that type: (repeatable -> OR within type)\n" +
+      "  --where key=val   match a frontmatter field (repeatable -> AND); a list\n" +
+      "                    field (e.g. tags) matches on membership\n" +
+      "  --id-prefix <p>   ids starting with <p>\n" +
+      "\n" +
+      "Edge emission (switches output from nodes to {from,type,to} edges; the node\n" +
+      "predicates above then restrict each emitted edge's SOURCE):\n" +
+      "  --edges           emit edges instead of nodes\n" +
+      "  --edge-type <T>   filter edges by type\n" +
+      "  --from <id>       out-edges whose source is <id>\n" +
+      "  --to <id>         in-edges whose target is <id>\n" +
+      "\n" +
+      "Projection: default table; --ids (one id per line), --summary (id + summary),\n" +
+      "--full (raw node block), --json (machine output). --nodes <dir> overrides the\n" +
+      "graph dir.",
+    examples: [
+      "spor query --type repo --ids",
+      "spor query --where status=open --type task --json",
+      "spor query --edges --edge-type grouped-under --to proj-rdi",
+    ],
+    run: (cfg, args) => cmdQuery(cfg, args),
+  },
 
   // --- Repo scoping ---
   disable: {

package/lib/config.js

@@ -85,6 +85,7 @@ const ENV_MAP = [
   ["INFER_THRESHOLD", "inferCommits.threshold"],
   ["QUEUE_FRONT", "queue.front.enabled"], // SPOR_QUEUE_FRONT=0 disables local git-derived front
   ["QUEUE_FRONT_DAYS", "queue.front.days"], // rolling front window (days)
+  ["QUEUE_PROJECT", "queue.project"], // default --project scope for `spor next` (both modes); explicit --project wins
 ];
 
 function isPlainObject(v) {

package/lib/graph.js

@@ -93,6 +93,9 @@ module.exports = {
   // shared read scope resolver (dec-spor-queue-slug-resolves-to-grouping):
   // bare slug -> home grouping union; repo node id -> single repo
   scopeFor: kernel.scopeFor,
+  // zero-match --project detection (issue-spor-next-project-token-not-roundtrippable):
+  // is a project token a known repo/grouping/alias, or scopeFor's fall-to-self?
+  projectKnown: kernel.projectKnown,
   // project end-of-life (issue-cc-project-lifecycle-queue-pollution)
   isArchivedProject: kernel.isArchivedProject,
   // registry (QUEUE.md §2): seed pack + graph-resident schema nodes

package/lib/kernel/graph.js

@@ -284,6 +284,25 @@ function scopeFor(graph, param) {
   return grouping ? gr[grouping] : new Set([repoId]);
 }
 
+// Does a `--project` token actually name something in this graph
+// (issue-spor-next-project-token-not-roundtrippable)? A token is KNOWN when it
+// is an existing node id (a `type: repo` or `type: project` grouping node — what
+// scopeFor pins or unions), a repo slug in the alias map, or a member/own key of
+// some grouping. An UNKNOWN token is exactly scopeFor's fall-back-to-itself case
+// (`new Set([param])` against a non-existent repo id) — it yields count:0 with
+// no warning. This reuses the existing resolvers (projectAliases / groupingOf)
+// rather than re-deriving the registry, so a bare slug that legitimately
+// up-resolves to its grouping (dec-spor-queue-slug-resolves-to-grouping) is
+// reported KNOWN — the deliberate semantics are untouched. Empty/falsy token =>
+// "known" (the global, unscoped read), so a caller that never passed --project
+// never warns.
+function projectKnown(graph, param) {
+  if (!param) return true;
+  if (graph.nodes?.[param]) return true;
+  if (graph.projectAliases?.[param]) return true;
+  return groupingOf(graph, param) != null;
+}
+
 // The grouping id a project-scope KEY belongs to, or null when it is not part of
 // any grouping. A grouping's own id maps to itself; a member repo maps to its
 // grouping. Used by the brief surface — a repo's product brief is
@@ -1024,6 +1043,7 @@ module.exports = {
   resolveProject,
   groupingOf,
   scopeFor,
+  projectKnown,
   isArchivedProject,
   compile,
   renderSkeleton,

package/lib/query.js

@@ -0,0 +1,206 @@
+// query.js — a pure, deterministic, filterable enumeration over a loaded
+// graph's nodes AND edges (task-spor-local-graph-query-verb). The local-mode
+// primitive under what remote mode offers as saved `render_lens` views: `get`
+// is one node, `next` is the ranked queue, `compile --query` is semantic
+// search — `query` is the structured, predicate-filtered list. No LLM, no
+// ranking, no graph walk: it reads `graph.nodes` (and each node's `edges`)
+// directly and returns plain data. Zero deps.
+//
+// Also a CLI (local mode / debugging):
+//   node lib/query.js [--nodes <dir>]
+//     # node selection (AND across distinct flags):
+//     [--type <T> ...]            nodes of that type: (repeatable -> OR within type)
+//     [--where key=value ...]     match a frontmatter field (repeatable -> AND);
+//                                 a list field matches on membership
+//     [--id-prefix <p>]           ids starting with <p>
+//     # edge emission (switches output to edges):
+//     [--edges]                   emit {from,type,to} edges, not nodes
+//     [--edge-type <T>]           filter edges by type
+//     [--from <id>]               out-edges whose SOURCE is <id>
+//     [--to <id>]                 in-edges whose TARGET is <id>
+//     # projection:
+//     [--ids | --summary | --full | --json]
+
+// Resolve a frontmatter field as a comparable. Lists (edges/pin/exclude and the
+// parser's inline-list registers) match on membership; everything else compares
+// as a string. Absent -> undefined (never matches).
+function fieldMatches(node, key, value) {
+  const v = node[key];
+  if (v === undefined || v === null) return false;
+  if (Array.isArray(v)) return v.map(String).includes(value);
+  return String(v) === value;
+}
+
+// queryGraph(graph, opts) -> { nodes } | { edges }
+//   opts.types       : string[]  — OR set over node `type:` (empty = any)
+//   opts.where       : [key, value][] — all must match (AND); list = membership
+//   opts.idPrefix    : string    — id startsWith
+//   opts.edges       : boolean   — emit edges instead of nodes
+//   opts.edgeType    : string    — filter emitted edges by type
+//   opts.from        : string    — out-edges from this source id
+//   opts.to          : string    — in-edges to this target id
+// Node predicates (types/where/idPrefix) restrict the candidate NODE set; in
+// edge mode they restrict the SOURCE node of each emitted edge.
+function queryGraph(graph, opts = {}) {
+  const types = opts.types && opts.types.length ? opts.types : null;
+  const where = opts.where || [];
+  const idPrefix = opts.idPrefix || null;
+
+  const nodeMatches = (n) => {
+    if (types && !types.includes(n.type)) return false;
+    if (idPrefix && !String(n.id).startsWith(idPrefix)) return false;
+    for (const [k, val] of where) if (!fieldMatches(n, k, val)) return false;
+    return true;
+  };
+
+  // Deterministic order: sort node ids once, reuse for nodes and edge sources.
+  const ids = Object.keys(graph.nodes).sort();
+
+  if (opts.edges) {
+    const edges = [];
+    for (const id of ids) {
+      const n = graph.nodes[id];
+      if (!nodeMatches(n)) continue; // node predicates restrict the edge SOURCE
+      if (opts.to != null) continue; // --to walks INTO a target below, not out
+      for (const e of n.edges || []) {
+        if (opts.edgeType && e.type !== opts.edgeType) continue;
+        if (opts.from != null && id !== opts.from) continue;
+        edges.push({ from: id, type: e.type, to: e.to });
+      }
+    }
+    // --to: in-edges whose target is <id>. Walk every source's out-edges (a
+    // node only stores its own out-edges) and keep those pointing at --to.
+    if (opts.to != null) {
+      for (const id of ids) {
+        const n = graph.nodes[id];
+        if (!nodeMatches(n)) continue; // predicates still scope the SOURCE
+        for (const e of n.edges || []) {
+          if (e.to !== opts.to) continue;
+          if (opts.edgeType && e.type !== opts.edgeType) continue;
+          if (opts.from != null && id !== opts.from) continue;
+          edges.push({ from: id, type: e.type, to: e.to });
+        }
+      }
+    }
+    return { edges };
+  }
+
+  const nodes = [];
+  for (const id of ids) {
+    const n = graph.nodes[id];
+    if (nodeMatches(n)) nodes.push(n);
+  }
+  return { nodes };
+}
+
+module.exports = { queryGraph, fieldMatches };
+
+// ---------- CLI (local mode / debugging) ----------
+
+if (require.main === module) {
+  const fs = require("fs");
+  const path = require("path");
+  const graphLib = require(path.join(__dirname, "graph.js"));
+
+  const argv = process.argv.slice(2);
+  // single-value flag reader (last wins), mirroring lib/queue.js's opt().
+  const opt = (n, d) => {
+    let v = d;
+    for (let i = 0; i < argv.length - 1; i++) if (argv[i] === `--${n}`) v = argv[i + 1];
+    return v;
+  };
+  // repeatable-value flag reader (collect every --flag VALUE pair).
+  const optAll = (n) => {
+    const out = [];
+    for (let i = 0; i < argv.length - 1; i++) if (argv[i] === `--${n}`) out.push(argv[i + 1]);
+    return out;
+  };
+  const has = (n) => argv.includes(`--${n}`);
+
+  // Client config cascade (dec-spor-client-config-cascade); nodesDir() honors
+  // config.nodes / SPOR_NODES then the graph-home default — byte-identical when
+  // no config is set. --nodes is the highest-precedence override (like queue.js).
+  const cfg = require(path.join(__dirname, "config.js")).loadConfig({ cwd: process.cwd() });
+  const NODES_DIR = path.resolve(opt("nodes", cfg.nodesDir()));
+  if (!fs.existsSync(NODES_DIR)) {
+    console.error(`no Spor graph at ${NODES_DIR}`);
+    process.exit(0);
+  }
+  const g = graphLib.loadGraph(NODES_DIR);
+
+  // --where key=value (repeatable). Split on the FIRST '=' so a value may
+  // itself contain '='.
+  const where = optAll("where").map((s) => {
+    const i = s.indexOf("=");
+    return i < 0 ? [s, ""] : [s.slice(0, i), s.slice(i + 1)];
+  });
+
+  const r = queryGraph(g, {
+    types: optAll("type"),
+    where,
+    idPrefix: opt("id-prefix", null),
+    edges: has("edges"),
+    edgeType: opt("edge-type", null),
+    from: has("from") ? opt("from", null) : null,
+    to: has("to") ? opt("to", null) : null,
+  });
+
+  if (has("json")) {
+    if (r.edges) process.stdout.write(JSON.stringify(r.edges, null, 2) + "\n");
+    else {
+      // Strip the parser's internal `file` field from JSON node output (it's a
+      // load-time artifact, not graph data).
+      const clean = r.nodes.map(({ file, ...rest }) => rest);
+      process.stdout.write(JSON.stringify(clean, null, 2) + "\n");
+    }
+    process.exit(0);
+  }
+
+  if (r.edges) {
+    if (!r.edges.length) console.log("no matching edges");
+    for (const e of r.edges) console.log(`${e.from} --${e.type}--> ${e.to}`);
+    process.exit(0);
+  }
+
+  const nodes = r.nodes;
+  if (has("ids")) {
+    for (const n of nodes) console.log(n.id);
+    process.exit(0);
+  }
+  if (has("summary")) {
+    if (!nodes.length) console.log("no matching nodes");
+    for (const n of nodes) console.log(`${n.id}  ${n.summary || n.title || ""}`.trimEnd());
+    process.exit(0);
+  }
+  if (has("full")) {
+    if (!nodes.length) console.log("no matching nodes");
+    // Compact frontmatter dump: the node's own raw file if readable, else a
+    // reconstructed key/edge view. Mirrors the spirit of `spor get`.
+    for (const n of nodes) {
+      const file = n.file && path.join(NODES_DIR, n.file);
+      let raw = null;
+      try { if (file) raw = fs.readFileSync(file, "utf8"); } catch { /* fall through */ }
+      if (raw != null) {
+        process.stdout.write(raw.endsWith("\n") ? raw : raw + "\n");
+      } else {
+        const { file: _f, ...rest } = n; // drop the load-time artifact
+        process.stdout.write(JSON.stringify(rest, null, 2) + "\n");
+      }
+      console.log("---");
+    }
+    process.exit(0);
+  }
+
+  // default human table.
+  if (!nodes.length) {
+    console.log("no matching nodes");
+    process.exit(0);
+  }
+  const idW = Math.max(...nodes.map((n) => n.id.length), 2);
+  const tyW = Math.max(...nodes.map((n) => (n.type || "").length), 4);
+  for (const n of nodes) {
+    const title = n.title || n.summary || "";
+    console.log(`${n.id.padEnd(idW)}  ${(n.type || "").padEnd(tyW)}  ${title}`.trimEnd());
+  }
+  console.log(`(${nodes.length} node${nodes.length === 1 ? "" : "s"})`);
+}

package/lib/queue.js

@@ -34,6 +34,40 @@ function rankQueue(graph, opts = {}) {
 // two nearly coincide, and front is the honest viewer-scoped signal. The window
 // and the on/off toggle live in the config cascade (queue.front.days /
 // queue.front.enabled); the CLI flags --days/--no-front map onto them.
+// The local git identity (`git config user.email`) of a repo, trimmed, or "" on
+// any failure (not a git repo, no identity, missing binary). This IS the local
+// $viewer comparand (dec-viewer-token-binding's local analogue: remote derives
+// $viewer from the authenticated token, local derives it from git config) — the
+// same read gitFront already did for front attribution, factored out so the
+// viewer wiring and the front map share one source of truth. Best-effort +
+// fail-open like every other local-mode path.
+function gitIdentityEmail(repoDir) {
+  const { spawnSync } = require("child_process");
+  const r = spawnSync("git", ["-C", repoDir, "config", "user.email"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  return r.status === 0 ? (r.stdout || "").trim() : "";
+}
+
+// Resolve a git email to the graph's `type: person` node by matching its
+// `email:` field (trim + case-insensitive). The LOCAL analogue of
+// dec-viewer-token-binding: remote binds $viewer from the authenticated token's
+// email, local binds it from `git config user.email` — identity derives ONLY
+// from git config, never from a caller-supplied parameter. Returns the person
+// node, or null when there is no email / no match — so an unbound identity
+// simply mutes nothing (activeMutes(null) is the empty set, byte-identical to a
+// queue read with no viewer).
+function viewerFor(graph, email) {
+  const want = String(email || "").trim().toLowerCase();
+  if (!want) return null;
+  for (const n of Object.values(graph.nodes)) {
+    if (n.type !== "person") continue;
+    if (typeof n.email === "string" && n.email.trim().toLowerCase() === want) return n;
+  }
+  return null;
+}
+
 function gitFront(repoDir, nodesName, days) {
   const { spawnSync } = require("child_process");
   const out = {};
@@ -44,7 +78,7 @@ function gitFront(repoDir, nodesName, days) {
     });
     return r.status === 0 ? r.stdout : null;
   };
-  const email = (run(["config", "user.email"]) || "").trim();
+  const email = gitIdentityEmail(repoDir);
   // --author is a regex matched against name OR email; anchor the email so a
   // substring of another author's line can't false-match. Unset identity ->
   // unfiltered (still useful on a graph committed under mixed identities,
@@ -64,7 +98,7 @@ function gitFront(repoDir, nodesName, days) {
   return out;
 }
 
-module.exports = { rankQueue, gitFront, PRIORITY_BUMP: kernel.PRIORITY_BUMP, DEFAULT_LIMIT: kernel.DEFAULT_LIMIT };
+module.exports = { rankQueue, gitFront, gitIdentityEmail, viewerFor, PRIORITY_BUMP: kernel.PRIORITY_BUMP, DEFAULT_LIMIT: kernel.DEFAULT_LIMIT };
 
 // ---------- CLI (local mode / debugging; new entry point, existing CLIs untouched) ----------
 
@@ -101,13 +135,32 @@ if (require.main === module) {
     : cfg.getNum("queue.front.days", 7);
   const frontOn = !argv.includes("--no-front") && cfg.getBool("queue.front.enabled", true);
   const front = frontOn ? gitFront(path.dirname(NODES_DIR), path.basename(NODES_DIR), days) : null;
+  // Local $viewer binding (issue-spor-local-mode-queue-mute-noop): per-viewer
+  // queue_mute was dead locally because no viewer was ever constructed, so
+  // activeMutes(undefined) was always empty. Resolve the git identity to its
+  // person node (viewerFor) and pass it through — the kernel already honors
+  // viewer.queue_mute. null when the identity matches no person node, so a graph
+  // with no person nodes (or an unmatched identity) is byte-identical to the
+  // pre-viewer read (no mutes, no muted count).
+  const viewer = viewerFor(g, gitIdentityEmail(path.dirname(NODES_DIR)));
+  const project = opt("project", null);
   const r = rankQueue(g, {
-    project: opt("project", null),
+    project,
     assignee: opt("assignee", null),
     limit: parseInt(opt("limit", String(kernel.DEFAULT_LIMIT)), 10),
     front,
     frontDays: days,
+    viewer,
   });
+  // Fail loud on a zero-match --project (issue-spor-next-project-token-not-
+  // roundtrippable): a token that resolves to none of the graph's repos /
+  // groupings / aliases silently yielded count:0 (scopeFor falls back to the
+  // token itself). Detect that unknown case (NOT the deliberate bare-slug ->
+  // grouping up-resolution, which is a known token) and say so on stderr; still
+  // exit 0 (fail-open). A known token behaves exactly as in 0.4.x.
+  if (project && !graphLib.projectKnown(g, project)) {
+    console.error(`project '${project}' matched no repo or grouping — queue is empty (try a repo slug, a repo-<slug> node id, or a grouping id)`);
+  }
   if (argv.includes("--json")) {
     process.stdout.write(JSON.stringify(r, null, 2) + "\n");
   } else {
@@ -117,5 +170,9 @@ if (require.main === module) {
       console.log(`   ${it.why}`);
     }
     if (r.count > r.items.length) console.log(`(${r.count - r.items.length} more — raise --limit)`);
+    // The kernel already surfaces the muted count in r.muted (and --json carries
+    // it); mirror it on the human path so the per-viewer hiding is never silent,
+    // the same way the "more — raise --limit" overflow is reported.
+    if (r.muted > 0) console.log(`(${r.muted} muted — your queue_mute)`);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sporhq/spor",
-  "version": "0.4.2",
+  "version": "0.5.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/skills/spor/SKILL.md

@@ -93,8 +93,29 @@ 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
+spor query --type task --where status=open --ids   # structured node/edge enumeration
 ```
 
+`spor query` is the local structured enumeration — the deterministic,
+predicate-filtered list that `get` (one node), `next` (the ranked queue) and
+`compile --query` (semantic search) are not; it is the local-mode primitive
+under what remote mode offers as saved `render_lens` views (use `spor lens`
+there). It AND-combines node predicates — `--type <T>` (repeatable),
+`--where key=value` (repeatable; a list field like `tags` matches on
+membership), `--id-prefix <p>` — and with `--edges` emits `{from,type,to}`
+edges instead, filterable by `--edge-type`, `--from <id>` (out-edges) and
+`--to <id>` (in-edges), e.g. `spor query --edges --edge-type grouped-under
+--to proj-rdi` answers "what is grouped under proj-rdi". Projections: default
+table, `--ids`, `--summary`, `--full`, `--json`.
+
+`spor next --project <token>` accepts three forms: a **repo slug** (resolves
+*up* to its home-project grouping and unions the members — the intuitive token),
+a **`repo-<slug>` node id** (pins that single repo — the escape hatch), or a
+**grouping id `proj-<stem>`** (the grouping union). An unknown token warns on
+stderr and yields an empty queue (it still exits 0). Pin a default scope for both
+modes with the `queue.project` config key (`SPOR_QUEUE_PROJECT`, or `.spor.json`
+`{"queue": {"project": "<token>"}}`); an explicit `--project` always wins.
+
 `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