0.5.7 - Discovery & classification fixes for monorepo instruction files

[cleverhoods]

Summary

ails check against monorepos misclassified per-package CLAUDE.md / AGENTS.md / GEMINI.md files as main, tripping match: {type: main} rules (size limits, structural checks) on nested files that the agent itself loads on-demand. The bug was reproduced against activepieces/activepieces, an open-source monorepo whose per-package nested CLAUDE.md / AGENTS.md files surfaced the false-positive size findings. Used as a test fixture only - no affiliation.

This release replaces the discovery + classification pipeline, refreshes per-agent configs against verified upstream docs, and adds project-level config knobs for cases the framework might run into some issues modelling it statically (Codex project_doc_fallback_filenames).

What changed

• Project root for ails check is now itself. No walking up past it looking for .git or .ails/backbone.yml. Files outside the targeted subtree are out of scope. This eliminates the "fixture inside a parent repo leaks parent files" class of bug. engine_helpers._find_project_root retains its walk-up role for cache key derivation only and now recognizes IDE workspace markers (.vscode/, .idea/, .github/) alongside .git / and .ails/backbone.yml.

• Discovery dispatches by file_type properties.

  • scope: global + loading: session_start + loose leaf pattern (**/X.md or bare X.md) → ancestor walk bounded at cwd.
  • scope: nested (new enum value) → descendant walk excluding cwd. Replaces the previous overload of scope: path_scoped for surfaces whose subtree applicability comes from file LOCATION (subdirectory CLAUDE.md / AGENTS.md / GEMINI.md), not from in-file frontmatter.
  • scope: global + path-prefixed pattern (.github/copilot-instructions.md) → resolve relative to project root.
  • scope: path_scoped (frontmatter-filtered) → descendant walk from cwd.

• Classification respects pattern shape. _location_matches_mode only enforces cwd's ancestor-chain placement for loose leaf patterns where ancestor-chain disambiguates main from nested_context. Path-prefixed patterns (.github/copilot-instructions.md) are pre-constrained by their prefix and skip the check.

• Filename matching is case-sensitive per the Codex source (codex-rs/core/src/agents_md.rs's DEFAULT_AGENTS_MD_FILENAME = "AGENTS.md") and the agents.md spec ("Filenames not on this list are ignored for instruction discovery."). Wrong-case copies in skill-asset directories no longer surface as instruction files.

• Symlinked instruction files dedupe by canonical path. Cursor scans both .cursor/skills/ and .claude/skills/ for cross-agent compatibility; when a project symlinks one to the other (.claude/skills -> ../.agents/skills), the same SKILL.md no longer surfaces twice. Circular symlinks are caught and skipped.

• depends_on resolves through supersession. When CODEX:S:0003 supersedes CORE:S:0027, dependents on CORE:S:0027 (CORE:S:0030, CORE:G:0006) are now satisfied by CODEX:S:0003 instead of warning that the dependency is "not loaded".

• Per-agent file_type configs refreshed against verified upstream docs: official source URLs on every file_type, nested_context declared for codex / cursor / copilot / generic, cursor.rules corrected to scope: path_scoped (frontmatter globs: filter), cursor.bugbot_rules corrected to scope: global (BugBot decides applicability), Codex AGENTS.override.md + Windows requirements.toml path + per-directory .codex/config.toml chain modeled, Gemini cross_read for AGENTS.md/CONTEXT.md.

New configuration surfaces

- .ails/config.yml gains two top-level keys:

  agents:                                                                                                                                                                    
    codex:
      fallback_filenames: ["TEAM_GUIDE.md", ".agents.md"]                                                                                                                    
                                                                                                                                                                             
  surfaces:
    cursor.rules:                                                                                                                                                            
      exclude: ["**/draft/**"]                                                                                                                                               
    claude.skills:
      include: [".github/skills/**/SKILL.md"]                                                                                                                                

• agents..fallback_filenames mirrors Codex project_doc_fallback_filenames so per-project alternative instruction filenames are picked up by the validator without round-tripping through the user's home ~/.codex/config.toml. surfaces..<file_type>.include/.exclude adjusts per-surface globs without modifying the bundled framework configs.

• .ails/config.local.yml (gitignored) now layers on top of the committed .ails/config.yml for personal/CI-specific overrides — object keys merge recursively, array keys extend, scalar keys are replaced.

• ails config set now writes .ails/.gitignore listing .gitignore itself and config.local.yml so layered local config stays out of version control by default.

Display

• The text formatter now distinguishes main (root-level instruction file) from nested (subdirectory copies). The scorecard and group renderer show a separate "Nested" section. Nested file paths display the full relative path (packages/web/CLAUDE.md) rather than the previous web/CLAUDE.md truncation, so users can locate the actual file.

npm packaging

• The packages/npm/README.md symlink has been replaced with a prepack script (cp ../../README.md ./README.md). The previous symlink approach broke npmjs.com's per-version README display — only the latest version showed any README content. The prepack copy ships a real README in the tarball without a committed duplicate. packages/npm/README.md is now gitignored.

Schema additions

• framework/schemas/agent.schema.yml and rule.schema.yml: added scope: nested enum value with documented semantics.

• framework/schemas/project.schema.yml: added agents and surfaces keys.

Documentation

• docs/configuration.md adds three sections: per-surface include/exclude with concrete examples, Codex fallback filenames, and .ails/config.local.yml layered overrides + .ails/.gitignore explanation. Also available here https://reporails.com/docs