docs(readme): refresh for v0.5 schema + agent-native badge; trim issue templates - #40
Merged
Merged
Conversation
…e templates - Add agent-native badge (https://anc.dev/score/anc) at the top of README plus crates.io / license shields. Closes local TODO 019 — `anc` scores 97% against its own spec and now displays it. - Update Example Output to current 33-check dogfood (was stale at 30) and show the post-summary badge embed hint emitted by `anc check` text mode at >=80%. - Update CLI Reference: add `--audit-profile <CATEGORY>` row and prose explainer pointing agents at `coverage/matrix.json#audit_profiles[]` rather than scraping `--help`. - Update JSON Output to schema 0.5: bump `schema_version` everywhere, add `confidence` to result shape, add the `badge` block, and document `target.path` as basename-only (PII-safe — the recent fix in #39). - Tighten the publishing-scorecard advisory: `target.path` is safe to commit; only `run.invocation` may carry per-machine paths. - Trim `.github/ISSUE_TEMPLATE/` to cli-scope per CONTRIBUTING.md routing — `pressure-test.yml`, `grade-a-cli.yml`, and `spec-question.yml` belong on the spec repo only and were duplicated here from before the rename. The chooser `config.yml` already redirects to the spec repo. - Add `00-blank.yml` so a "Blank issue" option sits first in the chooser ahead of structured forms. GitHub's built-in blank can't be reordered (it always lands last when enabled), so this is a yml template that mimics it; `blank_issues_enabled: false` stays as-is in `config.yml`. - Fix `cd agentnative` → `cd agentnative-cli` in Contributing block; add the `git config core.hooksPath scripts/hooks` line so contributors mirror CI on every push.
11 tasks
brettdavies
added a commit
that referenced
this pull request
May 1, 2026
## Summary Add `scripts/SYNCS.md` as the single navigable map of every inbound and outbound data edge between this repo and its siblings (`agentnative-spec`, `agentnative-site`, `homebrew-tap`, `crates.io`). Operators currently have to read four script headers + three prose docs (`RELEASES.md`, `CLAUDE.md`, `AGENTS.md`) and assemble the picture in their head; this file makes the system legible at a glance. ## Changelog ### Documentation - Add `scripts/SYNCS.md` — cross-repo sync map covering every spec/skill/coverage/release data flow with mechanism, payload, trigger, and drift check per edge. Includes a flowchart of inbound/outbound edges, a release-pipeline sequence diagram, and a cadence summary table reducing the system to "automatic vs manual" per sync point. ## Type of Change - [x] `docs`: Documentation update ## Related Issues/Stories - Story: n/a - Issue: n/a - Architecture: anchors back on `docs/solutions/architecture-patterns/cross-repo-artifact-sync-commit-over-fetch-20260420.md` (the "commit-over-fetch" decision) and `docs/solutions/best-practices/cross-repo-artifact-consumption-static-sites-2026-04-21.md` (the consumer-side pattern). - Related PRs: none. Complements (not blocked by) #40. ## Testing - [x] Manual testing completed - [x] All tests passing **Test Summary:** - Pre-push hook ran: fmt, clippy `-Dwarnings`, full test suite, cargo-deny, Windows libc grep + cross-target clippy — all green. - `markdownlint-cli2` fired via the auto-format hook on every save — no warnings. - Verified Mermaid blocks parse with the GitHub renderer (flowchart + sequence diagram). - Cross-checked every sync edge against the actual scripts (`scripts/sync-spec.sh`, `scripts/sync-skill-fixture.sh`, `scripts/sync-dev-after-release.sh`) and against `.github/workflows/release.yml` / `finalize-release.yml` / `skill-fixture-drift.yml` so the document matches the wired-up automation. ## Files Modified **Modified:** - None. **Created:** - `scripts/SYNCS.md` — 151 lines, cross-repo sync map. **Renamed:** - None. **Deleted:** - None. ## Key Features - One page that names every sync edge: spec → cli (`sync-spec.sh`), site → cli (`sync-skill-fixture.sh`), main → dev (`sync-dev-after-release.sh`), cli → site (coverage matrix + scorecards), cli → homebrew-tap (formula + bottles), cli → crates.io, and the inverse `finalize-release` dispatch. - For every edge: mechanism, payload, trigger/cadence, and drift check. - Two clustering events that drive the system — "new spec tag upstream" and "new anc release downstream" — each spelled out as a manual + automatic step list. - A "what's automatic vs manual" cadence summary so an operator can see at a glance which edges still need a human in the loop. ## Benefits - Operators stop reverse-engineering the sync graph from script headers when prepping a release. - Drift checks are explicit per edge, so adding a new sync surface comes with a paired drift question instead of a quiet skip. - Documents the "commit-over-fetch" pattern in a navigable form so future cross-repo consumers find the precedent before reinventing it. ## 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] Tests added/updated and passing - [x] No new warnings or errors introduced - [x] Changes are backward compatible (or breaking changes documented)
brettdavies
added a commit
that referenced
this pull request
May 1, 2026
## Summary v0.3.0 promotes 15 PRs from `dev` to `main`. Headline: scorecard schema bumps `0.3` → `0.5` (cumulative — `anc.commit` removed before tag), a new `anc skill install <host>` subcommand with hardened `git clone` + build-time host-map codegen, and a published agent-native badge surface (text-mode hint + JSON `badge` block) gated on a 80% eligibility floor. Plus PII fix on `target.path`, source-quality cleanup, README refresh, cross-repo sync map, and tooling-side hardening (PR template `**Renamed:**` subsection, `sync-spec` modernization, `sync-skill-fixture` drift gate, triple-diff release-flow check with squash-merge triage guidance). The release-prep also surfaced four corrections that came in via the canonical PR-to-dev flow during this ship: `#43` resynced the `skill.json` build-time fixture against upstream `agentnative-site/dev` (drift was blocking every open PR); `#42` corrected cross-repo URLs in `.github/ISSUE_TEMPLATE/` (broken since the v0.1.1 squash on `main`); `#45` replaced the release-flow's single-direction leak check with a triple-diff plus `git cherry` patch-id check (the latter caught the URL drift that motivated the change); `#46` added squash-merge-noise triage guidance to the `git cherry` step (the check produced 55 noisy `+` lines on first run, all expected, but the original comment didn't explain that). `#47` dropped the `anc.commit` field from the scorecard JSON before the v0.3.0 tag, since the `cargo:rerun-if-changed` `.git/` watches made cached builds fragile and `anc.version` is sufficient build identity. ## Changelog <!-- Per the changelog generation rules, the canonical changelog is in CHANGELOG.md. This release section reflects the same content; generate-changelog.sh extracts from each contributing PR's ## Changelog block. The bullets below are a curated highlight set for the PR body itself. --> ### Added - `anc skill install <host>` subcommand for six hosts (`claude_code`, `codex`, `cursor`, `factory`, `kiro`, `opencode`) with `--dry-run` and `--output {text,json}` flags and a uniform JSON envelope across success, error, and dry-run paths (#35). - Scorecard `--output json` self-describing metadata: four top-level blocks (`tool`, `anc`, `run`, `target`) + a `badge` block with `eligible`, `score_pct`, `embed_markdown`, `scorecard_url`, `badge_url`, `convention_url` (#34, #36). - `--output text` post-summary agent-native badge embed hint when the tool clears the 80% eligibility floor; "do not nag" rule below (#36). ### Changed - Scorecard `schema_version` bumped `0.3` → `0.4` → `0.5` (cumulative — `anc.commit` field removed before the v0.3.0 tag, see #47) (#34, #36). - `sync-spec.sh` modernized — remote-first tag resolution, `SPEC_REF` env override removed (#33). - `p7-naked-println` source check now exempts `build.rs` at any crate root (#38). - README refreshed for current state (schema 0.5, badge block, `--audit-profile`, basename `target.path`); `rust-version` bumped `1.87` → `1.88` (#34, #40). - `--output json` scorecard `anc` block no longer includes a `commit` field — `anc.version` is the build identity (#47). ### Fixed - `target.path` in `--output json` now emits the basename of the resolved target instead of the canonicalized absolute path — eliminates a home-dir / username PII leak that flowed into committed scorecards, badge URLs, and agent-posted artifacts (#39). - Eliminated four `.unwrap()` calls on infallible paths across `src/skill_install.rs` and `build.rs`, replaced with `.expect("…")` naming the contract (#38). - Cross-repo URLs in `.github/ISSUE_TEMPLATE/` corrected: spec → `agentnative`, site → `agentnative-site`, double-`cli` typo → `agentnative-cli` (#42). ### Documentation - `scripts/SYNCS.md` cross-repo sync map (#41). - `RELEASES.md` § "After publish — sync `dev` with the release" + new `sync-dev-after-release.sh` script formalizing the post-publish backport convention (#37). - `RELEASES.md` § "Releasing dev to main" step 4 replaced with a triple-diff verification block (A: main→release, B: release→dev, C: dev→main) plus a `git cherry` patch-id check (#45), with squash-merge-noise triage guidance added in #46. - README `## Install the skill` section + `[![agent-native]]` badge row (#35, #40). ## Type of Change - [x] `feat`: New feature (non-breaking change which adds functionality) - [x] `fix`: Bug fix (non-breaking change which fixes an issue) - [x] `chore`: Maintenance tasks (dependencies, config, etc.) - [x] `docs`: Documentation update ## Related Issues/Stories - Story: v0.3.0 release — twelve PRs across two days of work post-v0.2.0 plus four release-prep PRs (#42, #43, #45, #46) opened during the release ceremony to fix issues caught by the new triple-diff verification, plus #47 dropping `anc.commit` before the tag. - Issue: n/a - Architecture: scorecard schema evolution (`0.3 → 0.4 → 0.5`) covered in CLAUDE.md `## Scorecard v0.5 Fields`; skill-install architecture covered in CLAUDE.md `## Skill Install Verb`; release ceremony in `RELEASES.md`. - Related PRs: #30, #33, #34, #35, #36, #37, #38, #39, #40, #41, #42, #43, #45, #46, #47 — all merged to `dev` and cherry-picked here in chronological order. ## Testing - [x] Unit tests added/updated - [x] Integration tests added/updated - [x] Manual testing completed - [x] All tests passing **Test Summary:** - Unit tests: 535+ passing across all #34, #35, #36, #38, #39 PRs (counts varied as PRs landed). #47 simplified to ~520+ after dropping the `anc_commit_when_present_looks_like_short_sha` test. - Integration tests: full suite green at every cherry-pick step. New tests added: `tests/scorecard_metadata_security.rs` (red-team regressions for hostile binaries), `tests/scorecard_schema_v05.rs` (schema drift guard with `target.path` regression test), `tests/skill_install.rs` (10 active + 1 ignored e2e), `tests/dogfood.rs` (p2/p5 dogfood guards). - Coverage: pre-push hook (CI mirror) green at every step — fmt, clippy `-Dwarnings`, full test suite, cargo-deny, Windows compat (libc grep + cross-target clippy). - Triple-diff verification (the new step from #45) confirmed only `docs/plans/`, `docs/brainstorms/`, `docs/ideation/` (guarded paths) and the `docs/solutions` symlink remain on dev. Release-prep files (`CHANGELOG.md`, `Cargo.{toml,lock}`, `completions/*`) will backport to dev via `scripts/sync-dev-after-release.sh` post-publish per the convention from #37. The `git cherry` patch-id check produced 55 `+` lines on first run; all audited as expected (squash-merge patch-id mismatch + conflict-resolution drift + intentional skips), zero real misses — motivated #46's triage guidance. ## Files Modified **Modified:** - `Cargo.toml`, `Cargo.lock` — version `0.2.0 → 0.3.0`; `time = "=0.3.47"` added; `rust-version` bumped. - `CHANGELOG.md` — v0.3.0 release notes prepended. - `README.md`, `AGENTS.md`, `CLAUDE.md` — updated for schema 0.4/0.5, skill-install architecture, audit-profile, basename `target.path`, badge surface, `anc.commit` removal. - `RELEASES.md` — post-publish backport step (#37); skill-fixture sync step; step 4 replaced with triple-diff + `git cherry` check (#45); squash-merge triage guidance added (#46). - `build.rs` — `emit_skill_hosts` codegen, `ANC_VERSION` emission (no longer Git-SHA-aware after #47). - `src/build_info.rs` — `ANC_VERSION` re-export; `ANC_COMMIT` and its test removed in #47. - `src/main.rs`, `src/cli.rs`, `src/error.rs`, `src/scorecard/mod.rs`, `src/argv.rs` — schema 0.4/0.5 metadata, skill-install dispatch, badge computation, basename helper. `AncInfo` shrinks to one field after #47. - `src/checks/source/rust/naked_println.rs` — build.rs exemption. - `src/skill_install/skill.json` — fixture refresh (`source.commit` pin and `verify` block removed by upstream). - `scripts/sync-spec.sh` — remote-first, `SPEC_REF` removed. - `scripts/hooks/pre-push` — Windows cross-clippy step. - `.github/pull_request_template.md` — `**Renamed:**` sub-header. - `.github/ISSUE_TEMPLATE/{config,false-positive,feature-request,scoring-bug}.yml` — corrected cross-repo URLs. - `completions/anc.{bash,zsh,fish,elvish,powershell}` — regenerated. **Created:** - `src/output.rs`, `src/skill_install.rs`, `src/skill_install/skill.json`. - `tests/dogfood.rs`, `tests/scorecard_metadata_security.rs`, `tests/scorecard_schema_v05.rs`, `tests/skill_install.rs`, `tests/fixtures/hostile-{hang,nonzero-exit,stdout-flood}/probe.sh`. - `scripts/sync-skill-fixture.sh`, `scripts/sync-dev-after-release.sh`, `scripts/SYNCS.md`. - `.github/workflows/skill-fixture-drift.yml`. - `.github/ISSUE_TEMPLATE/00-blank.yml`. **Renamed:** - `tests/scorecard_schema_v04.rs` → `tests/scorecard_schema_v05.rs` (drift guard now covers `badge.*` keys). - `tests/fixtures/skill.json` → `src/skill_install/skill.json` (codegen needs to read from a path inside cargo's package). **Deleted:** - `.github/ISSUE_TEMPLATE/grade-a-cli.yml`, `pressure-test.yml`, `spec-question.yml` — duplicates of the spec repo's set; routed via `config.yml`. - `src/build_info.rs::ANC_COMMIT` const (and its test) — dropped before tag, see #47. ## Breaking Changes - [x] No breaking changes The scorecard `schema_version` bumps (`0.3` → `0.4` → `0.5`) are additive within the documented `0.x` pre-launch policy. Pre-`0.4` consumers feature-detect the four metadata blocks; pre-`0.5` consumers feature-detect the `badge` key. `target.path` value semantics changed (basename instead of absolute path) — schema shape is unchanged, so consumers reading the field at all will continue to parse it; consumers using it for cross-host correlation should already have migrated to `tool.name`. `anc.commit` was added in 0.4 but removed before the v0.3.0 tag (#47); no public consumer of the field exists pre-launch. ## Deployment Notes - [x] No special deployment steps required Standard pipeline: tag push triggers crates.io publish (Trusted Publishing, OIDC), GitHub Release with all 5 platform archives + sha256sums, then dispatch to `brettdavies/homebrew-tap` for formula update. After `finalize-release.yml` flips `make_latest: true`, run `./scripts/sync-dev-after-release.sh v0.3.0` to backport `Cargo.toml`, `Cargo.lock`, `CHANGELOG.md` to dev (new convention from #37). ## 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)
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
Refresh
README.mdto match the post-v0.2.0 surface and add theanc.devagent-native badge at the top(local TODO 019). Trim
.github/ISSUE_TEMPLATE/to cli-scope perCONTRIBUTING.mdrouting and add a blank-issuefallback that sorts first in the chooser.
ancscores 97% against its own spec; the badge now displays the score on the canonical README.Changelog
Changed
badgeblock,--audit-profile <CATEGORY>documented underCLI Reference,
target.pathdocumented as basename-only (PII-safe), refreshed Example Output to match the live33-check dogfood and the post-summary badge embed hint.
Documentation
[](https://anc.dev/score/anc)badge plus crates.io andlicense shields at the top of
README.md..github/ISSUE_TEMPLATE/tofalse-positive,feature-request,scoring-bug, plus a new00-blank.ymlthat lets a Blank issue option sit first in the chooser ahead of the structured forms. Spec-side templates
(
pressure-test,grade-a-cli,spec-question) were duplicates of the spec repo's set from before therename. They belong on
brettdavies/agentnativeonly, andconfig.ymlalready redirects there.Type of Change
docs: Documentation updatechore: Maintenance tasks (dependencies, config, etc.)Related Issues/Stories
.context/compound-engineering/todos/019-completed-p0-add-anc-badge-to-readme.md)target.path) and feat(scorecard): badge embed hint after passing anc check (schema 0.5) #36 (badge embed in scorecard 0.5)Testing
Test Summary:
-Dwarnings, 445 unit + integration tests, cargo-deny, Windows libc grep + cross-target clippy, all green.cargo run -- check .confirms the live 33-check dogfood reported in the README's Example Output.curl -sSI https://anc.dev/badge/anc.svgandhttps://anc.dev/score/ancbothHTTP/2 200, so the embedded badge resolves before merge.Files Modified
Modified:
README.md: badge row, schema 0.5 / badge block, basenametarget.path,--audit-profileflag, refreshed Example Output, Contributing block fix.Created:
.github/ISSUE_TEMPLATE/00-blank.yml: blank-issue template that sorts first in the chooser.Renamed:
Deleted:
.github/ISSUE_TEMPLATE/grade-a-cli.yml: moved to spec repo only..github/ISSUE_TEMPLATE/pressure-test.yml: moved to spec repo only..github/ISSUE_TEMPLATE/spec-question.yml: moved to spec repo only.Key Features
CONTRIBUTING.md's cross-repo routing table, so no more spec-side issues get filed on the cli repo by accident.Benefits
anc.devor a Show HN reader checking the canonical implementation.Breaking Changes
Deployment Notes
Checklist