@sporhq/spor 0.20.1 → 0.21.0

package/.claude-plugin/plugin.json

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

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "spor",
-  "version": "0.20.1",
+  "version": "0.21.0",
   "description": "Maintains a typed, versioned knowledge graph and compiles compact briefings from it: session-start injection, per-prompt relevance digests, capture at discovery, end-of-session distillation, decision queue.",
   "author": {
     "name": "Spor",

package/API.md

@@ -206,6 +206,24 @@ 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>`.
 
+### `set_readiness`
+
+Micro-mutation, the agent-readiness manual override
+(dec-spor-agent-readiness-derived-classification), a verbatim sibling of
+`set_priority` above. Input `{ "id": "<node>", "readiness": "<value>" }`,
+where `<value>` is `agent` (the ONE hand-settable value of the otherwise
+structurally-derived `agent|human|untriaged` classification `rankQueue`
+computes) or a clearing form (`none`/`clear`/`""`) to demote the item back off
+agent-ready. There is no hand-settable `readiness: human` — human is always
+derived structurally (`requires: human`, `assigned → person`, held-task state,
+an open neighborhood question) and always wins over the stamp, so a later
+human-signal edit still flips a stamped item back. Output `{ "status":
+"updated", "id", "revision", "warnings" }`; an unknown value is `invalid_node`
+with the allowed value in `details`. Like `set_priority` it is a server-side
+read-modify-write — no client revision round-trip — and it stamps
+`readiness_by` (acting identity), `readiness_at`, and `readiness_via` (the
+door). The CLI wrapper is `spor ready <id> [--needs-input]`.
+
 ### `reserve`
 
 The fifth task-lease action (dec-cc-task-resumption-reservation), alongside
@@ -512,6 +530,7 @@ endpoint is the REST twin of a core call:
 | `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}/readiness` `{readiness}` | `spor ready`, triage make-ready pass | `set_readiness` semantics (§1): one-scalar agent-readiness override — `agent` or a clearing form (`none`/`clear`/`""`) to demote back to derived. No hand-settable `human` value (always structurally derived, always wins). Server-side read-modify-write (no revision), stamping `readiness_by`/`readiness_at`/`readiness_via`. Unknown value → `invalid_node` with the allowed value |
 | `POST /v1/nodes/{id}/claim` `{session?}` | `claim`/`set_status` MCP tools, `spor claim` CLI, `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 claim` and `spor dispatch` do, 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 renew` CLI, `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}/extend` `{ms, session?}` | `extend` MCP tool, `spor extend` CLI | manually stretch your live lease by `ms` milliseconds for a known long idle gap → `{ok, status, lease, capped_to_max?, claim_ttl_max_ms?}`. Bounded by the tenant's `claim_ttl_max` policy (a request past the ceiling caps to it, flagged `capped_to_max`); never shortens a lease. `ms` must be a positive number (`spor extend <id> <2h|45m|…>` parses the human duration client-side). A lapsed/stolen lease is `409 lease_lost` naming the holder |
@@ -531,6 +550,7 @@ endpoint is the REST twin of a core call:
 | `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 |
+| `POST /v1/merge` `{nodes: [...], mode?: "plan"\|"apply", id_map?: {...}, trust_attached_code?: bool, force?: bool}` | admin promoting one graph into another — pilot-to-org, or a local dogfood graph into a hosted tenant | bring another graph's exported node files (`nodes`: an array of raw node markdown strings) into this one without the failure mode of the naive `GET /v1/export \| POST /v1/nodes --if-exists skip` — silently DROPPING every colliding node while imported edges that pointed at it re-bind to this graph's unrelated same-named node (ordinal id schemes like `cap-<date>-<n>` collide across any two independently started graphs). **Admin-gated** (stewards→root, else `403 forbidden`): `mode:"apply"` writes through the same trusted bulk-import door the server uses internally, which preserves each incoming node's original attribution (a merge moves history, it does not re-author it) and skips the `transitions()`/policy gates (content validation still runs per node; create-only, one deferred commit). Every incoming node classifies as **imported** (id unknown here), **deduped** (id collides, content identical — attribution-blind, this graph's copy wins), **remapped** (id collides, content differs, and the id's final dash-segment is all-digits/*ordinal* — rewritten to `<id>-<sha256(content)[:7]>`, with every reference to the old id across the incoming batch rewritten to match), or **conflict** (id collides with different content and a *semantic* id; a `person` node's email already bound to a different id; or a `schema`/`workflow`/`workflow-run` node or a `stewards`-to-this-graph's-root edge — none of these ever merge silently). Conflicts are reported for manual triage and never written; the schema/workflow class is the one skippable via `trust_attached_code: true` (only for a whole graph you own). `mode:"plan"` (the default) runs the same classification and validation and returns the report without writing anything; `mode:"apply"` **refuses with `409 conflict`** (nothing written) whenever the plan still carries conflicts or validation errors, unless `force: true` — which imports the clean subset and knowingly leaves any reference to a skipped id unresolved. `id_map` (`{"old-id": "new-id"}`) seeds cross-id rewrites; feed a plan's own `id_map` back into the next request when a graph is too large for one batch (plan every batch first to build the complete map, then apply each). Response: `{mode, counts: {incoming, imported, deduped, remapped, conflicts, errors}, imported, deduped, remapped, conflicts, errors, id_map, results?, generated_at}` — `imported`/`deduped`/`remapped`/`conflicts` are arrays of `{id, new_id?, title?, reason?}`; `errors` is `{id, index?, errors: [...]}` (unparseable/invalid entries); `results` (apply mode only) carries the import door's per-entry write verdicts. Deterministic and idempotent — re-running an identical merge dedups everything the first run imported, safe after a partial failure. Called directly today (bearer admin token + `curl`); a CLI wrapper defaulting to plan mode is tracked separately (task-spor-cli-merge-verb) |
 | `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) |
 | `GET /v1/admin/tokens` | offboarding / audit; `spor admin token list` (= `spor token list --all`) | list PATs → `{tokens: [{hash_prefix, person, name, email, created, expires, expired}], count}` — never plaintext, never full hashes. Admin-only (§4). The team-wide view; the caller's own PATs are the self-serve `GET /v1/me/tokens` above |
 | `POST /v1/admin/tokens` `{person, expires?}` | onboarding; `spor invite` | mint a PAT bound to an existing person node (`expires` is `<N>d` or an ISO date) → 201 `{token, hash_prefix, person, name, email, expires}`; the plaintext `token` is returned **once**. Admin-only. Binds someone *else* (onboarding); the self-serve mint is `POST /v1/me/tokens` above |

