@sporhq/spor 0.18.4 → 0.18.6

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

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "spor",
-  "version": "0.18.4",
+  "version": "0.18.6",
   "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
@@ -319,10 +338,33 @@ render). Unknown `lens_id` still errors, carrying the same `catalog`/`lenses`
 list; engine failures (missing param, broken blocks) error with the message
 verbatim.
 
+### `render_program`
+
+The program/progress view over `blocks` topology — the birds-eye "where do we
+stand" for a large workstream, auto-derived on demand with no lens authoring.
+Input `{ "id": "<root-node-id>", "max_depth"?, "max_nodes"? }` → `{ "found":
+true, "root_id", "progress": {"total", "done", "active", "blocked", "open",
+"pct", "statuses"}, "count", "truncated"?, "view", "node_ids" }`. Given a root
+node (an umbrella task, a milestone — anything other work `blocks`), the
+server walks its gating tree — every node that blocks it, transitively over
+inbound `blocks` edges — and derives each node's bucket from the same truth
+the queue uses: terminal statuses, supersession, and live `resolves`/`answers`
+edges count as **done** (even while the status field lags — the effective
+status then reads `resolved` with a `resolved_by` ride-along); a node gated by
+its own live unresolved blockers is **blocked**; live unblocked work splits
+**active** vs **open**. `view` is the standard view tree (`as: "tree"` with an
+additive `progress` block); the text content is a progress-bar header plus the
+glyphed gating tree. Shared blockers render once and repeat as `repeat: true`
+leaves (counted once); `max_depth`/`max_nodes` caps count skipped branches
+into `truncated`, never silently. A root nothing blocks is a successful empty
+result whose prose says how to model the program (add `blocks` edges from the
+gating tasks). Unknown `id` errors with `{ "found": false, "error":
+"unknown_root" }`. The REST twin is `GET /v1/program/{id}` (§3).
+
 ### `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"? }` →
@@ -351,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.
 
@@ -373,7 +415,7 @@ contract from `lib/seed/` files — those miss resident overrides
 
 ### The MCP-app widget (`ui://spor/view-tree.html`)
 
-`my_queue` and `render_lens` 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
@@ -419,8 +461,10 @@ 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 |
 | `GET /v1/lens/{id}/render?format=html\|text\|json` | browsers, teammates without a checkout | run a lens OR workspace node and render its view tree (html default, plain text, or the raw tree as json). Read-only — no action forms; writes stay with `/v1/nodes` and the MCP tools. Auth is the caller's bearer header OR a signed read-only **render ticket** for shared links (browser links can't carry an Authorization header): `?ticket=<blob>` is accepted once and exchanged via a 302 for an HttpOnly `spor_render_ticket` cookie (kept out of URLs, logs, and view-to-view hrefs). The ticket binds `$viewer` to the recorded sharer and the render shows a "Viewing as &lt;sharer&gt;" banner. The former `?token=<PAT>` sharing path is **removed** — a shared link can never carry a write-capable credential |
 | `POST /v1/lens/{id}/ticket` `{expires?}` | sharing a view; `spor share` | mint a signed, expiring, read-only render ticket for the lens/workspace, recording the authenticated caller as the sharer → `{ticket, url, lens_id, sharer_person_id, exp}`. `expires` is `<N>d` or an ISO date (default `7d`, max `30d`); the caller must be bound to a person node (else `422 no_person`). The ticket carries no write scope and is honored only on the render route. The `spor share <lens-id> [--expires <Nd>]` CLI verb is the shell front-door (remote-only — tickets are minted and signed server-side); it prints the shareable link ready to paste, `--json` for the raw envelope |
 | `GET /v1/export` | bootstrap/offline; `spor export` | ustar tarball of `nodes/` for seeding a local read replica (`?gzip=1` compresses); see §5 for the response headers. `curl … \| tar x` reproduces `nodes/` byte-for-byte. `?history=1` instead streams a `git bundle --all` of the repo (`application/x-git-bundle`, full commit provenance, the customer data-exit path — `git clone <bundle> graph`); `?auth=1` ALSO bundles `auth/*.json` so a disaster restore reproduces the credential set (admin-gated: stewards-root → `403` otherwise). The `spor export [--gzip] [--history\|--auth] [--out <file>]` CLI verb is the shell front-door (remote downloads this; `--gzip`/`--out` also build the same `nodes/` tarball locally, while `--history`/`--auth` are remote-only) |

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/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.js

