@sporhq/spor 0.2.6 → 0.2.8

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

package/API.md

@@ -251,7 +251,8 @@ endpoint is the REST twin of a core call:
 | `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 |
 | `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. Accepts `?token=<PAT>` on this route only (browser links can't carry an Authorization header; the request log records the pathname, never the query) |
+| `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 | 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 |
 | `GET /v1/export` | bootstrap/offline | 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 |
 | `GET /v1/admin/tokens` | offboarding / audit | list PATs → `{tokens: [{hash_prefix, person, name, email, created, expires, expired}], count}` — never plaintext, never full hashes. Admin-only (§4) |
 | `POST /v1/admin/tokens` `{person, expires?}` | onboarding | 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 |
@@ -310,6 +311,14 @@ anything with a token.
   `{name, email}` attribution record. Access tokens are `spor_oat_…` (30d;
   legacy `sub_oat_…` accepted); refresh tokens are `spor_ort_…` (90d,
   rotating, single-use). Authorization codes are single-use, 10-minute.
+- **Render tickets (shared lens links).** `POST /v1/lens/{id}/ticket` (§3)
+  mints a signed, expiring, **read-only** ticket carrying `{lens_id,
+  sharer_person_id, exp}` — the credential a *shared* view link carries instead
+  of the sharer's PAT. It binds `$viewer` to the recorded sharer (rendered with
+  a "Viewing as" banner), is honored only on `GET /v1/lens/{id}/render`, and can
+  never authorize a write. Stateless (HMAC over a server-held key — no
+  revocation list, expiry is the bound); per-recipient/revocable grants are a
+  later fine-grained-authz refinement.
 
 Unauthenticated MCP calls are hard-rejected — there is no anonymous author.
 

package/GRAPH.md

@@ -88,7 +88,7 @@ Rules:
 | task       | `task-`   | active or planned work (status `open`/`active`/`done`/`abandoned`, gated; `done` requires a `decision`/`artifact` resolver — see below) |
 | issue      | `issue-`  | a defect/finding and its resolution lineage (queueable: open issues join the decision queue; status `open`/`active`/`resolved`, gated; `resolved` requires a `decision`/`artifact` resolver — see below) |
 | incident   | `inc-`    | something that went wrong in operation (queueable: live incidents join the decision queue) |
-| artifact   | `spec-`, `art-` | a document, spec, module, or build product worth referencing |
+| artifact   | `spec-`, `art-` | a document, spec, module, or build product worth referencing; when it represents a change it may carry an optional delivery-stage status `in-review`/`approved`/`merged`/`released` — see below |
 | norm       | `norm-`   | a standing convention or constraint (rides along in every project-relevant compile) |
 | briefing   | `brief-`  | a compiled briefing (output of this system; never traversed) |
 | correction | `corr-`   | standing fix to a briefing: pin/exclude/guidance (never traversed) |
@@ -112,6 +112,30 @@ either satisfies the gate. `abandoned` (task) is exempt: won't-do work produces
 nothing to record. The gate runs at write time on UPDATE only (the create path
 is ungated); it is backward-readable, so existing terminal nodes are untouched.
 
+The resolver must also be in a **resolving** state, not merely present
+(dec-spor-definition-of-done-org-policy). Completion bundled three axes —
+*recorded* (a why exists), *reviewed*, and *delivered* — and a resolver that is
+a change still in review has not delivered. So:
+
+- An `artifact` representing a change may carry a delivery-stage status:
+  `in-review`/`approved` are **non-resolving** (they keep the resolved target
+  live); `merged`/`released`, and any other/empty status, are **resolving**.
+  Plus flat scalar metadata the regex frontmatter parser already supports —
+  `delivery_ref` (PR url/commit/tag), `delivery_source` (e.g. `github`),
+  `size`, `labels`, `paths` (comma-scalars). The shape is source-blind, so a
+  GitHub reflection adapter and a native Spor review surface write the same
+  thing. Who may assert `merged`/`released` (the self-approval trust seam) is
+  later-stage policy, not a write gate here.
+- The read-time truth (`resolutionMap`) and the write-time `done`-gate both read
+  this **resolving-status partition off `graph.registry`** — never a hardcoded
+  table. The partition is the union of each node-schema's `status.non_resolving`
+  list; the seed declares `decision: [rejected]`, `task: [abandoned]`,
+  `artifact: [in-review, approved]`, reproducing the prior behavior
+  byte-identically. An org or team retunes the bar by editing a schema node, no
+  code change. A resolver with no delivery stage (the common case) resolves
+  exactly as before, so a change still in review keeps its task live without any
+  hand-managed `open` status.
+
 ## Norm ride-along
 
 A `norm` node (any `always_on` type) rides along on every compile — but the

package/README.md

@@ -24,21 +24,8 @@ Requires Node 20+ and nothing else — the client is zero-dependency. To run
 from a checkout instead (e.g. to hack on it), clone the repo and `npm link`
 from its root; that symlinks the same two commands onto your PATH.
 
-Then create the graph home (this is yours, kept outside any code repo):
-
-```bash
-spor init        # creates ~/.spor/nodes, git-inits it, writes .gitignore
-```
-
-`spor init` is idempotent. `spor status` then tells you the resolved mode,
-graph, project, and (in remote mode) server health and identity — run it any
-time you're unsure whether Spor is active or which graph you're on. (Without
-the `spor` CLI on your PATH the equivalent is
-`mkdir -p ~/.spor/nodes && git -C ~/.spor init && printf 'journal/\n' > ~/.spor/.gitignore`.)
-
-Then install for your agent. One verb wires up any supported host — it
-resolves the adapter manifest to this checkout and drops it into the host's
-config:
+Wire Spor into your agent. One verb resolves the adapter manifest to this
+install and drops it into the host's config:
 
 ```bash
 spor install claude     # Claude Code (via its plugin CLI — no marketplace browsing)
@@ -50,27 +37,33 @@ spor install            # no host => list the hosts detected on this machine
 per-repo config. `--all` installs every detected host, `--print` is a dry run,
 and `--server <url> --token <tok>` also points the client at a team graph in
 the same step. Re-running is idempotent — it refreshes the path and never
-duplicates your other hooks.
+duplicates your other hooks. (In Claude Code you can also install by hand:
+`/plugin marketplace add sporhq/spor` then `/plugin install spor@spor`.)
 
-In Claude Code you can still install from the marketplace by hand if you
-prefer:
+Then onboard a repo — one command, from inside it:
 
+```bash
+cd ~/my-repo && spor dispatch --backfill
 ```
-/plugin marketplace add sporhq/spor
-/plugin install spor@spor
-```
+
+That does the whole setup in one step: creates your graph home if it doesn't
+exist yet (`~/.spor/nodes`, git-initialised), registers the repo so Spor knows
+where it lives on this machine, makes sure Spor is enabled for it, and launches
+the `/spor:backfill` agent in a Claude Code background session — it mines git
+history, design docs, and issue trackers (edges first) and proposes how to
+group your repos into projects. Watch or attach to it with `claude agents`.
+Re-run it whenever you add a repo, or skip it entirely and just work —
+distillation grows the graph one session at a time.
+
+`spor status` tells you the resolved mode, graph, project, and (on a team
+graph) server health and identity — run it any time you're unsure whether Spor
+is active or which graph you're on. `spor init` does the graph-home setup on
+its own if you'd rather not dispatch anything yet.
 
 For the per-host event mapping, fidelity notes, distiller backend, and the
 `AGENTS.md` fallback for hosts with no hook support, see
 [adapters/](adapters/).
 
-To start with a populated graph, run `/spor:backfill` — the onboarding door. It
-dispatches the heavy mining (git history, design docs, issue trackers, edges
-first) to the bundled `spor-backfill` **subagent**, which runs in its own
-context, and then proposes how to group your repos into projects (re-run it as
-you add repos). Or skip it and just work — distillation grows the graph one
-session at a time.
-
 ## Dispatching background agents
 
 `spor dispatch` hands a task to Claude Code's background-agent machinery

package/bin/spor.js

@@ -101,7 +101,10 @@ function nodeCount(nodesDir) {
   }
 }
 
-function cmdInit(cfg) {
+// Idempotently create the local graph home (nodes/, git, .gitignore). Returns
+// { home, nodesDir, created } and prints nothing — callers do their own UX.
+// Shared by `spor init` and the `spor dispatch --backfill` onboarding path.
+function ensureGraphHome(cfg) {
   const home = cfg.graphHome();
   const nodesDir = path.join(home, "nodes");
   let created = false;
@@ -122,6 +125,11 @@ function cmdInit(cfg) {
       /* non-fatal */
     }
   }
+  return { home, nodesDir, created };
+}
+
+function cmdInit(cfg) {
+  const { home, nodesDir, created } = ensureGraphHome(cfg);
   out(`${created ? "Created" : "Graph already present at"} ${home}`);
   out(`  nodes:  ${nodesDir} (${nodeCount(nodesDir) ?? 0} nodes)`);
   out(`  mode:   ${cfg.mode()}`);
@@ -1004,6 +1012,45 @@ function shellQuote(s) {
   return /[^\w./:-]/.test(s) ? `'${String(s).replace(/'/g, "'\\''")}'` : s;
 }
 
