ai-rulez 5.2.1 → 5.3.0

package/README.md

@@ -45,10 +45,10 @@ repository can loosen.
 
 | Stage | What happens | Commands | Docs |
 | ----- | ------------ | -------- | ---- |
-| **Author** | Rules, context, skills, agents, commands and checks as markdown in `.ai-rulez/`, with domains, profiles, roles and includes. `.ai-rulez/` is an [OKF](docs/okf.md) bundle: OKF is the internal format, and `init`, `add` and the MCP tools write it. A pre-OKF tree still loads, with a deprecation notice; `migrate okf` converts it. | `init`, `add`, `convert`, `import`, `migrate okf` | [Author](docs/configuration.md) |
+| **Author** | Rules, context, skills, agents, commands and checks as markdown in `.ai-rulez/`, with domains, profiles, roles and includes. `.ai-rulez/` is an [OKF](docs/okf.md) bundle: OKF is the internal format, and `init`, `add` and the MCP tools write it. A pre-OKF tree still loads, with a deprecation notice; `migrate okf` converts it. Or keep `AGENTS.md` and `.agents/` as the source with `source = "agents"`: ai-rulez translates them to every other tool and never writes into them ([guide](docs/agents-source.md)). | `init`, `add`, `convert`, `import`, `migrate okf` | [Author](docs/configuration.md) |
 | **Generate** | Native files for 52 harnesses (Claude Code, Cursor, Codex, Copilot, Gemini CLI, OpenCode, Devin, Kilo and more), per project or per user. | `generate`, `doctor`, `clean` | [Harnesses](docs/harnesses.md) |
 | **Bundle** | Distributable plugin bundles, an Agent Plugins package, an OKF bundle, an ARD manifest, `AGENTS.md` and `llms.txt`. | `generate --plugin`, `export okf` | [Plugins](docs/plugins.md) |
-| **Lint and validate** | Content and security checks with stable `AR` codes, plus each standard's own schema or rules. | `validate`, `scan`, `okf validate`, `verify` | [Validate](docs/strict-validation.md) |
+| **Lint and validate** | Content and security checks with stable `AR` codes, plus each standard's own schema or rules. Works in a repository with no ai-rulez config (`--path`, `--glob` and `--outputs` pick what to lint); `judge` grades instruction files with a model, also without config. | `validate`, `scan`, `judge`, `okf validate`, `verify` | [Validate](docs/strict-validation.md) |
 | **Govern** | A content-pinning lock, reviewer approvals, Sigstore signing, an organization policy and an SBOM. | `lock`, `approve`, `sign`, `verify --attestation`, `sbom` | [Trust model](docs/trust-model.md) |
 | **Publish** | Reproducible, checksummed release artifacts to GitHub releases, npm, OCI and marketplaces. | `publish` | [Publish](docs/publish.md) |
 
@@ -144,7 +144,7 @@ each row, and is the source of truth for test status.
 | [CycloneDX / SPDX SBOM](docs/sbom.md) | supported | `sbom` | `sbom --check` |
 | [in-toto / DSSE / Sigstore](docs/signing.md) | supported | `sign` | `verify --attestation` |
 | [OpenTelemetry (OTLP)](docs/telemetry.md) | supported | `telemetry export --to otlp` | not applicable |
-| "Agent bundle" | planned, no spec yet | none | none |
+| "Agent bundle" | planned, no pinned spec | none | none |
 
 ## Usage
 
@@ -302,6 +302,9 @@ configured scope and plugin name for the released package.
 ai-rulez validate                        # config plus content checks, exit 2 on findings
 ai-rulez validate --explain AR001        # what a rule checks and how to suppress it
 ai-rulez validate --format sarif --output ai-rulez.sarif
+ai-rulez validate --path catalog --glob "plugins/**/*.json"   # also lint files outside .ai-rulez/
+ai-rulez validate --outputs              # also lint the generated files; each problem is reported once
+ai-rulez validate --strict               # in any repo: with no config it lints AGENTS.md, SKILL.md, .claude/, .agents/
 ai-rulez okf validate docs/okf           # lint any OKF bundle, ai-rulez's or a third party's
 ai-rulez generate --check                # generated files still match their sources
 ```
@@ -344,13 +347,16 @@ An organization [policy](docs/policy.md) sets tighten-only floors a repository c
 - **Telemetry.** Item-load records with an optional OTLP export. See [telemetry](docs/telemetry.md).
 - **Evals and improve.** `ai-rulez eval` scores skills; `improve` (experimental) optimizes them behind a held-out eval
   gate. See [evals](docs/evals.md) and [improve](docs/improve.md).
+- **Judge.** `ai-rulez judge` grades `AGENTS.md` and `.agents/*` with a model from the command line alone, with no config
+  file: `ai-rulez judge --estimate --model openai/gpt-4o-mini`, then `--allow-llm` to send. See [judge](docs/judge.md).
 - **Cost and inventory.** `tokens`, `cost`, `catalog` and `search` report what the configuration contains and costs.
 
 Existing project on 4.x? Run `ai-rulez migrate v5 --dry-run`, then see [Migrating to v5](docs/migration-v5.md).
 
 ## Documentation
 
-Full documentation at [goldziher.github.io/ai-rulez](https://goldziher.github.io/ai-rulez/).
+Full documentation at [goldziher.github.io/ai-rulez](https://goldziher.github.io/ai-rulez/). For how a source becomes
+generated files, and the package map, see [Architecture](docs/architecture.md).
 
 ## Git Hooks
 
@@ -364,7 +370,7 @@ Add to `.pre-commit-config.yaml`:
 ```yaml
 repos:
   - repo: https://github.com/Goldziher/ai-rulez
-    rev: v5.2.1
+    rev: v5.3.0
     hooks:
       - id: ai-rulez-recursive   # generate: write outputs for every nested .ai-rulez/ root
       - id: ai-rulez-validate    # validate --recursive: content, security and link checks
@@ -395,7 +401,7 @@ repository needs:
 [[hooks.sources]]
 id = "ai-rulez"
 git = "https://github.com/Goldziher/ai-rulez.git"
-revision = "v5.2.1"
+revision = "v5.3.0"
 hooks = ["ai-rulez-recursive", "ai-rulez-plugin-verify"]
 ```
 
@@ -468,9 +474,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: Goldziher/ai-rulez@main   # pin a release tag once one exists past v5.1.0 (the tag predates action.yml)
+      - uses: Goldziher/ai-rulez@v5.2.1   # a release tag from v5.2.0 on carries action.yml; pin the one you reviewed
         # with:
-        #   version: 5.1.0   # optional; omit (or "latest") to always use the newest release
+        #   version: 5.2.1   # optional; omit (or "latest") to always use the newest release
       - run: ai-rulez generate --check   # the committed output matches the sources
       - run: ai-rulez validate --strict  # content and security checks, warnings fail
       - run: ai-rulez lock --check        # pins were updated when the sources were

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-rulez",
-  "version": "5.2.1",
+  "version": "5.3.0",
   "description": "Standards-compliant lifecycle tool for agent knowledge and capabilities. Author rules, skills, agents and MCP servers once; generate for 52 harnesses; bundle as OKF, Agent Plugins and ARD; validate against each standard; govern with signing, approvals and policy; publish.",
   "keywords": [
     "agent-plugins",