git:20261005.bf1edd9 to git:20261005.ed9e01e

- ## Project Instruction Files

-

- `AGENTS.md` is the repository instruction source. Keep directory-specific guidance

- in the corresponding nested `AGENTS.md`.

-

- ## Critical Rules

- 1. **Rust workspace** - agnix-rules (data), agnix-core (lib), agnix-cli/agnix-lsp/agnix-mcp (binaries), agnix-wasm (WASM bindings)

- 2. **rules.json is source of truth** - `knowledge-base/rules.json` is the machine-readable source of truth. When adding a new rule, add it to BOTH `rules.json` AND `VALIDATION-RULES.md`. CI parity tests enforce this.

- 3. **Plain text output** - No emojis, no ASCII art

- 4. **Certainty filtering** - HIGH (>95%), MEDIUM (75-95%), LOW (<75%)

- 5. **Release binaries** - Compile with LTO, strip symbols

- 6. **Track work in GitHub issues** - All tasks tracked there

- 7. **Task is not done until tests added** - Every feature/fix must have quality tests

- 8. **Documentation** - Keep long-form docs in `README.md`, `SPEC.md`, and `knowledge-base/` (especially `knowledge-base/VALIDATION-RULES.md`). Keep `AGENTS.md` for agent instructions only.

- 9. **Always follow the skill/command flow as instructed** - No deviations

- 10. **No unnecessary files** - Don't create summary files, plan files, or temp docs unless specifically required

- 11. **Never merge without waiting for the `revuto-review` check to end successfully** - It might take time, but this is the major quality gate and most thorough review.

- 12. **You MUST follow the flow phases one by one** - If they state to use subagents, tools, or any specific method, you must follow it exactly as described.

- 13. **You MUST address all comments and reviews** - If reviewers leave comments, even minor ones, and even if not a requested change, you must address them all before merging. If you disagree, respond in the review comments. Minor comments must still be addressed.

- 14. **Use single dash for em-dashes** - In prose, use ` - ` (single dash with spaces), never ` -- ` (double dash). This does not apply to CLI flags like `--help` or `--fix`.

- ### Crate Dependency Graph

- ### Project Layout

- ### Core Modules (agnix-core)

-

- - `parsers/` - Frontmatter, JSON, Markdown parsing

- - `schemas/` - Type definitions for skill, hooks, agent, mcp, cline, roo, and other tool configs

- - `rules/` - Validators implementing Validator trait (40 validators)

- - `config.rs` - LintConfig, LintConfigBuilder, ConfigError, ToolVersions, SpecRevisions

- - `diagnostics.rs` - Diagnostic, Fix, DiagnosticLevel, ValidationOutcome, LintError (= CoreError), LintResult

- - `eval.rs` - Rule efficacy evaluation (precision/recall/F1)

- - `file_types/` - FileType enum, detect_file_type(), FileTypeDetector trait, FileTypeDetectorChain

- - `file_utils.rs` - Safe file I/O (symlink rejection, size limits)

- - `fixes.rs` - Auto-fix application engine

- - `fs.rs` - FileSystem trait abstraction (RealFileSystem, MockFileSystem)

- - `pipeline.rs` - `ValidationResult`, `validate_project()`, `validate_file()` -> `LintResult<ValidationOutcome>`

- - `registry.rs` - ValidatorRegistry, ValidatorRegistryBuilder, ValidatorProvider, factory functions

-

- ### Key Abstractions

-

- ```rust

- // Primary extension point

- // Implementors must be Send + Sync + 'static (cached in registry, shared across threads)

- pub trait Validator: Send + Sync + 'static {

- fn validate(&self, path: &Path, content: &str, config: &LintConfig) -> Vec<Diagnostic>;

- fn name(&self) -> &'static str { /* default: short type name */ }

- fn metadata(&self) -> ValidatorMetadata { /* default: empty rule_ids */ }

- }

-

- // Plugin architecture for extensibility

- pub trait ValidatorProvider: Send + Sync {

- fn name(&self) -> &str { /* default: short type name */ }

- fn validators(&self) -> Vec<(FileType, ValidatorFactory)>;

- fn named_validators(&self) -> Vec<(FileType, Option<&'static str>, ValidatorFactory)> { /* default: wraps validators() with None names */ }

- }

-

- // Registry with builder pattern and runtime filtering

- // Stores cached Box<dyn Validator> instances; no per-file re-instantiation

- pub struct ValidatorRegistry { /* ... */ }

-

- impl ValidatorRegistry {

- pub fn builder() -> ValidatorRegistryBuilder;

- pub fn with_defaults() -> Self;

- pub fn validators_for(&self, file_type: FileType) -> &[Box<dyn Validator>];

- pub fn total_validator_count(&self) -> usize;

- pub fn disable_validator(&mut self, name: &'static str);

- pub fn disable_validator_owned(&mut self, name: &str);

- }

-

- // Extensible file type detection (chain-of-responsibility)

- pub trait FileTypeDetector: Send + Sync {

- fn detect(&self, path: &Path) -> Option<FileType>;

- fn name(&self) -> &str { /* default: short type name */ }

- }

-

- pub struct FileTypeDetectorChain { /* ... */ }

-

- impl FileTypeDetectorChain {

- pub fn new() -> Self;

- pub fn with_builtin() -> Self;

- pub fn prepend(self, detector: impl FileTypeDetector + 'static) -> Self;

- pub fn push(self, detector: impl FileTypeDetector + 'static) -> Self;

- pub fn detect(&self, path: &Path) -> Option<FileType>;

- }

-

- // Validated config construction (fields are private)

- // Usage: LintConfig::builder().severity(Error).tools(vec![...]).build()?

- pub struct LintConfigBuilder { /* ... */ }

- impl LintConfigBuilder {

- pub fn severity(&mut self, s: SeverityLevel) -> &mut Self;

- pub fn target(&mut self, t: TargetTool) -> &mut Self;

- pub fn tools(&mut self, t: Vec<String>) -> &mut Self;

- pub fn exclude(&mut self, e: Vec<String>) -> &mut Self;

- pub fn disable_rule(&mut self, id: impl Into<String>) -> &mut Self;

- pub fn disable_validator(&mut self, name: impl Into<String>) -> &mut Self;

- pub fn build(&mut self) -> Result<LintConfig, ConfigError>;

- pub fn build_lenient(&mut self) -> Result<LintConfig, ConfigError>;

- // build_unchecked() exists but is #[cfg(any(test, feature = "__internal_unchecked"))]

- // __internal module exists but is #[cfg(any(test, feature = "__internal"))]

- // normalize_line_endings is stable at crate root: agnix_core::normalize_line_endings

- }

- impl LintConfig {

- pub fn builder() -> LintConfigBuilder;

- }

- ```

