loopctl-mcp-server 2.74.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",
@@ -4665,7 +4694,12 @@ const TOOLS = [
       "trustworthy answer plus its provenance rather than a ranked list to triage yourself; " +
       "use knowledge_search when you want to browse/enumerate matches. Additive — existing " +
       "knowledge tools are unchanged. If semantic ranking is unavailable it degrades to " +
-      "keyword-only (meta.fallback/fallback_reason), same as knowledge_search.",
+      "keyword-only (meta.fallback/fallback_reason), same as knowledge_search.\n\n" +
+      "TODAY THE CURATED BRANCH IS UNREACHABLE ON THIS DEPLOYMENT: a source counts as " +
+      "curated only if its article has curated_at set, and no article does — so every " +
+      "call returns provenance 'retrieved' and a null curated_article_id. Read a " +
+      "'retrieved' verdict as the normal case, not as evidence that a curated answer " +
+      "was considered and rejected. This line comes out when something actually curates.",
     inputSchema: {
       type: "object",
       properties: {
@@ -5656,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:
@@ -5674,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 " +
@@ -6493,7 +6593,40 @@ const TOOLS = [
       "search_follow_through carries two further biases pointing OPPOSITE ways: the 20-row " +
       "recording cap hides opens of results ranked beyond it (DOWN on large pages), while " +
       "one open credits EVERY search in the window that surfaced that article, not just the " +
-      "preceding one (UP when an agent refines and re-searches).",
+      "preceding one (UP when an agent refines and re-searches).\n\n" +
+      "Exact attribution (unit: READS — not surfaced results, not calls): attributed_opens " +
+      "/ cross_key_opens / direct_opens count READ rows by how their originating search was " +
+      "established, resolved server-side at write time and never accepted from a caller. " +
+      "Not comparable with followed_through, which counts SURFACED RESULTS later opened. " +
+      "cross_key_opens is the population followed_through cannot see: it correlates on " +
+      "api_key_id, and the injected recall hook searches under a different key from the " +
+      "session that reads, so that channel scores a structural ZERO there — meaning " +
+      "UNMEASURABLE, not unread. Cross-key attribution is circumstantial (two agents in one " +
+      "tenant can reach one article independently), hence labelled rather than folded in. " +
+      "direct_opens is the agent going straight to an article by link or cited id, which " +
+      "used to look identical to 'surfaced and ignored' — close to its opposite.\n\n" +
+      "Disposition (unit: SEARCH CALLS): searches_scored_with_follow_through, " +
+      "searches_reformulated and searches_quiet PARTITION searches_scored — NOT searches. " +
+      "Treating every not-opened search as a failure is wrong — an agent answered by the " +
+      "result snippet correctly opens nothing, and that is a success. A reformulation (the " +
+      "SAME SESSION issuing a later search call with a DIFFERENT QUERY in-window, nothing " +
+      "opened) is the closest thing to an unambiguous failure, so it is split out; what " +
+      "remains is `quiet` and is STILL a mixture of 'snippet sufficed' and 'rows ignored'. " +
+      "This surface does not separate them — do not read quiet as either.\n\n" +
+      "searches_scored is SMALLER than searches and the gap is NOT quiet traffic. A search " +
+      "is scoreable only if it carries a session identity (stamped forward-looking, so a " +
+      "pre-migration row reports searches_scored: 0) and comes from a channel that can " +
+      "react to a result at all — the recall hook and the session-start auto-query emit one " +
+      "distilled query per prompt and never see what came back, so they cannot reformulate " +
+      "by construction. They stay in every other denominator here, precision included. " +
+      "Read searches - searches_scored as n/a, never as zero.\n\n" +
+      "COMPARE ROWS ONLY WITHIN A metric_version. Every row carries the version of the " +
+      "definition set that produced it. Three changes have already altered what a figure here " +
+      "MEANS — searched went from search calls to surfaced results, infrastructure traffic " +
+      "began being excluded, and the disposition trio was rescoped — each forward-looking and " +
+      "each previously leaving no mark on the row, so a series read across one of those " +
+      "boundaries compares definitions rather than days. 0 means the row predates the stamp " +
+      "and its definitions are unknown.",
     inputSchema: {
       type: "object",
       properties: {
@@ -6515,8 +6648,15 @@ const TOOLS = [
   {
     name: "knowledge_analytics_top",
     description:
-      "Return the top accessed knowledge articles for the tenant. " +
-      "Use to identify which articles agents actually read. Requires orchestrator role.",
+      "Return the top READ knowledge articles for the tenant — articles whose body was " +
+      "actually delivered (get/context/drill). Requires orchestrator role.\n\n" +
+      "access_type DEFAULTS TO READS, not to every event. `search` and `index` rows are " +
+      "IMPRESSIONS the ranker produced — one per surfaced result — and they outnumber reads " +
+      "roughly 50:1, so the old unfiltered default ranked ranker output while claiming to " +
+      "show what agents read. Pass access_type:'all' if you genuinely want impressions " +
+      "counted, or a single type to select one. unique_keys counts distinct API KEYS, not " +
+      "agents: v2 mints one ephemeral key per dispatch, so one agent dispatched N times is " +
+      "N keys.",
     inputSchema: {
       type: "object",
       properties: {
@@ -6549,8 +6689,12 @@ const TOOLS = [
   {
     name: "knowledge_article_stats",
     description:
-      "Return per-article usage statistics: total accesses, unique agents, " +
-      "by-type breakdown, and the 10 most recent events. Requires orchestrator role.",
+      "Return per-article usage statistics: total_events (impressions included), " +
+      "total_reads (bodies actually delivered — get/context/drill), unique_keys, a by-type " +
+      "breakdown, and the 10 most recent events. Requires orchestrator role.\n\n" +
+      "Read total_reads, not total_events, when you want usage: impressions outnumber reads " +
+      "roughly 50:1. unique_keys counts distinct API KEYS rather than agents — v2 mints one " +
+      "ephemeral key per dispatch.",
     inputSchema: {
       type: "object",
       properties: {
@@ -6565,7 +6709,8 @@ const TOOLS = [
   {
     name: "knowledge_agent_usage",
     description:
-      "Return knowledge usage for an agent: total reads, unique articles, top read articles. " +
+      "Return knowledge usage for an agent: total_reads (bodies actually delivered), " +
+      "total_events (impressions included), unique articles, top read articles. " +
       "Pass api_key_id (api_keys.id credential) OR agent_id (agents.id logical identity) — not both. " +
       "Requires orchestrator role.",
     inputSchema: {
@@ -6600,8 +6745,11 @@ const TOOLS = [
   {
     name: "knowledge_unused_articles",
     description:
-      "Return published articles that have not been accessed in the configured " +
-      "time window. Use to identify dead-weight knowledge. Requires orchestrator role.",
+      "Return published articles that have not been READ in the configured time window. " +
+      "Use to identify dead-weight knowledge. Requires orchestrator role.\n\n" +
+      "\"Not read\" means no get/context/drill. It deliberately does NOT mean \"no event\": " +
+      "on that definition an article the ranker surfaces constantly and nobody ever opens " +
+      "counted as USED, which made this blind to the largest class of dead weight there is.",
     inputSchema: {
       type: "object",
       properties: {
@@ -7350,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.74.0",
+  "version": "2.76.0",
   "description": "MCP server for loopctl \u2014 structural trust for AI development loops",
   "type": "module",
   "main": "index.js",