diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 2e2ccc34..925c6ebe 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "claudius", - "version": "4.1.7", + "version": "4.2.0", "description": "Collection of specialized development agents and skills for Claude Code", "author": { "name": "lklimek", diff --git a/.github/workflows/test-report-pipeline.yml b/.github/workflows/test-report-pipeline.yml index e27b0f80..2a53c04e 100644 --- a/.github/workflows/test-report-pipeline.yml +++ b/.github/workflows/test-report-pipeline.yml @@ -5,16 +5,18 @@ on: paths: - 'scripts/**' - 'schemas/**' - - 'tests/fixtures/reports/**' - - 'tests/test_report_pipeline.sh' - - 'tests/test_consolidate_reports.py' + - 'skills/**' + - 'agents/**' + - 'tests/**' + - '.github/workflows/test-report-pipeline.yml' pull_request: paths: - 'scripts/**' - 'schemas/**' - - 'tests/fixtures/reports/**' - - 'tests/test_report_pipeline.sh' - - 'tests/test_consolidate_reports.py' + - 'skills/**' + - 'agents/**' + - 'tests/**' + - '.github/workflows/test-report-pipeline.yml' jobs: test: @@ -32,7 +34,7 @@ jobs: pip install pytest - name: Unit tests - run: python3 -m pytest tests/test_consolidate_reports.py -v + run: python3 -m pytest tests/ -q - name: Report pipeline (fixtures) run: ./tests/test_report_pipeline.sh diff --git a/CHANGELOG.md b/CHANGELOG.md index 4a758d2c..dc15536d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,23 @@ Format follows [Keep a Changelog](https://keepachangelog.com/). This project use ## [Unreleased] +## [4.2.0] - 2026-05-28 + +### Added + +- **Reviewer call-tree inspection**: `grumpy-review`, `review-pr`, and `check-pr-comments` now perform a deep transitive in-repo caller walk for every function modified by the diff. Reviewer probes the environment for the deepest analysis tool available (ctags, GNU global, ripgrep, tree-sitter) and falls back to grep-based caller extraction. Findings emit in new `call_tree` category with `CALL-` ID prefix. Walk is capped at depth 5, 200 callers, 60s per function; reviewer ranks modified functions by risk (public API > private; trait/interface impl > leaf; signature-changed > body-only) and walks the top 10 when a PR touches many. +- **Ephemeral-ID coding convention** in `skills/coding-best-practices/SKILL.md`: source code, comments, and committed docs MUST NOT reference transient review-finding IDs (e.g. `CMT-NNN`, `SEC-NNN`, `RUST-NNN`, `CALL-NNN`). Allow-list documented for permanent IDs (`ADR-NNN`, `RFC-NNN`, `CWE-NNN`, `CVE-YYYY-NNNN`, `OWASP-*`, GHSA, GitHub issue/PR refs, `TODO`/`FIXME`, committed test-spec IDs). Enforced two ways: Bilby (write-side, preloads BP) and `grumpy-review`/`review-pr` (review-side, via new `scripts/lint_ephemeral_ids.py`). +- **Schema**: `schemas/review-report.schema.json` extended with `call_tree` category and `CALL-` ID pattern (additive, no schema version bump). +- **Regression guards**: `tests/test_skill_frontmatter.py` parses every skill/agent frontmatter via PyYAML; `tests/test_bp_load_audit.py` asserts curated agent set loads `coding-best-practices`. + +### Changed + +- `coding-best-practices` skill is now loaded by every reviewer/coder agent (`architect-nagatha`, `claudius`, `developer-bilby` (already), `project-reviewer-adams` (already), `qa-engineer-marvin`, `security-engineer-smythe`, `technical-writer-trillian`, `ux-designer-diziet`) via YAML `skills:` frontmatter. Orchestrator skills that spawn coding/reviewing agents now explicitly require spawned agents preload BP (`grumpy-review` §3, `check-pr-comments` §3). + +### Fixed + +- `skills/release/SKILL.md`: YAML frontmatter `description:` value quoted to fix PyYAML parse error on unquoted colon. `claude plugin validate .` now exits 0 (previously reported this one error). + ## [4.1.7] - 2026-05-27 ### Changed @@ -164,15 +181,15 @@ v1/v2 reports are no longer accepted. Re-run the producer (grumpy-review / check ### Fixed -- `scripts/generate_review_report.py` (CQ-001): the resolved Unicode TTF is now also wired into matplotlib (`font_manager.addfont` + `rcParams["font.sans-serif"]`) so PDF chart labels — e.g. agent names from `agent_stats` — render non-Latin scripts instead of tofu boxes, matching the ReportLab text flow. Best-effort: a matplotlib font failure logs a warning and leaves chart glyphs degraded but never aborts the render. -- `scripts/generate_review_report.py` / CHANGELOG (DOC-001): corrected the font-discovery wording. The `scripts/fonts/DejaVuSans.ttf` slot is an optional user-supplied drop-in, **not** a font shipped with the plugin; system fonts come from the `fonts-dejavu` / `fonts-noto` packages. Module docstring and 3.14.3 changelog entry updated to match. +- `scripts/generate_review_report.py`: the resolved Unicode TTF is now also wired into matplotlib (`font_manager.addfont` + `rcParams["font.sans-serif"]`) so PDF chart labels — e.g. agent names from `agent_stats` — render non-Latin scripts instead of tofu boxes, matching the ReportLab text flow. Best-effort: a matplotlib font failure logs a warning and leaves chart glyphs degraded but never aborts the render. +- `scripts/generate_review_report.py` / CHANGELOG: corrected the font-discovery wording. The `scripts/fonts/DejaVuSans.ttf` slot is an optional user-supplied drop-in, **not** a font shipped with the plugin; system fonts come from the `fonts-dejavu` / `fonts-noto` packages. Module docstring and 3.14.3 changelog entry updated to match. ## [3.14.3] - 2026-05-05 ### Fixed -- `scripts/generate_review_report.py` (QA-004): PDF output now registers a Unicode TrueType font (DejaVu Sans / Noto Sans, with bold/italic/mono siblings via `pdfmetrics.registerFontFamily`) so emoji and non-Latin scripts (Cyrillic, Arabic, Hebrew, etc.) render correctly instead of as tofu boxes. Discovery order: `$CLAUDIUS_PDF_FONT` env override -> optional user-supplied `scripts/fonts/DejaVuSans.ttf` (not shipped with the plugin) -> common Linux locations (`/usr/share/fonts/truetype/dejavu`, `/usr/share/fonts/truetype/noto`, provided by `fonts-dejavu` / `fonts-noto`). When no TTF is found the renderer logs a warning to stderr and falls back to ReportLab's Helvetica/Courier core fonts (Latin-1 only) -- never crashes. -- `scripts/generate_review_report.py` (QA-005): `render_markdown_to_reportlab()` wraps the Markdown -> HTML -> ReportLab pass in try/except. On any failure (malformed input, parser exception, ReportLab mini-XML rejection) it logs a warning and falls back to a single XML-escaped preformatted block containing the raw source so no content is silently swallowed. +- `scripts/generate_review_report.py`: PDF output now registers a Unicode TrueType font (DejaVu Sans / Noto Sans, with bold/italic/mono siblings via `pdfmetrics.registerFontFamily`) so emoji and non-Latin scripts (Cyrillic, Arabic, Hebrew, etc.) render correctly instead of as tofu boxes. Discovery order: `$CLAUDIUS_PDF_FONT` env override -> optional user-supplied `scripts/fonts/DejaVuSans.ttf` (not shipped with the plugin) -> common Linux locations (`/usr/share/fonts/truetype/dejavu`, `/usr/share/fonts/truetype/noto`, provided by `fonts-dejavu` / `fonts-noto`). When no TTF is found the renderer logs a warning to stderr and falls back to ReportLab's Helvetica/Courier core fonts (Latin-1 only) -- never crashes. +- `scripts/generate_review_report.py`: `render_markdown_to_reportlab()` wraps the Markdown -> HTML -> ReportLab pass in try/except. On any failure (malformed input, parser exception, ReportLab mini-XML rejection) it logs a warning and falls back to a single XML-escaped preformatted block containing the raw source so no content is silently swallowed. ## [3.14.2] - 2026-05-05 diff --git a/agents/architect-nagatha.md b/agents/architect-nagatha.md index 0b56e28b..9c9e5a67 100644 --- a/agents/architect-nagatha.md +++ b/agents/architect-nagatha.md @@ -2,7 +2,7 @@ name: architect-nagatha description: "Use for system design, module boundaries, dependency review, architectural trade-offs, technology evaluation, library comparison, or validating plans before presenting to user." tools: ["Read", "Grep", "Glob", "Bash", "WebSearch", "WebFetch", "mcp__plugin_memcan_brain__search", "mcp__plugin_memcan_brain__search_memories", "mcp__plugin_memcan_brain__search_code", "mcp__plugin_memcan_brain__search_standards", "mcp__plugin_memcan_brain__add_memory", "mcp__plugin_claudius_github__get_file_contents", "mcp__plugin_claudius_github__search_repositories", "mcp__plugin_claudius_github__search_code", "mcp__plugin_claudius_github__pull_request_read", "mcp__plugin_claudius_github__list_pull_requests", "mcp__plugin_claudius_github__get_latest_release", "mcp__plugin_claudius_github__list_releases", "mcp__plugin_claudius_github__get_discussion", "mcp__plugin_claudius_github__get_discussion_comments"] -skills: ["security-best-practices", "rust-best-practices"] +skills: ["coding-best-practices", "security-best-practices", "rust-best-practices"] model: opus mcpServers: ["plugin_memcan_brain", "github"] --- diff --git a/agents/claudius.md b/agents/claudius.md index 6c41a7af..e1e44a3c 100644 --- a/agents/claudius.md +++ b/agents/claudius.md @@ -1,7 +1,7 @@ --- name: claudius description: "Personal software development assistant. Leads and coordinates development efforts. Always invoked when user interaction is needed." -skills: ["git-and-github", "severity", "grand-admiral"] +skills: ["coding-best-practices", "git-and-github", "severity", "grand-admiral"] memory: [user, project, local] model: opus[1m] mcpServers: ["plugin_memcan_brain", "github"] diff --git a/agents/qa-engineer-marvin.md b/agents/qa-engineer-marvin.md index f5607c96..82b4e887 100644 --- a/agents/qa-engineer-marvin.md +++ b/agents/qa-engineer-marvin.md @@ -3,7 +3,7 @@ name: qa-engineer-marvin description: "Use to validate that code matches requirements. Audits test coverage against specs, executes tests, and reports all mismatches." tools: ["Read", "Write", "Edit", "Grep", "Glob", "Bash", "Task", "mcp__plugin_memcan_brain__search", "mcp__plugin_memcan_brain__search_memories", "mcp__plugin_memcan_brain__search_code", "mcp__plugin_memcan_brain__search_standards", "mcp__plugin_memcan_brain__add_memory", "mcp__plugin_claudius_github__pull_request_read", "mcp__plugin_claudius_github__list_pull_requests", "mcp__plugin_claudius_github__issue_read", "mcp__plugin_claudius_github__list_issues", "mcp__plugin_claudius_github__search_issues", "mcp__plugin_claudius_github__actions_list", "mcp__plugin_claudius_github__actions_get", "mcp__plugin_claudius_github__get_job_logs"] model: opus -skills: ["security-best-practices", "severity", "report-format"] +skills: ["coding-best-practices", "security-best-practices", "severity", "report-format"] mcpServers: ["plugin_memcan_brain", "github"] --- diff --git a/agents/security-engineer-smythe.md b/agents/security-engineer-smythe.md index d23e7350..1022ccbc 100644 --- a/agents/security-engineer-smythe.md +++ b/agents/security-engineer-smythe.md @@ -2,7 +2,7 @@ name: security-engineer-smythe description: "Use for security audits, auth/crypto/input validation reviews, dependency scanning, secret detection, or validating plans before presenting to user." tools: ["Read", "Write", "Grep", "Glob", "Bash", "WebSearch", "WebFetch", "Task", "mcp__plugin_memcan_brain__search", "mcp__plugin_memcan_brain__search_memories", "mcp__plugin_memcan_brain__search_code", "mcp__plugin_memcan_brain__search_standards", "mcp__plugin_memcan_brain__add_memory", "mcp__plugin_claudius_github__list_code_scanning_alerts", "mcp__plugin_claudius_github__get_code_scanning_alert", "mcp__plugin_claudius_github__list_dependabot_alerts", "mcp__plugin_claudius_github__get_dependabot_alert", "mcp__plugin_claudius_github__list_secret_scanning_alerts", "mcp__plugin_claudius_github__get_secret_scanning_alert", "mcp__plugin_claudius_github__list_repository_security_advisories", "mcp__plugin_claudius_github__list_org_repository_security_advisories", "mcp__plugin_claudius_github__list_global_security_advisories", "mcp__plugin_claudius_github__get_global_security_advisory", "mcp__plugin_claudius_github__pull_request_read", "mcp__plugin_claudius_github__list_pull_requests", "mcp__plugin_claudius_github__search_code", "mcp__plugin_claudius_github__search_repositories", "mcp__plugin_claudius_github__get_file_contents", "mcp__plugin_claudius_github__get_commit", "mcp__plugin_claudius_github__list_commits"] -skills: ["security-best-practices", "severity", "report-format"] +skills: ["coding-best-practices", "security-best-practices", "severity", "report-format"] model: opus mcpServers: ["plugin_memcan_brain", "github"] --- diff --git a/agents/technical-writer-trillian.md b/agents/technical-writer-trillian.md index 160ef9a9..cc4843de 100644 --- a/agents/technical-writer-trillian.md +++ b/agents/technical-writer-trillian.md @@ -2,7 +2,7 @@ name: technical-writer-trillian description: "Use for creating, maintaining, or reviewing documentation — READMEs, API docs, tutorials, guides, changelogs, ADRs." tools: ["Read", "Write", "Edit", "Grep", "Glob", "Bash", "mcp__plugin_memcan_brain__search", "mcp__plugin_memcan_brain__search_memories", "mcp__plugin_memcan_brain__search_code", "mcp__plugin_memcan_brain__search_standards", "mcp__plugin_memcan_brain__add_memory", "mcp__plugin_claudius_github__pull_request_read", "mcp__plugin_claudius_github__list_pull_requests", "mcp__plugin_claudius_github__issue_read", "mcp__plugin_claudius_github__list_issues", "mcp__plugin_claudius_github__list_releases", "mcp__plugin_claudius_github__get_latest_release", "mcp__plugin_claudius_github__get_release_by_tag", "mcp__plugin_claudius_github__list_tags", "mcp__plugin_claudius_github__get_file_contents", "mcp__plugin_claudius_github__get_discussion", "mcp__plugin_claudius_github__get_discussion_comments"] -skills: ["report-format"] +skills: ["coding-best-practices", "report-format"] model: sonnet mcpServers: ["plugin_memcan_brain", "github"] --- diff --git a/agents/ux-designer-diziet.md b/agents/ux-designer-diziet.md index 21640c62..5dbc967a 100644 --- a/agents/ux-designer-diziet.md +++ b/agents/ux-designer-diziet.md @@ -2,7 +2,7 @@ name: ux-designer-diziet description: "Use at project start for requirements, domain analysis, stakeholder mapping, or during design for UI flows, interaction patterns, usability, accessibility, and validating plans before presenting to user." tools: ["Read", "Write", "Edit", "Grep", "Glob", "WebSearch", "WebFetch", "mcp__plugin_memcan_brain__search", "mcp__plugin_memcan_brain__search_memories", "mcp__plugin_memcan_brain__search_code", "mcp__plugin_memcan_brain__search_standards", "mcp__plugin_memcan_brain__add_memory", "mcp__plugin_claudius_github__pull_request_read", "mcp__plugin_claudius_github__list_pull_requests", "mcp__plugin_claudius_github__issue_read", "mcp__plugin_claudius_github__list_issues", "mcp__plugin_claudius_github__search_issues", "mcp__plugin_claudius_github__list_issue_types", "mcp__plugin_claudius_github__get_label", "mcp__plugin_claudius_github__get_discussion", "mcp__plugin_claudius_github__get_discussion_comments", "mcp__plugin_claudius_github__list_discussions", "mcp__plugin_claudius_github__list_discussion_categories"] -skills: [] +skills: ["coding-best-practices"] model: opus memory: user mcpServers: ["plugin_memcan_brain", "github"] diff --git a/schemas/review-report.schema.json b/schemas/review-report.schema.json index 84eb979c..f3636500 100644 --- a/schemas/review-report.schema.json +++ b/schemas/review-report.schema.json @@ -95,6 +95,7 @@ "security": { "type": "integer", "minimum": 0 }, "project": { "type": "integer", "minimum": 0 }, "code_quality": { "type": "integer", "minimum": 0 }, + "call_tree": { "type": "integer", "minimum": 0 }, "dependencies": { "type": "integer", "minimum": 0 }, "documentation": { "type": "integer", "minimum": 0 }, "pr_comments": { "type": "integer", "minimum": 0 }, @@ -226,8 +227,8 @@ "properties": { "id": { "type": "string", - "pattern": "^(SEC|QA|PROJ|CODE|RUST|PY|GO|FE|DOC|CMT|DEP|PPM)-\\d{3}$", - "description": "Finding ID with category prefix (SEC→security, PROJ→project, CODE/RUST/PY/GO/FE→code_quality, DOC→documentation, CMT→pr_comments, DEP→dependencies, PPM→pr_promises)" + "pattern": "^(SEC|QA|PROJ|CODE|RUST|PY|GO|FE|DOC|CMT|DEP|PPM|CALL)-\\d{3}$", + "description": "Finding ID with category prefix (SEC→security, PROJ→project, CODE/RUST/PY/GO/FE/QA→code_quality, DOC→documentation, CMT→pr_comments, DEP→dependencies, PPM→pr_promises, CALL→call_tree)" }, "severity": { "$ref": "#/$defs/severity" }, "risk": { "$ref": "#/$defs/severity_float", "description": "OWASP Likelihood normalized to [0,1]." }, @@ -292,7 +293,7 @@ "subtitle": { "type": "string" }, "category": { "type": "string", - "enum": ["security", "project", "code_quality", "dependencies", "documentation", "pr_comments", "pr_promises"] + "enum": ["security", "project", "code_quality", "call_tree", "dependencies", "documentation", "pr_comments", "pr_promises"] }, "findings": { "type": "array", diff --git a/scripts/consolidate_reports.py b/scripts/consolidate_reports.py index 0b61ebd5..b29c219c 100644 --- a/scripts/consolidate_reports.py +++ b/scripts/consolidate_reports.py @@ -69,6 +69,7 @@ "security": "SEC-", "project": "PROJ-", "code_quality": "CODE-", + "call_tree": "CALL-", "documentation": "DOC-", "pr_comments": "CMT-", "pr_promises": "PPM-", diff --git a/scripts/generate_review_report.py b/scripts/generate_review_report.py index 184f9e62..c858c5e0 100644 --- a/scripts/generate_review_report.py +++ b/scripts/generate_review_report.py @@ -94,6 +94,7 @@ "security": "Security", "project": "Project", "code_quality": "Code Quality", + "call_tree": "Call-Tree Inspection", "documentation": "Documentation", "dependencies": "Dependencies", "pr_comments": "PR Comments", @@ -552,10 +553,11 @@ def render_markdown(data: dict[str, Any]) -> str: "security": "Part I: Security Findings", "project": "Part II: Project Consistency", "code_quality": "Part III: Code Quality & Language Best Practices", - "dependencies": "Part IV: Dependencies", - "documentation": "Part V: Documentation", - "pr_comments": "Part VI: PR Comment Verification", - "pr_promises": "Part VII: PR Promise Verification", + "call_tree": "Part IV: Call-Tree Inspection", + "dependencies": "Part V: Dependencies", + "documentation": "Part VI: Documentation", + "pr_comments": "Part VII: PR Comment Verification", + "pr_promises": "Part VIII: PR Promise Verification", } for section in data.get("findings", []): cat = section.get("category", "") @@ -921,6 +923,7 @@ def render_markdown(data: dict[str, Any]) -> str: + @@ -1222,7 +1225,8 @@ def render_markdown(data: dict[str, Any]) -> str: const sevLabels = {5:"CRITICAL",4:"HIGH",3:"MEDIUM",2:"LOW",1:"INFO"}; const sevColors = {{ sev_colors_json }}; const catLabels = {"security":"Security","project":"Project Consistency", - "code_quality":"Code Quality","documentation":"Documentation", + "code_quality":"Code Quality","call_tree":"Call-Tree Inspection", + "documentation":"Documentation", "dependencies":"Dependencies","pr_comments":"PR Comments", "pr_promises":"PR Promises"}; @@ -1872,6 +1876,7 @@ def render_triage(data: dict[str, Any]) -> str: + diff --git a/scripts/lint_ephemeral_ids.py b/scripts/lint_ephemeral_ids.py new file mode 100755 index 00000000..dc6167d6 --- /dev/null +++ b/scripts/lint_ephemeral_ids.py @@ -0,0 +1,207 @@ +#!/usr/bin/env python3 +"""Dumb advisory lint for ephemeral review-finding IDs in committed artifacts. + +Ephemeral IDs (e.g. CMT-001, SEC-014, RUST-123, CALL-005) are reassigned every +time the consolidator runs and become dead references after merge. They must +never appear in committed source code, comments, or docs. + +Permanent IDs (ADR-NNN, RFC-NNN, CWE-NNN, CVE-YYYY-NNNN, OWASP-*, GHSA, GH +issue/PR refs, TODO/FIXME, committed test-spec IDs) are NOT flagged by this +lint — only the consolidator-owned prefix set is matched. + +The prefix set is imported from ``consolidate_reports`` to make drift between +this lint and the consolidator structurally impossible. ``QA-`` is included as +a known code-quality language sub-prefix that the schema accepts; the rest +come straight from ``CATEGORY_PREFIX`` and ``CODE_QUALITY_PREFIXES``. + +## Usage + + # File mode (default): scan every line of each file + python3 lint_ephemeral_ids.py path/to/file.md path/to/another.py + + # Diff mode: read a unified diff from stdin (or `git diff $BASE...HEAD`) + # and report only added (`+`) lines. + git diff $BASE...HEAD | python3 lint_ephemeral_ids.py --diff + + # Text output for human eyeballing + python3 lint_ephemeral_ids.py --format text path/to/file.md + +The script ALWAYS exits 0 — this is advisory. Reviewer skills decide whether +each hit is a genuine violation or an in-skill example block that demonstrates +the rule. The intentional false positives in the lint's own docstrings and in +the skill files demonstrating this rule are by design: keep the lint dumb. +""" + +from __future__ import annotations + +import argparse +import json +import re +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parent)) +from consolidate_reports import CATEGORY_PREFIX, CODE_QUALITY_PREFIXES # noqa: E402 + +# Build the prefix set from the consolidator's source of truth. Strip the +# trailing "-" so we can rebuild the regex on the alphabetic stems. +# ``QA-`` is added explicitly: the schema (review-report.schema.json) accepts +# it as a code-quality language sub-prefix even though the consolidator's +# Python dicts don't declare it. The drift test asserts this remains a +# SUPERSET of the consolidator's set. +_EXTRA_PREFIXES = {"QA-"} +PREFIXES: frozenset[str] = frozenset( + set(CATEGORY_PREFIX.values()) | set(CODE_QUALITY_PREFIXES) | _EXTRA_PREFIXES +) +_STEMS = sorted(p.rstrip("-") for p in PREFIXES) +PATTERN = re.compile(r"\b(" + "|".join(_STEMS) + r")-\d{3}\b") + + +def scan_text(text: str, source: str, *, line_offset: int = 0) -> list[dict]: + """Scan a block of text and return one hit per match. + + ``line_offset`` lets the caller shift reported line numbers when the text + is a slice of a larger document (e.g. diff hunks). The default 0 means + line numbers are 1-based relative to ``text``. + """ + hits: list[dict] = [] + for idx, line in enumerate(text.splitlines(), start=1): + for match in PATTERN.finditer(line): + hits.append( + { + "file": source, + "line": idx + line_offset, + "line_text": line.rstrip(), + "matched_id": match.group(0), + } + ) + return hits + + +def scan_file(path: Path) -> list[dict]: + """Scan every line of a file and return hits.""" + try: + text = path.read_text(encoding="utf-8", errors="replace") + except OSError as e: + print(f"WARN: cannot read {path}: {e}", file=sys.stderr) + return [] + return scan_text(text, str(path)) + + +_HUNK_HEADER = re.compile(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@") +_FILE_HEADER = re.compile(r"^\+\+\+ b/(.+)$") + + +def scan_diff(diff_text: str) -> list[dict]: + """Scan a unified diff and report only added (`+`) lines. + + File names come from ``+++ b/`` headers. Line numbers come from the + hunk header's new-file start, incremented for each context (` `) and + added (`+`) line; removed (`-`) lines do not advance the new-file pointer. + Skips diff metadata lines (``---``, ``+++``, ``@@``, ``diff``, ``index``) + and the ``\\ No newline at end of file`` marker (which is metadata, not + content, and must not advance the new-file pointer). + """ + hits: list[dict] = [] + current_file = "" + new_line = 0 + + for raw in diff_text.splitlines(): + if raw.startswith("+++ "): + m = _FILE_HEADER.match(raw) + if m: + current_file = m.group(1) + continue + if ( + raw.startswith("--- ") + or raw.startswith("diff ") + or raw.startswith("index ") + ): + continue + if raw.startswith("\\ "): + # "\ No newline at end of file" — diff metadata, not content. + continue + m = _HUNK_HEADER.match(raw) + if m: + new_line = int(m.group(1)) + continue + if raw.startswith("+"): + content = raw[1:] + for match in PATTERN.finditer(content): + hits.append( + { + "file": current_file, + "line": new_line, + "line_text": content.rstrip(), + "matched_id": match.group(0), + } + ) + new_line += 1 + elif raw.startswith("-"): + continue + else: + new_line += 1 + return hits + + +def format_text(hits: list[dict]) -> str: + """Render hits as one-line-per-hit human-readable text.""" + if not hits: + return "" + return "\n".join( + f"{h['file']}:{h['line']}: {h['matched_id']}: {h['line_text']}" for h in hits + ) + + +def parse_args(argv: list[str] | None = None) -> argparse.Namespace: + parser = argparse.ArgumentParser( + description=( + "Dumb advisory lint for ephemeral review-finding IDs " + "(CMT-/SEC-/RUST-/CALL-/etc.) in committed artifacts. " + "Always exits 0; the reviewer dismisses in-skill example matches." + ) + ) + parser.add_argument( + "files", + nargs="*", + type=Path, + help="Files to scan (file mode). Ignored when --diff is set.", + ) + parser.add_argument( + "--diff", + action="store_true", + help="Read a unified diff from stdin and report only added (`+`) lines.", + ) + parser.add_argument( + "--format", + choices=("json", "text"), + default="json", + help="Output format (default: json).", + ) + return parser.parse_args(argv) + + +def main(argv: list[str] | None = None) -> int: + args = parse_args(argv) + hits: list[dict] = [] + + if args.diff: + diff_text = sys.stdin.read() + hits = scan_diff(diff_text) + else: + for path in args.files: + hits.extend(scan_file(path)) + + if args.format == "json": + json.dump(hits, sys.stdout, ensure_ascii=False, indent=2) + sys.stdout.write("\n") + else: + text = format_text(hits) + if text: + print(text) + + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/requirements.txt b/scripts/requirements.txt index 2aab4abd..dff68a88 100644 --- a/scripts/requirements.txt +++ b/scripts/requirements.txt @@ -8,3 +8,4 @@ markupsafe>=2.0 matplotlib>=3.7 reportlab>=4.0 jsonschema>=4.0 +PyYAML>=6.0 diff --git a/skills/check-pr-comments/SKILL.md b/skills/check-pr-comments/SKILL.md index 44bf7833..56d39f68 100644 --- a/skills/check-pr-comments/SKILL.md +++ b/skills/check-pr-comments/SKILL.md @@ -1,7 +1,7 @@ --- name: check-pr-comments description: Use to verify PR review comments are addressed in code. Optionally produces triage-compatible report. -allowed-tools: Read, Write, Grep, Glob, Bash(gh pr checkout *), Bash(gh pr view *), Bash(git pull *), Bash(git fetch *), Bash(*validate_report.py *), Bash(*generate_review_report.py *), Bash(*gh-fetch-review-comments.sh *), Bash(*gh-fetch-reviews.sh *), Bash(*gh-list-review-threads.sh *), Bash(*gh-resolve-review-threads.sh *), mcp__plugin_claudius_github__pull_request_read, mcp__plugin_claudius_github__add_reply_to_pull_request_comment, mcp__plugin_claudius_github__add_issue_comment +allowed-tools: Read, Write, Grep, Glob, Bash(gh pr checkout *), Bash(gh pr view *), Bash(git pull *), Bash(git fetch *), Bash(git log *), Bash(git diff *), Bash(git rev-parse *), Bash(git show *), Bash(*validate_report.py *), Bash(*generate_review_report.py *), Bash(*gh-fetch-review-comments.sh *), Bash(*gh-fetch-reviews.sh *), Bash(*gh-list-review-threads.sh *), Bash(*gh-resolve-review-threads.sh *), Bash(which *), Bash(rg *), Bash(ctags *), Bash(global *), Bash(gtags *), Bash(tree-sitter *), Bash(gh search code*), mcp__plugin_claudius_github__pull_request_read, mcp__plugin_claudius_github__add_reply_to_pull_request_comment, mcp__plugin_claudius_github__add_issue_comment --- # Check PR Comments Workflow @@ -31,7 +31,7 @@ git pull ## 3. Verify Each Comment Against Current Code -For every inline comment, read the file at the referenced location and **verify whether the identified issue is actually fixed** -- not just whether the code changed. Specifically: +When verifying resolution, apply `coding-best-practices` Cross-Cutting Rules to the changed code. For every inline comment, read the file at the referenced location and **verify whether the identified issue is actually fixed** -- not just whether the code changed. Specifically: - **Verify state before resolving — broad instructions are not authorization.** Before classifying any thread as resolved, verify the actual code state at the referenced location matches the reviewer's request. Do NOT mark a thread resolved based on the user's blanket instruction ("just resolve everything") or on a follow-up commit message that *claims* to fix it. If a thread cannot be verified resolved against current code, classify it as `Unresolved` with an explicit "needs verification" recommendation. Surface the mismatch — never silently resolve. (Specific application of `coding-best-practices` Cross-Cutting Rules — "Verify facts before acting on broad instructions".) - Read the current code at the location the comment references @@ -40,6 +40,7 @@ For every inline comment, read the file at the referenced location and **verify - For comments with multiple sub-items, verify each one independently - A comment is only "resolved" if **all** of its sub-items are addressed - Verify the fix achieves the intended end-user or developer experience, not just technical correctness +- **Call-tree walk on touched functions**: if the comment references a function whose body or signature was modified in the resolution commits (`git diff $RESOLUTION_BASE...HEAD -- `), run the deep transitive in-repo caller walk per [../grumpy-review/references/call-tree-walk.md](../grumpy-review/references/call-tree-walk.md) on that function before declaring the thread resolved. A caller that still depends on the old contract turns a "fixed" thread into Unresolved with a CALL-tagged follow-up. **Classify each comment's author:** - **Bot**: username ends with `[bot]` (e.g. `dependabot[bot]`) or the GitHub API returns `type: "Bot"` for the author diff --git a/skills/coding-best-practices/SKILL.md b/skills/coding-best-practices/SKILL.md index 4a813dfc..e209edb6 100644 --- a/skills/coding-best-practices/SKILL.md +++ b/skills/coding-best-practices/SKILL.md @@ -36,6 +36,7 @@ Use the `report-format` skill for output structure. IDs are provisional (consoli - **Comment only when meaningful**: only add comments that provide context not obvious from the code itself. Don't comment self-explanatory code, simple one-liners, or anything a competent developer would understand at a glance. When a comment *is* needed: 1 line is great, 2 lines are good, 3 is mediocre — if you need more, the code itself should be clearer. - **Describe present state, not history**: comments document what code does NOW and why. Historical context — refactors, prior approaches, renames, evolution, "previously did X", "TODO: clean up old approach" — belongs in commit messages and PR descriptions. The reader has `git blame`. Acceptable exceptions are rare: citing an external constraint (upstream issue, RFC, kernel API quirk) that justifies a non-obvious current choice. Composes with `rust-best-practices` M-NO-TOMBSTONES — same principle, different framing. - **Two audiences, two budgets**: the line cap above is strict for internal commentary (≤2 lines preferred, 3 mediocre): inline `//` comments, private/non-`pub` rustdoc, module headers that just rephrase the file name. The cap relaxes to 5–10 lines for **public API rustdoc** that genuinely teaches downstream callers — parameters, return values, preconditions, error semantics, panic conditions, one-line examples. Both tiers obey present-state. The relaxation is on length, not on history. (See `rust-best-practices` C-EXAMPLE, C-FAILURE, M-FIRST-DOC-SENTENCE, M-CANONICAL-DOCS.) +- **No ephemeral review IDs in committed artifacts**: never reference transient review-finding IDs (`CMT-001`, `SEC-014`, `CODE-007`, `RUST-123`, `PROJ-002`, `CALL-005`, etc.) in source code, comments, READMEs, or any other committed file. These IDs are reassigned every time the consolidator runs and become dead references after merge. Allowed ID forms (permanent / standards-body / repo-permanent) include `ADR-NNN`, `RFC-NNN`, `CWE-NNN`, `CVE-YYYY-NNNN`, `OWASP-A0N` / `OWASP-LLM0N` / `OWASP-API0N`, ATT&CK IDs, `GHSA-…`, GitHub issue/PR refs (`#1234`, `org/repo#1234`), `TODO` / `FIXME` / `XXX` / `HACK` comments, and test-case IDs from a committed test-spec document. Rule of thumb: if the ID is born inside a regenerated JSON / triage report, it's forbidden in committed code; if the ID lives in a committed Markdown / YAML / standards-body doc, it's fine. Enforced advisory by `scripts/lint_ephemeral_ids.py` (reviewer-side) and by every developer agent that preloads this skill (write-side). - **UX/DX awareness**: before fixing an issue, understand the desired end-user or developer experience — a technically correct fix that breaks the user's mental model is not correct. - **Standards lookup**: use `search_standards` MCP tool (if available) to check coding and security standards when facing unfamiliar patterns or compliance questions. - **Verify dependency versions**: when adding new crates or packages, use WebSearch to check the latest published version on the official registry (crates.io, PyPI, npm, pkg.go.dev) and specify that exact version. Never guess or rely on memory for version numbers. diff --git a/skills/grumpy-review/SKILL.md b/skills/grumpy-review/SKILL.md index 3b39d6c4..590db355 100644 --- a/skills/grumpy-review/SKILL.md +++ b/skills/grumpy-review/SKILL.md @@ -4,7 +4,7 @@ description: "Parallel-agent code review for quality, security, dependencies, an agent: claudius context: fork model: opus -allowed-tools: Read, Grep, Glob, Write, Edit, Bash(git log *), Bash(git diff *), Bash(git rev-parse *), Bash(git show *), Bash(cargo audit *), Bash(npm audit *), Bash(pip-audit *), Bash(govulncheck *), Bash(*consolidate_reports.py *), Bash(*validate_report.py *), Bash(*generate_review_report.py *), Bash(mkdir *), Task, TaskCreate, TaskUpdate, TaskList, TaskGet, SendMessage +allowed-tools: Read, Grep, Glob, Write, Edit, Bash(git log *), Bash(git diff *), Bash(git rev-parse *), Bash(git show *), Bash(cargo audit *), Bash(npm audit *), Bash(pip-audit *), Bash(govulncheck *), Bash(*consolidate_reports.py *), Bash(*validate_report.py *), Bash(*generate_review_report.py *), Bash(*lint_ephemeral_ids.py *), Bash(which *), Bash(rg *), Bash(ctags *), Bash(global *), Bash(gtags *), Bash(tree-sitter *), Bash(gh search code*), Bash(mkdir *), Task, TaskCreate, TaskUpdate, TaskList, TaskGet, SendMessage --- # Code Review Methodology @@ -92,9 +92,10 @@ every review agent prompt MUST include these review-specific elements: 1. **Comparison base**: How to see what changed (`git show :` or `git diff`) 2. **Finding format**: Use the severity levels and structure defined below 3. **Review checklists**: Embed relevant checklist content or rely on the agent's preloaded skills -4. **UX/DX lens**: instruct agents to assess how findings affect end-user workflows and developer experience, not just code correctness -5. **CI context**: When MemCan/WebSearch are unavailable (e.g., CI), instruct agents: "Do not use memcan tools or WebSearch/WebFetch." -6. **File output**: Instruct agents to use the Write tool for creating files — never `cat > file` or heredoc redirections. +4. **BP preload**: every spawned reviewer agent (`security-engineer-smythe`, `project-reviewer-adams`, `developer-bilby`, `technical-writer-trillian`, etc.) MUST preload `coding-best-practices` so its Cross-Cutting Rules govern every finding — state this explicitly in each spawn prompt. +5. **UX/DX lens**: instruct agents to assess how findings affect end-user workflows and developer experience, not just code correctness +6. **CI context**: When MemCan/WebSearch are unavailable (e.g., CI), instruct agents: "Do not use memcan tools or WebSearch/WebFetch." +7. **File output**: Instruct agents to use the Write tool for creating files — never `cat > file` or heredoc redirections. ### Finding format (JSON) @@ -105,7 +106,7 @@ Each agent writes its output to the specified file path as valid JSON: [ { "title": "Section Title", - "category": "security|project|code_quality|dependencies|documentation", + "category": "security|project|code_quality|dependencies|documentation|call_tree", "findings": [ { "id": "PREFIX-001", @@ -136,7 +137,7 @@ Each agent writes its output to the specified file path as valid JSON: **Metadata**: emit `metadata.commit` as the full 40-character SHA (`git rev-parse HEAD`, not `--short`); omit when not in a git repo. The coordinator derives `metadata.repository` from `git remote get-url origin` — producers do not emit it. -**ID prefixes**: `SEC-` security, `PROJ-` project, `RUST-`/`PY-`/`GO-`/`FE-` language, `DOC-` docs. +**ID prefixes**: `SEC-` security, `PROJ-` project, `RUST-`/`PY-`/`GO-`/`FE-` language, `DOC-` docs, `CALL-` call-tree. Agents assign provisional sequential IDs within their prefix (e.g., `SEC-001`, `SEC-002`). IDs may collide across parallel agents — the consolidation step (5c) deduplicates and reassigns final IDs. @@ -148,6 +149,24 @@ final IDs. **Tags**: classification references — OWASP (`A01`–`A10`), CWE, language best-practice IDs, etc. Tag ALL security findings with OWASP categories. Non-security findings may omit tags. +### Call-tree inspection + +When the diff modifies or removes any function/method declaration, every code-quality reviewer agent MUST run a deep transitive in-repo caller walk before emitting findings. Methodology lives in [references/call-tree-walk.md](references/call-tree-walk.md) — read it once per review and follow the steps. + +Finding shape: `category: "call_tree"`, ID prefix `CALL-` (coordinator-assigned). The producer emits a provisional `CALL-NNN`. Every `call_tree` finding's `description` MUST start with a `Walked via: ` line so the reader can judge walk depth and tool quality. + +Skip the walk for pure additions, doc-only PRs, and changes confined to test files. + +### Ephemeral-ID lint + +After each agent emits findings, run the dumb ephemeral-ID lint against the diff: + +```bash +git diff $BASE_BRANCH...HEAD | python3 ${CLAUDE_SKILL_DIR}/../../scripts/lint_ephemeral_ids.py --diff +``` + +For each hit, judge whether the surrounding context is a genuine violation or a quoted/escaped example (e.g. a code fence inside a skill file demonstrating the rule, a test fixture asserting the rule, or this lint's own docstring). Dismiss in-skill examples; promote genuine violations to `code_quality` findings with `tags: ["ephemeral-id-reference"]` and ID prefix `CODE-` (coordinator-assigned). The lint always exits 0 — judgement is yours. + ## 4. Spawn Agents Spawn all agents in parallel following the general spawning guidelines. Use `model: "opus"` diff --git a/skills/grumpy-review/references/call-tree-walk.md b/skills/grumpy-review/references/call-tree-walk.md new file mode 100644 index 00000000..61b275e2 --- /dev/null +++ b/skills/grumpy-review/references/call-tree-walk.md @@ -0,0 +1,179 @@ +# Call-Tree Walk Methodology + +Authoritative recipe for deep transitive in-repo caller analysis on a PR. Referenced by `grumpy-review`, `review-pr`, and `check-pr-comments` skills. + +## Outcome + +For every function modified by the diff, surface every transitive in-repo caller whose assumption-set is invalidated by the new contract. Findings name the caller's `file:line`, the assumption that was broken, and the chain back to the modified function. + +## When to Run + +Trigger only when `git diff $BASE_BRANCH...HEAD` shows modified or removed function/method declarations. Skip for: + +- Pure additions (new functions, no callers exist yet). +- Doc-only PRs. +- Comment-only or whitespace-only diffs. +- Changes confined to test files (callers are tests; the walk is noise). + +A signature change without a body change still triggers — callers may depend on the old signature. + +## Step 1 — Inventory Modified Functions + +Enumerate every modified/removed function or method declaration from the diff. For each entry record: + +- Fully qualified name (`module::path::function` for Rust, `package.Type.method` for Go, `pkg.module.func` for Python, `Class#method` for JS/TS). +- Language. +- Visibility: `public` / `private` / `trait-or-interface-impl` / `leaf`. +- Change shape: `signature-changed` / `body-only`. +- Source location (`path:line`). + +Drop pure additions — they have no in-repo callers yet. + +## Step 2 — Rank and Truncate + +Score each entry on these dimensions (higher = more risk): + +| Dimension | High risk | Low risk | +|---|---|---| +| Visibility | public, trait/interface impl | private, leaf | +| Change shape | signature-changed | body-only | +| Module reach | widely-imported module, core trait | local utility, test helper | + +Order descending by composite risk. Keep the **top 10** and walk those. Defer the rest. + +Emit one INFO finding listing every modified function, marking which were walked vs deferred and why: + +```text +category: "call_tree" +id: CALL-NNN (coordinator-assigned) +risk: 0.1 +impact: 0.1 +scope: 0.3 +title: "Call-tree walk scoped to top 10 of N modified functions" +description: | + Walked via: + Walked: foo::bar, foo::baz, ... + Deferred (lower risk): foo::leaf_util, ... +``` + +## Step 3 — Probe Tooling + +Discover what the environment offers. Run cheap `which` probes once, cache the answers — `which` is the only detection primitive on every skill's allow-list, so prefer it over `test -f`/`ps -e` (which the sandbox blocks): + +```bash +which ctags global gtags rg ripgrep tree-sitter 2>/dev/null +``` + +The probe order is tool-agnostic — pick whatever the environment actually offers. Suggested order: + +| Tier | Tool | When | +|---|---|---| +| Best | `ctags -R --languages=` (universal-ctags) | Language-aware, fast, scriptable | +| Best | GNU global (`gtags` + `global -r `) | Language-aware, fastest cross-ref | +| Good | `tree-sitter query` | When grammar is installed; precise AST queries | +| OK | `gh search code repo:/ ""` | Cross-repo same-org (limited rate) | +| Fallback | `rg -n --type ''` | Always available | + +Record which tool you used; every emitted `CALL-` finding must include `Walked via: ` (e.g. `Walked via: ctags + rg fallback`). + +### Fallback regex hints + +| Language | Caller-extraction regex | +|---|---| +| Rust | `\b(|::)\s*\(` plus `use .*::` for re-exports | +| Python | `\b\s*\(` plus `from .* import ` and `self\.\s*\(` | +| Go | `\b\s*\(` plus `\.\s*\(` for receiver methods | +| JS/TS | `\b\s*\(` plus `import.*\b\b` and `\.\s*\(` | + +## Step 4 — Walk + +BFS from each modified function. Track the caller chain via parent pointer. + +Caps (per function): + +- **Depth**: 5 hops. +- **Caller count**: 200 unique callers. +- **Wall-clock**: 60 seconds. + +Dedupe by `file:line`. When any cap trips, stop that walk and emit one `CALL-` INFO finding noting the truncation point and which cap fired: + +```text +title: "Call-tree walk truncated at depth 5 for foo::bar" +description: | + Walked via: + Stopped at depth 5 with 87 callers enumerated; further hops not explored. +``` + +Skip walks that visit only test files — record as deferred in the ranking finding. + +## Step 5 — Per-Caller Judgement + +For each terminal caller, re-read the caller's code around `file:line` and check whether the assumption-set still holds. Mismatches become `CALL-` findings. + +Assumptions to verify (per the modified function's new contract): + +1. **Signature**: argument types, count, defaults, generic bounds. +2. **Return shape**: type, `Option`/`Result` wrapping, ownership. +3. **Error contract**: error variant added/removed; `?` propagation still typechecks; previously infallible call now fallible. +4. **Panic vs Result**: previously panicked, now returns `Err` (or vice versa). +5. **Side effects**: added I/O, lock acquisition, allocation, log emission. +6. **Performance**: previously O(1) now O(n); previously non-blocking now blocking. +7. **Concurrency**: thread-safety, `Send`/`Sync`, async-ness change. +8. **Semantics**: same arguments now produce different output (e.g. retry policy changed, default value changed). + +For each broken assumption, emit a `CALL-` finding scoped to the caller's `file:line`. The chain back to the modified function goes in `description`. + +### Severity rubric (composes with `claudius:severity`) + +| Severity | When | +|---|---| +| CRITICAL | Removed/renamed symbol still referenced by callers — especially in dynamic languages where the bug surfaces at runtime, not at compile time | +| HIGH | Behaviour-breaking semantic change (panic→Result, sync→async, return-shape change) with multiple unupdated callers | +| MEDIUM | Behaviour-breaking change with a single isolated caller, or signature change callers must adapt to | +| LOW | Stylistic drift — callers still work but no longer match the new idiom | +| INFO | Ranking summary, truncation notes, deferred-walk notes | + +Score `risk`/`impact`/`scope` per `claudius:severity`; let the coordinator derive the integer. + +## Step 6 — Emit Findings + +Finding shape (one section per modified function whose walk surfaced callers, or one consolidated section for the whole PR — pick whichever is more readable): + +```json +{ + "title": "Call-Tree Inspection", + "category": "call_tree", + "findings": [ + { + "id": "CALL-001", + "risk": 0.6, + "impact": 0.5, + "scope": 0.5, + "title": "Caller foo::bar still treats baz() as infallible", + "location": "src/foo/bar.rs:142", + "description": "Walked via: ctags + rg fallback\nChain: src/foo/bar.rs:142 → baz() (modified at src/baz.rs:88)\nbaz() now returns Result; caller uses the value directly without `?` or matching on Err.", + "recommendation": "Propagate the error via `?` or handle Err explicitly.", + "code_snippets": [ + {"language": "rust", "caption": "src/foo/bar.rs:140-145", "content": "let x = baz();\nuse_x(x);"} + ] + } + ] +} +``` + +Required fields on every `call_tree` finding: + +- `category: "call_tree"`. +- `id`: `CALL-NNN` — the producer emits a provisional ID; the coordinator reassigns. +- `description`: MUST include a line `Walked via: ` and the chain ` → … → `. +- `code_snippets`: one snippet per terminal caller with `language` matching the repo. +- `location`: caller's `file:line` (not the modified function's location — the finding is about the caller). + +Optional but encouraged: `tags` such as `signature-change`, `return-shape`, `panic-to-result`. + +## Anti-Patterns + +- **Walking every modified function on a 200-file refactor**. Rank, truncate to top 10, surface the rest as deferred. +- **Treating compile-time-checked callers as automatically safe**. Rust/TS will catch shape mismatches at the type level, but semantic changes (retry policy, default value, panic→Result re-wrap) still slip through — read the caller. +- **Walking into test files and flagging them as broken**. Tests track the new contract by definition; treat them as expected callers and skip emission. +- **Skipping the `Walked via:` line**. Without it the reader can't judge how thorough the walk was. diff --git a/skills/release/SKILL.md b/skills/release/SKILL.md index 508b0566..35040397 100644 --- a/skills/release/SKILL.md +++ b/skills/release/SKILL.md @@ -1,6 +1,6 @@ --- name: release -description: Bump version (SemVer 2.0), update changelog, commit, push, and create GitHub release. Auto-detects project tech stack (Rust, Python, JS/TS, Claude Code plugins, etc.). Args: major|minor|patch or auto-detect from commits. User-invocable only — agents must not invoke this skill autonomously. +description: "Bump version (SemVer 2.0), update changelog, commit, push, and create GitHub release. Auto-detects project tech stack (Rust, Python, JS/TS, Claude Code plugins, etc.). Args: major|minor|patch or auto-detect from commits. User-invocable only — agents must not invoke this skill autonomously." user-invocable: true disable-model-invocation: true --- diff --git a/skills/report-format/SKILL.md b/skills/report-format/SKILL.md index bef1d33c..aff03fc5 100644 --- a/skills/report-format/SKILL.md +++ b/skills/report-format/SKILL.md @@ -18,7 +18,7 @@ Agents emit a JSON array of `finding_section` objects: [ { "title": "Section Title", - "category": "security|project|code_quality|dependencies|documentation|pr_comments|pr_promises", + "category": "security|project|code_quality|call_tree|dependencies|documentation|pr_comments|pr_promises", "findings": [ { "id": "PREFIX-001", @@ -106,6 +106,7 @@ When writing findings to a file, ALWAYS use the Write tool — never use Bash co | `CMT-` | pr_comments | check-pr-comments | | `PPM-` | pr_promises | review-pr (Pass C: promise verification) | | `DEP-` | dependencies | review-dependency | +| `CALL-` | call_tree | reviewer call-tree inspection pass | IDs are provisional -- the consolidation step deduplicates and reassigns final IDs. diff --git a/skills/review-pr/SKILL.md b/skills/review-pr/SKILL.md index c367df1c..22f643de 100644 --- a/skills/review-pr/SKILL.md +++ b/skills/review-pr/SKILL.md @@ -3,7 +3,7 @@ name: review-pr description: Use to review a PR for code quality, security, and correctness. agent: claudius context: fork -allowed-tools: Read, Grep, Glob, Write, Bash(gh pr comment *), Bash(*gh-post-review.sh *), Bash(*gh-pr-base-sha.sh *), Bash(*gh-fetch-review-comments.sh *), Bash(*gh-fetch-reviews.sh *), Bash(git log *), Bash(git diff *), Bash(git rev-parse *), Bash(git show *), Bash(cargo audit *), Bash(npm audit *), Bash(pip-audit *), Bash(govulncheck *), Task, TaskCreate, TaskUpdate, TaskList, TaskGet, SendMessage, mcp__plugin_claudius_github__pull_request_read, mcp__plugin_claudius_github__add_issue_comment, mcp__plugin_claudius_github__pull_request_review_write, mcp__plugin_claudius_github__add_comment_to_pending_review +allowed-tools: Read, Grep, Glob, Write, Bash(gh pr comment *), Bash(*gh-post-review.sh *), Bash(*gh-pr-base-sha.sh *), Bash(*gh-fetch-review-comments.sh *), Bash(*gh-fetch-reviews.sh *), Bash(git log *), Bash(git diff *), Bash(git rev-parse *), Bash(git show *), Bash(cargo audit *), Bash(npm audit *), Bash(pip-audit *), Bash(govulncheck *), Bash(*lint_ephemeral_ids.py *), Bash(which *), Bash(rg *), Bash(ctags *), Bash(global *), Bash(gtags *), Bash(tree-sitter *), Bash(gh search code*), Task, TaskCreate, TaskUpdate, TaskList, TaskGet, SendMessage, mcp__plugin_claudius_github__pull_request_read, mcp__plugin_claudius_github__add_issue_comment, mcp__plugin_claudius_github__pull_request_review_write, mcp__plugin_claudius_github__add_comment_to_pending_review --- # PR Audit Workflow @@ -36,6 +36,8 @@ Invoke the `/claudius:grumpy-review` skill with the PR scope as the argument. It Pass the PR's scope (changed files, base branch) as context to the review methodology. +The grumpy-review delegation also covers the deep transitive call-tree walk (`category: "call_tree"`, `CALL-` prefix; see [../grumpy-review/references/call-tree-walk.md](../grumpy-review/references/call-tree-walk.md)) and the ephemeral-ID lint step — both are inherited automatically by invoking `/claudius:grumpy-review`. After the review completes, run `git diff $BASE_BRANCH...HEAD | python3 ${CLAUDE_SKILL_DIR}/../../scripts/lint_ephemeral_ids.py --diff` against the PR diff and fold any genuine `code_quality` hits into the audit before posting. + ## 3. Pass C — Promise Verification Audit whether the diff delivers what the PR's own self-description claims. Reuses the PR title, body, file list, and diff already fetched in §1 — no extra MCP calls. diff --git a/tests/fixtures/reports/v3-call-tree.json b/tests/fixtures/reports/v3-call-tree.json new file mode 100644 index 00000000..10665f60 --- /dev/null +++ b/tests/fixtures/reports/v3-call-tree.json @@ -0,0 +1,52 @@ +{ + "schema_version": "3.0.0", + "metadata": { + "project": "claudius", + "date": "2026-05-28" + }, + "executive_summary": { + "overall_assessment": "Call-tree inspection fixture exercising the CALL- prefix and call_tree category end-to-end." + }, + "summary_statistics": { + "total_findings": 2, + "severity_counts": { + "CRITICAL": 0, + "HIGH": 1, + "MEDIUM": 1, + "LOW": 0, + "INFO": 0 + } + }, + "findings": [ + { + "title": "Call-Tree Inspection", + "category": "call_tree", + "findings": [ + { + "id": "CALL-001", + "risk": 0.7, + "impact": 0.7, + "scope": 1.0, + "severity": 4, + "overall_severity": 0.8, + "title": "Unchecked recursion into untrusted path", + "location": "src/walker.rs:120-145", + "description": "Following the call chain `walk_dir` -> `descend` -> `descend` shows no depth guard; an attacker-controlled directory tree can blow the stack.", + "recommendation": "Add an explicit recursion-depth limit and surface a typed error when it is exceeded." + }, + { + "id": "CALL-002", + "risk": 0.5, + "impact": 0.5, + "scope": 1.0, + "severity": 3, + "overall_severity": 0.6666666666666666, + "title": "Error swallowed two frames deep", + "location": "src/walker.rs:200-210", + "description": "Walking `process_entry` -> `try_open` -> `_` discards the underlying `io::Error` and substitutes a generic message.", + "recommendation": "Propagate the source error via `#[source]` so callers can distinguish missing-file from permission-denied." + } + ] + } + ] +} diff --git a/tests/test_bp_load_audit.py b/tests/test_bp_load_audit.py new file mode 100644 index 00000000..af40afbd --- /dev/null +++ b/tests/test_bp_load_audit.py @@ -0,0 +1,57 @@ +"""BP-load audit: every coding/reviewing agent must declare `coding-best-practices`. + +Cross-Cutting Rules (no tombstones, present-state comments, verify-before-act, +minimize code, etc.) only bind an agent when it preloads `coding-best-practices`. +Reviewer agents that omit the skill silently skip those rules, so audits hinge +on this regression guard. + +The curated list below is the project-level contract — adding a new +coding/reviewing agent? Add it here too. +""" + +from __future__ import annotations + +from pathlib import Path + +import pytest +import yaml + +REPO_ROOT = Path(__file__).resolve().parent.parent +AGENTS_DIR = REPO_ROOT / "agents" + +# Agents that write, edit, or review code. Each MUST load `coding-best-practices` +# so its Cross-Cutting Rules govern every action and finding. +BP_REQUIRED_AGENTS = [ + "architect-nagatha", + "claudius", + "developer-bilby", + "project-reviewer-adams", + "qa-engineer-marvin", + "security-engineer-smythe", + "technical-writer-trillian", + "ux-designer-diziet", +] + + +def _load_frontmatter(agent_name: str) -> dict: + path = AGENTS_DIR / f"{agent_name}.md" + text = path.read_text(encoding="utf-8") + parts = text.split("---", 2) + assert len(parts) >= 3, f"{path}: no `---` frontmatter delimiters found" + data = yaml.safe_load(parts[1]) + assert isinstance(data, dict), f"{path}: frontmatter did not parse to a dict" + return data + + +@pytest.mark.parametrize("agent_name", BP_REQUIRED_AGENTS) +def test_agent_loads_coding_best_practices(agent_name: str) -> None: + fm = _load_frontmatter(agent_name) + skills = fm.get("skills", []) + assert isinstance(skills, list), ( + f"agents/{agent_name}.md: `skills` field must be a list, got {type(skills).__name__}" + ) + assert "coding-best-practices" in skills, ( + f"agents/{agent_name}.md: missing `coding-best-practices` in `skills` frontmatter " + f"(found: {skills}). Reviewer/coder agents must preload BP so its " + f"Cross-Cutting Rules govern every finding." + ) diff --git a/tests/test_consolidate_reports.py b/tests/test_consolidate_reports.py index d0c6b57d..b6a48a4b 100644 --- a/tests/test_consolidate_reports.py +++ b/tests/test_consolidate_reports.py @@ -312,6 +312,33 @@ def test_in_place_mutation_of_findings(self, make_finding, make_section): # The original finding object should have been mutated assert "id" in f + def test_call_tree_category_gets_call_prefix_and_populates_matrix( + self, make_finding, make_section + ): + """Stream A: the call_tree category must assign sequential CALL-NNN + IDs and the resulting matrix row must carry the call_tree column.""" + sections = [ + make_section( + category="call_tree", + title="Call-Tree Inspection", + findings=[ + make_finding(severity=4, title="Unbounded recursion"), + make_finding(severity=3, title="Swallowed error two frames deep"), + ], + ), + ] + cr.assign_ids(sections) + ids = [f["id"] for f in sections[0]["findings"]] + assert ids == ["CALL-001", "CALL-002"], ids + stats = cr.compute_statistics(sections, []) + matrix_by_sev = {row["severity"]: row for row in stats["severity_category_matrix"]} + assert matrix_by_sev["HIGH"]["call_tree"] == 1 + assert matrix_by_sev["MEDIUM"]["call_tree"] == 1 + # The original code_quality column must NOT pick up the call_tree counts — + # call_tree is its own category, NOT folded into code_quality. + assert matrix_by_sev["HIGH"]["code_quality"] == 0 + assert matrix_by_sev["MEDIUM"]["code_quality"] == 0 + # --------------------------------------------------------------------------- # compute_statistics diff --git a/tests/test_lint_ephemeral_ids.py b/tests/test_lint_ephemeral_ids.py new file mode 100644 index 00000000..a0a1fc32 --- /dev/null +++ b/tests/test_lint_ephemeral_ids.py @@ -0,0 +1,266 @@ +"""Tests for scripts/lint_ephemeral_ids.py. + +Covers: +- Positive matches across every consolidator prefix. +- Negative cases for the documented allow-list (ADR/RFC/CWE/CVE/OWASP/GHSA/etc.). +- Word-boundary edge cases (5-digit suffix rejected, no-boundary prefix rejected). +- ``--diff`` parsing (only added lines, line numbers from hunk headers). +- Prefix-source-of-truth assertion: lint's PREFIXES is a superset of the + consolidator's CATEGORY_PREFIX values. +""" + +from __future__ import annotations + +import json +import subprocess +import sys +from pathlib import Path + +import pytest + +REPO_ROOT = Path(__file__).resolve().parent.parent +SCRIPT = REPO_ROOT / "scripts" / "lint_ephemeral_ids.py" + +# Make the script importable for direct API tests. +sys.path.insert(0, str(REPO_ROOT / "scripts")) +import lint_ephemeral_ids as lint # noqa: E402 +from consolidate_reports import CATEGORY_PREFIX # noqa: E402 + + +# --------------------------------------------------------------------------- +# Positive cases — every consolidator-owned prefix +# --------------------------------------------------------------------------- +POSITIVE_CASES = [ + "CMT-001", + "SEC-014", + "RUST-123", + "CALL-005", + "PPM-002", + "DEP-007", + "CODE-099", + "QA-100", + "PROJ-001", + "PY-042", + "GO-007", + "FE-111", + "DOC-002", +] + + +@pytest.mark.parametrize("token", POSITIVE_CASES) +def test_positive_match(token: str) -> None: + hits = lint.scan_text(f"prefix {token} suffix", "") + assert len(hits) == 1 + assert hits[0]["matched_id"] == token + + +# --------------------------------------------------------------------------- +# Negative cases — documented allow-list +# --------------------------------------------------------------------------- +NEGATIVE_CASES = [ + "ADR-007", + "RFC-2119", + "CWE-79", + "CVE-2024-1234", + "OWASP-A02", + "OWASP-LLM01", + "OWASP-API03", + "GHSA-abc1-def2-ghi3", + "#1234", + "org/repo#42", + "TODO", + "FIXME", + "XXX", + "HACK", + "TS-001", # test-spec, not in consolidator set + "T-1234", # too short prefix +] + + +@pytest.mark.parametrize("token", NEGATIVE_CASES) +def test_negative_no_match(token: str) -> None: + hits = lint.scan_text(f"prefix {token} suffix", "") + assert hits == [] + + +# --------------------------------------------------------------------------- +# Word-boundary edges +# --------------------------------------------------------------------------- +def test_five_digit_suffix_rejected() -> None: + """Regex requires exactly 3 digits — 5-digit IDs are NOT ephemeral.""" + hits = lint.scan_text("see RUST-12345 docs", "") + assert hits == [] + + +def test_no_left_word_boundary_rejected() -> None: + """XRUST-001 must NOT match — the X eats the left \\b.""" + hits = lint.scan_text("token XRUST-001 here", "") + assert hits == [] + + +def test_trailing_punctuation_still_matches() -> None: + hits = lint.scan_text("see CMT-001. and done", "") + assert len(hits) == 1 + assert hits[0]["matched_id"] == "CMT-001" + + +def test_multiple_matches_same_line() -> None: + hits = lint.scan_text("both CMT-001 and SEC-014 here", "") + matched = {h["matched_id"] for h in hits} + assert matched == {"CMT-001", "SEC-014"} + assert all(h["line"] == 1 for h in hits) + + +# --------------------------------------------------------------------------- +# Diff mode +# --------------------------------------------------------------------------- +DIFF_FIXTURE = """\ +diff --git a/foo.py b/foo.py +index 1234567..89abcde 100644 +--- a/foo.py ++++ b/foo.py +@@ -10,4 +10,5 @@ + context line CMT-001 should be ignored +-removed line SEC-099 should be ignored ++added line CMT-002 should match ++another added RUST-007 + final context line +""" + + +def test_diff_mode_only_added_lines() -> None: + hits = lint.scan_diff(DIFF_FIXTURE) + matched_ids = sorted(h["matched_id"] for h in hits) + assert matched_ids == ["CMT-002", "RUST-007"] + files = {h["file"] for h in hits} + assert files == {"foo.py"} + + +def test_diff_mode_line_numbers_from_hunk() -> None: + """Added lines should report line numbers offset from hunk header start.""" + hits = lint.scan_diff(DIFF_FIXTURE) + by_id = {h["matched_id"]: h["line"] for h in hits} + # Hunk starts at new-file line 10; one context (10), one removed (skipped), + # then two added lines at 11 and 12. + assert by_id["CMT-002"] == 11 + assert by_id["RUST-007"] == 12 + + +NO_NEWLINE_DIFF_FIXTURE = """\ +diff --git a/foo.py b/foo.py +index 1234567..89abcde 100644 +--- a/foo.py ++++ b/foo.py +@@ -10,3 +10,4 @@ + context before CMT-001 ignored +-removed last line no newline +\\ No newline at end of file ++replacement last line ++trailing added CMT-002 should match +\\ No newline at end of file +""" + + +def test_diff_mode_no_newline_marker_does_not_shift_lines() -> None: + """The ``\\ No newline at end of file`` marker is diff metadata, not a + content line — it must not advance the new-file line counter, so added + matches after it report the correct line number.""" + hits = lint.scan_diff(NO_NEWLINE_DIFF_FIXTURE) + by_id = {h["matched_id"]: h["line"] for h in hits} + # Hunk starts at new-file line 10: context (10→11), removed (skipped), the + # no-newline marker (skipped, no advance), replacement added line (11→12), + # then the ephemeral-ID added line at 12. Were the marker mistakenly + # counted as content it would advance the counter and report 13. + assert by_id == {"CMT-002": 12} + + +def test_diff_mode_via_subprocess_stdin() -> None: + """End-to-end: pipe a diff through stdin, parse JSON output.""" + result = subprocess.run( + [sys.executable, str(SCRIPT), "--diff"], + input=DIFF_FIXTURE, + capture_output=True, + text=True, + check=True, + ) + assert result.returncode == 0 + payload = json.loads(result.stdout) + matched = sorted(h["matched_id"] for h in payload) + assert matched == ["CMT-002", "RUST-007"] + + +# --------------------------------------------------------------------------- +# File mode end-to-end +# --------------------------------------------------------------------------- +def test_file_mode_via_subprocess(tmp_path: Path) -> None: + target = tmp_path / "sample.md" + target.write_text("Talk about CMT-001 here.\nNo hits on this line.\nAlso SEC-014.\n") + result = subprocess.run( + [sys.executable, str(SCRIPT), str(target)], + capture_output=True, + text=True, + check=True, + ) + assert result.returncode == 0 + payload = json.loads(result.stdout) + assert len(payload) == 2 + by_line = {h["line"]: h["matched_id"] for h in payload} + assert by_line == {1: "CMT-001", 3: "SEC-014"} + + +def test_text_format_output(tmp_path: Path) -> None: + target = tmp_path / "sample.md" + target.write_text("Hit CMT-001 here.\n") + result = subprocess.run( + [sys.executable, str(SCRIPT), "--format", "text", str(target)], + capture_output=True, + text=True, + check=True, + ) + assert result.returncode == 0 + assert "CMT-001" in result.stdout + assert str(target) in result.stdout + + +def test_empty_files_list_emits_empty_json() -> None: + result = subprocess.run( + [sys.executable, str(SCRIPT)], + capture_output=True, + text=True, + check=True, + ) + assert result.returncode == 0 + assert json.loads(result.stdout) == [] + + +def test_always_exit_zero(tmp_path: Path) -> None: + """Even when hits are found, exit code is 0 (advisory lint).""" + target = tmp_path / "loud.md" + target.write_text("CMT-001 SEC-014 RUST-123\n") + result = subprocess.run( + [sys.executable, str(SCRIPT), str(target)], + capture_output=True, + text=True, + check=False, + ) + assert result.returncode == 0 + + +# --------------------------------------------------------------------------- +# Source-of-truth assertion: lint PREFIXES must cover the consolidator set. +# --------------------------------------------------------------------------- +def test_prefixes_superset_of_consolidator() -> None: + """Drift between lint and consolidator must be structurally impossible.""" + consolidator_set = set(CATEGORY_PREFIX.values()) + assert consolidator_set.issubset(set(lint.PREFIXES)), ( + f"Lint missing prefixes from consolidator: " + f"{consolidator_set - set(lint.PREFIXES)}" + ) + + +def test_pattern_built_from_prefixes() -> None: + """Regex must reflect the imported prefix set, not a stale literal.""" + # Every prefix stem (without the dash) must appear in the compiled pattern. + for prefix in lint.PREFIXES: + stem = prefix.rstrip("-") + assert stem in lint.PATTERN.pattern, f"Stem {stem!r} missing from regex" diff --git a/tests/test_render_v3.py b/tests/test_render_v3.py index dd216f3c..586e964d 100644 --- a/tests/test_render_v3.py +++ b/tests/test_render_v3.py @@ -635,6 +635,60 @@ def test_triage_finding_data_category_preserves_origin_category(): # --------------------------------------------------------------------------- # PDF # --------------------------------------------------------------------------- +def test_markdown_matrix_includes_call_tree_column(): + """Stream A: the Markdown scoreboard table must surface the new + call_tree category column (driven by CATEGORY_LABELS).""" + data = _load("v3-call-tree.json") + # The fixture has no pre-computed matrix; compute one to drive the renderer. + import sys as _sys + from pathlib import Path as _Path + + _sys.path.insert(0, str(_Path(__file__).resolve().parent.parent / "scripts")) + import consolidate_reports as cr # type: ignore + + data["summary_statistics"]["severity_category_matrix"] = cr.compute_statistics( + data["findings"], [] + )["severity_category_matrix"] + md = grr.render_markdown(data) + assert "Call-Tree Inspection" in md, md[:2000] + # The HIGH row must show the 1 finding under the call_tree column. + # Find the HIGH line and assert it contains a 1 in the call_tree column. + high_line = next(line for line in md.splitlines() if line.startswith("| HIGH ")) + # CATEGORY_LABELS order: security, project, code_quality, call_tree, ... + # cells: | HIGH | sec | proj | cq | call_tree | doc | dep | cmt | ppm | total | + cells = [c.strip() for c in high_line.split("|")] + # cells[0] is leading empty, cells[1]="HIGH", then category cells. + assert cells[1] == "HIGH" + # The 4th category column is call_tree. + assert cells[5] == "1", high_line + + +def test_html_includes_call_tree_in_filter_chip_and_js_labels(): + """Stream A: the HTML renderer must include call_tree in the category + filter dropdown, the Chart.js category-label list, and the JS catLabels + lookup — otherwise findings in that category render but can never be + filtered or scored against.""" + data = _load("v3-call-tree.json") + html = grr.render_html(data) + # Filter ' in html + # JS catLabels lookup carries the slug. + assert '"call_tree":"Call-Tree Inspection"' in html + # Chart.js category-label list (CATEGORY_LABELS values) carries the label. + assert "Call-Tree Inspection" in html + # The finding card data-category attribute reflects the new category. + assert 'data-category="call_tree"' in html + + +def test_triage_includes_call_tree_in_filter_and_data_attribute(): + """The triage renderer shares the template; the filter chip and + per-finding data-category must carry call_tree there too.""" + data = _load("v3-call-tree.json") + html = grr.render_triage(data) + assert '' in html + assert 'data-category="call_tree"' in html + + def test_pdf_full_renders(tmp_path): data = _load("v3-full.json") out = tmp_path / "out.pdf" diff --git a/tests/test_schema_v3_strict.py b/tests/test_schema_v3_strict.py index c06019fb..656b6270 100644 --- a/tests/test_schema_v3_strict.py +++ b/tests/test_schema_v3_strict.py @@ -104,6 +104,93 @@ def test_producer_shape_missing_required_text_is_still_rejected(self): ), "Expected schema to reject finding missing required `description`" +class TestCallTreeCategory: + """Stream A — the call_tree category and CALL- ID prefix must validate + end-to-end; unknown prefixes must still be rejected.""" + + def test_call_tree_fixture_passes_schema(self): + data = json.loads((FIXTURES / "v3-call-tree.json").read_text()) + errors = list(VALIDATOR.iter_errors(data)) + assert errors == [], [e.message for e in errors] + + def test_call_prefix_finding_validates(self): + """A standalone finding with id=CALL-001 and category=call_tree + must pass the v3 schema.""" + report = { + "schema_version": "3.0.0", + "metadata": {"project": "p", "date": "2026-05-28"}, + "executive_summary": {"overall_assessment": "ok"}, + "summary_statistics": { + "total_findings": 1, + "severity_counts": { + "CRITICAL": 0, + "HIGH": 0, + "MEDIUM": 1, + "LOW": 0, + "INFO": 0, + }, + }, + "findings": [ + { + "title": "Call-Tree Inspection", + "category": "call_tree", + "findings": [ + { + "id": "CALL-001", + "risk": 0.5, + "impact": 0.5, + "scope": 1.0, + "title": "Walked call chain hides an unbounded loop", + "location": "src/walker.rs:42-58", + "description": "Following foo -> bar -> baz, baz spins forever on attacker input.", + "recommendation": "Add an iteration bound and surface it through the public API.", + } + ], + } + ], + } + errors = list(VALIDATOR.iter_errors(report)) + assert errors == [], [e.message for e in errors] + + def test_unknown_id_prefix_is_rejected(self): + """An id with a prefix not in the schema's alternation must fail.""" + report = { + "schema_version": "3.0.0", + "metadata": {"project": "p", "date": "2026-05-28"}, + "executive_summary": {"overall_assessment": "ok"}, + "summary_statistics": { + "total_findings": 1, + "severity_counts": { + "CRITICAL": 0, + "HIGH": 0, + "MEDIUM": 1, + "LOW": 0, + "INFO": 0, + }, + }, + "findings": [ + { + "title": "Security Findings", + "category": "security", + "findings": [ + { + "id": "XYZ-001", + "risk": 0.5, + "impact": 0.5, + "scope": 1.0, + "title": "Bogus prefix", + "location": "src/x.rs:1", + "description": "d", + "recommendation": "r", + } + ], + } + ], + } + errors = list(VALIDATOR.iter_errors(report)) + assert errors, "Expected schema to reject finding with unknown id prefix XYZ-" + + class TestV2Legacy: def test_rejected(self): data = json.loads((LEGACY_FIXTURES / "v2-legacy.json").read_text()) diff --git a/tests/test_skill_frontmatter.py b/tests/test_skill_frontmatter.py new file mode 100644 index 00000000..50919e3b --- /dev/null +++ b/tests/test_skill_frontmatter.py @@ -0,0 +1,43 @@ +"""Regression guard: every skill/agent YAML frontmatter must parse cleanly via PyYAML. + +A skill or agent whose frontmatter fails to parse loads with empty metadata at +runtime — all frontmatter fields are silently dropped, breaking tool permissions, +descriptions, model selection, and skills preloading. Catching this in CI keeps +authors from shipping a SKILL.md with an unquoted colon, a stray tab, or any +other YAML poison that `claude plugin validate` rejects. +""" + +from __future__ import annotations + +from pathlib import Path + +import pytest +import yaml + +REPO_ROOT = Path(__file__).resolve().parent.parent + +FRONTMATTER_FILES = sorted(REPO_ROOT.glob("skills/*/SKILL.md")) + sorted( + REPO_ROOT.glob("agents/*.md") +) + + +def _extract_frontmatter(path: Path) -> str: + """Return the raw YAML frontmatter block between the first two `---` fences.""" + text = path.read_text(encoding="utf-8") + parts = text.split("---", 2) + if len(parts) < 3: + raise AssertionError(f"{path}: no `---` frontmatter delimiters found") + return parts[1] + + +@pytest.mark.parametrize("path", FRONTMATTER_FILES, ids=lambda p: str(p.relative_to(REPO_ROOT))) +def test_frontmatter_parses(path: Path) -> None: + raw = _extract_frontmatter(path) + data = yaml.safe_load(raw) + assert isinstance(data, dict), f"{path}: frontmatter parsed to {type(data).__name__}, expected dict" + assert "name" in data, f"{path}: frontmatter missing required `name` field" + + +def test_corpus_not_empty() -> None: + """Guard against the glob silently matching nothing (e.g. after a directory rename).""" + assert FRONTMATTER_FILES, "No SKILL.md or agent .md files discovered — glob is broken"