release: v0.5.0 — pin skill version to anc CLI version#23
Merged
Conversation
… sweep + SYNCS map (#14) ## Summary Three docs landings batched together since they all share the v0.3.0 release-prep arc: - **Skill bundle refresh** — closes the v0.3.0 gap that left the "fix → re-run → claim badge" loop incomplete in the agent-facing guide. - **RELEASES drift sweep** — backports the triple-diff verification block from `agentnative-cli` so the `dev → release/main` flow catches drift in both directions. - **SYNCS map** — new `docs/SYNCS.md` routing map for how spec content flows in and the bundle flows out. ## Changelog ### Added - `references/update-check.md` — pulled-out operational detail for the consumer-side update-check script (prompt copy, snooze ladder, state-dir layout). - New "The anc loop" section in `SKILL.md` documenting scorecard schema 0.5 fields (`coverage_summary.must.verified`, `badge.eligible`, `badge.score_pct`, `badge.embed_markdown`), the 80% badge eligibility floor, and the four `--audit-profile` categories (`human-tui`, `file-traversal`, `posix-utility`, `diagnostic-only`). - `anc skill install <host>` documented in `getting-started.md` § "Installing anc and this skill bundle" with `--dry-run`, `eval $(...)` capture, and `--output json` envelope. - `docs/SYNCS.md` — cross-repo sync map covering inbound (`agentnative` spec → this repo via `scripts/sync-spec.sh`) and outbound (this repo → consumer hosts; `agentnative-site` daily probe) edges, with manifest-vs-bundle ownership diagrams. ### Changed - Vendored-spec prose reference in `SKILL.md` bumped `v0.2.0 → v0.3.0` to match `spec/VERSION`. - `SKILL.md` description expanded with Rust/clap, scorecard, audit-profile, agent-native badge, and `anc skill install` keywords plus a SKIP clause that routes TUI builders to `--audit-profile human-tui` instead of this skill. - `SKILL.md` "Update check" block compressed from 35 lines (which buried the first-action intent) to a 6-line "First action: update check" stub; details moved to `references/update-check.md`. - `RELEASES.md` § "Releasing dev to main" step 4 — single guarded-paths grep replaced with a triple-diff verification block (A: main→release, B: release→dev, C: dev→main) plus a `git cherry HEAD origin/dev` patch-id check with squash-merge triage guidance. Mirrors the same step that landed on `agentnative-cli` during v0.3.0 prep. ## Type of Change - [x] `docs`: Documentation update ## Related Issues/Stories - Story: n/a - Issue: n/a - Architecture: n/a - Related PRs: agentnative-cli #45 (RELEASES triple-diff source), agentnative-cli #41 (SYNCS.md template), agentnative-cli #40 (badge schema 0.5 docs) ## Testing - [ ] Unit tests added/updated - [ ] Integration tests added/updated - [x] Manual testing completed - [x] All tests passing **Test Summary:** - markdownlint passes on all four touched/created files (auto-fix hook ran on each Write). - Verified `spec/VERSION` reads `0.3.0` so the prose bump aligns with the vendored snapshot. - Verified `--audit-profile` category list matches `cargo run -- check --help` output from `~/dev/agentnative-cli` HEAD. - Verified scorecard schema 0.5 keys (`coverage_summary`, `badge.*`, `audit_profile`, `tool/anc/run/target`) against a live `cargo run -- check --output json .` invocation. ## Files Modified **Modified:** - `SKILL.md` — compressed update-check block, added "The anc loop" section, expanded description with trigger keywords + SKIP clause, bumped spec ref to v0.3.0. - `getting-started.md` — added `anc skill install` examples, badge claim step in the existing-CLI loop, schema-0.5 stop conditions, `--audit-profile` category list. - `RELEASES.md` — step 4 triple-diff verification + `git cherry` patch-id check with squash-merge triage guidance. **Created:** - `references/update-check.md` — operational details pulled out of SKILL.md (prompt copy, snooze ladder, state-dir layout). - `docs/SYNCS.md` — cross-repo sync routing map. **Renamed:** - None. **Deleted:** - None. ## Breaking Changes - [x] No breaking changes - [ ] Breaking changes described below: ## 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
## Summary
Adds a `--ref <git-ref>` flag (and matching `SPEC_REF` env var) to
`scripts/sync-spec.sh` so the skill can vendor `agentnative-spec` from
an explicit branch, tag, or commit SHA rather than only the latest `v*`
tag. Default behavior (no `--ref`) is unchanged: still resolves the
latest `v*` tag. Refactored from `git clone` to `gh api` so all ref
types (latest tag, branch, tag, SHA) flow through the same code path
(`repos/{owner}/{repo}/contents/{path}?ref=<X>` with
`application/vnd.github.raw`). Mirrors the same refactor in
`agentnative-cli` and `agentnative-site`. Only `DEST_DIR` differs (skill
vendors into `spec/`, cli into `src/principles/spec/`).
Motivation: cross-repo coordination of in-flight spec work that has
landed on `dev` but is not yet tagged. The release-branch flow needs a
way to pin spec content to a specific commit without waiting for spec to
cut.
## Changelog
### Added
- `--ref <git-ref>` flag and matching `SPEC_REF` environment variable on
`scripts/sync-spec.sh` for vendoring `agentnative-spec` from an explicit
branch, tag, or commit SHA. Default behavior (no `--ref`) still resolves
the latest `v*` tag.
### Changed
- `scripts/sync-spec.sh` now uses `gh api` (raw content endpoint)
instead of `git clone` for the primary fetch path. All ref types share
one code path; the local-fallback path against `SPEC_ROOT` is preserved
for offline runs.
### Documentation
- `docs/SYNCS.md` spec-row mechanism column updated to describe `--ref`
/ `SPEC_REF`, the cross-repo coordination workflow, and the `gh api`
resolution semantics.
## 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: n/a
- Issue: n/a
- Architecture: n/a
- Related PRs: mirrors the corresponding `feat/sync-spec-ref-flag` PRs
in `brettdavies/agentnative-cli` and `brettdavies/agentnative-site`
## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [x] Manual testing completed
- [x] All tests passing
**Test Summary:**
- Validated against `--ref dev` (resolves to `b4f4d02`, picks up U1
conditional schema in p2 + p8).
- Validated against `--ref v0.4.0` (resolves to `90dd48b`, pre-U1).
- Default invocation (no `--ref`) still resolves the latest `v*` tag and
produces the same vendored tree as before the refactor.
## Files Modified
**Modified:**
- `scripts/sync-spec.sh`: added `--ref` / `SPEC_REF`, switched primary
fetch to `gh api`, kept local fallback, prints resolved short SHA every
run.
- `docs/SYNCS.md`: spec-row mechanism column + notes updated.
**Created:**
- None.
**Renamed:**
- None.
**Deleted:**
- None.
## Key Features
- `--ref` flag and `SPEC_REF` env var (flag wins over env).
- Single code path for all ref types via `gh api` raw content endpoint.
- Resolved short SHA printed every run, so the release-branch checklist
can record the exact pin.
- Local-fallback path against `SPEC_ROOT` still works when `gh api` is
unreachable.
## Benefits
- Unblocks release-branch flows that need to consume spec content from
`dev` (or a specific SHA) before the spec repo cuts a tag.
- Removes the shallow-vs-full clone distinction; one transport for every
ref type.
- Aligned surface across `agentnative-cli`, `agentnative-site`, and
`agentnative-skill` makes the cross-repo sync workflow legible.
## Breaking Changes
- [x] No breaking changes
- [ ] Breaking changes described below:
Default behavior (no `--ref`) is unchanged.
## Deployment Notes
- [x] No special deployment steps required
- [ ] Deployment steps documented below:
## Screenshots/Recordings
n/a. Script + docs change.
## Checklist
- [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)
## Additional Context
This is the third of three coordinated PRs adding `--ref` support across
the agent-native repos. The flag, env var, and behavior are identical
across all three; only `DEST_DIR` differs per repo.
## Summary Adds `scripts/hooks/pre-push`, a local CI mirror that runs the same two checks the GitHub Actions pipeline runs, so a maintainer running `git push` gets the same gate before the push hits GitHub. Modeled on the canonical `agentnative-cli/scripts/hooks/pre-push` pattern: numbered steps, `pass()` / `fail()` helpers, ANSI red/green output, `set -euo pipefail`, exit-code header. Tools that may not be on every dev machine are skipped with a one-line note rather than failing. ## Changelog ### Added - `scripts/hooks/pre-push`: local CI mirror that runs markdownlint-cli2 and shellcheck against the same surfaces CI checks, gating pushes before they reach GitHub. ## 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: brettdavies/agentnative-cli pre-push hook (the canonical pattern this mirrors) ## Testing - [x] Manual testing completed - [x] All tests passing **Test Summary:** Ran `bash scripts/hooks/pre-push` on the current tree end-to-end. Output: ```text Running local CI checks... markdownlint-cli2 v0.22.1 (markdownlint v0.40.0) Finding: **/*.md !node_modules !node_modules/** !**/node_modules/** !vendor/** !target/** !.git/** !*.min.md !spec/CHANGELOG.md !CHANGELOG.md Linting: 28 file(s) Summary: 0 error(s) markdownlint shellcheck All checks passed. ``` Also self-linted the hook: `shellcheck --severity=style scripts/hooks/pre-push` passes clean. ## Files Modified **Modified:** **Created:** - `scripts/hooks/pre-push` (executable) **Renamed:** **Deleted:** ## Key Features Inventory of CI checks ported into the hook, with step numbering matching the file: 1. **markdownlint** mirrors the `markdownlint` job in `ci.yml`. The CI workflow runs `DavidAnson/markdownlint-cli2-action` with `globs: **/*.md` and reads the committed `.markdownlint-cli2.yaml`. The local CLI honors the same config file, so passing the same glob reproduces CI behavior. Skipped with a one-line note when `markdownlint-cli2` is not installed. 2. **shellcheck** mirrors the `shellcheck` job in `ci.yml`, which runs `ludeeus/action-shellcheck` against `./scripts/` with `SHELLCHECK_OPTS=--severity=style`. Locally the hook walks `git ls-files 'scripts/*'`, filters to actual shell scripts (by `.sh` extension or `#!.*\b(bash|sh)\b` shebang) so `bin/` stays out, and includes `scripts/hooks/*` so the hook lints itself. Skipped with a one-line note when `shellcheck` is not installed. No other CI jobs exist to port. `.github/workflows/guard-main-docs.yml` is a `pull_request`-only guard that gates `dev->main` merges via an org-level reusable workflow and has no local-runnable equivalent. ## Benefits - Fail fast: catches markdownlint and shellcheck regressions before they hit GitHub Actions. - Same surface as CI: the hook reads the same `.markdownlint-cli2.yaml` and uses the same severity flag (`--severity=style`) the CI workflow sets, so a green hook is a green CI signal. - Optional, not load-bearing: every check skips silently when its tool is absent. CI is still the authoritative backstop. ## Breaking Changes - [x] No breaking changes ## Deployment Notes - [x] No special deployment steps required Activation is one-time per checkout, matching the `agentnative-cli` repo convention: ```bash git config core.hooksPath scripts/hooks ``` This is a local git-config flag, not a tracked file, so each maintainer opts in once after cloning. Mention this in `CONTRIBUTING.md` as a follow-up if desired (out of scope for this PR). ## Screenshots/Recordings n/a ## 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 ## Additional Context Hook ran clean end-to-end on the current tree. No findings were surfaced and no in-tree files were modified beyond the hook itself, so no scope creep.
## Summary **Channel migration: `.impeccable.md` → `PRODUCT.md`.** The skill bundle carries `PRODUCT.md` at the repo root as the channel-specific design-context file, inheriting from a vendored `BRAND.md` (universal voice and identity, source of truth in `agentnative-spec`). `scripts/sync-prose-tooling.sh` vendors `BRAND.md` from spec's `main` HEAD on a separate cadence from `scripts/sync-spec.sh`. `AGENTS.md` points authors at both files before touching skill-bundle prose. Aligns with `agentnative-spec`, `agentnative-site`, and `agentnative-cli`, which already migrated. **Tighter PR-body conventions.** The PR template's Summary placeholder reserves the section for the net diff (what merging produces vs. the base branch) and lists the verification artifacts to exclude (triple-diff stats, leak-check output, patch-id cherry-check counts, pre-push gate results, CI status, prose-scrub findings). `RELEASES.md` and `RELEASES-RATIONALE.md` codify the same rule in operational and rationale form. **Supporting docs:** - `.github/ISSUE_TEMPLATE/*.md` replaced by YAML forms (`bug-report.yml`, `bundle-proposal.yml`, `00-blank.yml`) plus `config.yml` routing visitors to the spec, cli, and site repos. - `CONTRIBUTING.md` rewritten: sibling-repo list widened to four (adds `agentnative-site`), Contribution Tiers table (Signal / Proposal / Code with intake + effort), AI-disclosure pointer at the spec's policy. - `README.md` repo-layout block adds `BRAND.md`, `PRODUCT.md`, `RELEASES-RATIONALE.md`, and `scripts/sync-prose-tooling.sh`; `anc.dev` principle-range link now covers `/p1` through `/p8` (spec added P8 on discoverability). - `RELEASES.md` "Apply" section for branch-protection rulesets is past-tensed (all three rulesets are installed; commands read as re-runnable for new repos or after a ruleset reset, not as gated on a future public-flip), with a `gh api repos/.../rulesets` verify recipe. - `RELEASES-RATIONALE.md` "Private-repo ruleset gap" section is rewritten as "Why the apply step is re-runnable" so the doc reads forward. ## Changelog ### Added - New skill-bundle channel-context layer: `PRODUCT.md` (channel design context), `BRAND.md` (universal voice, vendored from `agentnative-spec`), and `scripts/sync-prose-tooling.sh` (vendoring vehicle, decoupled from `scripts/sync-spec.sh`). - `RELEASES-RATIONALE.md` companion to `RELEASES.md` documents the rationale behind branching, PR conventions, CHANGELOG generation, spec-vendor pipeline, and branch protection. - GitHub issue forms: `bug-report.yml`, `bundle-proposal.yml`, `00-blank.yml`, and `config.yml`. ### Changed - PR template, `RELEASES.md`, and `RELEASES-RATIONALE.md` codify the net-diff PR-body rule: Summary describes the merged-state diff and excludes verification artifacts. - `RELEASES.md` "Apply" section for branch-protection rulesets past-tensed (all three rulesets installed; apply commands re-runnable). - `CONTRIBUTING.md` widens the sibling-repo list to four, adds a Contribution Tiers table (Signal / Proposal / Code), and points at the spec's AI-disclosure policy. - `README.md` repo-layout block lists `BRAND.md`, `PRODUCT.md`, `RELEASES-RATIONALE.md`, and `scripts/sync-prose-tooling.sh`; principle-range link covers `/p1` through `/p8`. - `AGENTS.md` adds a "Voice and prose rules" pointer to `PRODUCT.md` and `BRAND.md`. ### Removed - Legacy markdown issue templates (`bug_report.md`, `bundle_proposal.md`), replaced by YAML forms. ## 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 improvement - [x] `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: n/a - Issue: n/a - Architecture: aligns with the `.impeccable.md` → `PRODUCT.md` channel migration already shipped in `agentnative-spec`, `agentnative-site`, and `agentnative-cli`. - Related PRs: n/a ## Testing - [ ] Unit tests added/updated - [ ] Integration tests added/updated - [x] Manual testing completed - [x] All tests passing ## Files Modified **Modified:** - `.github/pull_request_template.md`: Summary placeholder adds the SCOPE rule and the verification-artifact EXCLUDE list. - `AGENTS.md`: new "Voice and prose rules" section pointing at `PRODUCT.md` and `BRAND.md`. - `CONTRIBUTING.md`: sibling-repo list widened to include `agentnative-site`; new Contribution Tiers table; AI-disclosure pointer; prose touch-up. - `README.md`: repo-layout block adds the four files this branch creates; principle-range link corrected to `/p1` through `/p8`; prose touch-up. - `RELEASES.md`: PR-body section codifies the net-diff and zero-verification-artifacts rules; "Apply" section past-tensed with a verify-installed-rulesets recipe. **Created:** - `BRAND.md`: vendored from `agentnative-spec/BRAND.md`. Edits land upstream, not here. - `PRODUCT.md`: skill-bundle channel design context, inheriting from `BRAND.md`. - `RELEASES-RATIONALE.md`: rationale companion to `RELEASES.md` (branching, PR conventions, CHANGELOG generation, spec-vendor pipeline, branch protection). - `scripts/sync-prose-tooling.sh`: vendors `BRAND.md` from `agentnative-spec`'s `main` HEAD. - `.github/ISSUE_TEMPLATE/00-blank.yml`: structured blank-issue template. - `.github/ISSUE_TEMPLATE/bug-report.yml`: structured bundle-bug form. - `.github/ISSUE_TEMPLATE/bundle-proposal.yml`: structured bundle-proposal form. - `.github/ISSUE_TEMPLATE/config.yml`: cross-repo routing links. **Renamed:** - None. **Deleted:** - `.github/ISSUE_TEMPLATE/bug_report.md`: superseded by `bug-report.yml`. - `.github/ISSUE_TEMPLATE/bundle_proposal.md`: superseded by `bundle-proposal.yml`. ## Key Features - Three-tier prose inheritance for the skill bundle: universal (`BRAND.md`) → channel (`PRODUCT.md`) → bundle artifacts (`SKILL.md`, `getting-started.md`, `references/`, `templates/`). - PR-body rule that excludes verification artifacts so the body reads as what shipped, not how it was assembled. - Structured GitHub issue forms with required AI-disclosure fields and route-check banners pointing at the right sibling repos. ## Benefits - Cross-repo legibility: spec, site, cli, and skill now share the same `BRAND.md` + `PRODUCT.md` shape. - Cleaner PR history: reviewers see substance, not workflow narration. - Lower friction for contributors: structured forms guide bug reports and proposals; the Contribution Tiers table sets expectations. ## Breaking Changes - [x] No breaking changes - [ ] Breaking changes described below: The `.impeccable.md` → `PRODUCT.md` rename is producer-side. The `/impeccable` skill loader resolves the legacy filename via auto-migration. ## Deployment Notes - [x] No special deployment steps required - [ ] Deployment steps documented below: ## Screenshots/Recordings n/a. Docs-only change. ## Checklist - [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 Adds `scripts/sync-dev-after-release.sh` to backport release-bookkeeping (`VERSION` + `CHANGELOG.md`) from `main` to `dev` after a release tag publishes. Mirrors `~/dev/agentnative-cli/scripts/sync-dev-after-release.sh`; this variant drops the Cargo.toml/Cargo.lock steps since the skill bundle is markdown-only. `RELEASES.md` gains an "After publish: sync `dev` with the release" subsection documenting the invocation; `RELEASES-RATIONALE.md` gains a matching "Why backport `main` → `dev` after publish" section explaining the direct-to-dev exception (one signed commit, no PR) and why `dev` needs the bookkeeping current. ## Changelog ### Added - `scripts/sync-dev-after-release.sh`: release-backport tool that overwrites `VERSION` with the released number and copies `CHANGELOG.md` verbatim from `origin/main` as one signed commit on `dev`. Idempotent on re-run. ### Changed - `RELEASES.md` documents the post-publish backport step under "Releasing dev to main." - `RELEASES-RATIONALE.md` documents the rationale for landing the backport as a direct-to-dev commit (rather than through a PR) and the load-bearing consequences of skipping it. ## 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: n/a - Issue: n/a - Architecture: mirrors the release-backport pattern already shipped in `agentnative-cli` (`scripts/sync-dev-after-release.sh` + corresponding RELEASES.md / RELEASES-RATIONALE.md sections). - Related PRs: n/a ## Testing - [ ] Unit tests added/updated - [ ] Integration tests added/updated - [x] Manual testing completed - [x] All tests passing ## Files Modified **Modified:** - `RELEASES.md`: new "After publish: sync `dev` with the release" subsection at the end of "Releasing dev to main." - `RELEASES-RATIONALE.md`: new "Why backport `main` → `dev` after publish" section between `bin/check-update` semantics and Prose scrubbing scope. **Created:** - `scripts/sync-dev-after-release.sh`: vX.Y.Z arg, verifies tag is on `origin/main`, fast-forward-pulls `dev`, overwrites `VERSION`, copies `CHANGELOG.md` from `origin/main`, commits with a `chore(release): backport vX.Y.Z artifacts to dev` message. Idempotent. **Renamed:** - None. **Deleted:** - None. ## Key Features - Direct-to-dev backport commit (no PR) makes the procedure fast and matches the cli's established convention. - Idempotent re-runs: safe to invoke from automation that doesn't track prior backport state. - Argument validation refuses anything not matching `vMAJOR.MINOR.PATCH` and refuses to run on a dirty working tree or a tag not reachable from `origin/main`. ## Benefits - `dev`'s `VERSION` stops drifting from the released number across release cycles. Feature branches cut from `dev` inherit the right baseline. - `bin/check-update` no longer reports false `UPGRADE_AVAILABLE` on consumer clones whose local `VERSION` came from a `dev` checkout. ## Breaking Changes - [x] No breaking changes - [ ] Breaking changes described below: ## Deployment Notes - [x] No special deployment steps required - [ ] Deployment steps documented below: After this PR merges, run `./scripts/sync-dev-after-release.sh v0.2.0` to backport the v0.2.0 release-bookkeeping that has been outstanding since 2026-04-29. ## Screenshots/Recordings n/a. Script + docs change. ## Checklist - [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)
Migrates the skill's compliance-audit terminology from "check" to "audit" so it matches the renamed `anc` subcommand. `anc check` becomes `anc audit`, the "checker" noun becomes "auditor", and the compliance-sense prose (the four-step loop, "compliance auditing", "audit IDs") follows. The vendored `spec/` is re-synced from agentnative-spec's `refactor/check-to-audit` branch, which applies the same rename upstream and adds the new P8 principle, bumping the bundled spec from 0.3.0 to 0.4.0. The same re-sync also starts vendoring `principles/scoring.md` (leaderboard formula and badge eligibility) and teaches `sync-spec.sh` to pull it. The rename is coupled to the unreleased `anc` 0.4.0, which removes the `check` subcommand with no back-compat alias. The installed `anc` 0.3.1 still requires `anc check`, so this branch must not merge until `anc` 0.4.0 ships. The unrelated update-check feature (`bin/check-update`, `references/update-check.md`) and incidental tokens (`git checkout`, `shellcheck`, checklists, CI status checks) keep their spelling: they are a different sense of "check". - P8 (Discoverable Through Agent Skill Bundles) principle, vendored from agentnative-spec v0.4.0. - `principles/scoring.md` (leaderboard formula, badge eligibility floor, color bands) is now vendored into `spec/`; `scripts/sync-spec.sh` fetches it alongside the principle files. - The canonical audit command is now `anc audit` (was `anc check`), matching the renamed `anc` subcommand. Skill docs, the four-step loop, and all `anc`-compliance prose now read "audit" and "auditor". - Bundled spec bumped 0.3.0 to 0.4.0; the skill now teaches eight principles. - `spec/README.md` now links to the upstream spec landing page (leaderboard, badge convention, acknowledgements) and documents `scoring.md` in the layout table. - [x] `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 - [ ] `BREAKING CHANGE`: Breaking API change (requires major version bump) - Story: n/a - Issue: n/a - Architecture: Coupled-release with agentnative-spec `refactor/check-to-audit` (commit a0771a7) and the unreleased `anc` 0.4.0 subcommand rename. - Related PRs: n/a - [ ] Unit tests added/updated - [ ] Integration tests added/updated - [x] Manual testing completed - [x] All tests passing **Test Summary:** - `git grep 'anc check'` returns zero matches; `git grep 'checker'` returns only the byte-faithful historical entry in `spec/CHANGELOG.md` (vendored, fixed upstream rather than here). - Corruption scan (`auditout`, `shellaudit`, `is a AUDIT`) returns zero matches; the update-check feature and incidental tokens are untouched. - `spec/` re-vendored via `scripts/sync-spec.sh --ref refactor/check-to-audit`; `spec/VERSION` is 0.4.0, P8 is present, and `scoring.md` is vendored. - `shellcheck` clean on `scripts/sync-spec.sh`; markdownlint clean on edited markdown. **Modified:** - Skill content: `SKILL.md`, `getting-started.md`, `README.md`, `AGENTS.md`, `CONTRIBUTING.md`, `PRODUCT.md`, `CHANGELOG.md`, `references/project-structure.md`. - Issue templates: `.github/ISSUE_TEMPLATE/00-blank.yml`, `bug-report.yml`, `bundle-proposal.yml`, `config.yml`. - Planning docs: `docs/brainstorms/2026-05-01-001`, `docs/brainstorms/2026-05-01-002`, `docs/plans/2026-04-27-001`, `docs/plans/2026-05-01-001`. - Sync tooling: `scripts/sync-spec.sh` (now vendors `scoring.md`). - Vendored spec (re-sync): `spec/VERSION`, `spec/CHANGELOG.md`, `spec/README.md`, `spec/principles/p1` through `p7`. **Created:** - `spec/principles/p8-discoverable-skill-bundle.md` (vendored). - `spec/principles/scoring.md` (vendored). **Renamed:** - None. **Deleted:** - None. - [ ] No breaking changes - [x] Breaking changes described below: The canonical audit command changes from `anc check` to `anc audit` with no transitional alias. Agents running `anc` 0.3.1 will break against the new docs; do not merge until `anc` 0.4.0 (with the `audit` subcommand) is released. - [x] No special deployment steps required - [ ] Deployment steps documented below: - [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 - [ ] Changes are backward compatible (or breaking changes documented)
…20) ## Summary `README.md`, `AGENTS.md`, and `CONTRIBUTING.md` each ended with literal `</content>` and `</invoke>` XML tags — leaked tool-output cruft from an earlier AI-assisted edit. These render as raw text in any markdown viewer (GitHub, Obsidian, mdformat) and degrade the first impression of the bundle. Strip them; the rest of each file is unchanged. `grep -rn '</content>\|</invoke>' --include='*.md' .` returns zero matches after the strip. ## Changelog ### Fixed - Strip leaked `</content>` / `</invoke>` XML trailers from `README.md`, `AGENTS.md`, and `CONTRIBUTING.md`. ## Type of Change - [x] `fix`: Bug fix (non-breaking change which fixes an issue) ## Files Modified **Modified:** `README.md`, `AGENTS.md`, `CONTRIBUTING.md` ## 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](https://www.conventionalcommits.org/) - [x] Self-review of code completed - [x] No new warnings or errors introduced - [x] Changes are backward compatible
## Summary Update the skill bundle to match `anc` v0.5.0's surface, re-vendor `spec/` to `agentnative-spec` v0.5.0, and add an `evals/` directory with three dispatchable prompts. The skill content was tracking `anc` v0.3.1. v0.5.0 shipped breaking renames (`check → audit`, `generate → emit`, `schema → emit schema`), a new scorecard JSON shape (schema 0.5 → 0.7, per-row `id` / `audit_id` / `tier` fields, two new statuses `opt_out` and `n_a`), a lowered badge floor (80% → 70%), and several new top-level flags (`--examples`, `--json`, `--raw`, `--color`, `--verbose`). `SKILL.md` and `getting-started.md` document that surface; the vendored spec at `spec/VERSION` is now 0.5.0. `evals/` ships three self-contained prompts that test the bundle via fresh-agent dispatch. Running them during this PR surfaced two doc gaps: the scoring formula's behavioral-layer-only scope, and the semantics of `coverage_summary.must.verified`. Both are fixed here. Each eval's "Anti-patterns to detect" section names the stale strings (schema 0.5, 80% floor, `requirement_id` field name) so re-runs surface drift. ## Changelog ### Added - Add `evals/` with three self-contained prompts covering greenfield Rust, remediate-existing-Rust, and multi-language Python (Click) workflows. - Document `anc skill install --all` and `anc skill update [host|--all]` in the install section. - Document `anc emit schema` for extracting the scorecard JSON Schema embedded in the binary. ### Changed - Re-vendor `spec/` to `agentnative-spec` v0.5.0. - Track `anc` v0.5.0 scorecard surface: schema 0.7, per-row `id` / `audit_id` / `tier` fields, `opt_out` and `n_a` statuses, 70% badge floor. - Surface new top-level flags: `--examples`, `--json`, `--raw`, `--color`, `--verbose`. ### Fixed - Correct the "no MUST violations" check: `coverage_summary.must.verified` counts any verdict (including `fail`), so the right bar is no `results[]` row where `tier == "must" && status == "fail"`. - Clarify that `badge.score_pct` is computed from behavioral-layer rows only. Source- and project-layer audits do not affect the score. ## Type of Change - [x] `feat`: New feature (non-breaking change which adds functionality) - [x] `docs`: Documentation update ## Files Modified **Modified:** `SKILL.md`, `getting-started.md`, `spec/VERSION`, `spec/CHANGELOG.md`, four `spec/principles/p*.md` files **Created:** `evals/README.md`, `evals/01-greenfield-rust-cli.md`, `evals/02-remediate-existing-rust-cli.md`, `evals/03-multilang-python-cli.md` ## 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
## Summary Light prose cleanup across four root markdown files: `SKILL.md`, `AGENTS.md`, `PRODUCT.md`, `SECURITY.md`. Punctuation that was carrying too much structural load gets replaced per-occurrence by the move that fits the construction's actual job (colon for term definitions, comma or parens for asides, semicolon or period for contrasts). No content is added or removed. No factual claims change. Cross-references, file paths, and code blocks are untouched. Five other root files (`CONTRIBUTING.md`, `README.md`, `RELEASES.md`, `RELEASES-RATIONALE.md`, `getting-started.md`) were already clean and are left alone. `BRAND.md` is deliberately skipped because it is vendored from `agentnative-spec` via `scripts/sync-prose-tooling.sh`; any recast here would be clobbered on the next sync. Cleanup there belongs upstream. `CHANGELOG.md` is also skipped (auto-generated by `git-cliff`). ## Changelog ### Documentation - Tighten prose in `SKILL.md`, `AGENTS.md`, `PRODUCT.md`, and `SECURITY.md`. Term-definition bullets switch to colon style; asides move into parens or commas; strong-contrast sentences split where it reads better. The Layout table in `AGENTS.md` is wrapped in scoring-skip comment markers because its column indicator is data, not prose. ## Type of Change - [x] `docs`: Documentation update ## Files Modified **Modified:** `SKILL.md`, `AGENTS.md`, `PRODUCT.md`, `SECURITY.md` ## 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
PR #19's squash commit (refactor: rename anc check to anc audit) modified files under `docs/brainstorms/` and `docs/plans/`, which exist on `dev` but must never reach `main` per `guard-main-docs.yml`. The initial `git update-index --remove` during conflict resolution was a no-op because the files were still in the working tree at that moment, so the cherry-pick committed them anyway. Net effect on the PR's diff against main: zero. The guard workflow uses `pulls.listFiles` (net diff), so the cleanup removes the leaked paths from the file list entirely and the guard passes.
Pin skill bundle version to anc CLI version. Bump VERSION 0.2.0 to 0.5.0 (versions 0.3.0 and 0.4.0 skipped so the skill tracks the canonical anc release number going forward). Re-render CHANGELOG with the cleaned v0.5.0 section sourced from PR bodies edited on GitHub, plus filler [0.3.0] and [0.4.0] sections documenting the version skip.
## Summary Move `scripts/sync-prose-tooling.sh` to dev-only. The script vendors `BRAND.md` from `agentnative-spec` and is a producer-side dev convenience, not part of the shipped bundle. Mirrors the agentnative-site PR #132 pattern. The merged result vs `dev` (before this PR): - The workflow guard's `extra_paths` now includes `scripts/sync-prose-tooling.sh`. Any future PR that adds or modifies the script in a release branch fails the guard. - `RELEASES.md` gains a `### Dev-direct exception` subsection that documents the two categories of dev-direct change: engineering docs and the prose-tooling vendoring vehicle. - `PRODUCT.md`, `AGENTS.md`, and `README.md` are reframed so the in-tree references to the script are accurate (named as a dev-only sync script rather than linked twice as if it shipped to consumers). `BRAND.md` itself still ships to `main`; consumers read it for skill voice. The script that vendors it does not. ## Changelog ### Changed - `.github/workflows/guard-main-docs.yml`: pass `extra_paths: 'scripts/sync-prose-tooling.sh'` to the reusable guard workflow. Future PRs to `main` that add or modify the script fail the check. - `RELEASES.md`: add a `### Dev-direct exception` subsection under `## Daily development` that names engineering docs and the prose-tooling vendoring vehicle as the two categories that commit directly to `dev` without the feature-branch + PR flow. - `PRODUCT.md`: reframe the `BRAND.md` inheritance text to name a "dev-only sync script" rather than linking the in-tree path twice. - `AGENTS.md`: align the Voice-and-prose-rules section with the same framing. - `README.md`: annotate the repo-layout entry for the script as `(dev-only; guarded off main)`. ## Type of Change - [x] `feat`: New feature (non-breaking change which adds functionality) ## Files Modified **Modified:** `.github/workflows/guard-main-docs.yml`, `RELEASES.md`, `PRODUCT.md`, `AGENTS.md`, `README.md` ## Breaking Changes - [x] No breaking changes ## Deployment Notes - [x] No special deployment steps required ## Related PRs - agentnative-site #132 (the prototype pattern) ## 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
#25) ## Summary Hardens `scripts/sync-dev-after-release.sh` with two preconditions that catch release-flow drift the existing checks miss. Adds a `--dry-run` flag plus duplicate-section guard to `scripts/generate-changelog.sh` to enable the regen check. The merged result vs `dev`: - `sync-dev-after-release.sh` verifies the GitHub Release for `$VERSION` is published (not draft, not missing) before backporting. Tag-reachable-from-main is necessary but not sufficient; consumers see the new version via `gh release`, so the release artifact must actually exist. - `sync-dev-after-release.sh` runs `generate-changelog.sh --dry-run --tag $VERSION` after the backport commit and warns when PR bodies have drifted from main's CHANGELOG.md. Drift is non-fatal (the backport is still correct against current `main`) but flagged so a follow-up release branch can regenerate cleanly. - `generate-changelog.sh` accepts `--dry-run`. It stashes CHANGELOG.md, runs the normal flow in place, prints a unified diff to stderr if the regenerated content differs, restores the original on EXIT trap, and exits 1 on drift. - `generate-changelog.sh` skips the prepend when CHANGELOG.md already has a section for the current tag. Mirrors `agentnative-cli` PR #68's duplicate-section guard. Previously, re-running on an already-published tag emitted a second copy of the section and an empty compare link. ## Changelog ### Added - `scripts/generate-changelog.sh`: `--dry-run` flag prints a unified diff of what regeneration would change without modifying `CHANGELOG.md`. Exits 0 when the file is idempotent vs current PR bodies, exits 1 on drift. - `scripts/sync-dev-after-release.sh`: GitHub Release published-state precondition via `gh release view --json isDraft`. Exits 67 when the release is missing or draft. - `scripts/sync-dev-after-release.sh`: post-sync regen-idempotency check via `generate-changelog.sh --dry-run`. Warns (does not fail) when PR bodies have drifted from main's `CHANGELOG.md`. ### Fixed - `scripts/generate-changelog.sh` no longer prepends a duplicate section when `CHANGELOG.md` already has one for the current tag. Mirrors `agentnative-cli` PR #68. ## Type of Change - [x] `feat`: New feature (non-breaking change which adds functionality) ## Files Modified **Modified:** `scripts/generate-changelog.sh`, `scripts/sync-dev-after-release.sh` ## 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
…dies The prose-tooling dev-only move (#24) and the sync-dev-after-release.sh hardening (#25) merged to dev after release/v0.5.0 was opened. Both cherry-pick cleanly. This commit regenerates the v0.5.0 section via `scripts/generate-changelog.sh` so the bullets come from the upstream PR bodies rather than being hand-edited. Procedure: delete `[0.5.0]` + filler `[0.4.0]` / `[0.3.0]` sections, re-run the script (which now finds the two newly cherry-picked PRs in git history), then re-add the filler sections. The `[0.2.0]` and `[0.1.0]` sections are untouched.
brettdavies
force-pushed
the
release/v0.5.0
branch
from
793a8c4 to
a9af2bc
Compare
PR #24 added `scripts/sync-prose-tooling.sh` to the workflow guard's `extra_paths`, making it a dev-only artifact. The file rode onto this release branch via PR #17's cherry-pick (which predates the guard). The guard now correctly fails the PR-to-main because the file is being added. Drop the file on the release branch only. It stays on `dev` as the vendoring vehicle for `BRAND.md`; `BRAND.md` itself still ships to `main` (consumers read it).
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
Release v0.5.0 of the
agent-native-cliskill bundle. The skill version is now pinned to theancCLI version goingforward; versions 0.3.0 and 0.4.0 are skipped to align numbering.
The merged result vs
main:land at
spec/principles/scoring.md).SKILL.mdandgetting-started.mdtrack theancv0.5.0 scorecard surface (schema 0.7, per-rowid/audit_id/tierfields,opt_outandn_astatuses, 70% credit-weighted badge floor, new top-level flags).evals/directory with three dispatchable prompts (greenfield Rust, remediate existing Rust, multi-languagePython via Click).
scripts/sync-dev-after-release.sh(post-release backport with two preconditions addedin PR feat(scripts): harden sync-dev-after-release.sh with two preconditions #25),
scripts/hooks/pre-push(local CI mirror),scripts/sync-spec.sh--refflag (vendor a specificbranch / tag / commit).
scripts/generate-changelog.shgains--dry-runand a duplicate-section guard (PR feat(scripts): harden sync-dev-after-release.sh with two preconditions #25, mirrorsagentnative-cliPR #68).
scripts/sync-prose-tooling.shis moved to dev-only (PR feat(prose-tooling): move sync script to dev-only #24, mirrorsagentnative-sitePR #132); the workflowguard's
extra_pathskeeps the script offmaingoing forward.anc checkrenamed toanc auditacross the bundle;anc emit schemadocumented for the embedded scorecard JSONSchema.
PRODUCT.md,BRAND.md,RELEASES-RATIONALE.md.</content>/</invoke>XML trailers removed from top-level markdown; prose tightened acrossSKILL.md,AGENTS.md,PRODUCT.md,SECURITY.md.Changelog
See
CHANGELOG.md§[0.5.0]for the full entry.Type of Change
chore: Maintenance tasks (dependencies, config, etc.)feat: New feature (non-breaking change which adds functionality)Files Modified
The release surface vs
maincovers the bundle docs (SKILL.md,getting-started.md,README.md,AGENTS.md,CONTRIBUTING.md,RELEASES.md,SECURITY.md), the channel layer (PRODUCT.md,BRAND.md,RELEASES-RATIONALE.md), the vendored spec (spec/VERSION,spec/CHANGELOG.md, 8 principle files plusscoring.md), four newevals/files, fourscripts/files (sync-dev-after-release.sh,sync-prose-tooling.sh,generate-changelog.shupdates,hooks/pre-push),.github/workflows/guard-main-docs.yml,the GitHub issue forms,
VERSION, andCHANGELOG.md.Breaking Changes
The
anc checktoanc auditrename in the bundle's documentation tracks the upstreamancCLI rename. Anyone withtheir own scripts referencing
anc checkshould consult theancv0.4.0 changelog for the rename and update.Deployment Notes
v0.5.0is tagged, consumersdetect the new release on their next
bin/check-updaterun.Checklist