@sporhq/spor 0.18.5 → 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.5",
+  "version": "0.19.0",
   "author": {
     "name": "losthammer"
   }

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "spor",
-  "version": "0.18.5",
+  "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/API.md

@@ -58,9 +58,9 @@ Streamable HTTP, implemented with the official SDK. All tool results are
 returned as both human-readable text content and structured JSON.
 
 The server advertises **`instructions`** (the SDK initialize result, surfaced
-by clients as an "MCP Server Instructions" block). It frames the eleven tools
-as an **ORIENT → TRAVERSE → COMMIT** loop rather than eleven independent
-verbs, so an assistant can infer a recursive research chain — e.g. `my_queue`
+by clients as an "MCP Server Instructions" block). It frames the tools
+as an **ORIENT → TRAVERSE → COMMIT** loop rather than a flat list of independent
+verbs, so an assistant can infer a recursive research chain — e.g. `show_queue`
 (or `recent_changes` for "what happened lately") → `query_graph` with `root_id`
 (deepen) → `render_lens` on a lineage lens →
 `put_node`/`capture` the outcome — instead of reconstructing it from per-tool
@@ -232,10 +232,12 @@ text fit no schema (or failed validation twice) and was preserved as a
 `cap-…` capture-pending node — ingestion-quality failures never lose text.
 Only an unreachable ingestion model is an error (`ingestion_unavailable`).
 
-### `my_queue`
+### `show_queue`
 
