docs(scripts): add SYNCS.md cross-repo sync map - #41
Merged
Conversation
Lay out every inbound and outbound data edge between agentnative-cli and its sibling repos (spec, site, homebrew-tap, crates.io) in one navigable document. Complements the per-script header comments and the prose in RELEASES.md / CLAUDE.md / AGENTS.md by giving operators a single page to reason about what triggers what, who owns each drift check, and which sync points are automated vs manual. Includes: - A flowchart of inbound/outbound edges with this repo at the center. - Two tables (Upstream / Downstream) detailing mechanism, payload, trigger, and drift check for every sync point. - Release/sync orchestration prose anchored on the two events that drive everything (new spec tag upstream, new anc release downstream). - A sequence diagram of the release pipeline through to finalize-release. - A cadence summary table reducing the system to "automatic vs manual" per edge.
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
Add
scripts/SYNCS.mdas the single navigable map of every inbound and outbound data edge between this repo and itssiblings (
agentnative-spec,agentnative-site,homebrew-tap,crates.io). Operators currently have to read fourscript headers + three prose docs (
RELEASES.md,CLAUDE.md,AGENTS.md) and assemble the picture in their head; thisfile makes the system legible at a glance.
Changelog
Documentation
scripts/SYNCS.md, a 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
docs: Documentation updateRelated Issues/Stories
docs/solutions/architecture-patterns/cross-repo-artifact-sync-commit-over-fetch-20260420.md(the "commit-over-fetch" decision) anddocs/solutions/best-practices/cross-repo-artifact-consumption-static-sites-2026-04-21.md(the consumer-side pattern).Testing
Test Summary:
-Dwarnings, full test suite, cargo-deny, Windows libc grep + cross-target clippy, all green.markdownlint-cli2fired via the auto-format hook on every save, no warnings.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.ymlso the document matches the wired-up automation.Files Modified
Modified:
Created:
scripts/SYNCS.md: 151 lines, cross-repo sync map.Renamed:
Deleted:
Key Features
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 inversefinalize-releasedispatch.Benefits
Breaking Changes
Deployment Notes
Checklist