release: v0.4.0 contract additions plus new P8 principle#26
Merged
Conversation
## Summary v0.4.0 extends the spec contract with new requirements across P1, P2, P4, and P6, and adds a new principle (P8) covering agent skill bundles. The release also folds in the quality work the v0.4.0 handoff scoped after the branch caught up to `dev`: a comprehensive prose polish on `principles/`, voice polish on the load-bearing decision doc, the new "No false canonicalization" anti-pattern in the spec-channel `.impeccable.md`, and pre-push hook hardening that surfaced during the work. Substantive content additions (each adds a new requirement ID; together fires the coupled-release norm at scale): - **P1**: new MUST `p1-must-secret-non-leaky-path` for CLIs accepting secret material. - **P2**: new MUST `p2-must-schema-print`, new SHOULD `p2-should-schema-file`, new SHOULD `p2-should-json-aliases`. - **P4**: new SHOULD `p4-should-enumerate-valid-set` for closed-set input rejection. - **P6**: new MUST `p6-must-sigterm` for long-running operations; new MAY `p6-may-standard-names`. - **New P8** "Discoverable Through Agent Skill Bundles": one MUST, one SHOULD, two MAY-tier requirements. - **VERSION**: 0.3.1 → 0.4.0 (MINOR per `principles/AGENTS.md`; new MUSTs added). Ancillary work folded in during the branch-history catch-up and the polish that followed: - `.impeccable.md`: new anti-pattern "No false canonicalization" with corpus audit and applications across P8. - `docs/decisions/p1-behavioral-must.md`: voice polish to RFC-style decision-record register. - Comprehensive prose review across all 9 files in `principles/` and `docs/decisions/p1-behavioral-must.md` for spec-voice consistency. Substance unchanged. - `scripts/prose-check.sh`: vocabulary additions for new vendor names; LanguageTool rule exclusions extended for `A_INSTALL`, `IS_AND_ARE`, `SINGULAR_NOUN_ADV_AGREEMENT` (technical-prose false positives); top-of-file comment block extended with downstream-step guidance for prose-review tooling. - `scripts/hooks/pre-push`: dirty-tree precondition prevents the gate from passing on a working tree that does not match the pushed commits; `--changed-only` regex fixed for `principles/AGENTS.md` parity with full-scan mode. Plan doc: `docs/plans/2026-05-06-001-feat-v0.4.0-additions-plan.md` (on `dev` per the planning-doc convention). ## Changelog ### Added - P1 MUST `p1-must-secret-non-leaky-path` (conditional on CLI accepting secret material): sensitive inputs are readable via stdin or a `--*-file` flag; flag-value and env-var inputs MAY exist for convenience but MUST NOT be the only path. - P2 MUST `p2-must-schema-print` (conditional on structured output): expose the output schema via a `schema` subcommand or `--schema` flag, runtime-discoverable, with a documented format identifier (canonical recommendation: JSON Schema 2020-12). - P2 SHOULD `p2-should-schema-file` (conditional on structured output): also export the schema to a stable file path so CI and static-analysis consumers can pin without invoking the tool. - P2 SHOULD `p2-should-json-aliases`: accept `--json` and `--jsonl` as aliases for `--output json` and `--output jsonl`. - P4 SHOULD `p4-should-enumerate-valid-set` (conditional on closed-set rejection): when rejecting input against an enum or fixed-allowed-values set, the error message includes the valid set. - P6 MUST `p6-must-sigterm` (conditional on long-running operations): flush or roll back partial writes, release locks, exit non-zero within a bounded shutdown window. Next invocation succeeds without manual cleanup. - P6 MAY `p6-may-standard-names` (conditional on subcommands): follow community-standard verbs (`get` / `list` / `create` / `update` / `delete`) and flag spellings (`--force`, `--yes`, `--limit`, `--quiet`, `--verbose`). - New principle **P8 Discoverable Through Agent Skill Bundles** (four requirements: `p8-must-bundle-install`, `p8-should-bundle-exists`, `p8-may-install-all`, `p8-may-bundle-update`). CLIs ship a top-level skill bundle (`AGENTS.md`, `SKILL.md`, or equivalent) and provide an install path that registers the bundle with installed agent runtimes (canonical form: `tool skill install [<host>]`). ### Changed - `VERSION`: 0.3.1 → 0.4.0 (MINOR per `principles/AGENTS.md`'s versioning rules; new MUSTs added). - `.impeccable.md`: new spec-channel anti-pattern "No false canonicalization". When a bullet names an outcome the implementer can satisfy any way, prose uses indefinite articles and avoids language that canonicalizes one shape; when a bullet names a citable single-shape pattern, prose uses definite articles and cites the source. ## Linked check review Companion PR on `brettdavies/agentnative-cli` is forthcoming. v0.4.0 fires the coupled-release norm hard (10 new requirement IDs across P1, P2, P4, P6, plus the entire P8). The companion work is tracked at `agentnative-cli/.context/compound-engineering/todos/020-pending-p0-spec-v0-4-0-companion-pr.md` (local-only by design; not committed). Order of operations per the plan doc: (a) this PR review-ready, (b) cut companion branch on `agentnative-cli`, (c) cross-link both PR bodies, (d) merge spec PR first, companion within 24 hours so registry-drift CI on `agentnative-cli`'s `dev` does not stay red. This PR will be amended with the companion-PR URL once the companion branch is open. ## Human reviewer **Reviewer:** @brettdavies ## AI disclosure Authored end-to-end across multiple sessions by Claude Opus 4.7 (1M context) under @brettdavies's direction. Brett owns the structural decisions (which bullets land at which tier, the canonical-vs-open framing for P8, the doctrine bullet, the branch-history strategy) and reviewed every commit before push; the AI drafted prose and tooling under those constraints, and a 10-subagent re-pass refined the prose review after Brett flagged a first AI pass as too mechanical.
Hoists the PR-body quality rules out of the release-specific procedure into a general section that applies to every PR. Captures the lesson surfaced during the v0.4.0 release prep: PR bodies follow the template verbatim with no invented sections; Summary is NEW user-facing substance, not workflow recap; verification output stays local; internal tooling commits do not appear in the body's Changelog because cliff.toml skips ^chore. Release-PR-specific note (Changelog repetition is harmless because cliff.toml's ^release skip prevents double-counting) sits in the same section since it is a footnote on the general rules.
brettdavies
added a commit
that referenced
this pull request
May 7, 2026
…kport) Backport of release-prep changes that landed on main via the v0.4.0 release PR (#26) and the v0.3.1 release PR (#23) but never merged back to dev. Mechanical sync, no new content. Direct commit per the backport carve-out: each file's content was already reviewed via the release PR that put it on main, so re-reviewing here is theater. Files synced from origin/main: - CHANGELOG.md — release-only updates ([0.3.1] and [0.4.0] entries generated by scripts/generate-changelog.sh on each release branch). - README.md — v0.3.1's prose polish (longer Example output paragraph and surrounding edits) that was applied on the release branch and never round-tripped to dev. - RELEASES.md — v0.3.1's Prose scrubbing section additions plus v0.4.0's new ## PR body section landed on release/v0.4.0. - cliff.toml — em-dash fix in the changelog header preamble landed on release/v0.4.0 alongside CHANGELOG regeneration. After this commit, `git diff origin/dev..origin/main --name-only | grep -v '^docs/'` is empty for non-doc paths (docs/architecture, docs/brainstorms, docs/plans correctly stay dev-only by design — they are blocked from main by guard-main-docs and are out of scope for this backport).
15 tasks
brettdavies
added a commit
to brettdavies/agentnative-cli
that referenced
this pull request
May 7, 2026
#50) ## Summary v0.4.0 spec sync companion. Ships live check implementations for 11 new requirement IDs across P1, P2, P4, P6, and the brand-new P8 (skill bundle discoverability), suppresses `p6-must-sigterm` under `--audit-profile human-tui` to mirror `p6-sigpipe`'s rationale, and bumps the CLI from 0.3.1 to 0.4.0. ## Changelog ### Added - Add P1 secret-handling check (`p1-must-secret-non-leaky-path`): scans target CLIs' `--help` for secret-bearing flag families (`--token`, `--password`, `--api-key`, `--secret`, `--auth`, `--credential`) and verifies each has either a `--*-file` companion or stdin path advertised. Vacuous Pass when no secret-bearing flag is detected. - Add P2 schema trio (`p2-must-schema-print`, `p2-should-schema-file`, `p2-should-json-aliases`): runtime-discoverable output schema via `schema` subcommand or `--schema` flag, file-export of schemas (`schema/*.json`, `*.schema.json` at repo root), and `--json` / `--jsonl` short aliases for `--output`. - Add P4 closed-set rejection check (`p4-should-enumerate-valid-set`, Rust + Python): detects clap `ValueEnum`, `PossibleValuesParser`, `value_parser!`, and Python `argparse.choices=` / `click.Choice()`. - Add P6 lifecycle and naming checks (`p6-must-sigterm`, Rust + Python; `p6-may-standard-names`): SIGTERM-handler detection across `signal_hook`, `tokio::signal::unix`, `signal.signal`, and `loop.add_signal_handler`; community-standard-verb allow-list applied to top-level subcommands. - Add P8 skill-bundle suite (`p8-should-bundle-exists`, `p8-must-bundle-install`, `p8-may-install-all`, `p8-may-bundle-update`): repo-root detection of `AGENTS.md` / `SKILL.md` with YAML frontmatter, plus help-surface probes for `skill install`, `skill install --all`, and `skill update` / `skill upgrade`. Brand-new principle in the registry. ### Changed - Bump CLI from 0.3.1 to 0.4.0 (MINOR; meaningful coverage growth across five principles, including a brand-new principle). ### Documentation - Document prose-scrubbing runbook in `RELEASES.md` for release-flow artifacts (PR bodies, `CHANGELOG.md`, release-PR bodies) using Vale + LanguageTool + unslop. - Add `## PR body` section to `RELEASES.md` codifying what belongs in PR bodies (NEW user-facing substance, six required template sections) and what does not (workflow recap, triple-diff output, pre-push gate results, CI status, AI attribution). ## Type of Change - [x] `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 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 - [ ] `BREAKING CHANGE`: Breaking API change (requires major version bump) ## Related Issues/Stories - Story: agentnative-spec v0.4.0 (brettdavies/agentnative#25, brettdavies/agentnative#26) - Issue: n/a - Architecture: docs/plans/2026-05-07-001-feat-v0.4.0-spec-sync-plan.md - Related PRs: docs/plans/2026-05-07-002-feat-prose-tooling-import-plan.md (sibling, no governance deadline) ## Files Modified **Modified:** - `Cargo.toml`, `Cargo.lock`: version 0.3.1 to 0.4.0 - `RELEASES.md`: prose-scrubbing runbook + new `## PR body` section - `docs/coverage-matrix.md`, `coverage/matrix.json`: regenerated for 57 requirements - `src/principles/spec/**`: vendored from agentnative-spec v0.4.0 - `src/principles/registry.rs`: counter bumps, principle range to `1..=8`, `p6-sigterm` in `HumanTui` suppression - `src/types.rs`, `src/scorecard/mod.rs`: `CheckGroup::P8` variant + label/order - `src/checks/{behavioral,project,source/{rust,python}}/mod.rs`: register the 13 new check files - `tests/build_parser.rs`: integration test pin updated for v0.4.0 / 57 requirements **Created:** - `src/principles/spec/principles/p8-discoverable-skill-bundle.md` (vendored) - `src/checks/behavioral/secret_non_leaky_path.rs` (P1) - `src/checks/source/{rust,python}/enumerate_valid_set.rs` (P4) - `src/checks/behavioral/{schema_print,json_aliases}.rs`, `src/checks/project/schema_file.rs` (P2) - `src/checks/source/{rust,python}/sigterm.rs`, `src/checks/behavioral/standard_names.rs` (P6) - `src/checks/project/bundle_exists.rs`, `src/checks/behavioral/{bundle_install,install_all,bundle_update}.rs` (P8) **Renamed:** - None. **Deleted:** - None. ## Testing - [x] Unit tests added/updated - [x] Integration tests added/updated - [x] Manual testing completed (dogfood `anc check .`) - [x] All tests passing **Test Summary:** 495 unit tests pass; 51 integration tests pass (including the spec-version drift sentry, the `convention_check_result_constructed_only_in_run_body` rule, the `dangling_cover_ids` detector, and the matrix artifact drift gate); clippy `-Dwarnings` clean; `anc generate coverage-matrix --check` exits 0.
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.4.0 grows the contract with new requirements across P1, P2, P4, P6 plus an entirely new principle (P8). 10 new requirement IDs total, firing the coupled-release norm: a companion PR on
brettdavies/agentnative-clifollows this merge to keep the CLI's registry-drift CI green within the documented 24-hour window.Changelog
Added
p1-must-secret-non-leaky-path(conditional on CLI accepting secret material): sensitive inputs are readable via stdin or a--*-fileflag; flag-value and env-var inputs MAY exist for convenience but MUST NOT be the only path.p2-must-schema-print(conditional on structured output): expose the output schema via aschemasubcommand or--schemaflag, runtime-discoverable, with a documented format identifier (canonical recommendation: JSON Schema 2020-12).p2-should-schema-file(conditional on structured output): also export the schema to a stable file path so CI and static-analysis consumers can pin without invoking the tool.p2-should-json-aliases: accept--jsonand--jsonlas aliases for--output jsonand--output jsonl.p4-should-enumerate-valid-set(conditional on closed-set rejection): when rejecting input against an enum or fixed-allowed-values set, the error message includes the valid set.p6-must-sigterm(conditional on long-running operations): flush or roll back partial writes, release locks, exit non-zero within a bounded shutdown window. Next invocation succeeds without manual cleanup.p6-may-standard-names(conditional on subcommands): follow community-standard verbs (get/list/create/update/delete) and flag spellings (--force,--yes,--limit,--quiet,--verbose).p8-must-bundle-install,p8-should-bundle-exists,p8-may-install-all,p8-may-bundle-update). CLIs ship a top-level skill bundle (AGENTS.md,SKILL.md, or equivalent) and provide an install path that registers the bundle with installed agent runtimes (canonical form:tool skill install [<host>]).Changed
VERSION: 0.3.1 → 0.4.0 (MINOR perprinciples/AGENTS.md's versioning rules; new MUSTs added)..impeccable.md: new spec-channel anti-pattern "No false canonicalization". When a bullet names an outcome the implementer can satisfy any way, prose uses indefinite articles and avoids language that canonicalizes one shape; when a bullet names a citable single-shape pattern, prose uses definite articles and cites the source.Linked check review
PR #25 (the dev-side v0.4.0 work) flagged the companion PR on
brettdavies/agentnative-clias forthcoming. The companion PR remains the next gating step after this merge, per the coupled-release norm inprinciples/AGENTS.md. Order of operations: (a) merge this release PR, (b) cut companion branch onagentnative-clireferencing v0.4.0's 10 new requirement IDs, (c) link in the companion PR body. Within 24 hours of merging this PR to keep registry-drift CI onagentnative-cli'sdevgreen.Human reviewer
Reviewer: @brettdavies
AI disclosure
Authored end-to-end across multiple sessions by Claude Opus 4.7 (1M context) under @brettdavies's direction; Brett owns structural decisions and reviewed each commit before push.