@sporhq/spor 0.2.8 → 0.3.0

package/.claude-plugin/plugin.json

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

package/API.md

@@ -52,7 +52,8 @@ 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`
-→ `query_graph` with `root_id` (deepen) → `render_lens` on a lineage lens →
+(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
 descriptions. `query_graph`'s `root_id` is the recursive-deepen move (walk
 neighbor → neighbor); `render_lens` lineage lenses trace why a node exists,
@@ -172,14 +173,32 @@ Only an unreachable ingestion model is an error (`ingestion_unavailable`).
 ### `my_queue`
 
 The decision queue (QUEUE.md §4/§5). Input `{ "project"?: "slug",
-"limit"?: 20 }` → `{ "items": [{id, title, type, status, priority, score,
-signals: {blocking, heat, staleness, age_days}, suggest: "do|close", why}],
-"count": N, "questions": [] }` — queueable live nodes ranked by the default
-blend, each with a one-line *why*. Items already retired by a live inbound
-resolves/answers edge are excluded whatever their status field reads; open
-gardener findings ride along per item as `findings`. Structured output
-additionally carries `view` — the queue projected into the view-tree catalog
-for the MCP-app widget (below).
+"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,
+"total_count": N, "truncated": false, "next_offset": null, "questions": []
+}` — queueable live nodes ranked by the default blend, each with a one-line
+*why*. Items already retired by a live inbound resolves/answers edge are
+excluded whatever their status field reads; open gardener findings ride
+along per item as `findings`. Structured output additionally carries
+`view` — the queue projected into the view-tree catalog for the MCP-app
+widget (below).
+
+**Limit and pagination.** `limit` is the page size (default 20, **max
+100** — values above the max are clamped, not rejected); `offset` skips that
+many items in the ranked order before the page (default 0). The aggregate
+counts (`counts_by_type` / `_project` / `_suggest`, `total_count`) always
+cover the **full** ranked set regardless of the page, so a single call
+answers "how many issues vs tasks" without paging or project-splitting.
+`returned_count` is the size of this page, `truncated` is true when more
+items follow it, and `next_offset` is the offset to pass next to continue
+(null on the last page). Pagination is **offset over a point-in-time ranked
+slice, not a cursor**: the queue re-ranks on every call (heat, age, leases,
+and status all shift), so an offset resumes the same slice only if the
+ranking has not changed between calls — the benign failure mode is an item
+seen twice or skipped once across a re-rank, never a hard error. Walk the
+whole queue by re-calling with `offset = next_offset` until `next_offset` is
+null.
 
 ### `ask_question`
 
@@ -216,6 +235,25 @@ render). Unknown `lens_id` still errors, carrying the same `catalog`/`lenses`
 list; engine failures (missing param, broken blocks) error with the message
 verbatim.
 
+### `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
+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"? }` →
+`{ "changes": [{id, change, commit, date, committed_by, type, title,
+authored_via, author}], "count", "head", "since", "project", "generated_at",
+"node_ids" }`. `since` is a 7–40 hex commit sha (changes in `sha..HEAD`) or a
+date/relative phrase git understands (`"12 hours ago"`, `"2026-06-15"`);
+omitted, it returns the most recent changes. `project` scopes to one project's
+nodes (deletions, whose project is gone, are necessarily omitted when scoped).
+Each entry is decorated with the node's CURRENT `authored_via`
+(`capture`/`distill`/`gardener` = machine, else human) — the trust signal the
+rendered digest/briefing hides. The tool returns the changed nodes as data;
+the model writes the prose summary (no LLM on this path). It is the MCP twin of
+`GET /v1/changes` (§3), sharing one core so the two surfaces never drift.
+
 ### The MCP-app widget (`ui://spor/view-tree.html`)
 
 `my_queue` and `render_lens` declare a UI resource via
@@ -237,7 +275,7 @@ endpoint is the REST twin of a core call:
 |---|---|---|
 | `GET /v1/status` | session-start, monitoring | `{node_count, projects: {...}, head, uptime, metrics}`; doubles as the health check. `?titles=1` adds `titles: [{id, type, project, title}]` — the one-round-trip graph index the distiller dedups against |
 | `GET /v1/me` | `spor whoami`/`status`, onboarding | identity echo for the bearer token → `{person, name, email, bound, is_admin}`. `bound:false` means the token authenticates but maps to **no person node** (legacy/OAuth, or minted before the node existed), so routed questions and the personal queue will be empty — the client warns on it (the silent identity-degradation signal). `is_admin` reflects the `stewards→root` edge that gates the token-admin surface |