- ### Validation Flow

- ### LSP Architecture

- - Backend holds `Arc<ArcSwap<LintConfig>>` for lock-free config reads, immutable `Arc<ValidatorRegistry>`, document cache

- - Validation runs in `spawn_blocking()` (CPU-bound, sync)

- - Events: `did_open`, `did_change`, `did_save`, `did_close`, `did_change_configuration`, `codeAction`, `hover`

- cargo check # Compile check

- cargo test # Run tests and doc tests

- cargo nextest run --workspace # Optional process-per-test runner

- cargo build --release # Build binaries

- cargo run --bin agnix -- . # Run CLI

- cargo run --bin agnix-lsp # Run LSP server

- cargo run --bin agnix-mcp # Run MCP server

- For local checks, prefer a scoped crate or integration binary, for example

- `cargo test -p agnix-core --test fix_integration`. Cargo remains the local

- preflight and CI default after measurement; nextest is available for optional

- local runs.

- The default nextest profile uses two test processes; increase `--test-threads` only within the

- machine's CPU budget. Dev and test builds retain file and line backtraces with

- `line-tables-only` debug information. Release profiles are unchanged.

-

- CI runs lint and workspace merge contracts on owner PRs and pushes to main.

- Owner PRs run scoped tests locally before pushing. External contributors,

- the daily run, manual CI runs, PRs labeled `full-suite` before a push, and release

- validation run the full test suite.

- Nextest does not run doc tests; pair it with `cargo test --workspace --doc`.

-

- ## Rules Reference

-

- 457 rules defined in `knowledge-base/rules.json` (source of truth)

-

-

- Human-readable docs: `knowledge-base/VALIDATION-RULES.md`

- Format: `[CATEGORY]-[NUMBER]` (AS-004, CC-HK-001, etc.)

- **Adding a new rule**: Add to BOTH `rules.json` AND `VALIDATION-RULES.md`. CI parity tests will fail if they drift. Each rule in `rules.json` must include complete `evidence` metadata (source_type, source_urls, verified_on, applies_to, normative_level, tests). See VALIDATION-RULES.md for the evidence schema reference. Then run `node scripts/sync-rule-bookkeeping.js` (add `--validators=N` if a new validator was registered) to update the derived locations: `total_rules` + `last_updated` in rules.json, count phrases in AGENTS.md/README.md, the `crates/agnix-rules/rules.json` mirror, and the website docs. CI enforces this with `--check` mode.

- ## Current State

- - Production-ready with full validation pipeline (current version: the latest [GitHub release](https://github.com/agent-sh/agnix/releases))

- - 457 validation rules across 40 validators

- - 4200+ passing tests

- - LSP + MCP servers with VS Code extension

- - See GitHub issues for roadmap

- ## Tool Support Tiers

- agnix validates 11 tools today - those with a per-tool validator in `crates/agnix-core/src/rules/`. Tier indicates support priority (higher = stricter testing and release tracking).

- Release tracking for these is automated where the upstream publishes to GitHub: see `.github/tool-release-baselines.json` and `.github/workflows/tool-release-watch.yml`.

- **Watchlist** (no validator yet; tracked manually in `knowledge-base/RESEARCH-TRACKING.md`):

- - continue, Antigravity, Tabnine, Codeium, Amazon Q, Aider, SourceGraph Cody, pi

- **E** (no support): Everything else - community contributions welcome via the Tool Support Request issue template.

- - SPEC.md - Technical reference

- - knowledge-base/INDEX.md - Knowledge navigation

-

- ## Validation scope

-

- agnix is CPU-only Rust/WASM tooling. Choose checks for the changed behavior:

- formatting, lint, tests, rule bookkeeping and parity, packaging, and review.

- Use the relevant checks in `scripts/preflight.sh`; CPU-only tooling and docs do

- not need a GPU gate. If a future change introduces GPU, runtime or model behavior

- or related claims, require the corresponding native, model and hardware

- qualification before claiming support. CPU checks cannot provide that proof.