@sporhq/spor 0.18.6 → 0.19.0

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "spor",
   "displayName": "Spor Context Compiler",
   "description": "Maintains a typed, versioned knowledge graph and compiles compact briefings from it: session-start injection, per-prompt relevance digests, capture at discovery, end-of-session distillation, decision queue.",
-  "version": "0.18.6",
+  "version": "0.19.0",
   "author": {
     "name": "losthammer"
   }

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "spor",
-  "version": "0.18.6",
+  "version": "0.19.0",
   "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.",
   "author": {
     "name": "Spor",

package/GRAPH.md

@@ -444,6 +444,43 @@ opt-in that turns scoped norms on; set them with `spor repos tag <slug>
 keeps the project-scoped behavior above, so a graph using no `applies_to_*` is
 byte-identical (norm-cc-byte-identical-refactor).
 
+A norm may also declare **coupling anchors**
+(dec-spor-coupling-norms-declared-first): two flat inline lists, `couples_when:`
+(trigger file globs — "when files matching these change") and `couples_also:`
+(the coupled artifacts that should change in the same edit, or be consciously
+dismissed). A norm carrying both becomes a **coupling norm**: the post-tool
+hook glob-matches every Write/Edit's repo-relative path against the trigger
+sets and, on a hit, injects the targets as an edit-time nudge — once per
+session per norm, deterministic, no LLM (task-spor-coupling-nudge-posttool;
+`SPOR_COUPLING_NUDGE=0` disables). The glob dialect is small: `**` crosses
+path segments, `*` stays within one, `?` is one character, a trailing `/`
+means the whole subtree, and a bare `API.md` anchors at the repo root. An
+entry may be **repo-qualified** as `<slug>:<glob>` (or `repo-<slug>:<glob>`)
+so one norm couples artifacts across repos — a qualified trigger fires only in
+that repo and bypasses the norm's scope (the pin IS the scope), while an
+unqualified trigger applies wherever the norm itself applies: its
+`applies_to_*` selectors when declared, else its `project:` stamp (unstamped =
+every repo — the org-wide case, e.g. `couples_when: [.nvmrc]` /
+`couples_also: [Dockerfile]`). Targets may be qualified the same way for
+display. Either key alone, a scalar value, or the keys on a non-norm type are
+inert (validate warns). The matcher is `lib/kernel/coupling.js`; a graph with
+no coupling norms is byte-identical.
+
+The boundary-time consumer of the same anchors is **`spor check`**
+(task-spor-cli-check-coupling-verb): given a change set (uncommitted vs HEAD
+by default; `--staged`, `--range a..b`, or `--files`), it reports each
+coupling norm whose triggers are touched while its same-repo targets are not —
+advisory by default, `--strict` exits 1 for CI/pre-commit; targets pinned to
+another repo surface as reminders, never failures. A coupling norm may
+additionally declare a machine-checkable **value invariant** — two scalar
+keys, `couples_value_a:`/`couples_value_b:`, each `<path>#<regex>` (first
+capture group = the value, e.g. `couples_value_a: .nvmrc#v?(\d+)` /
+`couples_value_b: Dockerfile#FROM node:(\d+)`) — and `spor check` compares the
+two extracted values: "these now disagree" beats "you probably forgot", an
+agreeing invariant suppresses the untouched heuristic, and a disagreement
+reports even when both files were touched. A half-declared or malformed pair
+is inert (validate warns).
+
 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
@@ -616,6 +653,10 @@ edges:
   the deterministic router walks `stewards` edges from the question's relevance
   neighborhood to the closest steward and writes a `routed-to` edge to that
   person; an unrouted question (no steward matched) surfaces to everyone.
