reporails · cleverhoods · May 12, 2026 · May 9, 2026 · May 10, 2026 · May 11, 2026
diff --git a/.ails/backbone.yml b/.ails/backbone.yml
diff --git a/.gitignore b/.gitignore
@@ -16,15 +16,21 @@ specs/
 /.mcp.json
 /CLAUDE.md
 
+# Local project backbone (developer-private; documents internal modules,
+# specs paths, and toolchain that should not ship in a public repo)
+/.ails/backbone.yml
+
 # Pre-existing local rule-harness scaffolds with the wrong filename for CORE
 # rules (should be AGENTS.md — agent-agnostic). 0.5.6 will rename these and
 # track them properly. Until then they live local-only.
 framework/rules/**/tests/**/CLAUDE.md
 framework/rules/**/tests/**/.claude/
 
-# Bundled ONNX embedding model — fetched by scripts/fetch_bundled_model.py
-# (dev-only, not committed; populated on clone and in CI before hatch build)
+# Bundled ML assets — fetched by scripts/fetch_bundled_model.py
+# (dev-only, not committed; populated on clone and in CI before hatch build).
+# ONNX embedder (~80 MB) + spaCy en_core_web_sm pipeline (~15 MB).
 src/reporails_cli/bundled/models/
+src/reporails_cli/bundled/spacy/
 
 # npm packaging — README.md is copied from the repo root by the prepack
 # script in packages/npm/package.json before `npm pack` / `npm publish`.

diff --git a/.ignore b/.ignore
@@ -1,5 +1,5 @@
 # Prevent Claude Code from discovering .claude directories inside test fixtures
 # as real configuration. Ripgrep (used by Claude for file discovery) respects
 # .ignore files with .gitignore syntax.