-The decision queue (QUEUE.md §4/§5). Input `{ "project"?: "slug",
-"types"?: ["task"], "exclude_types"?: ["capture-pending"], "limit"?: 20,
+The decision queue (QUEUE.md §4/§5) — the data answer to "show my queue" /
+"what's next" / "the backlog". Input `{ "project"?: "slug",
+"types"?: ["task"], "exclude_types"?: ["capture-pending"], "assignee"?:
+"<person-id>|me", "limit"?: 20,
 "offset"?: 0 }` → `{ "items": [{id, title, type, status,
 priority, score, signals: {blocking, heat, staleness, age_days}, suggest:
 "do|close", why}], "count": N, "offset": 0, "returned_count": N,
@@ -277,6 +279,23 @@ queue, not what the firehose hid. The type compared is the type the item
 surfaces as, so `exclude_types: ["schema"]` also hides schema-approval items.
 Omitting both (or passing empty arrays) filters nothing.
 
+**Per-person scope** (task-cc-queue-assignee-filtering). `assignee` scopes the
+ranked queue to the work one person carries — the union of nodes with an
+`assigned` edge to them and the nodes they `steward`; `assignee: "me"` binds
+to the caller (QUEUE.md §4). This is a **narrower carrying view**, not the
+queue: for the ordinary "my queue" / "what's next" answer, omit `assignee`
+entirely — pass it only when the caller explicitly asks for directly
+assigned or stewarded work.
+
+### `render_queue`
+
+The widget twin of `show_queue`: same input, same queue, but this tool
+declares the view-tree UI resource (below) so an MCP-Apps host reliably
+attaches the interactive queue widget. Semantics, ranking, filters, and
+pagination match `show_queue` exactly — it exists only to make widget
+attachment an explicit choice; `show_queue` remains the data-oriented
+queue tool for hosts (and turns) that just need the answer.
+
 ### `ask_question`
 
 File a question the graph could not answer. Input `{ "text": "<the
@@ -345,7 +364,7 @@ gating tasks). Unknown `id` errors with `{ "found": false, "error":
 ### `recent_changes`
 
 The team's recent-activity feed — the temporal entry point the other read
-tools lack (`query_graph` is semantic search, `my_queue` is forward-looking
+tools lack (`query_graph` is semantic search, `show_queue` is forward-looking
 open work, `render_lens` renders current state). It answers "what changed /
 what was done in the last N hours", "what did the agents write overnight", and
 "what landed since `<commit>`". Input `{ "since"?, "project"?, "limit"? }` →
@@ -374,7 +393,7 @@ oldest-open bottlenecks. **Completion is a node's status-TRANSITION time** (when
 it entered its final terminal run), never `updated_at`, so a later edge append
 can't corrupt the "completed last week" signal (dec-spor-git-derived-timestamps).
 `project` (a repo slug or grouping id) scopes it through the same up-resolution
-as `my_queue`; `types` restricts node types; `weeks`/`top`/`aging` shape the
+as `show_queue`; `types` restricts node types; `weeks`/`top`/`aging` shape the
 window. The MCP twin of `GET /v1/analytics` (§3) over the same `store.analytics`
 core — for the shell-less Cowork audience that can't run the CLI.
 
@@ -396,7 +415,7 @@ contract from `lib/seed/` files — those miss resident overrides
 
 ### The MCP-app widget (`ui://spor/view-tree.html`)
 
-`my_queue`, `render_lens`, and `render_program` declare a UI resource via
+`render_queue`, `render_lens`, and `render_program` declare a UI resource via
 `_meta.ui.resourceUri`: a single trusted interpreter of the view-tree
 component catalog that MCP-apps hosts (Claude, Goose, VS Code) render as an
 interactive iframe — status chips, progress bars, lineage trees, node detail
@@ -442,6 +461,7 @@ endpoint is the REST twin of a core call:
 | `POST /v1/corrections` | /spor:correct | `propose_correction` semantics → 201 `{status, id, revision, warnings}` |
 | `GET /v1/queue?project=&assignee=&type=&exclude_type=&limit=&offset=` | /spor:next, session-start | the ranked decision queue: `{items, count, offset, returned_count, total_count, truncated, next_offset, counts_by_type, counts_by_project, counts_by_suggest, muted?, dormant?, questions, asked, findings, pending, reviews, policy?, generated_at}` — items retired by a live resolves/answers edge are excluded; items hidden by the viewer's `queue_mute` or parked by a future `wake:` date (QUEUE.md §4) are counted, never silently dropped; `questions`/`findings`/`pending` are the routed-to-me-plus-unrouted views for the authenticated identity, `asked` is the questions you filed, and `reviews` is the nodes whose review is requested of you (an open `review-requested` edge to your person node — explicitly targeted, no unrouted fallback). `limit` is the page size (default 20, **max 100**, clamped not rejected) and `offset` skips that many items in the ranked order (default 0); the `counts_*`/`total_count` aggregates always cover the FULL ranked set regardless of the page, so one call answers "how many issues vs tasks" without paging, while `truncated`/`next_offset` let a client walk the rest by re-requesting with `offset=next_offset` until `next_offset` is null. Pagination is offset over a point-in-time ranked slice (the queue re-ranks every call), not a cursor — it resumes the same slice only across an unchanged ranking. `project` resolves through the shared up-resolution (dec-spor-queue-slug-resolves-to-grouping): a bare repo slug unions its home-project grouping's member queues, the repo NODE id (`repo-<slug>`) pins one repo, a grouping id (`proj-<slug>`) is used directly; **omitting `project` is the cross-project firehose** (every repo's queue at once). `assignee=<person-id>` scopes to the work that person carries (their `assigned`/`stewards` edges) — a manager's "who is carrying what"; `assignee=me` binds to the caller (empty if the token maps to no person node). `type=`/`exclude_type=` (comma-separated, repeatable) whitelist/blacklist node types from the ranking (exclude wins on overlap) — a hard scope filter applied before scoring, so the aggregates describe the filtered queue (task-cc-queue-filtering-enhancements) |
 | `GET /v1/analytics?project=&type=&weeks=&top=&aging=&format=` | remote `spor analytics`, the `analytics` MCP tool | work-flow analytics — the SERVER twin of the local-only `spor analytics` consumer, for a remote/Cowork teammate with no local graph repo to fold (task-spor-server-analytics-surface): created-vs-completed weekly cohorts, throughput, cycle-time median/p90, current WIP by node type, and the oldest-open bottlenecks, computed by the pure analytics kernel over the resident graph + a HEAD-keyed status-transition fold. **Completion is a node's status-TRANSITION time** (when it entered its final terminal run, from git content history), never `updated_at`, so a later edge append can't corrupt the "completed last week" signal (dec-spor-git-derived-timestamps). Default returns the machine (JSON) report `{window, weekly, totals, throughput, cycleTimeDays, wip, bottlenecks, coverage}`; `?format=text` renders the human report. `project` resolves through the shared up-resolution like `/v1/queue` (bare repo slug → grouping union; `repo-<slug>`/`proj-<slug>` id pins) — a zero-match scope rides back as the additive `project_warning` field (text mode prefixes a `# ` line). `type=` (comma-separated, repeatable) restricts node types; `weeks`/`top`/`aging` shape the window (clamped 1–52 / 1–100 / 1–365). A bad slug/type is `422`. The remote arm of `spor analytics` fetches the JSON and renders it with the SAME `renderReport` the local consumer uses, so remote and local output match (norm-spor-cli-mode-parity, task-spor-analytics-remote-cli-dispatch) |
+| `GET /v1/metrics/capture?since=` | the cross-author capture-discipline eval harvest (task-spor-tenant-capture-metrics-export) | capture-discipline aggregates for an **opted-in** deployment — the same kernel the dogfood CLI runs (`lib-engine/kernel/capture-metrics.js`), computed server-side over the resident graph plus the FULL request journal (every rotated `server.log` segment). Three gates stack (dec-spor-tenant-metrics-aggregates-only): the per-machine opt-in env `SPOR_METRICS_EXPORT` (unset → the route 404s, so a never-opted tenant shows no surface), admin auth (stewards→root, 403), and **unconditional redaction** — the body carries counts/rates only: by-identity keys are stable per-tenant pseudonyms (`author-<hash12>`, salted at `cache/metrics-salt` so per-author trends survive across windows), closure entries keep `{edge, latency_days}` but drop node ids, and id lists reduce to `open_count`/`slug_smell_count`. No journal lines, node bodies, or capture prose ever exit. `?since=YYYY-MM-DD` bounds the window (malformed → `422`) |
 | `POST /v1/questions` `{text, title?, mentions?, project?}` | ask_question's REST twin | file a question node; deterministically routed to the steward of the closest relevance-neighborhood node, unrouted if none → 201 `{status, id, project, routed_to, via, asker, revision, warnings}`. `project` is derived from the relevance neighborhood (then the asker's home project) unless an explicit `project` slug overrides it — pass that for a mention-less question (a dispatched agent injects its session project); a malformed slug → 400 |
 | `POST /v1/gardener` | ops cron / on demand; `spor admin gardener` | run a gardener sweep now; findings filed as queue items → `{checked, filed, resolved, skipped, generated_at}` (`filed`/`resolved`/`skipped` are id lists, `checked` a count). The `spor admin gardener [--json]` CLI verb is the shell front-door (remote-only — the server owns the gardener); authenticated but **not** admin-gated server-side today (unlike `/v1/backup`), so any valid team token can trigger it — the verb still surfaces a 403 as an admin-privilege (stewards→root) hint for a deployment that adds the gate |
 | `GET /v1/program/{id}?format=json\|text&depth=&max_nodes=` | program oversight, /spor:brief follow-ups | the program/progress view (`render_program`'s REST twin, one kernel behind both doors): the gating tree of everything that `blocks` `{id}` transitively, with resolution-derived progress (`{progress: {total, done, active, blocked, open, pct, statuses}}` on the view root; done = terminal status / supersession / live resolves-answers edge, exactly the queue's truth). JSON view tree by default, `?format=text` for the terminal rendering; `depth`/`max_nodes` bound expansion and count skipped branches into `truncated`, never silently. 404 for an unknown id |

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/QUEUE.md

@@ -331,7 +331,7 @@ person), `reviewed-by` (they approved — what `view.approvals` carries and the
 quorum counts), and `changes-requested-by` (they asked for changes — carried
 separately as `view.changes_requested`, never an approval). A single edge
 flips type in place across the lifecycle. An open `review-requested` edge
-surfaces the node in that reviewer's `my_queue` `reviews` set, through the same
+surfaces the node in that reviewer's `show_queue` `reviews` set, through the same
 per-person routing filter questions and findings use — reviewer *selection* at
 request time and quorum *enforcement* at gate time are distinct points.
 
@@ -474,7 +474,7 @@ node id; an optional `@YYYY-MM-DD` makes the mute self-expiring, so
 "sideline this project for now" can't silently rot into a permanent blind
 spot. Muting is per-viewer presentation at queue-compile time, not graph
 state — items stay live and visible to everyone else — and the hidden
-count is reported (`muted: N` on the result, a trailing line on `my_queue`)
+count is reported (`muted: N` on the result, a trailing line on `show_queue`)
 so the queue never silently truncates.
 
 Scheduled dormancy is the graph-state counterpart of the mute: a queueable
@@ -508,18 +508,18 @@ The queue is a compile mode, not a new store:
   (`repo-<slug>`) is the escape hatch back to one repo; an exact grouping id
   (`proj-<slug>`) is used directly; an ungrouped repo falls back to itself.
   **Omitting `project` entirely is the cross-project firehose** (every repo's
-  queue at once); `/spor:next --all-projects` and `my_queue` / `GET /v1/queue`
+  queue at once); `/spor:next --all-projects` and `show_queue` / `GET /v1/queue`
   with no `project` reach it.
 - `includeTypes`/`excludeTypes` (task-cc-queue-filtering-enhancements) whitelist
   or blacklist node types FROM THE RANKING — `GET /v1/queue?type=&exclude_type=`
