release: v0.5.0-audit-rename - #72
Merged
Merged
Conversation
…ements (#55) ## Summary Closes the bidirectional spec/check coverage gap surfaced by an audit: the registry had 27 requirements with no verifier and 5 cli checks had no `covers()` declaration. This branch wires what is verifiable via the behavioral layer and adds the two `p3-version` requirements the existing `VersionCheck` was already enforcing in spirit. Net result: 39 covered spec IDs (up from 32), 20 spec orphans (down from 27), 51 dogfood checks (up from 44). Depends on the spec PR adding `p3-must-version` and `p3-should-version-short` to `agentnative-spec`. The vendored copy in this branch already carries the new requirements so the cli builds standalone; re-running `scripts/sync-spec.sh` after the spec PR tags will be a no-op. ## Changelog ### Added - Add `p2-raw-flag`, `p2-more-formats`, `p3-examples-subcommand`, `p6-color-flag`, `p7-verbose`, `p7-limit`, and `p7-cursor-pagination` behavioral checks. The two list-style checks (`p7-limit`, `p7-cursor-pagination`) vacuously skip when the target CLI has no list-style subcommand; the other five always run and produce Pass / Warn on flag presence in top-level `--help`. - `VersionCheck` now probes the short-alias family (`-V`, `-v`, `-version`) alongside `--version`. Pass when both work, Warn when only `--version` works (MUST satisfied, SHOULD missed), Fail when neither works. - `AgentsMdCheck` now declares it covers `p8-should-bundle-exists`. The check already verified a subset of what P8 demands; this exposes the link to the coverage matrix. ### Changed - Vendored spec bump: `src/principles/spec/principles/p3-progressive-help-discovery.md` carries the two new `p3-must-version` and `p3-should-version-short` requirements (universal applicability). `REQUIREMENTS.len()` 57 -> 59; MUST count 27 -> 28; SHOULD count 20 -> 21; MAY count unchanged at 10. - Coverage matrix regenerated: `docs/coverage-matrix.md` and `coverage/matrix.json` reflect 59 requirement rows and the new verifier links. ### Documentation - Update `tests/build_parser.rs` and `src/principles/registry.rs` test counters to match the new 59-requirement registry. ## Type of Change - [x] `feat`: New feature (non-breaking change which adds functionality) ## Related Issues/Stories - Story: n/a - Issue: n/a - Architecture: Cross-repo coordination — spec changes live in the companion PR on `brettdavies/agentnative` branch `feat/p3-must-version`. Both PRs should land together, or the spec PR can land first and the cli PR will re-vendor at sync time without further changes. - Related PRs: n/a (spec companion PR linked at the top of this body) ## Testing - [x] Unit tests added/updated - [x] Integration tests added/updated - [x] Manual testing completed - [x] All tests passing **Test Summary:** - New tests for the 7 behavioral checks (3-4 cases each: Pass / Warn / Skip / applicability gate) plus the shared `behavioral::list_style::has_list_style_subcommand` helper (5 cases covering verb-list drift). New tests for the extended `VersionCheck` (Warn when only `--version` works, Pass when a short alias also works). 21 new test cases total. - `cargo test`: 621 passed, 2 ignored across 7 suites. - `cargo clippy --release --all-targets -- -Dwarnings`: clean. - `cargo fmt --check`: clean. - `./target/release/anc check .`: 51 checks, 37 pass, 7 warn, 0 fail, 7 skip, 0 error. Score 84% (down from 93% pre-branch because four new MAY/SHOULD checks legitimately surface gaps in `anc` itself: no `--raw`, no `--examples`, no `--color`, no `--verbose`). - Bidirectional audit: 0 dangling covers references; 20 spec orphans (down from 27); 39 covered IDs (up from 32). ## Files Modified **Modified:** - `coverage/matrix.json`, `docs/coverage-matrix.md` (regenerated artifacts). - `src/checks/behavioral/mod.rs` (registers 7 new checks + 1 shared helper module). - `src/checks/behavioral/version.rs` (extended check + 2 new test cases). - `src/checks/project/agents_md.rs` (added `covers()` declaration). - `src/principles/registry.rs` (test counters 57 -> 59, MUST 27 -> 28, SHOULD 20 -> 21). - `src/principles/spec/principles/p3-progressive-help-discovery.md` (vendored from spec branch). - `tests/build_parser.rs` (test counter 57 -> 59). **Created:** - `src/checks/behavioral/color_flag.rs` - `src/checks/behavioral/cursor_pagination.rs` - `src/checks/behavioral/examples_subcommand.rs` - `src/checks/behavioral/limit_flag.rs` - `src/checks/behavioral/list_style.rs` (shared helper) - `src/checks/behavioral/more_formats.rs` - `src/checks/behavioral/raw_flag.rs` - `src/checks/behavioral/verbose_flag.rs` **Renamed:** - None. **Deleted:** - None. ## Breaking Changes - [x] No breaking changes ## Deployment Notes - [x] No special deployment steps required. The cli ships standalone with the vendored spec changes; once the spec PR tags a release, `scripts/sync-spec.sh` will be a no-op on this content. ## Additional Context Remaining 20 spec orphans queued for follow-up branch(es), grouped by required follow-up shape: - Error-battery probes: `p2-must-exit-codes`, `p2-must-json-errors`, `p4-must-actionable-errors`, `p4-should-json-error-output`. - Source-layer work (out of scope for this branch): `p4-should-gating-before-network`, `p5-should-idempotency`, `p6-should-tier-gating`. - Destructive-op detection: `p5-must-force-yes`, `p5-must-read-write-distinction`. - Subcommand-help recursion: `p3-must-subcommand-examples`, `p3-should-paired-examples`, `p3-should-about-long-about`, `p6-should-subcommand-operations`. - Stdin probe: `p6-should-stdin-input`. - Spec disambiguation (`p7-should-timeout` overlaps semantically with the verified `p6-must-timeout-network`). - Conditional-applicability gating: `p1-should-defaults-in-help`, `p1-may-rich-tui`, `p2-should-consistent-envelope`, `p6-should-consistent-naming`, `p7-may-auto-verbosity`.
…#56) ## Summary Continues the spec/check coverage-closing work from #55. Six new behavioral checks wire previously-orphaned spec requirements via `--help` probes and a `-h` vs `--help` differential probe. Covers 6 of the 14 orphans remaining after #55. The rest need error-battery setup, source-layer work, or destructive-op detection (queued for follow-up branches). No spec changes this round; all requirements already exist in the registry. ## Changelog ### Added - Add `p1-defaults-in-help` behavioral check. Scans `--help` for `[default: …]` / `(default: …)` / `default:` annotations. SHOULD-tier, universal. - Add `p1-rich-tui` behavioral check. Detects rich-TUI surface area via `--tui` / `--interactive` / `--ui` flags or spinner/progress/tui/ncurses/indicatif mentions in help text. MAY-tier, universal. - Add `p3-about-long-about` behavioral check. Probes both `-h` and `--help` directly and Warns when the two outputs are byte-identical (no `long_about` defined). SHOULD-tier, universal. - Add `p6-stdin-input` behavioral check. Gated on input-accepting subcommand verbs (process/parse/convert/transform/analyze/validate/format/lint/check); Warns when help text does not mention stdin or `-` as a path placeholder. SHOULD-tier, conditional. - Add `p6-consistent-naming` behavioral check. Classifies subcommands against a common-verb list; Warns when verb-first and noun-first patterns mix. SHOULD-tier, conditional on 2+ user-defined subcommands. - Add `p7-timeout-behavioral` behavioral check. Gated on long-running subcommand verbs (serve/daemon/watch/tail/monitor/follow/run/start/stream); Warns when no `--timeout` / `--deadline` / `--max-time` flag advertised. SHOULD-tier, conditional. Distinct from the source-layer `p6-must-timeout-network` which gates on network-library usage. ### Changed - Coverage matrix regenerated: `docs/coverage-matrix.md` and `coverage/matrix.json` reflect 6 new verifier links across P1, P3, P6, and P7 requirement rows. ## Type of Change - [x] `feat`: New feature (non-breaking change which adds functionality) ## Related Issues/Stories - Story: n/a - Issue: n/a - Architecture: No spec changes — all 6 requirements already existed in the registry. This PR adds the verifier checks. - Related PRs: #55 (prior coverage-closing batch). ## Testing - [x] Unit tests added/updated - [x] Integration tests added/updated - [x] Manual testing completed - [x] All tests passing **Test Summary:** - 22 new test cases across the 6 new checks: Pass / Warn / Skip paths for each, plus applicability-gate verification for the conditional checks (`p6-stdin-input`, `p6-consistent-naming`, `p7-timeout-behavioral`). - `cargo test`: 642 passed, 2 ignored across 7 suites. - `cargo clippy --release --all-targets -- -Dwarnings`: clean. - `cargo fmt --check`: clean. - `./target/release/anc check .`: 57 checks (up from 51), 37 pass, 12 warn, 0 fail, 8 skip, 0 error. Score drops from 84% to ~75% because the 6 new checks legitimately surface gaps in `anc` itself (no default-value annotations on top-level help; no TUI surface; identical `-h`/`--help` output; no stdin docs on the `check` subcommand at the top level; mixed verb/noun subcommand naming; vacuous skip on the timeout gate). - Bidirectional audit: 0 dangling covers references; 14 spec orphans (down from 20); 45 covered IDs (up from 39). ## Files Modified **Modified:** - `coverage/matrix.json`, `docs/coverage-matrix.md` (regenerated artifacts). - `src/checks/behavioral/mod.rs` (registers 6 new check modules). **Created:** - `src/checks/behavioral/about_long_about.rs` - `src/checks/behavioral/consistent_naming.rs` - `src/checks/behavioral/defaults_in_help.rs` - `src/checks/behavioral/rich_tui.rs` - `src/checks/behavioral/stdin_input.rs` - `src/checks/behavioral/timeout_behavioral.rs` **Renamed:** - None. **Deleted:** - None. ## Breaking Changes - [x] No breaking changes ## Deployment Notes - [x] No special deployment steps required. ## Additional Context Remaining 14 orphans queued for subsequent branches, grouped by required follow-up shape: - Error-battery probes (5): `p2-must-exit-codes`, `p2-must-json-errors`, `p2-should-consistent-envelope`, `p4-must-actionable-errors`, `p4-should-json-error-output`. All need a known-bad invocation harness and assertion on JSON envelope shape / exit codes. - Subcommand-help recursion (3): `p3-must-subcommand-examples`, `p3-should-paired-examples`, `p6-should-subcommand-operations`. Each subcommand needs its own `--help` probe. - Destructive-op detection (2): `p5-must-force-yes`, `p5-must-read-write-distinction`. Both need a heuristic to classify whether a CLI has destructive operations. - Source-layer work (out of scope for behavioral-only batches): `p4-should-gating-before-network`, `p5-should-idempotency`, `p6-should-tier-gating`. - Auto-verbosity (1): `p7-may-auto-verbosity`. Needs TTY-vs-pipe behavior comparison rather than a flag probe.
…e) (#57) ## Summary Wires 11 behavioral checks against the 11 remaining behavioral-doable orphan requirements. After this batch lands, the only orphans left will be the 3 source-layer ones declared out of scope by current policy (`p4-should-gating-before-network`, `p5-should-idempotency`, `p6-should-tier-gating`). The work is grouped by probe shape so checks within a group share helpers and runner cache: - **Group A: error-battery (5 checks):** a single bad-flag probe (`--this-flag-does-not-exist-anc`) feeds five P2/P4 checks that observe exit codes, error messages, and JSON envelopes. - **Group B: subcommand-help recursion (3 checks):** a shared helper walks each top-level subcommand's `--help` (capped at one level, skipping built-in `help`/`completions`) and feeds three P3/P6 example/operation checks. - **Group C: destructive-op detection (2 checks):** a shared verb list classifies subcommand names as destructive/read/write and feeds two P5 safety checks. - **Group D: TTY-vs-pipe (1 check):** scans `--help` for TTY-aware language since pty allocation is out of scope. Audit confirms orphan count drops from 14 to 3, MUST orphans drop to zero, behavioral coverage is complete. ## Changelog ### Added - 11 behavioral checks closing the remaining behavioral orphan coverage: structured exit codes, JSON error envelopes, consistent envelope shape, actionable error messages, JSON error output, subcommand examples, paired text+JSON examples, subcommand-shaped operations, force/yes on destructive subcommands, read/write surface distinction, and TTY-aware verbosity. ## Type of Change - [x] `feat`: New feature (non-breaking change which adds functionality) ## Related Issues/Stories - Story: n/a - Issue: n/a - Architecture: n/a - Related PRs: #55, #56 (prior orphan-coverage batches) ## Testing - [x] Unit tests added/updated - [x] Integration tests added/updated - [x] Manual testing completed - [x] All tests passing **Test Summary:** - Unit tests: 624 passing (was 575; +49 new) - Integration tests: 12 dogfood + convention tests passing - Pre-push gate (mirrors CI): fmt clean, clippy `-Dwarnings` clean, cargo-deny clean, Windows compat clean Coverage matrix regenerated and drift-check clean (`anc generate coverage-matrix --check` exits 0). ## Files Modified **Modified:** - `src/checks/behavioral/mod.rs`: register 11 new check structs plus 3 shared helper modules. - `tests/dogfood.rs`: add `p2-json-errors` to the temporary allowlist with a justification (anc itself uses clap's `parse()` rather than `try_parse()`, so it emits plain-text errors regardless of `--output json`; honoring JSON mode for parse errors is separate work). - `coverage/matrix.json`: regenerated from the registry + `covers()` declarations. - `docs/coverage-matrix.md`: regenerated table now showing the 11 newly-covered IDs. **Created:** - `src/checks/behavioral/error_probe.rs`: shared bad-flag probe + JSON applicability gate (Group A). - `src/checks/behavioral/structured_exit_codes.rs`: `p2-must-exit-codes`. - `src/checks/behavioral/json_errors.rs`: `p2-must-json-errors` (strict 3-key envelope). - `src/checks/behavioral/consistent_envelope.rs`: `p2-should-consistent-envelope`. - `src/checks/behavioral/actionable_errors.rs`: `p4-must-actionable-errors`. - `src/checks/behavioral/json_error_output.rs`: `p4-should-json-error-output`. - `src/checks/behavioral/subcommand_help.rs`: shared subcommand `--help` recursion (Group B). - `src/checks/behavioral/subcommand_examples.rs`: `p3-must-subcommand-examples`. - `src/checks/behavioral/paired_examples.rs`: `p3-should-paired-examples`. - `src/checks/behavioral/subcommand_operations.rs`: `p6-should-subcommand-operations`. - `src/checks/behavioral/destructive_ops.rs`: shared destructive/read/write verb classification (Group C). - `src/checks/behavioral/force_yes.rs`: `p5-must-force-yes`. - `src/checks/behavioral/read_write_distinction.rs`: `p5-must-read-write-distinction`. - `src/checks/behavioral/auto_verbosity.rs`: `p7-may-auto-verbosity`. **Renamed:** - None. **Deleted:** - None. ## Key Features The dogfood pass against `anc` itself surfaces real, defensible gaps that future PRs should close: - `p2-json-errors` → Fail (allowlisted as pending; clap `parse()` vs `try_parse()`). - `p3-subcommand-examples` → Fail (subcommands lack example blocks; clap `after_help` would satisfy). - `p3-paired-examples`, `p4-json-error-output`, `p7-auto-verbosity` → Warn (room for improvement). These verdicts are the dogfooding loop working as designed: checks find real issues in the linter itself.
Dogfood `anc audit .` against itself surfaced 1 MUST failure
(`p2-json-errors`) plus a long tail of SHOULD/MAY warns. This branch
clears all of them: 0 fail, 0 warn, score 100%.
Final shape uses `audit` (matching `npm audit` / `cargo audit` /
`pip-audit` / `bundler-audit` convention) and `emit` (matching `rustc
--emit` for artifact production).
- Top-level `--verbose` / `-v` flag (env `AGENTNATIVE_VERBOSE`) for
diagnostic escalation, mutually exclusive with `--quiet`.
- Top-level `--examples` flag prints a curated invocation block and
exits. Pairs with `--output json` (or `--json`) so structured-output
consumers can fetch the block without parsing full `--help`.
- Top-level `--color auto|always|never` (env `AGENTNATIVE_COLOR`) wraps
text-mode status prefixes in ANSI styling, honoring NO_COLOR and TTY
detection.
- Top-level `--raw` emits one `id<TAB>status` line per check with no
headers, summary, or badge hint. Pipe-friendly for `grep`/`awk`
workflows.
- Per-subcommand `Examples:` blocks in `--help` for `audit`, `emit`,
`skill`.
- `anc skill install --all` and `anc skill update [host|--all]` iterate
every known host in one invocation. Update guards against operating on
non-bundle directories via a `SKILL.md` marker file.
- `audit` accepted as a community-standard verb in the p6-standard-names
check (alongside `npm audit`, `cargo audit`, etc.).
- BREAKING: `anc check` renamed to `anc audit`; `anc generate` renamed
to `anc emit`; `anc schema` removed and folded under `anc emit schema`.
The implicit-default-subcommand injection now writes `audit`. Update
scripts and CI invocations.
- Top-level `--help` now renders an extended description (`long_about`)
with paired text + JSON example invocations; `-h` still shows the
concise summary.
- `STANDARD_VERBS` in p6-standard-names is now alphabetized within and
across subgroups for review-friendliness; doc-comment notes the
invariant.
- `src/project.rs` stderr warnings now reference `anc audit src/`
instead of `anc check src/` when the file-walk hits depth or count
limits.
- Error output under `--output json` / `--json` now emits a JSON
envelope to stderr with `error`, `kind`, and `message` fields instead of
clap's plain-text rendering, so agents pinned to JSON can parse failures
with one shape.
- `--help --output json` and `--version --output json` emit JSON
envelopes so structured-output consumers can probe help and version
without a separate text parser.
- `--examples` is no longer `exclusive = true`, so `anc --examples
--output json` now produces the JSON envelope it always claimed to
support (was failing with `argument-conflict`).
- `EXAMPLES_BLOCK` content (printed by `anc --examples`) updated to use
current subcommand names (was still showing `anc check`, `anc generate`,
`anc schema`).
- p2-schema-print check now walks one level into top-level subcommand
help to discover `schema` exposed as a nested verb (e.g., `anc emit
schema`), matching how an agent walks `--help` chains. Benefits every
CLI checked by anc, not just anc itself.
-
`scorecard::audience::tests::duplicate_signal_in_results_trips_debug_assert`
is gated on `#[cfg(debug_assertions)]` so it runs only where
`debug_assert!` actually fires (previously failed silently under `cargo
test --release`).
- Embedded `schema/scorecard.schema.json` description fields updated to
reference `anc audit` rather than `anc check`.
- [x] `feat`: New feature (non-breaking change which adds functionality)
- [x] `fix`: Bug fix (non-breaking change which fixes an issue)
- [x] `refactor`: Code refactoring (no functional changes)
- [x] `BREAKING CHANGE`: Breaking API change (requires major version
bump on next release)
- Story: n/a
- Issue: n/a
- Architecture: n/a
- Related PRs: None
- [x] Unit tests added/updated
- [x] Integration tests added/updated
- [x] Manual testing completed
- [x] All tests passing
**Test Summary:**
- Release mode: 738 passed, 0 failed, 2 ignored.
- Debug mode: 739 passed, 0 failed, 2 ignored.
- New integration tests for the JSON envelope contract: bad invocation
under `--output json` AND `--json` alias, help/version under JSON mode,
and a negative test confirming text mode still uses clap's default
rendering.
- Dogfood: `./target/release/anc audit .` produces `68 checks: 58 pass,
0 warn, 0 fail, 10 skip, 0 error` and Score 100%.
Before vs after dogfood, by check ID:
| Check | Tier | Before | After |
| --- | --- | --- | --- |
| `p2-json-errors` | MUST | FAIL | PASS |
| `p3-subcommand-examples` | MUST | FAIL | PASS |
| `p2-json-output` | SHOULD | WARN | PASS |
| `p2-consistent-envelope` | SHOULD | SKIP | PASS |
| `p4-json-error-output` | SHOULD | WARN | PASS |
| `p3-about-long-about` | SHOULD | WARN | PASS |
| `p3-paired-examples` | SHOULD | WARN | PASS |
| `p1-defaults-in-help` | SHOULD | WARN | PASS |
| `p6-stdin-input` | SHOULD | WARN | PASS |
| `p6-consistent-naming` | SHOULD | WARN | PASS |
| `p7-verbose` | SHOULD | WARN | PASS |
| `p3-examples-subcommand` | MAY | WARN | PASS |
| `p1-rich-tui` | MAY | WARN | PASS |
| `p2-raw-flag` | MAY | WARN | PASS |
| `p6-color-flag` | MAY | WARN | PASS |
| `p7-auto-verbosity` | MAY | WARN | PASS |
| `p8-install-all` | MAY | WARN | PASS |
| `p8-bundle-update` | MAY | WARN | PASS |
**Modified:**
- `src/main.rs`: switch from `parse_from` to `try_parse_from`;
clap-error router for JSON envelope on help/version/parse-failure;
`--verbose` preflight; `--examples` short-circuit; `--raw` + `--color`
wiring; Generate → Emit + Check → Audit dispatch; runtime AppError path
routes through JSON envelope when JSON mode is requested.
- `src/cli.rs`: long_about, after_help per subcommand, `--verbose` /
`--examples` / `--color` / `--raw` flags, ColorChoice enum, Audit / Emit
/ Skill restructure, removal of top-level Schema variant.
- `src/argv.rs`: skip default-subcommand injection when top-level
`--help` / `-h` / `--version` / `-V` appears; `inject_audit` helper;
tests updated for the rename.
- `src/scorecard/mod.rs`: TextOptions { raw, color }, format_text_raw,
color application via anstyle, tests, doc-comments synced to renamed
surface.
- `src/skill_install.rs`: `run_install_multi` / `run_update_multi` /
`compute_update_envelope` with `--all` iteration and `SKILL.md` marker
guard for refresh.
- `src/checks/behavioral/schema_print.rs`: depth-1 subcommand walk for
nested `schema` discovery.
- `src/checks/behavioral/standard_names.rs`: add `audit` to
STANDARD_VERBS; alphabetize subgroups and entries within each.
- `src/principles/matrix.rs`: `GENERATED_BY` constant references the
renamed subcommand.
- `src/scorecard/audience.rs`: `#[cfg(debug_assertions)]` gate on
duplicate-signal-trips-debug-assert test.
- `src/project.rs`: stderr warnings about file-walk depth/count limits
reference the renamed subcommand.
- `tests/integration.rs`: JSON envelope assertions, exit-code-0
acceptance for self-dogfood, subcommand renames, test function name
renames.
- `tests/dogfood.rs`, `tests/scorecard_schema_v05.rs`,
`tests/scorecard_metadata_security.rs`, `tests/skill_install.rs`:
subcommand renames; runtime-guard message update for `skill install`
missing-host.
- `schema/scorecard.schema.json`: description fields updated to
reference `anc audit`.
- `completions/anc.bash`, `anc.zsh`, `anc.fish`, `anc.elvish`,
`anc.powershell`: regenerated against the renamed CLI surface.
- `coverage/matrix.json`: regenerated against the new `GENERATED_BY`
constant.
- `Cargo.toml`, `Cargo.lock`: `anstyle`, `anstream` declared as direct
deps (already transitive via clap).
- `README.md`, `AGENTS.md`, `CLAUDE.md`, `PRODUCT.md`,
`scripts/SYNCS.md`, `scripts/prose-check.sh`,
`.github/ISSUE_TEMPLATE/*`: command renames across consumer-facing docs.
**Created:**
- `src/json_error.rs`: argv sniff for JSON mode, envelope renderers
(error / help / version), clap error classifier.
- `src/color.rs`: `should_color` (TTY + NO_COLOR + ColorChoice),
`status_style`, `paint`.
**Renamed:**
- `Commands::Check` → `Commands::Audit`
- `Commands::Generate` → `Commands::Emit`
- `GenerateKind` → `EmitKind`
- `run_generate` → `run_emit`
- Test function families `test_check_*` → `test_audit_*`,
`test_generate_coverage_matrix_*` → `test_emit_coverage_matrix_*`.
**Deleted:**
- `Commands::Schema` (folded under `EmitKind::Schema`). Pre-1.0 break,
no back-compat alias per project direction.
- One JSON contract surface across help / version / errors: agents
pinned to `--output json` get a parseable envelope for every exit path.
- `anc audit .` reads like the conventional audit-tool invocation (`npm
audit`, `cargo audit`); the heuristic that previously rejected `audit`
was incomplete and is now corrected.
- The skill bundle has multi-host install and update via a single
invocation, with a marker-file guard so update never removes an
arbitrary directory the user typed by mistake.
- anc passes its own dogfood at 100%. Closes the gap that prevented anc
from displaying the badge it produces for others.
- Improves the p2-schema-print check for every tool: depth-1 subcommand
walk recognizes nested `schema` (e.g., `anc emit schema`) as
discoverable, matching how an agent discovers the surface via `--help`
chaining.
- `audit` added to `STANDARD_VERBS` benefits every audit-class CLI
checked by anc, not just anc itself.
- [x] Breaking changes described below
`anc check` → `anc audit`. `anc generate coverage-matrix` → `anc emit
coverage-matrix`. `anc schema` → `anc emit schema`. No back-compat
aliases; pre-1.0 (`0.4.0`) so the break is acceptable per project
direction. Scripts, CI invocations, and Makefiles need the rename.
- [x] No special deployment steps required
Behavior under `--output json` is byte-identical for the happy path;
only the error / help / version envelopes are new. Text-mode is
byte-identical except for the color flag's effect when explicitly set to
`always` in a non-TTY.
- [x] Code follows project conventions and style guidelines
- [x] Commit messages follow Conventional Commits
- [x] Self-review of code completed
- [x] Tests added/updated and passing
- [x] No new warnings or errors introduced
- [ ] Changes are backward compatible (no, see Breaking Changes above)
## Summary
Adds a `--ref <git-ref>` flag (and matching `SPEC_REF` env var) to
`scripts/sync-spec.sh` so the cli can vendor `agentnative-spec` from an
explicit branch, tag, or commit SHA, not just the latest `v*` tag.
Default behavior (no `--ref`) is unchanged: resolves the latest `v*`
tag.
Refactored the script's transport from `git clone` to `gh api` so all
ref types (latest tag, branch, tag, SHA) take the same code path through
`repos/{owner}/{repo}/contents/{path}?ref=<X>` with the raw accept
header. The local-checkout fallback (when `gh api` is unreachable) still
uses `git` against `SPEC_ROOT` for offline development.
## Changelog
### Added
- `scripts/sync-spec.sh` now accepts `--ref <git-ref>` (or `SPEC_REF`
env var) to vendor `agentnative-spec` from an explicit branch, tag, or
commit SHA. Default behavior unchanged: resolves the latest `v*` tag.
- The resolved short SHA prints every run regardless of ref type, so
consumer PRs can record the exact pin in their body.
### Changed
- `scripts/sync-spec.sh` transport refactored from `git clone` to `gh
api`. Reduces the shallow-vs-full clone distinction, makes ref
resolution uniform across tag / branch / SHA, and removes the need for a
local clone except as an offline fallback.
- `scripts/SYNCS.md` documents the new flag, the `gh api` transport, the
local-checkout fallback, and the convention of recording the resolved
SHA in any consumer PR body.
## Type of Change
- [x] `feat`: New feature (non-breaking change which adds functionality)
- [x] `docs`: Documentation update
## Related Issues/Stories
- Story: n/a
- Issue: n/a
- Architecture: cross-repo coordination between `agentnative-cli`,
`agentnative-spec`, and `agentnative-site` for in-flight spec work.
- Related PRs: `brettdavies/agentnative#34` (spec taxonomy unit on
`dev`, not yet tagged) is the motivating example. Site-side counterpart:
`brettdavies/agentnative-site` `feat/sync-spec-ref-flag` ships the same
flag surface for parity.
## Testing
- [x] Manual testing completed
- [x] All tests passing
**Test Summary:**
- `cargo build --release`: clean (the script change is a build-time
input but the vendored tree on this branch is unchanged, so the codegen
produces the same `REQUIREMENTS` slice).
- `bash scripts/sync-spec.sh --help` prints the documented banner
including the new flag and env var.
- Default invocation path (no `--ref`) still resolves the latest `v*`
tag via `gh api` and writes the same files into `src/principles/spec/`
as before.
## Files Modified
**Modified:**
- `scripts/sync-spec.sh`: `--ref` flag + `SPEC_REF` env var, `gh api`
transport, local-checkout fallback, resolved-SHA printout, banner
updated to current subcommand name (`anc audit`).
- `scripts/SYNCS.md`: documents the new flag, transport, fallback, and
the consumer-PR-body recording convention.
**Created:**
- None.
**Renamed:**
- None.
**Deleted:**
- None.
## Key Features
- Cross-repo coordination is explicit: a cli or site PR that depends on
in-flight spec work can pin the exact branch / tag / SHA being vendored
and record the resolved SHA in the PR body. No more silent "we re-pulled
`v0.4.0` and missed the conditional-applicability schema" surprises.
- The transport unification (`gh api` for all ref types) eliminates a
class of edge cases where shallow vs full clones behaved differently for
tag vs branch resolution.
## Benefits
- Unblocks the U2 scorecard-fairness work in `agentnative-cli`, which
needs the conditional-applicability shape that lives on the spec's `dev`
branch but isn't tagged yet.
- Reduces dependency on a local `~/dev/agentnative-spec` checkout. The
`gh api` path works in CI and on fresh machines without needing the spec
repo cloned locally.
## Breaking Changes
- [x] No breaking changes
Default behavior is byte-identical to before. The `--ref` flag is
opt-in; existing scripts that call `sync-spec.sh` with no arguments get
the same result.
## Deployment Notes
- [x] No special deployment steps required
Build-time input only. The vendored tree is unchanged on this branch, so
cargo's codegen produces the same output. The flag only matters when
someone re-runs `sync-spec.sh` with `--ref`.
## Checklist
- [x] Code follows project conventions and style guidelines
- [x] Commit messages follow Conventional Commits
- [x] Self-review of code completed
- [x] Tests added/updated and passing
- [x] No new warnings or errors introduced
- [x] Changes are backward compatible
## Summary `shellcheck scripts/sync-spec.sh` flagged a dead variable (`spec_ref`) introduced by the recent `--ref` refactor in #59. Removed. Zero behavior change. While here, closed the process gap that allowed it to ship: added `shellcheck` to the local pre-push hook. Also audited the sibling agentnative-* repos and the shared `brettdavies/.github` reusable workflow for the same gap; results in the Coverage Gap section below. ## Changelog ### Added - `scripts/hooks/pre-push` now runs `shellcheck --severity=warning` against every tracked `*.sh` plus everything under `scripts/hooks/` (so the hook itself is linted). Uses `git ls-files` so vendored / `.gitignore`d scripts are excluded. Skips with a one-line note if `shellcheck` is not installed, matching the existing `cargo deny` pattern. ### Fixed - Removed dead `spec_ref` variable in `scripts/sync-spec.sh` (SC2034). Declared during the `--ref` refactor in #59 but never read; the actual code uses the `SPEC_REF` env var directly. ## Type of Change - [x] `fix`: Bug fix (dead-code removal) - [x] `feat`: Pre-push hook gains a shellcheck step ## Related Issues/Stories - Story: n/a - Issue: n/a - Architecture: closes the local-side shell-linting gap that let SC2034 ship through #59. - Related PRs: #59 introduced the dead variable. CI-side and sibling-repo follow-ups described below. ## Testing - [x] Manual testing completed - [x] All tests passing **Test Summary:** - `shellcheck scripts/sync-spec.sh` → 0 findings (was 1 before). - `shellcheck --severity=warning <every tracked .sh + scripts/hooks/*>` → 0 findings across the whole tree. - `bash scripts/hooks/pre-push` runs end-to-end on the current tree: fmt, clippy, test, deny, shellcheck, windows-grep, windows-clippy all pass. - `bash scripts/sync-spec.sh --help` banner unchanged. - `cargo build --release` clean. ## Files Modified **Modified:** - `scripts/sync-spec.sh`: removed the `spec_ref=""` declaration and its stale comment line. - `scripts/hooks/pre-push`: added shellcheck step as step 5, renumbered windows-grep / windows-clippy to 6 / 7 in the source comments. **Created:** - None. **Renamed:** - None. **Deleted:** - None. ## Severity threshold rationale `--severity=warning` catches: - SC2034 (unused variable, what #59 shipped) - SC2086 (missing quoting that would break on spaces in paths) - SC2155 (`local var=$(...)` masking exit codes) - SC2046 (word splitting of unquoted command substitution) - SC2178 (writing scalar to an array variable) - SC2128 (using an array in scalar context) - (and the rest of the warning-tier rules) It deliberately skips info/style noise. Specifically lets through SC2016 on `scripts/prose-check.sh:196` (intentional single-quote `jaq` filter where the dollar-signs are jaq syntax, not shell variables) without needing an inline `# shellcheck disable=` directive. Tightening to `--severity=info` later is a one-line change if you want stricter enforcement. ## Coverage gap across the agentnative-* ecosystem Subagent sweep of the three sibling repos plus the shared reusable workflow: | Repo | Pre-push shellcheck | CI shellcheck | `.sh` files | | --------------------- | ------------------- | ----------------------------------------------------------------- | ---------------------------- | | `agentnative-cli` | **yes (this PR)** | no | ~7 | | `agentnative-spec` | no | no | 3 | | `agentnative-site` | no | no | **32** (largest exposure) | | `agentnative-skill` | no pre-push hook | yes (`ludeeus/action-shellcheck@2.0.0` on `./scripts/`, style severity) | 3 | | `brettdavies/.github` | n/a | no (`rust-ci.yml` has no shellcheck step; just fmt/clippy/test/deny/package/changelog) | n/a | Summary: the only repo with shellcheck today is `agentnative-skill`, and it runs in CI only. The shared `rust-ci.yml` that `agentnative-cli`, `agentnative-spec`, and `agentnative-site` all delegate to does NOT run shellcheck, so adding it there would close the gap across every Rust consumer in one stroke. ## Follow-up work (not in this PR) 1. **CI side for this repo**: add shellcheck to `brettdavies/.github`'s `rust-ci.yml` (closes the gap for cli + spec + site simultaneously), or add a job locally in `agentnative-cli/.github/workflows/ci.yml`. 2. **Pre-push hooks in sibling repos**: port this step to `agentnative-spec/scripts/hooks/pre-push` and `agentnative-site/scripts/hooks/pre-push`. Site has 32 `.sh` files, so the payoff is highest there. 3. **Pre-push hook in agentnative-skill**: add one. The repo has CI shellcheck but no fast-feedback loop locally. ## Breaking Changes - [x] No breaking changes Pre-push step is opt-in (skips silently if `shellcheck` is not installed). ## Deployment Notes - [x] No special deployment steps required Maintainers who want the new step should `brew install shellcheck` (or apt equivalent). Otherwise the existing pipeline behavior is preserved. ## Checklist - [x] Code follows project conventions and style guidelines - [x] Commit messages follow Conventional Commits - [x] Self-review of code completed - [x] Tests added/updated and passing - [x] No new warnings or errors introduced - [x] Changes are backward compatible
…tifacts (#61) ## Summary Tightens the PR-body convention so the Summary section carries only net-diff substance, never verification artifacts. The three docs (`RELEASES.md`, `RELEASES-RATIONALE.md`, `.github/pull_request_template.md`) now state explicitly that triple-diff stats, leak-check output, patch-id cherry-check counts, pre-push gate results, CI status, and prose-scrub findings belong nowhere in the body. Anomalies get fixed before push; the body describes what merged, not how it was assembled. The template comment now lists the exclusions inline so an author writing a body has the rule in front of them at the moment they would otherwise be tempted to paste in narration. ## Type of Change - [x] `docs`: Documentation update ## Related Issues/Stories - Story: n/a - Issue: n/a - Architecture: n/a - Related PRs: None ## Files Modified **Modified:** - `.github/pull_request_template.md`: Summary comment expanded with explicit exclusion list (triple-diff blocks, leak-check output, patch-id counts, pre-push and CI narration). - `RELEASES.md`: Conventions list gains two bullets, "Summary describes net diff only" and "Zero verification artifacts in the body". - `RELEASES-RATIONALE.md`: Net-diff-not-intermediate-state framing made explicit; examples of excluded artifacts enumerated. **Created:** - None. **Renamed:** - None. **Deleted:** - None. ## Breaking Changes - [x] No breaking changes ## Deployment Notes - [x] No special deployment steps required ## Checklist - [x] Code follows project conventions and style guidelines - [x] Commit messages follow Conventional Commits - [x] Self-review of code completed - [x] No new warnings or errors introduced - [x] Changes are backward compatible
…agation (schema 0.6) (#62) ## Summary Ships U2 of the scorecard fairness taxonomy plan (`docs/plans/2026-05-21-001-feat-scorecard-fairness-taxonomy-plan.md` in the agentnative-site repo): the CLI now emits a 7-status taxonomy with per-row results, antecedent propagation for conditional requirements, and a bumped scorecard schema. The vendored spec snaps to `agentnative-spec` dev at commit `b4f4d02` (PR brettdavies/agentnative#34, U1) so the new `applicability.kind: conditional` / `antecedent.check_id` shape parses against five conditional rows in p2 and p8. The status enum gains `opt_out` (deliberate non-adoption) and `n_a` (conditional antecedent unmet); the existing five values are preserved. `Summary` gains matching counters. Every entry in `results[]` now represents one requirement row instead of one probe, carries the row's RFC 2119 `tier` (`must`/`should`/`may`), and names the originating probe in `check_id`. A probe whose `Check::covers()` lists multiple rows (e.g., `p3-version` → `p3-must-version` + `p3-should-version-short`) now produces multiple result entries. Two probes (`p8-bundle-exists` and `p2-json-output`) emit `opt_out` directly when their feature is absent; antecedent propagation rewrites every conditional row whose antecedent collapses to `opt_out` / `n_a` so downstream MUSTs and MAYs stop double-counting against tools that deliberately do not ship the prerequisite feature. The badge score formula keeps its `pass / (pass + warn + fail)` shape but extends the exclusion set to cover the new statuses: `opt_out` is excluded from the denominator and `n_a` is excluded from both sides, per the plan's transitional posture (the final tier-weighted formula is the U3 spec issue, after the disambiguated input has been rescored). Text mode renders the new statuses as `OPT` and `N/A` badges; the summary line shows all seven counters. Three parser strictness fixes the red team surfaced harden the build-time spec gate: whitespace-only `check_id` is rejected, mixed legacy `if:` plus new `kind:` in one applicability block now errors (instead of silently dropping the legacy prose), and any key inside `antecedent` beyond `check_id` errors by name so v2 compound-antecedent syntax (`op: any_of`) cannot ship under v1 semantics. The `Cargo.toml` version and `CHANGELOG.md` are unchanged; both are release-PR artifacts per `RELEASES.md`. ## Changelog ### Added - New `opt_out` and `n_a` scorecard statuses surface in `anc audit --output json` (`status` field on each row and matching counters in `summary`). `opt_out` marks deliberate non-adoption (tool ships no `--output` flag, no `AGENTS.md` bundle); `n_a` marks a conditional requirement whose antecedent is unmet. Pre-0.6 consumers treat both as unknown and feature-detect. - Each entry in `results[]` now carries a `tier` field (`must` / `should` / `may`, or `null` for rows not in the registry) and a `check_id` field naming the probe that produced the row. - `anc emit schema` returns the schema 0.6 contract (`$id: https://anc.dev/scorecard-v0.6.schema.json`) with the new status enum values, summary counters, and per-row fields. ### Changed - `anc audit --output json` emits one result entry per requirement-row instead of one per `check_id`. A probe like `p3-version` (covers `p3-must-version` and `p3-should-version-short`) now produces two distinct entries, each tier-stamped, so downstream scoring layers no longer need a coverage-matrix join to attribute a probe's outcome to a specific RFC 2119 level. - Conditional requirement rows whose antecedent collapses to `opt_out` or `n_a` are propagated to `n_a` in `results[]`; rows whose antecedent is `skip` or `error` inherit the indeterminacy. The propagated evidence string names the antecedent check id so the chain is legible from the JSON alone. - The badge denominator excludes `opt_out` (transitional) and excludes `n_a` from both sides, matching the plan's posture that no formula is provably fair until the input shape is disambiguated. - `anc audit` text mode renders `OPT` and `N/A` status badges alongside the existing five, and the summary line reports all seven counters. - `p8-bundle-exists` emits `opt_out` when no top-level `AGENTS.md` or `SKILL.md` is found (a malformed bundle still emits `warn`); `p2-json-output` emits `opt_out` when no `--output` or `--format` flag is detected at top level or in any subcommand. - The vendored `agentnative-spec` tree updates to `dev` commit `b4f4d02` (PR brettdavies/agentnative#34). Five rows in `p2` and `p8` migrate to the new `applicability.kind: conditional` / `antecedent.check_id` shape; the remaining 18 legacy `applicability.if: <prose>` rows stay as-is until each prerequisite grows a machine-readable check id. ### Fixed - The spec parser now rejects three malformed inputs that previously fell through silently: `antecedent.check_id` containing only whitespace, an applicability block carrying both legacy `if:` and new `kind:` (the legacy branch only fired for single-key maps, so the prose was being dropped on the floor), and any key inside `antecedent` other than `check_id` (compound antecedents are deferred to v2 of the schema per the plan's Sub-decision 2b). ### Documentation - `schema/scorecard.schema.json` regenerates against the 0.6 contract: new enum values, new required counters, `tier` and `check_id` on `CheckResultView`, and a refreshed `examples[0]` block. - `coverage/matrix.json` and `docs/coverage-matrix.md` regenerate against the new conditional applicability shape. Conditional rows surface with `applicability.antecedent.check_id` populated; legacy rows continue to emit `applicability.condition: "<prose>"`. ## Type of Change - [x] `feat`: New feature (non-breaking change which adds functionality) ## Related Issues/Stories - Story: U2 of `docs/plans/2026-05-21-001-feat-scorecard-fairness-taxonomy-plan.md` (agentnative-site) - Issue: n/a - Architecture: `docs/plans/2026-05-21-001-feat-scorecard-fairness-taxonomy-plan.md` (agentnative-site repo) - Related PRs: brettdavies/agentnative#34 (U1, spec — landed on `dev`, vendored here at SHA `b4f4d02`) ## Testing - [x] Unit tests added/updated - [x] Integration tests added/updated - [x] Manual testing completed - [x] All tests passing **Test Summary:** - Unit and integration tests: 786 passing (29 net-new across parser, registry, scorecard, schema drift) - Pre-push gate: fmt, clippy `-Dwarnings`, full test suite, cargo-deny, shellcheck, Windows compat — all green - Manual dogfood: `anc audit . --output json` produces a schema 0.6 scorecard with the self-target at the v0.4.0 baseline (no opt_out / n_a, since the repo ships both `--output` and `AGENTS.md`); `anc audit --command echo --output json` exercises the propagation chain end-to-end (`summary.opt_out: 1` for `p2-must-output-flag` from direct emission, `summary.n_a: 1` for `p2-must-schema-print` from antecedent propagation) - `anc emit coverage-matrix --check` clean (committed artifacts match the registry plus `covers()` declarations) ## Files Modified **Modified:** - `build_support/parser.rs`: New conditional applicability shape (`kind: conditional` + `antecedent.check_id`) parses alongside the legacy `if:` form; three strictness fixes for the malformed-input edge cases. - `src/principles/registry.rs`: `Applicability::Conditional` becomes a struct variant with `condition` and `antecedent` fields; new `Antecedent` type carries `check_id`. Two registry-consistency guards added. - `src/principles/matrix.rs`: Matrix renderer handles both the legacy condition and the new antecedent shape; matrix.json emits the new shape via additive serde fields. - `src/types.rs`: `CheckStatus` gains `OptOut(String)` and `NotApplicable(String)`. - `src/scorecard/mod.rs`: `SCHEMA_VERSION` bumps to 0.6; new `fan_out_per_row` and `propagate_antecedents` helpers run inside `build_scorecard`; `CheckResultView` gains `tier` + `check_id`; `Summary` gains `opt_out` + `n_a` counters; `score_pct`, `build_summary`, `format_text`, `format_text_raw`, `exit_code` updated for the new variants. Twenty-seven new tests covering fan-out, propagation, score formula, summary invariants, serialization roundtrip. - `src/checks/project/bundle_exists.rs`: Emits `OptOut` when no bundle file is found; malformed bundle still emits `Warn`. - `src/checks/behavioral/json_output.rs`: Emits `OptOut` when no `--output` / `--format` flag is detected at top level or in any subcommand. - `src/principles/spec/principles/p1-non-interactive-by-default.md` through `p8-discoverable-skill-bundle.md`: Vendored at `agentnative-spec` dev SHA `b4f4d02`; five rows in p2 and p8 carry the new conditional shape. - `schema/scorecard.schema.json`: Schema 0.6 contract (`$id`, enum values, required counters, `tier` + `check_id` on results, refreshed example). - `coverage/matrix.json` and `docs/coverage-matrix.md`: Regenerated against the new applicability shape. - `tests/integration.rs`: Schema version assertion bumped to `0.6`; the `audit_profile diagnostic-only` test looks up the per-row id `p5-must-dry-run` (with `check_id: "p5-dry-run"`) under per-row emission. - `tests/scorecard_metadata_security.rs`: Schema version assertion bumped to `0.6`. - `tests/scorecard_schema_v05.rs`: Schema version assertion bumped to `0.6`; `assert_v05_shape` walks the new `summary.opt_out` / `summary.n_a` keys and every row's `tier` / `check_id`. Six schema-drift guards assert the committed schema agrees with the live scorecard. - `tests/build_parser.rs`: Eight parser red-team tests covering malformed `antecedent` shapes, whitespace-only `check_id`, mixed legacy plus new shape, smuggled v2 `op:` key, and a defense-in-depth `emit_rust` quote-escape test. **Created:** - None. **Renamed:** - None. **Deleted:** - None. ## Breaking Changes - [x] No breaking changes Schema 0.6 is an additive evolution of 0.5: every pre-0.6 key remains, the new keys are populated alongside the existing ones, and consumers that do not understand `opt_out` / `n_a` should treat them as `skip` (the conservative bucket, matching the contract in the schema's own description). The site renderer, leaderboard ingest, and any third-party agent consumer can ship their schema-0.6 support out-of-band without coordination. The one shape change that warrants a heads-up: each entry in `results[]` is now keyed by requirement row id (e.g., `p3-must-version`) instead of probe id (e.g., `p3-version`). Consumers that pinned on the probe id should switch to the new `check_id` field on each row, which carries the probe provenance forward. ## Deployment Notes - [x] No special deployment steps required The release PR will bump `Cargo.toml` and `CHANGELOG.md`. Downstream consumers (site renderer, Homebrew tap, registry rescore) consume the published artifact after the tag pushes; no out-of-band coordination needed. ## Checklist - [x] Code follows project conventions and style guidelines - [x] Commit messages follow Conventional Commits - [x] Self-review of code completed - [x] Tests added/updated and passing - [x] No new warnings or errors introduced - [x] Changes are backward compatible (consumers feature-detect new keys)
The `--output text` view, its badge, and the process exit code were computed from raw probe results, while `--output json` already ran the schema-0.6 per-row + antecedent-propagation pipeline. So the terminal printed probe ids (`p2-schema-print`) instead of requirement-row ids (`p2-must-schema-print`), could never render `[N/A ]` (only propagation produces `n_a`), and its row count, badge score, and exit code could disagree with the JSON the site and scorer consume. A human auditing `bat` saw `[FAIL] … (p2-schema-print)` for a MUST the tool is actually exempt from. This routes all three text-side surfaces through the same pipeline. The fan-out + propagation pair that `build_scorecard` inlined is extracted into `build_row_results`, and `main::run` derives one per-row set that feeds `format_text`, `compute_badge`, and `exit_code`. Text and JSON now agree on the row set, counts, badge score, and exit code. The JSON path is byte-identical and the schema stays `0.6`. - `anc audit` (text mode) now reports the same requirement rows as `--output json`: requirement-row ids (`p2-must-schema-print`) instead of probe ids, with the requirement tier (`must`/`should`/`may`) shown on each row. - The process exit code now reflects the per-row result set in both output modes. A requirement that collapses to `n_a` because its conditional prerequisite is `opt_out` no longer forces a non-zero exit; only a live `Fail`/`Error` exits `2` and a live `Warn` exits `1`. - Text mode now renders `[N/A ]` (with antecedent evidence) for conditional requirements whose prerequisite was opted out, instead of showing a misleading `[FAIL]` on the probe id. Text row count and badge score now match `--output json`. - [x] `fix`: Bug fix (non-breaking change which fixes an issue) - Story: n/a - Issue: n/a - Architecture: `docs/plans/2026-05-27-002-fix-text-renderer-per-row-parity-plan.md` - Related PRs: #62 (per-row pipeline + schema 0.6, JSON path only) - [x] Unit tests added/updated - [x] Integration tests added/updated - [x] Manual testing completed - [x] All tests passing **Test Summary:** - New unit tests: `build_row_results_fans_out_then_propagates`, `exit_code_drops_to_zero_when_consequent_propagates_to_n_a`, `text_and_json_agree_on_a_propagated_conditional_row` (bat-shaped fixture asserting consequent shows `n_a` not `fail`, row counts match, badge scores match). - New integration test: `test_text_and_json_agree_on_row_count_and_exit_code` audits `ls` in both modes and pins text row count == JSON `results.len()` and exit-code parity, catching any revert that feeds the text renderer raw probe results. - Existing `format_text_*` / `format_text_raw` / R4 audit-profile masking tests pass unchanged. **Modified:** - `src/main.rs`: derive one per-row projection after the principle filter; feed it to `format_text`, `compute_badge`, and `exit_code`. - `src/scorecard/mod.rs`: add `build_row_results`; `build_scorecard` calls it; `format_text` renders the tier suffix; consolidate the `Level`→token mapping behind `Level::as_str`. - `src/principles/registry.rs`: add `Level::as_str` as the single source of truth for the `must`/`should`/`may` token. - `tests/integration.rs`: text/JSON row-count + exit-code parity guard. - `docs/plans/2026-05-27-002-fix-text-renderer-per-row-parity-plan.md`: status `proposed` → `completed`. **Created:** - None. **Renamed:** - None. **Deleted:** - None. - [x] No breaking changes The CLI surface and JSON schema are unchanged. The exit-code semantics shift for one edge: a tool that raw-Fails a check whose requirement row propagates to `n_a` now exits `0`/`1` instead of `2`. That is the corrected behavior (the requirement does not apply), it matches what the JSON `summary` already reported, and `anc` is `0.x` pre-launch. The `--audit-profile` masking path (plan R4) is independent and unchanged. - [x] No special deployment steps required No additional operational monitoring is required because `anc` is a local CLI with no runtime service. The only downstream consumer is `agentnative-site`, which reads the JSON scorecard; the JSON path is byte-identical (schema stays `0.6`), so there is no consumer impact. Spot-check after merge: `anc audit --command bat` (text) shows `[N/A ] … (p2-must-schema-print) (must)` and no `[FAIL] … (p2-schema-print)`, and `anc audit --command bat` / `--output json` agree on exit code. - [x] Code follows project conventions and style guidelines - [x] Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) - [x] Self-review of code completed - [x] Tests added/updated and passing - [x] No new warnings or errors introduced - [x] Changes are backward compatible (or breaking changes documented)
#64) ## Summary Implements U3b of the scorecard fairness taxonomy plan: the CLI now computes the final leaderboard score defined in `agentnative-spec` `principles/scoring.md` (authority: `agentnative-spec@972c9d3`), replacing the transitional formula shipped in U2. The score now reflects shipped-binary behavior only. `score_pct` is restricted to behavioral-layer rows; source- and project-layer checks still emit in the scorecard but no longer move the score or badge eligibility. Over the denominator set `D = {pass, warn, fail, opt_out}`, the score is a credit-weighted ratio (`pass` 1.0, `warn` 0.5, `fail` and `opt_out` 0.0) with `n_a` / `skip` / `error` excluded from `D`. `opt_out` now counts in the denominator so deliberate non-adoption is reflected. Tier weights are published flat (MUST = SHOULD = MAY = 1) but encoded as named constants in the general `Σ w·credit / Σ w` form, so a future non-flat re-tune is a one-line change. The badge eligibility floor drops from 80% to 70%. A consequence of the behavioral-only scope: `anc audit . --source` now scores 0% and ineligible by design, because a source-only run has no behavioral rows to score. anc dogfoods to 100% in `--binary` and full mode (34 of 34 behavioral checks pass; 9 behavioral skips are excluded from the denominator). `Cargo.toml` version, `CHANGELOG.md`, and the tag publish are deferred to the release PR that closes out this unit, per the plan. ## Changelog ### Changed - The leaderboard score now reflects shipped-binary behavior only: source- and project-layer checks no longer affect `score_pct` or badge eligibility. - `score_pct` is now credit-weighted: `warn` earns half credit and `opt_out` counts against the score, replacing the prior pass-only ratio. - Lower the agent-native badge eligibility floor from 80% to 70%. ## Type of Change - [x] `feat`: New feature (non-breaking change which adds functionality) ## Related Issues/Stories - Story: U3b in `agentnative-site/docs/plans/2026-05-21-001-feat-scorecard-fairness-taxonomy-plan.md` - Issue: None. - Architecture: Formula authority is `agentnative-spec@972c9d3` `principles/scoring.md`. - Related PRs: brettdavies/agentnative#39 (spec formula, U3); #62 (7-status taxonomy, U2). ## Testing - [x] Unit tests added/updated - [x] All tests passing **Test Summary:** - Unit + integration tests: 793 passing, 2 ignored, across 7 suites. - Added: warn half-credit, behavioral-only exclusion, and the `scoring.md` worked example (20 pass / 7 warn / 0 fail / 1 opt_out / 1 n_a / 14 skip → 84). Reworked the at-floor (now 70%), opt_out-in-denominator, and full-pipeline propagation cases. - `cargo fmt --check`, `cargo clippy --all-targets --all-features -D warnings`, and `cargo test` all green. ## Files Modified **Modified:** - `src/scorecard/mod.rs`: rewrote `score_pct` (behavioral-only, credit-weighted, tier-weighted); added `tier_weight` and `status_credit` helpers; lowered `BADGE_ELIGIBILITY_FLOOR_PCT` to 70; updated badge docstrings and tests. - `README.md`: rewrote the Scoring section (7 statuses, credit formula, behavioral-only scope, 70% floor, cohort bands), the dogfood table, and the badge field reference. - `CLAUDE.md`: updated the scorecard `badge` reference to the new formula. **Created:** - None. **Renamed:** - None. **Deleted:** - None. ## Breaking Changes - [x] No breaking changes Scorecard schema stays at `0.6`; the change is in how `score_pct` is computed, not in the JSON shape. Consumers reading `badge.score_pct` see different values after rescore but no shape change. ## Deployment Notes - [x] No special deployment steps required The public registry rescore against this formula is U6 in the site repo, gated on a published CLI release, not part of this PR.
…de (#65) Renames the linter's domain noun from "check" to "audit" across the whole codebase so the concept matches the CLI verb (`anc audit`) top to bottom. The `Check` trait becomes `Audit`; `CheckResult` / `CheckStatus` / `CheckGroup` / `CheckLayer` / `CheckResultView` become `Audit*`; ~73 `*Check` structs and ~50 `check_*` helpers take `*Audit` / `audit_*` names; `src/check.rs` moves to `src/audit.rs` and `src/checks/` moves to `src/audits/`. The scorecard and coverage-matrix JSON rename their `check_id` field to `audit_id`; the scorecard schema bumps 0.6 → 0.7, while the coverage matrix keeps `schema_version` 1.0 (unreleased, so the field rename needs no version bump). Help text, docs, planning docs, shell completions, and issue templates follow. The vendored `agentnative-spec` tree is re-synced to the upstream state that adopts the same vocabulary. The principle prose now cites `anc audit --principle N .` and "audit IDs", and the P2/P8 antecedent frontmatter carries `audit_id`, which matches the build-parser. The resync also newly vendors `principles/scoring.md`, the spec-side scoring-formula authority that the scorecard's `badge.score_pct` mirrors (reference only; `build.rs` ignores it because its filter requires a leading `p`). `scripts/sync-spec.sh` now fetches `scoring.md` alongside the numbered principles. Generic English uses of "check" stay "check" because they are not the linter's concept: verify-mode `--check` flags (the CI drift guards, same idiom as `cargo fmt --check`), the consumer-owned `prose-check.sh` / `test-prose-check.mjs` tooling, "drift check" / "leak-check" / "status-check" narration, the issue-template "check for duplicates" / "check the registry source" search instructions, cargo-deny config, GitHub status-check contexts, and Vale's output field. Where the prior rename pass over-applied the substitution to these, this PR restores them. The issue templates' domain-noun renames are kept (Audit ID, `anc audit` results, `auditor-bug` labels). - Rename the `check_id` field to `audit_id` in `anc audit --output json` scorecards and in `coverage/matrix.json`. Scorecard `schema_version` goes 0.6 → 0.7 and its JSON Schema `$id` becomes `scorecard-v0.7`; the coverage matrix keeps `schema_version` 1.0 (unreleased). Consumers pinning `check_id` must read `audit_id`. - CLI help and output now describe the work as "audits" (for example, "Run only behavioral audits") to match the `anc audit` verb. - [ ] `feat`: New feature (non-breaking change which adds functionality) - [ ] `fix`: Bug fix (non-breaking change which fixes an issue) - [x] `refactor`: Code refactoring (no functional changes) - [ ] `perf`: Performance improvement - [ ] `docs`: Documentation update - [ ] `test`: Adding or updating tests - [ ] `chore`: Maintenance tasks (dependencies, config, etc.) - [ ] `ci`: CI/CD configuration changes - [ ] `style`: Code style/formatting changes - [ ] `build`: Build system changes - [x] `BREAKING CHANGE`: Breaking API change (requires major version bump) - Story: n/a - Issue: n/a - Architecture: n/a - Related PRs: `agentnative-site` must read `audit_id` and the new schema versions in lockstep (see Deployment Notes) - [x] Unit tests added/updated - [x] Integration tests added/updated - [x] Manual testing completed - [x] All tests passing **Test Summary:** - Unit tests: 676 passing (1 ignored); schema-version and `audit_id` field expectations updated to match the rename. - Integration tests: 57 passing; the resync renamed one (`test_emit_coverage_matrix_drift_check_passes_on_committed_artifacts`) and added none. - Coverage: n/a (not measured in this repo). - Manual: dogfooded `anc audit .` and `anc audit . --output json` (rows carry `audit_id`, scorecard `schema_version` 0.7); `anc emit coverage-matrix --check` drift guard exits 0. **Modified:** - Rust source under `src/` (trait, `types.rs`, `scorecard/`, `principles/`, `runner/`, `cli.rs`, `main.rs`) and `tests/` - `schema/scorecard.schema.json`, `coverage/matrix.json`, `docs/coverage-matrix.md`, `completions/anc.*` - `README.md`, `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md`, `RELEASES.md`, `RELEASES-RATIONALE.md`, `PRODUCT.md`, `Cargo.toml`, `scripts/SYNCS.md`, `scripts/sync-spec.sh`, `.github/ISSUE_TEMPLATE/*`, and planning docs under `docs/` - Vendored spec re-sync: principle files P1–P8 and `src/principles/spec/README.md` (`anc audit` prose; P2/P8 `audit_id` frontmatter) **Created:** - `src/principles/spec/principles/scoring.md` (vendored scoring-formula authority; reference only) **Renamed:** - `src/check.rs` → `src/audit.rs` - `src/checks/` → `src/audits/` (83 files, via `git mv`) - 5 planning/research docs whose filenames contained "check" → "audit" **Deleted:** - None (all moves are renames). - [ ] No breaking changes - [x] Breaking changes described below: The JSON `check_id` field is renamed to `audit_id` in both the scorecard and the coverage matrix. The scorecard bumps `schema_version` 0.6 → 0.7 and its JSON Schema `$id` to `scorecard-v0.7`; the coverage matrix keeps `schema_version` 1.0 because it has not shipped to a released consumer. Migration: read `audit_id` in place of `check_id` and feature-detect the scorecard's new version. Enum wire values (`pass`, `behavioral`, etc.) and requirement-row IDs are unchanged. - [ ] No special deployment steps required - [x] Deployment steps documented below: `agentnative-spec` is already aligned: this PR re-syncs from the upstream spec that has adopted `audit_id` antecedent frontmatter and `anc audit` prose, so the vendored tree and the build-parser agree. The remaining lockstep consumer is the site: - `agentnative-site`: update `src/build/coverage.mjs`, the copied `src/data/coverage-matrix.json`, `scripts/score_sandbox/frame.py`, and `tests/build.test.ts` to read `audit_id` (the coverage matrix stays schema 1.0; the scorecard moves to 0.7), or it breaks on the next scorecard / matrix ingest. - One vocabulary end to end: the verb users run (`anc audit`), the code, the JSON, and the vendored spec prose all say "audit". - Removes the long-standing split where the public surface said "audit" while the internals said "check". - [x] Code follows project conventions and style guidelines - [x] Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) - [x] Self-review of code completed - [x] Tests added/updated and passing - [x] No new warnings or errors introduced - [x] Changes are backward compatible (or breaking changes documented)
## Summary Vendors agentnative-spec v0.5.0 (upstream commit `d5d4086`) into `src/principles/spec/`. The diff is six files: `VERSION` bump 0.4.0 → 0.5.0, the upstream `CHANGELOG.md`, and prose-only edits on p3/p4/p5/p7 retargeting deferred-work footnotes from "v0.4.0 PR" to "future PR" now that those PRs have landed. No new requirements arrive via this sync. Every substantive item the upstream v0.5.0 release notes advertise already shipped here ahead of the spec release (PRs #55, #62, #65, and the scoring work): - `p3-must-version` and `p3-should-version-short` - The 7-status taxonomy with antecedent propagation (scorecard schema 0.6) - The `check` → `audit` rename - Badge floor lowered 80 → 70, with four cohort bands This vendoring closes the loop so the in-tree registry and the upstream tag point at the same content. The only consumer-visible behavior change is the scorecard's `spec_version` field, which starts emitting `"0.5.0"` instead of `"0.4.0"`. ## Changelog ### Changed - Scorecard `spec_version` now reports `"0.5.0"` (vendored agentnative-spec bumped 0.4.0 → 0.5.0). ## Type of Change - [x] `feat`: New feature (non-breaking change which adds functionality) ## Related Issues/Stories - Upstream tag: https://github.com/brettdavies/agentnative/releases/tag/v0.5.0 - Vendored commit: `d5d4086` - Pre-shipped here: #55, #62, #65 ## Testing - [x] All tests passing **Test Summary:** - `cargo build`: clean - `cargo test`: 793 passed, 2 ignored - `anc emit coverage-matrix --check`: exit 0 (no registry drift) - Pre-push hook (fmt, clippy `-Dwarnings`, test, cargo-deny, Windows check): passed ## Files Modified **Modified:** - `src/principles/spec/VERSION` - `src/principles/spec/CHANGELOG.md` - `src/principles/spec/principles/p3-progressive-help-discovery.md` - `src/principles/spec/principles/p4-fail-fast-actionable-errors.md` - `src/principles/spec/principles/p5-safe-retries-mutation-boundaries.md` - `src/principles/spec/principles/p7-bounded-high-signal-responses.md` ## Breaking Changes - [x] No breaking changes ## Deployment Notes - [x] No special deployment steps required
Adds RELEASES-PREFLIGHT.md, a go/no-go checklist that gates the release/v<version> cut. Covers what CI structurally can't: scorecard JSON-shape diffs against the last tag, real-world smoke against external CLIs, cross-compile and skill-install distribution paths, cross-repo sequencing (agentnative-site, agentnative-spec readiness), and post-tag verification of the homebrew + crates.io + site loop. Slots in before step 1 of RELEASES.md § Releasing dev to main. Each item is an explicit go/no-go; an unchecked or red item holds the release.
PR #65 (check->audit rename) renamed two spike files under docs/plans/ that don't exist on main (guard-main-docs blocks docs/plans/). Git's rename-detection during cherry-pick onto the release branch saw the renames as new file additions, sneaking them through. Removes the two stragglers so the leak check in RELEASES.md step 4 sees a clean tree before the release PR opens.
…ation files Cherry-picks of feature PRs that touched docs/plans/ etc. brought those files onto the release branch. They are blocked from main by guard-main-docs.yml, so the leak check at RELEASES.md step 4 flagged 20 paths. Removes all of them in one pass so the leak check is clean before the version bump. Supersedes the narrower spike-only cleanup that ran before the full leak check was performed; the prior commit is left in place rather than rewriting history.
#68) ## Summary Tightens prose across the 11 tracked markdown docs in the repo: `CLAUDE.md`, `AGENTS.md`, `scripts/SYNCS.md`, `README.md`, `PRODUCT.md`, `RELEASES-PREFLIGHT.md`, `RELEASES.md`, `RELEASES-RATIONALE.md`, `.github/pull_request_template.md`, `styles/brand/README.md`, and `BRAND.md`. Also applies a one-time prose pass to the historical sections of `CHANGELOG.md` (an explicit exception to the no-manual-edits rule, since the equivalent fix on upstream PR bodies has already shipped). Bundles three release-flow hygiene fixes that surfaced during the prose pass: 1. `scripts/generate-changelog.sh` now refuses to prepend a duplicate `[vX.Y.Z]` section when one already exists in `CHANGELOG.md`. Re-running with an already-published tag previously emitted a second copy of the same section and an empty `vX.Y.Z...vX.Y.Z` compare link. 2. `RELEASES.md` gains a "Cherry-pick conflicts on guarded paths" subsection documenting the `git update-index --remove` plus `gio trash` resolution pattern for modify/delete and rename/delete conflicts on `docs/plans/`, `docs/brainstorms/`, and `docs/ideation/` paths during release cherry-picks. Standard `git rm` is denied by repo policy; the plumbing form is the supported alternative. 3. `anc emit coverage-matrix` writes its generated trailer in a form that survives the prose-check pipeline; the matching `--check` failure message in `src/main.rs` uses the same form. `styles/brand/README.md` is generator-emitted, so the fix is sustained by updating the `styles/brand/*.yml` rule sources and the `scripts/generate-pack-readme.mjs` trailer. Future regenerations stay clean. ## Changelog ### Changed - Tightened prose across all 11 tracked markdown docs in the repo plus historical sections of `CHANGELOG.md`. Each occurrence of a recurring punctuation pattern was replaced with the alternative best matching the local context (colon, semicolon, period, comma, or a small rewording). - `anc emit coverage-matrix` writes the trailer as `<!-- Generated by `anc emit coverage-matrix`; do not edit by hand -->`; the `--check` failure message in `src/main.rs` uses the same form. - `styles/brand/README.md` regenerated against tightened `styles/brand/*.yml` rule sources and updated `scripts/generate-pack-readme.mjs` trailer so the drift check stays clean on future regenerations. ### Fixed - `scripts/generate-changelog.sh` now refuses to prepend a duplicate `[X.Y.Z]` section when one already exists in `CHANGELOG.md`. Re-running the script with an already-published tag previously emitted a second copy of the same section and an empty `vX.Y.Z...vX.Y.Z` compare link. ### Documentation - `RELEASES.md` gains a "Cherry-pick conflicts on guarded paths" subsection documenting the `git update-index --remove` plus `gio trash` resolution pattern for modify/delete and rename/delete conflicts on `docs/plans/`, `docs/brainstorms/`, and `docs/ideation/` paths during release cherry-picks. Standard `git rm` is denied by repo policy; the plumbing form is the supported alternative. ## Type of Change - [x] `docs`: Documentation update ## Related Issues/Stories - Story: n/a - Issue: n/a - Architecture: Cross-repo prose cleanup ahead of the v0.5.0 release; mirrored as cherry-pick onto the release branch after this PR merges. - Related PRs: n/a ## Testing - [x] All tests passing **Test Summary:** - `cargo test`: 793 passed, 2 ignored - `anc emit coverage-matrix --check`: exit 0 (no drift) - `bun scripts/generate-pack-readme.mjs --check`: exit 0 (no drift) ## Files Modified **Modified:** - `AGENTS.md`, `BRAND.md`, `CHANGELOG.md`, `CLAUDE.md`, `PRODUCT.md`, `README.md`, `RELEASES-PREFLIGHT.md`, `RELEASES-RATIONALE.md`, `RELEASES.md`, `.github/pull_request_template.md`, `scripts/SYNCS.md`, `styles/brand/README.md` - `styles/brand/FillerAdjectives.yml`, `styles/brand/HedgeWords.yml`, `styles/brand/MarketingRegister.yml`, `scripts/generate-pack-readme.mjs` (sustains the `styles/brand/README.md` fix across regen) - `scripts/generate-changelog.sh` (duplicate-section guard) - `src/main.rs`, `src/principles/matrix.rs`, `docs/coverage-matrix.md` (matrix trailer at the source) **Created:** - None. **Renamed:** - None. **Deleted:** - None. ## Breaking Changes - [x] No breaking changes ## Deployment Notes - [x] No special deployment steps required
…ve (#69) ## Summary Repositions the Vale prose-check stack (`styles/`, `.vale.ini`, `scripts/prose-check.sh`) as dev-only contributor tooling, mirroring `agentnative-spec` PR #45 (ed066b6). This is the evergreen half: workflow guard, doc reference updates, and dev-direct exception note. The actual file deletions on `main` happen in a follow-up performed directly on the `release/v0.5.0` branch so that one release cycle removes the files from `main`; from then on the workflow guard keeps them out. Bundles two small release-doc polish items that surfaced during the same review pass: a guarded-path leak-check entry in `RELEASES-PREFLIGHT.md`, and a version-neutral rename of `CLAUDE.md` § "Scorecard v0.5 Fields" to § "Scorecard JSON fields" so the heading stops aging out as schema versions move. ## Changelog ### Changed - `.github/workflows/guard-main-docs.yml`: pass `extra_paths: 'styles/,.vale.ini,scripts/prose-check.sh'` to the reusable guard workflow. Future PRs to `main` that add or modify those paths fail the check. Mirrors the path values used by `agentnative-spec`. - `BRAND.md`: refreshed verbatim from `agentnative-spec` to pick up the "narrative is authoritative for both the why and the what" reframing and the `(dev-only)` annotation on the Vale-rule-pack column of the Channel-artifacts table. As a vendored mirror, BRAND.md should match the spec word for word. - `PRODUCT.md`: Inheritance and Register sections retune to "authoritative voice contract" framing; explicitly names the rule pack as dev-only tooling that does not ship to `main`. Removes the dead `styles/brand/README.md` / `styles/brand/*.yml` / `styles/config/vocabularies/cli/` links. - `AGENTS.md`: rewrites the "Voice and prose rules" section to drop the `scripts/prose-check.sh` invocation example and the rule-pack vendoring prose; mirrors the spec's AGENTS.md voice-contract paragraph. - `scripts/SYNCS.md`: drops the `sync-prose-tooling.sh` row from the upstream sync table, the matching mermaid arrow, and the Reference section entry. - `RELEASES.md`: prose-scrubbing intro no longer promises a future vendoring; explicitly names the spec checkout as the Vale config source. - `CLAUDE.md`: § "Scorecard v0.5 Fields" renamed to § "Scorecard JSON fields"; the cross-link in `RELEASES-PREFLIGHT.md` updates to match. ### Added - `RELEASES.md` gains a `### Dev-direct exception` subsection under Daily development, mirroring the spec's same insertion point and content. Names the two path categories (engineering docs and prose-check stack) that may be committed directly to `dev` without a feature branch. - `RELEASES-PREFLIGHT.md` gains a "Release mechanics sanity" item that runs the same guarded-path leak check `RELEASES.md` step 4 runs, so operators catch leaks before the release PR opens. Points at the new `RELEASES.md` § Cherry-pick conflicts on guarded paths subsection for resolution. ## Type of Change - [x] `ci`: CI/CD configuration changes ## Related Issues/Stories - Story: n/a - Issue: n/a - Architecture: Mirrors `agentnative-spec` PR #45 (ed066b6) "feat(prose-check): move stack to dev-only". The spec's follow-up release PR (#46, 20b9deb) performed the corresponding file deletions on `main`; this repo's equivalent deletions happen on `release/v0.5.0` after this PR merges. - Related PRs: agentnative-spec#45, agentnative-spec#46 ## Testing - [x] All tests passing **Test Summary:** - `cargo test`: 793 passed, 2 ignored. - `cargo build`: clean. - `bash scripts/prose-check.sh --vale-only` on dev: stack still present, runs as expected. ## Files Modified **Modified:** - `.github/workflows/guard-main-docs.yml` - `AGENTS.md`, `BRAND.md`, `CLAUDE.md`, `PRODUCT.md`, `RELEASES.md`, `RELEASES-PREFLIGHT.md`, `scripts/SYNCS.md` **Created:** - None. **Renamed:** - None. **Deleted:** - None on this branch. The actual prose-check stack deletions (`.vale.ini`, `styles/`, `scripts/prose-check.sh`, plus the orphaned helpers `scripts/sync-prose-tooling.sh`, `scripts/test-prose-check.mjs`, `scripts/generate-pack-readme.mjs`) ship on the release branch. ## Breaking Changes - [x] No breaking changes ## Deployment Notes - [x] No special deployment steps required
Performs the release-branch deletions that pair with the `feat/remove-vale-and-prose-tooling` dev PR (#69). Once this release lands on `main`, the `guard-main-docs` workflow added in #69 keeps these paths from being reintroduced. Removes: - `.vale.ini` (the Vale config root, in extra_paths) - `styles/` (rule packs + vocab; the brand pack came in via the spec-vendored bundle, in extra_paths) - `scripts/prose-check.sh` (consumer-owned orchestrator, in extra_paths) - `scripts/sync-prose-tooling.sh` (orphaned without the rule pack to vendor) - `scripts/test-prose-check.mjs` (orphaned without prose-check.sh) - `scripts/generate-pack-readme.mjs` (orphaned without styles/brand/) Dev still has the stack for contributors who want a local prose-check pipeline; the spec repo remains the canonical source for the rule packs.
… convention (#71) ## Summary Bumps the `coverage/matrix.json` `schema_version` from `"1.0"` to `"0.1"` so the matrix follows the same pre-release `0.x` convention as every other version-bearing surface in the project (the `anc` crate at `0.5.0`, the scorecard JSON schema at `0.7`, the vendored spec at `0.5.0`). The `1.0` originated in v0.1.1 when the registry plus codegen first landed; nothing publicly consumed the matrix at that time, so the version was effectively a stability claim the shape has not earned yet. Safe for the only consumer: `agentnative-site/src/build/coverage.mjs` validates that `schema_version` is present but does NOT pin a specific value (no `SUPPORTED_MATRIX_VERSIONS` allowlist, unlike the scorecard's contract). The vendored copy at `agentnative-site/src/data/coverage-matrix.json` will re-sync on the site's next coverage-matrix import. ## Changelog ### Changed - `coverage/matrix.json` `schema_version` is now `"0.1"` (was `"1.0"`). The shape evolves additively until first public release locks it; consumers should feature-detect new fields rather than pin to an exact value. ### Documentation - `CLAUDE.md` § Coverage Matrix Artifact Lifecycle: updates the documented `schema_version` value and notes the pre-release-shape convention. ## Type of Change - [x] `fix`: Bug fix (non-breaking change which fixes an issue) ## Related Issues/Stories - Story: n/a - Issue: n/a - Architecture: Aligns with the project's `0.x`-while-unreleased version convention used by the CLI crate, scorecard JSON schema, vendored spec, and badge URL. Cherry-picked onto `release/v0.5.0` after this PR merges. - Related PRs: n/a ## Testing - [x] All tests passing **Test Summary:** - `cargo test`: 793 passed, 2 ignored. - `cargo build --release`: clean. - `anc emit coverage-matrix --check`: exit 0 (no drift between regenerated artifact and the new constant). ## Files Modified **Modified:** - `src/principles/matrix.rs` (constant change, 1 line). - `coverage/matrix.json` (regenerated against the new constant, single-field diff). - `tests/integration.rs` (literal expectation update, 1 line). - `CLAUDE.md` (cross-reference update). **Created:** - None. **Renamed:** - None. **Deleted:** - None. ## Breaking Changes - [x] No breaking changes The matrix has no public consumer pinning the prior value; the site validates the field's existence, not its value. ## Deployment Notes - [x] No special deployment steps required The site's vendored copy at `agentnative-site/src/data/coverage-matrix.json` will need a re-sync at its convenience. That is a site-side concern, not gating for this PR or the v0.5.0 release.
…nd patterns (#73) ## Summary Teaches the `p6-should-consistent-naming` behavioral audit to recognize the standard modern CLI shape that combines top-level verbs (`anc audit`, `gh pull`) with noun-grouped verb hierarchies (`anc skill install`, `gh repo create`). The previous heuristic flat-classified every top-level subcommand by name alone and Warned whenever the surface mixed verbs and nouns, which penalized every major CLI that uses this pattern (git, gh, kubectl, docker, npm, cargo, anc itself). The audit now probes one level deeper for each top-level non-verb subcommand and classifies it into one of three buckets: - **TopLevelVerb**: name is a known verb, OR a non-verb with no children (leaf action like `anc emit`), OR a non-verb whose children are all non-verbs themselves (verb-with-noun-objects shape like `anc emit coverage-matrix`). - **HierarchicalNounVerb**: non-verb name whose children are uniformly verbs (`anc skill install` / `skill update`). The noun groups its verbs; the action position stays predictable at the second level. - **Mixed**: non-verb name whose children include both verbs and non-verbs. The action position is unpredictable even within the group. This is the only case that warns. Score impact on `anc` self-audit: **99 → 100**. `uv` and `cargo` continue to warn because their second-level mixes are genuine (`uv` has `tool`, `python`, `pip`, `self` with mixed children; `cargo` has `toolchain`, `override`, `self`). The Warn evidence now names the offending subcommands so the operator can target the fix. ## Changelog ### Changed - `p6-should-consistent-naming` heuristic now recognizes hierarchical noun-verb subcommand patterns. Top-level verbs combined with noun-grouped verbs (the standard `git`, `gh`, `kubectl`, `docker`, `npm`, `cargo`, `anc` shape) Pass; only genuine inconsistency at the second level (a non-verb subcommand whose children include both verbs and non-verbs) Warns. The audit probes one level deeper per non-verb top-level subcommand via the existing cached `BinaryRunner` infrastructure. - `emit` added to the audit's `COMMON_VERBS` list so it is classified directly as a top-level verb action. - Warn evidence now names every offending subcommand by name so the operator can target the fix. ## Type of Change - [x] `feat`: New feature (non-breaking change which adds functionality) ## Related Issues/Stories - Story: n/a - Issue: n/a - Architecture: Surfaced during the v0.5.0 self-audit pass; the prior heuristic incorrectly Warned on `anc`'s own surface (1 verb `audit`, 1 verb-with-noun-objects `emit`, 1 noun-with-verb-children `skill`). The new heuristic matches the goal of "agents can predict where the action lives" rather than insisting on a single-convention surface. - Related PRs: cherry-picked to `release/v0.5.0-audit-rename` after this PR merges. ## Testing - [x] All tests passing **Test Summary:** - `cargo test`: 800 passed, 2 ignored (was 793; +7 new red-team cases in `consistent_naming`). - `cargo build --release`: clean. - `anc emit coverage-matrix --check`: exit 0. - `cargo deny check advisories`: ok. - Score deltas across the six audit targets: | Target | Before | After | Note | |---|---|---|---| | `anc` (self) | 99 / warn | **100 / pass** | The fix. | | `jq` | 77 / skip | 77 / skip | No subcommand surface. | | `gh` | 68 / skip | 68 / skip | Probe gating unchanged. | | `uv` | 73 / warn | 73 / warn | Genuine: `tool` / `python` / `pip` / `self` have mixed children. | | `cargo` | 69 / warn | 69 / warn | Genuine: `toolchain` / `override` / `self` have mixed children. | | `bc` | 74 / skip | 74 / skip | No subcommand surface. | ## Files Modified **Modified:** - `src/audits/behavioral/consistent_naming.rs` (+273 / -41): new `Classification` enum, child-probing closure parameter, three-bucket classification logic, 10-case red-team test matrix covering anc / git / Mixed / leaf-noun / clap-builtin filtering / single-command skip / case-insensitivity / warn-message format. **Created:** - None. **Renamed:** - None. **Deleted:** - None. ## Breaking Changes - [x] No breaking changes The audit ID (`p6-consistent-naming`), the requirement ID it covers (`p6-should-consistent-naming`), the tier (SHOULD), the principle group (P6), and the layer (behavioral) are unchanged. The scorecard JSON shape is unchanged. The behavior change is one audit's Pass/Warn boundary moving to the more accurate side; consumers feature-detect status values as before. ## Deployment Notes - [x] No special deployment steps required
The original v0.5.0 CHANGELOG section was generated before the hierarchical noun-verb consistent-naming fix (PR #73) was cherry-picked onto the release branch. Regenerated to include the new bullet plus a couple of others (#68, #69, #71 cherry-picks) that landed between the first generation and now. Side-effect: the section header date moves 2026-05-31 -> 2026-06-01 since git-cliff uses the regeneration date. The tag will publish today; the new date matches the actual release date.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
v0.5.0ofanc. Vendoredagentnative-specadvances0.4.0→0.5.0. Scorecard JSON schema advances0.5→0.7in two steps (7-status taxonomy at0.6;check_id→audit_idrename at0.7). Coverage matrix JSONschema_versionrebases from"1.0"to"0.1"so it matches the project's pre-release0.xconvention. Two new universal P3 requirements (p3-must-version,p3-should-version-short) plus 22 additional behavioral checks across P1-P8 close the remaining behavioral orphan coverage. CLI subcommand surface renamescheck→auditandgenerate→emit(breaking). Badge eligibility floor lowers from 80% to 70%, and the leaderboard score becomes credit-weighted on shipped-binary behavior only. The Vale prose-check stack (styles/,.vale.ini,scripts/prose-check.sh) moves to dev-only contributor tooling; the workflow guard keeps it out ofmaingoing forward.Changelog
Added
p3-must-version,p3-should-version-short) verify that every CLI ships a--versionflag plus a short alias from the-V/-v/-versionfamily.opt_outandn_ascorecard statuses surface explicit non-adoption and unmet-antecedent rows; eachresults[]entry now carriestierplusaudit_id. Pre-0.6consumers feature-detect.--verbose/-v(envAGENTNATIVE_VERBOSE),--examples,--color, and--rawflags surface diagnostic detail, curated invocation blocks, ANSI styling control, and pipe-friendlyid<TAB>statusrows.anc skill install --allandanc skill update [host|--all]iterate every known host in one invocation.Changed
anc checkrenamed toanc audit;anc generaterenamed toanc emit;anc schemafolded underanc emit schema. The implicit-default-subcommand injection now writesaudit. Update scripts and CI invocations.schema_versionadvances"0.5"→"0.7"(two-step), thecheck_idfield renames toaudit_id, andresults[]switches to one entry per requirement-row rather than per probe. Consumers pinning the prior shape must feature-detect or update.score_pctis now credit-weighted on shipped-binary behavior only:warnearns half credit,opt_outcounts against, source/project audits no longer affect the score. Badge eligibility floor lowers from 80% to 70%.agentnative-specadvances0.4.0→0.5.0; scorecardspec_versionreports"0.5.0".coverage/matrix.jsonschema_versionbumps"1.0"→"0.1"so the matrix follows the project's pre-release0.xconvention used by the CLI crate, scorecard schema, and vendored spec. The lone consumer (agentnative-site/src/build/coverage.mjs) validates the field's existence but does not pin a specific value, so this is safe.styles/,.vale.ini,scripts/prose-check.sh) repositions as dev-only contributor tooling.guard-main-docs.ymlblocks those paths frommaingoing forward.Fixed
--output json/--jsonnow emits a JSON envelope witherror,kind,messageinstead of clap's plain-text rendering, so agents pinned to JSON can parse failures with one shape.[N/A](with antecedent evidence) for conditional requirements whose prerequisite was opted out, instead of a misleading[FAIL]on the probe id. Text row count and badge score match--output json.antecedent.audit_id, mixed legacyif:+ newkind:, unknown keys insideantecedent).Documentation
RELEASES-PREFLIGHT.mdlands as the operational pre-flight checklist gating each release cut.RELEASES.mdgains a### Cherry-pick conflicts on guarded pathssubsection and a### Dev-direct exceptionsubsection covering engineering-docs paths and the prose-check stack.CHANGELOG.mdcarry the same per-occurrence punctuation tightening applied to all 64 PR bodies in the v0.4.0 → v0.5.0 window.Type of Change
BREAKING CHANGE: Breaking API change (requires major version bump)Related Issues/Stories
agentnative-specv0.5.0(vendored at upstream commitd5d4086). Consumer-facing JSON shape moves to schema0.7with theaudit_idrename.dev.Testing
Test Summary:
cargo test: 793 passed, 2 ignored.anc emit coverage-matrix --check: exit 0.cargo deny check advisories: ok.RELEASES-PREFLIGHT.md: green except the cross-repoagentnative-siteschema gap (tracked separately).Files Modified
Modified:
src/audits/,src/scorecard/,src/principles/,src/main.rs,src/cli.rs,src/audit.rs,src/types.rs,src/runner/,src/source.rs,src/skill_install.rs, and supporting modules.schema/scorecard.schema.jsonregenerated to the0.7contract.src/principles/spec/*advances tov0.5.0.docs/coverage-matrix.md,coverage/matrix.jsonreflect 59 requirement rows..github/workflows/guard-main-docs.yml(extra_paths).README.md,AGENTS.md,CLAUDE.md,PRODUCT.md,BRAND.md,RELEASES.md,RELEASES-RATIONALE.md,scripts/SYNCS.md,.github/pull_request_template.md,CHANGELOG.md.scripts/generate-changelog.sh(duplicate-section guard),scripts/sync-spec.sh(--refflag andgh apitransport),scripts/hooks/pre-push(shellcheck step).Cargo.toml,Cargo.lock(0.5.0).Created:
RELEASES-PREFLIGHT.md(operational pre-flight checklist).Renamed:
anc check→anc audit(subcommand surface).anc generate→anc emit(subcommand surface).check_id→audit_id(JSON field).Deleted:
.vale.ini,styles/,scripts/prose-check.sh, plus the orphaned helpersscripts/sync-prose-tooling.sh,scripts/test-prose-check.mjs,scripts/generate-pack-readme.mjs. Replaced by theguard-main-docs.ymlextra_pathsguard that keeps the stack offmaingoing forward.Breaking Changes
schema_version"0.5"→"0.7".check_idrenamed toaudit_id(per-row and incoverage/matrix.json).results[]switches to one entry per requirement-row instead of per probe; each entry carries newtierandaudit_idfields. Status enum expands from 3 to 7 values (pass,warn,fail,opt_out,n_a,skip,error). Consumers pinned to0.5or the priorcheck_idfield must update.anc checkrenamed toanc audit;anc generaterenamed toanc emit;anc schemafolded underanc emit schema. Scripts and CI invocations pinned to the old names must update.Deployment Notes
agentnative-sitemust add'0.7'to itsSUPPORTED_SCHEMA_VERSIONSallowlist before this release is tagged. Without that, the site's regen pipeline rejects everyv0.5.0scorecard upload../scripts/sync-dev-after-release.sh v0.5.0 && git push origin devperRELEASES.md§ After publish to backportCargo.toml,Cargo.lock, andCHANGELOG.mdtodev.