v8.4.5 - Quality Metric Correctness

Quality Metric Correctness & Semgrep Documentation

Fixed

• Successful Imports: 1 anomaly resolved: quality_control_check.py now reports 82 of 86 importable modules (was 1). The bug: importlib.import_module("lib.dashboard") was sys.path-sensitive — when launched as py lib/quality_control_check.py, sys.path contained lib/ (not the project root), so the dotted-path resolution failed for ~99% of files and the ModuleNotFoundError was silently swallowed. Replaced with importlib.util.spec_from_file_location + exec_module (file-based, sys.path-independent). Stdout/stderr redirected during exec_module to keep top-level prints from dashboard.py / web_page_validator.py out of the report.
• Command undercount (v8.4.1 bug class, recurring): glob("*.md") on commands/ missed the 10 category subfolders, reporting 1 instead of 41. Now glob("**/*.md").
• documentation_coverage formula: previously divided by total repo markdown count (including archived reports under data/reports/archive/), crushing the percentage toward 0% as docs grew. Renormalized against 100 + (agents*10) + (skills*10) so the percentage reflects component documentation quality.
• pattern_storage.py bootstrap schema: _ensure_directory() wrote bare [] when the patterns file was missing, pre-empting init's dict-wrapped schema. Fresh /learn:init no longer emits a spurious validate warning.
• Dashboard favicon 404: added <link rel="icon" href="data:,"> to dashboard.py HTML head. web_page_validator.py reports 0 errors.
• Stale bug citation: commands/debug/eval.md's reference to random.uniform() in dashboard.py:710-712 marked (RESOLVED in v8.3.0) — dashboard is now 452 lines with no random usage; target retained only as a worked example.

Added

• docs/KNOWN_ISSUES.md: expanded the Semgrep Guardian PreToolUse hook note with concrete disable instructions. Key clarification: the Semgrep Guardian hook is NOT shipped by this plugin — it is the separate user-level semgrep@claude-plugins-official plugin in ~/.claude/settings.json. When it fails closed (unauthenticated), it blocks all Bash / Edit / Write operations. Disable via "semgrep@claude-plugins-official": false + restart, or log in via /mcp.
• Brain MCP integration documentation (see "Post-release documentation updates" below).

Post-release documentation updates

Two follow-up commits on main (after the v8.4.5 tag at b0de056) extend the documentation without changing plugin code:

• 768dc69 — Comprehensive v8.4.5 doc sync + GitHub SEO update: Added What Changed in v8.4.5 section to docs/KNOWLEDGE_MANAGEMENT.md (plus backfilled v8.4.3/v8.4.4), new full release notes file docs/release-notes/RELEASE_NOTES_v8.4.5.md, two methodology bullets in docs/APPROACH_AND_METHOD.md (metrics truthfulness + user-level hooks aren't plugin bugs), Metrics Must Mean What Their Name Says section in TESTING.md, and corrected stale README counts (35→36 agents, 40→41 commands, 9→10 categories). Updated GitHub repo description (removed inaccurate "40+ linters / CodeRabbit PR reviews") and curated 20 repo topics for SEO (added subagents, multi-agent-system, agent-framework, llm, large-language-models).

• 74fe9ff — Comprehensive Brain MCP integration documentation sync: New guideline file docs/guidelines/BRAIN_MCP_INTEGRATION_GUIDELINES.md (7.5 KB) covering optional external Brain MCP server integration. Documents three durable lessons from the v8.4.5 knowledge-transfer session: (1) brain_ask_oracle under-ranks newly-taught project-scoped items (cold-start + scope filter) while brain_retrieve_knowledge(query, projectId) reliably surfaces them — not data loss, a ranking property; (2) auto-mode classifier prevents agents from editing ~/.claude/settings.json to widen their own permissions.allow (deliberate permission-self-grant guardrail); (3) Brain MCP client does not auto-reconnect on transport drop — use /mcp reconnect or full restart. Added three new methodology bullets (#9 two retrieval paths, #10 permission self-grants, #11 authorization framing) and three new known-issues entries.

Methodology Documentation

Four bullets in docs/APPROACH_AND_METHOD.md (v8.4.5):

7. Metrics Must Mean What Their Name Says: When a metric depends on environment state (sys.path, env vars, CWD), prefer an API that takes the path explicitly over one that does implicit resolution. Also: redirect stdout/stderr during exec_module so diagnostic prints from imported modules don't pollute the report.

8. User-Level Hooks Are Not Plugin Bugs: When a session is paralyzed by a PreToolUse hook, check (a) .claude-plugin/plugin.json for a hooks block, (b) user-level ~/.claude/settings.json for enabledPlugins, and (c) whether the error string names a specific vendor before claiming a hook-related bug in any plugin.

9. Two Retrieval Paths, Two Different Failure Modes: When an external knowledge store exposes both a ranking-based oracle and a vector-similarity scoped search, they fail differently. Always probe the unranked path before declaring data loss.

10. Permission Self-Grants Are Not For Agents To Make: The auto-mode classifier denies agent attempts to widen its own permissions.allow list, even when the user said "continue all as suggested." This is a load-bearing safety property. Surface the desired change to the user with exact JSON.

11. Authorization Framing Affects Batch Operations: Bulk MCP operations delegated to subagents should not put authorization claims in the task prompt's prose — the classifier treats self-authored framing as suspicious. Let each call stand on its own.

Verification

Check	Result
ruff check .	All checks passed
pytest tests/ -q	113 passed, 0 skipped, 0 warnings (2.74s)
validate-claude-plugin.py	Score: 100/100, PERFECT, marketplace sync OK
quality_control_check.py	Overall Score: 100/100, Successful Imports: 82/86
Component metadata	104/104 files valid (36 agents + 41 commands + 27 skills)
Dashboard live test	11/11 endpoints HTTP 200, JSON well-formed
End-to-end web validation	0 console errors, 0 JS errors, 0 network errors
Brain MCP knowledge transfer	15/15 items stored in both projects (cmqnrt7et00070nnyk6hfsgcv + cmqnjwmqg00010nnylz6ra1ui), confidence 1.0, all retrievable via scoped search

Upgrade Notes

This is a backwards-compatible patch release. No action required for existing users — the next /plugin update will pull v8.4.5.

Users who hit the Semgrep Guardian hook can find disable instructions in docs/KNOWN_ISSUES.md under "Data & Tooling Integrity".

Users integrating with the optional external Brain MCP server should read docs/guidelines/BRAIN_MCP_INTEGRATION_GUIDELINES.md for the retrieval-path distinction and recovery procedures.

Commits in this release cycle

• b0de056 — release: v8.4.5 - quality metric correctness, semgrep hook documentation (the tagged release commit)
• 768dc69 — docs: comprehensive v8.4.5 doc sync + GitHub SEO update
• 74fe9ff — docs: comprehensive Brain MCP integration documentation sync

Full Changelog

v8.4.4...v8.4.5