chore(sync-spec): drop SHA-pin claims, modernize to remote-first vendoring#11
Merged
Conversation
Eliminates all SHA-pin model claims and the SPEC_REF override surface.
After this commit, `rg` for any of {SHA, sha-pin, commit sha, source.commit,
install.json, re-pin, SPEC_REF, pin/pinned/pinning} across shipping
content (excluding plans, license boilerplate, and changelogs) returns
zero matches.
Two coordinated cleanups, both serving the same goal: the install model
is "plain git clone + bin/check-update for staleness," nothing pins to
anything cross-repo, and the bundle's spec/ snapshot tracks the latest
upstream tag automatically.
1. Install-pin claims removed from RELEASES.md + AGENTS.md:
- RELEASES.md pipeline diagram: drop "site re-pins to commit SHA"
- RELEASES.md post-merge step 5 (SHA handoff to site): replaced with
a one-liner pointing at bin/check-update for consumer staleness
- RELEASES.md protect-tags description: drop "install.json pins to"
- AGENTS.md NEVER-do bullet: drop "install endpoints pin to"
2. Spec-vendor pinning eliminated entirely:
- sync-spec.sh: drops SPEC_REF env var; always auto-resolves the
latest v* tag from the local SPEC_ROOT checkout via `git tag --list
'v*' --sort=-version:refname | head -n 1`. SPEC_ROOT override still
supported for non-default checkout locations.
- AGENTS.md, README.md, spec/README.md, CONTRIBUTING.md: drop
"at a pinned ref" / "at a pinned SPEC_REF" / "the pin and resync"
/ "the current pin is recorded" / "at a new SPEC_REF" prose. Spec
version is recorded in spec/VERSION; that is the documented surface.
Bundle behavior unchanged (consumers still get a spec/ snapshot; consumers
still detect new releases via bin/check-update). Producer-side workflow
simplified: no manual SPEC_REF bumps; running sync-spec.sh after a fetch
is the entire recipe.
sync-spec.sh now resolves the latest v* tag from a remote URL (SPEC_REMOTE_URL, default https://github.com/brettdavies/agentnative.git) via `git ls-remote --tags --sort=-version:refname`, then shallow-clones that tag into a temp directory for extraction. If the remote query fails (network down, URL wrong, server error), the script falls back to the local SPEC_ROOT-based logic from the previous commit. Three execution paths verified: - Remote OK → "vendoring v0.3.0 (5cea8bf) from remote https://...git" - Remote fail → "warning: remote query failed; falling back to local /home/.../agentnative-spec" then proceeds with local tag resolution - Both fail → hard error with both URL and SPEC_ROOT printed Cleanup: temp clone directory is removed on script exit (any path), guarded by a trap so half-successful clones don't leak. Doc updates: - AGENTS.md "Spec sync" section: drop the manual `git fetch --tags` step (remote query is the new happy path); add SPEC_REMOTE_URL override. - spec/README.md "Resync" section: same. Behavior unchanged for the pure-local invocation: SPEC_ROOT still works exactly as before, just as a fallback rather than the primary source.
brettdavies
changed the title
brettdavies
added a commit
that referenced
this pull request
Apr 29, 2026
…oring (#11) ## Summary Two coordinated cleanups to `scripts/sync-spec.sh` and surrounding docs: 1. **Drop the SHA-pin model.** Eliminates all SHA-pin claims and the `SPEC_REF` override surface. After this PR merges, `rg` for any of `SHA`, `sha-pin`, `commit sha`, `source.commit`, `install.json`, `re-pin`, `SPEC_REF`, `pin`, `pinned`, `pinning` across shipping content (excluding `docs/plans/`, license boilerplate, and `CHANGELOG.md` / `spec/CHANGELOG.md`) returns **zero** matches. 2. **Remote-first vendoring with local fallback.** `sync-spec.sh` queries the upstream remote for the latest `v*` tag first; only falls back to a local `SPEC_ROOT` checkout when the remote is unreachable. Removes the manual `git fetch --tags` step from the happy path; works in fresh environments without a pre-existing local clone. ## Changelog ### Changed - `scripts/sync-spec.sh`: - **No longer accepts `SPEC_REF`.** Always vendors the latest `v*` tag. - **Resolution path:** queries `SPEC_REMOTE_URL` (default `https://github.com/brettdavies/agentnative.git`) via `git ls-remote --tags --sort=-version:refname`, picks the latest `v*`, then shallow-clones that tag into a temp directory for extraction. On any remote failure, falls back to the existing `SPEC_ROOT`-based logic (default `$HOME/dev/agentnative-spec`). - **New env var `SPEC_REMOTE_URL`** for overriding the remote. - **Temp clone is auto-cleaned** on script exit via trap. ### Removed - All SHA-pin claims from public-facing markdown (`RELEASES.md`, `AGENTS.md`, `README.md`, `spec/README.md`, `CONTRIBUTING.md`): pipeline diagram's "site re-pins to commit SHA" step, the post-merge "site re-pins via its own PR" step, the `protect-tags.json` / `install endpoints` claims that tags are pinned to install endpoints, and the spec-vendor "pinned ref" / "pinned `SPEC_REF`" / "current pin is recorded" vocabulary across all docs. ### Documentation - `AGENTS.md` `## Spec sync` section: rewritten — single-step recipe (`scripts/sync-spec.sh` then review); notes the remote-first / local-fallback behavior and the `SPEC_REMOTE_URL` / `SPEC_ROOT` overrides. Commit-message example uses `<version>` placeholder instead of a hard-coded version. - `spec/README.md` `## Resync` section: rewritten similarly; drops the manually-maintained `**Current snapshot:**` line and points readers at `spec/VERSION` (which `sync-spec.sh` writes verbatim from upstream). - `RELEASES.md` post-merge sequence ends at the GitHub Release; replaces deleted step 5 with a one-liner pointing consumers at `bin/check-update`. ## Type of Change - [x] `chore`: Maintenance tasks (dependencies, config, etc.) - [x] `docs`: Documentation update ## Related Issues/Stories - Architecture: `docs/plans/2026-04-28-001-feat-update-check-mechanism-plan.md` U6 (retroactive plan-doc + repo SHA-pin scrub) — partial. Plan files themselves are not scrubbed in this PR (they are dev-only and contain the historical record of the SHA-pin removal effort). - Related PRs: PR #10 (spec re-vendor v0.3.0) — touches different `RELEASES.md` hunks; no conflict expected at merge. - Mirror: `agentnative-cli/scripts/sync-spec.sh` is the documented mirror of this script. Lockstep update PR will land there as a separate change. ## Testing - [x] Manual testing completed - [x] All tests passing **Test Summary:** - `markdownlint-cli2` clean on all touched files (PostToolUse hook ran on each edit). - `shellcheck --severity=style scripts/sync-spec.sh`: clean. - `bash -n scripts/sync-spec.sh`: clean. - **Remote-success path** verified live: queried `https://github.com/brettdavies/agentnative.git`, resolved `v0.3.0`, shallow-cloned, vendored 7 principles + VERSION + CHANGELOG.md. Output: `vendoring v0.3.0 (5cea8bf) from remote https://github.com/brettdavies/agentnative.git`. - **Remote-fail-local-success path** verified by setting `SPEC_REMOTE_URL=https://github.com/brettdavies/does-not-exist.git`. Output: `warning: remote query failed; falling back to local /home/brett/dev/agentnative-spec` followed by successful vendor from local. - **Both-fail path** verified by setting both bogus remote and bogus `SPEC_ROOT=/tmp/no-such-dir`. Output: `error: remote unreachable and SPEC_ROOT is not a git repository: /tmp/no-such-dir` with both URL and path printed for debugging. - Final grep across shipping content for the full pin-vocabulary regex: **zero** matches. ## Follow-ups (not blocking this PR) - `agentnative-cli/scripts/sync-spec.sh` is documented as a mirror of this script (only `DEST_DIR` differs). Lockstep PR coming in that repo to apply the same modernization. - `agentnative-site` does not yet have a `sync-spec.sh` (only a plan doc). When that script lands per `docs/plans/2026-04-23-001-feat-sync-spec-plan.md`, it should adopt the same remote-first / no-SPEC_REF shape. - Plan files under `docs/plans/` retain SHA-pin language as historical record. If a future cleanup pass wants to scrub them too, that's a separate dev-only PR.
12 tasks
brettdavies
added a commit
that referenced
this pull request
Apr 29, 2026
…on (#10) ## Summary Re-vendor `spec/` from `agentnative-spec` v0.2.0 → v0.3.0 (status flips draft → active across all 7 principles, prose edits from upstream G11 red-team pass) and add a `## Spec re-vendoring` section to `RELEASES.md` documenting the upstream-only coordination model. Originally landed as an in-cherry-pick on `release/v0.2.0` (commit `837ab9a` → amended `1640460`). Converting to a real PR so the v0.2.0 CHANGELOG carries a curated bullet for the spec bump — direct cherry-picks have no PR body for `scripts/generate-changelog.sh` to extract from. After PR #11 (sync-spec modernization) landed on dev, this branch was rebased and the new RELEASES.md section was rewritten to drop `SPEC_REF` references that PR #11 eliminated. ## Changelog ### Changed - Spec content vendored under `spec/` re-vendored from `agentnative-spec` v0.2.0 to v0.3.0. All 7 principles flip `status: draft` → `status: active` (P1–P7 are now the shipped baseline); prose tightened across P1 (TUI parenthetical), P2 (sysexits acknowledgment), P4 (dependency-gating cleanup), P5 (`--dry-run` write-gate + retry hedge), P6 (SIGPIPE language-neutral + global-flags behavioral lead), P7 (LLM-vs-non-LLM cost generalization). No requirement IDs added/removed/renamed; no level changes. Full upstream context: agentnative `v0.3.0` CHANGELOG. ### Documentation - `RELEASES.md` gains a `## Spec re-vendoring` section between `## Why branch from main, not dev` and `## Version bump procedure`, documenting the `scripts/sync-spec.sh` re-vendor step. The script auto-resolves the latest upstream tag from the remote, so no manual version selection is needed at re-vendor time. ## Type of Change - [x] `chore`: Maintenance tasks (dependencies, config, etc.) - [x] `docs`: Documentation update ## Related Issues/Stories - Architecture: `docs/plans/2026-04-27-001-bootstrap-agentnative-skill-plan.md` task #15 (in-cherry-pick edits subsection) - Related PRs: PR #11 (`chore(sync-spec): drop SHA-pin claims, modernize to remote-first vendoring`) — already merged; this PR was rebased onto dev after #11 landed and its added section was updated to match the post-#11 vocabulary. - Replaces: in-cherry-pick commit `1640460` on `release/v0.2.0`. After this PR squash-lands on `dev`, the release branch will be replayed to swap `1640460` for this PR's squash commit (which carries the curated CHANGELOG bullet). ## Testing - [x] Manual testing completed - [x] All tests passing **Test Summary:** - `markdownlint-cli2` clean on all touched files (PostToolUse hook ran on each edit; explicit pre-push run after the post-rebase RELEASES.md fix: 0 errors). - `shellcheck` n/a (no shell changes — this PR no longer touches `scripts/sync-spec.sh`; that surface is owned by PR #11 which is already on dev). - `spec/VERSION` confirmed at `0.3.0`. - `spec/CHANGELOG.md` carries the curated v0.3.0 entry from upstream agentnative. - Post-rebase diff against `origin/dev`: 10 files, +294/-60 — only `spec/*` (vendored content) and `RELEASES.md` (new section). No conflict against PR #11's already-landed `sync-spec.sh` modernization. - Vocabulary check: `rg` for `SPEC_REF` in this PR's diff returns zero matches (was non-zero before rebase; fixed by amending the RELEASES.md section to use the auto-resolve framing). ## Files Modified **Modified:** - `RELEASES.md` — `+8 lines`: new `## Spec re-vendoring` section between existing sections. - `spec/VERSION` — `0.2.0` → `0.3.0`. - `spec/CHANGELOG.md` — re-vendored from upstream; carries the v0.3.0 entry. - `spec/principles/p1-non-interactive-by-default.md` — re-vendored. - `spec/principles/p2-structured-parseable-output.md` — re-vendored. - `spec/principles/p3-progressive-help-discovery.md` — re-vendored. - `spec/principles/p4-fail-fast-actionable-errors.md` — re-vendored. - `spec/principles/p5-safe-retries-mutation-boundaries.md` — re-vendored. - `spec/principles/p6-composable-predictable-command-structure.md` — re-vendored. - `spec/principles/p7-bounded-high-signal-responses.md` — re-vendored. ## Breaking Changes - [x] No breaking changes The principle status flip from `draft` → `active` is a state-of-spec signal, not a contract change. Requirement IDs, levels, and applicability are unchanged. ## Deployment Notes - [x] No special deployment steps required Vendored content only; consumers pick up the new spec on their next `git pull --ff-only` (driven by `bin/check-update`). ## 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 (CI: markdownlint + shellcheck pass) - [x] No new warnings or errors introduced - [x] Changes are backward compatible
13 tasks
brettdavies
added a commit
that referenced
this pull request
Apr 29, 2026
…on (#10) ## Summary Re-vendor `spec/` from `agentnative-spec` v0.2.0 → v0.3.0 (status flips draft → active across all 7 principles, prose edits from upstream G11 red-team pass) and add a `## Spec re-vendoring` section to `RELEASES.md` documenting the upstream-only coordination model. Originally landed as an in-cherry-pick on `release/v0.2.0` (commit `837ab9a` → amended `1640460`). Converting to a real PR so the v0.2.0 CHANGELOG carries a curated bullet for the spec bump — direct cherry-picks have no PR body for `scripts/generate-changelog.sh` to extract from. After PR #11 (sync-spec modernization) landed on dev, this branch was rebased and the new RELEASES.md section was rewritten to drop `SPEC_REF` references that PR #11 eliminated. ## Changelog ### Changed - Spec content vendored under `spec/` re-vendored from `agentnative-spec` v0.2.0 to v0.3.0. All 7 principles flip `status: draft` → `status: active` (P1–P7 are now the shipped baseline); prose tightened across P1 (TUI parenthetical), P2 (sysexits acknowledgment), P4 (dependency-gating cleanup), P5 (`--dry-run` write-gate + retry hedge), P6 (SIGPIPE language-neutral + global-flags behavioral lead), P7 (LLM-vs-non-LLM cost generalization). No requirement IDs added/removed/renamed; no level changes. Full upstream context: agentnative `v0.3.0` CHANGELOG. ### Documentation - `RELEASES.md` gains a `## Spec re-vendoring` section between `## Why branch from main, not dev` and `## Version bump procedure`, documenting the `scripts/sync-spec.sh` re-vendor step. The script auto-resolves the latest upstream tag from the remote, so no manual version selection is needed at re-vendor time. ## Type of Change - [x] `chore`: Maintenance tasks (dependencies, config, etc.) - [x] `docs`: Documentation update ## Related Issues/Stories - Architecture: `docs/plans/2026-04-27-001-bootstrap-agentnative-skill-plan.md` task #15 (in-cherry-pick edits subsection) - Related PRs: PR #11 (`chore(sync-spec): drop SHA-pin claims, modernize to remote-first vendoring`) — already merged; this PR was rebased onto dev after #11 landed and its added section was updated to match the post-#11 vocabulary. - Replaces: in-cherry-pick commit `1640460` on `release/v0.2.0`. After this PR squash-lands on `dev`, the release branch will be replayed to swap `1640460` for this PR's squash commit (which carries the curated CHANGELOG bullet). ## Testing - [x] Manual testing completed - [x] All tests passing **Test Summary:** - `markdownlint-cli2` clean on all touched files (PostToolUse hook ran on each edit; explicit pre-push run after the post-rebase RELEASES.md fix: 0 errors). - `shellcheck` n/a (no shell changes — this PR no longer touches `scripts/sync-spec.sh`; that surface is owned by PR #11 which is already on dev). - `spec/VERSION` confirmed at `0.3.0`. - `spec/CHANGELOG.md` carries the curated v0.3.0 entry from upstream agentnative. - Post-rebase diff against `origin/dev`: 10 files, +294/-60 — only `spec/*` (vendored content) and `RELEASES.md` (new section). No conflict against PR #11's already-landed `sync-spec.sh` modernization. - Vocabulary check: `rg` for `SPEC_REF` in this PR's diff returns zero matches (was non-zero before rebase; fixed by amending the RELEASES.md section to use the auto-resolve framing). ## Files Modified **Modified:** - `RELEASES.md` — `+8 lines`: new `## Spec re-vendoring` section between existing sections. - `spec/VERSION` — `0.2.0` → `0.3.0`. - `spec/CHANGELOG.md` — re-vendored from upstream; carries the v0.3.0 entry. - `spec/principles/p1-non-interactive-by-default.md` — re-vendored. - `spec/principles/p2-structured-parseable-output.md` — re-vendored. - `spec/principles/p3-progressive-help-discovery.md` — re-vendored. - `spec/principles/p4-fail-fast-actionable-errors.md` — re-vendored. - `spec/principles/p5-safe-retries-mutation-boundaries.md` — re-vendored. - `spec/principles/p6-composable-predictable-command-structure.md` — re-vendored. - `spec/principles/p7-bounded-high-signal-responses.md` — re-vendored. ## Breaking Changes - [x] No breaking changes The principle status flip from `draft` → `active` is a state-of-spec signal, not a contract change. Requirement IDs, levels, and applicability are unchanged. ## Deployment Notes - [x] No special deployment steps required Vendored content only; consumers pick up the new spec on their next `git pull --ff-only` (driven by `bin/check-update`). ## 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 (CI: markdownlint + shellcheck pass) - [x] No new warnings or errors introduced - [x] Changes are backward compatible
brettdavies
added a commit
that referenced
this pull request
Apr 29, 2026
…oring (#11) ## Summary Two coordinated cleanups to `scripts/sync-spec.sh` and surrounding docs: 1. **Drop the SHA-pin model.** Eliminates all SHA-pin claims and the `SPEC_REF` override surface. After this PR merges, `rg` for any of `SHA`, `sha-pin`, `commit sha`, `source.commit`, `install.json`, `re-pin`, `SPEC_REF`, `pin`, `pinned`, `pinning` across shipping content (excluding `docs/plans/`, license boilerplate, and `CHANGELOG.md` / `spec/CHANGELOG.md`) returns **zero** matches. 2. **Remote-first vendoring with local fallback.** `sync-spec.sh` queries the upstream remote for the latest `v*` tag first; only falls back to a local `SPEC_ROOT` checkout when the remote is unreachable. Removes the manual `git fetch --tags` step from the happy path; works in fresh environments without a pre-existing local clone. ## Changelog ### Changed - `scripts/sync-spec.sh`: - **No longer accepts `SPEC_REF`.** Always vendors the latest `v*` tag. - **Resolution path:** queries `SPEC_REMOTE_URL` (default `https://github.com/brettdavies/agentnative.git`) via `git ls-remote --tags --sort=-version:refname`, picks the latest `v*`, then shallow-clones that tag into a temp directory for extraction. On any remote failure, falls back to the existing `SPEC_ROOT`-based logic (default `$HOME/dev/agentnative-spec`). - **New env var `SPEC_REMOTE_URL`** for overriding the remote. - **Temp clone is auto-cleaned** on script exit via trap. ### Removed - All SHA-pin claims from public-facing markdown (`RELEASES.md`, `AGENTS.md`, `README.md`, `spec/README.md`, `CONTRIBUTING.md`): pipeline diagram's "site re-pins to commit SHA" step, the post-merge "site re-pins via its own PR" step, the `protect-tags.json` / `install endpoints` claims that tags are pinned to install endpoints, and the spec-vendor "pinned ref" / "pinned `SPEC_REF`" / "current pin is recorded" vocabulary across all docs. ### Documentation - `AGENTS.md` `## Spec sync` section: rewritten — single-step recipe (`scripts/sync-spec.sh` then review); notes the remote-first / local-fallback behavior and the `SPEC_REMOTE_URL` / `SPEC_ROOT` overrides. Commit-message example uses `<version>` placeholder instead of a hard-coded version. - `spec/README.md` `## Resync` section: rewritten similarly; drops the manually-maintained `**Current snapshot:**` line and points readers at `spec/VERSION` (which `sync-spec.sh` writes verbatim from upstream). - `RELEASES.md` post-merge sequence ends at the GitHub Release; replaces deleted step 5 with a one-liner pointing consumers at `bin/check-update`. ## Type of Change - [x] `chore`: Maintenance tasks (dependencies, config, etc.) - [x] `docs`: Documentation update ## Related Issues/Stories - Architecture: `docs/plans/2026-04-28-001-feat-update-check-mechanism-plan.md` U6 (retroactive plan-doc + repo SHA-pin scrub) — partial. Plan files themselves are not scrubbed in this PR (they are dev-only and contain the historical record of the SHA-pin removal effort). - Related PRs: PR #10 (spec re-vendor v0.3.0) — touches different `RELEASES.md` hunks; no conflict expected at merge. - Mirror: `agentnative-cli/scripts/sync-spec.sh` is the documented mirror of this script. Lockstep update PR will land there as a separate change. ## Testing - [x] Manual testing completed - [x] All tests passing **Test Summary:** - `markdownlint-cli2` clean on all touched files (PostToolUse hook ran on each edit). - `shellcheck --severity=style scripts/sync-spec.sh`: clean. - `bash -n scripts/sync-spec.sh`: clean. - **Remote-success path** verified live: queried `https://github.com/brettdavies/agentnative.git`, resolved `v0.3.0`, shallow-cloned, vendored 7 principles + VERSION + CHANGELOG.md. Output: `vendoring v0.3.0 (5cea8bf) from remote https://github.com/brettdavies/agentnative.git`. - **Remote-fail-local-success path** verified by setting `SPEC_REMOTE_URL=https://github.com/brettdavies/does-not-exist.git`. Output: `warning: remote query failed; falling back to local /home/brett/dev/agentnative-spec` followed by successful vendor from local. - **Both-fail path** verified by setting both bogus remote and bogus `SPEC_ROOT=/tmp/no-such-dir`. Output: `error: remote unreachable and SPEC_ROOT is not a git repository: /tmp/no-such-dir` with both URL and path printed for debugging. - Final grep across shipping content for the full pin-vocabulary regex: **zero** matches. ## Follow-ups (not blocking this PR) - `agentnative-cli/scripts/sync-spec.sh` is documented as a mirror of this script (only `DEST_DIR` differs). Lockstep PR coming in that repo to apply the same modernization. - `agentnative-site` does not yet have a `sync-spec.sh` (only a plan doc). When that script lands per `docs/plans/2026-04-23-001-feat-sync-spec-plan.md`, it should adopt the same remote-first / no-SPEC_REF shape. - Plan files under `docs/plans/` retain SHA-pin language as historical record. If a future cleanup pass wants to scrub them too, that's a separate dev-only PR.
brettdavies
added a commit
that referenced
this pull request
Apr 29, 2026
Bump VERSION to 0.2.0 and regenerate CHANGELOG via scripts/generate-changelog.sh against the cherry-picked PRs (#1, #2, #3, #4, #6, #7, #8, #9, #10, #11). PR bodies were audited by parallel subagents against .github/pull_request_template.md before this regen — empty stubs removed, missing template sections added, internal-detail bullets moved out of ## Changelog, PR #11's nested sub-bullets flattened so the generator preserves them. Squash-merge of release/v0.2.0 onto main becomes the v0.2.0 anchor.
12 tasks
brettdavies
added a commit
that referenced
this pull request
Apr 29, 2026
…on (#10) ## Summary Re-vendor `spec/` from `agentnative-spec` v0.2.0 → v0.3.0 (status flips draft → active across all 7 principles, prose edits from upstream G11 red-team pass) and add a `## Spec re-vendoring` section to `RELEASES.md` documenting the upstream-only coordination model. Originally landed as an in-cherry-pick on `release/v0.2.0` (commit `837ab9a` → amended `1640460`). Converting to a real PR so the v0.2.0 CHANGELOG carries a curated bullet for the spec bump — direct cherry-picks have no PR body for `scripts/generate-changelog.sh` to extract from. After PR #11 (sync-spec modernization) landed on dev, this branch was rebased and the new RELEASES.md section was rewritten to drop `SPEC_REF` references that PR #11 eliminated. ## Changelog ### Changed - Spec content vendored under `spec/` re-vendored from `agentnative-spec` v0.2.0 to v0.3.0. All 7 principles flip `status: draft` → `status: active` (P1–P7 are now the shipped baseline); prose tightened across P1 (TUI parenthetical), P2 (sysexits acknowledgment), P4 (dependency-gating cleanup), P5 (`--dry-run` write-gate + retry hedge), P6 (SIGPIPE language-neutral + global-flags behavioral lead), P7 (LLM-vs-non-LLM cost generalization). No requirement IDs added/removed/renamed; no level changes. Full upstream context: agentnative `v0.3.0` CHANGELOG. ### Documentation - `RELEASES.md` gains a `## Spec re-vendoring` section between `## Why branch from main, not dev` and `## Version bump procedure`, documenting the `scripts/sync-spec.sh` re-vendor step. The script auto-resolves the latest upstream tag from the remote, so no manual version selection is needed at re-vendor time. ## Type of Change - [x] `chore`: Maintenance tasks (dependencies, config, etc.) - [x] `docs`: Documentation update ## Related Issues/Stories - Architecture: `docs/plans/2026-04-27-001-bootstrap-agentnative-skill-plan.md` task #15 (in-cherry-pick edits subsection) - Related PRs: PR #11 (`chore(sync-spec): drop SHA-pin claims, modernize to remote-first vendoring`) — already merged; this PR was rebased onto dev after #11 landed and its added section was updated to match the post-#11 vocabulary. - Replaces: in-cherry-pick commit `1640460` on `release/v0.2.0`. After this PR squash-lands on `dev`, the release branch will be replayed to swap `1640460` for this PR's squash commit (which carries the curated CHANGELOG bullet). ## Testing - [x] Manual testing completed - [x] All tests passing **Test Summary:** - `markdownlint-cli2` clean on all touched files (PostToolUse hook ran on each edit; explicit pre-push run after the post-rebase RELEASES.md fix: 0 errors). - `shellcheck` n/a (no shell changes — this PR no longer touches `scripts/sync-spec.sh`; that surface is owned by PR #11 which is already on dev). - `spec/VERSION` confirmed at `0.3.0`. - `spec/CHANGELOG.md` carries the curated v0.3.0 entry from upstream agentnative. - Post-rebase diff against `origin/dev`: 10 files, +294/-60 — only `spec/*` (vendored content) and `RELEASES.md` (new section). No conflict against PR #11's already-landed `sync-spec.sh` modernization. - Vocabulary check: `rg` for `SPEC_REF` in this PR's diff returns zero matches (was non-zero before rebase; fixed by amending the RELEASES.md section to use the auto-resolve framing). ## Files Modified **Modified:** - `RELEASES.md` — `+8 lines`: new `## Spec re-vendoring` section between existing sections. - `spec/VERSION` — `0.2.0` → `0.3.0`. - `spec/CHANGELOG.md` — re-vendored from upstream; carries the v0.3.0 entry. - `spec/principles/p1-non-interactive-by-default.md` — re-vendored. - `spec/principles/p2-structured-parseable-output.md` — re-vendored. - `spec/principles/p3-progressive-help-discovery.md` — re-vendored. - `spec/principles/p4-fail-fast-actionable-errors.md` — re-vendored. - `spec/principles/p5-safe-retries-mutation-boundaries.md` — re-vendored. - `spec/principles/p6-composable-predictable-command-structure.md` — re-vendored. - `spec/principles/p7-bounded-high-signal-responses.md` — re-vendored. ## Breaking Changes - [x] No breaking changes The principle status flip from `draft` → `active` is a state-of-spec signal, not a contract change. Requirement IDs, levels, and applicability are unchanged. ## Deployment Notes - [x] No special deployment steps required Vendored content only; consumers pick up the new spec on their next `git pull --ff-only` (driven by `bin/check-update`). ## 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 (CI: markdownlint + shellcheck pass) - [x] No new warnings or errors introduced - [x] Changes are backward compatible
brettdavies
added a commit
that referenced
this pull request
Apr 29, 2026
…oring (#11) ## Summary Two coordinated cleanups to `scripts/sync-spec.sh` and surrounding docs: 1. **Drop the SHA-pin model.** Eliminates all SHA-pin claims and the `SPEC_REF` override surface. After this PR merges, `rg` for any of `SHA`, `sha-pin`, `commit sha`, `source.commit`, `install.json`, `re-pin`, `SPEC_REF`, `pin`, `pinned`, `pinning` across shipping content (excluding `docs/plans/`, license boilerplate, and `CHANGELOG.md` / `spec/CHANGELOG.md`) returns **zero** matches. 2. **Remote-first vendoring with local fallback.** `sync-spec.sh` queries the upstream remote for the latest `v*` tag first; only falls back to a local `SPEC_ROOT` checkout when the remote is unreachable. Removes the manual `git fetch --tags` step from the happy path; works in fresh environments without a pre-existing local clone. ## Changelog ### Changed - `scripts/sync-spec.sh`: - **No longer accepts `SPEC_REF`.** Always vendors the latest `v*` tag. - **Resolution path:** queries `SPEC_REMOTE_URL` (default `https://github.com/brettdavies/agentnative.git`) via `git ls-remote --tags --sort=-version:refname`, picks the latest `v*`, then shallow-clones that tag into a temp directory for extraction. On any remote failure, falls back to the existing `SPEC_ROOT`-based logic (default `$HOME/dev/agentnative-spec`). - **New env var `SPEC_REMOTE_URL`** for overriding the remote. - **Temp clone is auto-cleaned** on script exit via trap. ### Removed - All SHA-pin claims from public-facing markdown (`RELEASES.md`, `AGENTS.md`, `README.md`, `spec/README.md`, `CONTRIBUTING.md`): pipeline diagram's "site re-pins to commit SHA" step, the post-merge "site re-pins via its own PR" step, the `protect-tags.json` / `install endpoints` claims that tags are pinned to install endpoints, and the spec-vendor "pinned ref" / "pinned `SPEC_REF`" / "current pin is recorded" vocabulary across all docs. ### Documentation - `AGENTS.md` `## Spec sync` section: rewritten — single-step recipe (`scripts/sync-spec.sh` then review); notes the remote-first / local-fallback behavior and the `SPEC_REMOTE_URL` / `SPEC_ROOT` overrides. Commit-message example uses `<version>` placeholder instead of a hard-coded version. - `spec/README.md` `## Resync` section: rewritten similarly; drops the manually-maintained `**Current snapshot:**` line and points readers at `spec/VERSION` (which `sync-spec.sh` writes verbatim from upstream). - `RELEASES.md` post-merge sequence ends at the GitHub Release; replaces deleted step 5 with a one-liner pointing consumers at `bin/check-update`. ## Type of Change - [x] `chore`: Maintenance tasks (dependencies, config, etc.) - [x] `docs`: Documentation update ## Related Issues/Stories - Architecture: `docs/plans/2026-04-28-001-feat-update-check-mechanism-plan.md` U6 (retroactive plan-doc + repo SHA-pin scrub) — partial. Plan files themselves are not scrubbed in this PR (they are dev-only and contain the historical record of the SHA-pin removal effort). - Related PRs: PR #10 (spec re-vendor v0.3.0) — touches different `RELEASES.md` hunks; no conflict expected at merge. - Mirror: `agentnative-cli/scripts/sync-spec.sh` is the documented mirror of this script. Lockstep update PR will land there as a separate change. ## Testing - [x] Manual testing completed - [x] All tests passing **Test Summary:** - `markdownlint-cli2` clean on all touched files (PostToolUse hook ran on each edit). - `shellcheck --severity=style scripts/sync-spec.sh`: clean. - `bash -n scripts/sync-spec.sh`: clean. - **Remote-success path** verified live: queried `https://github.com/brettdavies/agentnative.git`, resolved `v0.3.0`, shallow-cloned, vendored 7 principles + VERSION + CHANGELOG.md. Output: `vendoring v0.3.0 (5cea8bf) from remote https://github.com/brettdavies/agentnative.git`. - **Remote-fail-local-success path** verified by setting `SPEC_REMOTE_URL=https://github.com/brettdavies/does-not-exist.git`. Output: `warning: remote query failed; falling back to local /home/brett/dev/agentnative-spec` followed by successful vendor from local. - **Both-fail path** verified by setting both bogus remote and bogus `SPEC_ROOT=/tmp/no-such-dir`. Output: `error: remote unreachable and SPEC_ROOT is not a git repository: /tmp/no-such-dir` with both URL and path printed for debugging. - Final grep across shipping content for the full pin-vocabulary regex: **zero** matches. ## Follow-ups (not blocking this PR) - `agentnative-cli/scripts/sync-spec.sh` is documented as a mirror of this script (only `DEST_DIR` differs). Lockstep PR coming in that repo to apply the same modernization. - `agentnative-site` does not yet have a `sync-spec.sh` (only a plan doc). When that script lands per `docs/plans/2026-04-23-001-feat-sync-spec-plan.md`, it should adopt the same remote-first / no-SPEC_REF shape. - Plan files under `docs/plans/` retain SHA-pin language as historical record. If a future cleanup pass wants to scrub them too, that's a separate dev-only PR.
brettdavies
added a commit
that referenced
this pull request
Apr 29, 2026
Bump VERSION to 0.2.0 and regenerate CHANGELOG via scripts/generate-changelog.sh against the cherry-picked PRs (#1, #2, #3, #4, #6, #7, #8, #9, #10, #11, #13). PR bodies were audited by parallel subagents against .github/pull_request_template.md before this regen. PR #13 added CHANGELOG.md to .markdownlint-cli2.yaml ignores so the generated long-line bullets no longer trip MD013 on the release CI run. Squash-merge of release/v0.2.0 onto main becomes the v0.2.0 anchor.
brettdavies
added a commit
that referenced
this pull request
Apr 29, 2026
## Summary First public release of the `agent-native-cli` skill bundle (`agentnative-skill` repo). Establishes the canonical brettdavies cherry-pick release pattern (`feature → dev → release/* → main`), ships the flat install layout consumers will pull via plain `git clone`, and lands the consumer-side update-check mechanism that replaces the deprecated `install.json` SHA-pin advisory. Cherry-picks 10 dev PRs (#1–#4, #6–#11, #13) onto `origin/main` plus three direct-to-release-branch fixup commits (`9f6e276`, `23e1a76` from the bootstrap window) and the curated `chore(release): v0.2.0` commit. PR #5 (docs-only public-flip follow-up) stayed on `dev` per the cherry-pick rule. The original in-cherry-pick spec re-vendor (`837ab9a` → `1640460`) was converted to a real PR (#10) so the v0.2.0 CHANGELOG carries a curated bullet for the spec v0.2.0 → v0.3.0 bump. PR-body template alignment was audited by parallel subagents before this regeneration — empty stubs removed, missing template sections added, internal-detail bullets moved out of `## Changelog`, PR #11's nested sub-bullets flattened. ## Changelog ### Added - Version-controlled GitHub repository rulesets for `main`, `dev`, and release tags (`v*`). Apply procedure documented in `.github/rulesets/README.md`. by @brettdavies in #1 - `AGENTS.md` (root) describing the bundle layout, lint commands, branch model, and hard rules for agents. by @brettdavies in #2 - `RELEASES.md` (root) documenting a release procedure for this repo (later rewritten in #3 to the canonical full `release/*` pattern). - `.github/pull_request_template.md` (canonical PR template). - `.github/workflows/guard-main-docs.yml` caller for the `brettdavies/.github` reusable workflow that blocks `docs/plans/`, `docs/solutions/`, `docs/brainstorms/`, `docs/reviews/` from PRs targeting `main`. - `cliff.toml` — git-cliff configuration mirroring sibling repos. by @brettdavies in #3 - `scripts/generate-changelog.sh` — release-time CHANGELOG generator. Reads PR-body `## Changelog` sections and prepends a curated, attributed `[X.Y.Z]` section. Authoritative; never hand-edit `CHANGELOG.md`. - `CONTRIBUTING.md` — how to propose changes, link to release procedure. - `.github/ISSUE_TEMPLATE/bug_report.md` + `bundle_proposal.md` (replaces `principle_proposal.md` with corrected routing). - Vendored `spec/` tree from `agentnative-spec` — `VERSION`, `CHANGELOG.md`, `README.md`, and seven `principles/p*.md` files with machine-readable `requirements[]` frontmatter. The skill points at this canonical text instead of paraphrasing. by @brettdavies in #4 - `getting-started.md` covering three working agent loops (existing CLI / new Rust / other language), canonical `anc check --output json` invocations, and a "where things live" map. - `scripts/sync-spec.sh` for re-vendoring `agentnative-spec` on demand. - `LICENSE-APACHE` — dual-license under MIT or Apache-2.0 (consumer's choice). by @brettdavies in #6 - `bin/check-update` — gstack-style consumer-side update-check. Compares the installed `VERSION` against the producer repo's `main`, emits `UPGRADE_AVAILABLE <local> <remote>`, with cache TTL (60 min UP_TO_DATE / 720 min UPGRADE_AVAILABLE) and 3-level snooze (24h / 48h / 7d). State directory: `$HOME/.cache/agent-native-cli/`. by @brettdavies in #8 - `SKILL.md` `## Update check` section documenting the script's invocation and the `AskUserQuestion`-driven upgrade flow. ### Changed - **BREAKING (install layout):** Skill content lives at the repo root (`SKILL.md`, `bin/`, `spec/`, `references/`, `templates/`, `VERSION`). Plain `git clone --depth 1` and `git pull --ff-only` are the load-bearing install + update commands; no sparse-checkout magic, no post-install scripts. by @brettdavies in #9 (final flat shape; intermediate `bundle/` indirection from #3 reverted before launch). - License changed from MIT-only to dual MIT or Apache-2.0 (no MIT compatibility regression). by @brettdavies in #6 - Documentation now points at `https://anc.dev/skill` instead of `https://anc.dev/install`. by @brettdavies in #7 - Spec content vendored under `spec/` re-vendored from `agentnative-spec` v0.2.0 to v0.3.0. All 7 principles flip `status: draft` → `status: active`; prose tightened across P1–P7 from upstream's G11 red-team pass. No requirement IDs added/removed/renamed; no level changes. by @brettdavies in #10 - `scripts/sync-spec.sh` no longer accepts `SPEC_REF`. The script always vendors the latest `v*` tag, queried from `SPEC_REMOTE_URL` (default `https://github.com/brettdavies/agentnative.git`) via `git ls-remote --tags --sort=-version:refname` and shallow-cloned for extraction. On any remote failure, falls back to the existing `SPEC_ROOT`-based logic (default `$HOME/dev/agentnative-spec`). New env var `SPEC_REMOTE_URL` overrides the remote; the temp clone is auto-cleaned on script exit via trap. by @brettdavies in #11 ### Fixed - Harden `bin/check-update` against malformed local `VERSION` (apply SemVer regex; malformed → silent exit) and against curl failure being cached as UP_TO_DATE (skip cache write on network failure so the next invocation retries). by @brettdavies in #8 - Align table pipes in `SKILL.md` and `getting-started.md` (markdownlint MD060). by @brettdavies in #9 ### Documentation - `README.md` — License section rewritten to reflect dual licensing and link both LICENSE files; tree row updated. by @brettdavies in #6 - `CONTRIBUTING.md` — License section rewritten: contributions are dual-licensed at the consumer's option, no CLA, with an explicit pointer to the Apache §3 patent grant. - - `.markdownlint-cli2.yaml` excludes `CHANGELOG.md` from linting (matches the existing exclusion for `spec/CHANGELOG.md`). Aligns lint behavior with the `scripts/generate-changelog.sh` regen flow. by @brettdavies in #13 - All public-facing markdown (`RELEASES.md`, `AGENTS.md`, `README.md`, `spec/README.md`, `CONTRIBUTING.md`) scrubbed of SHA-pin model vocabulary: pipeline diagram's "site re-pins to commit SHA" step, the post-merge "site re-pins via its own PR" step, the `protect-tags.json` / `install endpoints` claims that tags are pinned to install endpoints, and the spec-vendor "pinned ref" / "pinned `SPEC_REF`" / "current pin is recorded" vocabulary across all docs. The new model is plain `git clone` + `bin/check-update` for staleness; nothing pins to anything cross-repo. by @brettdavies in #11 ### Removed - `bundle/scripts/check-compliance.sh` and 24 `bundle/scripts/checks/check-*.sh` files (plus `_helpers.sh`). `anc check --output json` is the canonical replacement. by @brettdavies in #4 - `bundle/references/principles-deep-dive.md` (419-line hand-typed paraphrase of the spec; canonical text now lives at `spec/principles/`). - `.github/ISSUE_TEMPLATE/principle_proposal.md` (replaced by `bundle_proposal.md` with corrected routing). - `.shellcheckrc` (its three disables targeted the deleted bundle scripts; producer scripts pass shellcheck unmodified). ## Type of Change - [x] `chore`: Maintenance tasks (release engineering) - [x] `BREAKING CHANGE`: Install layout changes (no v0.1.0 consumers exist; see Breaking Changes section) ## Related Issues/Stories - Architecture: `docs/plans/2026-04-27-001-bootstrap-agentnative-skill-plan.md` — bootstrap plan (task #15: launch-eve cherry-pick + admin-bypass decision recorded `2026-04-28`). - Architecture: `docs/plans/2026-04-28-001-feat-update-check-mechanism-plan.md` — update-check mechanism plan (drove PR #8 + the SHA-pin removal across PR #11 / repo docs). - Cross-repo: `agentnative-cli` — `scripts/sync-spec.sh` is the documented mirror; lockstep modernization is being driven in a parallel session. - Cross-repo: `agentnative-site` — installs this skill via `https://anc.dev/skill`; the `install.json` SHA-pin advisory is being removed in that repo (separate PR there) per the update-check plan's downstream coordination. ## Testing - [x] Manual testing completed - [x] All tests passing (CI: markdownlint + shellcheck on every cherry-picked commit) **Test Summary:** - `markdownlint-cli2` clean across the cherry-pick chain (PostToolUse hook ran on every edit; CI re-verified each PR). - `shellcheck --severity=style scripts/sync-spec.sh bin/check-update`: clean. - `bash -n scripts/sync-spec.sh bin/check-update`: clean. - `bin/check-update` 40-test battery (PR #8): 40 pass / 0 fail (unit + integration + e2e + red-team). - `scripts/sync-spec.sh` remote-success path verified live: queried `https://github.com/brettdavies/agentnative.git`, resolved `v0.3.0`, shallow-cloned, vendored 7 principles + VERSION + CHANGELOG. Remote-fail-local-success path verified by setting bogus `SPEC_REMOTE_URL` (warning + fallback to `$HOME/dev/agentnative-spec`). Both-fail path verified with bogus URL + bogus `SPEC_ROOT` (hard error with both printed). - Vocabulary check: `rg` for `SHA-pin` / `commit SHA` / `source.commit` / `install.json` / `re-pin` / `SPEC_REF` / `pin` / `pinned` / `pinning` across shipping content (excluding `docs/plans/`, license boilerplate, changelogs, vendored `spec/principles/`): **zero** matches. - PR-body template alignment: parallel audit subagents reported `verified=true` for PRs #1–#11. ## Files Modified **Cherry-picked from dev (squash commits):** - `8be19e6` — feat(bundle): consumer-side update-check mechanism (U1+U2) [#8] - `34b1da3` — refactor!: flatten bundle/* to repo root for plain git-clone install [#9] - `4461806` — chore(spec): re-vendor spec/ to v0.3.0 + RELEASES spec-revendor section [#10] - `fb50d18` — chore(sync-spec): drop SHA-pin claims, modernize to remote-first vendoring [#11] - `e67523e` — chore(lint): exclude CHANGELOG.md from markdownlint [#13] (added during release prep to unblock MD013 on the rich generated CHANGELOG) **Direct-to-release-branch fixup commits (bootstrap window):** - `9f6e276` — chore(rulesets): drop `.github/rulesets/README.md` - `23e1a76` — docs(bundle): trim trailing platform comment on `cargo install` line **Curated release commit:** - `d66d5bd` — chore(release): v0.2.0 (VERSION bump + regenerated CHANGELOG.md) **Plus PRs #1–#7 cherry-picked earlier in the bootstrap window:** rulesets (#1), AGENTS/PR-template/RELEASES scaffold (#2), bundle restructure + cliff.toml (#3), spec vendoring + skill pivot (#4), dual licensing (#6), `/skill` endpoint rename (#7). ## Breaking Changes - [x] Breaking changes described below **Install layout (PR #4 + PR #9):** the skill bundle's directory shape went from a paraphrased pre-anc layout (v0.1.0) → `bundle/` subdirectory (PR #3) → flat root (PR #9). The flat root is the load-bearing final shape: `git clone --depth 1` lands `SKILL.md` at the install root where Claude Code, Codex, Cursor, and OpenCode auto-discover it. **No real-world migration impact:** v0.1.0 has zero installed consumers (the install endpoint at `https://anc.dev/skill` is gated by this very release). The breaking-change classification is for SemVer hygiene, not user-impacting. **Bundle surface contract (PR #4):** the skill no longer ships shell-script compliance checks (`bundle/scripts/check-compliance.sh` + 24 `check-*.sh` files). `anc check --output json` is the canonical replacement; downstream tools that scraped the old shell scripts must migrate to `anc`. ## Deployment Notes - [x] Deployment steps documented below **Pre-merge admin-bypass (one-time):** the `protect-main` ruleset requires `markdownlint`, `shellcheck`, and `guard-docs / check-forbidden-docs` as required status checks. The third comes from `guard-main-docs.yml`, which only exists on `dev` (it's part of this very release). For the FIRST release PR, GitHub evaluates `pull_request` workflows from `main` (the base), so the guard-docs check cannot run. Resolution: admin-bypass this single PR via the existing `bypass_actors` on `protect-main` (`actor_type: RepositoryRole, actor_id: 5, bypass_mode: always`). One-off; subsequent releases run cleanly. See bootstrap plan §15 (decision recorded `2026-04-28`). **Post-merge sequence (per RELEASES.md):** 1. Tag the squash commit on `main`: ```bash git checkout main && git pull git tag -a v0.2.0 -m "v0.2.0" git push origin v0.2.0 ``` 2. Create the GitHub Release with the v0.2.0 CHANGELOG section as notes: ```bash gh release create v0.2.0 --title "v0.2.0" \ --notes "$(awk '/^## \[0\.2\.0\]/{flag=1; next} /^## \[/{flag=0} flag' CHANGELOG.md)" ``` 3. Consumers detect the new release on their next `bin/check-update` run; no site-side coordination step (the SHA-pin model is gone, per #11). ## 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 (CI green on every cherry-picked commit) - [x] No new warnings or errors introduced - [x] Changes are backward compatible (or breaking changes documented in Breaking Changes section) ## Additional Context - Full v0.2.0 entry in [`CHANGELOG.md`](./CHANGELOG.md) (this section is a copy; CHANGELOG.md is canonical). - The PR-body audit run produced template-aligned bodies for all 11 merged PRs; CHANGELOG.md was regenerated from the audited bodies before this PR opened.
brettdavies
added a commit
that referenced
this pull request
Apr 29, 2026
Bootstrap plan (2026-04-27-001): - Task #15 (v0.2.0 release) flipped to checked. Step 3a complete via PR #12 squash-merge to main 2026-04-29 ~16:38 PT (commit 2b10c84). Step 3b (tag + GitHub Release) still pending; commands documented in PR #12 body's Deployment Notes. - Added an "Executed scope (2026-04-29)" addendum capturing the three axes the launch-eve plan diverged on: (a) in-cherry-pick spec re-vendor was converted to a real PR (#10) so the v0.2.0 CHANGELOG carries a curated bullet for the spec bump; (b) two extra PRs added to launch-wave scope mid-execution — PR #11 (SHA-pin scrub + sync-spec.sh modernization) and PR #13 (CHANGELOG.md markdownlint exclusion); (c) the launch-eve admin-bypass concern was pessimistic — guard-docs check ran cleanly from PR head, no bypass needed. - Final cherry-pick chain table appended for the historical record. Update-check mechanism plan (2026-04-28-001) — first commit of this plan to dev: - U1 (bin/check-update script) flipped to done via PR #8. - U2 (SKILL.md preamble + bundle-doc pin-vocab drop) flipped to done via PR #8; broader pin-vocab scrub across RELEASES/AGENTS/README/ CONTRIBUTING/spec/README shipped via PR #11 (added mid-flight to launch-wave scope per U6). - U6 (retroactive scrub) flipped to done for skill scope: PR #11 handled the skill-side cleanup; bootstrap plan task #15 + central tracker (gstack file, separate edit) updated 2026-04-29. Site-side scrubs (U3-U5 + agentnative-site cross-repo-canonical-pointer.md) still pending in the user's parallel session. - U3-U5 remain unchecked — agentnative-site scope, parallel session. The central launch tracker (~/.gstack/projects/brettdavies-agentnative/brett-dev-design-show-hn- launch-inversion-20260427-144756.md) was updated in parallel to: - Mark step 3a done (PR #12 squash 2b10c84) and step 3b pending. - Drop SHA-pin re-pin claims from steps 4 + 5 + the launch-day timeline + the per-repo plan table + the dev-status block (per U6 scrub instructions). Replaced with references to bin/check-update (PR #8) and a note that source.commit is being removed from skill.json in agentnative-site U3 (parallel session). - Step 4 retains the install.json -> skill.json file-rename context from PR #44 since that's still in scope for the site cherry-pick. That tracker is not a git-repo file, so the edits land directly on disk; this commit only touches the two plan files in this repo.
11 tasks
brettdavies
added a commit
to brettdavies/agentnative-site
that referenced
this pull request
May 1, 2026
## Summary Removes the dead SHA-pin enforcement surface for the `agent-native-cli` skill. The pin was deprecated upstream in [`agentnative-skill` PR #11](brettdavies/agentnative-skill#11) (2026-04-29) when update detection moved to the skill bundle's `bin/check-update` (compares the local bundle's `VERSION` against `main` on GitHub). The site repo carried the full enforcement surface — manifest fields, build validation, schema docs, release runbook, tests, e2e probe, prose — as dead ceremony that surfaced on every skill release as a SHA bump that no longer carried a contract. Audit assertion: across shipping content (excluding `docs/plans/`, `docs/brainstorms/`, `docs/reviews/`, `docs/solutions/`, `CHANGELOG.md`), zero matches remain for `source.commit`, `verify.expected`, `COMMIT_RE`, `47a76cce…`, `re-pin`, `pinned commit`, `pinned at commit`, or `commit pin`. The four surviving SHA references in shipping content are unrelated domains (scorecard `anc.commit` rendering, font supply chain, CLI registry version parsing) and intentionally untouched. ## Changelog ### Removed - Skill SHA-pin fields (`source.commit`, `verify` block) and their build-time enforcement. ### Changed - Skill-release procedure no longer requires a manifest re-pin; updates are detected by the skill bundle's `bin/check-update` against `main` on GitHub. ## Type of Change - [x] `chore`: Maintenance tasks (dependencies, config, etc.) ## Related Issues/Stories - Story: n/a - Issue: n/a - Architecture: agentnative-skill PR #11 (the upstream deprecation that this site-side PR completes) - Related PRs: #66 (\`fix/scorecard-anc-render\` — sibling cleanup, same theme of removing dead SHA-pin ceremony) ## Testing - [x] Unit tests added/updated - [x] All tests passing **Test Summary:** - 203/203 unit + regression tests pass (4 SHA-pin-specific assertions deleted; no new failures) - \`bun run build\` clean - E2E \`skill\` Playwright project structurally untouched — the two pin-freshness checks (HEAD == \`source.commit\`, remote-HEAD == \`source.commit\`) are dropped; the install-clone-lands-\`SKILL.md\` check stays ## Files Modified **Modified:** - \`src/data/skill.json\` — \`source.commit\` and \`verify\` object removed - \`src/build/skill.mjs\` — \`COMMIT_RE\`, verify validation, \`REQUIRED_VERIFY\` list, "pinned at commit" prose, \`## Verify\` markdown section all removed - \`docs/DESIGN.md\` §3.9 — schema-table rows for \`source.commit\` and \`verify.*\` removed; build-validation prose, source-repo-coupling paragraph, release runbook bullet updated - \`RELEASES.md\` §"Skill releases" — re-pin step rewritten as conditional manifest bump - \`scripts/SYNCS.md\` — re-pin language scrubbed from the skill-release flow + reference list - \`tests/build.test.ts\` — non-hex / uppercase-hex commit rejection tests + \`source.commit\` / \`verify\` fixture fields removed - \`tests/regression.test.ts\` — \`source.commit\` / \`verify.expected\` invariants removed; required-keys list updated - \`tests/e2e/skill.e2e.ts\` — pin-freshness checks dropped (HEAD == \`source.commit\` and remote-HEAD == \`source.commit\`) **Created:** None. **Renamed:** None. **Deleted:** None. ## Key Features n/a — pure removal of dead enforcement surface. ## Benefits - **Dead-ceremony reduction**: skill releases no longer think about a SHA bump that doesn't carry a contract. - **Schema-render coherence**: \`/skill.json\`'s shape now matches the documented update model (\`bin/check-update\` against \`main\`). - **Release-runbook simplification**: \`RELEASES.md\` skill-release procedure becomes a conditional manifest bump rather than a mandatory re-pin step. ## Breaking Changes - [x] No breaking changes (consumer-side) \`agentnative-cli\`'s \`src/skill_install/skill.json\` fixture pulls \`src/data/skill.json\` from this repo. The shape change here will surface in CLI's \`skill-fixture-drift\` workflow on its next PR — coordinated CLI-side update should land in lockstep. ## Deployment Notes - [x] No special deployment steps required After deploy, \`https://anc.dev/skill.json\` will lose \`source.commit\` and the \`verify\` object. The \`schema_version: 1\` field stays — agents reading the JSON should already tolerate field removal within v1 since the schema doc described \`verify.expected\` as advisory only. ## 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 (consumer-side; cross-repo coordination noted above) ## Additional Context This PR ships in parallel with #66 (\`fix/scorecard-anc-render\`) — sibling cleanup of skill-shaped SHA-pin ceremony that lived in the scorecard render. The two branches were cut independently to keep concerns tight; either can land first.
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
Two coordinated cleanups to
scripts/sync-spec.shand surrounding docs:Drop the SHA-pin model. Eliminates all SHA-pin claims and the
SPEC_REFoverride surface. After this PR merges,rgfor any ofSHA,sha-pin,commit sha,source.commit,install.json,re-pin,SPEC_REF,pin,pinned,pinningacross shipping content (excludingdocs/plans/, license boilerplate, andCHANGELOG.md/spec/CHANGELOG.md) returns zero matches.Remote-first vendoring with local fallback.
sync-spec.shqueries the upstream remote for the latestv*tagfirst; only falls back to a local
SPEC_ROOTcheckout when the remote is unreachable. Removes the manualgit fetch --tagsstep from the happy path; works in fresh environments without a pre-existing local clone.Changelog
Changed
scripts/sync-spec.shno longer acceptsSPEC_REF. The script always vendors the latestv*tag, queried fromSPEC_REMOTE_URL(defaulthttps://github.com/brettdavies/agentnative.git) viagit ls-remote --tags --sort=-version:refnameand shallow-cloned for extraction. On any remote failure, falls back to the existingSPEC_ROOT-based logic (default$HOME/dev/agentnative-spec). New env varSPEC_REMOTE_URLoverrides the remote; the temp clone is auto-cleaned on script exit via trap.Removed
RELEASES.md,AGENTS.md,README.md,spec/README.md,CONTRIBUTING.md): pipeline diagram's "site re-pins to commit SHA" step, the post-merge "site re-pins via its ownPR" step, the
protect-tags.json/install endpointsclaims that tags are pinned to install endpoints, and thespec-vendor "pinned ref" / "pinned
SPEC_REF" / "current pin is recorded" vocabulary across all docs.Documentation
AGENTS.md## Spec syncsection: rewritten — single-step recipe (scripts/sync-spec.shthen review); notes theremote-first / local-fallback behavior and the
SPEC_REMOTE_URL/SPEC_ROOToverrides. Commit-message example uses<version>placeholder instead of a hard-coded version.spec/README.md## Resyncsection: rewritten similarly; drops the manually-maintained**Current snapshot:**line and points readers at
spec/VERSION(whichsync-spec.shwrites verbatim from upstream).RELEASES.mdpost-merge sequence ends at the GitHub Release; replaces deleted step 5 with a one-liner pointingconsumers at
bin/check-update.Type of Change
chore: Maintenance tasks (dependencies, config, etc.)docs: Documentation updateRelated Issues/Stories
docs/plans/2026-04-28-001-feat-update-check-mechanism-plan.mdU6 (retroactive plan-doc + repo SHA-pin scrub) — partial. Plan files themselves are not scrubbed in this PR (they are dev-only and contain the historical record of the SHA-pin removal effort).RELEASES.mdhunks; no conflict expected at merge.agentnative-cli/scripts/sync-spec.shis the documented mirror of this script. Lockstep update PR will land there as a separate change.Testing
Test Summary:
markdownlint-cli2clean on all touched files (PostToolUse hook ran on each edit).shellcheck --severity=style scripts/sync-spec.sh: clean.bash -n scripts/sync-spec.sh: clean.https://github.com/brettdavies/agentnative.git, resolvedv0.3.0,shallow-cloned, vendored 7 principles + VERSION + CHANGELOG.md. Output:
vendoring v0.3.0 (5cea8bf) from remote https://github.com/brettdavies/agentnative.git.SPEC_REMOTE_URL=https://github.com/brettdavies/does-not-exist.git. Output:warning: remote query failed; falling back to local /home/brett/dev/agentnative-specfollowed by successful vendor from local.SPEC_ROOT=/tmp/no-such-dir. Output:error: remote unreachable and SPEC_ROOT is not a git repository: /tmp/no-such-dirwith both URL and path printed for debugging.Files Modified
Modified:
scripts/sync-spec.sh— remote-first resolution,SPEC_REMOTE_URLsupport, temp-clone cleanup trap,SPEC_REFremoved.AGENTS.md—## Spec syncsection rewritten.spec/README.md—## Resyncsection rewritten;**Current snapshot:**line dropped.RELEASES.md— pipeline diagram and post-merge sequence updated; SHA-pin step replaced withbin/check-updatepointer.README.md— SHA-pin claims removed.CONTRIBUTING.md— SHA-pin claims removed.Breaking Changes
SPEC_REFwas an undocumented override surface; removing it is a contract cleanup, not a breaking change for any documented workflow. Default behavior (no env vars set) is strictly improved: works in fresh environments without a pre-existing local clone.Deployment Notes
Script + docs only. Next time a contributor runs
scripts/sync-spec.sh, it will use the new remote-first path automatically.Checklist
Follow-ups (not blocking this PR)
agentnative-cli/scripts/sync-spec.shis documented as a mirror of this script (onlyDEST_DIRdiffers). Lockstep PR coming in that repo to apply the same modernization.agentnative-sitedoes not yet have async-spec.sh(only a plan doc). When that script lands perdocs/plans/2026-04-23-001-feat-sync-spec-plan.md, it should adopt the same remote-first / no-SPEC_REF shape.docs/plans/retain SHA-pin language as historical record. If a future cleanup pass wants to scrub them too, that's a separate dev-only PR.