-| `GET /v1/briefing/{project}` | session-start | read the `brief-<project>` node → `{found, version, body, graph_status}`. The slug resolves through project-node aliases (GRAPH.md "Project identity nodes") before lookup. Optional `?fp=root:<sha>,remote:<host/path>,...` carries the repo's fingerprints: the server learns them onto the owning project node, and an unknown slug with a known fingerprint files an alias proposal in the queue |
+| `GET /v1/briefing/{project}` | session-start | read the `brief-<project>` node → `{found, version, body, project_brief?, graph_status}`. The slug resolves through project-node aliases (GRAPH.md "Project identity nodes") before lookup. A BARE repo slug also rides up to its home-project grouping: the grouping's `brief-<grouping>` node returns alongside as `project_brief` (the product context spanning sibling repos), matching the shared up-resolution (dec-spor-queue-slug-resolves-to-grouping); passing the repo NODE id (`repo-<slug>`) is the escape hatch that returns only the repo brief, no `project_brief`. Optional `?fp=root:<sha>,remote:<host/path>,...` carries the repo's fingerprints: the server learns them onto the owning project node, and an unknown slug with a known fingerprint files an alias proposal in the queue |
 | `POST /v1/digest` `{query, min_sim?}` | prompt-context | digest-mode compile → `{found, text}`; `found: false` is a successful empty result |
 | `GET /v1/nodes/{id}` | /spor:brief | `get_node` semantics; when a live inbound resolves/answers edge contradicts a still-open status the response carries `resolution`, and open gardener findings about the node ride along as `open_findings` |
 | `POST /v1/nodes` | drain-outbox, mechanical writers | `put_node` semantics, batch: `{nodes: [...], if_exists: "skip"}` (entries may be raw strings or `{node, if_exists, revision}`) → `{results: [...]}`, 207 when any entry failed |
@@ -245,10 +283,11 @@ endpoint is the REST twin of a core call:
 | `POST /v1/nodes/{id}/status` `{status}` | scripts, mechanical writers | `set_status` semantics (§1): one-scalar update through the `transitions()` gate |
 | `POST /v1/nodes/{id}/commits` `{repo, sha}` | post-tool / link-commits | `link_commit`: append `repo@sha` to the node's `commits:` list (kebab-case repo slug, 7–40 lowercase hex, ≤40 commits per node); idempotent, prefix-aware dedup |
 | `GET /v1/commits/{sha}?repo=` | sessions doing git archaeology | sha → nodes lookup over the `commits:` fields (≥7 hex, abbreviated or full); each match carries `{repo, sha, id, type, title, summary, status, project}` — blame a line, get the why |
+| `GET /v1/changes?since=&project=&limit=` | `recent_changes`'s REST twin; audit review | the remote audit trail: a git-log projection over `nodes/` → `{changes: [{id, change, commit, date, committed_by, type, title, authored_via, author}], count, head, since, generated_at}`, newest change per node first. `since` is a 7–40 hex sha (`sha..HEAD`) or a date/relative phrase git understands (`--since`); an unresolvable sha is `422`. `project` scopes to one project's nodes (deletions are omitted when scoped, their project being gone). `limit` bounds nodes returned (default 100, **max 500**). Each entry's `authored_via` is the current machine-vs-human signal (`capture`/`distill`/`gardener` = machine). Lets a remote client review what agents wrote without the whole `/v1/export` tarball |
 | `POST /v1/capture` | distill, /spor:defer | `capture` semantics: `{text, context: {project, during, blocks?, needed_by?}, source?}` → ingestion model + validate + commit → `{status, ids, nodes, summary, warnings}`. `source: "distill"` marks backstop captures in the journal. `context.blocks` (a node id, must exist) and `context.needed_by` (`YYYY-MM-DD`) declare a cross-project dependency (task-cc-xproject-dependency-loop): set `context.project` to the SERVING project and the server attaches a `blocks` edge to the requester + the deadline deterministically (not via the model) onto the primary node. A missing `blocks` target is `404`; a non-date `needed_by` is `422` — both rejected before any model call |
 | `POST /v1/distill/report` | distill | sweep telemetry, journal-only (no store mutation): `{facts, captured?, spooled?, rejected?, project?, session?}` → `{status: "reported"}`; zero-fact sweeps report too |
 | `POST /v1/corrections` | /spor:correct | `propose_correction` semantics → 201 `{status, id, revision, warnings}` |
-| `GET /v1/queue?project=&limit=` | /spor:next, session-start | the ranked decision queue: `{items, count, muted?, dormant?, questions, findings, 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` are the routed-to-me-plus-unrouted views for the authenticated identity |
+| `GET /v1/queue?project=&assignee=&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, findings, 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` are the routed-to-me-plus-unrouted views for the authenticated identity. `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. `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) |
 | `POST /v1/questions` `{text, title?, mentions?}` | 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, routed_to, via, asker, revision, warnings}` |
 | `POST /v1/gardener` | ops cron / on demand | run a gardener sweep now; findings filed as queue items → `{filed, resolved, ..., generated_at}` |
 | `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 |