@@ -4859,6 +4859,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 +5570,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
@@ -8472,10 +8527,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 +8939,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()

package/lib/kernel/graph.js

@@ -954,7 +954,7 @@ function compile(graph, opts = {}) {
   // The digest/briefing renders used to emit only (type, project, date) +
   // summary, so a done/rejected/resolved node read as live guidance — inviting
   // relitigation of dismissed approaches. Two truth signals get surfaced, the
-  // same ones get_node/my_queue already honor:
+  // same ones get_node/show_queue already honor:
   //   - a TERMINAL status field (done, rejected, resolved, …) is appended to
   //     the parenthetical, so the reader sees the node is not live work.
   //   - an inbound resolves/answers edge that retires a still-open node

package/lib/seed/schema-edge-review-requested.md

@@ -14,7 +14,7 @@ shipped with the plugin as a registry default (QUEUE.md §2). It is the
 dec-spor-definition-of-done-org-policy): a resolving artifact (a change/PR)
 or any work node points a `review-requested` edge at each `person` a review
 is wanted from. The server surfaces those nodes into each named reviewer's
-personal queue (`my_queue` `reviews`), the same per-person filter questions
+personal queue (`show_queue` `reviews`), the same per-person filter questions
 and findings route through.
 
 An outcome **flips the edge in place**: an approval rewrites it to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sporhq/spor",
-  "version": "0.18.4",
+  "version": "0.18.6",
   "description": "Spor — a shared memory substrate for teams and agents. Decisions, their reasons, and the traces they leave. Knowledge-graph context compiler: session-start briefings, per-prompt digests, capture at discovery, end-of-session distillation, decision queue.",
   "license": "Apache-2.0",
   "author": "Anthony Allen",

package/scripts/engines/agents-md.js

@@ -4,6 +4,15 @@
 // local briefing sources, same append-or-replace semantics. The session-start
 // floor for hosts without hooks; status goes to stderr (hook hosts treat
 // stdout as the hook's response).
+//
+// Two callers, two shapes (task-spor-agents-md-capture-discipline-directive):
+//   - `spor-hook agents-md` (adapter session-start floor): directive +
+//     standing-briefing embed — hook-less hosts get their briefing here.
+//   - `spor agents-md` (CLI verb, also ridden by `spor enable` / `spor
+//     upgrade`): directive only by default — hooked hosts already get the
+//     briefing at session start, and the committed block should carry the
+//     durable instruction, not a briefing snapshot that stales between
+//     refreshes.
 
 const fs = require("fs");
 const path = require("path");
@@ -19,9 +28,34 @@ const LEGACY_END = "<!-- substrate:end -->";
 function toolsLine() {
   const server = u.serverBase();
   const mcp = server ? ` It is reachable over MCP at ${server}/mcp (bearer token).` : "";
-  return `A team knowledge graph (Spor) holds prior decisions, constraints, dismissed approaches, and deferred work.${mcp} Before designing or deciding anything non-trivial, check it (query_graph). When you defer discovered work or make a decision worth keeping, record it (capture — 2-3 sentences; the server types and links it). Ask my_queue what to work on next. When a git commit implements a tracked node (a task, decision, or issue), add a 'Spor: <node-id>' trailer to the commit message, in the final trailer block alongside any Co-Authored-By (no blank line between trailers) — git then records which node the commit serves, and the graph records the commit's sha.`;
+  return `A team knowledge graph (Spor) holds prior decisions, constraints, dismissed approaches, and deferred work.${mcp} Before designing or deciding anything non-trivial, check it (query_graph). Ask show_queue what to work on next. When a git commit implements a tracked node (a task, decision, or issue), add a 'Spor: <node-id>' trailer to the commit message, in the final trailer block alongside any Co-Authored-By (no blank line between trailers) — git then records which node the commit serves, and the graph records the commit's sha.`;
 }
 
