Skip to content

Commit c710439

Browse files
cdeustclaude
andcommitted
fix(doc-claims): gate the three tool-count copies the review found (#597)
The audit asked for the class, not the number, and found three older copies. `.bestpractices.json` cited the pinned test as test_standalone_baseline_is_52_tools, two count moves stale, and the TOOL_CLAIM regex could not see it because the digits sit inside an identifier with no preceding space: a new PINNED_TEST_NAME_CLAIM family checks that form. `.claude-plugin/marketplace.json` advertised 50 tools (53 with upstreams) to every install and was scanned by nothing; it now has a targeted check rather than joining SCANNED_FILES, because the same description field recounts the plugin's version history, where past counts are quotations and the generic scan would fail them. The docker-smoke floor stays a literal, now pinned to the derived surface by a test. Both new checks were driven to failure before being trusted: 55/58 in the marketplace and 52 in the pinned name each produce a named failure. The gate's own fixtures gained the two subjects, since a family that matches nothing fails as vacuous by design. Full suite: 8771 passed, 8 skipped. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01Cz7A6goxVzfKL9NT7k4zDH
1 parent 4a86760 commit c710439

7 files changed

Lines changed: 80 additions & 3 deletions

File tree

‎.bestpractices.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -231,7 +231,7 @@
231231
"documentation_quick_start_justification": "https://github.com/cdeust/Cortex#getting-started \u2014 download the .mcpb bundle and open it in Claude Desktop, or install the Claude Code plugin; it runs immediately on the built-in SQLite backend with no database to provision. The Examples section then shows a full store/recall round trip.",
232232

233233
"documentation_current_status": "Met",
234-
"documentation_current_justification": "Documentation defects are treated as defects and fixed in the same PR, and the advertised numbers are now machine-checked rather than hand-maintained: https://github.com/cdeust/Cortex/blob/main/scripts/check_doc_claims.py fails the build when the tool count, reference count, mechanism count, version or test count in README, CONTRIBUTING, CLAUDE.md, GOVERNANCE.md, the MCPB manifest or the docs tree disagrees with the repository (the tool count is itself pinned to the live registry by tests_py/test_main.py::test_standalone_baseline_is_52_tools). It runs in the Lint job on every push and pull request, and with the live collected test count in the test job. Introducing it surfaced and fixed eight stale claims in this same PR, including a `mypy --strict` gate the project has never run and two MCP tools that moved to cortex-viz in v3.21.0 but were still documented here.",
234+
"documentation_current_justification": "Documentation defects are treated as defects and fixed in the same PR, and the advertised numbers are now machine-checked rather than hand-maintained: https://github.com/cdeust/Cortex/blob/main/scripts/check_doc_claims.py fails the build when the tool count, reference count, mechanism count, version or test count in README, CONTRIBUTING, CLAUDE.md, GOVERNANCE.md, the MCPB manifest or the docs tree disagrees with the repository (the tool count is itself pinned to the live registry by tests_py/test_main.py::test_standalone_baseline_is_57_tools). It runs in the Lint job on every push and pull request, and with the live collected test count in the test job. Introducing it surfaced and fixed eight stale claims in this same PR, including a `mypy --strict` gate the project has never run and two MCP tools that moved to cortex-viz in v3.21.0 but were still documented here.",
235235

236236
"documentation_achievements_status": "Met",
237237
"documentation_achievements_justification": "The OpenSSF Best Practices badge is displayed in the README badge row, hyperlinked to the project page, within hours of the passing level being awarded on 2026-07-27: https://github.com/cdeust/Cortex#readme (badge image https://www.bestpractices.dev/projects/13836/badge).",

‎.claude-plugin/marketplace.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
{
1313
"name": "hypermnesia-mcp",
1414
"source": "./",
15-
"description": "Cortex — persistent memory and cognitive profiling for Claude Code (renamed from the 'cortex' plugin in v4.15.0 to match the PyPI/MCP-registry identity hypermnesia-mcp) — thermodynamic memory with heat/decay, intent-aware retrieval, biological plasticity, codebase intelligence, and cognitive profiling. 50 MCP tools (53 with the optional ai-architect-mcp-codebase + ai-architect-mcp-spec integrations) with enriched schemas (visualization extracted to the standalone Hypermnesia MCP Viz server). PostgreSQL + pgvector in CLI mode; automatic SQLite fallback in Cowork/sandboxed mode. v3.17.0 — autonomous per-project wiki: SessionStart auto-spawns a 6-hour consolidate cycle; a headless `claude -p` worker drains the curation-gap queue, calls codebase-intelligence MCP tools to ground each section in the real call graph, and authors missing anchor pages (architecture / services / api / data-flow / operations / decisions / PRD) per project from the source tree. 15 canonical scopes × 13 file sections; per-project dashboards under `wiki/_dashboards/`. Mermaid diagrams have a 🔍 lens with zoom + pan. Workflow graph with caller-qualified CALLS chains rendering full method-to-method dependencies (native tree-sitter, no AP required). Side panel humanized for non-technical users. Ingests codebase analysis (ai-architect-mcp-codebase) and PRDs (ai-architect-mcp-spec) into wiki + memory + knowledge graph. Docker image available.",
15+
"description": "Cortex — persistent memory and cognitive profiling for Claude Code (renamed from the 'cortex' plugin in v4.15.0 to match the PyPI/MCP-registry identity hypermnesia-mcp) — thermodynamic memory with heat/decay, intent-aware retrieval, biological plasticity, codebase intelligence, and cognitive profiling. 57 MCP tools (60 with the optional ai-architect-mcp-codebase + ai-architect-mcp-spec integrations) with enriched schemas (visualization extracted to the standalone Hypermnesia MCP Viz server). PostgreSQL + pgvector in CLI mode; automatic SQLite fallback in Cowork/sandboxed mode. v3.17.0 — autonomous per-project wiki: SessionStart auto-spawns a 6-hour consolidate cycle; a headless `claude -p` worker drains the curation-gap queue, calls codebase-intelligence MCP tools to ground each section in the real call graph, and authors missing anchor pages (architecture / services / api / data-flow / operations / decisions / PRD) per project from the source tree. 15 canonical scopes × 13 file sections; per-project dashboards under `wiki/_dashboards/`. Mermaid diagrams have a 🔍 lens with zoom + pan. Workflow graph with caller-qualified CALLS chains rendering full method-to-method dependencies (native tree-sitter, no AP required). Side panel humanized for non-technical users. Ingests codebase analysis (ai-architect-mcp-codebase) and PRDs (ai-architect-mcp-spec) into wiki + memory + knowledge graph. Docker image available.",
1616
"version": "4.22.0",
1717
"author": {
1818
"name": "Clement Deust",

‎CHANGELOG.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,14 @@ adheres to [Semantic Versioning](https://semver.org/).
1515
CI jobs on a number nothing had updated. `mcp_server/tool_surface.py` now
1616
reads the surface from the registry modules and the verifier derives its
1717
bounds from it, with a test pinning both against what `register_all`
18-
actually registers.
18+
actually registers. The review of that fix found three more copies, all
19+
older than it: `.bestpractices.json` named the pinned test at 52 inside an
20+
identifier, where the claim regex could not see it; `.claude-plugin/
21+
marketplace.json` advertised 50 tools to every install and was scanned by
22+
nothing; and the docker-smoke floor was a bare literal. The first two are
23+
corrected and now gate-checked, the marketplace one by a targeted check
24+
because that same field also recounts the plugin's version history, and the
25+
third is pinned by a test.
1926

2027
- **Prediction records, and a score for the confidences they carry (#597).**
2128
Cortex stored what happened and never what was expected, so nothing it held

‎scripts/check_doc_claims.py‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,11 @@
6969
)
7070
# source: ADR-0713
7171
TEST_CLAIM = re.compile(r"(\d+)(?:\s+tests|-test suite)\b")
72+
# The pinned test name carries the standalone count inside an identifier,
73+
# where no space precedes the digits, so TOOL_CLAIM never saw it and it
74+
# sat stale at 52 across two count moves.
75+
# source: the decision recorded as ADR number 1077
76+
PINNED_TEST_NAME_CLAIM = re.compile(r"test_standalone_baseline_is_(\d+)_tools")
7277

7378

7479
def read(relative_path: str) -> str:
@@ -127,6 +132,12 @@ def collect_failures(test_count: int | None) -> list[str]:
127132
standalone, total = canonical_tool_counts()
128133
failures = check_counts(TOOL_CLAIM, standalone, "tools")
129134
failures += check_counts(TOOL_TOTAL_CLAIM, total, "tools with integrations")
135+
failures += check_counts(
136+
PINNED_TEST_NAME_CLAIM, standalone, "tools in the pinned test name"
137+
)
138+
failures += doc_claim_structural.check_marketplace_tool_counts(
139+
read, standalone, total
140+
)
130141
failures += check_counts(REFERENCE_CLAIM, canonical_reference_count(), "references")
131142
failures += check_counts(MECHANISM_CLAIM, canonical_mechanism_count(), "mechanisms")
132143
failures += check_no_hotlinked_badges()

‎scripts/doc_claim_structural.py‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -142,3 +142,41 @@ def check_scanned_json_parses(
142142
except json.JSONDecodeError as error:
143143
failures.append(f"{relative_path}: not valid JSON — {error}")
144144
return failures
145+
146+
147+
# The marketplace entry advertises the surface to every install, and its
148+
# description also recounts the plugin's version history, where past counts
149+
# are quotations rather than claims. Only the current sentence is checked,
150+
# and it must exist: a gate that cannot find its subject must fail.
151+
# source: the decision recorded as ADR number 1077
152+
MARKETPLACE_TOOL_COUNTS = re.compile(r"(\d+) MCP tools \((\d+) with the optional")
153+
MARKETPLACE_PATH = ".claude-plugin/marketplace.json"
154+
155+
156+
def check_marketplace_tool_counts(
157+
read_fn: ReadFn, standalone: int, total: int
158+
) -> list[str]:
159+
"""The marketplace description's current tool counts, nothing else."""
160+
try:
161+
text = read_fn(MARKETPLACE_PATH)
162+
except OSError as exc:
163+
return [f"{MARKETPLACE_PATH}: unreadable ({exc})"]
164+
match = MARKETPLACE_TOOL_COUNTS.search(text)
165+
if match is None:
166+
return [
167+
f"{MARKETPLACE_PATH}: no 'N MCP tools (M with the optional ...' "
168+
"sentence found; the gate has lost its subject"
169+
]
170+
found_standalone, found_total = (int(group) for group in match.groups())
171+
failures = []
172+
if found_standalone != standalone:
173+
failures.append(
174+
f"{MARKETPLACE_PATH}: advertises {found_standalone} tools, "
175+
f"canonical is {standalone}"
176+
)
177+
if found_total != total:
178+
failures.append(
179+
f"{MARKETPLACE_PATH}: advertises {found_total} tools with "
180+
f"integrations, canonical is {total}"
181+
)
182+
return failures

‎tests_py/scripts/test_check_doc_claims.py‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -551,8 +551,16 @@ class CollectFailuresTests(unittest.TestCase):
551551
CONSISTENT = (
552552
"52 memory tools (55 total with upstream).\n"
553553
"A 2-reference bibliography of 36 mechanisms.\n"
554+
# The count also lives inside the pinned test's NAME, where no space
555+
# precedes the digits; its own family is checked since ADR-1077.
556+
"Pinned by tests_py/test_main.py::test_standalone_baseline_is_52_tools.\n"
554557
)
555558

559+
# The marketplace description states the surface to every install and is
560+
# checked on its own, not through SCANNED_FILES, because the same field
561+
# recounts the plugin's version history (ADR-1077).
562+
MARKETPLACE = '{"description": "52 MCP tools (55 with the optional bits)"}'
563+
556564
def setUp(self):
557565
self._real_read = gate.read
558566
self._real_files = gate.SCANNED_FILES
@@ -568,6 +576,7 @@ def _install(self, doc: str, badge: str | None = "6260", readme: str | None = No
568576
"tests_py/test_main.py": PINNED_TEST,
569577
"docs/papers/bibliography.md": BIBLIOGRAPHY,
570578
"README.md": readme or '<img src="assets/badge-tests.svg" alt="tests">\n',
579+
".claude-plugin/marketplace.json": self.MARKETPLACE,
571580
}
572581
# None omits the file entirely (a missing-badge scenario); any other
573582
# string is spliced into the <title> as-is, so a non-digit value

‎tests_py/test_tool_surface.py‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,3 +38,15 @@ def test_the_host_contract_bounds_follow_the_surface() -> None:
3838

3939
assert MIN_FULL_TOOL_COUNT == len(standalone_tool_names())
4040
assert MAX_FULL_TOOL_COUNT == MIN_FULL_TOOL_COUNT + len(UPSTREAM_TOOL_NAMES)
41+
42+
43+
def test_the_docker_smoke_floor_follows_the_surface() -> None:
44+
"""The last bare literal: a shell default nothing tied to the registries."""
45+
import pathlib
46+
import re
47+
48+
script = pathlib.Path("scripts/docker_smoke.sh").read_text(encoding="utf-8")
49+
match = re.search(r'MIN_TOOL_COUNT="\$\{CORTEX_SMOKE_MIN_TOOLS:-(\d+)\}"', script)
50+
51+
assert match, "docker_smoke.sh no longer declares MIN_TOOL_COUNT as expected"
52+
assert int(match.group(1)) == len(standalone_tool_names())

0 commit comments

Comments
 (0)