@@ -366,3 +405,55 @@ SPOR_TOKEN=spor_pat_...                # per-user token (§4)
 Failure policy: **fail open, never block** — a hook must never break a
 session; connection refused, timeout, 5xx, and auth failure all collapse to
 "the graph has nothing for you".
+
+Because fail-open hides degradation by design — a crashing engine and a
+quiet success look identical, and stranded captures pile up unseen in
+`outbox/dead/` — the client carries three operability surfaces
+(task-cc-client-hook-operability-diagnostics):
+
+- **Crash telemetry.** The dispatcher's top-level catch appends one line to
+  `journal/remote.log` (`dispatcher <event>: crashed (fail-open, exit 0):
+  …`) before honoring the exit-0 contract, so a crash is distinguishable
+  from healthy silence after the fact.
+- **Session-start nudge.** When `outbox/dead/` is non-empty or the outbox
+  spool exceeds a depth threshold, session-start splices a one-line warning
+  into the same channel as the `OFFLINE`/`AUTH FAILED` banner, pointing at
+  `spor-hook doctor`.
+- **`spor-hook doctor`.** An operator-run, read-only diagnostic (no stdin,
+  exits 0) that reports resolved mode, server reachability, token validity,
+  outbox + dead-letter counts with the oldest file's age, cached-briefing
+  freshness, and the trailing error lines from `journal/remote.log` and
+  `journal/distill.log`.
+
+### 6.1 Per-repo graph home (local-mode git sharing)
+
+In **local mode** a code repo can bind itself to a specific graph home with a
+`graph: <path>` key in its committed `.spor` marker (the same flat `key: value`
+marker that carries `repo:`/`project:`). This is how a team shares one graph
+for free over plain git, with no server (dec-spor-local-mode-sharing-boundary):
+
+```
+# .spor at the repo root
+repo: my-service
+graph: ../my-team-graph     # path, resolved relative to this marker
+```
+
+Contract:
+
+- **Precedence.** The `graph:` binding **overrides `SPOR_HOME`** — it is the
+  one input above the environment — but loses to an explicit CLI `--home`. A
+  `home` set in `.spor.json` config stays *below* the environment, unchanged; only the
+  `.spor` marker `graph:` key beats env. (A contributor with a personal global
+  `SPOR_HOME` therefore still inherits the shared graph inside a shared-graph
+  repo.)
+- **Resolution.** Relative to the marker's own directory (so a committed
+  relative path is stable regardless of cwd); nearest-ancestor marker carrying
+  a `graph:` key wins.
+- **Mode.** Local mode only. With `SPOR_SERVER` set the server is the graph and
+  the marker is ignored.
+- **Hygiene.** When a marker home is in force the client maintains a
+  `.gitignore` in it covering the machine-local, per-person state
+  (`journal/`, `cache/`, `outbox/`, `auth/`, `config.json`); only the durable
+  `nodes/` and brief `history/` are committed. The SessionEnd distiller leaves
+  distilled nodes **uncommitted** (for the human PR flow) instead of
+  auto-committing when the graph home is the same git repo as the code repo.

package/GRAPH.md

@@ -136,6 +136,46 @@ a change still in review has not delivered. So:
   exactly as before, so a change still in review keeps its task live without any
   hand-managed `open` status.
 
