v0.5.0

Summary

Major catalog expansion from 17 to 102 rules. Agent-specific rules migrated to
their own namespaces (CLAUDE:, CODEX:, COPILOT:), new context_quality
category added, and all OpenGrep references removed in favor of native regex
pattern matching.

438 files changed — 8,938 insertions, 2,499 deletions.

Highlights

Rule catalog: 17 → 102

Category	Count
Structure	36
Content	32
Context Quality (new)	7
Efficiency	5
Governance	9
Maintenance	1
Agent — Claude	8
Agent — Codex	2
Agent — Copilot	2

Agent namespace migration

Agent-specific rules now live under their own coordinate namespaces instead of
being mixed into CORE:. Hook and skill rules migrated from core to
CLAUDE:S:, CODEX:S:, and COPILOT:S:.

New category: Context Quality (X)

Rules that evaluate whether instruction files provide sufficient project
context for effective agent work — architecture overviews, tech stack
declarations, directory layouts, path scoping, and priority ordering.

OpenGrep removal

All references to OpenGrep/Semgrep replaced with native regex pattern
matching. docs/opengrep-guide.md → docs/pattern-guide.md. Backbone key
rules.patterns.opengrep → rules.patterns.patterns_yml.

Schema changes

• Added context_quality category (letter X) to coordinate patterns and
  category enums
• Normalized agent override severity enum syntax; added critical value
• Added pattern validation to agent config excludes items
• Added internal source type to sources schema
• Sources schema version corrected from stale 1.0.0 to 0.1.0
• Rule schema bumped to 0.1.1
• Check ID format canonicalized to NAMESPACE.CATEGORY.SLOT.descriptive-name

Other changes

• Generic agent — new agents/generic/config.yml for running core rules
  without agent-specific config
• Bootstrap skill — redesigned to synthesize project context (navigation,
  operations, constraints) instead of counting files
• Test harness — added /test-rules skill for docker compose local
  harness
• Pre-commit hook — enforces UNRELEASED.md is staged when touching core/,
  agents/, schemas/, registry/, or docs/
• CI — test harness disabled in CI/release workflows pending
  reporails-cli 0.5.0 compatibility

Removed rules

Deprecated and removed from 0.4.x:

• Core: avoid-generic-placeholder-content, boundary-constraints,
  include-project-context, project-architecture-documentation,
  verification-build-commands, cross-agent-compatibility,
  valid-glob-patterns-in-frontmatter, valid-internal-references,
  monorepo-nested-instruction-files, root-instruction-file-presence,
  structured-markdown-format
• Agent: CLAUDE import-syntax, path-scoped-rules, rules-directory; CODEX
  combined-instruction-size-limit; COPILOT copilot-instructions-placement,
  copilot-path-specific-instructions

Upgrade notes

• Coordinate map fully rebuilt — any tooling referencing 0.4.x coordinates
  must update
• Agent configs now use arrays for main_instruction_file
• Check IDs use new canonical format
  (NAMESPACE.CATEGORY.SLOT.descriptive-name)

Full Changelog: 0.4.1...0.5.0

v0.4.1

v0.4.1 - Workflow documentation

Every shared workflow now pairs its mermaid flowchart (the what) with prose sections explaining the why — key decisions, design rationale, and constraint justifications.

Changed

• level-sync — Why a single source of truth, why three subcommands
• rule-validation — Why three layers in this order, why template resolution happens before OpenGrep only
• rule-update — Why coordinates are immutable, why templates must survive the save, why the fix loop exists
• rule-creation — Why type classification comes first, why sources before generation, why validate before save
• qa-smoke-test — Why this sequence, why cleanup must always run

Context

rule-implementation.md already followed this pattern and served as the template for the others. No workflow logic changed — only documentation was added.

Full Changelog: 0.4.0...0.4.1

0.4.0

Rules consolidation — focused rule set, GitHub Copilot support, new categories.

Highlights

47 → 17 rules. The core rule set has been consolidated to the rules that matter most. Opinionated and agent-specific rules moved to
https://github.com/reporails/recommended.

GitHub Copilot CLI is now a supported agent alongside Claude Code and Codex — with agent config, custom instructions, and 2 Copilot-specific rules.

New categories. Governance and Maintenance join Structure and Content as core rule categories.

Breaking changes

• Complete coordinate renumbering — all coordinates reassigned from fresh sequence. If you reference rule IDs in tooling or configs, update them against
  registry/coordinate-map.yml.
• Rule removals — 30 rules removed from core/agents. Most are available in https://github.com/reporails/recommended as RRAILS_ rules.

Test harness

• Agent excludes in config.yml — wildcard patterns like CLAUDE:* skip irrelevant rules
• --agent flag scopes discovery to that agent's rules plus core

What's next

