loopctl-mcp-server 2.66.0 → 2.68.0

package/README.md

@@ -254,10 +254,10 @@ Epic 39 Repo Coordination Bus — a lightweight, tenant-isolated channel for age
 | `knowledge_search` | Search the knowledge wiki by topic (keyword, semantic, or combined). Returns snippets. **Ranked, published-only, and LAGS writes by minutes while embeddings index — do NOT use for existence/idempotency/dedup checks (a fresh write false-negatives); use `knowledge_list` for that.** `q` is optional when `tags`/`category` are supplied — that **list mode** returns the complete filtered set paginated via `offset`/`limit` over `meta.total_count`. `meta.total_count` is mode-dependent — read `meta.total_count_scope` (`keyword_matches`/`ranked_corpus`/`merged_candidates`/`filtered_set`) and don't use a relevance-mode count to size the wiki (use `knowledge_list` or `knowledge_stats`). Optional: `project_id`, `story_id` for attribution. |
 | `knowledge_hybrid_search` | Resolve a topic to a **single best answer with provenance** (US-31.4). Runs combined keyword+semantic over the full ranked pool, then decides whether a governed **curated** source actually answers. `meta.provenance` is `curated` (trust it — the canonical article is first in `data`, `meta.curated_article_id` points at it) or `retrieved` (best fuzzy match, `curated_article_id` null); `meta.confidence` is the winner's absolute score. Prefer over `knowledge_search` when you want one trustworthy answer, not a list to triage. Degrades to keyword-only like `knowledge_search` when embeddings are unavailable. Required: `query`. Optional: `project_id`, `category`, `tags`, `match`, `limit`, `offset`. |
 | `knowledge_progressive_index` | Progressive disclosure — a **cheap, capped index** of what's relevant to a topic (compact stubs: `id`/`title`/`category`/`summary`, **no bodies**), curated-preferred and hub-enriched, capped at top-K (`meta.truncated` when the pool exceeded it). Survey a topic without flooding context, then open only what you need via `knowledge_progressive_drill`. Required: `topic`. Optional: `category`, `limit`. |
-| `knowledge_heat_index` | Browse the corpus with **no query at all** — capped compact stubs (`id`/`title`/`category`/`heat`/`summary`, **no bodies**) ranked by how many **distinct readers** (agents, not key rows — repeat reads by one reader count once, ties broken by the number of distinct days read, never by raw read count) opened each article inside a window. Every other retrieval tool starts from a query and so shares one failure mode: a paraphrase, or material topically central but lexically dissimilar to the question, comes back empty and reads as "the KB has nothing" rather than "I asked badly". Reach for it when a search came back empty or thin, or to survey what the fleet actually reads before you know what to ask. **Ordering is usage, not relevance**, and drilling a listed tenant article (`knowledge_progressive_drill`) does not add heat to what it opened — otherwise being shown would produce the rank that shows it. A `knowledge_get` of the same id still counts, as does a drill of a system canonical, whose body has no other read path. `meta` states `heat_window` (snapped to a UTC day boundary, narrowing only, so the payload is stable between refreshes and safe in a cached prefix), `counted_access_types`, `char_budget`/`chars`, `truncated` and `unresolved`. Open a stub with `knowledge_progressive_drill` — **not** `knowledge_get`, which cannot resolve the published system canonicals this index also lists. Optional: `category`, `limit`, `since`. |
-| `knowledge_progressive_drill` | Open one stub from `knowledge_progressive_index` or `knowledge_heat_index` — returns the **full article body** for the given id, scope-enforced. Resolves both tenant-owned articles and published system canonicals (the same set those indexes surface). A tenant article opened this way is recorded under an access type `knowledge_heat_index` does not count, so that index cannot rank on the reads it caused. Required: `article_id`. |
+| `knowledge_heat_index` | Browse the corpus with **no query at all** — capped compact stubs (`id`/`title`/`category`/`heat`/`summary`, **no bodies**) ranked by how many **distinct readers** (agents, not key rows — repeat reads by one reader count once, ties broken by the number of distinct days read, never by raw read count) opened each article inside a window. Every other retrieval tool starts from a query and so shares one failure mode: a paraphrase, or material topically central but lexically dissimilar to the question, comes back empty and reads as "the KB has nothing" rather than "I asked badly". Reach for it when a search came back empty or thin, or to survey what the fleet actually reads before you know what to ask. **Ordering is usage, not relevance**, and drilling a listed article (`knowledge_progressive_drill`) does not add heat to what it opened, at any scope — otherwise being shown would produce the rank that shows it. A `knowledge_get` of the same id does count. `meta` states `heat_window` (the default window is snapped to a UTC day boundary so the payload is stable between refreshes and safe in a cached prefix; an explicit `since` is served verbatim), `counted_access_types`, `char_budget`/`chars` (BYTES of the encoded stub array, framing included), `truncated` and `unresolved`. Both read tools open a stub, canonicals included — pick by what the read MEANS: a drill is uncounted, a `get` is a counted vote. Optional: `category`, `limit`, `since`. |
+| `knowledge_progressive_drill` | Open one stub from `knowledge_progressive_index` or `knowledge_heat_index` — returns the **full article body** for the given id, scope-enforced. Resolves both tenant-owned articles and published system canonicals (the same set those indexes surface). Every article opened this way is recorded under an access type `knowledge_heat_index` does not count, whatever its scope, so that index can never rank on the reads it caused. `knowledge_get` reaches the same ids and DOES count — use it when the read is a deliberate vote rather than a step in following a list. Required: `article_id`. |
 | `knowledge_list` | List articles (`id`, `title`, `category`, `status`, `tags`, `source_type`, `source_id`, `idempotency_key`, timestamps), filtered + paginated. **Body-less summary by default** (safe to page up to `limit=1000`); pass `include_body: true` to also return `body`, in which case the page is bounded by a ~5 MB byte budget — continue via `meta.next_offset` while `meta.has_more`. **Lag-free, all-status** read of the DB of record — unlike `knowledge_search` (ranked, published-only, lags writes) and `knowledge_index` (id/title/category only). The right tool to enumerate/dedup/repair and for idempotency/existence checks: filter by `tags`, `source_type`+`source_id`, or `idempotency_key` and read `meta.total_count` (exact). Single full body → `knowledge_get`; relevant bodies → `knowledge_context`; bulk dump → `knowledge_export`. Optional: `project_id`, `category`, `status`, `tags`, `source_type`, `source_id`, `idempotency_key`, `offset`, `limit`, `include_body`. |