+## The org-defined policy layer
+
+"What it takes to reach a resolving/done state" beyond the native floor —
+quorum, qualified approvers, agent-vs-human distinctions — lives in **`policy`
+nodes**, a reserved schema kind layered ON TOP of the per-type
+`transitions()` gate (task-cc-policy-layer, dec-spor-policy-layer-activate;
+dec-spor-definition-of-done-org-policy Stage 2). A policy node is an ordinary
+`type: schema` node with `kind: policy`, a `governs` scope block in its fenced
+`json` payload, and an attached fenced `js` block exporting
+`gate(current, proposed, view) -> { allow, reason? }`. The payload declares the
+scope; the gate is the rule. For example, a policy `governs`-ing tasks in
+project `my-team` with a payload `{ "governs": { "types": ["task"], "projects":
+["my-team"] } }` and a `gate` that, on a `done` transition, counts
+`view.approvals` whose `roles` include `reviewer` and denies unless there are at
+least two — the definition-of-done quorum gate.
+
+- **Selection is governs-traversal.** `governs.types` restricts the policy to
+  those node types, `governs.projects` to those project slugs; an absent or
+  empty axis means "any". A node is governed by every policy whose every
+  present axis matches it — so an org-wide policy (no `governs`) and a
+  team-scoped one can both apply, most-specific first.
+- **The gate is AND-ed with `transitions()`, never replaces it.** Every
+  governing policy's `gate()` must also `allow` the write; any deny stops it.
+  A policy can only ADD a constraint — it can never loosen a type's
+  `transitions()` or the native self-approval floor beneath both
+  (dec-cc-policy-floor-now-layer-deferred). Like `transitions()`, the gate is
+  fail-closed (a crashing gate denies) and runs on UPDATE only.
+- **Approvals are review edges.** The gate context carries `view.approvals`:
+  the node's own `reviewed-by`/`approved-by` edges to `person` nodes, each
+  joined to that person's `roles` register, with the node's own author
+  excluded (the self-approval floor — a policy can't be used to launder it).
+  The first concrete rule is the **definition-of-done quorum gate**: a work
+  node's `done` transition additionally requires a quorum of approvals from
+  qualified roles. (The `reviewed-by`/`approved-by` edge types and a native
+  review surface ship with review-as-graph-object; the policy kind, scope
+  selection, and the gate AND are landed now.)
+- **Policy nodes go through the same proposal/activation flow they govern** —
+  a proposed policy is inert until a *different* identity activates it (the
+  native floor protects against self-amendment circularity).
+
 ## Norm ride-along
 
 A `norm` node (any `always_on` type) rides along on every compile — but the
@@ -210,6 +250,13 @@ edges:
   into distinct identities. With no subtree marker the search reaches the root
   and inference is unchanged. Zero-config slug inference stays the default, and
   a graph with no repo nodes behaves exactly as before.
+- The same flat marker can also carry a `graph: <path>` key — a per-repo
+  **graph home binding** (NOT identity), for free local-mode graph sharing over
+  plain git. It points the repo at a shared graph home (resolved relative to the
+  marker dir) and overrides `SPOR_HOME` in local mode; a contributor with their
+  own personal `SPOR_HOME` still inherits the shared graph inside the repo. See
+  API.md §6.1 for the full contract (precedence, the generated `.gitignore`, and
+  the distiller's PR-flow behavior).
 - **Git worktrees** resolve to their main repo, not the worktree directory's
   basename. A linked worktree shares the main repo's root-commit sha and
   remotes, so inferring identity from its (markerless, often throwaway-named)
@@ -245,9 +292,16 @@ date: 2026-06-13
 ---
 ```
 
-- **Reads.** repo-scoped = nodes stamped that repo's slug; project-scoped = the
-  union over the nodes of every repo `grouped-under` the project. Session-start
-  injects the repo brief AND the project brief.
+- **Reads.** Every read surface (queue, brief, digest) resolves its scope token
+  through one shared up-resolution step (dec-spor-queue-slug-resolves-to-grouping):
+  a BARE repo slug resolves up to its home-project grouping and reads the union
+  over every repo `grouped-under` it — the intuitive token returns the whole
+  product, matching the project brief session-start already injects. The repo
+  NODE id (`repo-<slug>`) is the escape hatch back to single-repo scope; an exact
+  grouping id (`proj-<slug>`) is used directly; an ungrouped repo (or a slug no
+  repo node claims) falls back to itself. So project-scoped = the grouping union,
+  single-repo-scoped = that one repo via its node id. Session-start injects the
+  repo brief AND the project brief.
 - **Active project** (dec-cc-active-project-declared-default). When a repo
   serves more than one project, cwd no longer names the active one. A session's
   active project is the repo's home project (its `grouped-under` edge) by
@@ -274,6 +328,7 @@ type: person
 title: Anthony Allen
 summary: Maintainer; stewards the schema registry and the hook engines.
 email: losthammer@gmail.com
+roles: [reviewer, maintainer]
 queue_mute: [some-noisy-project, task-noisy-job@2026-07-01]
 date: 2026-06-10
 edges:
@@ -295,13 +350,21 @@ edges:
   neighborhood to the closest steward and writes a `routed-to` edge to that
   person; an unrouted question (no steward matched) surfaces to everyone.
 - **`assigned`** points work (task/issue) at a person; per-person queues filter
-  on it. **`answers`** points any answer node back at the `question-` it
+  on it (the queue's `assignee` parameter — `GET /v1/queue?assignee=<person>`,
+  unioned with the person's `stewards` edges; QUEUE.md §5). **`answers`** points
+  any answer node back at the `question-` it
   resolves — the answer loop is lineage, not messaging, so the asker's next
   compile pulls the answer through the question's neighborhood.
 - **`queue_mute`** (flat inline list of project slugs or node ids, each with an
   optional `@YYYY-MM-DD` expiry) is per-viewer presentation only: the queue
   hides those items for this person and reports how many it hid; they stay live
   and visible to everyone else (QUEUE.md §4).
+- **`roles`** (flat inline list, e.g. `roles: [reviewer, maintainer]`) is the
+  qualification register the org-defined policy layer reads. A scoped `policy`
+  node's gate counts approvals from persons holding a named role — the
+  definition-of-done quorum gate is the first such rule (see "The org-defined
+  policy layer" below). Declarative data only; absent it, a person holds no
+  roles and the field has no effect.
 
 ### Onboarding a team member
 

package/QUEUE.md

@@ -287,12 +287,34 @@ levels, and keeping them distinct is the design:
    gate context so identity-aware rules are expressible.
 
 A wider org-defined **policy layer** — a reserved `policy` kind in the
-schema family whose gate would run on every write AND-ed with the per-type
+schema family whose gate runs on a write AND-ed with the per-type
 `transitions()`, carrying role lists, quorum rules, agent-vs-human
-distinctions, and the queue-blend override as one mechanism — is
-deliberately deferred until a real org rule demands more than the floor
-(dec-cc-policy-floor-now-layer-deferred). The enabling hook (`view.actor`)
-ships now so the layer needs no core change when it comes.
+distinctions, and (eventually) the queue-blend override as one mechanism — was
+deferred until a real org rule demanded more than the floor
+(dec-cc-policy-floor-now-layer-deferred), then activated once one did
+(dec-spor-policy-layer-activate). The first rule it expresses is the
+**definition-of-done quorum gate** (dec-spor-definition-of-done-org-policy
+Stage 2): a `policy` schema node, selected for a node by **governs-traversal**
+(`governs.{types,projects}`; nearest scope wins, an org-wide policy still
+applies), runs `gate(current, proposed, view)` AND-ed with the type's
+`transitions()` — any deny stops the write, so a policy can only ADD a
+constraint, never loosen the gate or the native floor beneath it. The
+quorum gate requires a work node's `done` transition to carry a quorum of
+approvals from qualified roles: `view.approvals` is the node's
+`reviewed-by`/`approved-by` edges to `person` nodes joined to each person's
+`roles` register, with the node's own author excluded (the self-approval floor).
+The enabling hook (`view.actor`) shipped with the floor, so this was net-new
+policy-kind work, not core surgery (GRAPH.md "The org-defined policy layer").
+
+Still on the layer's roadmap, beyond the quorum gate: the agent-vs-human
+claim-eligibility promoted-set (task-cc-claim-eligibility-policy), the
+queue-blend override absorbed as a `policy` rather than the separate
+`queue-policy` singleton (task-cc-schema-queue-policy-override), the seed
+`reviewed-by`/`approved-by` edge types + a native review surface
+(review-as-graph-object, Stage 3, which supplies the approval edges the quorum
+gate counts), and a fuller governs-traversal that walks the project/path
+hierarchy via `governs`/`governed-by` edges rather than matching the flat
+`governs.{types,projects}` scope.
 
 ## 3. The capture flow, end to end
 
@@ -339,11 +361,28 @@ signals via its schema's `queueSignals()`:
   merely retrieved — a single prompt-submit digest lists ~60 — so only
   work-class ops count (issue-cc-heat-amplification and its digest round).
 - **front** — the viewer's own write-class ops on the node (puts, edges,
-  status flips, captures during it) over the last week, identity-scoped
-  from the same journal (`store.writeActivity`). Counts the node itself
-  only — no neighborhood propagation — so provenance hubs can't ride it;
-  capped below the p1 bump so human priority stays supreme
-  (dec-cc-queue-front-from-attribution).
+  status flips, captures during it) over a rolling window (default 7 days),
+  identity-scoped. In **remote** mode the server injects it from the same
+  request journal (`store.writeActivity`). In **local** mode there is no
+  request log, so it is reconstructed from **git history**
+  (`gitFront()` in `lib/queue.js`, task-cc-local-front-productionize): the
+  graph home is a git repo the distiller auto-commits into, the local
+  `git config user.email` is the viewer identity, and a commit that
+  adds/modifies/renames `nodes/<id>.md` is a write-class op on that node.
+  `git log --since=<days> days ago --author=<email> --diff-filter=ACMR
+  --name-only -- nodes/` yields the same `{nodeId: count}` map the server
+  builds; each commit lists a touched file once, so occurrences across the
+  log = the node's write count. Pure deletes (D) are excluded — a removed
+  node isn't live work — and there is no neighborhood spread, matching the
+  server. It is best-effort and fail-open: not a git repo, no commits, or an
+  unset `user.email` yields an empty map (front 0 everywhere, the pre-front
+  ordering). The window and an on/off toggle live in the config cascade
+  (`queue.front.days` / `queue.front.enabled`, env `SPOR_QUEUE_FRONT_DAYS` /
+  `SPOR_QUEUE_FRONT`); the `lib/queue.js` CLI flags `--days` / `--no-front`
+  override them. Counts the node itself only — no neighborhood propagation —
+  so provenance hubs can't ride it; capped below the p1 bump so human
+  priority stays supreme; and the why-line states the actual window
+  ("N writes in the last D days") (dec-cc-queue-front-from-attribution).
 - **staleness** — anchors superseded or gone; high staleness suggests
   closing, not doing.
 - **age**, and any org-specific signal the schema's code adds (SLA clocks,
@@ -392,10 +431,17 @@ and edges see it normally; only queue ranking waits.
 
 The queue is a compile mode, not a new store:
 
-- `rankQueue(graph, {person?, project?})` in the core: collect nodes whose
-  schema says `queueable: true` and status is live, run `queueSignals()`,
+- `rankQueue(graph, {assignee?, project?, ...})` in the core: collect nodes
+  whose schema says `queueable: true` and status is live, run `queueSignals()`,
   blend, return ranked items each carrying its one-line *why* ("blocks 3
-  open tasks; anchors hot this week").
+  open tasks; anchors hot this week"). `assignee` (a person node id) narrows
+  the queue to the work that person carries — see "Per-person queues" below.
+- The `project` filter resolves through the one shared up-resolution step every
+  read surface shares (dec-spor-queue-slug-resolves-to-grouping): a BARE repo
+  slug resolves up to its home-project grouping and unions the member repos'
+  queues — the intuitive token returns the whole product; the repo NODE id
+  (`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.
 - Exposed as `GET /v1/queue` (hooks, session-start "open front" line),
   `my_queue` (the registered MCP stub finally does work — and when Tier 2
   routing lands, routed questions and stewarded items join the same queue),
@@ -406,8 +452,28 @@ The queue is a compile mode, not a new store:
   Tier-2 routed questions are all queueable schemas. "Home is a decision
   queue" falls out of one mechanism.
 
-Per-person queues need only Tier 2's person nodes and `stewards`/`assigned`
-edge schemas — assignment is an edge like everything else.
+**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
+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
+nodes plus the seed `assigned`/`stewards` schemas), so this needed no new
+store — the same blend, signals, and why-lines, narrowed to a person. A
+manager answers "who is carrying what" and "what is X blocked on" by naming
+each person in turn; an unknown or departed person id returns an empty queue,
+never the whole team's work. The filter is a hard scope like `project` (it
+composes with it) and never overrides liveness — a terminal task assigned to
+the person still leaves the queue.
+
+A **grouped** team-capacity view (everyone's open work at once, bucketed by
+owner) is a first-party manager need, not merely a customer illustration —
+the `lens-team-capacity` example (in the meridian fixture corpus) is the
+shape. Shipping it as a live-native default lens is deferred: the lens engine
+groups by a frontmatter field, so a live grouping by the `assigned` *edge*
+awaits group-by-edge-target support; the meridian fixture works because it
+also carries an `owner:` field. Until then the `assignee` filter is the
+shipped per-person surface (iterate it per person for the capacity picture).
 
 ## 6. The gardener
 