• Tombstone backfill for pre-0.4.0 coordinates (planned post-0.5.0)
• Efficiency category rules (currently empty)

v0.3.1

What's Changed

• Update release mechanism.

Full Changelog: 0.2.2...0.3.1

0.2.2

0.2.2 — 2026-02-04

Changed

• Package Schema: 0.2.2
• Collapsed rules listing in CLAUDE.md

Fixed

• Rule ID mapping inconsistency in CLAUDE_S2

0.2.1

Release notes for 0.2.1:

Focus split — 18 core rules in dedicated repo, opinionated rules moved to reporails/recommended.

What changed

This release separates core validation rules from opinionated/governance rules. Core rules (18) stay here. The 26 opinionated rules now live in reporails/recommended and can be pulled in with ails check --with-recommended.

Highlights

• Package schema v0.0.1 — formal contract for rule packages
• Rule renumbering — 18 core rules renumbered to fill gaps (S1-S4, C1-C5, E1-E2, M1-M4, CLAUDE_M1, CLAUDE_S1-S2)
• Level redistribution — M3/M4 moved from L6 to L5; L6 is now detection-only (backbone.yml presence)
• Schema updates — rule schema v0.0.7 (package layer), agent schema v0.0.2 (fixed stale examples)
• Docs rewritten — README and CONTRIBUTING now frame reporails as validation (not linting), quickstart aligned with CLI

Removed

• 26 opinionated rules → reporails/recommended
• sources.schema.yml, evidence-chain.md, opengrep-patterns.md

Install / Upgrade

npx @reporails/cli install
                                                                                                                                                                           
# Or update rules only:
ails update 
                                                                                                                                                                           
Stats                                                                                                                                                                      
                                                                                                                                                                           
- 18 rules (15 core + 3 Claude-specific)                                                                                                                                   
- 6 schemas (rule, agent, project, package, user, levels)                                                                                                                  
                                                            

0.2.0

Trust Architecture

Tier-derived rule classification, schema breaking changes, directory restructuring with co-located tests, and multi-agent support.

Added

• Trust Architecture: Two-tier model (core/experimental) derived from source weights replaces stored confidence. 55 new backed_by entries across 17 rules; 2 new community
  sources
• Rule Structure: Co-located test files (fail/pass) for all rules; pattern_confidence field across all 43 rule frontmatters
• Levels: levels.yml canonical level→rule mappings; levels.schema.yml; /manage-levels skill
• M6 Rule: Backbone index completeness
• Codex Agent: agents/codex/ for OpenAI Codex AGENTS.md files
• Backbone: Path-scoped reminders; central resolution reference

Changed

• BREAKING — Rule Schema v5: pattern_confidence added; confidence removed; tiers derived from backed_by weights
• BREAKING — Sources Schema v3: 3 source types (official 1.0, research 0.8, community 0.4); tier derivation replaces stored confidence
• BREAKING — Project Schema v3: tiers object replaces confidence/profile
• BREAKING — Rule IDs: Sequential renumbering with separate agent namespaces
• BREAKING — Directory Structure: All rules in {rule-id}/ directories with co-located tests
• Schema Versions: Integer → semver strings ("0.0.X")
• Release Tags: Dropped v prefix — bare semver tags (e.g., 0.2.0)

Fixed

• Pattern anchoring for file-level content matching (C4, C12, E2, E3, E4, E5)
• 8 rule fixes: language targets, detection strategies, missing sources, semantic inversions

Removed

• Cursor scope from sources registry

Metrics
┌─────────┬───────────────────────────────────┐
│ Metric │ Value │
├─────────┼───────────────────────────────────┤
│ Rules │ 44 (37 core + 6 Claude + 1 Codex) │
├─────────┼───────────────────────────────────┤
│ Schemas │ 6 — all semver versioned │
├─────────┼───────────────────────────────────┤
│ Sources │ 23 weighted with extracted claims │
├─────────┼───────────────────────────────────┤
│ Agents │ 2 (Claude, Codex) │
└─────────┴───────────────────────────────────┘

Full Changelog: v0.1.1...0.2.0

v0.1.1

Full Changelog: v0.1.0...v0.1.1

v0.1.0

Full Changelog: v0.0.1...v0.1.0

v0.0.1

Reporails Rules v0.0.1

Initial release of community-maintained rules for linting AI coding agent instruction files.

Included

• 37 core rules across 5 categories (Structure, Content, Efficiency, Governance, Maintenance)
• 6 Claude-specific rules
• Claude Code skills for contributing (/generate-rule, /validate-rules, etc.)

Categories

Category	Rules	Focus
Structure	S1-S7	File organization, size limits
Content	C1-C12	Clarity, completeness
Efficiency	E1-E8	Token optimization
Governance	G1-G8	Ownership, security
Maintenance	M1-M7	Versioning, review

Usage

uvx reporails-cli init
ails check .