agent-sh/agnix v0.2.0

on GitHub

Added

• crates.io publishing support (#20)
  • New agnix-rules crate for independent rule updates without CLI republish
  • LICENSE-MIT and LICENSE-APACHE files for dual licensing
  • Crate-level READMEs for crates.io pages
  • Automatic crates.io publish on release tags via CI workflow
  • Parity test ensures rules.json stays in sync between knowledge-base and crate
  • Input validation in build.rs for secure code generation
• Language Server Protocol (LSP) implementation for real-time editor validation (#18)
  • New agnix-lsp crate with tower-lsp backend
  • Real-time diagnostics on document changes (textDocument/didChange)
  • Real-time diagnostics on file open and save events
  • Quick-fix code actions from Fix objects
  • Hover documentation for frontmatter fields
  • Document content caching for performance
  • Supports all 100 agnix validation rules with severity mapping
  • Workspace boundary validation for security (prevents path traversal)
  • Config caching optimization for performance
  • Editor support for VS Code, Neovim, Helix, and other LSP-compatible editors
  • Comprehensive test coverage with 36 unit and integration tests
  • Installation: cargo install --path crates/agnix-lsp
  • LSP now loads .agnix.toml from workspace root (#174)
• Multi-tool support via tools array in config (#175)
  • Specify tools = ["claude-code", "cursor"] to enable only relevant rules
  • Tool-specific rules (CC-, COP-, CUR-*) filtered based on tools list
  • Generic rules (AS-, XP-, AGM-, MCP-, PE-*) always apply
  • Case-insensitive tool name matching
  • Takes precedence over legacy target field for flexibility
• VS Code extension with full LSP integration (#22)
  • Real-time diagnostics for all 100 validation rules
  • Status bar indicator showing agnix validation status
  • Syntax highlighting for SKILL.md YAML frontmatter
  • Commands: 'Restart Language Server' and 'Show Output Channel'
  • Configuration: agnix.lspPath, agnix.enable, agnix.trace.server
  • Safe LSP binary detection (prevents command injection)
  • Documentation in editors/vscode/README.md
• Spec Drift Sentinel workflow for automated upstream specification monitoring (#107)
  • Weekly checks for S-tier sources (Agent Skills, MCP, Claude Code, Codex CLI, OpenCode)
  • Monthly checks for A-tier sources (Cursor, GitHub Copilot, Cline)
  • SHA256 content hashing with whitespace normalization for drift detection
  • Baseline storage in .github/spec-baselines.json
  • Auto-creates GitHub issues when drift detected with actionable review steps
  • Manual workflow dispatch for on-demand checks and baseline updates
  • Security hardened: HTTPS-only URL validation, SHA-pinned actions, minimal permissions
• Version-aware validation with configurable tool and spec versions
  • New VER-001 rule: Warns when no tool/spec versions are pinned in .agnix.toml
  • Added [tool_versions] section for pinning tool versions (claude_code, codex, cursor, copilot)
  • Added [spec_revisions] section for pinning spec versions (mcp_protocol, agent_skills_spec, agents_md_spec)
  • CC-HK-010 and MCP-008 now add assumption notes when versions are not pinned
  • Diagnostics include assumption field explaining version-dependent behavior
  • Documentation in README.md and VALIDATION-RULES.md
• Cross-layer contradiction detection with 3 new validation rules (XP-004 to XP-006)
  • XP-004: Conflicting build/test commands detection (npm vs pnpm vs yarn vs bun)
  • XP-005: Conflicting tool constraints detection (allow vs disallow across files)
  • XP-006: Multiple instruction layers without documented precedence warning
  • Detects contradictions across CLAUDE.md, AGENTS.md, .cursor/rules, and Copilot files
  • HashMap-based O(n*m) algorithms for efficient conflict detection
  • Word boundary matching to prevent false positives
  • Backup file exclusion (.bak, .old, .tmp, .swp, ~)
• Evidence metadata schema for all 100 validation rules
  • Added evidence field to each rule in knowledge-base/rules.json with:
    • source_type: Classification (spec, vendor_docs, vendor_code, paper, community)
    • source_urls: Links to authoritative documentation or specifications
    • verified_on: ISO 8601 date of last verification
    • applies_to: Tool/version/spec applicability constraints
    • normative_level: RFC 2119 level (MUST, SHOULD, BEST_PRACTICE)
    • tests: Coverage tracking (unit, fixtures, e2e)
  • Build-time SARIF rule generation from rules.json (replaces hardcoded registry)
  • CI validation tests for evidence metadata completeness and validity
  • Documentation in VALIDATION-RULES.md with schema reference and examples
• Cursor Project Rules support with 6 new validation rules (CUR-001 to CUR-006)
  • CUR-001: Empty .mdc rule file detection
  • CUR-002: Missing frontmatter warning
  • CUR-003: Invalid YAML frontmatter validation
  • CUR-004: Invalid glob pattern in globs field
  • CUR-005: Unknown frontmatter keys warning
  • CUR-006: Legacy .cursorrules migration warning
  • New file type detection for .cursor/rules/*.mdc and .cursorrules
  • Comprehensive test coverage with 8 fixtures

Performance

• LSP server now caches ValidatorRegistry in Backend struct (#171)
  • Registry wrapped in Arc and shared across spawn_blocking validation tasks
  • Eliminates redundant HashMap allocations and validator factory lookups per validation
• AS-015 directory size validation now short-circuits when limit exceeded, improving performance on large skill directories (#84)
• Stream file walk to reduce memory usage on large repositories (#172)
  • Replaced collect-then-validate pattern with streaming par_bridge()
  • Eliminated intermediate Vec storage (O(n) to O(1) memory for file paths)
  • Use AtomicUsize and Arc<Mutex> for concurrent metadata collection
  • Small synchronization overhead traded for significant memory reduction on large repos

Tests

• Added validation pipeline tests for AGENTS.md path collection and files_checked counter (#83)

Changed

• Tool mappings derived from rules.json at compile time (#176)
  • VALID_TOOLS and TOOL_RULE_PREFIXES now extracted from rules.json evidence metadata
  • New helper functions in agnix-rules: valid_tools(), get_tool_for_prefix(), get_prefixes_for_tool()
  • Config tools array validation uses derived mappings instead of hardcoded list
  • Backward compatibility maintained with "copilot" alias for "github-copilot"
  • Zero runtime cost - all mappings resolved at compile time
• Narrowed agnix-core public API surface (#85)
  • Made parsers, rules, schemas, and file_utils modules private
  • Re-exported Validator trait for custom validator implementations
  • No breaking changes for agnix-cli or external consumers using documented API

Removed

• Removed unused config flags tool_names and required_fields from .agnix.toml
  • These flags were never referenced in the codebase
  • Backward compatibility maintained - old configs with these fields still parse correctly

Fixed

• Mutex locks in streaming validation now use unwrap() for consistent fail-fast on poisoning (#172)
• CLAUDE/AGENTS parity test now resilient to different directory structures (worktrees, symlinks)
  • Replaced brittle .ancestors().nth(2) with dynamic workspace root detection
  • New workspace_root() helper searches for [workspace] in ancestor Cargo.toml files
• JSON output files_checked now correctly reports total validated files, not just files with diagnostics
• CLI --target flag now validates values instead of silently falling back to "generic"
  • Invalid values rejected with helpful error message showing valid options
  • Prevents configuration typos from going unnoticed
• GitHub Action: Windows binary extension handling (.exe)
• GitHub Action: Missing verbose flag in SARIF output re-run
• GitHub Action: Document jq dependency and fail-on-error input in README
• Config parse errors now display a warning instead of silently falling back to defaults
  • Invalid .agnix.toml files show clear error message with parse location
  • Validation continues with default config after displaying warning
  • Warning goes to stderr, preserving JSON/SARIF output validity
• Pinned cargo-machete to version 0.9.1 in CI workflow to prevent nondeterministic build failures
• Exclude patterns now prune directories during traversal to reduce IO on large repos
• CLI init command output replaced checkmark emoji with plain text prefix
• Reject --fix, --dry-run, and --fix-safe when using JSON or SARIF output formats
• Exclude glob patterns now match correctly when validate_project() is called with absolute paths (#67)
  • Patterns like target/** previously failed to match when walker yielded absolute paths
  • Added path normalization by stripping base path prefix before glob matching
• PE-001 through PE-004 rules now properly dispatch on CLAUDE.md and AGENTS.md files (PromptValidator was implemented but not registered in ValidatorRegistry)
• is_mcp_revision_pinned() now correctly returns false when neither spec_revisions.mcp_protocol nor mcp_protocol_version are explicitly set
  • Previously always returned true due to serde(default) on mcp_protocol_version
  • This allows MCP-008 assumption notes to appear when no version is configured

Security

• GitHub Action: Validate version input format to prevent path traversal attacks
• GitHub Action: Sanitize diagnostic messages in workflow commands to prevent injection
• GitHub Action: Use authenticated GitHub API requests when token available (avoids rate limits)
• Blocked @import paths that resolve outside the project root to prevent traversal
• Hardened file reading with symlink rejection and size limits:
  • Added FileSymlink error to reject symlinks (prevents path traversal)
  • Added FileTooBig error for files exceeding 1 MiB (prevents DoS)
  • New file_utils module with safe_read_file() using symlink_metadata()
  • Applied to validation, imports, fixes, and config loading
  • Cross-platform tests for Unix and Windows symlink handling
• Hardened GitHub Actions workflows with security best practices:
  • Added explicit permissions blocks to all workflows (principle of least privilege)
  • SHA-pinned all third-party actions to prevent supply chain attacks
  • Restricted cache saves to main branch only (prevents cache poisoning from PRs)
  • Documented SHA pin reference in .github/workflows/README.md for maintainability

Added

• Evaluation harness with agnix eval command for measuring rule efficacy

  • Load test cases from YAML manifests with expected rule IDs
  • Calculate precision, recall, and F1 scores per rule and overall
  • Output formats: markdown (default), JSON, CSV
  • Filter by rule prefix (--filter)
  • Verbose mode for per-case details (--verbose)
  • 39 test cases covering AS-, CC-SK-, MCP-, AGM-, XP-, XML-, REF-* rules
  • Path traversal protection (relative paths only)
  • Documentation in knowledge-base/EVALUATION.md

• MCP-008 rule for protocol version validation with configurable mcp_protocol_version option

• 5 new parse error rules with normalized IDs (AS-016, CC-HK-012, CC-AG-007, CC-PL-006, MCP-007)

• Auto-fix support for CC-MEM-005 and CC-MEM-007 memory rules

  • CC-MEM-005: Delete lines containing generic instructions
  • CC-MEM-007: Replace weak constraint language with stronger alternatives
  • CRLF line ending support for correct byte offsets on Windows

• Auto-fix implementations for five additional rules:

  • AS-004: Convert invalid skill names to kebab-case (case-only fixes marked safe)
  • AS-010: Prepend "Use when user wants to " to descriptions missing trigger phrase
  • XML-001: Automatically insert closing XML tags for unclosed elements
  • CC-HK-001: Replace invalid hook event names with closest valid match
  • CC-SK-007: Replace unrestricted Bash access with scoped alternatives (e.g., Bash(git:*))

• Reusable GitHub Action for CI/CD integration:

  • Composite action using pre-built release binaries
  • Inputs for path, strict, target, config, format, verbose, version
  • Outputs for result, errors, warnings, sarif-file
  • GitHub annotations from validation diagnostics
  • Cross-platform support (Linux, macOS, Windows)
  • Test workflow for action validation

• Release workflow for automated binary distribution on version tags:

  • Builds for 5 targets (linux-gnu, linux-musl, macos-x86, macos-arm, windows)
  • Creates archives with SHA256 checksums
  • Extracts release notes from CHANGELOG.md
  • Uploads artifacts to GitHub Releases

• 52 CLI integration tests for comprehensive coverage of all output formats and flags:

  • 12 rule family coverage tests (AS, CC-SK, CC-HK, CC-AG, MCP, XML, CC-PL, COP, AGM, CC-MEM, REF, XP)
  • 5 SARIF output validation tests (schema, tool info, rules, locations, help URIs)
  • 6 text output formatting tests (location, levels, summary, verbose mode)
  • 5 fix/dry-run flag tests (--fix, --fix-safe, --dry-run)
  • 5 flag combination tests (--strict, --verbose, --target, --validate)

• Support for instruction filename variants:

  • CLAUDE.local.md - Claude Code local instructions (not synced to cloud)
  • AGENTS.local.md - Codex CLI/OpenCode local instructions
  • AGENTS.override.md - Codex CLI override file for workspace-specific rules
  • All variants are validated with the same rules as their base files

• Rule parity CI check to ensure documented rules stay in sync with implementation:

  • Added knowledge-base/rules.json as machine-readable source of truth for all 84 rules
  • Added crates/agnix-cli/tests/rule_parity.rs integration test suite
  • CI fails if rules drift between documentation, SARIF registry, and implementation
  • CLAUDE.md/AGENTS.md updated to document rules.json workflow

• GitHub Copilot instruction files validation with 4 rules (COP-001 to COP-004)

  • COP-001: Empty/missing global copilot-instructions.md
  • COP-002: Invalid YAML frontmatter in scoped instruction files
  • COP-003: Invalid applyTo glob pattern
  • COP-004: Unknown frontmatter keys
  • Supports .github/copilot-instructions.md (global instructions)
  • Supports .github/instructions/*.instructions.md (path-scoped instructions)
  • Config-based copilot category toggle (rules.copilot)

• ValidatorRegistry API for custom validator registration in agnix-core

• AGENTS.md validation rules (AGM-001 to AGM-006)

  • AGM-001: Valid markdown structure
  • AGM-002: Missing section headers
  • AGM-003: Character limit (12000 for Windsurf)
  • AGM-004: Missing project context
  • AGM-005: Unguarded platform features
  • AGM-006: Nested AGENTS.md hierarchy

• AGENTS.md validator now runs via the default registry, with project-level AGM-006 detection

• Explicit HTML anchors in VALIDATION-RULES.md for SARIF help_uri links (#88)

  • Added 80 anchors (one per rule) to fix GitHub anchor mismatch
  • Added tests to validate help_uri format and anchor correctness

• Prompt Engineering validation with 4 rules (PE-001 to PE-004)

  • PE-001: Detects critical content in middle of document (lost in the middle effect)
  • PE-002: Warns when chain-of-thought markers used on simple tasks
  • PE-003: Detects weak imperative language (should, try, consider) in critical sections
  • PE-004: Flags ambiguous instructions (e.g., "be helpful", "as needed")

• PromptValidator implementation in agnix-core

• Config-based prompt_engineering category toggle (rules.prompt_engineering)

• 8 test fixtures in tests/fixtures/prompt/ directory

• 48 comprehensive unit tests for prompt engineering validation

• MCP (Model Context Protocol) validation with 6 rules (MCP-001 to MCP-006)

  • MCP-001: Validates JSON-RPC version is "2.0"
  • MCP-002: Validates required tool fields (name, description, inputSchema)
  • MCP-003: Validates inputSchema is valid JSON Schema
  • MCP-004: Warns when tool description is too short (<10 chars)
  • MCP-005: Warns when tool lacks consent mechanism (requiresApproval/confirmation)
  • MCP-006: Warns about untrusted annotations that should be validated

• McpValidator and McpToolSchema in agnix-core

• Config-based MCP category toggle (rules.mcp)

• 8 test fixtures in tests/fixtures/mcp/ directory

• 48 comprehensive unit tests for MCP validation

• Cross-platform validation rules XP-001, XP-002, XP-003

  • XP-001: Detects Claude-specific features (hooks, context:fork, agent, allowed-tools) in AGENTS.md (error)
    • Supports section guards: Features inside Claude-specific sections (e.g., ## Claude Code Specific) are allowed
  • XP-002: Validates AGENTS.md markdown structure for cross-platform compatibility (warning)
  • XP-003: Detects hard-coded platform paths (.claude/, .opencode/, .cursor/, etc.) in configs (warning)

• New cross_platform config category toggle for XP-* rules

• 5 test fixtures in tests/fixtures/cross_platform/ directory

• 30 comprehensive unit tests for cross-platform validation

• Hook timeout validation rules CC-HK-010 and CC-HK-011

  • CC-HK-010: Warns when hooks lack timeout specification (MEDIUM)
  • CC-HK-011: Errors when timeout value is invalid (negative, zero, or non-integer) (HIGH)
  • Two new test fixtures: no-timeout.json, invalid-timeout.json

• Claude Memory validation rules CC-MEM-004, CC-MEM-006 through CC-MEM-010

  • CC-MEM-004: Validates npm scripts referenced in CLAUDE.md exist in package.json
  • CC-MEM-006: Detects negative instructions ("don't", "never") without positive alternatives
  • CC-MEM-007: Warns about weak constraint language ("should", "try") in critical sections
  • CC-MEM-008: Detects critical content in middle of document (lost in the middle effect)
  • CC-MEM-009: Warns when file exceeds ~1500 tokens, suggests using @imports
  • CC-MEM-010: Detects significant overlap (>40%) between CLAUDE.md and README.md

• SARIF 2.1.0 output format with --format sarif CLI option for CI/CD integration

  • Full SARIF 2.1.0 specification compliance with JSON schema validation
  • Includes all 80 validation rules in driver.rules with help URIs
  • Supports GitHub Code Scanning and other SARIF-compatible tools
  • Proper exit codes for CI workflows (errors exit 1)
  • Path normalization for cross-platform compatibility
  • 8 comprehensive integration tests for SARIF output

• SkillValidator Claude Code rules (CC-SK-001 to CC-SK-005, CC-SK-008 to CC-SK-009)

  • CC-SK-001: Validates model field values (sonnet, opus, haiku, inherit)
  • CC-SK-002: Validates context field must be 'fork' or omitted
  • CC-SK-003: Requires 'agent' field when context is 'fork'
  • CC-SK-004: Requires 'context: fork' when agent field is present
  • CC-SK-005: Validates agent type values (Explore, Plan, general-purpose, or custom kebab-case names 1-64 chars)
  • CC-SK-006: Dangerous skills must set 'disable-model-invocation: true'
  • CC-SK-007: Warns on unrestricted Bash access (suggests scoped versions)
  • CC-SK-008: Validates tool names in allowed-tools against known Claude Code tools
  • CC-SK-009: Warns when too many dynamic injections (!`) detected (>3)

• 27 comprehensive unit tests for skill validation (244 total tests)

• 9 test fixtures in tests/fixtures/skills/ directory for CC-SK rules

• JSON output format with --format json CLI option for programmatic consumption

  • Simple, human-readable structure for easy parsing and integration
  • Includes version, files_checked, diagnostics array, and summary counts
  • Cross-platform path normalization (forward slashes)
  • Proper exit codes for CI workflows (errors exit 1)
  • 14 comprehensive unit tests for JSON output

• Comprehensive CI workflow with format check, clippy, machete, and test matrix (3 OS x 2 Rust versions)

• Security scanning workflow with CodeQL analysis and cargo-audit (runs on push, PR, and weekly schedule)

• Changelog validation workflow to ensure CHANGELOG.md is updated in PRs

• PluginValidator implementation with 5 validation rules (CC-PL-001 to CC-PL-005)

  • CC-PL-001: Validates plugin.json is in .claude-plugin/ directory
  • CC-PL-002: Detects misplaced components (skills/agents/hooks) inside .claude-plugin/
  • CC-PL-003: Validates version uses semver format (X.Y.Z)
  • CC-PL-004: Validates required fields (name, description, version)
  • CC-PL-005: Validates name field is not empty

• Path traversal protection with MAX_TRAVERSAL_DEPTH limit

• 47 comprehensive tests for plugin validation (234 total tests)

• 4 test fixtures in tests/fixtures/plugins/ directory

• Auto-fix infrastructure with CLI flags:

  • --fix: Apply automatic fixes to detected issues
  • --dry-run: Preview fixes without modifying files
  • --fix-safe: Only apply high-certainty (safe) fixes

• Fix struct with FixKind enum (Replace, Insert, Delete) in diagnostics

• apply_fixes() function to process and apply fixes to files

• Diagnostics now include [fixable] marker in output for issues with available fixes

• Hint message in CLI output when fixable issues are detected

• Config-based rule filtering with category toggles (skills, hooks, agents, memory, plugins, xml, imports)

• Target tool filtering - CC-* rules automatically disabled for non-Claude Code targets (Cursor, Codex)

• Individual rule disabling via disabled_rules config list

• is_rule_enabled() method with category and target awareness

• AgentValidator implementation with 6 validation rules (CC-AG-001 to CC-AG-006)

  • CC-AG-001: Validates required 'name' field in agent frontmatter
  • CC-AG-002: Validates required 'description' field in agent frontmatter
  • CC-AG-003: Validates model values (sonnet, opus, haiku, inherit)
  • CC-AG-004: Validates permissionMode values (default, acceptEdits, dontAsk, bypassPermissions, plan)
  • CC-AG-005: Validates referenced skills exist at .claude/skills/[name]/SKILL.md
  • CC-AG-006: Detects conflicts between 'tools' and 'disallowedTools' arrays

• Path traversal security protection for skill name validation

• 44 comprehensive tests for agent validation (152 total tests)

• 7 test fixtures in tests/fixtures/agents/ directory

• Parallel file validation using rayon for improved performance on large projects

• Deterministic diagnostic output with sorting by severity and file path

• Comprehensive tests for parallel validation edge cases

• Reference validator rules REF-001 and REF-002

  • REF-001: @import references must point to existing files (error)
  • REF-002: Markdown links text should point to existing files (error)
  • Both rules are in the "imports" category
  • Supports fragment stripping (file.md#section validates file.md)
  • Skips external URLs (http://, https://, mailto:, etc.)
  • 4 test fixtures in tests/fixtures/refs/ directory
  • 31 comprehensive unit tests for reference validation

Changed

• Removed miette dependency from agnix-core to reduce binary size and compile times
  • agnix-core is now a pure library without terminal output dependencies
  • CLI continues to use colored for output formatting
  • Removed 8 unused LintError variants that used miette-specific features
• Downgraded 5 rules from ERROR to WARNING severity based on RFC 2119 audit:
  • PE-001 (Lost in the middle): Research-based recommendation, not spec violation
  • PE-002 (Chain-of-thought on simple task): Best practice advice, not requirement
  • CC-MEM-004 (Invalid command reference): Helpful validation, not breaking error
  • AGM-003 (Character limit): Uses SHOULD in documentation (Windsurf-specific)
  • AGM-005 (Platform-specific features): Uses SHOULD in documentation
• Imports validator now routes diagnostics by file type:
  • CLAUDE.md files emit CC-MEM-001/002/003 (Claude Code memory rules)
  • Non-CLAUDE markdown files emit REF-001 (generic reference validation)
  • Improved security with path traversal protection (rejects absolute paths)
  • Fixed critical bug: file type now determined per-file during recursion
• XML validator now emits specific rule IDs for each error type:
  • XML-001: Unclosed XML tag
  • XML-002: Mismatched closing tag
  • XML-003: Unmatched closing tag
• Individual XML rules can now be disabled via disabled_rules config
• Test fixtures restructured for improved validator integration:
  • Skills: Moved to subdirectory pattern (deep-reference/SKILL.md, missing-frontmatter/SKILL.md, windows-path/SKILL.md)
  • MCP: Renamed with .mcp.json suffix for proper FileType detection
  • Ensures validate_project() correctly identifies fixture types during integration tests
• validate_project() now processes files in parallel while maintaining deterministic output
• Directory walking remains sequential, only validation is parallelized
• All validators now respect config-based category toggles and disabled rules
• Config structure enhanced with category-based toggles (legacy flags still supported)
• Knowledge base docs refreshed (rule counts, AGENTS.md support tiers, Cursor rules)
• Fixture layout aligned with detector paths to ensure validators exercise fixtures directly
• CC-HK-010 timeout thresholds now align with official Claude Code documentation
  • Command hooks: warn when timeout > 600s (10-minute default)
  • Prompt hooks: warn when timeout > 30s (30-second default)

Performance

• Significant speed improvements on projects with many files