-| `knowledge_get` | Get full article content by ID. Use after search to read an article in detail. Each link carries only its FAR side (`article: {id, title}`, plus `similarity` when scored); both arrays are ranked (open conflicts first, then descending similarity, then oldest-first for the unscored) and capped at 25 per direction, with `links_total` / `links_truncated` reporting the truth (`count` returns both, so one cheap call tells you whether the full fetch is capped). Pass `links: "count"` or `"none"` when you only want the text — on a well-linked hub the link block is several times the body. `potential_conflicts` is returned in all three modes, itself capped at 25 with `conflicts_total` / `conflicts_truncated`. Optional: `links`, `project_id`, `story_id` for attribution. |
+| `knowledge_get` | Get full article content by ID. Use after search to read an article in detail. Resolves tenant-owned articles **and published system canonicals**, and records a COUNTED read (it feeds `knowledge_heat_index`) — reach for `knowledge_progressive_drill` instead when you are merely following an index this system just produced. Each link carries only its FAR side (`article: {id, title}`, plus `similarity` when scored); both arrays are ranked (open conflicts first, then descending similarity, then oldest-first for the unscored) and capped at 25 per direction, with `links_total` / `links_truncated` reporting the truth (`count` returns both, so one cheap call tells you whether the full fetch is capped). Pass `links: "count"` or `"none"` when you only want the text — on a well-linked hub the link block is several times the body. `potential_conflicts` is returned in all three modes, itself capped at 25 with `conflicts_total` / `conflicts_truncated`. Optional: `links`, `project_id`, `story_id` for attribution. |
 | `knowledge_context` | Get relevance-and-recency-ranked full articles for a task query. Best knowledge for your current context. **Agent-memory scoping**: `memory_types` (comma-separated, OR — observation/finding/summary/decision/question/task), `agents` (comma-separated agent_ids, OR), `conversation_id` (exact) filter on article `metadata` (JSONB `@>`). Optional: `project_id`, `story_id` for attribution, `limit`, `recency_weight`. |
 | `knowledge_graph` | Multi-hop traversal of the published article-link graph from `article_id` (depth 1–3, default 1), **bounded to agent's visible articles**. Agent callers see only their own and `shared` articles. Bidirectional, cycle-safe, bounded to 100 nodes / 500 edges (`truncated` flags a cap). Returns `nodes` (`id`/`title`/`category`/`depth`) + `edges` (`source_article_id`/`target_article_id`/`relationship_type`). Explore typed connections beyond `knowledge_context`'s 1-hop links. Required: `article_id`. Optional: `depth`, `project_id`. |
 | `knowledge_suggest_links` | Ranked typed-link **candidates** for an article by embedding similarity among **visible articles** — **read-only** (creates nothing). Excludes the article itself + any already-linked article (either direction, any type); only embedded published articles visible to the caller. Agent callers see only their own and `shared` articles. Returns `{id, title, category, similarity_score}` highest-first, to create as a **typed** link (relates_to/derived_from/contradicts/supersedes). Required: `article_id`. Optional: `threshold` (cosine floor 0–1, default 0.5), `limit` (default 5). |
