loopctl-mcp-server 2.68.0 → 2.70.0

package/README.md

@@ -266,8 +266,8 @@ Epic 39 Repo Coordination Bus — a lightweight, tenant-isolated channel for age
 | `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. Required: `source_article_id`, `target_article_id`, `disposition`. Optional: `authoritative_article_id`, `classification`, `evidence`, `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). 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 (reversible + audited); visibility-scoped, so another agent's private/owner memory 404s. Required: `article_id`. Optional: `title`, `body`, `category`, `tags`, `metadata`. |
+| `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 (reversible + audited); 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. |
 | `knowledge_okf_import` | **Requires `LOOPCTL_USER_KEY`.** Import an OKF v0.1 bundle from a local directory. Creates or (with `merge`) updates articles; tolerates and preserves unknown frontmatter. |
 
@@ -304,6 +304,7 @@ it is enforced server-side and a no-op for a non-superadmin key — see below.)
 | `knowledge_bulk_delete` | **Requires `LOOPCTL_USER_KEY`.** Bulk archive (default, reversible) or IRREVERSIBLE hard-delete by selector. Provide exactly one selector: `article_ids` (list), `source_type`+`source_id` (every active article from a source), or `tag`+`confirm:true` (every active article with the tag — high blast radius). Default = set-based soft archive (idempotent; `meta.count`=archived, `meta.counts`/`meta.results` give the breakdown; ≤5000). **Dry-run** (`dry_run:true`) mutates nothing, returns `meta.would_affect` (with `hard:true` also a single-use `meta.token`, or `meta.confirm_hash` for oversized selectors). **Hard delete** (irreversible): dry-run with `hard:true` for a token, then call again with `hard:true`+`token` to FK-correctly delete the frozen id-set (links first, access events cascade). |
 | `knowledge_drafts` | List draft (unpublished) knowledge articles with pagination. Optional: `limit` (default 20, max 1000 — over-max → 400, no silent clamp), `offset` (default 0), `project_id`. Returns `meta.total_count`. |
 | `knowledge_lint` | Run a lint check on the knowledge wiki to identify stale or low-coverage articles. Optional: `project_id`, `stale_days`, `min_coverage`, `max_per_category` (default 50, max 500). True totals returned in `summary.total_per_category`. |
+| `knowledge_consolidation` | Read the nightly consolidation ("dream") report: NUMBERED proposals for reconciling the corpus, each naming the articles involved and quoting an excerpt from each as evidence. **REPORT ONLY** — the pass writes no articles, links or conflict resolutions; every proposal is `pending` and this tool applies nothing. Classes: `duplicate_capture` (titles that collide once case/punctuation normalize away, or idempotency keys that collide under the same normalization while differing verbatim — capture tag-format drift, which the novelty gate does not catch because novelty scoring and idempotency are separate paths), `contradiction_candidate` (a SYSTEM-flagged `potential_conflict` pair of PUBLISHED articles with no recorded verdict — record one with `knowledge_resolve_conflict`, which accepts exactly these pairs), `generic_title` (a placeholder title that collides on active-title uniqueness and blocks hub creation), `stale_entry`. **Denominators:** `corpus_size` = PUBLISHED articles owned by the tenant at scan time, not its total article count; `proposal_count` = the TRUE pre-cap count of PROPOSALS, not of articles (one duplicate group of three articles is ONE proposal, and one article can appear in proposals of several classes); `persisted_count` = proposal ROWS the report carries, lower than `proposal_count` exactly when a class hit `max_per_class` (`truncated` flags which); `meta.total_count` counts persisted proposals matching the `class` filter, so it is bounded by `persisted_count`, never `proposal_count`. `review_status`/`reviewed_by`/`reviewed_at` reset to pending/null whenever the nightly pass re-derives a proposal — refreshed machine output never inherits an approval. Requires orchestrator role. Optional: `day` (ISO8601, default most recent report), `class`, `limit` (default 50, max 500), `offset`. |
 | `knowledge_export` | Export all knowledge articles as an OKF v0.1 bundle (gzipped tar archive, unbounded, bounded-memory streaming, fail-closed). Returns a curl command for direct download — **the download requires `LOOPCTL_USER_KEY`** (an orchestrator key would 403). Pass `format=json` for buffered in-memory JSON (convenience tool for file writers; capped at `export_max_buffered_export_articles` — returns 413 if over-cap). Optional: `project_id`, `format` (`tar.gz` default or `json`). |
 | `knowledge_ingest` | Submit a URL or raw content for knowledge extraction. Enqueues an Oban job. Extracted articles are **drafts by default** (lower-trust LLM output); pass `publish: true` to publish on extraction. **BYO:** runs on the tenant's own Anthropic key — a keyless tenant gets a 422 whose result leads with an `ACTION REQUIRED` notice pointing at `set_llm_config` (see [First-time setup](#first-time-setup--provision-your-byo-llm-keys)). Required: `source_type`. One of: `url` or `content`. Optional: `project_id`, `publish`. |
 | `knowledge_ingest_batch` | Submit up to 50 ingestion items in a single request. Each item has the same shape as `knowledge_ingest` (incl. `publish`). Returns per-item results. Required: `items`. Optional: batch-level `project_id` / `publish` defaults. |

package/index.js

@@ -1927,6 +1927,20 @@ async function knowledgeLint({ project_id, stale_days, min_coverage, max_per_cat
   return toContent(result);
 }
 
+async function knowledgeConsolidation({ day, class: klass, limit, offset } = {}) {
+  const params = new URLSearchParams();
+  if (day) params.set("day", String(day));
+  if (klass) params.set("class", String(klass));
+  if (limit != null) params.set("limit", String(limit));
+  if (offset != null) params.set("offset", String(offset));
+  const qs = params.toString();
+  const path = qs
+    ? `/api/v1/knowledge/consolidation?${qs}`
+    : "/api/v1/knowledge/consolidation";
+  const result = await apiCall("GET", path, null, process.env.LOOPCTL_ORCH_KEY);
+  return toContent(result);
+}
+
 async function knowledgeIngest({ url, content, source_type, project_id, publish }) {
   const body = { source_type };
   if (url) body.url = url;
@@ -4720,7 +4734,14 @@ const TOOLS = [
         tags: {
           type: "array",
           items: { type: "string" },
-          description: "Optional: list of tags.",
+          description:
+            "Optional: list of TOPICAL tags. RESERVED NAMESPACE: the 'idem-' prefix belongs " +
+            "to per-source idempotency keys — a tag starting with it must be " +
+            "idem-<family>-<digest> where <digest> is a 12- or 40-character lowercase hex " +
+            "digest (e.g. idem-url-7ebe1ca33431), or the write is REJECTED with a 422. It is " +
+            "never silently rewritten. Do not put a topic in that prefix. For idempotent " +
+            "capture use the idempotency_key field, which is server-guaranteed unique per " +
+            "tenant — a tag is not.",
         },
         project_id: {
           type: "string",
@@ -4822,7 +4843,11 @@ const TOOLS = [
         tags: {
           type: "array",
           items: { type: "string" },
-          description: "Optional: REPLACES the whole tags array (send the full desired set).",
+          description:
+            "Optional: REPLACES the whole tags array (send the full desired set). RESERVED " +
+            "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 " +
+            "update is REJECTED with a 422 — it is never silently rewritten.",
         },
         metadata: {
           type: "object",
@@ -5447,6 +5472,63 @@ const TOOLS = [
       required: [],
     },
   },
+  {
+    name: "knowledge_consolidation",
+    description:
+      "Read the nightly consolidation (\"dream\") report: NUMBERED proposals for reconciling " +
+      "the corpus, each naming the articles involved and quoting an excerpt from each as " +
+      "evidence. REPORT ONLY — the pass writes no articles, links or conflict resolutions, " +
+      "every proposal is `pending`, and this tool applies nothing. Requires orchestrator role.\n\n" +
+      "Classes: `duplicate_capture` (titles that collide once case/punctuation normalize away, " +
+      "or idempotency keys that collide under the same normalization while differing verbatim — " +
+      "capture tag-format drift, which the novelty gate does not catch because novelty scoring " +
+      "and idempotency are separate paths); `contradiction_candidate` (a SYSTEM-flagged " +
+      "potential_conflict pair of PUBLISHED articles with no recorded verdict — record one via " +
+      "knowledge_resolve_conflict, which accepts exactly these pairs; this report writes " +
+      "none); `generic_title` (a placeholder title that collides on active-title uniqueness and " +
+      "blocks hub creation); `stale_entry` (past the lint staleness threshold, never reconciled).\n\n" +
+      "Denominators: `corpus_size` counts PUBLISHED articles owned by the tenant at scan time, " +
+      "not its total article count. `proposal_count` is the TRUE pre-cap count of PROPOSALS, not " +
+      "of articles — one duplicate group of three articles is ONE proposal, and one article can " +
+      "appear in proposals of several classes. `persisted_count` is how many proposal ROWS the " +
+      "report carries, lower than `proposal_count` exactly when a class hit `max_per_class` " +
+      "(`truncated` flags which). `meta.total_count` counts persisted proposals matching the " +
+      "`class` filter, so it is bounded by `persisted_count`, never by `proposal_count`.\n\n" +
+      "Review state (`review_status`/`reviewed_by`/`reviewed_at`) RESETS to pending/null whenever " +
+      "the nightly pass re-derives a proposal: refreshed machine output never inherits an approval.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        day: {
+          type: "string",
+          description:
+            "Optional ISO8601 date (YYYY-MM-DD, UTC) of the report to read. Defaults to the most recent report.",
+        },
+        class: {
+          type: "string",
+          enum: [
+            "duplicate_capture",
+            "contradiction_candidate",
+            "generic_title",
+            "stale_entry",
+          ],
+          description: "Optional: return only proposals of this class.",
+        },
+        limit: {
+          type: "integer",
+          description: "Proposals per page. Default 50, max 500 (clamped, never rejected).",
+          default: 50,
+          minimum: 1,
+        },
+        offset: {
+          type: "integer",
+          description: "Proposals to skip. Default 0.",
+          minimum: 0,
+        },
+      },
+      required: [],
+    },
+  },
   {
     name: "knowledge_export",
     description:
@@ -6899,6 +6981,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "knowledge_lint":
       return await knowledgeLint(args);
 
+    case "knowledge_consolidation":
+      return await knowledgeConsolidation(args);
+
     case "knowledge_export":
       return await knowledgeExport(args);
 

package/package.json

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