package/README.md

@@ -40,6 +40,21 @@ the same step. Re-running is idempotent — it refreshes the path and never
 duplicates your other hooks. (In Claude Code you can also install by hand:
 `/plugin marketplace add sporhq/spor` then `/plugin install spor@spor`.)
 
+Upgrading. Bumping the package does **not** refresh what an agent already
+loaded — Claude Code runs its own cached copy of the plugin, so new
+skills/hooks won't appear until that copy is updated. After an npm bump, run:
+
+```bash
+npm install -g @sporhq/spor   # update the package on disk
+spor upgrade                  # refresh every wired host to it, then restart
+```
+
+`spor upgrade` updates Claude Code's plugin (`marketplace update` +
+`plugin update`) and re-points the hook hosts at the new install; pass a host
+(`spor upgrade claude`) to scope it, or `--print` for a dry run. `spor status`
+flags the gap on its own — it shows the loaded plugin version and marks it
+`STALE` when the package on disk is newer.
+
 Then onboard a repo — one command, from inside it:
 
 ```bash
@@ -74,6 +89,7 @@ spor dispatch "wire up token rotation in the pipeline"   # free-text task, brief
 spor dispatch issue-86                                    # a node id — briefs its neighborhood
 spor dispatch --from-queue                                # the top item from 'spor next'
 spor dispatch --backfill                                  # onboard this repo via /spor:backfill
+spor dispatch <task> --template prompt.tpl                # launch your own prompt, context injected
 spor dispatch <task> --print                              # dry run: show dir, prompt, argv
 ```
 
