feat(v0.1.1): principle registry, coverage matrix, check renames + scorecard v1.1#21
Merged
brettdavies merged 8 commits intodevfrom Apr 20, 2026
Merged
Conversation
Introduces `src/principles/` — flat `&'static [Requirement]` covering every MUST, SHOULD, and MAY across P1–P7 (46 entries), plus a matrix generator that cross-references the registry against each check's new `Check::covers()` declaration. - `registry.rs` defines `Requirement`, `Level`, `Applicability`, `ExceptionCategory` with ID stability guarantees. - `matrix.rs` builds the inverse map (requirement → verifying check) and renders `docs/coverage-matrix.md` + `coverage/matrix.json`. - `Check::covers()` returns `&'static [&'static str]`, empty by default; dangling references are surfaced by the matrix generator. - `anc generate coverage-matrix` with `--out`, `--json-out`, `--check` (drift guard for CI).
Aligns checks and scorecard with the new principle registry.
Check renames (semantic correction — the spec requirements these
verified live in P1, not P6):
- p6-tty-detection → p1-tty-detection-source (P1 SHOULD, TTY detection)
- p6-env-flags → p1-env-flags-source (P1 MUST, env-var flags)
The rename breaks results[].id in the 10 committed scorecards under
brettdavies/agentnative-site — handoff 3 regenerates them.
P1 applicability gate (`src/checks/behavioral/non_interactive.rs`)
now explicitly passes when ANY of three signals holds:
1. help-on-bare-invocation (clap `arg_required_else_help` shape)
2. agentic-flag-present in `--help` (`--no-interactive` and variants)
3. stdin-as-primary-input (clean exit when stdin is /dev/null)
This blocks the dogfood break — without it, `anc` warned itself.
Every spec-verifying check now declares `covers()` so the matrix
generator can build coverage_summary.
Scorecard JSON bumps to schema_version 1.1:
- coverage_summary { must/should/may × total/verified }
- audience (stub, null until v0.1.3)
- audit_profile (stub, null until v0.1.3)
Commits `docs/coverage-matrix.md` + `coverage/matrix.json` — CI drift
guard covered by `anc generate coverage-matrix --check` and a new
integration test.
Handoffs 2 (plus session brief), 3, and 5 target the agentnative-site repo and now live there; handoffs 1 and 4 stay here. All six docs gain a sibling-handoff nav table so any reader can find siblings across repos. Fix pre-existing broken path in handoff 2 (the doctrine-call handoff is in docs/plans/spikes/, not docs/plans/). Relativize paths that became in-repo after the move and prefix cross-repo code paths with ~/dev/agentnative/ for clarity. The receiving commit in agentnative-site follows in a separate PR.
Add four new sections to CLAUDE.md covering the surfaces that landed in handoff 1 (PR #21): - Principle Registry editing rules (ID pattern, append order, counter tests as drift guards, Applicability semantics, reserved ExceptionCategory). - covers() declaration pattern (static-slice return type, opt-in default, dangling-ID drift detector). - Coverage matrix artifact lifecycle (committed, not generated; --check flag; integration test mirror; when to regenerate). - Scorecard v1.1 field discipline (coverage_summary populated every run; audience and audit_profile reserved for v0.1.3; consumers must feature-detect). Closes the unchecked DoD item from handoff 1.
Release-infrastructure plan (2026-04-02-002): flip frontmatter status from `active` to `complete`. v0.1.0 shipped via full pipeline on 2026-04-16; all 6 units satisfied. Handoff 1 plan (2026-04-20 v0.1.1): add `status: in-progress` to frontmatter, tick all 8 DoD checkboxes with evidence (test counts, schema versions, dogfood result, CLAUDE.md commit SHA), and add a Progress section noting scope-complete / PR #21 open / smoke green / final pre-merge run pending.
Sweep Cargo.toml (repository, homepage), README install/clone URLs, and RELEASES.md ruleset/check-runs API paths to the renamed repo. Homepage now points at anc.dev.
Add seven issue templates for structured reporting: - false-positive, scoring-bug, feature-request, grade-a-cli, pressure-test, spec-question, and config.yml chooser.
brettdavies
added a commit
that referenced
this pull request
Apr 20, 2026
The URL-sweep bullet previously carried release-engineering detail about the `release/v0.1.1-*` branch completing cliff.toml and issue-template refs. Simplified the PR #21 body (`gh pr edit 21`) and regenerated so the user-visible changelog stays focused on the repo rename itself.
brettdavies
added a commit
that referenced
this pull request
Apr 20, 2026
## Summary Release PR cutting v0.1.1 onto `main`. Bundles the v0.1.1 feature payload (principle registry, coverage matrix, check renames, scorecard v1.1, issue templates) from [#21](#21) plus the residual URL-rename work needed after the GitHub repo moved `brettdavies/agentnative` → `brettdavies/agentnative-cli`. The tag push after merge triggers crates.io publish (Trusted Publishing), GitHub Release (5 targets + sha256sum), and Homebrew tap dispatch. ## Changelog ### Added - `anc generate coverage-matrix` subcommand (`--out`, `--json-out`, `--check` drift guard). Emits `docs/coverage-matrix.md` + `coverage/matrix.json` from the spec registry + each check's declared `covers()`. - Scorecard JSON v1.1 fields: `schema_version: "1.1"`, `coverage_summary` (`must`/`should`/`may` × `total`/`verified`), `audience` (reserved, null until v0.1.3), `audit_profile` (reserved, null until v0.1.3). - GitHub issue templates for structured reporting: false-positive, scoring-bug, feature-request, grade-a-cli, pressure-test, spec-question (+ chooser `config.yml`). ### Changed - Renamed `p6-tty-detection` → `p1-tty-detection-source` (verifies the P1 SHOULD for TTY detection, not a P6 concern). - Renamed `p6-env-flags` → `p1-env-flags-source` (verifies the P1 MUST that every flag be settable via env var — lives in P1, not P6). - Repo URL references swept to `brettdavies/agentnative-cli` (renamed from `brettdavies/agentnative`). `Cargo.toml` `homepage` now points at `https://anc.dev`. ### Fixed - P1 applicability gate (`src/checks/behavioral/non_interactive.rs`) now passes when any of help-on-bare-invocation, agentic-flag-present, or stdin-as-primary-input is observed. Previously `anc` risked warning itself once `p1-flag-existence` lands in v0.1.2. ## Type of Change - [x] `feat`: New feature (release vehicle carrying v0.1.1) ## Related Issues/Stories - Feature PR: [#21](#21) — `feat(v0.1.1): principle registry, coverage matrix, check renames + scorecard v1.1` - Plan: `docs/plans/2026-04-20-v011-handoff-1-agentnative-impl.md` (dev-only) - Changelog script: `scripts/generate-changelog.sh` (ran on this branch; CHANGELOG.md committed verbatim from the script output — no manual edits) ## Testing - [x] Pre-push hook passed on this branch (fmt, clippy `-Dwarnings`, 321 unit tests + 41 integration tests, `cargo deny`, Windows compat) - [x] CI on the underlying `feat/v011-*` branch (pre-squash-merge to dev): all green - [x] `cargo run -- check .`: 26 pass / 2 warn / 0 fail / 2 skip (dogfood) - [x] `cargo run -- generate coverage-matrix --check`: exit 0 (no drift) ## Files Modified **Modified on this release branch (beyond the PR #21 cherry-pick):** - `cliff.toml`: `repo = "agentnative-cli"` (so changelog links resolve against the renamed repo) - `.github/ISSUE_TEMPLATE/*.yml` (7 files): prose URL references swept to `brettdavies/agentnative-cli` - `Cargo.toml`, `Cargo.lock`: version bump `0.1.0` → `0.1.1` - `completions/anc.{bash,zsh,fish,elvish,powershell}`: regenerated to pick up the `generate coverage-matrix` subcommand - `CHANGELOG.md`: generated by `scripts/generate-changelog.sh` ## Breaking Changes - [x] Breaking changes described below Check ID renames land in this release (from PR #21): | Old ID | New ID | |---------------------|---------------------------| | `p6-tty-detection` | `p1-tty-detection-source` | | `p6-env-flags` | `p1-env-flags-source` | Downstream scorecard-JSON consumers (notably the `agentnative-site` `/score/<tool>` page) see changed `results[].id` values. Handoff 3 regenerates the committed scorecards against v0.1.1. ## Deployment Notes - [x] Deployment steps documented below 1. Squash-merge this PR to `main`. 2. Tag on `main` (annotated, per `tag.gpgsign=true` default): ```bash git checkout main && git pull git tag -a -m "Release v0.1.1" v0.1.1 git push origin main --tags ``` 3. Tag push triggers `.github/workflows/release.yml` → reusable `rust-release.yml`: `check-version` → `audit` → `build` (5 targets) → `publish-crate` (Trusted Publishing OIDC) → `release` (non-draft, `make_latest: false`) → `homebrew` dispatch → `finalize-release` flips `make_latest: true`. 4. **Precondition** (manual, one-time): crates.io Trusted Publishing entry must point at `brettdavies/agentnative-cli` (renamed from `brettdavies/agentnative`). Verify at `https://crates.io/settings/tokens/trusted-publishing` before tagging — OIDC claim from the renamed repo won't match a stale entry and the publish step will fail with an auth error. ## Checklist - [x] Code follows project conventions and style guidelines - [x] Commit messages follow Conventional Commits - [x] Self-review completed - [x] Tests added/updated and passing (on upstream feat branch) - [x] No new warnings or errors introduced - [x] Breaking changes documented (rename map above) - [x] CHANGELOG.md generated via script, no manual edits
4 tasks
brettdavies
added a commit
that referenced
this pull request
Apr 21, 2026
## Summary Small post-release doc sync against what actually shipped in v0.1.1. Not tied to the next release — lands on \`dev\` for the next release branch to cherry-pick whenever it cuts. Two files touched: - **\`README.md\`** — refreshed the sample dogfood output. The block at line 82 showed \`30 checks: 20 pass, 8 warn, 0 fail, 2 skip, 0 error\`, which was accurate pre-v0.1.1. After the P1 applicability gate fix landed, current state is \`30 checks: 26 pass, 2 warn, 0 fail, 2 skip, 0 error\`. Just the sample output; check count and structure unchanged. - **\`AGENTS.md\`** — closed a real drift. The \"Adding a New Check\" section listed the \`Check\` trait methods as \`id()\`, \`group()\`, \`layer()\`, \`applicable()\`, \`run()\` — missing \`covers()\` which landed in v0.1.1. New contributors adding a check without \`covers()\` would silently not appear in the coverage matrix. Also added the \`cargo run -- generate coverage-matrix\` regeneration step. Project Structure list gained \`src/principles/registry.rs\` and \`src/principles/matrix.rs\`. Cross-references CLAUDE.md for the full conventions (registry rules, drift detector, artifact lifecycle). ## Changelog ### Documentation - Document the \`covers()\` trait method and the coverage-matrix regeneration step in the \"Adding a New Check\" guide. - Refresh README sample output to match v0.1.1 dogfood behaviour. ## Type of Change - [x] \`docs\`: Documentation update ## Related - v0.1.1 feature PR: [#21](#21) — introduced \`covers()\`, \`src/principles/registry.rs\`, and \`anc generate coverage-matrix\`. - CLAUDE.md already has the full registry + drift-detector conventions (landed in that PR); this PR just makes AGENTS.md point at them so contributors hit it from the right entry doc. ## Testing - [x] Confirmed README sample output matches \`cargo run -- check .\` on main at commit 5400c43. - [x] AGENTS.md additions are factual (no change to behavior). - [x] CLAUDE.md and RELEASES.md reviewed — already current, no edits needed. ## Files Modified - \`AGENTS.md\` — 9 insertions, 1 deletion. - \`README.md\` — 1 insertion, 1 deletion.
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.1.1 foundation handoff 1 of 3 — lands the honest-verification scaffolding in
agentnative. Introduces thePrincipleRegistry+ coverage-matrix generator, addsCheck::covers(), corrects two miscategorized checks, fixes theP1 applicability gate that was about to warn the linter against itself, and bumps the scorecard JSON schema to v1.1.
Also sweeps up repo URL references after the GitHub rename to
agentnative-cliand adds structured issue templates.Changelog
Added
anc generate coverage-matrixsubcommand (--out,--json-out,--checkdrift guard). Emitsdocs/coverage-matrix.md+coverage/matrix.jsonfrom the spec registry + each check's declaredcovers().schema_version: "1.1",coverage_summary(must/should/may×total/verified),audience(reserved, null until v0.1.3),audit_profile(reserved, null until v0.1.3).pressure-test, spec-question (+ chooser
config.yml).Changed
p6-tty-detection→p1-tty-detection-source(verifies the P1 SHOULD for TTY detection, not a P6 concern).p6-env-flags→p1-env-flags-source(verifies the P1 MUST that every flag be settable via env var — livesin P1, not P6).
brettdavies/agentnative-cli(renamed frombrettdavies/agentnative).Cargo.tomlhomepagenow points athttps://anc.dev.Fixed
src/checks/behavioral/non_interactive.rs) now passes when any of help-on-bare-invocation,agentic-flag-present, or stdin-as-primary-input is observed. Previously
ancrisked warning itself oncep1-flag-existencelands in v0.1.2.Type of Change
feat: New featureRelated Issues/Stories
docs/plans/2026-04-20-v011-handoff-1-agentnative-impl.md~/.gstack/projects/brettdavies-agentnative/ceo-plans/2026-04-20-p1-doctrine-spec-coverage.md~/.gstack/projects/brettdavies-agentnative/brett-dev-eng-review-test-plan-20260420-132817.mdTesting
cargo run -- check .)Test Summary:
cargo fmt --check: cleancargo clippy --all-targets -- -Dwarnings: cleancargo run -- check .: 26 pass / 2 warn / 0 fail / 2 skip (dogfood OK)cargo run -- generate coverage-matrix --check: exit 0 (no drift)Files Modified
Created:
src/principles/mod.rs,src/principles/registry.rs,src/principles/matrix.rsdocs/coverage-matrix.md,coverage/matrix.json.github/ISSUE_TEMPLATE/(7 templates + config chooser)Modified:
src/check.rs—Check::covers()with empty defaultsrc/cli.rs,src/main.rs—generate coverage-matrixwiringsrc/checks/**/*.rs— per-checkcovers()declarations (19 checks)src/scorecard.rs— v1.1 scorecard shape + coverage-summary buildersrc/checks/behavioral/non_interactive.rs— P1 applicability gatetests/integration.rs— generate/drift integration testsCargo.toml,README.md,RELEASES.md— repo URL sweep (cliff.toml and issue-template prose completed onrelease/v0.1.1-*)Check Rename Map (for handoff 3)
The rename breaks
results[].idin every scorecard JSON committed tobrettdavies/agentnative-site. Handoff 3 regenerates. Old → new:p6-tty-detectionp1-tty-detection-sourcep6-env-flagsp1-env-flags-sourceRegistry snapshot (2026-04-20)
46 requirements: 23 MUST / 16 SHOULD / 7 MAY.
registry_size_matches_spectest guards against drift; bumping thecounter is a deliberate act.
Coverage at launch
Uncovered entries are now explicit in
docs/coverage-matrix.md— readerscan see what
ancverifies vs. what the spec claims. Closing more coverage is the job of v0.1.2 (handoff 4).Breaking Changes
Check ID renames (
p6-tty-detection,p6-env-flags) are breaking foranyone consuming scorecard JSON downstream. Site regeneration is tracked in handoff 3 and lands before v0.1.1 tags.
Deployment Notes
v0.1.1 tag gated on handoff 2 (site spec) also landing.
Checklist