@@ -326,7 +326,7 @@ it is enforced server-side and a no-op for a non-superadmin key — see below.)
 | `knowledge_agent_usage` | Per-agent knowledge usage: total reads, unique articles, top read articles. Required: exactly one of `api_key_id` (credential) or `agent_id` (logical identity). Optional: `limit`, `since_days`. See Wiki Attribution section. |
 | `knowledge_unused_articles` | Published articles with zero accesses in the window. Optional: `days_unused` (default 30), `limit` (default 50, max 200). |
 | `knowledge_curation_log` | Concise human-readable log of KB CURATION adjustments — novelty-gate decisions (`gate_duplicate`/`gate_draft`/`gate_skip`) and conflict resolutions (`supersede`/`merge`/`dismiss`) — for analyzing the agents'-KB rollout, distinct from the verbose audit log. Each entry: `{at, kind, summary, refs, actor, confidence}`. **RECORDED ONLY when `settings.kb_curation_log` is on** (PATCH `/api/v1/admin/tenants/:id` with `settings:{kb_curation_log:true}`); off by default = no rows. Most recent first. Requires orchestrator role. Optional: `kind`, `since` (ISO8601), `limit` (default 50, max 500), `offset`. |
-| `knowledge_retrieval_metrics` | Daily retrieval-PRECISION time series: for each day, the share of search results the agent then opened (search → get/context within a window). A proxy for whether retrieval is improving as the corpus is de-duplicated, better navigated (MOCs), and conflict-resolved. Most recent day first. Requires orchestrator role. Optional: `limit` (default 30, max 365), `offset`. |
+| `knowledge_retrieval_metrics` | Daily retrieval-PRECISION time series: for each day, the share of RECORDED surfaced search RESULTS the agent then opened (search → get/context within a window). A proxy for whether retrieval is improving as the corpus is de-duplicated, better navigated (MOCs), and conflict-resolved. **Denominators (#582):** `precision` = `followed_through`/`searched`, where `searched` counts RECORDED surfaced RESULTS — one row per result put in front of the agent, capped at the first 20 per call (cap enforced by `Loopctl.Knowledge.Analytics.max_recorded_search_results/0`) — not search calls (`results_recorded` is the same number named for its unit). That cap makes `precision` precision@20: a call returning more contributes only 20, and an open of a result ranked beyond the cap is in neither term. The per-CALL rate is the separate `search_follow_through` = `searches_with_follow_through`/`searches` (distinct QUERY-BEARING calls — query-less `list`/`list_keyset` enumeration pages are excluded). `results_returned` is the true un-truncated count for those same calls. The four call-level fields are filtered per ROW, not per day, so a day mixing pre-#582 or enumeration rows with real searches reports a PARTIAL figure rather than 0 — and `results_returned` is NOT comparable to `searched`. Zero-result and keyless searches are unrecordable, so both ratios are upper bounds — and both rise when a search returns FEWER results, so never optimise them without the absolute `followed_through`; `search_follow_through` is additionally biased DOWN by the recording cap (opens beyond rank 20 are invisible) and UP by crediting every search in the window that surfaced the opened article. Most recent day first. Requires orchestrator role. Optional: `limit` (default 30, max 365), `offset`. |
 
 ### Egress / Privacy Tools (US-41.4)
 

package/index.js

@@ -4511,10 +4511,11 @@ const TOOLS = [
       "KB has nothing' rather than 'I asked badly'. Reach for this when a search came back " +
       "empty or thin, or to survey what the fleet actually reads before you know what to " +
       "ask. Ordering is usage, NOT relevance to any query. Open a stub with " +
-      "knowledge_progressive_drill (not knowledge_get — this index also lists published " +
-      "system canonicals, which knowledge_get cannot resolve). Drilling a tenant article " +
-      "adds NO heat to what you opened, so this index cannot feed the ranking that showed " +
-      "you the stub; a knowledge_get of the same id does count.",
+      "knowledge_progressive_drill: drilling adds NO heat to what you opened, whatever its " +
+      "scope, so this index can never feed the ranking that showed you the stub. " +
+      "knowledge_get resolves the same ids (published system canonicals included) and DOES " +
+      "count as a read — use it when you are deliberately voting for an article's " +
+      "usefulness, not when you are just following this list.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4531,9 +4532,9 @@ const TOOLS = [
           description:
             "Optional: ISO-8601 timestamp; count only reads at/after it. Defaults to the " +
             "last 90 days, clamped to at most 365 days of lookback and to no later than " +
-            "today. Snapped to a UTC day boundary in the NARROWING direction (never wider " +
-            "than you asked for; a timestamp inside the current UTC day is used exactly as " +
-            "given), and meta.heat_window echoes what you got.",
+            "the start of today. An explicit timestamp is otherwise served VERBATIM; only " +
+            "the default and the ceiling are anchored at the start of today, which is what " +
+            "keeps a default refresh byte-identical. meta.heat_window echoes what you got.",
         },
       },
       required: [],