+// The capture-discipline directive — user-voice standing instructions that
+// make graph upkeep part of the work instead of an afterthought. One source
+// of truth, versioned with the package: the hook floor, the CLI verb, and
+// `spor enable`/`spor upgrade` all write THIS text, so a wording change ships
+// to every managed block on the next refresh. Each bullet encodes a failure
+// mode observed in the 2026-07-04 capture retrospective
+// (art-cc-capture-discipline-results-2): work discovered but never filed,
+// fix-before-issue, decisions kept only in chat, durable facts leaking to
+// private auto-memory, and bare status flips.
+const DIRECTIVE = `Keep the graph current as you work — do these unprompted:
+
+- The moment work is discovered that you won't do right now (an out-of-scope
+  bug, a follow-up, a dismissed approach), capture it before moving on:
+  /spor:defer (or \`spor add "..."\`) — 2-3 sentences in your own words; the
+  server types and links it.
+- Found a defect you ARE about to fix? File it first, fix second — the issue
+  node is the lineage the fix resolves.
+- Made a decision worth keeping (approach chosen, alternative ruled out,
+  gotcha paid for)? Capture it at the moment it is made, not at session end.
+- Durable, team-relevant facts belong in the graph, never only in private
+  auto-memory or scratch notes. If you are about to "remember" something a
+  teammate or future session could need, capture it to Spor as well.
+- When tracked work finishes, close the loop: record the resolution (a
+  decision or artifact node with a \`resolves\` edge), not a bare status flip.`;
+
 // Body after the second '---' line (awk), head -c 7000, $() newline strip.
 function nodeBody(raw) {
   const lines = raw.split("\n");
@@ -35,59 +69,57 @@ function nodeBody(raw) {
   return u.stripTrailingNewlines(u.byteHead(awkOut, 7000));
 }
 
-async function agentsMd(input, args = []) {
+// Core writer: compose the managed block and splice it into AGENTS.md at the
+// repo root. `briefing: false` skips the standing-briefing fetch/embed
+// entirely (no server round-trip). Returns { file, meta, hadBriefing }.
+async function writeAgentsBlock({ cwd, briefing = true }) {
   const graph = u.graphHome();
-  let cwd = "";
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--cwd") cwd = args[i + 1] ?? "";
-  }
-  if (!cwd && input && input.cwd) cwd = input.cwd;
-  if (!cwd) cwd = process.cwd();
-
   const root = u.git(cwd, ["rev-parse", "--show-toplevel"])?.trim() || cwd;
   const slug = u.projectSlug(root);
 
   let body = "";
   let meta = "";
-  if (u.serverBase()) {
-    const resp = await u.curl(`${u.serverBase()}/v1/briefing/${slug}`, {
-      headers: u.bearer(),
-      timeoutMs: 6000,
-    });
-    try {
-      const parsed = JSON.parse(resp.body);
-      if (parsed.found === true) {
-        // jq -r emits a trailing newline; head -c counts it; $() strips it.
-        body = u.stripTrailingNewlines(u.byteHead((parsed.body ?? "") + "\n", 7000));
-        const version = parsed.version ?? 1;
-        meta = `brief-${slug} v${version} @ ${u.serverHost()}`;
-      }
-    } catch {}
-  } else {
-    const brief = path.join(graph, "nodes", `brief-${slug}.md`);
-    if (fs.existsSync(brief)) {
-      let raw = "";
+  if (briefing) {
+    if (u.serverBase()) {
+      const resp = await u.curl(`${u.serverBase()}/v1/briefing/${slug}`, {
+        headers: u.bearer(),
+        timeoutMs: 6000,
+      });
       try {
-        raw = fs.readFileSync(brief, "utf8");
+        const parsed = JSON.parse(resp.body);
+        if (parsed.found === true) {
+          // jq -r emits a trailing newline; head -c counts it; $() strips it.
+          body = u.stripTrailingNewlines(u.byteHead((parsed.body ?? "") + "\n", 7000));
+          const version = parsed.version ?? 1;
+          meta = `brief-${slug} v${version} @ ${u.serverHost()}`;
+        }
       } catch {}
-      body = nodeBody(raw);
-      const version = raw.match(/^version: *(.*)$/m)?.[1] ?? "";
-      meta = `brief-${slug} v${version || "1"} (local)`;
+    } else {
+      const brief = path.join(graph, "nodes", `brief-${slug}.md`);
+      if (fs.existsSync(brief)) {
+        let raw = "";
+        try {
+          raw = fs.readFileSync(brief, "utf8");
+        } catch {}
+        body = nodeBody(raw);
+        const version = raw.match(/^version: *(.*)$/m)?.[1] ?? "";
+        meta = `brief-${slug} v${version || "1"} (local)`;
+      }
     }
   }
 
-  const tools = toolsLine();
-  const section = body
-    ? `## Spor team graph
+  const directive = `## Spor team graph
 
-${tools}
+${toolsLine()}
 
-### Standing project briefing (${meta}, machine-compiled ${u.localDate()} — do not hand-edit this section; refresh with \`spor-hook agents-md\`)
+${DIRECTIVE}`;
+  const section = body
+    ? `${directive}
 
-${body}`
-    : `## Spor team graph
+### Standing project briefing (${meta}, machine-compiled ${u.localDate()} — do not hand-edit this section; refresh with \`spor agents-md --briefing\`)
 
-${tools}`;
+${body}`
+    : directive;
 
   const file = path.join(root, "AGENTS.md");
   const block = `${BEGIN}\n${section}\n${END}`;
@@ -127,8 +159,24 @@ ${tools}`;
   const tmp = file + `.spor-tmp-${process.pid}`;
   fs.writeFileSync(tmp, out);
   fs.renameSync(tmp, file);
-  process.stderr.write(`updated ${file} (${meta || "no briefing yet, MCP pointers only"})\n`);
+  return { file, meta, hadBriefing: !!body };
+}
+
+async function agentsMd(input, args = []) {
+  let cwd = "";
+  let briefing = true;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--cwd") cwd = args[i + 1] ?? "";
+    if (args[i] === "--directive-only") briefing = false;
+  }
+  if (!cwd && input && input.cwd) cwd = input.cwd;
+  if (!cwd) cwd = process.cwd();
+
+  const { file, meta } = await writeAgentsBlock({ cwd, briefing });
+  process.stderr.write(
+    `updated ${file} (${briefing ? meta || "no briefing yet, MCP pointers only" : "directive only"})\n`
+  );
   return null;
 }
 
-module.exports = { agentsMd };
+module.exports = { agentsMd, writeAgentsBlock, DIRECTIVE };

package/skills/next/SKILL.md

@@ -26,8 +26,16 @@ to surface (see Presenting). Don't echo `SPOR_SERVER`/`SPOR_TOKEN`/`SPOR_HOME`
 or announce which mode is running unless the user asks — it's plumbing; if you
 ever need to confirm the resolved mode/scope, `spor status` reports it.
 
-**In Cowork (no shell)**, call the `my_queue` MCP tool instead, with the same
-fields (`project`, `types`, `exclude_types` arrays, `limit`/`offset`).
+**In Cowork (no shell)**, call the `show_queue` MCP tool instead, with the same
+fields (`project`, `types`, `exclude_types` arrays, `limit`/`offset`). Omit
+`assignee` for the ordinary "my queue" answer — `assignee: "me"` narrows to
+directly assigned/stewarded work only, a narrower carrying view. In an
+MCP-Apps host that should attach the interactive queue widget, use
+`render_queue` (same fields; `show_queue` stays the data answer).
+
+(A different question — "how far along is the whole workstream?", progress
+rather than next actions — is the program view: the `render_program` MCP tool
+or `GET /v1/program/<root-id>`; see /spor:spor.)
 
 **Scope and filter flags** (task-cc-queue-filtering-enhancements). The queue
 defaults to this repo's project; three optional, composable levers widen or
@@ -46,7 +54,7 @@ pending captures"):
   (comma-separated, repeatable, exclude wins on overlap). They apply *before*
   ranking, so the aggregate counts describe the filtered queue.
 
-The `my_queue` MCP tool takes the same as fields.
+The `show_queue` MCP tool takes the same fields.
 
 ## In-flight awareness — don't re-pick work an agent is already on (Claude Code only)
 
@@ -62,12 +70,12 @@ boolean — and a `dispatched` summary (`{id, name, state, status, cwd}`) on the
 in-flight ones — by matching live background agents to node ids. Add
 `--hide-dispatched` to drop the in-flight items entirely (it reports a
 `hidden_dispatched` count, never silently). This is best-effort and
-Claude-Code-only: the `my_queue` / server queue can't see local background
+Claude-Code-only: the `show_queue` / server queue can't see local background
 agents, so the flag fails soft (every item reads `in_flight:false`) when the
 `claude` binary is absent (e.g. in Cowork or a plain shell).
 
 Prefer reading that flag over shelling out yourself. When you only have the raw
-`my_queue` output (which doesn't carry the flag), an item is **in flight** when
+`show_queue` output (which doesn't carry the flag), an item is **in flight** when
 a `kind: "background"` agent from `claude agents --json` has `name` equal to the
 item's id and `state` is not `"done"`. For those items: badge them "🤖 agent
 dispatched — in progress" and keep them OUT of the top "pick this next"

package/skills/spor/SKILL.md

@@ -200,13 +200,62 @@ In Cowork (Anthropic's chat workspace) and Claude Code with the connector there
 is no shell and no ambient injection — reach the graph through the **Spor MCP
 tools** instead: `query_graph` (ORIENT/TRAVERSE: free-text search, or `root_id`
 to compile one node's neighborhood), `get_node` (raw node + revision),
-`my_queue` (the ranked queue), `render_lens` (a saved board/table/lineage view;
-no id lists them), and to COMMIT: `capture` (raw prose → server types it — reach
+`show_queue` (the ranked queue — omit `assignee` for the ordinary "my queue"
+answer; `assignee: "me"` narrows to directly assigned/stewarded work only),
+`render_queue` (the same queue when an MCP-Apps host should attach the
+interactive widget; `show_queue` stays the data answer), `render_lens` (a saved
+board/table/lineage view; no id lists them), `render_program` (the
+program/progress view for a workstream: given a root node other work `blocks`,
+the gating tree of everything blocking it transitively, with
+resolution-derived progress — "how far along is X?", where `show_queue`
+answers "what's next?"; REST twin `GET /v1/program/{id}`; an empty result
+means nothing carries a `blocks` edge to that root yet — see "Grouping work
+under an umbrella node" below for how to model one), and to COMMIT:
+`capture` (raw prose → server types it — reach
 for this when unsure of the shape), or the precise writes `put_node` /
 `add_edge` / `set_status`. Close loops with edges: answer a question with a node
 carrying an `answers` edge; close work with a `resolves` edge from a
 `decision`/`artifact`.
 
+## Grouping work under an umbrella node (programs)
+
+When a workstream outgrows a handful of nodes — a milestone, a refactoring
+program, a launch — group it under an **umbrella node** so the program view
+can render it. There is no `program` node type: the umbrella is an ordinary
+node, almost always a `task` (id like `task-<stem>-program`) whose body says
+what the program is and what "done" means. (`type: project` /
+`grouped-under` is the unrelated repo-identity layer — never use it to group
+work.)
+
+Membership is **`blocks` topology**: each member carries a `blocks` edge TO
+the umbrella — "the umbrella can't finish until this does":
+
+```bash
+spor edge task-api-rate-limit blocks task-platform-hardening-program
+# MCP: add_edge {id: "task-api-rate-limit", type: "blocks", to: "task-platform-hardening-program"}
+```
+
+- Write it from the member's perspective (member `blocks` umbrella). The
+  inverse spelling (`blocked-by` on the umbrella) is accepted and flipped;
+  duplicate edges are a no-op.
+- **Only `blocks` edges count.** The program view walks inbound `blocks`
+  edges transitively and nothing else — members joined by `relates-to`,
+  `mentions`, or `derived-from` are invisible to it (and to the queue's
+  blocked-gating).
+- Nest freely: a workstream hub that `blocks` the program hub hangs its whole
+  subtree under it — the walk is transitive, so one edge per level is enough.
+- The gating is real, not cosmetic: the umbrella leaves the actionable queue
+  until its members land, and closing it at the end still needs a resolver
+  like any task.
+
+Read it back with `render_program` (`{id: "<umbrella-id>"}`; REST `GET
+/v1/program/<id>`): the gating tree with resolution-derived progress, where
+**done** = terminal status, supersession, or a live `resolves`/`answers`
+edge — the queue's truth, even while a status field lags. An empty result
+means nothing `blocks` the root yet — add the member edges above.
+`show_queue` answers "what's next?"; `render_program` answers "how far along
+is the whole thing?".
+
 ## Adding a node or edge type
 
 Because schemas are themselves nodes, you extend the ontology by **writing a

package/skills/spor/references/concepts.md

@@ -60,7 +60,7 @@ are same-direction synonyms renamed at write time.
 | resolves | 0.9 | this fixes/closes the target | — |
 | triggered-by | 0.7 | this run was triggered by the target | — |
 | performs | 0.8 | this run is an execution of the target workflow | — |
-| blocks | 0.7 | the target can't proceed until this does | inverse `blocked-by` |
+| blocks | 0.7 | the target can't proceed until this does | inverse `blocked-by`; also program membership — member `blocks` umbrella, rendered by `render_program` |
 | answers | 0.7 | this answers the target question | inverse `answered-by` |
 | assigned | 0.5 | work assigned to this person OR agent (explicit routing; an agent target may carry a `profile:` per-assignment override) | — |
 | relates-to | 0.5 | weak association | alias `related-to` |

package/skills/triage/SKILL.md

@@ -42,8 +42,9 @@ finish the whole queue in one sitting — say what you triaged and what's left.
 
 ## 1. Pull the queue and read the landscape
 
-Get it with the queue's own resolver — `spor next --json` (or the `my_queue`
-MCP tool in Cowork). Read the **aggregates**, not just the page: `total_count`,
+Get it with the queue's own resolver — `spor next --json` (or the `show_queue`
+MCP tool in Cowork; omit `assignee` — `assignee: "me"` narrows to directly
+assigned/stewarded work only). Read the **aggregates**, not just the page: `total_count`,
 `counts_by_type`, `counts_by_suggest`, and the side-channels `pending`
 (unprocessed captures), `questions` (routed/unrouted to you), `findings`
 (gardener observations), plus `dormant`/`muted` counts.
@@ -210,6 +211,12 @@ Record a confirmed one as a `blocks` edge from the prerequisite to the dependent
 (mirroring how an issue records its block). The dependent then leaves the
 actionable queue until its blocker resolves — which is the point.
 
+Once the topology is recorded you can sanity-check it from the top: the
+program/progress view (`render_program` MCP tool, or `GET
+/v1/program/<root-id>` in a shell) walks a root node's gating tree over
+`blocks` edges with resolution-derived progress — a fast way to confirm the
+edges you just wrote hang the work under the right umbrella.
+
 ## 7. Open questions → brief the lineage, then answer
 
 This is where triage earns its keep: the queue's `questions` are decisions