refactor!: rename the linter's "check" domain noun to "audit" repo-wide - #65
Merged
Conversation
The CLI verb has been `audit` (`anc audit`) for releases, but the layer beneath it still called the concept a "check". This unifies the vocabulary so the thing `anc` does, and a unit of evidence, is an "audit" top to bottom. Code: `Check` trait to `Audit`; `CheckResult`/`CheckStatus`/`CheckGroup`/`CheckLayer`/`CheckResultView` to `Audit*`; ~73 `*Check` structs to `*Audit`; ~50 `check_*` helpers to `audit_*`; `SIGNAL_CHECK_IDS` to `SIGNAL_AUDIT_IDS`; `src/check.rs` to `src/audit.rs`; `src/checks/` to `src/audits/` (via git mv to preserve blame). Wire/schema: the `check_id` JSON field becomes `audit_id`. coverage/matrix.json schema_version 1.0 to 2.0; scorecard schema_version 0.6 to 0.7; schema/scorecard.schema.json $id to scorecard-v0.7. Committed artifacts regenerated; the `--check` drift guard passes. Preserved deliberately: verify-mode `--check` flags (CI drift guards, same idiom as `cargo fmt --check`); cargo-deny, GitHub status-check, and Vale tool vocabulary; generated CHANGELOG history; vendored spec prose where "check" is a generic verb. Docs, plans, shell completions, and issue templates swept to match; `checker` becomes `auditor`. BREAKING CHANGE: scorecard and coverage-matrix JSON rename the `check_id` field to `audit_id` (schema_version 0.6 to 0.7 and 1.0 to 2.0). Consumers pinning `check_id` must read `audit_id`. agentnative-site and agentnative-spec require lockstep updates.
…audit rename Re-syncs the vendored agentnative-spec tree and fixes the fallout from the prior repo-wide "check"→"audit" rename, which had over-applied the substitution to generic English uses of "check". Spec re-sync: - Vendors the updated principle prose (P1-P8), which now cites `anc audit --principle N .` and "audit IDs" in place of the old `agentnative check` / "check IDs" wording; P2 and P8 frontmatter bump `last-revised` to 2026-05-29. - Adds `src/principles/spec/principles/scoring.md`, the spec-side scoring-formula authority the scorecard's `badge.score_pct` mirrors. Reference only; `build.rs` ignores it (its filter requires a leading `p`). - Teaches `scripts/sync-spec.sh` to vendor `scoring.md` explicitly and updates `scripts/SYNCS.md` + the spec `README.md` manifest to document it. Rename corrections (restore "check" where it is the correct word, not the domain noun): - `--check` drift mode and its prose: "drift check", "leak-check", patch-id "cherry-check", "status-check" context strings. - Consumer-owned tooling names: `prose-check.sh`, `test-prose-check.mjs`. - Internal identifiers: test `test_emit_coverage_matrix_drift_check_passes_on_committed_artifacts`, `skill_install` destination-check fixtures, registry suppression-table comment. No compiled-behavior change: the test rename is internal, `scoring.md` is unparsed reference, and the principle prose updates are vendored docs. Plan, brainstorm, and ideation docs carry the same terminology corrections.
…tructions The repo-wide check→audit rename over-applied the substitution to five issue-template lines where "check" is the generic English verb (search and inspect), not the linter's domain noun. Restore "check for duplicates" and "check the registry source". The domain-noun renames in the same files (Audit ID, `anc audit` results, auditor-bug labels) stay "audit".
The check→audit rename had bumped the coverage matrix `schema_version` 1.0 → 2.0 to flag the `check_id` → `audit_id` field rename as breaking. The matrix has not shipped to any released consumer, so the field rename needs no version bump. Hold the `SCHEMA_VERSION` constant at 1.0 and regenerate `coverage/matrix.json`; the `audit_id` field rename stays. The scorecard schema is unaffected.
The repo-wide check→audit rename substituted "check" in three docs where it was not the linter's domain noun. - CONTRIBUTING.md: `cargo deny check` is a real cargo-deny subcommand (the pre-push hook runs it); `cargo deny audit` does not exist. Restore both occurrences. - RELEASES-RATIONALE.md: GitHub-domain literals and generic verbs. `required_status_checks[]` is a branch-protection ruleset field; `check-runs` is the GitHub API endpoint and `.check_runs[]` its response field; plus "status checks report green", "CI check status", "mentally check", "automated prose check", and "patch-id cherry check". - README.md: "checks `--help`" and "Checks for `AGENTS.md`" describe examining and existence, not the audit noun. Domain-noun renames in the same files stay "audit": the `anc audit` verb, behavioral and source audits, audit IDs, and the "language auditor" modules.
The repo-wide check→audit rename rewrote tokens that are external identifiers or historical references, not the linter's domain noun. - RELEASES.md: the `cargo deny check` command (cargo-deny has no `audit` subcommand), the `lt_check` shell function and "grammar check", the `check-version` release job, and four GitHub status-check context strings that must match `protect-main.json` byte-for-byte (`ci / Package check`, `guard-docs / check-forbidden-docs`, `guard-provenance / check-provenance`, `guard-release / check-release-branch-name`). Plus the generic verbs "cherry check" and "prose check". - .github/workflows/ci.yml: the comment described the reusable workflow as running `cargo-deny audit`; the action runs `cargo deny check`. - scripts/SYNCS.md: the `check-version` release job (three references) and "Pre-flight checks". - docs/plans/: the `check-version` job, the `check-version-extract.sh` site script, and the historical `feat/python-checks-and-validation` branch from PR #15 (verified against the real PR head ref). - RELEASES.md and RELEASES-RATIONALE.md: the `release/v0.2.0-python-checks` branch-name example, which cites a real shipped release. The release job named `audit` and the "Security audit" status context are correct and stay "audit".
A five-agent parallel audit of the full diff (both directions) plus follow-up sweeps found the rename had over-applied "check"→"audit" to generic verbs, external identifiers, and grammar. Behavior is unchanged; 793 tests pass.
Code:
- Generic verbs restored to "check" in comments and doc-comments: source.rs pattern helpers, color.rs NO_COLOR routing, project.rs binary discovery ("existence check", "[[bin]] entries"), runner condvar/parser comments, several test comments (contract, bidirectional, RFC-3339 shape), and the sys_exit/env_flags/list_style comments.
- `audit_destination` reverted to `check_destination` (a skill-install precondition guard, not an `Audit`-trait audit; dev named it check_destination) along with its doc comments and test message.
- `bin/check-update` doc reference (the real script in agentnative-skill, not `bin/audit-update`).
- "a audit" / "A audit" corrected to "an audit" (article slips from the mechanical rename).
- Restored the perfect-rust test fixture, an arbitrary fake CLI, to its consistent dev form.
Top-level docs:
- CLAUDE.md: "Windows compatibility check", "the pre-push hook checks this", "Check CI status", "existence check".
- RELEASES.md: "required status checks" (GitHub branch-protection term).
Planning docs (historical references the rename falsified):
- PR #17 branch `refactor/check-status-convention`, the design-doc heading "Behavioral Check Error Handling", the `behavioral-checks.md` handoff, `gh pr checks` (not `gh pr audits`), "CI checks passed", and "status checks page".
- Restored `check_destination` and the conflict-check prose in the skill-subcommand plan, and the old-verb did-you-mean examples in the remove-implicit-default-subcommand plan, keeping the genuine domain renames (the `Audit` subcommand variant, behavioral/source audits, the renamed test).
- Re-fixed `audit-version-extract.sh`: the agentnative-site scoring script is correctly named "audit-", distinct from the CLI's `check-version` release job.
The CLI's domain noun stays "audit" throughout: the `anc audit` verb, the `Audit` trait, audit IDs, the `audit_id` field, and behavioral/source/project audits.
4 tasks
brettdavies
added a commit
that referenced
this pull request
May 31, 2026
## 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
brettdavies
added a commit
that referenced
this pull request
Jun 1, 2026
## Summary `v0.5.0` of `anc`. Vendored `agentnative-spec` advances `0.4.0` → `0.5.0`. Scorecard JSON schema advances `0.5` → `0.7` in two steps (7-status taxonomy at `0.6`; `check_id` → `audit_id` rename at `0.7`). Coverage matrix JSON `schema_version` rebases from `"1.0"` to `"0.1"` so it matches the project's pre-release `0.x` convention. 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 renames `check` → `audit` and `generate` → `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 of `main` going forward. ## Changelog ### Added - 22 new behavioral checks across P1-P8 close the remaining behavioral orphan coverage (verbose, color, raw, examples, defaults-in-help, rich-tui, about/long-about, stdin-input, consistent-naming, timeout-behavioral, structured exit codes, JSON error envelopes, actionable errors, force/yes, read/write distinction, TTY-aware verbosity, and more). - Two universal P3 requirements (`p3-must-version`, `p3-should-version-short`) verify that every CLI ships a `--version` flag plus a short alias from the `-V` / `-v` / `-version` family. - New `opt_out` and `n_a` scorecard statuses surface explicit non-adoption and unmet-antecedent rows; each `results[]` entry now carries `tier` plus `audit_id`. Pre-`0.6` consumers feature-detect. - Top-level `--verbose` / `-v` (env `AGENTNATIVE_VERBOSE`), `--examples`, `--color`, and `--raw` flags surface diagnostic detail, curated invocation blocks, ANSI styling control, and pipe-friendly `id<TAB>status` rows. - `anc skill install --all` and `anc skill update [host|--all]` iterate every known host in one invocation. ### Changed - **BREAKING**: `anc check` renamed to `anc audit`; `anc generate` renamed to `anc emit`; `anc schema` folded under `anc emit schema`. The implicit-default-subcommand injection now writes `audit`. Update scripts and CI invocations. - **BREAKING**: scorecard `schema_version` advances `"0.5"` → `"0.7"` (two-step), the `check_id` field renames to `audit_id`, and `results[]` switches to one entry per requirement-row rather than per probe. Consumers pinning the prior shape must feature-detect or update. - Leaderboard `score_pct` is now credit-weighted on shipped-binary behavior only: `warn` earns half credit, `opt_out` counts against, source/project audits no longer affect the score. Badge eligibility floor lowers from 80% to 70%. - Vendored `agentnative-spec` advances `0.4.0` → `0.5.0`; scorecard `spec_version` reports `"0.5.0"`. - `coverage/matrix.json` `schema_version` bumps `"1.0"` → `"0.1"` so the matrix follows the project's pre-release `0.x` convention 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. - Vale prose-check stack (`styles/`, `.vale.ini`, `scripts/prose-check.sh`) repositions as dev-only contributor tooling. `guard-main-docs.yml` blocks those paths from `main` going forward. ### Fixed - Error output under `--output json` / `--json` now emits a JSON envelope with `error`, `kind`, `message` instead of clap's plain-text rendering, so agents pinned to JSON can parse failures with one shape. - Text mode now renders `[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`. - The spec parser rejects three malformed conditional-applicability inputs that previously fell through silently (whitespace-only `antecedent.audit_id`, mixed legacy `if:` + new `kind:`, unknown keys inside `antecedent`). ### Documentation - `RELEASES-PREFLIGHT.md` lands as the operational pre-flight checklist gating each release cut. `RELEASES.md` gains a `### Cherry-pick conflicts on guarded paths` subsection and a `### Dev-direct exception` subsection covering engineering-docs paths and the prose-check stack. - Repo-wide prose pass: every tracked markdown doc plus the historical sections of `CHANGELOG.md` carry the same per-occurrence punctuation tightening applied to all 64 PR bodies in the v0.4.0 → v0.5.0 window. ## Type of Change - [x] `BREAKING CHANGE`: Breaking API change (requires major version bump) ## Related Issues/Stories - Story: n/a - Issue: n/a - Architecture: `agentnative-spec` `v0.5.0` (vendored at upstream commit `d5d4086`). Consumer-facing JSON shape moves to schema `0.7` with the `audit_id` rename. - Related PRs: cherry-picks of #55, #56, #57, #58, #59, #60, #61, #62, #63, #64, #65, #66, #68, #69 from `dev`. ## Testing - [x] All tests passing **Test Summary:** - `cargo test`: 793 passed, 2 ignored. - `anc emit coverage-matrix --check`: exit 0. - `cargo deny check advisories`: ok. - Release-mechanics preflight per `RELEASES-PREFLIGHT.md`: green except the cross-repo `agentnative-site` schema gap (tracked separately). ## Files Modified **Modified:** - Source: `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: `schema/scorecard.schema.json` regenerated to the `0.7` contract. - Vendored spec: `src/principles/spec/*` advances to `v0.5.0`. - Coverage artifacts: `docs/coverage-matrix.md`, `coverage/matrix.json` reflect 59 requirement rows. - Workflows: `.github/workflows/guard-main-docs.yml` (extra_paths). - Tracked docs: `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: `scripts/generate-changelog.sh` (duplicate-section guard), `scripts/sync-spec.sh` (`--ref` flag and `gh api` transport), `scripts/hooks/pre-push` (shellcheck step). - Build identity: `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). - Scorecard `check_id` → `audit_id` (JSON field). **Deleted:** - `.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`. Replaced by the `guard-main-docs.yml` `extra_paths` guard that keeps the stack off `main` going forward. ## Breaking Changes - [x] Breaking changes described below: 1. **Scorecard JSON shape**: `schema_version` `"0.5"` → `"0.7"`. `check_id` renamed to `audit_id` (per-row and in `coverage/matrix.json`). `results[]` switches to one entry per requirement-row instead of per probe; each entry carries new `tier` and `audit_id` fields. Status enum expands from 3 to 7 values (`pass`, `warn`, `fail`, `opt_out`, `n_a`, `skip`, `error`). Consumers pinned to `0.5` or the prior `check_id` field must update. 2. **Subcommand surface**: `anc check` renamed to `anc audit`; `anc generate` renamed to `anc emit`; `anc schema` folded under `anc emit schema`. Scripts and CI invocations pinned to the old names must update. ## Deployment Notes - `agentnative-site` must add `'0.7'` to its `SUPPORTED_SCHEMA_VERSIONS` allowlist before this release is tagged. Without that, the site's regen pipeline rejects every `v0.5.0` scorecard upload. - After tag publish: run `./scripts/sync-dev-after-release.sh v0.5.0 && git push origin dev` per `RELEASES.md` § After publish to backport `Cargo.toml`, `Cargo.lock`, and `CHANGELOG.md` to `dev`.
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
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. TheChecktrait becomesAudit;CheckResult/CheckStatus/CheckGroup/CheckLayer/CheckResultViewbecomeAudit*; ~73*Checkstructs and ~50check_*helpers take*Audit/audit_*names;src/check.rsmoves tosrc/audit.rsandsrc/checks/moves tosrc/audits/. The scorecard and coverage-matrix JSON rename theircheck_idfield toaudit_id; the scorecard schema bumps 0.6 → 0.7, while the coverage matrix keepsschema_version1.0 (unreleased, so the field rename needs no version bump). Help text, docs, planning docs, shell completions, and issue templates follow.The vendored
agentnative-spectree is re-synced to the upstream state that adopts the same vocabulary. The principle prose now citesanc audit --principle N .and "audit IDs", and the P2/P8 antecedent frontmatter carriesaudit_id, which matches the build-parser. The resync also newly vendorsprinciples/scoring.md, the spec-side scoring-formula authority that the scorecard'sbadge.score_pctmirrors (reference only;build.rsignores it because its filter requires a leadingp).scripts/sync-spec.shnow fetchesscoring.mdalongside the numbered principles.Generic English uses of "check" stay "check" because they are not the linter's concept: verify-mode
--checkflags (the CI drift guards, same idiom ascargo fmt --check), the consumer-ownedprose-check.sh/test-prose-check.mjstooling, "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 auditresults,auditor-buglabels).Changelog
Changed
check_idfield toaudit_idinanc audit --output jsonscorecards and incoverage/matrix.json. Scorecardschema_versiongoes 0.6 → 0.7 and its JSON Schema$idbecomesscorecard-v0.7; the coverage matrix keepsschema_version1.0 (unreleased). Consumers pinningcheck_idmust readaudit_id.anc auditverb.Type of Change
feat: New feature (non-breaking change which adds functionality)fix: Bug fix (non-breaking change which fixes an issue)refactor: Code refactoring (no functional changes)perf: Performance improvementdocs: Documentation updatetest: Adding or updating testschore: Maintenance tasks (dependencies, config, etc.)ci: CI/CD configuration changesstyle: Code style/formatting changesbuild: Build system changesBREAKING CHANGE: Breaking API change (requires major version bump)Related Issues/Stories
agentnative-sitemust readaudit_idand the new schema versions in lockstep (see Deployment Notes)Testing
Test Summary:
audit_idfield expectations updated to match the rename.test_emit_coverage_matrix_drift_check_passes_on_committed_artifacts) and added none.anc audit .andanc audit . --output json(rows carryaudit_id, scorecardschema_version0.7);anc emit coverage-matrix --checkdrift guard exits 0.Files Modified
Modified:
src/(trait,types.rs,scorecard/,principles/,runner/,cli.rs,main.rs) andtests/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 underdocs/src/principles/spec/README.md(anc auditprose; P2/P8audit_idfrontmatter)Created:
src/principles/spec/principles/scoring.md(vendored scoring-formula authority; reference only)Renamed:
src/check.rs→src/audit.rssrc/checks/→src/audits/(83 files, viagit mv)Deleted:
Breaking Changes
The JSON
check_idfield is renamed toaudit_idin both the scorecard and the coverage matrix. The scorecard bumpsschema_version0.6 → 0.7 and its JSON Schema$idtoscorecard-v0.7; the coverage matrix keepsschema_version1.0 because it has not shipped to a released consumer. Migration: readaudit_idin place ofcheck_idand feature-detect the scorecard's new version. Enum wire values (pass,behavioral, etc.) and requirement-row IDs are unchanged.Deployment Notes
agentnative-specis already aligned: this PR re-syncs from the upstream spec that has adoptedaudit_idantecedent frontmatter andanc auditprose, so the vendored tree and the build-parser agree. The remaining lockstep consumer is the site:agentnative-site: updatesrc/build/coverage.mjs, the copiedsrc/data/coverage-matrix.json,scripts/score_sandbox/frame.py, andtests/build.test.tsto readaudit_id(the coverage matrix stays schema 1.0; the scorecard moves to 0.7), or it breaks on the next scorecard / matrix ingest.Benefits
anc audit), the code, the JSON, and the vendored spec prose all say "audit".Checklist