+  The question schema's `validate()` door rejects a title/summary/body that is
+  ONLY an unfilled template token (`<question>`, `{{text}}`, `[id]`) so a docs
+  example run verbatim can't mint an information-free routed ask
+  (issue-spor-ask-question-template-placeholder-validation).
 - **`assigned`** points work (task/issue) at a person; per-person queues filter
   on it (the queue's `assignee` parameter — `GET /v1/queue?assignee=<person>`,
   unioned with the person's `stewards` edges; QUEUE.md §5). **`answers`** points

package/README.md

@@ -6,6 +6,8 @@ It keeps track of the useful things that normally disappear into chat history: d
 
 The name comes from Norwegian: *spor* means the track something leaves behind.
 
+📖 **Full documentation: [docs.sporhq.io](https://docs.sporhq.io)** — concepts, getting started, the CLI, the REST API, the MCP surface, and the hosted product.
+
 ## Why use Spor?
 
 Coding agents are good at working inside a single session. The problem is everything before and after that session.
@@ -515,6 +517,7 @@ This matters because some hosts cache plugins or hook definitions. Updating the
 
 ## More docs
 
+* [docs.sporhq.io](https://docs.sporhq.io) — the full documentation site: concepts, getting started, CLI, REST API, MCP, and the hosted guide
 * `GRAPH.md` — graph format, node types, edges, and schema behaviour
 * `API.md` — REST and MCP server contract
 * `QUEUE.md` — queue, capture, routing, and workflow details

package/bin/spor-hook.js

@@ -162,7 +162,18 @@ async function main() {
       /* logging must never break fail-open */
     }
   }
-  if (!cfg.enabled()) return;
+  if (!cfg.enabled()) {
+    // A repo disabled purely by the opt-in DEFAULT that this machine has prior
+    // Spor history for gets a one-time discovery hint instead of silence
+    // (issue-spor-opt-in-silent-disable-no-indication) — session-start only,
+    // evidence-gated, once per repo; see scripts/engines/enable-hint.js.
+    if (event === "session-start") {
+      const { enableHint } = require("../scripts/engines/enable-hint");
+      const hint = enableHint(payload);
+      if (hint) emit(hint, payload, host);
+    }
+    return;
+  }
 
   // Debounced distill: spool the payload and hand off to a per-session
   // watcher (one at a time — the lock holds the watcher's pid; stale locks
@@ -204,7 +215,11 @@ async function main() {
   const engine = ENGINES[event]();
   const out = await engine(payload);
   if (!out) return;
+  emit(out, payload, host);
+}
 
+// Write an engine's output envelope to stdout in the host's dialect.
+function emit(out, payload, host) {
   // Cursor speaks a flat snake_case output: {additional_context} only.
   // (jq -c framing: compact JSON with a trailing newline.)
   if (host === "cursor") {

package/bin/spor.js

@@ -1701,6 +1701,140 @@ async function fetchRemoteExportNodes(cfg, label) {
   }
 }
 
+// `spor check` — the coupling-drift report over a diff
+// (task-spor-cli-check-coupling-verb, dec-spor-coupling-norms-declared-first):
+// the boundary-time consumer of the same coupling norms the post-tool nudge
+// serves at edit time (one matcher, lib/kernel/coupling.js). Resolve a change
+// set via LOCAL git (always — the diff is where you run), load the graph's
+// coupling norms (local nodes dir, or the team graph via GET /v1/export in
+// remote mode, the documented graph-wide-sweep path), and report each norm
+// whose `couples_when` triggers are touched while its `couples_also` targets
+// are not — plus value-invariant disagreement for norms carrying
+// couples_value_a/b. Advisory by default (exit 0); --strict exits 1 on
+// findings for CI/pre-commit enforcement.
+async function cmdCheck(cfg, args) {
+  const cwd = process.cwd();
+  const topR = git(cwd, ["rev-parse", "--show-toplevel"]);
+  const top = topR.status === 0 ? topR.stdout.trim() : "";
+  if (!top) {
+    err("check: not inside a git repository (the change set is a git diff)");
+    return 1;
+  }
+  const slug = u.projectSlug(top);
+  const range = optVal(args, "range");
+  const staged = args.includes("--staged");
+  const strict = args.includes("--strict");
+  const json = args.includes("--json");
+  let files = null;
+  const fi = args.indexOf("--files");
+  if (fi >= 0) {
+    files = [];
+    for (let i = fi + 1; i < args.length && !String(args[i]).startsWith("--"); i++) files.push(args[i]);
+    if (!files.length) {
+      err("check: --files needs at least one path");
+      return 1;
+    }
+  }
+  if ((range ? 1 : 0) + (staged ? 1 : 0) + (files ? 1 : 0) > 1) {
+    err("check: --range, --staged, and --files are mutually exclusive");
+    return 1;
+  }
+
+  // The change set, as repo-relative forward-slash paths (git's own spelling).
+  let changed = [];
+  let rightRev = null; // where value invariants read from (--range reads the range's right side)
+  if (files) {
+    changed = files.map((f) => {
+      const abs = path.isAbsolute(f) ? f : path.resolve(cwd, f);
+      return path.relative(top, abs).split(path.sep).join("/");
+    });
+  } else if (range) {
+    const r = git(top, ["diff", "--name-only", range]);
+    if (r.status !== 0) {
+      err(`check: could not resolve --range '${range}' (${(r.stderr || "").trim().split("\n")[0]})`);
+      return 1;
+    }
+    changed = r.stdout.split("\n").filter(Boolean);
+    const i = range.lastIndexOf("..");
+    rightRev = i > 0 ? range.slice(i + 2) || "HEAD" : null;
+  } else if (staged) {
+    const r = git(top, ["diff", "--name-only", "--cached"]);
+    if (r.status !== 0) {
+      err("check: git diff --cached failed");
+      return 1;
+    }
+    changed = r.stdout.split("\n").filter(Boolean);
+  } else {
+    // Default: everything uncommitted vs HEAD (staged + unstaged) plus
+    // untracked files — the mid-session / pre-commit superset, so an unstaged
+    // edit can't silently pass. (The task sketch said "staged by default";
+    // staged-only reports NOTHING for the common unstaged-working-tree case —
+    // false confidence — so the default is the honest superset and --staged is
+    // the narrow pre-commit view.) A repo with no commits yet falls back to
+    // the index.
+    const d = git(top, ["diff", "--name-only", "HEAD"]);
+    if (d.status === 0) changed = d.stdout.split("\n").filter(Boolean);
+    else {
+      const c = git(top, ["diff", "--name-only", "--cached"]);
+      if (c.status === 0) changed = c.stdout.split("\n").filter(Boolean);
+    }
+    const un = git(top, ["ls-files", "--others", "--exclude-standard"]);
+    if (un.status === 0) changed.push(...un.stdout.split("\n").filter(Boolean));
+  }
+  changed = [...new Set(changed)];
+
+  // The coupling norms: local nodes dir, or the team graph via /v1/export.
+  const couplingLib = require(path.join(ROOT, "lib", "kernel", "coupling.js"));
+  const scanDir = (nodesDir) => {
+    let names = [];
+    try {
+      names = fs.readdirSync(nodesDir).sort();
+    } catch {}
+    return couplingLib.scanCouplingEntries((f) => fs.readFileSync(path.join(nodesDir, f), "utf8"), names);
+  };
+  let scan;
+  let cleanupFetched = null;
+  if (cfg.mode() === "remote" && !namesLocalGraph(args)) {
+    const fetched = await fetchRemoteExportNodes(cfg, "check");
+    if (fetched.error) return 1; // already reported (offline / HTTP error)
+    cleanupFetched = fetched.cleanup;
+    scan = scanDir(fetched.nodesDir);
+  } else {
+    const nodesDir = optVal(args, "nodes") || cfg.nodesDir();
+    if (!fs.existsSync(nodesDir)) {
+      err(`no graph at ${nodesDir} — run 'spor init' first`);
+      return 1;
+    }
+    scan = scanDir(nodesDir);
+  }
+  try {
+    const checkLib = require(path.join(ROOT, "lib", "check.js"));
+    const readFile = (rel) => {
+      try {
+        if (rightRev) {
+          const r = git(top, ["show", `${rightRev}:${rel}`]);
+          return r.status === 0 ? r.stdout : null;
+        }
+        return fs.readFileSync(path.join(top, rel), "utf8");
+      } catch {
+        return null;
+      }
+    };
+    const { checked, findings, reminders } = checkLib.runCheck({
+      slug,
+      changed,
+      norms: scan.norms,
+      repoTags: scan.repo_tags[slug] ?? [],
+      readFile,
+    });
+    if (json) out(JSON.stringify({ project: slug, changed, checked, findings, reminders, strict }, null, 2));
+    else out(checkLib.renderReport({ slug, changed, checked, findings, reminders }, { strict }));
+    return strict && findings.length ? 1 : 0;
+  } finally {
+    if (cleanupFetched) cleanupFetched();
+  }
+}
+
 // analytics folds a graph's git history into created-vs-completed metrics
 // (task-spor-work-analytics-consumer). Unlike query/validate (no server twin) it
 // is dual-mode: local mode runs the in-repo consumer (lib/analytics.js) over
@@ -8331,6 +8465,38 @@ const COMMANDS = {
     ],
     run: (cfg, args) => cmdChanges(cfg, args),
   },
+  check: {
+    group: "Graph", parse: "raw", args: "[--staged|--range <a..b>|--files <f...>] [--strict] [--json]",
+    summary: "coupling-drift report over a diff — triggers touched, targets not",
+    help:
+      "Check a change set against the graph's COUPLING NORMS (norm nodes carrying\n" +
+      "couples_when/couples_also file globs — GRAPH.md \"coupling anchors\"): report\n" +
+      "each norm whose trigger set is touched while its target set is not — the\n" +
+      "boundary-time twin of the edit-time post-tool coupling nudge, sharing one\n" +
+      "matcher (lib/kernel/coupling.js). A norm carrying a value invariant\n" +
+      "(couples_value_a/b: <path>#<regex>) has its two extracted values compared:\n" +
+      "\"these now disagree\" beats \"you probably forgot\", and an agreeing invariant\n" +
+      "suppresses the untouched heuristic. Targets pinned to another repo are\n" +
+      "surfaced as reminders, never failures (verify them there).\n" +
+      "\n" +
+      "The change set is always LOCAL git; the norms are mode-aware (local graph, or\n" +
+      "the team graph via GET /v1/export in remote mode).\n" +
+      "\n" +
+      "  --staged          check the index only (the pre-commit view); default is\n" +
+      "                    everything uncommitted vs HEAD plus untracked files\n" +
+      "  --range <a..b>    check a commit range (CI; value invariants read the right side)\n" +
+      "  --files <f...>    an explicit file list (paths, repo-relative or absolute)\n" +
+      "  --strict          exit 1 when findings exist (CI / pre-commit enforcement)\n" +
+      "  --json            machine-readable {project, changed, checked, findings}\n" +
+      "  --nodes <dir>     read this local graph dir instead of the resolved home",
+    examples: [
+      "spor check",
+      "spor check --staged --strict",
+      "spor check --range origin/main..HEAD --strict",
+      "spor check --files lib/seed/schema-task.md --json",
+    ],
+    run: (cfg, args) => cmdCheck(cfg, args),
+  },
   export: {
     group: "Graph", parse: "strict", args: "[--gzip] [--history|--auth] [--out <file>]",
     summary: "the nodes/ tarball, or the --history bundle / --auth restore backup (GET /v1/export)",

package/lib/check.js

@@ -0,0 +1,162 @@
+"use strict";
+// check.js — the coupling-drift checker behind `spor check`
+// (task-spor-cli-check-coupling-verb, dec-spor-coupling-norms-declared-first):
+// the boundary-time half of the coupling norms the post-tool nudge serves at
+// edit time. Given a change set (repo-relative paths) and the graph's coupling
+// norms, report each norm whose trigger set (`couples_when`) is touched while
+// its target set (`couples_also`) is not — plus, for norms carrying a VALUE
+// invariant (`couples_value_a`/`couples_value_b`), whether the two extracted
+// values actually agree ("these two now disagree" beats "you probably
+// forgot"). Pure over injected inputs — the CLI resolves git, mode, and norm
+// loading; this module never touches the network.
+
+const coupling = require("./kernel/coupling.js");
+
+const arr = (v) => (Array.isArray(v) ? v : []);
+
+// Does any changed path satisfy one couples_also target entry (same-repo view)?
+function targetTouched(glob, changed) {
+  const re = coupling.globToRegExp(glob);
+  return changed.some((p) => re.test(p));
+}
+
+// Check one norm's value invariant against the change. Returns null when the
+// norm declares none, else:
+//   { checked: true,  agree, a: {file, value}, b: {file, value} }
+//   { checked: false, reason: "cross-repo" | "malformed" | "unreadable", ... }
+// `readFile(relPath)` returns file content or null (the CLI wires it to the
+// working tree, or `git show <rev>:<path>` for --range).
+function checkValueInvariant(norm, { slug, readFile }) {
+  if (norm.couples_value_a == null && norm.couples_value_b == null) return null;
+  const specA = coupling.parseValueSpec(norm.couples_value_a);
+  const specB = coupling.parseValueSpec(norm.couples_value_b);
+  if (!specA || !specB) return { checked: false, reason: "malformed" };
+  for (const s of [specA, specB]) {
+    if (s.repo !== null && !coupling.repoMatches(s.repo, slug)) {
+      return { checked: false, reason: "cross-repo", file: `${s.repo}:${s.file}` };
+    }
+  }
+  const contentA = readFile(specA.file);
+  const contentB = readFile(specB.file);
+  if (contentA == null || contentB == null) {
+    return { checked: false, reason: "unreadable", file: contentA == null ? specA.file : specB.file };
+  }
+  const a = coupling.extractValue(contentA, specA.pattern);
+  const b = coupling.extractValue(contentB, specB.pattern);
+  if (a == null || b == null) {
+    return { checked: false, reason: "unreadable", file: a == null ? specA.file : specB.file, pattern_miss: true };
+  }
+  return { checked: true, agree: a === b, a: { file: specA.file, value: a }, b: { file: specB.file, value: b } };
+}
+
+// The check. Inputs:
+//   slug      — this repo's project slug (scopes the norms, resolves qualifiers)
+//   changed   — repo-relative forward-slash paths of the change set
+//   norms     — coupling norms (scanCouplingEntries output)
+//   repoTags  — this repo's `tags:` (feeds applies_to_tags scope)
+//   readFile  — (relPath) -> content|null, for value invariants
+// Returns { checked, findings, reminders }: `checked` counts the norms whose
+// trigger set was evaluated against this change; findings are, per norm, one of
+//   kind "untouched"          — triggers hit, same-repo targets untouched
+//   kind "value-disagreement" — the declared invariant's two values differ
+//   kind "value-unverifiable" — triggers hit but the invariant could not be
+//                               read/parsed here (carries the untouched list)
+// A norm whose invariant CHECKS and AGREES emits nothing even when target
+// globs look untouched — the machine-checkable truth beats the heuristic
+// (e.g. the Dockerfile already carried the right version).
+// `reminders` are triggered norms whose OTHER-REPO targets can't be verified
+// by this diff — surfaced as information, never findings (else every
+// cross-repo coupling would fail --strict unconditionally); a norm appears
+// there only when it produced no finding (a finding already carries its
+// cross_repo list).
+function runCheck({ slug, changed, norms, repoTags = [], readFile = () => null }) {
+  const findings = [];
+  const reminders = [];
+  let checkedCount = 0;
+  for (const norm of arr(norms)) {
+    if (!coupling.isCouplingNorm(norm)) continue;
+    checkedCount++;
+    const ctx = { slug, repoTags };
+    const triggered = arr(changed).filter((p) => coupling.couplingHit(norm, { ...ctx, relPath: p }));
+    const invariant = checkValueInvariant(norm, { slug, readFile });
+    // The invariant also arms on a change to either of its own files, so a
+    // target edited to the WRONG value is caught even when the norm's glob
+    // targets were all touched.
+    const invariantFiles = [norm.couples_value_a, norm.couples_value_b]
+      .map((s) => coupling.parseValueSpec(s))
+      .filter((s) => s && (s.repo === null || coupling.repoMatches(s.repo, slug)))
+      .map((s) => s.file);
+    const invariantArmed = triggered.length > 0 || arr(changed).some((p) => invariantFiles.includes(p));
+    if (!triggered.length && !(invariant && invariantArmed)) continue;
+
+    // Partition targets: same-repo ones are checkable against this diff;
+    // other-repo ones can only be surfaced as reminders.
+    const untouched = [];
+    const crossRepo = [];
+    for (const entry of arr(norm.couples_also)) {
+      const { repo, glob } = coupling.parseEntry(entry);
+      if (repo !== null && !coupling.repoMatches(repo, slug)) {
+        crossRepo.push(entry);
+        continue;
+      }
+      if (!targetTouched(glob, arr(changed))) untouched.push(entry);
+    }
+
+    const base = { norm: norm.id, title: norm.title ?? null, triggered, cross_repo: crossRepo };
+    const before = findings.length;
+    if (invariant && invariantArmed) {
+      if (invariant.checked) {
+        if (!invariant.agree) {
+          findings.push({ kind: "value-disagreement", ...base, untouched, a: invariant.a, b: invariant.b });
+        }
+        // agree -> the invariant is authoritative; no untouched finding.
+      } else if (triggered.length && untouched.length) {
+        findings.push({ kind: "value-unverifiable", ...base, untouched, reason: invariant.reason, file: invariant.file ?? null });
+      }
+    } else if (triggered.length && untouched.length) {
+      findings.push({ kind: "untouched", ...base, untouched });
+    }
+    if (findings.length === before && triggered.length && crossRepo.length) {
+      reminders.push({ norm: norm.id, title: norm.title ?? null, triggered, cross_repo: crossRepo });
+    }
+  }
+  return { checked: checkedCount, findings, reminders };
+}
+
+// The human report. One block per finding; the summary line always prints so
+// a clean run is visibly a run, not a silent no-op. Cross-repo reminders
+// render after the findings, informational only.
+function renderReport({ slug, changed, checked, findings, reminders = [] }, { strict = false } = {}) {
+  const lines = [];
+  const n = findings.length;
+  lines.push(
+    `spor check: ${n === 0 ? "ok" : `${n} finding${n === 1 ? "" : "s"}`} (${changed.length} changed file${changed.length === 1 ? "" : "s"}, ${checked} coupling norm${checked === 1 ? "" : "s"}, project ${slug})`
+  );
+  for (const f of findings) {
+    lines.push("");
+    lines.push(`${f.norm}${f.title ? ` — ${f.title}` : ""}`);
+    if (f.triggered.length) lines.push(`  triggered by: ${f.triggered.join(", ")}`);
+    if (f.kind === "value-disagreement") {
+      lines.push(`  value disagreement: ${f.a.file} (${f.a.value}) != ${f.b.file} (${f.b.value})`);
+    }
+    if (f.untouched && f.untouched.length && f.kind !== "value-disagreement") {
+      lines.push(`  untouched: ${f.untouched.join(", ")}`);
+    }
+    if (f.kind === "value-unverifiable") {
+      lines.push(`  value invariant not verifiable here (${f.reason}${f.file ? `: ${f.file}` : ""})`);
+    }
+    if (f.cross_repo && f.cross_repo.length) {
+      lines.push(`  other-repo targets (verify there): ${f.cross_repo.join(", ")}`);
+    }
+  }
+  for (const r of reminders) {
+    lines.push("");
+    lines.push(`${r.norm}${r.title ? ` — ${r.title}` : ""} (reminder)`);
+    if (r.triggered.length) lines.push(`  triggered by: ${r.triggered.join(", ")}`);
+    lines.push(`  other-repo targets (verify there): ${r.cross_repo.join(", ")}`);
+  }
+  if (n > 0 && !strict) lines.push("", "(advisory — exit 0; run with --strict to fail on findings)");
+  return lines.join("\n");
+}
+
+module.exports = { runCheck, renderReport, checkValueInvariant };

package/lib/config.js

@@ -72,7 +72,7 @@ const REPO_FORBIDDEN_KEYS = ["token"];
 // warning so a silently-ignored setting is visible rather than mysterious.
 const KNOWN_KEYS = new Set([
   "mode", "server", "token", "home", "nodes", "enabled", "org",
-  "search", "queue", "distill", "nudge", "claimNudge", "inferCommits", "dispatch",
+  "search", "queue", "distill", "nudge", "claimNudge", "couplingNudge", "inferCommits", "dispatch",
   // Path-scoped sub-briefs for monorepos (dec-spor-monorepo-path-scoped-briefs):
   // an optional relative-subtree-path -> brief-id map. Committable repo config,
   // kept SEPARATE from the flat `.spor` identity marker; session-start routes to
@@ -101,6 +101,8 @@ const ENV_MAP = [
   ["NUDGE_TIMEOUT", "nudge.timeoutMs"], // bound a hung nudge backend (ms)
   ["CLAIM_NUDGE", "claimNudge.enabled"], // SPOR_CLAIM_NUDGE=0 disables the claim heartbeat+nudge
   ["CLAIM_NUDGE_TIMEOUT", "claimNudge.timeoutMs"], // bound the lease-lookup/heartbeat curls (ms)
+  ["COUPLING_NUDGE", "couplingNudge.enabled"], // SPOR_COUPLING_NUDGE=0 disables the edit-time coupling nudge
+  ["COUPLING_NUDGE_TIMEOUT", "couplingNudge.timeoutMs"], // bound the remote coupling-snapshot download (ms)
   ["INFER_COMMITS", "inferCommits.enabled"],
   ["INFER_THRESHOLD", "inferCommits.threshold"],
   ["QUEUE_FRONT", "queue.front.enabled"], // SPOR_QUEUE_FRONT=0 disables local git-derived front
@@ -661,6 +663,19 @@ class Config {
     if (explicit !== undefined) return this.getBool("enabled", true);
     return this._repoMarker;
   }
+  // True iff the plugin is inactive purely by the opt-in DEFAULT — no explicit
+  // `enabled` flag anywhere in the cascade, no mode:off, no repo marker
+  // (issue-spor-opt-in-silent-disable-no-indication). This is the one inactive
+  // state where a discovery hint is appropriate: an explicit opt-out
+  // (enabled:false, SPOR_ENABLED=0, mode:off) is a deliberate choice and must
+  // stay silent.
+  disabledByDefault() {
+    return (
+      this.get("mode", "auto") !== "off" &&
+      this.get("enabled", undefined) === undefined &&
+      !this._repoMarker
+    );
+  }
 }
 
 module.exports = { loadConfig, Config, DEFAULTS, DEFAULT_SERVER, ENV_MAP, repoMarkerGraph, repoMarkerOrg, repoMarkerPresent };