@@ -88,6 +104,16 @@ Spor already knows where that repo lives. Flags pass through to `claude`
 (`--model`, `--permission-mode`, `--agent`, `--name`); `--full` embeds the whole
 neighborhood and `--no-brief` skips the briefing.
 
+**Your own prompt.** By default the briefing is prepended to a built-in prompt
+shell. Pass `--template <file>` (or set a default path in `dispatch.template`)
+to supply your own prompt instead, with Handlebars-style `{{placeholder}}`
+tokens substituted from the dispatch context: `{{brief}}` (the compiled
+briefing, aka `{{briefing}}`/`{{neighbourhood}}`), `{{task}}`, `{{node}}`,
+`{{title}}`, `{{slug}}`, `{{dir}}`, and `{{default}}` (the whole built-in
+prompt, so you can wrap rather than replace it). Unknown placeholders blank out
+with a warning. The template takes over the prompt entirely — you decide where
+the brief and task land.
+
 ## What your agent gets, and gives back
 
 The loop runs without you having to drive it:
@@ -153,10 +179,11 @@ edges to the nodes it relates to; the format is documented in
 ## Team mode
 
 Single-player Spor is the whole client. Team mode is what you reach for when
-the graph should be shared: one graph served to your entire team — the people
-and their agents alike — with per-identity attribution on every node,
+the graph should be shared *live*: one graph served to your entire team — the
+people and their agents alike — with per-identity attribution on every node,
 transactional writes so concurrent work doesn't clobber, and a shared