-framework/rules/**/tests/**
+framework/rules/**/**/tests/**
 tests/fixtures/**
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.5.9
+
+### Added
+
+- Tooling: `uv run poe specs_check` validates internal subsystem coverage (declared subsystems exist, each spec is within line-budget, modules colocate under one subpackage); `uv run poe spec_drift` flags potentially stale design docs whose source has been edited more recently
+- Tooling: expanded `pytest` marker taxonomy in `pyproject.toml` for granular test selection (lane, cost, subsystem) with new poe tasks `test_fast`, `test_arch`, `test_contracts`, `test_markers`
+- Tooling: every `tests/*` test function now carries pytest lane (`unit`/`integration`/`e2e`) + subsystem (`subsys_*`) markers; `check_test_markers.py` enforces tagging on every `qa_fast` run, enabling `pytest -m subsys_caching` and similar slicing
+- Tooling: hexagonal platform substrate skeleton bootstrapped at `core/platform/{contract,dto,policy,adapters,runtime,config,observability,utils}` with report-only architecture tests guarding pure-layer purity and adapter boundary (`tests/unit/architecture/`)
+
+### Changed
+
+- Build: bundle the `en_core_web_sm` spaCy pipeline (~15 MB) inside the wheel under `bundled/spacy/`, alongside the existing bundled ONNX embedder. `core/mapper/models.py` loads the pipeline by local filesystem path. End users no longer need a separate model download — `pip install reporails-cli` (or `uv pip install`, or `npx @reporails/cli`) delivers the full model bundle.
+- Build: tightened `requires-python` to `>=3.12,<3.14`; Python 3.14 ships a `pydantic.v1` introspection regression that breaks `import spacy`. The CLI's verb-lexicon fallback covered the failure silently but with reduced precision. The pin restores spaCy classification under `uv sync`.
+- API client: outgoing diagnostic requests now carry a `User-Agent: reporails-cli/<version>` header for accurate attribution in server-side logs; previously the generic `python-httpx/<version>` default was sent.
+- Funnel: rate-limit CTA surfaces a "Try again in ~N min." hint when the server returns `reset_in`, between the limit blurb and the upgrade prompt.
+- Funnel: CTA and bug-report URLs render as OSC 8 terminal hyperlinks with a short clickable label (`github.com/reporails/cli/issues/new`) instead of dumping the full percent-encoded prefilled URL; falls back to the short label on terminals without hyperlink support.
+- Funnel: demoted the "Could not parse N response body" and "Server returned N for tier=" stderr warnings to debug logging so they no longer print above the diagnostic report; reworded the `unknown_error` CTA to `Diagnostics server returned HTTP <code>`.
+- Display: file rows annotate duplicates with `(+alias)` labels — symlinked surfaces show the differing path component (e.g. `mintlify (+.claude)`), same-directory content-identical pairs show the alternate filename (e.g. `AGENTS.md (+CLAUDE.md)`).
+- Internals: hexagonal platform substrate consolidated under `core/platform/{contract,dto,policy,adapters,runtime,config,observability,utils}`. Every top-level `core/*.py` moved into its appropriate layer (DTOs, adapters, runtime, etc.), with a new `core/install/` subsystem for installer-related modules. Architecture tests at `tests/unit/architecture/` run in fail mode — any forbidden cross-layer import blocks the build.
+- Internals: five subsystems consolidated into named subpackages — `core/cache/`, `core/funnel/`, `core/classify/`, `core/heal/`, `core/discovery/`, `core/lint/` — each matching its design boundary.
+- Internals: the mapper subsystem went the furthest. `core/mapper/mapper.py` was split into one module per pipeline stage (`imports.py`, `parse.py`, `classify.py`, `annotate.py`, `embed.py`, `cluster.py`, `assemble.py`) plus shared `models.py`, `serialize.py`, `inspect.py`. The orchestration spine retains the name `core/mapper/pipeline.py`. Public import surface (`map_ruleset`, `content_hash`, `map_file`) is unchanged; callers now import via the `core.mapper` package facade.
+- Internals: removed the legacy "recommended" rules-overlay machinery from `ails config set/get/list`, `GlobalConfig`/`ProjectConfig`, and `core/install/`. User-installed rule packages remain supported through the generic `packages: [...]` mechanism in `.ails/config.yml` (clone any rule pack into `.ails/packages/<name>/` or `~/.reporails/packages/<name>/`).
+
+### Fixed
+
+- Check: `frontmatter_valid_glob` no longer crashes on comma-separated `paths:` values; each entry is now split and validated individually, and invalid glob syntax surfaces as a structured check failure instead of an unhandled exception
+- Discovery: skill and rule files that appear under multiple agent surfaces via symlinks (e.g. `.claude/skills/` → `.agents/skills/`) are now collapsed to one canonical entry, eliminating duplicate findings and inflated scoring
+
+### Removed
+
+- CLI: removed `ails map`.
+
 ## 0.5.8
 
 ### Added

diff --git a/CLAUDE.md b/CLAUDE.md
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
-# Reporails CLI (v0.5.8)
+# Reporails CLI (v0.5.9)
 
-> **AI Instruction Diagnostics for coding agents. Validates the entire agentic instruction system against 92+ rules across six categories. Supports Claude, Codex, Copilot, Cursor, and Gemini.**
+> **AI Instruction Diagnostics for coding agents. Validates the entire agentic instruction system against 120+ rules across six rule packs (core + per-agent). Supports Claude, Codex, Copilot, Cursor, and Gemini.**
 > 
 > *Beta phase - moving fast, feedback welcome.*
 

diff --git a/framework/rules/core/heading-as-instruction/rule.md b/framework/rules/core/heading-as-instruction/rule.md
@@ -42,4 +42,4 @@ Use the heading as a section label and put the instruction in the first line of
 
 ## Limitations
 
-Detects charged heading atoms (headings classified as directive, imperative, or constraint by the charge classifier). Short headings with common verbs may be false positives — "## Process" is a label, not an instruction, but contains a verb.
+Detects headings classified as directive, imperative, or constraint. Short headings with common verbs may be false positives — "## Process" is a label, not an instruction, but contains a verb.
diff --git a/hatch_build.py b/hatch_build.py
@@ -15,10 +15,12 @@
     "framework/sources.yml": "reporails_cli/sources.yml",
 }
 
-# Bundled model (gitignored, but must be in wheel).
+# Bundled ML assets (gitignored, but must be in wheel).
 # Populated by scripts/fetch_bundled_model.py before build.
 BUNDLED_MODEL = "src/reporails_cli/bundled/models"
 BUNDLED_MODEL_DEST = "reporails_cli/bundled/models"
+BUNDLED_SPACY = "src/reporails_cli/bundled/spacy"
+BUNDLED_SPACY_DEST = "reporails_cli/bundled/spacy"
 
 # Directory names to skip when bundling (rule test fixtures are dev-only)
 SKIP_DIRS = {"tests"}
@@ -53,6 +55,15 @@ def initialize(self, version: str, build_data: dict[str, Any]) -> None:
                 rel = path.relative_to(root / "src")
                 force_include[str(path)] = str(rel)
 
+        # Bundle spaCy en_core_web_sm model (gitignored but required at runtime)
+        spacy_dir = root / BUNDLED_SPACY
+        if spacy_dir.is_dir():
+            for path in spacy_dir.rglob("*"):
+                if not path.is_file():
+                    continue
+                rel = path.relative_to(root / "src")
+                force_include[str(path)] = str(rel)
+
         # Remove the pyproject.toml force-include entries (they'd double-include)
         # — handled by clearing them from config before this hook, or by
         #   removing them from pyproject.toml entirely.

diff --git a/packages/npm/package.json b/packages/npm/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@reporails/cli",
-  "version": "0.5.8",
+  "version": "0.5.9",
   "description": "AI instruction diagnostics for coding agents",
   "type": "module",
   "bin": {

diff --git a/pyproject.toml b/pyproject.toml
@@ -1,10 +1,10 @@
 [project]
 name = "reporails-cli"
-version = "0.5.8"
+version = "0.5.9"
 description = "AI instruction diagnostics for coding agents"
 readme = "README.md"
 license = "BUSL-1.1"
-requires-python = ">=3.12"
+requires-python = ">=3.12,<3.14"
 authors = [{ name = "Reporails Team" }]
 keywords = ["ai-instructions", "claude", "codex", "copilot", "cursor", "gemini", "diagnostics", "validation", "mcp"]
 classifiers = [
@@ -34,9 +34,11 @@ dependencies = [
     "onnxruntime>=1.18,<2",
     "tokenizers>=0.19,<1",
     "numpy>=1.26,<3",
-    # spaCy drives Phase 3 imperative classification in the mapper. It's a
-    # hard requirement — the fallback verb lexicon drops charge accuracy
-    # from 96% to ~78%. With the torch blocker active, spaCy loads in ~1s.
+    # spaCy provides the dependency-parser branch of the classifier. With
+    # the torch blocker active, spaCy loads in ~1s. The en_core_web_sm
+    # pipeline files ship inside the wheel under bundled/spacy/ rather
+    # than as a separate runtime dep — spaCy does not publish its language
+    # models on PyPI, so a direct-URL pin would block PyPI publication.
     "spacy>=3.8.11,<4",
     # sklearn for topic clustering in mapper
     "scikit-learn>=1.4.0",
@@ -91,8 +93,6 @@ Issues = "https://github.com/reporails/cli/issues"
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
-[tool.hatch.metadata]
-
 [tool.hatch.build.targets.wheel]
 packages = ["src/reporails_cli"]
 artifacts = [
@@ -110,10 +110,16 @@ type = "mypy src/"
 test_unit = "pytest tests/unit/ -v"
 test_integration = "pytest tests/integration/ -v"
 test_smoke = "pytest tests/smoke/ -v -m e2e"
-qa_fast = ["fmt", "lint_fix", "lint", "pylint_struct", "type", "test_unit"]
+qa_fast = ["fmt", "lint_fix", "lint", "pylint_struct", "type", "test_markers", "test_unit"]
 qa = ["fmt", "lint_fix", "lint", "pylint_struct", "type", "test_unit", "test_integration", "test_smoke"]
 mcp_dev = "python -m reporails_cli.interfaces.mcp.server"
 fetch_bundled_model = "python scripts/fetch_bundled_model.py"
+specs_check = "python scripts/specs_check.py"
+spec_drift = "python scripts/check_spec_drift.py"
+test_markers = "python scripts/check_test_markers.py"
+test_fast = "pytest -m 'unit and not slow and not requires_model'"
+test_arch = "pytest -m architecture"
+test_contracts = "pytest -m contract"
 
 [tool.ruff]
 target-version = "py312"
@@ -171,7 +177,29 @@ max-module-lines = 600
 testpaths = ["tests"]
 addopts = "--strict-markers"
 markers = [
-    "unit: Fast, isolated unit tests",
-    "integration: Cross-component tests",
-    "e2e: End-to-end tests",
+    # Lane — mutually exclusive within a test
+    "unit: Fast, isolated, no I/O outside repo, no ML models",
+    "integration: Cross-component, may load ML models",
+    "e2e: End-to-end CLI on fixture project",
+    "smoke: Alias for e2e (preferred for new tests)",
+    "architecture: AST/structural assertions across the codebase",
+    "contract: Pure validator function in isolation",
+    # Cost — orthogonal, additive
+    "slow: Takes more than 1 second",
+    "requires_model: Needs the bundled ML runtime",
+    "requires_network: Hits real external service",
+    "real_deps: Needs API key or live backend",
+    # Subsystem tags — one or more per test
+    "subsys_caching",
+    "subsys_map",
+    "subsys_classify",
+    "subsys_runtime",
+    "subsys_heal",
+    "subsys_funnel",
+    "subsys_lint",
+    "subsys_diagnostic",
+    "subsys_server",
+    "subsys_api",
+    "subsys_gates",
+    "subsys_cli_ux",
 ]
Original file line number	Diff line number	Diff line change
Expand Up		@@ -42,4 +42,4 @@ Use the heading as a section label and put the instruction in the first line of

		## Limitations

		Detects charged heading atoms (headings classified as directive, imperative, or constraint by the charge classifier). Short headings with common verbs may be false positives — "## Process" is a label, not an instruction, but contains a verb.
		Detects headings classified as directive, imperative, or constraint. Short headings with common verbs may be false positives — "## Process" is a label, not an instruction, but contains a verb.