Skip to content

chore(sync-spec): modernize — remote-first, drop SPEC_REF - #33

Merged
brettdavies merged 1 commit into
devfrom
chore/sync-spec-modernize
Apr 29, 2026
Merged

chore(sync-spec): modernize — remote-first, drop SPEC_REF#33
brettdavies merged 1 commit into
devfrom
chore/sync-spec-modernize

Conversation

@brettdavies

@brettdavies brettdavies commented Apr 29, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

Summary

Lockstep update with brettdavies/agentnative-skill PR #11. Both repos now share an identical sync-spec.sh shape;
only DEST_DIR differs (src/principles/spec/ here vs spec/ in the skill repo).

Two coordinated changes to scripts/sync-spec.sh:

  1. Drop SPEC_REF override entirely. The script always vendors the latest v* tag; no opt-in version selection.
    Removes the SPEC_REF env var, the SPEC_REF default that constantly went stale (last value v0.3.0), and all
    the doc references that pointed at manual bumps.

  2. Resolve from remote first, fall back to local. New flow:

    1. git ls-remote --tags --sort=-version:refname against SPEC_REMOTE_URL
      (default https://github.com/brettdavies/agentnative.git) to discover the latest tag without a checkout.
    2. Fall back to git -C \"$SPEC_REPO\" tag --sort=-version:refname only when the remote query fails or returns
      no tags. Prior order was the opposite: local-first, with remote as override.
    3. Document offline use via --from-local <path> for full reproducibility (no network needed if the user has a
      checkout already).

Changelog

Changed

  • Vendoring now always tracks the latest published spec tag; SPEC_REF env override removed. Run
    bash scripts/sync-spec.sh to refresh; no environment configuration required.

Documentation

  • AGENTS.md and src/principles/spec/README.md updated to reflect the simpler vendor flow.

Type of Change

  • chore: Maintenance tasks (dependencies, config, etc.)

Related Issues/Stories

Testing

  • Manual testing completed
  • All checks passing

Test Summary: Pre-push hook passed (fmt, clippy -Dwarnings, test, cargo-deny, Windows compatibility).

Files Modified

Modified:

  • scripts/sync-spec.sh: remote-first resolution, SPEC_REF removed
  • AGENTS.md: vendor-flow doc updates
  • src/principles/spec/README.md: vendor-flow doc updates

Breaking Changes

  • No breaking changes (consumer-facing: anyone who relied on SPEC_REF for a non-latest tag must now use
    --from-local <path-to-checkout-at-desired-tag>).

Deployment Notes

  • No special deployment steps required.

Checklist

  • Code follows project conventions and style guidelines
  • Commit messages follow Conventional Commits
  • Self-review of code completed
  • No new warnings or errors introduced
  • Changes are backward compatible

@brettdavies
chore(sync-spec): modernize — remote-first, drop SPEC_REF
7aaf808 
Lockstep update with brettdavies/agentnative-skill PR #11. Both repos
now share an identical sync-spec.sh shape; only DEST_DIR differs
(src/principles/spec/ here vs. spec/ in the skill repo).

Two coordinated changes:

1. Drop SPEC_REF override entirely. The script always vendors the
   latest v* tag; no opt-in version selection. Removes the SPEC_REF
   env var, the SPEC_REF default that constantly went stale (was
   v0.3.0), and all the doc references that called out manual bumps.

2. Resolve from remote first, fall back to local. New flow:
   a. `git ls-remote --tags --sort=-version:refname` against
      SPEC_REMOTE_URL (default https://github.com/brettdavies/agentnative.git)
      → pick latest v* tag.
   b. `git clone --depth 1 --branch <tag>` that tag into a temp dir.
   c. On any remote failure, warn and fall back to local SPEC_ROOT
      (default $HOME/dev/agentnative-spec) — the previous behavior.
   d. Both fail → hard error with both URL and SPEC_ROOT printed.
   New env var SPEC_REMOTE_URL overrides the remote. Temp clone is
   trap-cleaned on script exit.

Doc updates (AGENTS.md, src/principles/spec/README.md):

- AGENTS.md "Spec source (principles)": drop "pinned snapshot",
  "default SPEC_REF", "current pin", and "bump via SPEC_REF=..."
  language. Resync cadence now mentions remote-first / local-fallback
  behavior; companion repository_dispatch trigger framing preserved.
- src/principles/spec/README.md: drop hand-maintained "Current pin"
  line (the truth lives in spec/VERSION); rewrite Resync section to
  document the new single-step flow plus SPEC_REMOTE_URL / SPEC_ROOT
  overrides.

build.rs and build_support/parser.rs untouched — DEST_DIR is unchanged
(src/principles/spec/), so the Rust build inputs see the same shape.

Behavior verified locally: remote-success path resolves v0.3.0 from
GitHub and writes 7 principles + VERSION + CHANGELOG. Live test on
this branch matched the existing src/principles/spec/ content exactly
(reverted post-test).
@brettdavies
brettdavies merged commit fff3f13 into dev Apr 29, 2026
6 checks passed
@brettdavies
brettdavies deleted the chore/sync-spec-modernize branch April 29, 2026 21:33
@brettdavies brettdavies mentioned this pull request May 1, 2026
Merged
16 tasks
brettdavies added a commit that referenced this pull request May 1, 2026
@brettdavies
release: v0.3.0 (#44)
8789d09 
## 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)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@brettdavies