package/GRAPH.md

@@ -75,9 +75,11 @@ Rules:
   `- {type: assigned, to: agent-X, profile: profile-Y}` — preserved on the edge
   object (the per-assignment profile override; see "The agent orchestration
   layer"). Plain `{type, to}` edges are unchanged.
-- `commits` is an optional inline list of repo-qualified git shas
-  (`commits: [wf@1a2b3c4d, ...]`, kebab-case repo slug + 7–40 hex) linking
-  the node to the code commits that implement it (task-cc-commit-linking).
+- `commits` is an optional list of repo-qualified git shas (kebab-case repo
+  slug + 7–40 hex), inline (`commits: [wf@1a2b3c4d, ...]`) or as a YAML block
+  list (`commits:` followed by indented `- wf@1a2b3c4d` lines — both forms
+  parse to the same array), linking the node to the code commits that
+  implement it (task-cc-commit-linking).
   Commits are not nodes — a node-per-commit would mirror `git log` and drown
   the curated graph; the field plus the `Spor: <node-id>`
   commit-message trailer give both directions (node→commit here, commit→node

package/QUEUE.md

@@ -528,6 +528,43 @@ 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.
 
+**Agent-readiness** (dec-spor-agent-readiness-derived-classification). Each
+ranked item carries a **derived** classification `readiness:
+agent|human|untriaged` (plus `readiness_reasons[]`), computed structurally in
+the render pass — no LLM (the `queueSignals` hook can only add numbers to
+score), no graph state (a status overloads the lifecycle vocab; an edge has no
+natural target). It answers "can a coding agent complete this unattended, or
+does a human have to act first?" Derivation, **human wins over agent** so a
+later open question or `requires: human` edit flips a stamped item back:
+- **human** — `requires:` includes `human` (the first consumer of the
+  risk-class register, §schema-requires: work unsatisfiable by any agent) · an
+  `assigned → person` edge (it is that person's work) · held-task state (the
+  front self-limit's `suggest: triage`) · the item is itself an open question
+  or unprocessed capture · an open (live, unanswered) question node in its
+  1-hop neighborhood (a soft spec gap to close first).
+- **agent** — an explicit `readiness: agent` frontmatter stamp with
+  `readiness_by` provenance (mirroring `priority`/`priority_by`, the one
+  hand-set piece — a make-ready stamp verb + REST twin, slice 2) · or an
+  `assigned → agent` edge.
+- **untriaged** otherwise — the deliberate third bucket ("nobody has checked
+  the spec"), which rides **no** readiness fields, so the item is
+  byte-identical when no readiness data exists.
+
+Readiness leads the why-line when decisive (`agent-ready: …` / `needs human:
+…`), and the envelope gains `counts_by_readiness` ({agent, human, untriaged},
+present only when there is readiness signal or a readiness facet was asked
+for) — the headline "how much of my queue can an agent take right now?" A
+**readiness filter** (`rankQueue({readiness})`, a class or array; today on the
+kernel opt and the local CLI's `--readiness`, comma-separated — the `GET
+/v1/queue?readiness=` param, `show_queue {readiness}`, and remote `spor next
+--readiness` forwarding land with the server render-surfaces slice,
+task-spor-queue-readiness-render-surfaces) narrows the queue to a class as a
+hard scope like `project`/`type` (schema-approval items, outside the
+classification, are excluded). A graph with no readiness data is byte-identical to before — no
+fields, no clause, no count. Hard triage gaps recorded during a make-ready pass
+become explicit `blocks` edges (which correctly remove the item until
+answered); readiness handles the soft/derived side.
+
 **Per-person queues** (task-cc-queue-assignee-filtering). `rankQueue`'s
 `assignee` parameter — and `GET /v1/queue?assignee=<person-id>` /
 `show_queue {assignee}` (use `assignee=me` to bind to the caller) — scopes the