@sporhq/spor 0.12.0 → 0.13.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.12.0",
+  "version": "0.13.0",
   "author": { "name": "losthammer" }
 }

package/API.md

@@ -137,6 +137,32 @@ different attributes → the edge's attribute set is replaced (not merged) in
 place. Omitting `attrs` never touches an existing edge's attributes, so a bare
 `add_edge` is unchanged.
 
+**Submitting a review is one call.** The review-outcome edges
+(`review-requested` / `reviewed-by` / `changes-requested-by`, plus the
+`approved-by` approval synonym) are mutually exclusive per `(node, person)` —
+the edge type *is* that reviewer's current verdict — so adding one review edge
+to a person **flips** any sibling review edge to that same person in place
+instead of leaving two contradictory edges. A reviewer thus turns a pending
+`review-requested` into `reviewed-by` (or `changes-requested-by`, or back) with
+one `add_edge`, no remove-and-re-add or whole-node `put_node`; the flip is
+reported in `warnings` (`flipped review-requested -> reviewed-by for <person>`).
+This is scoped strictly to the review family — every other edge type keeps the
+plain append-or-idempotent behavior above.
+
+### `remove_edge`
+
+Micro-mutation, the withdrawal twin of `add_edge`. Input `{ "id": "<node>",
+"type": "<edge type>", "to": "<target>" }` — accepts canonical, alias, and
+inverse forms, normalized exactly as `add_edge` (an inverse form removes the
+canonical edge on the *other* node and echoes that node's id). Output
+`{ "status": "updated|skipped", "id": <node actually modified>, "revision",
+"warnings" }`; a missing edge is an idempotent `skipped`, never an error. Use it
+when a relationship should simply cease to exist — a *withdrawn* review request
+or a *dismissed* review — which the `add_edge` review flip cannot express (the
+flip only swaps one verdict for another *within* the family; it never drops an
+edge). To change a verdict in place, prefer `add_edge`; reach for `remove_edge`
+to withdraw one. The REST twin is `DELETE /v1/nodes/{id}/edges` (§3).
+
 ### `set_status`
 
 Micro-mutation. Input `{ "id": "<node>", "status": "<value>" }`. Output
@@ -146,6 +172,20 @@ reason, exactly as on a full put. set_status on a `type: schema` node is how
 a human flips `proposed → active` (it carries the same authority as the
 equivalent put).
 
+### `set_priority`
+
+Micro-mutation, the human-override half of the decision queue
+(dec-cc-opinionated-queue-blend). Input `{ "id": "<node>", "priority":
+"<value>" }`, where `<value>` is `p1` (highest), `p2`, `p3`, or a clearing
+form (`none`/`clear`/`""`/`p0`) to remove it. Output `{ "status": "updated",
+"id", "revision", "warnings" }`; an unknown value is `invalid_node` with the
+allowed list in `details`. Like `set_status` it is a server-side
+read-modify-write — no client revision round-trip — and it stamps
+`priority_by` (acting identity), `priority_at`, and `priority_via` (the door)
+so an agent-set priority is distinguishable from human triage
+(issue-cc-priority-attribution-gap). The CLI wrapper is `spor priority <id>
+<p1|p2|p3|clear>`.
+
 ### `propose_correction`
 
 Sugar over `put_node` for the correction loop. Input:
@@ -324,8 +364,10 @@ endpoint is the REST twin of a core call:
 | `POST /v1/digest` `{query, root?, project?, min_sim?}` | prompt-context, /spor:brief | digest-mode compile → `{found, text}`; `found: false` is a successful empty result. `root` is the structural-walk twin of `query` (the two are mutually exclusive; `root` wins, an unknown id is `422`). Optional `project` is the session slug: the server scopes the compile to it — the same-project relevance boost, the grouping union, and the `always_on` norm `applies_to_*` ride-along — resolving the slug through project-node aliases/groupings inside compile (dec-spor-queue-slug-resolves-to-grouping), exactly as `/v1/queue` does. A bad slug is `422`; **omitting `project` runs the digest project-blind (byte-identical to before)**, so older clients that send only `{query}` are unaffected |
 | `GET /v1/nodes/{id}` | /spor:brief | `get_node` semantics; the node's active schema may attach read-time enrichment via a `get(node, ctx)` hook (GRAPH.md) — the seed `question`/`issue`/`task`/`incident` schemas attach `resolution`: a live inbound resolves/answers edge carrying the resolver's `summary`/`title` and a `lagging` flag (set when it contradicts a still-open status, clear when the node is already terminal, e.g. an answered question pointing at its answer). Open gardener findings about the node ride along as `open_findings`, and a node marked stale by an inbound supersedes edge as `superseded_by`. All enrichment is additive top-level keys; ignore unknown ones |
 | `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 |
-| `POST /v1/nodes/{id}/edges` `{type, to, attrs?}` | scripts, mechanical writers | `add_edge` semantics (§1): normalize/flip, dedupe, append — no revision echo. Optional `attrs` adds trailing flat edge attributes (e.g. a per-assignment `profile:` override); re-adding the same edge with different attrs upserts the set |
+| `POST /v1/nodes/{id}/edges` `{type, to, attrs?}` | scripts, mechanical writers | `add_edge` semantics (§1): normalize/flip, dedupe, append — no revision echo. Optional `attrs` adds trailing flat edge attributes (e.g. a per-assignment `profile:` override); re-adding the same edge with different attrs upserts the set. Adding a review-outcome edge (`reviewed-by`/`changes-requested-by`/`review-requested`) flips a sibling review edge to the same person in place — the one-call submit-review primitive |
+| `DELETE /v1/nodes/{id}/edges` `{type, to}` | scripts, mechanical writers | `remove_edge` semantics (§1): the withdrawal twin of the POST above — drop one typed edge by `{type, to}`, normalize/flip exactly as `add_edge` (an inverse form removes the canonical edge on the *other* node and echoes its id), no revision echo. A missing edge is an idempotent `skipped`. For *withdrawing* a relationship the review flip can't express — a pulled review request, a dismissed review |
 | `POST /v1/nodes/{id}/status` `{status}` | scripts, mechanical writers | `set_status` semantics (§1): one-scalar update through the `transitions()` gate. Setting a work node to an in-progress status also CLAIMS it (same lease as `/claim` below) |
+| `POST /v1/nodes/{id}/priority` `{priority}` | `spor priority`, queue triage | `set_priority` semantics (§1): one-scalar human-override update — `p1`/`p2`/`p3` or a clearing form (`none`/`clear`/`""`/`p0`). Server-side read-modify-write (no revision), stamping `priority_by`/`priority_at`/`priority_via` for the audit trail (issue-cc-priority-attribution-gap). Unknown value → `invalid_node` with the allowed list |
 | `POST /v1/nodes/{id}/claim` `{session?}` | `claim`/`set_status` MCP tools, `spor dispatch` | take the heartbeat-renewed lease (dec-cc-task-claim-lease): writes the durable `assigned` edge once, attributes to `$viewer` from the token (never an argument), and creates the ephemeral lease → `{ok, status, lease: {node_id, by, expires, expires_at, session, claimed_at}, edge}`. A live lease held by ANOTHER person is `409 conflict` naming the holder + expiry (re-claiming your OWN live claim just renews it). `session` scopes the heartbeat (omit to leave it person-scoped, so any of the claimer's sessions may renew — what `spor dispatch` does at the PRE-launch claim, since `claude --bg` self-allocates the run session only at launch; dispatch then renews with the real session once it has read it from `claude agents --json`, dec-spor-dispatch-bg-session-late-bind) |
 | `POST /v1/nodes/{id}/renew` `{session?}` | post-tool heartbeat, `renew` MCP tool, `spor dispatch` | bump the live lease's expiry only — no commit; the heartbeat that keeps a claim from lapsing. A lapsed/stolen lease is `409` (names the current holder). Person-scoped: any of the claimer's sessions may renew; a `session` binds the lease to that run (`spor dispatch` uses this to bind the captured `claude --bg` session post-launch) |
 | `POST /v1/nodes/{id}/release` | `release` MCP tool | drop the lease AND retire the durable `assigned` edge, returning the node to the pool. Idempotent (releasing a node you hold no lease on still succeeds, cleaning up any lingering `assigned` edge of yours); releasing a claim someone else holds is `409` naming the holder |

package/GRAPH.md

@@ -218,12 +218,22 @@ the server runs on the write path:
   human-readable error strings; `[]` means accept. A non-empty array rejects the
   write (`invalid_node`), each string surfaced to the writer as
   `<schema-id> validate(): <your message>`. This is where required/typed custom
-  fields are enforced.
-- **`transitions(current, proposed, view) -> { allow, reason? }`** — the status
-  gate. Runs on **update only** (the create path is ungated, so a status-less or
-  any first write is always allowed). `current` is the stored node (or `null` if
-  its file is unparseable), `proposed` is the incoming node, and `view` is a
-  read-only join the server computes for the gate:
+  fields — and **status-vocabulary membership** — are enforced. Membership is a
+  property of the node in isolation, so it belongs at the door, where create and
+  update see it alike; the seed `task`/`issue`/`decision`/`question`/
+  `capture-pending` schemas check it here. Putting it ONLY in `transitions()`
+  (update-only) let a node be BORN with an off-vocabulary status that a later
+  re-validating write then rejected (issue-spor-node-create-bypasses-status-
+  vocabulary); `validate()` and `transitions()` share one `VALID` list so the
+  two paths can't drift.
+- **`transitions(current, proposed, view) -> { allow, reason? }`** — the
+  *transition* gate. Runs on **update only** (the create path is ungated by it,
+  so a status-less or any first write passes; status-vocabulary membership is
+  gated separately in `validate()` above, on create too). This is where
+  state-machine legality and the completion-resolver gate live — both properties
+  of the current→proposed *transition*, not of the node alone. `current` is the
+  stored node (or `null` if its file is unparseable), `proposed` is the incoming
+  node, and `view` is a read-only join the server computes for the gate:
   - `view.targets[id]` — `{ exists, type, status, superseded }` for each node
     this one points an edge at (outbound);
   - `view.resolvers` — live **inbound** `resolves`/`answers` edges pointing at
@@ -292,9 +302,11 @@ date: 2026-06-16
 
 Escalation nodes track a customer-facing incident from raise to close.
 `severity` is a free-form frontmatter field this schema makes mandatory and
-constrains in `validate()`; the status machine and the close-time resolver gate
-live in `transitions()`. Both are the same procedural model the seed types use —
-there is no declarative field or status enum to fill in.
+constrains in `validate()`, alongside status-vocabulary membership (the door
+runs on create AND update, so the two paths agree on the enum); the close-time
+resolver gate — a property of the *transition* — lives in `transitions()`
+(update only). Both are the same procedural model the seed types use — there is
+no declarative field or status enum to fill in.
 
 ```json
 {
@@ -306,9 +318,17 @@ there is no declarative field or status enum to fill in.
 ```
 
 ```js
+// The status vocabulary, shared by validate() (membership; create AND update)
+// and transitions() (the close-time gate; update only) so the two paths agree
+// on the enum (issue-spor-node-create-bypasses-status-vocabulary).
+const VALID = ["open", "mitigated", "closed"];
+
 // validate(node) — runs at the door on EVERY write (create and update). Returns
-// an array of error strings; [] accepts. Enforce the free-form custom field here:
-// the payload declares no field list, so a required/typed field is code.
+// an array of error strings; [] accepts. Enforce node-in-isolation properties
+// here: the free-form custom field (no payload field list, so a required/typed
+// field is code) AND status-vocabulary membership — checking membership at the
+// door is what makes create and update agree on the enum (a node can never be
+// born with an off-vocabulary status that the close gate below would reject).
 export function validate(node) {
   const errors = [];
   const VALID_SEVERITY = ["sev1", "sev2", "sev3"];
@@ -317,22 +337,21 @@ export function validate(node) {
   } else if (VALID_SEVERITY.indexOf(String(node.severity)) === -1) {
     errors.push("invalid severity '" + node.severity + "': use sev1, sev2, or sev3");
   }
+  const s = ((node && node.status) || "").toLowerCase();
+  if (s !== "" && VALID.indexOf(s) === -1) {
+    errors.push("invalid escalation status '" + s + "': valid statuses are " +
+      "open, mitigated, closed — or none, meaning live");
+  }
   return errors;
 }
 
 // transitions(current, proposed, view) — runs on UPDATE only; returns
-// { allow, reason? }. Empty status (status-less = live) is always allowed.
+// { allow, reason? }. Gates the *transition*, not membership (validate() owns
+// that): closing requires a durable outcome on the graph. Empty status
+// (status-less = live) is always allowed.
 export function transitions(current, proposed, view) {
-  const VALID = ["open", "mitigated", "closed"];
   const next = ((proposed && proposed.status) || "").toLowerCase();
   if (next === "") return { allow: true };
-  if (VALID.indexOf(next) === -1) {
-    return {
-      allow: false,
-      reason: "invalid escalation status '" + next + "': valid statuses are " +
-        "open, mitigated, closed — or none, meaning live",
-    };
-  }
   // closed must record a durable outcome on the graph: a decision or artifact
   // that resolves this escalation (an inbound resolves edge). view.resolvers is
   // already filtered to resolving states, so an in-review fix does not count.
@@ -520,6 +539,7 @@ type: person
 title: Anthony Allen
 summary: Maintainer; stewards the schema registry and the hook engines.
 email: losthammer@gmail.com
+github: losthammer
 roles: [reviewer, maintainer]
 queue_mute: [some-noisy-project, task-noisy-job@2026-07-01]
 date: 2026-06-10
@@ -557,6 +577,15 @@ edges:
   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.
+- **`github`** (flat inline scalar, e.g. `github: octocat`) is the person's
+  GitHub handle — the login→person key the Spor server's GitHub review
+  reflection maps by. When a GitHub review or merge is reflected into the graph,
+  the event's GitHub login is matched (case-insensitively) to the person whose
+  `github` equals it, so the approval attaches to the right person's review
+  edges and counts toward the policy quorum gate; `github_login` is an accepted
+  alias, and an operator login→email map is the fallback. Declarative data only;
+  absent it, the person can't be resolved from a GitHub login and the field has
+  no effect.
 
 ### Onboarding a team member
 
@@ -813,7 +842,8 @@ Edges are written in the canonical direction above, but the server's write
 path accepts two normalized forms (API.md §1, registry data on each
 edge schema): **aliases** — same-direction synonyms renamed in place
 (`related-to` → `relates-to`, `derives-from` → `derived-from`,
-`supercedes` → `supersedes`) — and **inverse labels** — the edge read from
+`supercedes` → `supersedes`, `approved-by` → `reviewed-by`) — and **inverse
+labels** — the edge read from
 the target's side, flipped onto the target node on write (`blocked-by` →
 `blocks`, `answered-by` → `answers`, `superseded-by` → `supersedes`).
 Hand-written nodes should still use the canonical forms.