loopctl-mcp-server 2.75.0 → 2.76.0

package/README.md

@@ -264,8 +264,9 @@ Epic 39 Repo Coordination Bus — a lightweight, tenant-isolated channel for age
 | `knowledge_distant_pairs` | Distant-but-bridgeable article pairs in the optimal-novelty embedding band (cosine distance, default 0.3–0.7) — the creative sweet spot. Sampled from **agent's visible published articles**; agent callers see only their own and `shared` articles. `bridge_path: true` requires a ≤2-hop link path. Returns `{a, b, distance}` pairs, paginated. Optional: `min_distance`, `max_distance`, `bridge_path`, `limit` (default 20, max 100), `offset`. |
 | `knowledge_novelty` | Score ideas by novelty: embeds each idea's text, returns `novelty_score` = cosine distance to the nearest **visible** prior proposal (0 = identical, higher = more novel, up to 2.0; `null` when the idea text is blank, no visible priors exist, or embedding fails — see `meta.prior_count`). Agent callers see only their own and `shared` articles as priors. Priors default to articles tagged `proposal`. Provide ideas as `texts` (strings) OR `ideas` (strings or objects), ≤50. Optional: `prior_tag`. |
 | `knowledge_random_walk` | Random walk through the link graph from `start_id` (no cycles, up to `length` nodes), traversing only **agent's visible published articles**, surfacing unexpected connections. Agent callers see only their own and `shared` articles. Returns `{id, title, category}` in walk order. Required: `start_id`. Optional: `length` (default 4, max 25). |
-| `knowledge_conflicts` | List potential-conflict article pairs — published articles flagged "too similar to comfortably coexist" by the auto-linker / nightly lint sweep, highest-overlap first. The KB only FLAGS the pair; it does NOT decide redundancy-vs-contradiction — that's your call with live context. Each entry has both articles (id/title/status/category) + similarity. Then merge (supersede one, `knowledge_create` the merged article, or PATCH) or reconcile if they genuinely disagree. Paginated with `total_count` in meta. Agent role. Optional: `limit` (default 50, max 1000, clamped), `offset`. |
-| `knowledge_resolve_conflict` | Record YOUR verdict on a potential-conflict pair (from `knowledge_conflicts`). Dispositions: `dismiss` (false positive, drops from queue), `supersede` (one wins — pass `authoritative_article_id`; nightly executor links + retires loser, only at `confidence:"high"`, reversible/audited), `merge` (at high confidence an LLM synthesizes both into ONE new DRAFT, sources preserved, never auto-published). Non-destructive at agent role — you record intent, the privileged nightly job executes. Last-write-wins per pair. **`supersede` is the one disposition that retires an article unattended**, so its `confidence` is capped server-side: an agent-role `"high"` is recorded as `"medium"` (`data.requested_confidence` + `note` say so) and the pair stays in `knowledge_conflicts` until an orchestrator+ key records it at high; a `high` supersede also REQUIRES `evidence` (422 without it). `merge` is never capped. Required: `source_article_id`, `target_article_id`, `disposition`. Optional: `authoritative_article_id`, `classification`, `evidence` (required for a high supersede), `confidence`. |
+| `knowledge_conflicts` | List potential-conflict article pairs — published articles flagged "too similar to comfortably coexist" by the auto-linker / nightly lint sweep, highest-overlap first. The KB only FLAGS the pair; it does NOT decide redundancy-vs-contradiction — that's your call with live context. Each entry has both articles (id/title/status/category) + similarity. Then merge (supersede one, `knowledge_create` the merged article, or PATCH) or reconcile if they genuinely disagree. Paginated with `total_count` in meta. Agent role. Optional: `limit` (default 50, max 1000, clamped), `offset`, `origin` (`system` or `asserted` — asserted rows lead the default ordering, so pass `system` to review machine-flagged pairs alone). |
+| `knowledge_assert_conflict` | **ASSERT** a conflict between two articles the system never flagged — the way to contest an article you just deliberately refuted. `knowledge_resolve_conflict` only reaches pairs the AUTO-LINKER flagged by similarity, which is exactly wrong for a correction: the pair is minutes old (the nightly linker has not run) and a good correction argues about the CONCLUSION, so it may never be similar enough to be flagged at all. The pair then appears in `knowledge_conflicts` with `origin: "asserted"` and your claim attached, and in both articles' `potential_conflicts`. **It retires, hides and down-ranks nothing**, and does not remove either article from curated answers (that still needs a system flag). **And you cannot judge your own assertion** — `knowledge_resolve_conflict` returns `409 self_asserted_conflict` to the asserting key, because you named both ids; another key decides. Idempotent per pair (`created: false` on a re-assert; never overwrites a system flag's provenance). Agent role. Required: `source_article_id`, `target_article_id`, `evidence`. Optional: `classification`, `proposed_authoritative_article_id`. |
+| `knowledge_resolve_conflict` | Record YOUR verdict on a potential-conflict pair (from `knowledge_conflicts`). Dispositions: `dismiss` (false positive, drops from queue), `supersede` (one wins — pass `authoritative_article_id`; nightly executor links + retires loser, only at `confidence:"high"`, reversible/audited), `merge` (at high confidence an LLM synthesizes both into ONE new DRAFT, sources preserved, never auto-published). Non-destructive at agent role — you record intent, the privileged nightly job executes. Only pairs with a real flag are reachable; for a pair that was never flagged, use `knowledge_assert_conflict` first — and note that a DIFFERENT key must then record the verdict. Last-write-wins per pair. **`supersede` is the one disposition that retires an article unattended**, so its `confidence` is capped server-side: an agent-role `"high"` is recorded as `"medium"` (`data.requested_confidence` + `note` say so) and the pair stays in `knowledge_conflicts` until an orchestrator+ key records it at high; a `high` supersede also REQUIRES `evidence` (422 without it). `merge` is never capped. Sent on `LOOPCTL_AGENT_KEY`, so a pair YOU asserted answers `409 self_asserted_conflict` here by design — another principal (a second session, an orchestrator, a human operator) records that verdict. Required: `source_article_id`, `target_article_id`, `disposition`. Optional: `authoritative_article_id`, `classification`, `evidence` (required for a high supersede), `confidence`. |
 | `knowledge_create` | Create a new knowledge article. File findings, document patterns, or record decisions. **Published immediately by default** (visible per `metadata.visibility` — default `owner` for agent authors, only visible to that agent; `shared` for visibility to all agents) — the response `note` says which outcome occurred. Pass `draft: true` to stage it for later review instead (publish afterwards with `knowledge_publish`). Pass `metadata: {visibility: "shared"}` to make the article visible to other agents; higher roles can set visibility and agent_id explicitly. Pass `idempotency_key` for idempotent capture (re-creating with the same key is a no-op returning the existing article — no partial duplicates). RESERVED TAG NAMESPACE: a tag starting with `idem-` must be `idem-<family>-<digest>` (digest = 12 or 40 lowercase hex chars, e.g. `idem-url-7ebe1ca33431`) or the write is rejected 422 — never silently rewritten; put topics outside that prefix and use `idempotency_key` for idempotent capture. Optional: `category`, `tags`, `project_id`, `draft`, `idempotency_key`, `source_type`, `source_id`, `metadata`. |
 | `knowledge_update` | Edit an EXISTING article IN PLACE, **preserving its ID** (IDs are load-bearing — cited in project CLAUDE.mds and cross-links). Fold in a new fact, tidy a hub, retag, or reclassify without churning a new row. Send only the fields to change; `tags` REPLACES the whole array. A changed body/tags re-triggers embedding + auto-linking. Agent role — KB-content curation (non-destructive + audited; the in-place edit overwrites the prior body, so it is not reversible either); visibility-scoped, so another agent's private/owner memory 404s. The reserved `idem-` tag namespace applies here too (see `knowledge_create`). Required: `article_id`. Optional: `title`, `body`, `category`, `tags`, `metadata`. |
 | `knowledge_okf_export` | **Requires `LOOPCTL_USER_KEY`.** Export the wiki as a portable OKF (Open Knowledge Format) v0.1 bundle of markdown files. Writes to `out_dir`, or returns `{files, meta}` inline. |