-  (comma-separated), `my_queue {types, exclude_types}`, and
+  (comma-separated), `show_queue {types, exclude_types}`, and
   `spor next --type/--exclude-type`. Given both, the include set is narrowed and
   then the excludes are removed from it (exclude wins on overlap). Like `project`
   it is a hard scope applied before scoring (the aggregates describe the filtered
   queue), it composes with `project`/`assignee`, and the type compared is the one
   the item surfaces as (so excluding `schema` hides schema-approval items too).
 - Exposed as `GET /v1/queue` (hooks, session-start "open front" line),
-  `my_queue` (the registered MCP stub finally does work — and when Tier 2
+  `show_queue` (the registered MCP stub finally does work — and when Tier 2
   routing lands, routed questions and stewarded items join the same queue),
   and `/spor:next` (presents the queue; picking an item triggers a
   full `--root <task-id>` compile so work starts pre-briefed).
@@ -530,7 +530,7 @@ The queue is a compile mode, not a new store:
 
 **Per-person queues** (task-cc-queue-assignee-filtering). `rankQueue`'s
 `assignee` parameter — and `GET /v1/queue?assignee=<person-id>` /
-`my_queue {assignee}` (use `assignee=me` to bind to the caller) — scopes the
+`show_queue {assignee}` (use `assignee=me` to bind to the caller) — scopes the
 ranked queue to the work one person carries: the union of nodes with an
 outbound `assigned` edge to them (work→person) and the nodes they `steward`
 (person→node). Assignment is an edge like everything else (Tier-2's person
@@ -584,7 +584,7 @@ targets — subject first — form its relevance neighborhood, the first
 stewarded node wins (the server's deterministic Tier-2 routing walk), and
 the route materializes as a `routed-to` edge plus a body note. No steward
 anywhere leaves the finding unrouted. The queue surfaces (`GET /v1/queue`,
-`my_queue`) carry a `findings` field mirroring `questions`: open findings
+`show_queue`) carry a `findings` field mirroring `questions`: open findings
 routed to the authenticated identity plus unrouted ones — a finding routed
 to someone else stays out of your view, so gardener output lands with the
 people who steward what it observed instead of everyone.
@@ -646,7 +646,7 @@ the structural truth:
    in TODOs, that's evidence for a post-tool TODO-comment nudge, not more
    prompt.)
 3. **Queue** — ✅ SHIPPED. `rankQueue()` in the core (`lib/queue.js`, also a
-   CLI for local mode), `GET /v1/queue`, real `my_queue`, `/spor:next`.
+   CLI for local mode), `GET /v1/queue`, real `show_queue`, `/spor:next`.
    The task and capture-pending seed schemas are `queueable: true`; the §4
    signals (blocking / heat / staleness / age) are computed natively in the
    core for now — per-schema `queueSignals()` attached code joins via the