@@ -4547,8 +4548,12 @@ const TOOLS = [
       "body for the given id, scope-enforced. Resolves both tenant-owned articles and " +
       "published system canonicals (the same set the index surfaces). This is the drill " +
       "half of progressive disclosure: index cheaply, then open only the article(s) you " +
-      "need. (knowledge_get works for tenant articles too; use this to also reach the " +
-      "system canonicals the progressive index can surface.)",
+      "need.\n\n" +
+      "Pick between this and knowledge_get by what the read MEANS, not by what it can " +
+      "reach — both resolve the same ids now. A drill records an UNCOUNTED read, so " +
+      "following an index never raises the heat of what that index just showed you; " +
+      "knowledge_get records a counted one, which is a vote that the article was worth " +
+      "opening on its own. Following a list is not a vote.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4565,6 +4570,9 @@ const TOOLS = [
     name: "knowledge_get",
     description:
       "Get full article content by ID. Use after search to read an article in detail. " +
+      "Resolves tenant-owned articles AND published system canonicals. Records a COUNTED " +
+      "read (it feeds knowledge_heat_index); use knowledge_progressive_drill instead when " +
+      "you are merely following an index this system just handed you. " +
       "Pass story_id when working on a loopctl story so reads attribute correctly. " +
       "If the response carries a non-empty `potential_conflicts` array AND the conflict is " +
       "material to your current task, act on it: read the peer, judge redundant/complementary/" +
@@ -6034,10 +6042,36 @@ const TOOLS = [
     name: "knowledge_retrieval_metrics",
     description:
       "Return the daily retrieval-PRECISION time series (agents' KB #3): for each day, the " +
-      "share of search results the agent then opened (search → get/context within a window). " +
-      "A proxy for whether retrieval is improving — watch it trend up as the corpus is " +
-      "de-duplicated, better navigated (MOCs), and conflict-resolved. Most recent day first. " +
-      "Requires orchestrator role.",
+      "share of RECORDED surfaced search RESULTS the agent then opened (search → get/context " +
+      "within a window). A proxy for whether retrieval is improving — watch it trend up as " +
+      "the corpus is de-duplicated, better navigated (MOCs), and conflict-resolved. Most " +
+      "recent day first. Requires orchestrator role.\n\n" +
+      // The cap is enforced by Loopctl.Knowledge.Analytics.max_recorded_search_results/0
+      // (Elixir); this JS string cannot interpolate it, so change both together.
+      "Denominators (#582): precision = followed_through / searched, and `searched` counts " +
+      "RECORDED surfaced RESULTS — one row per result put in front of the agent, capped at " +
+      "the first 20 per call — not search calls (`results_recorded` is the same number, " +
+      "named for its unit). Because of that cap precision is precision@20: a call returning " +
+      "more results contributes only 20 to `searched`, and an open of a result ranked beyond " +
+      "the cap is in neither term. The per-CALL rate is separate: `search_follow_through` = " +
+      "searches_with_follow_through / searches — the share of QUERY-BEARING SEARCHES that " +
+      "led to an open. `results_returned` is the true un-truncated result count for those " +
+      "same calls, so it exceeds the rows those calls wrote whenever a page hit the cap.\n\n" +
+      "Call-level population: the four call-level fields are filtered per ROW, not per day " +
+      "— a row counts only if it carries a search identity (nothing recorded before #582 " +
+      "does) and is not a query-less enumeration page (list / list_keyset; browsing is not " +
+      "searching). A day that mixes qualifying and non-qualifying rows reports a PARTIAL " +
+      "searches / results_returned, not 0. Do NOT compare results_returned against " +
+      "searched: different row populations, so results_returned < searched is normal on a " +
+      "legacy-heavy or browse-heavy day.\n\n" +
+      "Caveats: zero-result searches and keyless searches are structurally unrecordable and " +
+      "sit in NO denominator, so both ratios are upper bounds; and both rise if a search " +
+      "simply returns FEWER results, with no better retrieval. Never optimise either alone — " +
+      "read them with the absolute followed_through and the volume fields. " +
+      "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).",
     inputSchema: {
       type: "object",
       properties: {

package/package.json

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