chore(lint): exclude CHANGELOG.md from markdownlint#13
Merged
Conversation
CHANGELOG.md is a generated artifact (scripts/generate-changelog.sh writes single-line bullets per PR; one bullet often exceeds the 120-char MD013 line-length limit because PR-body content is dense). Wrapping those lines would conflict with the generator on every regen. Mirrors the existing exclusion for spec/CHANGELOG.md (also a generated or vendored artifact). Both files share the same exclusion rationale: content is authored elsewhere, lint rules don't apply at this layer. Surfaced when the v0.2.0 release CHANGELOG (rich PR-body bullets across 9 cherry-picked PRs after the parallel PR-body audit) tripped MD013 on the release/v0.2.0 -> main CI run.
brettdavies
added a commit
that referenced
this pull request
Apr 29, 2026
## Summary `CHANGELOG.md` is a generated artifact — `scripts/generate-changelog.sh` writes single-line bullets per PR, and rich PR-body bullets routinely exceed the 120-char MD013 line-length limit. Wrapping those lines would conflict with the generator on every regen. Mirrors the existing exclusion for `spec/CHANGELOG.md` (also generated / vendored). Same rationale: content is authored elsewhere, this repo's lint rules don't apply at this layer. Surfaced when the v0.2.0 release CHANGELOG (9 cherry-picked PRs' worth of curated bullets after the parallel PR-body audit) tripped MD013 on the `release/v0.2.0` → `main` CI run. ## Changelog ### Changed - `.markdownlint-cli2.yaml` excludes `CHANGELOG.md` from linting. Aligns its treatment with `spec/CHANGELOG.md` and reflects that the file is regenerated by `scripts/generate-changelog.sh`, not hand-edited. Per-line content is governed by PR-body bullets in source PRs, not by this repo's MD013 line-length rule. ## Type of Change - [x] `chore`: Maintenance tasks (config) ## Related Issues/Stories - Related PRs: gates `release/v0.2.0` → `main` (PR #12). The v0.2.0 release CHANGELOG content is the trigger; without this lint exclusion, every release will trip MD013. ## Testing - [x] Manual testing completed - [x] All tests passing **Test Summary:** - `markdownlint-cli2 'CHANGELOG.md'` after the config change: `Linting: 0 file(s) / Summary: 0 error(s)` (file correctly excluded). - `markdownlint-cli2 '**/*.md'` (full repo): unchanged behavior on all other files. ## Files Modified **Modified:** - `.markdownlint-cli2.yaml` — added `- "CHANGELOG.md"` to ignores list with a comment explaining the rationale. ## Breaking Changes - [x] No breaking changes Lint config tweak only; no shipping content affected. ## 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
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.
12 tasks
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.
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
CHANGELOG.mdis a generated artifact —scripts/generate-changelog.shwrites single-line bullets per PR, and richPR-body bullets routinely exceed the 120-char MD013 line-length limit. Wrapping those lines would conflict with the
generator on every regen.
Mirrors the existing exclusion for
spec/CHANGELOG.md(also generated / vendored). Same rationale: content is authoredelsewhere, this repo's lint rules don't apply at this layer.
Surfaced when the v0.2.0 release CHANGELOG (9 cherry-picked PRs' worth of curated bullets after the parallel PR-body
audit) tripped MD013 on the
release/v0.2.0→mainCI run.Changelog
Changed
.markdownlint-cli2.yamlexcludesCHANGELOG.mdfrom linting. Aligns its treatment withspec/CHANGELOG.mdandreflects that the file is regenerated by
scripts/generate-changelog.sh, not hand-edited. Per-line content isgoverned by PR-body bullets in source PRs, not by this repo's MD013 line-length rule.
Type of Change
chore: Maintenance tasks (config)Related Issues/Stories
release/v0.2.0→main(PR release: v0.2.0 — agent-native CLI skill bundle public launch #12). The v0.2.0 release CHANGELOG content is the trigger; without this lint exclusion, every release will trip MD013.Testing
Test Summary:
markdownlint-cli2 'CHANGELOG.md'after the config change:Linting: 0 file(s) / Summary: 0 error(s)(file correctly excluded).markdownlint-cli2 '**/*.md'(full repo): unchanged behavior on all other files.Files Modified
Modified:
.markdownlint-cli2.yaml— added- "CHANGELOG.md"to ignores list with a comment explaining the rationale.Breaking Changes
Lint config tweak only; no shipping content affected.
Deployment Notes
Checklist