package/index.js

@@ -2062,6 +2062,26 @@ async function knowledgeConflicts({ limit, offset }) {
   return toContent(result);
 }
 
+async function knowledgeAssertConflict({
+  source_article_id,
+  target_article_id,
+  classification,
+  evidence,
+  proposed_authoritative_article_id,
+}) {
+  const payload = { source_article_id, target_article_id, evidence };
+  if (classification) payload.classification = classification;
+  if (proposed_authoritative_article_id)
+    payload.proposed_authoritative_article_id = proposed_authoritative_article_id;
+  const result = await apiCall(
+    "POST",
+    "/api/v1/knowledge/conflicts",
+    payload,
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  return toContent(result);
+}
+
 async function knowledgeResolveConflict({
   source_article_id,
   target_article_id,
@@ -2076,6 +2096,15 @@ async function knowledgeResolveConflict({
   if (classification) payload.classification = classification;
   if (evidence) payload.evidence = evidence;
   if (confidence) payload.confidence = confidence;
+  // #730: the AGENT key, the same one every other knowledge_* verb sends. It must NOT
+  // reach for LOOPCTL_ORCH_KEY to get past a 409 self_asserted_conflict: that 409 is the
+  // separation working, and clearing it by handing this process a second, higher-privileged
+  // key is the workaround this repo forbids outright ("the MCP server must NEVER hold both
+  // implementer and reviewer keys in the same process"). It would also lift the #331
+  // supersede confidence cap and the agent visibility scope on EVERY verdict, not just on
+  // an asserted pair — an agent-role "high" supersede would stop being capped to "medium"
+  // and the nightly executor would retire the loser unattended. A pair you asserted is
+  // judged by a DIFFERENT key: another session, an orchestrator, or a human operator.
   const result = await apiCall(
     "POST",
     "/api/v1/knowledge/conflicts/resolve",
@@ -5661,6 +5690,65 @@ const TOOLS = [
       required: [],
     },
   },
+  {
+    name: "knowledge_assert_conflict",
+    description:
+      "ASSERT a conflict between two articles the system never flagged — the way to contest " +
+      "an article you have just deliberately refuted. knowledge_resolve_conflict only " +
+      "reaches pairs the AUTO-LINKER flagged by similarity, which is exactly wrong for a " +
+      "correction: your pair is minutes old (the nightly linker has not run), and a good " +
+      "correction argues about the CONCLUSION so it may never be similar enough to be " +
+      "flagged at all. Use this the moment you write an article that contradicts an " +
+      "existing one — do not settle for a 'SUPERSEDED' banner in the loser's body, which " +
+      "changes no ranking and is invisible to any caller reading snippets. " +
+      "`evidence` is REQUIRED: an assertion carries no similarity score, so your argument " +
+      "IS what the reviewer judges. " +
+      "WHAT THIS DOES: the pair appears in knowledge_conflicts with origin \"asserted\" and " +
+      "your claim attached, and in both articles' potential_conflicts. " +
+      "WHAT IT DOES NOT DO: it does not retire, hide, or down-rank either article, and it " +
+      "does not remove either from curated answers (that still needs a system flag). AND " +
+      "YOU CANNOT JUDGE YOUR OWN ASSERTION — knowledge_resolve_conflict returns 409 " +
+      "self_asserted_conflict to the key that asserted the pair, because you named both " +
+      "ids and a party that arranges a pair does not also certify the verdict on it. " +
+      "Another key (a human, an orchestrator, a later session) decides. " +
+      "Idempotent per pair: re-asserting returns the existing flag (created: false) and " +
+      "never overwrites a system flag's provenance. Agent role.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        source_article_id: {
+          type: "string",
+          description: "One article of the pair (UUID). Order does not matter.",
+        },
+        target_article_id: {
+          type: "string",
+          description: "The other article of the pair (UUID).",
+        },
+        classification: {
+          type: "string",
+          enum: ["redundant", "complementary", "contradictory"],
+          description:
+            "What kind of conflict you are asserting: redundant (same claim twice), " +
+            "complementary (same topic, different facets), or contradictory (cannot both " +
+            "be true — the usual reason to assert).",
+        },
+        evidence: {
+          type: "string",
+          description:
+            "REQUIRED. Why these two conflict, ideally the ground truth that settles it " +
+            "(commit, file:line, URL, measurement, observed behavior). This travels with " +
+            "the pair in knowledge_conflicts and is what the deciding key reads.",
+        },
+        proposed_authoritative_article_id: {
+          type: "string",
+          description:
+            "Optional: which of the two you believe should win. Recorded as your CLAIM on " +
+            "the queue row — it applies nothing and is not a verdict.",
+        },
+      },
+      required: ["source_article_id", "target_article_id", "evidence"],
+    },
+  },
   {
     name: "knowledge_resolve_conflict",
     description:
@@ -5679,6 +5767,13 @@ const TOOLS = [
       "recorded as \"medium\" (see data.requested_confidence and note in the response) and " +
       "the pair STAYS in knowledge_conflicts until an orchestrator+ key records it at high. " +
       "'merge' is never capped and executes normally at agent role. " +
+      "Only pairs with a real flag are reachable here — if the pair you want was never " +
+      "flagged (you just wrote an article refuting another), assert it first with " +
+      "knowledge_assert_conflict; a DIFFERENT PRINCIPAL then records the verdict, since the " +
+      "asserter of a pair may not judge it (409 self_asserted_conflict). This tool sends " +
+      "LOOPCTL_AGENT_KEY, so a pair YOU asserted answers 409 here by design — hand it to " +
+      "another session, an orchestrator, or a human operator rather than reaching for a " +
+      "higher-privileged key. " +
       "Last-write-wins per pair, so re-recording with fresher ground truth overrides. " +
       "Resolve only conflicts material to your current task; adjudicate against the actual " +
       "system, and if you can't tell which is right, LEAVE IT UNRECORDED rather than " +
@@ -7403,6 +7498,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "knowledge_conflicts":
       return await knowledgeConflicts(args);
 
+    case "knowledge_assert_conflict":
+      return await knowledgeAssertConflict(args);
+
     case "knowledge_resolve_conflict":
       return await knowledgeResolveConflict(args);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopctl-mcp-server",
-  "version": "2.75.0",
+  "version": "2.76.0",
   "description": "MCP server for loopctl \u2014 structural trust for AI development loops",
   "type": "module",
   "main": "index.js",