-decision queue ranked across the team.
+decision queue ranked across the team. (A team can also share a graph for free
+over plain git, with no server — see "Sharing a graph over git" below.)
 
 Team mode adds something a personal graph can't do: when a question can't be
 answered from what's already there, it routes to the person most likely to
@@ -176,6 +203,59 @@ server is ever unreachable, the client fails open — it falls back to a local
 cache or to nothing, never blocking your session. The full contract a client
 programs against is in [API.md](API.md).
 
+> **Split-brain warning (local mode + a claude.ai Spor connector).** If your
+> Claude Code is logged into a claude.ai account that has a **Spor MCP
+> connector**, that connector is live in your sessions too — even in local
+> mode — so you have *two* write surfaces at once: the local `$SPOR_HOME` file
+> graph (skills, CLI, and ambient hook captures) and the remote team graph
+> behind the connector (MCP-tool captures). Captures can split across them
+> with no signal which got which. Pick one surface: either set `SPOR_SERVER`/
+> `SPOR_TOKEN` to go fully remote, or disable the claude.ai Spor connector to
+> stay fully local. `spor status` detects this and warns.
+
+A team graph can also carry **lenses** — saved views (a board, a table, a
+lineage tree) defined as nodes and rendered by the server. View them from the
+shell:
+
+```bash
+spor lens                          # list the available lenses
+spor lens lens-roadmap             # render one to the terminal (text)
+spor lens lens-roadmap --format json   # the raw view tree, for piping
+spor lens lens-roadmap --project wf    # pass a lens parameter
+```
+
+Rendering happens server-side (the same engine as the `render_lens` MCP tool),
+so `spor lens` is a team-mode verb — in local mode it tells you to point at a
+team graph rather than failing.
+
+## Sharing a graph over git — no server
+
+A team can share one graph for free, with no live server, by treating the
+graph as the ordinary git repo it already is — everyone clones, pulls, and
+pushes it. Point a code repo at a shared graph with a `graph:` line in its
+committed `.spor` marker:
+
+```
+# .spor — committed at the repo root
+repo: my-service
+graph: ../my-team-graph
+```
+
+The path resolves relative to the marker, so the conventional layout is the
+graph as a **sibling** repo (`../my-team-graph`) each teammate clones alongside
+the code. This binding **overrides `SPOR_HOME`**: even a contributor with their
+own personal `~/.spor` inherits the shared graph while working in this repo, so
+prior decisions and dismissed approaches come for free. Distilled nodes land in
+the shared graph as plain markdown and ride your normal PR flow.
+
+Spor keeps the shared graph clean for you: it writes a `.gitignore` covering
+the machine-local, per-person state (`journal/`, `cache/`, `outbox/`, `auth/`,
+`config.json`) so only the durable `nodes/` (and brief `history/`) are
+committed, and the end-of-session distiller leaves nodes uncommitted for your
+PR — rather than auto-committing — when the graph lives inside the code repo
+itself. This is the free tier's sharing model; the live **Team mode** server
+above adds real-time concurrent writes, question routing, and hosted isolation.
+
 ## Configuration
 
 Settings can live in config files instead of environment variables, cascading
@@ -227,12 +307,38 @@ verifiable rather than asserted:
 - `SPOR_DISTILL=0` (or `distill.enabled: false`) disables distillation — you
   keep briefings with no SessionEnd model spend.
 - `SPOR_NUDGE=0` (or `nudge.enabled: false`) disables the capture nudge.
