specguard-mcp 0.1.35 → 0.1.36

package/README.md

@@ -628,12 +628,15 @@ body text, whatever file they sit in), clustered by similarity. Answers the refa
 the overview's per-run rankings cannot: where the same test is written twice, before you delete or
 merge anything.
 
-**This is the expensive read in this toolset.** The census is linear but measured in seconds —
-seven queries at every size, tens of seconds extrapolated at the 20,000-test design point — which
-is why the platform serves it only to a client that asks (`?near_duplicates=`, shipped by SPGD-703)
-and answers `near_duplicates: null` on the plain overview. Calling this tool **is** the ask;
-`get_repository_overview` never sends it, so an agent reading the overview cannot pay the census by
-accident.
+**This call is served stored** (SPGD-1474): the platform computes the census once per write that
+moves its inputs — at each ingest, after identity resolution settles the run's identities, and
+again when a run is deleted from the repository (which can move the run the weight figures are
+weighed on) — and keeps it — so the answer returns in
+milliseconds instead of running the minutes-scale computation that used to sit behind the ask and
+never fit this bridge's 30-second deadline. The opt-in ask is unchanged wire contract
+(`?near_duplicates=`, shipped by SPGD-703, still opens the block; the plain overview still answers
+`near_duplicates: null` without it, and `get_repository_overview` never sends the ask). Calling
+this tool **is** the ask.
 
 Nothing about the **census** is choosable — the clusters are the repository's, computed over
 every run; one call returns them all. (The server reads only that the `near_duplicates` key is
@@ -657,6 +660,12 @@ Read the response with its own rules in mind:
 
 - `similarity_floor` and `similarity_basis` sit **first** in the block and qualify every figure
   below them — a cluster count without what "similar" meant is a count you cannot act on.
+- `computed_at` is when the stored census was taken and `weighed_run_id` is the run its weight
+  figures are from — read the stamp before acting on the figures. A census read shortly after an
+  ingest **or a run deletion** may be the **previous** artifact, carrying its own stamp, while the
+  recompute for the new state is still running; a `near_duplicates` block of `null` on this tool
+  means no census has
+  been computed for the repository yet (never a live computation, never zeros).
 - `member_count` (texts in the repository, across every run) and `example_count` (examples in the
   one run `weighed_run_id` names) are **different grains**: a three-example table-driven loop is
   one member and three examples. Never fold them.
@@ -667,6 +676,21 @@ Read the response with its own rules in mind:
   run's examples.
 - `similarity_range` is `[strongest, weakest]`: membership is transitive, similarity is not.
 - `total_seconds` is `null` where nothing was timed — never a zero that would read as free.
+- `layer_source` at the head of the block states where the layer dimension comes from: **declared
+  via the intent protocol** when at least one clustered member's examples declared a layer, `null`
+  on a suite that declared nothing — absence stated, never an empty fiction. The layers are
+  DECLARED, never inferred: no path or directory convention is consulted anywhere in the cut (a
+  `request`-declared test under `spec/models/` reports `request`).
+- `layer_redundancy` classifies each cluster: `cross_layer` when its members declared two or more
+  DISTINCT layers (the same behaviour covered on several levels — the test-pyramid question),
+  `same_layer` when confined to one (a plain duplicate), `null` when its members declared nothing
+  — neither state, never folded into `same_layer`.
+- `layer_groups` holds the members grouped by declared layer (alphabetically, the undeclared LAST
+  as the `layer: null` group), each group's members in the same five-field shape the flat list
+  serves. A member whose own examples declared two layers appears in EACH group it declared, so
+  the groups' sizes can exceed `member_count` by exactly those members — that is the finding, not
+  an arithmetic bug — and a member that declared nothing stays in its cluster's null group, never
+  dropped.
 - `clusters: []` with a real `identity_count` is the **success** state (nothing reads alike); the
   three silences — nothing ingested, nothing embedded, nothing alike — are kept distinguishable by
   `recorded_count` / `identity_count` / the list itself.

package/dist/src/tools/near-duplicate-clusters.d.ts

@@ -4,7 +4,9 @@ import type { ToolDefinition } from "./types.js";
  * platform by SPGD-703 (`specguard` `c43dc19`, 2026-08-28), which added the
  * `near_duplicates` block to `RepositoryOverview` behind an opt-in ask.
  *
- * == What the block is, and why it is behind an ask at all
+ * == What the block is, and why it is behind an ask at all (this section is
+ * the pre-SPGD-1474 story — the cost was live on the request; the next section
+ * is what changed)
  *
  * It is the suite-wide near-duplicate census: which tests READ alike — same
  * body text, not same file — clustered by the engine SPGD-369 shipped
@@ -21,6 +23,27 @@ import type { ToolDefinition } from "./types.js";
  * else. Splitting the tools splits the cost along exactly the line the server
  * drew.
  *
+ * == SPGD-1474: the census is computed at ingest, and this read is stored
+ *
+ * The minutes-scale compute no longer sits behind the request (and could never
+ * fit this bridge's 30-second default deadline). The server computes the census
+ * once per write that moves its inputs — at each ingest, after identity
+ * resolution settles the run's identities, and again when a run is deleted from
+ * the repository (which can move the run the weight figures are weighed on) —
+ * persists it, and serves the stored artifact, so a call here costs one stored
+ * read and returns in milliseconds. The opt-in ask is unchanged wire contract
+ * (`?near_duplicates=` still opens the block; the plain overview still answers
+ * `null` without it), and the tool split still stands: one call, one census,
+ * no accidental cost. What changed is the latency story and the honesty
+ * machinery around it: the block carries `computed_at` (when the stored
+ * artifact was taken) and `weighed_run_id` (which run its weight figures are
+ * from), so a consumer can always tell how fresh the census it is reading is.
+ * A request arriving between a completed write and the finished recompute
+ * serves the PREVIOUS stored census with its own stamp — never a live
+ * computation, never an unstamped answer. Between those writes (an ingest, or a
+ * run deletion) the stored census is exactly what a live computation would
+ * return: the inputs change only there.
+ *
  * == The ask is always sent, and always spelled `"true"`
  *
  * The server reads only whether the parameter is PRESENT

package/dist/src/tools/near-duplicate-clusters.js

@@ -5,7 +5,9 @@ import { optionalString } from "./args.js";
  * platform by SPGD-703 (`specguard` `c43dc19`, 2026-08-28), which added the
  * `near_duplicates` block to `RepositoryOverview` behind an opt-in ask.
  *
- * == What the block is, and why it is behind an ask at all
+ * == What the block is, and why it is behind an ask at all (this section is
+ * the pre-SPGD-1474 story — the cost was live on the request; the next section
+ * is what changed)
  *
  * It is the suite-wide near-duplicate census: which tests READ alike — same
  * body text, not same file — clustered by the engine SPGD-369 shipped
@@ -22,6 +24,27 @@ import { optionalString } from "./args.js";
  * else. Splitting the tools splits the cost along exactly the line the server
  * drew.
  *
+ * == SPGD-1474: the census is computed at ingest, and this read is stored
+ *
+ * The minutes-scale compute no longer sits behind the request (and could never
+ * fit this bridge's 30-second default deadline). The server computes the census
+ * once per write that moves its inputs — at each ingest, after identity
+ * resolution settles the run's identities, and again when a run is deleted from
+ * the repository (which can move the run the weight figures are weighed on) —
+ * persists it, and serves the stored artifact, so a call here costs one stored
+ * read and returns in milliseconds. The opt-in ask is unchanged wire contract
+ * (`?near_duplicates=` still opens the block; the plain overview still answers
+ * `null` without it), and the tool split still stands: one call, one census,
+ * no accidental cost. What changed is the latency story and the honesty
+ * machinery around it: the block carries `computed_at` (when the stored
+ * artifact was taken) and `weighed_run_id` (which run its weight figures are
+ * from), so a consumer can always tell how fresh the census it is reading is.
+ * A request arriving between a completed write and the finished recompute
+ * serves the PREVIOUS stored census with its own stamp — never a live
+ * computation, never an unstamped answer. Between those writes (an ingest, or a
+ * run deletion) the stored census is exactly what a live computation would
+ * return: the inputs change only there.
+ *
  * == The ask is always sent, and always spelled `"true"`
  *
  * The server reads only whether the parameter is PRESENT
@@ -78,10 +101,20 @@ const nearDuplicateClusters = {
         "(same body text, whatever file they sit in), clustered by similarity. Answers the refactoring " +
         "question the overview's per-run rankings cannot: where is the same test written twice, before " +
         "you delete or merge anything. " +
-        "THIS IS THE EXPENSIVE READ ON THIS BRIDGE: the census is linear but measured in seconds — seven " +
-        "queries at every size, tens of seconds extrapolated at the 20,000-test design point — which is " +
-        "exactly why the server serves it only to a client that asks (`?near_duplicates=`) and answers " +
-        "`near_duplicates: null` on the plain overview. Calling this tool IS the ask; nothing about the " +
+        "This call is SERVED STORED: the server computes the census at each ingest and on each run " +
+        "deletion and keeps it, so the " +
+        "answer returns in milliseconds instead of running the minutes-scale computation that used to " +
+        "sit behind the ask (and never fit this bridge's 30-second deadline). READ THE STAMP: " +
+        "`computed_at` is when the stored artifact was taken and `weighed_run_id` is the run its weight " +
+        "figures are from — a census read shortly after an ingest or a run deletion may be the PREVIOUS " +
+        "artifact, stamped, " +
+        "while the recompute runs; between such writes the stored census is exactly what a live computation " +
+        "would return. The opt-in ask is unchanged wire contract: the server answers `near_duplicates: " +
+        "null` on the plain overview (no ask, not one query), and `null` ON THIS TOOL means no census has " +
+        "been computed for the repository yet — a repository that has never ingested, read in the window " +
+        "before its first computation lands. It is never a live computation and never zeros: a repository " +
+        "whose every test reads differently serves a stored block with `clusters: []` and real counts. " +
+        "Calling this tool IS the ask; nothing about the " +
         "census is choosable — the clusters are the repository's, computed over every run, and one call " +
         "returns them all. WHICH repository is censused is the one choice there is: pass `repository` " +
         "(a numeric id from `list_repositories`) to census that named repository under either member " +
@@ -102,6 +135,21 @@ const nearDuplicateClusters = {
         "[strongest, weakest]: membership is transitive, similarity is not, and the gap between the edges " +
         "is the merge risk. `total_seconds` is raw and `null` where nothing was timed — never a zero " +
         "that would read as free. " +
+        "READ THE LAYER CUT AS DECLARATIONS, NEVER AS A GUESS: `layer_source` at the head of the block " +
+        "states where the layer dimension comes from — it is 'declared via the intent protocol' when at " +
+        "least one clustered member's examples declared a layer, and `null` on a suite that declared " +
+        "nothing, which is absence STATED, not an empty grouping to read as a finding. Each cluster " +
+        "carries `layer_redundancy` — `cross_layer` when its members declared two or more DISTINCT " +
+        "layers (the same behaviour covered on several levels: the test-pyramid question), `same_layer` " +
+        "when confined to one (a plain duplicate), `null` when its members declared nothing, which is " +
+        "neither and must not be folded into `same_layer` — and `layer_groups`, the members grouped by " +
+        "the layer their examples declared, alphabetically, with the undeclared LAST as the " +
+        "`layer: null` group. No path or directory convention is consulted anywhere in the cut: a " +
+        "`request`-declared test living under spec/models is reported `request`, because declarations " +
+        "do not lie and paths do. A member whose own examples declared two layers appears in EACH group " +
+        "it declared — so the groups' sizes can exceed `member_count` by exactly those members, which " +
+        "is the finding, not an arithmetic bug — and a member that declared nothing stays in its " +
+        "cluster's null group, never dropped. " +
         "A quiet answer is a FINDING, not a gap: `clusters: []` with a real `identity_count` is the " +
         "success state (nothing reads alike), and the three silences — nothing ingested " +
         "(`recorded_count: 0`), nothing embedded (`identity_count: 0`), nothing alike — are kept " +

package/dist/src/tools/near-duplicate-clusters.js.map

@@ -1 +1 @@
-{"version":3,"file":"near-duplicate-clusters.js","sourceRoot":"","sources":["../../../src/tools/near-duplicate-clusters.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAG3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,MAAM,qBAAqB,GAAmB;IAC5C,IAAI,EAAE,yBAAyB;IAE/B,KAAK,EAAE,yBAAyB;IAEhC,WAAW,EACT,2FAA2F;QAC3F,gGAAgG;QAChG,gGAAgG;QAChG,gCAAgC;QAChC,kGAAkG;QAClG,iGAAiG;QACjG,gGAAgG;QAChG,iGAAiG;QACjG,iGAAiG;QACjG,+FAA+F;QAC/F,8FAA8F;QAC9F,gGAAgG;QAChG,6FAA6F;QAC7F,WAAW;QACX,iGAAiG;QACjG,6FAA6F;QAC7F,+FAA+F;QAC/F,gGAAgG;QAChG,8DAA8D;QAC9D,iGAAiG;QACjG,8FAA8F;QAC9F,iGAAiG;QACjG,iGAAiG;QACjG,oGAAoG;QACpG,2FAA2F;QAC3F,mGAAmG;QACnG,8FAA8F;QAC9F,2BAA2B;QAC3B,6FAA6F;QAC7F,iFAAiF;QACjF,0FAA0F;QAC1F,6EAA6E;QAC7E,wFAAwF;QACxF,sFAAsF;QACtF,4FAA4F;QAC5F,4FAA4F;QAC5F,wFAAwF;QACxF,0FAA0F;QAC1F,wFAAwF;QACxF,uCAAuC;QACvC,2FAA2F;QAC3F,2FAA2F;QAC3F,2FAA2F;QAC3F,4FAA4F;QAC5F,8FAA8F;QAC9F,kBAAkB;IAEpB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,sFAAsF;oBACtF,iFAAiF;oBACjF,6CAA6C;oBAC7C,wFAAwF;oBACxF,6EAA6E;oBAC7E,+EAA+E;oBAC/E,qFAAqF;oBACrF,kFAAkF;oBAClF,4EAA4E;oBAC5E,iFAAiF;oBACjF,wEAAwE;oBACxE,4DAA4D;oBAC5D,mFAAmF;oBACnF,6DAA6D;aAChE;SACF;QACD,oBAAoB,EAAE,KAAK;KAC5B;IAED,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO;QACrB,MAAM,UAAU,GAAG,cAAc,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC,CAAC;QACpE,uEAAuE;QACvE,oDAAoD;QACpD,wEAAwE;QACxE,yEAAyE;QACzE,sEAAsE;QACtE,wEAAwE;QACxE,0EAA0E;QAC1E,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,gBAAgB,CAAC,OAAO,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;QAEnE,MAAM,QAAQ,GAAG,MAAM,aAAa,CAClC,GAAG,EACH,IAAI,EACJ;YACE,uEAAuE;YACvE,mEAAmE;YACnE,kDAAkD;YAClD,eAAe,EAAE,MAAM;SACxB,EACD,OAAO,CAAC,KAAK,CACd,CAAC;QAEF,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;YACvC,UAAU,EAAE,QAAQ;SACrB,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,eAAe,qBAAqB,CAAC"}
+{"version":3,"file":"near-duplicate-clusters.js","sourceRoot":"","sources":["../../../src/tools/near-duplicate-clusters.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specguard-mcp",
-  "version": "0.1.35",
+  "version": "0.1.36",
   "description": "MCP server exposing SpecGuard suite intelligence to AI coding agents",
   "license": "ISC",
   "type": "module",