+// Re-enable Spor for a repo by merging { enabled: true } into its committable
+// .spor.json (and clearing a `mode: off`, which also disables). Used by the
+// --backfill onboarding to repair a repo a prior `spor disable` turned off.
+function enableRepoAt(dir) {
+  const file = path.join(dir, ".spor.json");
+  let data = {};
+  try {
+    data = JSON.parse(fs.readFileSync(file, "utf8")) || {};
+  } catch {
+    /* absent or malformed — start fresh */
+  }
+  data.enabled = true;
+  if (data.mode === "off") delete data.mode;
+  try {
+    fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n");
+  } catch {
+    /* non-fatal */
+  }
+}
+
+// `spor dispatch --backfill` is the onboarding door (task-spor-cli-dispatch-
+// background-agents): set the repo up before launching its backfill agent.
+// Idempotent; prints what it did. The dir-registration happens in cmdDispatch
+// (it applies to every dispatch), this adds the init + enable steps.
+function onboardRepo(cfg, dir) {
+  // Init the local graph home — but only in local mode; remote mode keeps the
+  // graph on the server, so there is nothing to create locally.
+  if (cfg.mode() !== "remote") {
+    const r = ensureGraphHome(cfg);
+    out(r.created ? `initialized graph home at ${r.home}` : `graph home ready: ${r.home}`);
+  }
+  // Re-enable the repo if a prior `spor disable` turned it off, so onboarding a
+  // disabled repo actually works instead of silently launching into a no-op.
+  if (!cfg.enabled()) {
+    enableRepoAt(dir);
+    out(`re-enabled Spor for ${dir}`);
+  }
+}
+
 async function cmdDispatch(cfg, args) {
   const dryRun = args.includes("--print") || args.includes("--dry-run");
   const full = args.includes("--full");
@@ -1089,9 +1136,6 @@ async function cmdDispatch(cfg, args) {
     err(`target dir does not exist: ${res.dir}`);
     return 1;
   }
-  // Learn the mapping from this CLI use too.
-  u.registerRepo(cfg.graphHome(), res.slug, res.dir);
-
   const prompt = brief
     ? `# Spor briefing (compiled for this task — your standing context)\n\n${brief}\n\n---\n\n# Task\n\n${instruction}\n`
     : instruction;
@@ -1106,12 +1150,26 @@ async function cmdDispatch(cfg, args) {
 
   if (dryRun) {
     out(`dir:    ${res.dir}  (slug: ${res.slug}, via ${res.source})`);
+    if (backfill) {
+      const steps = [];
+      if (cfg.mode() !== "remote") steps.push(fs.existsSync(cfg.nodesDir()) ? "graph home ready" : "init graph home");
+      steps.push(`register ${res.slug} → ${res.dir}`);
+      if (!cfg.enabled()) steps.push("re-enable repo (currently disabled)");
+      out(`onboard: ${steps.join("; ")}`);
+    }
     out(`brief:  ${brief ? `${brief.length} bytes` : "(none — graph had nothing relevant, or --no-brief/--backfill)"}`);
     out(`run:    ${claudeBin} ${claudeArgs.slice(0, -1).map(shellQuote).join(" ")} <prompt>`);
     out(`\n--- prompt ---\n${prompt}`);
     return 0;
   }
 
+  // Side effects (real run only — --print writes nothing). --backfill is the
+  // onboarding door, so it sets the repo up (init + enable) first; every
+  // dispatch self-registers the dir it resolved.
+  if (backfill) onboardRepo(cfg, res.dir);
+  u.registerRepo(cfg.graphHome(), res.slug, res.dir);
+  if (backfill) out(`registered ${res.slug} → ${res.dir}; launching the backfill agent…`);
+
   if (claudeBin === "claude" && !hasCmd("claude")) {
     err("claude CLI not on PATH — install Claude Code, then re-run (or 'spor dispatch … --print' to see the prompt).");
     return 1;

package/lib/kernel/registry.js

@@ -167,6 +167,21 @@ function parseSchemaNode(node) {
         const p = Array.isArray(payload.prefix) ? payload.prefix : [payload.prefix];
         if (!p.length || p.some((x) => typeof x !== "string" || !x)) errors.push(`prefix must be a non-empty string or array of strings`);
       }
+      // status disposition (dec-spor-definition-of-done-org-policy): the
+      // resolving-status partition the kernel reads off the registry instead of
+      // a hardcoded table. `non_resolving` lists the statuses in which a node of
+      // this type, acting as a RESOLVER, does NOT retire its targets (a withdrawn
+      // decision, an in-review change). Optional; unlisted statuses resolve.
+      if (payload.status != null) {
+        if (typeof payload.status !== "object" || Array.isArray(payload.status)) {
+          errors.push(`status must be an object`);
+        } else if (payload.status.non_resolving != null) {
+          const nr = payload.status.non_resolving;
+          if (!Array.isArray(nr) || nr.some((x) => typeof x !== "string" || !x)) {
+            errors.push(`status.non_resolving must be an array of non-empty strings`);
+          }
+        }
+      }
     } else if (node.kind === "queue-policy") {
       // Singleton: the registry holds at most one (graph beats seed, higher
       // version wins). The blend lives in attached code — a `rank` export is
@@ -336,6 +351,29 @@ class Registry {
     return !!(s && s.payload.queueable === true);
   }
 
+  // Resolution partition (dec-spor-definition-of-done-org-policy): the set of
+  // statuses in which a node, acting as a RESOLVER, does NOT retire its targets.
+  // Unioned across every node-schema's `status.non_resolving` (type-blind, like
+  // the hardcoded NON_RESOLVING set it replaces in resolution.js). Lowercased.
+  // The kernel reads this off graph.registry instead of owning a table; an org
+  // reconfigures the bar by editing a schema node, no code change. Seed
+  // assignments reproduce the old {rejected, abandoned} set byte-identically.
+  nonResolvingStatuses() {
+    const out = new Set();
+    for (const s of this.nodeSchemas.values()) {
+      const nr = s.payload.status && s.payload.status.non_resolving;
+      if (Array.isArray(nr)) for (const v of nr) if (typeof v === "string" && v) out.add(v.toLowerCase());
+    }
+    return out;
+  }
+
+  // A resolver in this status retires its targets (the read-time completion
+  // truth). Empty/unlisted statuses resolve; only declared non-resolving
+  // statuses (withdrawn decisions, in-review changes) keep the target live.
+  isResolvingStatus(status) {
+    return !this.nonResolvingStatuses().has((status || "").toLowerCase());
+  }
+
   // ---- snapshots (back-compat exports in graph.js are derived from these) ----
 
   edgeWeights() {

package/lib/kernel/resolution.js

@@ -28,15 +28,24 @@ const TERMINAL = new Set([
   "done", "resolved", "superseded", "rejected", "closed", "completed", "abandoned", "answered",
   "merged", // a triaged capture-pending: its content now lives in proper nodes
 ]);
-const NON_RESOLVING = new Set(["rejected", "abandoned"]);
+// Fallback resolving partition, used ONLY when a graph carries no registry
+// (hand-built test graphs). The live partition is read off graph.registry
+// (dec-spor-definition-of-done-org-policy): resolution.js no longer owns the
+// table — it is compiled from each node-schema's `status.non_resolving`, and
+// the seed reproduces this exact set byte-identically. The kernel never learns
+// the words delivery/merged/in-review; it checks status against the partition.
+const FALLBACK_NON_RESOLVING = new Set(["rejected", "abandoned"]);
 
 const isTerminalStatus = (s) => TERMINAL.has((s || "").toLowerCase());
 
 function resolutionMap(graph) {
   const out = {};
+  const nonResolving = graph.registry && typeof graph.registry.nonResolvingStatuses === "function"
+    ? graph.registry.nonResolvingStatuses()
+    : FALLBACK_NON_RESOLVING;
   for (const r of Object.values(graph.nodes)) {
     if (graph.supersededBy[r.id]) continue;
-    if (NON_RESOLVING.has((r.status || "").toLowerCase())) continue;
+    if (nonResolving.has((r.status || "").toLowerCase())) continue;
     for (const e of r.edges ?? []) {
       if (e.type !== "resolves" && e.type !== "answers") continue;
       const target = graph.nodes[e.to];

package/lib/seed/schema-artifact.md

@@ -2,9 +2,9 @@
 id: schema-artifact
 type: schema
 kind: node-schema
-schema_version: 2026.06.10.2
+schema_version: 2026.06.15.1
 title: Seed schema for artifact nodes
-summary: Node schema for the artifact type — a document, spec, module, or build product worth referencing. Seed-pack mirror of the GRAPH.md ontology; a graph-resident schema node for this type overrides it.
+summary: Node schema for the artifact type — a document, spec, module, or build product worth referencing, optionally carrying a delivery-stage status when it represents a change. Seed-pack mirror of the GRAPH.md ontology; a graph-resident schema node for this type overrides it.
 date: 2026-06-10
 ---
 
@@ -12,6 +12,42 @@ Seed schema for the `artifact` node type, shipped with the plugin as a
 registry default (QUEUE.md §2). A `type: schema` node in the graph with
 `kind: node-schema` and the same `node_type` overrides this entry.
 
+Delivery-stage vocab (2026.06.15.1, dec-spor-definition-of-done-org-policy):
+an artifact that represents a *change* (a PR, a branch, a release) — rather than
+a static doc or spec — may carry an OPTIONAL delivery-stage `status`:
+
+| status      | resolving? | meaning                                            |
+|-------------|------------|----------------------------------------------------|
+| `in-review` | no         | change submitted, under review — keeps its task live |
+| `approved`  | no         | reviewed and approved, not yet landed — task still live |
+| `merged`    | yes        | landed on the default branch — retires its task    |
+| `released`  | yes        | shipped/released                                   |
+
+The non-resolving stages are declared in `status.non_resolving`, the artifact's
+half of the resolving partition the kernel reads off `graph.registry`: a
+resolver in `in-review`/`approved` does not retire its targets, so a task whose
+only resolver is a change still in review stays live (this is what dissolves the
+overnight-review smell — no `open` status to hand-manage). `merged`/`released`
+and any unlisted/empty status resolve, so existing artifacts (no delivery stage)
+are unaffected and the seed is byte-identical with the prior hardcoded set.
+
+The stage is one half of a **source-blind** resolver contract (so a GitHub
+reflection adapter and a native Spor review surface write the same shape). The
+other half is flat scalar frontmatter the regex parser already supports — no
+inline-list generalization:
+
+- `delivery_ref` — the change's address (PR url, commit sha, tag).
+- `delivery_source` — where it lives (e.g. `github`, `spor`).
+- `size`, `labels`, `paths` — diff metadata as comma-scalars
+  (`paths: lib/x.js, lib/y.js`).
+
+The kernel never reads these keys; it reads `status` against the partition only.
+The **trust seam** — *who* may assert `merged`/`released` (the self-approval
+floor: an author cannot land their own change) — is policy that lands in a later
+stage (the policy kind + the reflection adapter), not here. There is no status
+gate on this type: the stages are optional recognized values, and an artifact
+remains free to be a plain doc with no status.
+
 ```json
 {
   "node_type": "artifact",
@@ -19,6 +55,20 @@ registry default (QUEUE.md §2). A `type: schema` node in the graph with
   "prefix": [
     "spec-",
     "art-"
-  ]
+  ],
+  "status": {
+    "non_resolving": [
+      "in-review",
+      "approved"
+    ]
+  },
+  "display": {
+    "statuses": {
+      "in-review": "active",
+      "approved": "active",
+      "merged": "positive",
+      "released": "positive"
+    }
+  }
 }
 ```

package/lib/seed/schema-decision.md

@@ -2,7 +2,7 @@
 id: schema-decision
 type: schema
 kind: node-schema
-schema_version: 2026.06.13.1
+schema_version: 2026.06.15.1
 title: Seed schema for decision nodes
 summary: Node schema for the decision type — a choice that was made, with the why. Seed-pack mirror of the GRAPH.md ontology; a graph-resident schema node for this type overrides it.
 date: 2026-06-10
@@ -19,13 +19,25 @@ queue-terminal values are not shadowed by synonyms
 approach is filed (the distiller writes it, prompts/client/distill-local.md).
 Write-time gate, backward-readable, no upgrade chain.
 
+`status.non_resolving` (2026.06.15.1): a `rejected` decision — a recorded-then-
+declined choice — resolves nothing, so as a resolver it does not retire its
+targets. This is the registry-declared half of the resolving partition the
+kernel reads off `graph.registry` (dec-spor-definition-of-done-org-policy);
+resolution.js no longer hardcodes the `{rejected, abandoned}` set. Registry
+behavior only, no node-shape change, backward-readable, no upgrade chain.
+
 ```json
 {
   "node_type": "decision",
   "description": "a choice that was made, with the why",
   "prefix": [
     "dec-"
-  ]
+  ],
+  "status": {
+    "non_resolving": [
+      "rejected"
+    ]
+  }
 }
 ```
 

package/lib/seed/schema-task.md

@@ -2,7 +2,7 @@
 id: schema-task
 type: schema
 kind: node-schema
-schema_version: 2026.06.14.1
+schema_version: 2026.06.15.1
 title: Seed schema for task nodes
 summary: Node schema for the task type — active or planned work. Seed-pack mirror of the GRAPH.md ontology; a graph-resident schema node for this type overrides it.
 date: 2026-06-10
@@ -25,6 +25,18 @@ node surfaces in the neighborhood. `abandoned` (won't do) is exempt; nothing
 was produced to record. Both are write-time gates, backward-readable (no
 stored-shape change; existing `done` tasks are untouched), no upgrade chain.
 
+`transitions()` + `status` (2026.06.15.1, dec-spor-definition-of-done-org-policy):
+the completion gate tightens — `done` requires the inbound resolver to be in a
+*resolving* state, not merely present. The host supplies the registry's
+resolving partition on the view as `non_resolving_statuses` (the same
+`status.non_resolving` the kernel's `resolutionMap` reads), and the gate counts a
+decision/artifact resolver only when its status is not named there. So a human
+cannot hand-flip `done` past an in-review change — the write-time mirror of the
+read-time retirement rule. `status.non_resolving: [abandoned]` declares the
+type's half of the partition: an abandoned task resolves nothing. Absent the
+partition on the view (an older server) every resolver counts exactly as before,
+so the gate is backward-readable with no node-shape change and no upgrade chain.
+
 ```json
 {
   "node_type": "task",
@@ -32,7 +44,12 @@ stored-shape change; existing `done` tasks are untouched), no upgrade chain.
   "prefix": [
     "task-"
   ],
-  "queueable": true
+  "queueable": true,
+  "status": {
+    "non_resolving": [
+      "abandoned"
+    ]
+  }
 }
 ```
 
@@ -55,22 +72,32 @@ export function transitions(current, proposed, view) {
     };
   }
   // (2) completion must record a durable outcome on the graph: a decision or
-  // artifact that resolves this task (task-cc-terminal-status-requires-resolver).
-  // `abandoned` is exempt. view.resolvers = live inbound resolves/answers edges
-  // with their source type.
+  // artifact that resolves this task (task-cc-terminal-status-requires-resolver),
+  // AND that resolver must be in a RESOLVING state — not an in-review change
+  // (dec-spor-definition-of-done-org-policy). `abandoned` is exempt.
+  // view.resolvers = live inbound resolves/answers edges with their source type
+  // and status; view.non_resolving_statuses = the registry's resolving partition
+  // the host supplies (the same status.non_resolving the kernel's resolutionMap
+  // reads). A resolver counts unless its status is named non-resolving, so an
+  // older host that omits the partition behaves exactly as before
+  // (backward-readable).
   if (next === "done") {
     const rs = (view && view.resolvers) || [];
+    const nonResolving = (view && view.non_resolving_statuses) || [];
     let ok = false;
     for (let i = 0; i < rs.length; i++) {
-      if (rs[i].type === "decision" || rs[i].type === "artifact") { ok = true; break; }
+      const isChange = rs[i].type === "decision" || rs[i].type === "artifact";
+      const st = ((rs[i] && rs[i].status) || "").toLowerCase();
+      if (isChange && nonResolving.indexOf(st) === -1) { ok = true; break; }
     }
     if (!ok) {
       return {
         allow: false,
-        reason: "done requires a decision or artifact node that resolves this " +
-          "task (an inbound resolves edge) — record the outcome on the graph, " +
-          "even a few lines like a commit message, so it surfaces in the " +
-          "neighborhood; or set abandoned if it won't be done. " +
+        reason: "done requires a decision or artifact node in a RESOLVING state " +
+          "that resolves this task (an inbound resolves edge) — record the " +
+          "outcome on the graph, even a few lines like a commit message, so it " +
+          "surfaces in the neighborhood; a change still in review keeps the task " +
+          "live until it lands. Or set abandoned if it won't be done. " +
           "(task-cc-terminal-status-requires-resolver)",
       };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sporhq/spor",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "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/session-start.js

@@ -272,17 +272,35 @@ ${body}`;
   }
 
   // -------------------------------------------------------------------------
-  // LOCAL MODE (original behavior — byte-identical to session-start.sh)
+  // LOCAL MODE (original behavior — byte-identical to session-start.sh, except
+  // the empty/absent-graph onboarding line below)
   // -------------------------------------------------------------------------
-  if (!fs.existsSync(nodes)) return null;
-
   let files = [];
   try {
     files = fs.readdirSync(nodes).filter((f) => f.endsWith(".md"));
   } catch {
-    return null;
+    /* no nodes/ dir yet (fresh/onboarding home) or unreadable — count stays 0 */
   }
   const count = files.length;
+
+  // Empty or absent local graph — the onboarding moment, e.g. right after
+  // `spor dispatch --backfill` inits the home (it creates an empty nodes/ dir)
+  // or a fresh `spor init`. Remote mode always emits a status line here ("no
+  // standing briefing for <slug> yet"); local mode used to return null (no dir)
+  // or claim "0 nodes active" (empty dir), so the SessionStart hook looked like
+  // it never ran during onboarding — the parity gap reported when SessionStart
+  // appeared dead for `claude --bg` (it fires; source=startup). Emit the parity
+  // line so onboarding is visibly underway and points at the bootstrap path
+  // (issue-cc-local-mode-session-start-empty-graph-fallback). Side effects above
+  // (registerRepo, plugin-root) already ran; the repo-identity write below is
+  // gated on projCount>0, so nothing else is skipped by returning early here.
+  if (count === 0) {
+    return envelope(
+      `No Spor briefing for ${slug} yet — the local graph at ${nodes} is empty. ` +
+        `Bootstrap this repo with /spor:backfill (or 'spor dispatch --backfill'); ` +
+        `knowledge you capture lands here as you work. ${USAGE_LOCAL}`
+    );
+  }
   // Repo identity (task-cc-project-identity-nodes): a resident `type: repo`
   // node (renamed from the former `type: project`,
   // dec-cc-repo-project-two-layer-identity) whose `slugs:` register (or id)