+- The capture nudge runs synchronously after a `.md` write, so its backend's
+  latency is felt in the tool loop. `SPOR_NUDGE_CMD` (or `nudge.cmd`) points it
+  at a faster classifier — Gemini Flash via the bundled
+  `scripts/distill-gemini.sh` returns in ~2–7s versus ~17s for a `claude -p`
+  cold boot, with no quality regression. Two bounds keep a bad session cheap:
+  `SPOR_NUDGE_MAX` (or `nudge.maxCalls`, default 20) caps classifier calls per
+  session, and `SPOR_NUDGE_TIMEOUT` (or `nudge.timeoutMs`, default 30000ms)
+  kills a hung backend. The distiller has the same `distill.cmd` and
+  `distill.timeoutMs` (`SPOR_DISTILL_TIMEOUT`, default 120000ms) levers. See
+  [adapters/README.md](adapters/README.md) for the backend contract.
 - Every call appends a row to `$SPOR_HOME/journal/llm-calls/<date>.jsonl` with
   token usage and the model-reported cost. `spor cost` (`--since YYYY-MM-DD`,
   `--project <slug>`, `--json`) totals it by source. Custom `SPOR_DISTILL_CMD`
   /`SPOR_NUDGE_CMD` backends return text only, so their rows count as
   cost-unknown.
 
+### Health and diagnostics
+
+The hooks fail open — they never break a session — which also means a dead
+server or a revoked token degrades quietly. To make that legible, run:
+
+```bash
+spor-hook doctor
+```
+
+It prints a one-shot health report: resolved mode, server reachability and
+token validity, the outbox and dead-letter depth (with the oldest stranded
+capture's age), how fresh the cached briefing is, and the most recent error
+lines from `journal/remote.log` and `journal/distill.log`. When captures
+have been stranded (a dead-letter pile-up or a deep outbox), session-start
+also surfaces a one-line nudge alongside its status banner pointing you here.
+
 ## Pointers
 
 - [GRAPH.md](GRAPH.md) — the node and edge format: what a node file looks

package/adapters/README.md

@@ -56,3 +56,35 @@ export SPOR_DISTILL_CMD="$HOME/repos/spor/scripts/distill-gemini.sh"
 
 The journal records the backend per call (`journal/llm-calls/`), so distill
 quality stays observable across backends through the same eval loop.
+
+## Capture-nudge backend
+
+The post-tool capture nudge (a Write/Edit of substantial prose to a `.md`
+outside the graph runs a classifier and, if it finds capturable facts, injects
+a capture-or-dismiss nudge) uses the **same backend contract** as the
+distiller — prompt on stdin, response on stdout — but a separate variable so
+you can point the two at different models:
+
+- `SPOR_NUDGE_CMD` — custom classifier command (defaults to `claude -p --model
+  haiku`, same as the distiller). Because the contract is identical,
+  `scripts/distill-gemini.sh` doubles as a nudge backend (it keys off
+  `SPOR_DISTILL_MODEL`, default `gemini-3.5-flash`):
+
+  ```sh
+  export SPOR_NUDGE_CMD="$HOME/repos/spor/scripts/distill-gemini.sh"
+  ```
+
+  This is the recommended latency fix: the nudge runs **synchronously** in the
+  tool loop, and Gemini Flash returns in ~2–7s versus ~17s for a `claude -p`
+  cold boot, with no quality regression (dec-cc-nudge-flash-latency).
+- `SPOR_NUDGE=0` — disable the nudge entirely.
+- `SPOR_NUDGE_MAX` — per-session ceiling on classifier calls (default 20),
+  bounding spend/latency in a docs-heavy session where many `.md` files each
+  classify to nothing. (A separate cap stops after 3 *fired* nudges.)
+- `SPOR_NUDGE_TIMEOUT` — milliseconds before a hung classifier is killed
+  (default 30000), so a wedged backend can't block the tool loop.
+
+(Legacy `SUBSTRATE_*` spellings are still read for all four.) The same
+`SPOR_DISTILLING=1` recursion guard is exported around the call, and the
+journal records each nudge call under `journal/llm-calls/` (source `nudge`)
+through the same eval loop as the distiller.

package/adapters/codex/README.md

@@ -27,11 +27,15 @@ is just a manifest over `bin/spor-hook`.
    # Distiller backend — Codex hosts usually won't have the claude CLI.
    # Contract: prompt on stdin, response on stdout.
    export SPOR_DISTILL_CMD='codex exec -'
+   # Capture-nudge backend — same contract, but it runs synchronously in the
+   # tool loop, so prefer a fast model. SPOR_NUDGE=0 disables it.
+   export SPOR_NUDGE_CMD='codex exec -'
    ```
 
-   (Legacy `SUBSTRATE_*` names are still read.) Without `SPOR_DISTILL_CMD`
-   the distiller defaults to `claude -p --model haiku`, which is fine if the
-   claude CLI is installed.
+   (Legacy `SUBSTRATE_*` names are still read.) Without `SPOR_DISTILL_CMD` /
+   `SPOR_NUDGE_CMD` both default to `claude -p --model haiku`, which is fine if
+   the claude CLI is installed. See [adapters/README.md](../README.md) for the
+   nudge bounds (`SPOR_NUDGE_MAX`, `SPOR_NUDGE_TIMEOUT`).
 
 ## Event mapping