@@ -740,5 +740,5 @@ which held: each landed as one commit on top of the registry.
   computed item list in the sandbox — accepts `[{id, score}]` or an
   `{id: score}` map; unmentioned items keep their default-blend score.
   Fail-soft: a broken policy annotates the result (`policy: {id, applied,
-  error?}` on `/v1/queue` and `my_queue`) and the built-in blend stands; a
+  error?}` on `/v1/queue` and `show_queue`) and the built-in blend stands; a
   proposed policy is inert until approved like any schema node.

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/adapters/README.md

@@ -18,7 +18,10 @@ The Spor client is a portable core behind per-host adapters
   nothing and exits 0.
 - **Universal surfaces**: the server's MCP endpoint (`/mcp`) and REST
   (`/v1/*`) work from any host; `spor-hook agents-md` maintains a managed
-  Spor section in `AGENTS.md` as the floor for hook-less hosts.
+  Spor section in `AGENTS.md` (capture-discipline directive + standing
+  briefing) as the floor for hook-less hosts. The committable directive-only
+  form of the same block is `spor agents-md` (written by `spor enable` by
+  default, refreshed by `spor upgrade`) — see `spor help agents-md`.
 - **Adapters**: a manifest per host mapping its event names onto the
   dispatcher.
 

package/adapters/codex/README.md

@@ -80,7 +80,7 @@ is just a manifest over `bin/spor-hook.js`.
   the distill engine short-circuits on it — so a `codex exec` distiller that
   fires its own Stop hook cannot recurse.
 - MCP: add the Spor server to `~/.codex/config.toml` for on-demand graph
-  access (`query_graph`, `capture`, `my_queue`):
+  access (`query_graph`, `capture`, `show_queue`):
 
   ```toml
   [mcp_servers.spor]

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
@@ -4859,6 +4993,57 @@ function cmdLink(cfg, { positionals }) {
   return 0;
 }
 
+// --- spor agents-md: committed capture-discipline directive ----------------
+// (task-spor-agents-md-capture-discipline-directive) Write/refresh the managed
+// AGENTS.md block with the standing user-voice directive to keep the graph
+// current. The 2026-07 retrospective found front-loaded user-voice directives
+// were the one condition that reliably produced unprompted capture (~8/8 vs a
+// ~0-10% baseline), while the hook-injected preamble saying the same thing in
+// system-reminder voice underperformed — so the directive belongs in a
+// COMMITTED instructions file, where it reaches every contributor and every
+// dispatched agent. Default is directive-only: hooked hosts already receive
+// the briefing at session start, and a committed briefing snapshot stales;
+// --briefing restores the full hook-less floor (directive + briefing embed).
+async function cmdAgentsMd(cfg, { values }) {
+  const root = repoRoot();
+  const { writeAgentsBlock } = require(path.join(ROOT, "scripts", "engines", "agents-md.js"));
+  const { file, meta } = await writeAgentsBlock({ cwd: root, briefing: !!values.briefing });
+  out(`updated ${file} (${values.briefing ? meta || "no briefing yet, MCP pointers only" : "capture-discipline directive"})`);
+  // CLAUDE.md rides along via an @AGENTS.md import (Claude Code resolves
+  // @-imports): if the repo has a CLAUDE.md that never mentions AGENTS.md,
+  // Claude Code sessions would miss the directive entirely. Append the import
+  // once; never CREATE a CLAUDE.md (AGENTS.md alone is the portable surface).
+  if (!values["no-claude-md"]) {
+    const claudeMd = path.join(root, "CLAUDE.md");
+    if (fs.existsSync(claudeMd)) {
+      const txt = fs.readFileSync(claudeMd, "utf8");
+      if (!/AGENTS\.md/.test(txt)) {
+        fs.writeFileSync(claudeMd, txt + (txt.endsWith("\n") ? "" : "\n") + "\n@AGENTS.md\n");
+        out(`updated ${claudeMd} (@AGENTS.md import appended)`);
+      }
+    }
+  }
+  out("  commit the file(s) so every contributor and dispatched agent inherits the directive");
+  return 0;
+}
+
+// `spor upgrade` rider: the committed directive tracks the packaged wording —
+// refresh the current repo's managed block IF one exists, preserving whether
+// it embedded a briefing. A repo that never opted into the block is untouched.
+async function refreshAgentsBlockIfManaged(root = repoRoot()) {
+  const file = path.join(root, "AGENTS.md");
+  let existing = "";
+  try {
+    existing = fs.readFileSync(file, "utf8");
+  } catch {
+    return;
+  }
+  if (!existing.includes("<!-- spor:begin -->") && !existing.includes("<!-- substrate:begin -->")) return;
+  const { writeAgentsBlock } = require(path.join(ROOT, "scripts", "engines", "agents-md.js"));
+  await writeAgentsBlock({ cwd: root, briefing: /### Standing project briefing/.test(existing) });
+  out(`refreshed ${file} (managed Spor block — commit if the wording changed)`);
+}
+
 // --- spor install / setup: wire spor into a host agent ---------------------
 // dec-cc-portable-core-adapters ships a manifest per host under adapters/<host>/
 // with a __SPOR_ROOT__ placeholder; installing one resolves the placeholder to
@@ -5519,6 +5704,10 @@ async function cmdUpgrade(cfg, { values, positionals: pos }) {
     if (r !== 0) rc = r;
   }
   if (!dryRun) {
+    // The committed AGENTS.md directive versions with the package — refresh
+    // the current repo's managed block so wording changes actually ship
+    // (task-spor-agents-md-capture-discipline-directive). No-op without one.
+    await refreshAgentsBlockIfManaged();
     out("");
     out("Restart any running sessions so the refreshed hooks/plugin load.");
     // The refresh above closes the loaded-vs-installed gap; this closes the
@@ -8276,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)",
@@ -8472,10 +8693,40 @@ const COMMANDS = {
     run: (cfg) => cmdScope(false),
   },
   enable: {
-    group: "Repo scoping", parse: "strict", args: "", options: {},
-    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),
+    group: "Repo scoping", parse: "strict", args: "",
+    options: { "no-agents": { type: "boolean", desc: "skip writing the AGENTS.md capture-discipline directive" } },
+    summary: "opt this repo in (.spor.json + AGENTS.md directive)",
+    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'). Also writes the\nAGENTS.md capture-discipline directive (see 'spor help agents-md'; skip with\n--no-agents). Commit the files to share the setting.",
+    run: async (cfg, p) => {
+      const rc = cmdScope(true);
+      // Enabling is the moment this repo's work was decided to belong in the
+      // graph — the standing directive rides along by default.
+      if (rc === 0 && !p.values["no-agents"]) await cmdAgentsMd(cfg, { values: {} });
+      return rc;
+    },
+  },
+  "agents-md": {
+    group: "Repo scoping", parse: "strict", args: "", aliases: ["agents"],
+    summary: "write/refresh the committed AGENTS.md graph-upkeep directive",
+    help:
+      "Write (or idempotently refresh) the managed Spor block in AGENTS.md at the\n" +
+      "repo root: standing user-voice instructions to keep the graph current —\n" +
+      "capture discovered work when it appears, file issues before fixing, prefer\n" +
+      "the graph over private auto-memory for durable facts, resolve with\n" +
+      "artifacts, add Spor: commit trailers. Committed, it reaches every\n" +
+      "contributor and dispatched agent; 'spor upgrade' refreshes the wording.\n" +
+      "If a CLAUDE.md exists that never mentions AGENTS.md, an @AGENTS.md import\n" +
+      "is appended so Claude Code sessions inherit the directive too.\n" +
+      "By default the block carries the directive only (hooked hosts get their\n" +
+      "briefing at session start); --briefing also embeds the standing project\n" +
+      "briefing — the floor for hosts without hooks (same block 'spor-hook\n" +
+      "agents-md' maintains from adapter session-start hooks).",
+    options: {
+      briefing: { type: "boolean", desc: "also embed the standing project briefing (hook-less floor)" },
+      "no-claude-md": { type: "boolean", desc: "don't append the @AGENTS.md import to an existing CLAUDE.md" },
+    },
+    examples: ["spor agents-md", "spor agents-md --briefing"],
+    run: (cfg, p) => cmdAgentsMd(cfg, p),
   },
   link: {
     group: "Repo scoping", parse: "strict", args: "<slug>", options: {},
@@ -8854,7 +9105,7 @@ async function main() {
 // Expose the pure helpers for unit tests (the version-check logic has no I/O),
 // and only run the CLI when invoked directly — requiring this file must not
 // kick off main() and call process.exit under the test runner.
-module.exports = { nodeFloor, nodeRuntimeCheck, verCmp, sporConnectorBound, COMMANDS, resolveVerb, getNodeJson, gitBlobSha };
+module.exports = { nodeFloor, nodeRuntimeCheck, verCmp, sporConnectorBound, COMMANDS, resolveVerb, getNodeJson, gitBlobSha, refreshAgentsBlockIfManaged };
 
 if (require.main === module) {
   main()