docs: prose cleanup across tracked docs and release-flow tooling fixes - #68
Merged
Merged
Conversation
…icts Adds a "Cherry-pick conflicts on guarded paths" subsection to RELEASES.md covering the standard resolution when cherry-picks of feature PRs that touched docs/plans/ / docs/brainstorms/ / etc. hit modify/delete or rename/delete conflicts on the release branch. Captures the two-step plumbing pattern (git update-index --remove + gio trash) since `git rm` is denied by repo policy, and the xargs/ alias gotcha that requires gio trash rather than the trash alias when batching. Surfaced during the release/v0.5.0 cut: PR #58 and PR #65 both triggered the pattern, the latter via rename detection on docs/plans/ spike files.
…ections Re-running ./scripts/generate-changelog.sh with the current CHANGELOG.md already containing a [vX.Y.Z] section caused git-cliff to prepend a second copy of the same section, producing an empty vX.Y.Z...vX.Y.Z compare link and a duplicate header. Surfaced during the v0.5.0 cut when the script was re-invoked after PR body edits. Adds a pre-flight grep against CHANGELOG.md for an existing section header matching the resolved TAG; if found, exit 1 with guidance to remove the existing section before re-running. Ported from the agentnative-spec copy of the same script.
Recasts 26 em-dashes across the v0.1.0 through v0.4.0 historical sections to match the unslop pass applied to the 64 PR bodies upstream. Per-occurrence judgment per the unslop recasting guide (colons for label-description, semicolons for independent clauses inside parens, periods for strong continuation, "which" for participial asides) rather than bucket substitution. Manual edit explicitly authorized as a one-time exception to the "hand-editing CHANGELOG.md produces drift the next regeneration overwrites" rule. The next regen will pull the now-clean PR bodies, so the historical sections stay consistent only as long as the script guard added in 285c25d prevents re-running on this version. unslop score: 3 -> 0 / verdict clean / em-dash count: 26 -> 0.
Sweeps em-dashes (U+2014) from the 11 tracked, consumer-facing markdown docs using per-occurrence judgment from the unslop recasting guide rather than bucket substitution. Total prose recasts: - CLAUDE.md: 50 - AGENTS.md: 32 - scripts/SYNCS.md: 28 (plus one list-structure repair) - README.md: 8 - PRODUCT.md: 13 - RELEASES-PREFLIGHT.md: 10 - RELEASES.md: 4 - RELEASES-RATIONALE.md: 2 - .github/pull_request_template.md: 5 - styles/brand/README.md: 4 - BRAND.md: 1 11 em-dashes remain across the file set, all inside fenced code blocks (masked by score.py: AGENTS.md bash, scripts/SYNCS.md mermaid, README.md text, RELEASES.md bash). Editing them would falsify sample output. styles/brand/README.md is generator-emitted; the fix is sustained by updating styles/brand/*.yml (the rule sources) and scripts/generate-pack-readme.mjs (the trailer + drift message). Drift check passes post-regen. Final state across all 11 docs: unslop score 0, verdict clean.
The trailer "<!-- Generated by anc emit coverage-matrix; do not edit by hand -->" is emitted by src/principles/matrix.rs and gets clobbered on every regen. Updates the writeln! template + the matching error strings in src/main.rs's --check failure branches (which mirrored the em-dash form) so future regenerations stay clean. Regenerates docs/coverage-matrix.md against the new template; drift check exits 0.
brettdavies
added a commit
that referenced
this pull request
May 31, 2026
#68) ## Summary Tightens prose across the 11 tracked markdown docs in the repo: `CLAUDE.md`, `AGENTS.md`, `scripts/SYNCS.md`, `README.md`, `PRODUCT.md`, `RELEASES-PREFLIGHT.md`, `RELEASES.md`, `RELEASES-RATIONALE.md`, `.github/pull_request_template.md`, `styles/brand/README.md`, and `BRAND.md`. Also applies a one-time prose pass to the historical sections of `CHANGELOG.md` (an explicit exception to the no-manual-edits rule, since the equivalent fix on upstream PR bodies has already shipped). Bundles three release-flow hygiene fixes that surfaced during the prose pass: 1. `scripts/generate-changelog.sh` now refuses to prepend a duplicate `[vX.Y.Z]` section when one already exists in `CHANGELOG.md`. Re-running with an already-published tag previously emitted a second copy of the same section and an empty `vX.Y.Z...vX.Y.Z` compare link. 2. `RELEASES.md` gains a "Cherry-pick conflicts on guarded paths" subsection documenting the `git update-index --remove` plus `gio trash` resolution pattern for modify/delete and rename/delete conflicts on `docs/plans/`, `docs/brainstorms/`, and `docs/ideation/` paths during release cherry-picks. Standard `git rm` is denied by repo policy; the plumbing form is the supported alternative. 3. `anc emit coverage-matrix` writes its generated trailer in a form that survives the prose-check pipeline; the matching `--check` failure message in `src/main.rs` uses the same form. `styles/brand/README.md` is generator-emitted, so the fix is sustained by updating the `styles/brand/*.yml` rule sources and the `scripts/generate-pack-readme.mjs` trailer. Future regenerations stay clean. ## Changelog ### Changed - Tightened prose across all 11 tracked markdown docs in the repo plus historical sections of `CHANGELOG.md`. Each occurrence of a recurring punctuation pattern was replaced with the alternative best matching the local context (colon, semicolon, period, comma, or a small rewording). - `anc emit coverage-matrix` writes the trailer as `<!-- Generated by `anc emit coverage-matrix`; do not edit by hand -->`; the `--check` failure message in `src/main.rs` uses the same form. - `styles/brand/README.md` regenerated against tightened `styles/brand/*.yml` rule sources and updated `scripts/generate-pack-readme.mjs` trailer so the drift check stays clean on future regenerations. ### Fixed - `scripts/generate-changelog.sh` now refuses to prepend a duplicate `[X.Y.Z]` section when one already exists in `CHANGELOG.md`. Re-running the script with an already-published tag previously emitted a second copy of the same section and an empty `vX.Y.Z...vX.Y.Z` compare link. ### Documentation - `RELEASES.md` gains a "Cherry-pick conflicts on guarded paths" subsection documenting the `git update-index --remove` plus `gio trash` resolution pattern for modify/delete and rename/delete conflicts on `docs/plans/`, `docs/brainstorms/`, and `docs/ideation/` paths during release cherry-picks. Standard `git rm` is denied by repo policy; the plumbing form is the supported alternative. ## Type of Change - [x] `docs`: Documentation update ## Related Issues/Stories - Story: n/a - Issue: n/a - Architecture: Cross-repo prose cleanup ahead of the v0.5.0 release; mirrored as cherry-pick onto the release branch after this PR merges. - Related PRs: n/a ## Testing - [x] All tests passing **Test Summary:** - `cargo test`: 793 passed, 2 ignored - `anc emit coverage-matrix --check`: exit 0 (no drift) - `bun scripts/generate-pack-readme.mjs --check`: exit 0 (no drift) ## Files Modified **Modified:** - `AGENTS.md`, `BRAND.md`, `CHANGELOG.md`, `CLAUDE.md`, `PRODUCT.md`, `README.md`, `RELEASES-PREFLIGHT.md`, `RELEASES-RATIONALE.md`, `RELEASES.md`, `.github/pull_request_template.md`, `scripts/SYNCS.md`, `styles/brand/README.md` - `styles/brand/FillerAdjectives.yml`, `styles/brand/HedgeWords.yml`, `styles/brand/MarketingRegister.yml`, `scripts/generate-pack-readme.mjs` (sustains the `styles/brand/README.md` fix across regen) - `scripts/generate-changelog.sh` (duplicate-section guard) - `src/main.rs`, `src/principles/matrix.rs`, `docs/coverage-matrix.md` (matrix trailer at the source) **Created:** - None. **Renamed:** - None. **Deleted:** - None. ## Breaking Changes - [x] No breaking changes ## Deployment Notes - [x] No special deployment steps required
brettdavies
added a commit
that referenced
this pull request
Jun 1, 2026
The original v0.5.0 CHANGELOG section was generated before the hierarchical noun-verb consistent-naming fix (PR #73) was cherry-picked onto the release branch. Regenerated to include the new bullet plus a couple of others (#68, #69, #71 cherry-picks) that landed between the first generation and now. Side-effect: the section header date moves 2026-05-31 -> 2026-06-01 since git-cliff uses the regeneration date. The tag will publish today; the new date matches the actual release date.
brettdavies
added a commit
that referenced
this pull request
Jun 1, 2026
## Summary `v0.5.0` of `anc`. Vendored `agentnative-spec` advances `0.4.0` → `0.5.0`. Scorecard JSON schema advances `0.5` → `0.7` in two steps (7-status taxonomy at `0.6`; `check_id` → `audit_id` rename at `0.7`). Coverage matrix JSON `schema_version` rebases from `"1.0"` to `"0.1"` so it matches the project's pre-release `0.x` convention. Two new universal P3 requirements (`p3-must-version`, `p3-should-version-short`) plus 22 additional behavioral checks across P1-P8 close the remaining behavioral orphan coverage. CLI subcommand surface renames `check` → `audit` and `generate` → `emit` (breaking). Badge eligibility floor lowers from 80% to 70%, and the leaderboard score becomes credit-weighted on shipped-binary behavior only. The Vale prose-check stack (`styles/`, `.vale.ini`, `scripts/prose-check.sh`) moves to dev-only contributor tooling; the workflow guard keeps it out of `main` going forward. ## Changelog ### Added - 22 new behavioral checks across P1-P8 close the remaining behavioral orphan coverage (verbose, color, raw, examples, defaults-in-help, rich-tui, about/long-about, stdin-input, consistent-naming, timeout-behavioral, structured exit codes, JSON error envelopes, actionable errors, force/yes, read/write distinction, TTY-aware verbosity, and more). - Two universal P3 requirements (`p3-must-version`, `p3-should-version-short`) verify that every CLI ships a `--version` flag plus a short alias from the `-V` / `-v` / `-version` family. - New `opt_out` and `n_a` scorecard statuses surface explicit non-adoption and unmet-antecedent rows; each `results[]` entry now carries `tier` plus `audit_id`. Pre-`0.6` consumers feature-detect. - Top-level `--verbose` / `-v` (env `AGENTNATIVE_VERBOSE`), `--examples`, `--color`, and `--raw` flags surface diagnostic detail, curated invocation blocks, ANSI styling control, and pipe-friendly `id<TAB>status` rows. - `anc skill install --all` and `anc skill update [host|--all]` iterate every known host in one invocation. ### Changed - **BREAKING**: `anc check` renamed to `anc audit`; `anc generate` renamed to `anc emit`; `anc schema` folded under `anc emit schema`. The implicit-default-subcommand injection now writes `audit`. Update scripts and CI invocations. - **BREAKING**: scorecard `schema_version` advances `"0.5"` → `"0.7"` (two-step), the `check_id` field renames to `audit_id`, and `results[]` switches to one entry per requirement-row rather than per probe. Consumers pinning the prior shape must feature-detect or update. - Leaderboard `score_pct` is now credit-weighted on shipped-binary behavior only: `warn` earns half credit, `opt_out` counts against, source/project audits no longer affect the score. Badge eligibility floor lowers from 80% to 70%. - Vendored `agentnative-spec` advances `0.4.0` → `0.5.0`; scorecard `spec_version` reports `"0.5.0"`. - `coverage/matrix.json` `schema_version` bumps `"1.0"` → `"0.1"` so the matrix follows the project's pre-release `0.x` convention used by the CLI crate, scorecard schema, and vendored spec. The lone consumer (`agentnative-site/src/build/coverage.mjs`) validates the field's existence but does not pin a specific value, so this is safe. - Vale prose-check stack (`styles/`, `.vale.ini`, `scripts/prose-check.sh`) repositions as dev-only contributor tooling. `guard-main-docs.yml` blocks those paths from `main` going forward. ### Fixed - Error output under `--output json` / `--json` now emits a JSON envelope with `error`, `kind`, `message` instead of clap's plain-text rendering, so agents pinned to JSON can parse failures with one shape. - Text mode now renders `[N/A]` (with antecedent evidence) for conditional requirements whose prerequisite was opted out, instead of a misleading `[FAIL]` on the probe id. Text row count and badge score match `--output json`. - The spec parser rejects three malformed conditional-applicability inputs that previously fell through silently (whitespace-only `antecedent.audit_id`, mixed legacy `if:` + new `kind:`, unknown keys inside `antecedent`). ### Documentation - `RELEASES-PREFLIGHT.md` lands as the operational pre-flight checklist gating each release cut. `RELEASES.md` gains a `### Cherry-pick conflicts on guarded paths` subsection and a `### Dev-direct exception` subsection covering engineering-docs paths and the prose-check stack. - Repo-wide prose pass: every tracked markdown doc plus the historical sections of `CHANGELOG.md` carry the same per-occurrence punctuation tightening applied to all 64 PR bodies in the v0.4.0 → v0.5.0 window. ## Type of Change - [x] `BREAKING CHANGE`: Breaking API change (requires major version bump) ## Related Issues/Stories - Story: n/a - Issue: n/a - Architecture: `agentnative-spec` `v0.5.0` (vendored at upstream commit `d5d4086`). Consumer-facing JSON shape moves to schema `0.7` with the `audit_id` rename. - Related PRs: cherry-picks of #55, #56, #57, #58, #59, #60, #61, #62, #63, #64, #65, #66, #68, #69 from `dev`. ## Testing - [x] All tests passing **Test Summary:** - `cargo test`: 793 passed, 2 ignored. - `anc emit coverage-matrix --check`: exit 0. - `cargo deny check advisories`: ok. - Release-mechanics preflight per `RELEASES-PREFLIGHT.md`: green except the cross-repo `agentnative-site` schema gap (tracked separately). ## Files Modified **Modified:** - Source: `src/audits/`, `src/scorecard/`, `src/principles/`, `src/main.rs`, `src/cli.rs`, `src/audit.rs`, `src/types.rs`, `src/runner/`, `src/source.rs`, `src/skill_install.rs`, and supporting modules. - Schema: `schema/scorecard.schema.json` regenerated to the `0.7` contract. - Vendored spec: `src/principles/spec/*` advances to `v0.5.0`. - Coverage artifacts: `docs/coverage-matrix.md`, `coverage/matrix.json` reflect 59 requirement rows. - Workflows: `.github/workflows/guard-main-docs.yml` (extra_paths). - Tracked docs: `README.md`, `AGENTS.md`, `CLAUDE.md`, `PRODUCT.md`, `BRAND.md`, `RELEASES.md`, `RELEASES-RATIONALE.md`, `scripts/SYNCS.md`, `.github/pull_request_template.md`, `CHANGELOG.md`. - Scripts: `scripts/generate-changelog.sh` (duplicate-section guard), `scripts/sync-spec.sh` (`--ref` flag and `gh api` transport), `scripts/hooks/pre-push` (shellcheck step). - Build identity: `Cargo.toml`, `Cargo.lock` (`0.5.0`). **Created:** - `RELEASES-PREFLIGHT.md` (operational pre-flight checklist). **Renamed:** - `anc check` → `anc audit` (subcommand surface). - `anc generate` → `anc emit` (subcommand surface). - Scorecard `check_id` → `audit_id` (JSON field). **Deleted:** - `.vale.ini`, `styles/`, `scripts/prose-check.sh`, plus the orphaned helpers `scripts/sync-prose-tooling.sh`, `scripts/test-prose-check.mjs`, `scripts/generate-pack-readme.mjs`. Replaced by the `guard-main-docs.yml` `extra_paths` guard that keeps the stack off `main` going forward. ## Breaking Changes - [x] Breaking changes described below: 1. **Scorecard JSON shape**: `schema_version` `"0.5"` → `"0.7"`. `check_id` renamed to `audit_id` (per-row and in `coverage/matrix.json`). `results[]` switches to one entry per requirement-row instead of per probe; each entry carries new `tier` and `audit_id` fields. Status enum expands from 3 to 7 values (`pass`, `warn`, `fail`, `opt_out`, `n_a`, `skip`, `error`). Consumers pinned to `0.5` or the prior `check_id` field must update. 2. **Subcommand surface**: `anc check` renamed to `anc audit`; `anc generate` renamed to `anc emit`; `anc schema` folded under `anc emit schema`. Scripts and CI invocations pinned to the old names must update. ## Deployment Notes - `agentnative-site` must add `'0.7'` to its `SUPPORTED_SCHEMA_VERSIONS` allowlist before this release is tagged. Without that, the site's regen pipeline rejects every `v0.5.0` scorecard upload. - After tag publish: run `./scripts/sync-dev-after-release.sh v0.5.0 && git push origin dev` per `RELEASES.md` § After publish to backport `Cargo.toml`, `Cargo.lock`, and `CHANGELOG.md` to `dev`.
brettdavies
added a commit
that referenced
this pull request
Jun 1, 2026
…--dry-run Adds a P0 plan to mirror the three not-yet-shipped items from brettdavies/agentnative-skill PR #25 into this repo: a GitHub Release published-state precondition and a post-sync regen-idempotency check on `scripts/sync-dev-after-release.sh`, plus a `--dry-run` flag on `scripts/generate-changelog.sh`. The duplicate-section guard from the same skill PR already landed here via PR #68 and is called out as such so the implementer scopes the work correctly. Reference PR: brettdavies/agentnative-skill#25
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
Tightens prose across the 11 tracked markdown docs in the repo:
CLAUDE.md,AGENTS.md,scripts/SYNCS.md,README.md,PRODUCT.md,RELEASES-PREFLIGHT.md,RELEASES.md,RELEASES-RATIONALE.md,.github/pull_request_template.md,styles/brand/README.md, andBRAND.md. Also applies a one-time prose pass to thehistorical sections of
CHANGELOG.md(an explicit exception to the no-manual-edits rule, since the equivalent fix onupstream PR bodies has already shipped).
Bundles three release-flow hygiene fixes that surfaced during the prose pass:
scripts/generate-changelog.shnow refuses to prepend a duplicate[vX.Y.Z]section when one already exists inCHANGELOG.md. Re-running with an already-published tag previously emitted a second copy of the same section andan empty
vX.Y.Z...vX.Y.Zcompare link.RELEASES.mdgains a "Cherry-pick conflicts on guarded paths" subsection documenting thegit update-index --removeplusgio trashresolution pattern for modify/delete and rename/delete conflicts ondocs/plans/,docs/brainstorms/, anddocs/ideation/paths during release cherry-picks. Standardgit rmis denied by repopolicy; the plumbing form is the supported alternative.
anc emit coverage-matrixwrites its generated trailer in a form that survives the prose-check pipeline; thematching
--checkfailure message insrc/main.rsuses the same form.styles/brand/README.mdis generator-emitted, so the fix is sustained by updating thestyles/brand/*.ymlrulesources and the
scripts/generate-pack-readme.mjstrailer. Future regenerations stay clean.Changelog
Changed
CHANGELOG.md. Eachoccurrence of a recurring punctuation pattern was replaced with the alternative best matching the local context
(colon, semicolon, period, comma, or a small rewording).
anc emit coverage-matrixwrites the trailer as<!-- Generated byanc emit coverage-matrix; do not edit by hand -->; the--checkfailure message insrc/main.rsuses the same form.styles/brand/README.mdregenerated against tightenedstyles/brand/*.ymlrule sources and updatedscripts/generate-pack-readme.mjstrailer so the drift check stays clean on future regenerations.Fixed
scripts/generate-changelog.shnow refuses to prepend a duplicate[X.Y.Z]section when one already exists inCHANGELOG.md. Re-running the script with an already-published tag previously emitted a second copy of the samesection and an empty
vX.Y.Z...vX.Y.Zcompare link.Documentation
RELEASES.mdgains a "Cherry-pick conflicts on guarded paths" subsection documenting thegit update-index --removeplusgio trashresolution pattern for modify/delete and rename/delete conflicts ondocs/plans/,docs/brainstorms/, anddocs/ideation/paths during release cherry-picks. Standardgit rmis denied by repopolicy; the plumbing form is the supported alternative.
Type of Change
docs: Documentation updateRelated Issues/Stories
after this PR merges.
Testing
Test Summary:
cargo test: 793 passed, 2 ignoredanc emit coverage-matrix --check: exit 0 (no drift)bun scripts/generate-pack-readme.mjs --check: exit 0 (no drift)Files Modified
Modified:
AGENTS.md,BRAND.md,CHANGELOG.md,CLAUDE.md,PRODUCT.md,README.md,RELEASES-PREFLIGHT.md,RELEASES-RATIONALE.md,RELEASES.md,.github/pull_request_template.md,scripts/SYNCS.md,styles/brand/README.mdstyles/brand/FillerAdjectives.yml,styles/brand/HedgeWords.yml,styles/brand/MarketingRegister.yml,scripts/generate-pack-readme.mjs(sustains thestyles/brand/README.mdfix across regen)scripts/generate-changelog.sh(duplicate-section guard)src/main.rs,src/principles/matrix.rs,docs/coverage-matrix.md(matrix trailer at the source)Created:
Renamed:
Deleted:
Breaking Changes
Deployment Notes