@sporhq/spor 0.18.0 → 0.18.1

package/.claude-plugin/plugin.json

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

package/API.md

@@ -402,7 +402,7 @@ endpoint is the REST twin of a core call:
 | `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 |
 | `GET /v1/nodes/{id}/history?limit=N` | `spor history <id>`, the `node_history` MCP tool | per-node commit lineage — a `git log` projection over `nodes/{id}.md` → `{id, head, count, history: [{sha, short, actor, actor_name, actor_email, date, message, internal, person}]}`, newest first. Each revision is labeled `internal:true` for a server-internal write (boot reconcile / migration, `server@spor.invalid`) vs. a real actor, and mapped to its `person` node by author email. Deliberately NOT `git log --follow` (node files share heavy frontmatter boilerplate, so similarity-based rename detection crosses node boundaries — dec-spor-node-history-git-log-projection). `limit` defaults to 50, max 200. The frontmatter `author` re-stamps to the LAST editor on every write, so this is the only durable record of the full chain of editors. A node with no commit history (unknown id) is `404`; a bad id is `422`. The `spor history <id>` CLI verb is the shell front-door (remote reads this; local mode runs the same projection over the graph home) |
 | `GET /v1/nodes/{id}/history/{sha}` | `spor history <id> <sha>`, `node_history` (sha mode) | one revision's detail, the expensive half gated behind an explicit per-sha fetch → the history record for that commit plus `{change, patch, content}`: the change type (`A`/`M`/`D`/`R`), the patch this commit introduced to the node file, and the full node content at that revision (`null` when the commit deleted it). The `sha` must be one from the node's own history — a sha that didn't touch the node, or an unresolvable sha, is `404`; a malformed sha is `422` |
-| `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. Entries are applied **sequentially** and each is fully validated before the next — including the completion-resolver gate that runs on create (GRAPH.md "the resolver gate") — so a born-terminal node (`done` task / `resolved` issue) must have its resolving `decision`/`artifact` EARLIER in the same batch (**resolver-first ordering**; the batch does not defer the gate to end-of-batch, dec-spor-batch-create-gate-resolver-first-ordering). The 207 is partial-success: entries already applied before a later entry's failure are not rolled back |
+| `POST /v1/nodes` | `spor put-node`, 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. Entries are applied **sequentially** and each is fully validated before the next — including the completion-resolver gate that runs on create (GRAPH.md "the resolver gate") — so a born-terminal node (`done` task / `resolved` issue) must have its resolving `decision`/`artifact` EARLIER in the same batch (**resolver-first ordering**; the batch does not defer the gate to end-of-batch, dec-spor-batch-create-gate-resolver-first-ordering). The 207 is partial-success: entries already applied before a later entry's failure are not rolled back |
 | `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) |

package/bin/spor.js

@@ -747,6 +747,191 @@ function gitBlobSha(buf) {
   return h.digest("hex");
 }
 
+// --- spor put-node: full validated node writes -----------------------------
+// The shell twin of MCP put_node / REST POST /v1/nodes: write a complete node
+// markdown file (frontmatter + body) through the same create/update collision
+// policy instead of dropping to raw REST from scripts and skills.
+function readPutNodeInput(input) {
+  if (!input || input === "-") {
+    try {
+      return { raw: fs.readFileSync(0, "utf8"), label: "stdin" };
+    } catch (e) {
+      return { error: `could not read stdin: ${e.message}` };
+    }
+  }
+  try {
+    return { raw: fs.readFileSync(input, "utf8"), label: input };
+  } catch (e) {
+    return { error: `could not read ${input}: ${e.message}` };
+  }
+}
+
+function parsePutNode(raw, label) {
+  const graphLib = require(path.join(ROOT, "lib", "graph.js"));
+  let first;
+  try {
+    first = graphLib.parseFrontmatter(raw, label || "incoming.md");
+  } catch (e) {
+    return { error: `invalid node: ${e.message}` };
+  }
+  if (!first.id) return { error: "invalid node: missing id" };
+  if (!NODE_ID_RE.test(first.id)) return { error: `bad node id '${first.id}' — expected kebab-case` };
+  try {
+    return { node: graphLib.parseFrontmatter(raw, `${first.id}.md`) };
+  } catch (e) {
+    return { error: `invalid node: ${e.message}` };
+  }
+}
+
+function normalizeIfExists(raw) {
+  const value = raw == null ? "error" : String(raw).trim().toLowerCase();
+  if (["error", "skip", "update"].includes(value)) return { ok: true, value };
+  return { ok: false, error: `--if-exists must be one of: error, skip, update` };
+}
+
+function renderPutNodeResult(res, json) {
+  if (json) {
+    out(JSON.stringify(res || {}, null, 2));
+    return;
+  }
+  const status = (res && res.status) || "ok";
+  const id = res && res.id ? res.id : "(unknown)";
+  const rev = res && res.revision ? ` @ ${res.revision}` : "";
+  out(status === "skipped" ? `put-node skipped: ${id}${rev}` : `put-node ${status}: ${id}${rev}`);
+  for (const w of (res && res.warnings) || []) err(`  warning: ${w}`);
+}
+
+function putNodeEntryError(res0, httpStatus, prefix = "put-node") {
+  const parts = [];
+  if (res0 && res0.message) parts.push(res0.message);
+  if (res0 && res0.code && !parts.includes(res0.code)) parts.push(res0.code);
+  if (res0 && Array.isArray(res0.details)) parts.push(...res0.details);
+  if (res0 && res0.revision) parts.push(`current revision: ${res0.revision}`);
+  return `${prefix} error ${httpStatus}${parts.length ? `: ${parts.join("; ")}` : ""}`;
+}
+
+function copyNodeFilesForValidation(srcNodes, dstNodes, targetId, raw) {
+  fs.mkdirSync(dstNodes, { recursive: true });
+  for (const ent of fs.readdirSync(srcNodes, { withFileTypes: true })) {
+    if (!ent.isFile() || !ent.name.endsWith(".md")) continue;
+    if (ent.name === `${targetId}.md`) continue;
+    fs.copyFileSync(path.join(srcNodes, ent.name), path.join(dstNodes, ent.name));
+  }
+  fs.writeFileSync(path.join(dstNodes, `${targetId}.md`), raw);
+}
+
+function validatePutNodeLocal(nodesDir, node, raw) {
+  const graphLib = require(path.join(ROOT, "lib", "graph.js"));
+  let g;
+  try {
+    g = graphLib.loadGraph(nodesDir);
+  } catch (e) {
+    return { error: `could not load graph: ${e.message}` };
+  }
+  const v = graphLib.validateNode(g, node);
+  if (!v.ok) return { error: `invalid node:\n  ${v.errors.join("\n  ")}` };
+
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "spor-put-node-"));
+  const tmpNodes = path.join(tmp, "nodes");
+  try {
+    copyNodeFilesForValidation(nodesDir, tmpNodes, node.id, raw);
+    const vg = graphLib.validateGraph(tmpNodes);
+    if (vg.errors && vg.errors.length) return { error: `invalid graph after put-node:\n  ${vg.errors.join("\n  ")}` };
+    return { ok: true, warnings: vg.warnings || [] };
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+async function cmdPutNode(cfg, { values, positionals }) {
+  const input = positionals[0] || "-";
+  const ifExists = normalizeIfExists(values["if-exists"]);
+  if (!ifExists.ok) {
+    err(ifExists.error);
+    return 1;
+  }
+  const policy = ifExists.value;
+  const revision = values.revision || null;
+  if (policy === "update" && !revision) {
+    err("put-node update requires --revision from 'spor get <id> --json'");
+    return 1;
+  }
+  if (policy !== "update" && revision) {
+    err("--revision is only valid with --if-exists update");
+    return 1;
+  }
+
+  const inputRes = readPutNodeInput(input);
+  if (inputRes.error) {
+    err(inputRes.error);
+    return 1;
+  }
+  const raw = inputRes.raw;
+  const parsed = parsePutNode(raw, inputRes.label);
+  if (parsed.error) {
+    err(parsed.error);
+    return 1;
+  }
+  const id = parsed.node.id;
+
+  if (cfg.mode() === "remote") {
+    const entry = { node: raw, if_exists: policy };
+    if (revision) entry.revision = revision;
+    const r = await remote.post(cfg, "/v1/nodes", { nodes: [entry] }, { timeoutMs: 15000 });
+    if (r.transport) {
+      err(`offline — could not reach server (${r.error})`);
+      return 1;
+    }
+    const res0 = r.json && r.json.results && r.json.results[0];
+    if (!(res0 && res0.ok)) {
+      const top = r.json && r.json.error;
+      if (top && !res0) err(`put-node error ${r.status}${top.message ? `: ${top.message}` : ""}`);
+      else err(putNodeEntryError(res0, r.status));
+      return 1;
+    }
+    renderPutNodeResult(res0, !!values.json);
+    return 0;
+  }
+
+  const nodesDir = cfg.nodesDir();
+  if (!fs.existsSync(nodesDir)) {
+    err(`no graph at ${nodesDir} — run 'spor init' first`);
+    return 1;
+  }
+  const file = path.join(nodesDir, `${id}.md`);
+  const exists = fs.existsSync(file);
+  if (policy === "error" && exists) {
+    err(`node already exists: ${id} (use --if-exists update with --revision, or --if-exists skip)`);
+    return 1;
+  }
+  if (policy === "skip" && exists) {
+    const res = { ok: true, status: "skipped", id, revision: gitBlobSha(fs.readFileSync(file)), warnings: [] };
+    renderPutNodeResult(res, !!values.json);
+    return 0;
+  }
+  if (policy === "update") {
+    if (!exists) {
+      err(`no such node: ${id}`);
+      return 1;
+    }
+    const current = gitBlobSha(fs.readFileSync(file));
+    if (current !== revision) {
+      err(`put-node conflict: stale revision for ${id}; current revision: ${current}`);
+      return 1;
+    }
+  }
+
+  const valid = validatePutNodeLocal(nodesDir, parsed.node, raw);
+  if (valid.error) {
+    err(valid.error);
+    return 1;
+  }
+  fs.writeFileSync(file, raw);
+  const res = { ok: true, status: exists ? "updated" : "created", id, revision: gitBlobSha(Buffer.from(raw)), warnings: valid.warnings || [] };
+  renderPutNodeResult(res, !!values.json);
+  return 0;
+}
+
 // --- spor blame / commits: commit-sha -> nodes reverse lookup ---------------
 // (task-spor-blame-commit-lookup-cli-verb) The shell verb over the commit->node
 // reverse index: which decisions/tasks/issues reference a git commit in their
@@ -7777,6 +7962,34 @@ const COMMANDS = {
     examples: ["spor get dec-cc-zero-dep-client", "spor get dec-cc-zero-dep-client --json"],
     run: (cfg, p) => cmdGet(cfg, p),
   },
+  "put-node": {
+    group: "Graph", parse: "strict", args: "[<file>|-]",
+    summary: "write a full node markdown file (local validated write; remote: /v1/nodes)",
+    help:
+      "Create, skip, or update one complete node markdown file (frontmatter + body)\n" +
+      "through the same validated full-node write path as MCP put_node / REST\n" +
+      "POST /v1/nodes. With no file, or with '-', reads the node markdown from stdin.\n\n" +
+      "Collision policy is explicit: --if-exists error (default) rejects an existing\n" +
+      "id, --if-exists skip no-ops on collision, and --if-exists update replaces an\n" +
+      "existing node only when --revision matches the blob SHA you read earlier.\n" +
+      "Get that revision with 'spor get <id> --json'; re-read and retry on conflict.\n\n" +
+      "Remote mode sends one-entry batch put_node to /v1/nodes, so server attribution,\n" +
+      "schema transition gates, edge normalization, and validation all apply. Local\n" +
+      "mode writes nodes/<id>.md after parsing and validating the candidate against a\n" +
+      "temporary graph view, so a malformed full node never lands on disk.",
+    options: {
+      "if-exists": { type: "string", value: "error|skip|update", desc: "collision policy (default: error)" },
+      revision: { type: "string", value: "sha", desc: "required with --if-exists update; from 'spor get <id> --json'" },
+      json: { type: "boolean", desc: "machine-readable result envelope" },
+    },
+    examples: [
+      "spor put-node ./nodes/dec-x.md",
+      "spor get dec-x --json",
+      "spor put-node ./dec-x.md --if-exists update --revision <blob-sha>",
+      "cat ./task-new.md | spor put-node --if-exists error",
+    ],
+    run: (cfg, p) => cmdPutNode(cfg, p),
+  },
   blame: {
     group: "Graph", parse: "strict", args: "<sha> [--repo <slug>]", aliases: ["commits"],
     summary: "which nodes reference a commit (local: graph scan; remote: /v1/commits/<sha>)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sporhq/spor",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "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/skills/spor/SKILL.md

@@ -80,6 +80,9 @@ rest are mode-specific (`spor status` confirms which mode you're in):
 spor status                    # resolved mode, graph, project, identity, health
 spor next [--project <slug>]   # the ranked decision queue — "what's next"
 spor get <id>                  # one node by id
+spor put-node [<file>|-] --if-exists <error|skip|update> [--revision <sha>]
+                               # write a full node markdown file through validated put_node semantics;
+                               # use `spor get <id> --json` first and pass its revision for updates
 spor blame <sha> [--repo <s>]  # which nodes reference a git commit (alias: spor commits <sha>)
 spor history <id> [<sha>]      # a node's commit lineage (actor/when/what); <sha> = that revision's diff (local git log / GET /v1/nodes/<id>/history)
 spor schema [<type>]           # introspect the live registry (types/prefixes/weights/flags/gates,
@@ -161,6 +164,13 @@ A few of these have enough surface to be worth a sentence:
   read from git content history, never `updated_at`
   (dec-spor-git-derived-timestamps). `--project`/`--type`/`--weeks`/`--json`
   scope and shape it.
+- **`spor put-node`** is the shell twin of MCP `put_node` / REST `POST
+  /v1/nodes`: pass a complete node markdown file, or `-`/stdin. Default
+  `--if-exists error` rejects collisions; `--if-exists skip` no-ops on an
+  existing id; `--if-exists update` requires the `revision` from `spor get <id>
+  --json` so updates are optimistic-concurrency checked instead of last-writer
+  wins. Prefer `spor edge`/`spor set-status` for narrow mutations; use
+  `put-node` for full-node artifacts such as briefing versions or body edits.
 - **`spor compile`/`spor brief`** are mode-aware: local runs the in-repo
   compiler, remote dispatches to the server (this is what `/spor:brief` pulls).
   In local mode add `--project <repo-slug>` to scope to a repo — without it

package/skills/triage/SKILL.md

@@ -148,7 +148,43 @@ referenced prior-art artifact no longer trips this; a genuine non-resolving work
 product still does. The one thing triage must not do is leave the flag with no
 decision — it's a question addressed to you.
 
-## 5. Latent dependencies → record missing `blocks` edges
+## 5. Stale briefing findings → recompile the briefing
+
+Gardener findings about briefing freshness are not ordinary "close?" chores.
+If a finding says a `brief-*` node is stale, missing `derived-from`
+provenance, has an input-fingerprint mismatch, or has source-set drift, the
+repair is a new briefing version with current provenance. Do not merely
+acknowledge the finding or mark it handled while the stale briefing remains in
+place — that leaves session-start serving bad context.
+
+Treat the affected briefing as a build artifact and rebuild it:
+
+- Read the finding and the affected `brief-*` node (`spor get <finding-id>` and
+  `spor get <brief-id>`). Check its `compiled-for`, `derived-from`, and
+  `shaped-by` edges so you know what it was meant to brief and which
+  corrections must still apply.
+- Compile/research the current source set for the briefing target. For a
+  root/node briefing, run `spor brief <target-id>` for the human body; in a local
+  graph, `spor compile --root <target-id> --skeleton` can produce the updated
+  provenance skeleton. For a standing project briefing, compile the current
+  repo/product context and honor every standing correction named by `shaped-by`.
+- Write the affected `brief-*` node as the next `version:` with the refreshed
+  body, exact current `derived-from` inputs, preserved `compiled-for`, and any
+  relevant `shaped-by` correction edges. Use `spor put-node <file> --if-exists
+  update --revision <sha>` (or MCP `put_node`) so the update is validated and
+  optimistic-concurrency checked.
+- Verify the condition clears, or is ready for the gardener to auto-resolve:
+  re-read the briefing and, when appropriate, run `spor admin gardener --json`
+  to confirm the stale-briefing finding is no longer filed.
+- Only after the repaired briefing exists should the finding be considered
+  handled. If the finding still fires, keep it open and report what source or
+  correction is still unresolved.
+
+This is intentionally more work than closing a stale anchor: stale briefing
+findings affect future agent context, so triage must leave a fresh `brief-*`
+artifact behind.
+
+## 6. Latent dependencies → record missing `blocks` edges
 
 Find tasks that should carry a `blocks`/`blocked-by` edge but don't — work the
 queue surfaces as actionable that actually can't start until something else
@@ -174,7 +210,7 @@ Record a confirmed one as a `blocks` edge from the prerequisite to the dependent
 (mirroring how an issue records its block). The dependent then leaves the
 actionable queue until its blocker resolves — which is the point.
 
-## 6. Open questions → brief the lineage, then answer
+## 7. Open questions → brief the lineage, then answer
 
 This is where triage earns its keep: the queue's `questions` are decisions
 waiting on a human, and a bare list of them is useless — the reader can't answer
@@ -200,7 +236,7 @@ decide.** For each open question:
 (If `questions` is empty there's nothing to do here — but it's the step most
 often forgotten, so check it every pass.)
 
-## 7. Prioritise → unblockers first
+## 8. Prioritise → unblockers first
 
 Once you understand the dependency shape, set explicit `priority:` (`p1`/`p2`/
 `p3`) so the queue sequences correctly. The highest-leverage move is to **bump
@@ -224,7 +260,7 @@ genuinely ready work, start/claim it or let `front` decay; don't fake a resolver
 to undo it. (A bare reference no longer trips this —
 `issue-spor-queue-held-guard-false-positive-referenced-outcome`.)
 
-## 8. Present the outcome
+## 9. Present the outcome
 
 Talk to a human, in plain language. Lead with what you did and what to pick up
 next, one short reason each. Give a compact before/after (queue size, what
@@ -246,11 +282,11 @@ the REST endpoint against the resolved server; in Cowork use the MCP tool. See
 | Set priority | `spor priority <id> <p1\|p2\|p3\|clear>` (or `POST /v1/nodes/<id>/priority {priority}`) | `set_priority` |
 | Set status (merged/rejected/resolved/…) | `spor set-status <id> <status>` (or `POST /v1/nodes/<id>/status {status}`) | `set_status` |
 | Add edge (supersedes/blocks/relates-to/answers) | `spor edge <id> <type> <to>` (or `POST /v1/nodes/<id>/edges {type, to}`) | `add_edge` |
-| Edit a field (body) | `POST /v1/nodes {nodes:[{node, if_exists:"update", revision}]}` | `put_node` |
+| Edit a field (body) | `spor put-node <file> --if-exists update --revision <sha>` (or `POST /v1/nodes {nodes:[{node, if_exists:"update", revision}]}`) | `put_node` |
 | Compile a question's lineage | `spor brief <id>` | `query_graph root_id=<id>` |
 
 Edges normalize/flip/dedupe server-side, so write a `blocks` from the
-prerequisite's perspective and let it record the inverse. `put_node` needs
+prerequisite's perspective and let it record the inverse. `spor put-node` / `put_node` needs
 `if_exists:"update"` **and** the current `revision` — without the explicit mode
 it skips an existing node. Status flips run through the schema `transitions()`
 gate (and terminal closes through the completion-resolver gate), so a denied