Repository navigation
release: v0.5.0 — p3 version MUST + p8 conditional applicability + audit rename - #44
Merged
Merged
Conversation
…aul, releases split (#30) Establishes a four-repo contribution framework so visitors and agents land on the right intake for their contribution shape. Pairs `RELEASES.md` as a runbook with a new `RELEASES-RATIONALE.md` decision log, separating operational steps from the "why" behind them. Renames the `grade-a-cli` issue template to `grading-finding` to match its actual purpose (spec-feedback derived from scoring a real CLI, not a registry submission). Scrubs personal-environment hostnames from prose-check tooling so the LanguageTool integration documents the service generically. Folds in mechanical pre-push fixes (markdown wrap to 120 cols, Vale vocab additions, one spec-voice rewrite) so the branch lands hook-clean. - Three-tier contribution framework (Signal / Proposal / Code) in `CONTRIBUTING.md` with a "Where to file what" routing table covering all four repos - `00-blank.yml` issue template, sort-prefixed to the top of the picker, with an agent-facing footer redirecting to structured templates - Fourth `contact_link` in `.github/ISSUE_TEMPLATE/config.yml` routing skill-bundle issues to the bundle repo - Issue template `grade-a-cli.yml` renamed to `grading-finding.yml`, with `name`, `description`, and `labels` updated to match the actual purpose - `RELEASES.md` reduced from runbook-plus-rationale (339 lines) to runbook-only (201 lines), cross-linking the new rationale doc - `AGENTS.md` updated from three-repo to four-repo ecosystem; template references updated - `scripts/prose-check.sh` default `LANGUAGETOOL_URL` is now `http://languagetool:8081` (service-name default; consumers override via env var) - `docs/architecture/languagetool-deployment.md` (deployment knowledge compounded into the shared `solutions-docs` repo as `self-hosted-languagetool-for-prose-check-stacks-2026-05-20.md`) No check changes needed. This PR only touches contributor-facing intake, runbook organization, and prose-check tooling. No MUST/SHOULD/MAY tier add, remove, or move, no requirement ID changes, no frontmatter shape changes. **Reviewer:** @brettdavies Drafted with Claude as a writing partner across multiple sessions. Brett reviewed and committed every change. **Modified:** - `.github/ISSUE_TEMPLATE/config.yml`: fourth `contact_link` for skill-bundle issues - `AGENTS.md`: three-repo to four-repo ecosystem; template references - `CONTRIBUTING.md`: three-tier framework, four-way routing table, AI disclosure pointer - `RELEASES.md`: runbook-only (rationale moved out) - `docs/architecture/voice-enforcement.md`: LanguageTool URL scrubbed, redirect to shared solution doc - `scripts/hooks/pre-push`: header prose scrubbed of personal-environment hostnames - `scripts/prose-check.sh`: default `LANGUAGETOOL_URL` is service-name (`http://languagetool:8081`) - `styles/config/vocabularies/brand/accept.txt`: added `backports`, `implementer/s`, `runbook/s` **Created:** - `.github/ISSUE_TEMPLATE/00-blank.yml`: blank template with agent-facing footer - `RELEASES-RATIONALE.md`: release-pipeline decision log **Renamed:** - `.github/ISSUE_TEMPLATE/grade-a-cli.yml` → `.github/ISSUE_TEMPLATE/grading-finding.yml` **Deleted:** - `docs/architecture/languagetool-deployment.md` (compounded into `solutions-docs`) - Story: n/a - Issue: n/a - Architecture: Shared infrastructure pattern compounded into `solutions-docs` as `self-hosted-languagetool-for-prose-check-stacks-2026-05-20.md` - Related PRs: Parallel `CONTRIBUTING` refresh and `RELEASES`-split work is being prepared in `agentnative-cli`, `agentnative-site`, and `agentnative-skill`. The `RELEASES.md` and `RELEASES-RATIONALE.md` split mirrors the pattern introduced in `agentnative-site` and is being rolled out across all four ecosystem repos in parallel sessions. The runbook holds commands, paths, and decision tables for cutting a release; the rationale doc holds the "why" behind branching choices, PR conventions, release gating, CHANGELOG generation, and the prose-check pipeline. The `grade-a-cli` rename closes a long-standing misframing. That template was originally for spec-feedback findings derived from scoring a real CLI, but its name suggested it was the path for adding a CLI to the registry. The actual registry-submission path is `add-tool-to-registry.yml` in the `agentnative-cli` repo. The two intakes now have clear, non-overlapping names. The LanguageTool URL scrub removes references to a developer-environment hostname from shipped artifacts (`scripts/prose-check.sh`, `scripts/hooks/pre-push`, `docs/architecture/voice-enforcement.md`). The default URL is now the docker-compose service name (`http://languagetool:8081`), and consumers without a self-hosted instance get a graceful skip from the prose-check stack.
…ersion pin (#31) Folds in the in-flight prose-tooling refactor that was sitting as WIP on `dev`, closes two stale plan-status flips from the v0.4.0 wave, relocates a pair of operational coordination plans out of `docs/plans/`, and corrects an outdated version pin in the README. Four concerns: - `refactor(prose)` + `chore(prose)`: `scripts/prose-check.sh` now sources the shared `lt_check` shell helper from `brettdavies/dotfiles` instead of carrying its own LT_URL probe, denylist, and per-file curl loop. Architecture doc and consumer guidance (`CONTRIBUTING.md` § Voice enforcement, `RELEASES.md` § Prose scrubbing) updated to name `lt_check` as the only supported entry point so all four agentnative repos share one source of truth. Brand vocabulary picks up `denylist` and `longCode`; one non-normative `must` in the architecture doc rephrased to descriptive voice so the MUST/SHOULD/MAY axis stays reserved for the principles. - `docs(plans)`: flips two v0.4.0-era plans from `active` → `shipped` (P2/P4 envelope SHOULDs landed in v0.4.0 PR operational coordination plan from `docs/plans/`. Operational coordination working docs belong with their sibling artifacts under `.context/`, not in tracked spec governance. - `docs(readme)`: bumps the inline version pin on `README.md:17` from v0.3.1 to v0.4.0 to match `VERSION` and the eight-principle surface. - - - - - No check changes needed. The PR introduces no MUST/SHOULD/MAY tier additions, removals, or moves. Prose-only README polish + plan status flips + script-side LT delegation; the `requirements[]` contract is unchanged. **Reviewer:** @brettdavies Claude Code authored the commit messages, this PR body, the `lt_check` refactor in `scripts/prose-check.sh`, and the plan-status frontmatter flips. The `lt_check` helper itself (in `brettdavies/dotfiles`) was authored separately; the CONTRIBUTING / RELEASES / voice-enforcement consumer-side updates are Claude-authored against the helper's contract. Brett reviewed before merge.
…#33) ## Summary Adds two P3 requirements that the existing `agentnative-cli::VersionCheck` was already enforcing in spirit. The cli's coverage matrix listed `p3-version` as a check with no spec requirement to point its `covers()` at, even though the principle's prose section already named `p3-version` as a measurement vector. This PR aligns the frontmatter with the prose and the cli implementation. ## Changelog ### Added - `p3-must-version` (universal MUST): top-level `--version` prints a non-empty version line and exits 0. - `p3-should-version-short` (universal SHOULD): a short alias (`-V` per clap default; `-v` per Node/npm/Bun/Yarn/Make convention; `-version` per Go's `flag` package) accompanies `--version`. Any of the three forms is sufficient. ## Linked check review brettdavies/agentnative-cli#55 The cli companion PR extends `VersionCheck` to probe both `--version` and the short-alias family (`-V`, `-v`, `-version`) with a Pass/Warn/Fail rubric: Pass when both work, Warn when only `--version` works (MUST satisfied, SHOULD missed), Fail when neither works. `covers()` returns the two new IDs. Coverage matrix on that branch is regenerated and the registry test counters move from 57 -> 59 (with MUST 27 -> 28 and SHOULD 20 -> 21). ## Human reviewer **Reviewer:** @brettdavies ## AI disclosure AI-assisted edit. The audit that surfaced the gap, the requirement text, and the rationale in this body were drafted during a pairing session with Claude (Anthropic). The repo maintainer reviewed and approved before submission. Spec validation (`scripts/validate-principles.mjs`) and prose tooling (Vale, LanguageTool, unslop) ran on the change.
## Summary
Adds a machine-checkable conditional applicability shape to the
principle frontmatter so verifiers can drive consequent evaluation from
an antecedent's status rather than from a prose-only reason string. The
new shape coexists with the existing `universal` and `{if: <reason>}`
forms. Authors pick the machine-checkable form whenever the antecedent
has a verifier in the CLI's catalog today.
Migrates the five conditional requirement rows whose antecedents already
have CLI verifiers: `p2-must-schema-print` and `p2-should-schema-file`
(antecedent `p2-json-output`); `p8-must-bundle-install`,
`p8-may-install-all`, and `p8-may-bundle-update` (antecedent
`p8-bundle-exists`). The remaining 18 `{if: <reason>}` rows across p1,
p3, p4, p5, p6, p7 stay as-is until the CLI's verifier catalog grows to
cover their prerequisites.
Lands U1 of the [Path 2 scoring-fairness
plan](https://github.com/brettdavies/agentnative-site/blob/dev/docs/plans/2026-05-21-001-feat-scorecard-fairness-taxonomy-plan.md).
The 7-status taxonomy and the propagation table are documented here so
U2 (CLI) can implement the verifier-side semantics against a stable
contract.
## Changelog
### Added
- Conditional applicability shape `{kind: conditional, antecedent:
{check_id: <id>}}` for machine-checkable conditionals. The `check_id` is
a verifier identifier, not a requirement `id`; the v1 schema is
single-antecedent only, with compound antecedents (`op`/`checks`)
deferred to v2 and rejected by the validator.
- Antecedent-status propagation table mapping the antecedent's status
(under the 7-status taxonomy: `pass`, `warn`, `fail`, `opt_out`, `n_a`,
`skip`, `error`) to the consequent's emission, including the inheritance
rules for `skip` and `error`.
### Changed
- Migrate p2 (`p2-must-schema-print`, `p2-should-schema-file`) and p8
(`p8-must-bundle-install`, `p8-may-install-all`, `p8-may-bundle-update`)
applicability from `{if: <reason>}` to the new shape. Antecedent for p2
is `p2-json-output`; for p8 is `p8-bundle-exists`. No tier changes.
## Linked check review
Coupled-release pending. The CLI's `Applicability` parser does not
recognize `{kind: conditional, antecedent: {check_id}}` today and will
skip or error on the five migrated rows once it next syncs the spec. U2
of the [Path 2
plan](https://github.com/brettdavies/agentnative-site/blob/dev/docs/plans/2026-05-21-001-feat-scorecard-fairness-taxonomy-plan.md)
extends the CLI's parser and emits the propagation table semantics. No
spec `VERSION` bump in this PR: the bump lands with the release PR that
closes out the taxonomy unit.
## Human reviewer
**Reviewer:** @brettdavies
## AI disclosure
Schema extension, validator branch, AGENTS.md propagation table, and p8
prose re-expression drafted by Claude under direct supervision; design
decisions (where the new shape lives, what `check_id` references,
migration scope) reviewed and approved interactively before any file
changes landed.
## Summary Updates `docs/syncs.md` to reflect three reality shifts in the downstream sync mechanism that the doc had drifted away from: 1. **All three consumer scripts** (cli, skill, site) now use `gh api` against the GitHub contents endpoint to vendor files at a resolved ref, not `git clone`. Same code path covers branches, tags, and commit SHAs via the `?ref=<X>` query parameter; local-checkout fallback covers offline runs. The doc previously described only the cli + skill scripts and called the resolution "remote-first, falls back to local." 2. **The `--ref <branch|tag|SHA>` flag** (and matching `SPEC_REF` environment variable) is now uniform across all three scripts. The use case is cross-repo coordination: a CLI or site change that consumes an in-flight spec contract can vendor `dev` (or a specific SHA) before the spec cuts a tag, then re-sync to the tag once it lands. The flag existed on the scripts but wasn't documented anywhere central. 3. **The site repo's sync had shipped** but the doc still marked it "PLANNED, not yet built," stale since the `2026-04-23-001-feat-sync-spec-plan.md` plan landed in the site repo. Refreshed to describe the live mechanism (`scripts/sync-spec.sh` → `src/data/spec/`, `SPEC_VERSION` consumed via `src/build/util.mjs`). Also corrects the mermaid diagram (site arrow is now solid `manual<br/>sync-spec.sh`, no longer dashed `planned`), the file-paths-per-consumer table (real `src/data/spec/` instead of `(planned, e.g. ...)`), and the "consistency reference" section at the bottom (real path for the site script, not a plan reference). No functional change. The scripts and flag already exist; the doc just catches up to reality. ## Changelog <!-- Prose-only doc clarification; nothing user-facing changed in the spec itself. Per template guidance, omitted. --> ## Linked check review No check changes needed. This PR touches `docs/syncs.md` only. No principle frontmatter, no `requirements[]` changes, no tier moves. The CLI's `Applicability` parser is unaffected. ## Human reviewer **Reviewer:** @brettdavies ## AI disclosure PR body drafted by Claude under direct supervision. The underlying commit (`c2d9673`) was authored by Brett directly; this PR is the review-surface wrapper around an already-committed docs change.
## Summary Adds a `shellcheck --severity=warning` step to the pre-push hook between the pack-README drift check and the prose-check stage. Lints every tracked `*.sh` plus everything under `scripts/hooks/` at warning severity, which catches real bugs (unused vars, quoting issues, missing exits) while ignoring info/style noise. Skips with a one-line note when shellcheck isn't on PATH. Zero findings on the current tree, including the hook script itself. Mirrors the pattern landed in [`agentnative-cli` commit `a014240`](brettdavies/agentnative-cli@a014240). The doc-comment block in the new shell-linting section was worded so lines starting with `# shellcheck` (which would otherwise be parsed as SC1072/SC1073 directives) are avoided. The rebase onto dev (after retargeting this PR from `main` → `dev`) carried three small consistency edits in the same file so the resulting diff stays self-contained: - Renumbered the header pipeline list: shellcheck takes step 8; prose-check is now step 9. - Updated the "branch deletions" comment from "stages 7 and 8 redirect their child stdin to /dev/null" to "stages 7 and 9," since the new step 8 (shellcheck) doesn't redirect stdin. - Preferred dev's prose-check description ("plus LanguageTool when reachable") over the older base's wording ("plus LanguageTool over Tailscale when reachable"). ## Changelog <!-- CI / hook plumbing only; no user-facing change in the spec contract. Per template guidance, Changelog is omitted. --> ## Linked check review No check changes needed. This PR touches `scripts/hooks/pre-push` only. No principle frontmatter, no `requirements[]` changes, no tier moves. ## Human reviewer **Reviewer:** @brettdavies ## AI disclosure Hook edits, doc comments, SC1072/SC1073 collision avoidance, conflict resolution during the rebase onto dev, and this PR body were AI-drafted under direct supervision. Branch authoring, scope decision, slot placement between the pack-README drift and prose-check stages, and the base-branch retarget were Brett's calls.
…#37) ## Summary `.github/pull_request_template.md` § `## Summary` now carries a SCOPE / EXCLUDE block matching the `## Changelog` comment's instructional style. The block tells the author to describe the net diff only and lists the verification artifacts that don't belong in the body: triple-diff stats, leak-check output, patch-id cherry-check counts, pre-push gate results, CI status, prose-scrub findings, and any "I ran X and it returned Y" narration. `RELEASES.md` § PR body splits the previous single "no explainer prose" bullet into three: the original general statement, a "Summary describes the net diff only" bullet covering scope, and a "Zero verification artifacts in the body" bullet naming the banned outputs. `RELEASES-RATIONALE.md` § "No explainer prose in the body" gains the "net diff" frame and the specific example phrasings ("A: 12 files, B: none, C: clean", "`guard-main-docs` runs clean", "no guarded paths leaked") so future readers recognize the patterns they shouldn't write. ## Changelog <!-- Prose-only clarification of an existing rule; no requirement semantics change. --> ## Linked check review No check changes needed. PR template and release docs only; no principle text or requirement semantics changed, so `anc` has nothing new to validate. ## Human reviewer **Reviewer:** @brettdavies ## AI disclosure AI (Claude Opus 4.7) drafted the audit findings, the three edits, and this PR body; @brettdavies reviewed the audit, scoped the work to a new feature branch, and approved the SCOPE / EXCLUDE wording before submission.
…es (#38) ## Summary Tightens the principle `last-revised` rule so any frontmatter mutation stamps today's date, adds `scripts/check-last-revised.mjs` to enforce the rule at pre-push and PR CI (with a `--fix` flag), and backfills seven principle files whose dates had drifted because the old rule's "prose-only" carve-out was ambiguous enough to skip applicability-shape migrations and `summary` rewrites. Audit found one file (p3) where the discipline was followed correctly. Six files were off by 1 to 15 days; the worst cases were p2 and p8 (PR #34 conditional-applicability migration) and p5/p7 (summary rewrites in #25/#22). The backfill diff touches only `last-revised`, so it does not trigger the new check, because the rule fires on frontmatter-sans-date deltas and the backfill leaves frontmatter-sans-date unchanged. ## Changelog ### Changed - `last-revised` discipline tightened: any frontmatter mutation (summary rewrites, applicability shape migrations, tier changes, requirement add/remove, status flips, reordering) stamps today's date. Prose-only edits below the closing `---` fence remain exempt. Enforced by `scripts/check-last-revised.mjs` at pre-push and PR CI. ### Fixed - Backfilled `last-revised` on p1, p2, p4, p5, p6, p7, p8 to match each file's most recent substantive frontmatter change. p3 was already correct. ## Linked check review no check changes needed: this PR is governance + tooling only and does not alter any MUST/SHOULD/MAY tier, requirement ID, or applicability shape. `anc`'s vendored `spec/` will pick up the corrected dates on its next sync. ## Human reviewer **Reviewer:** @brettdavies ## AI disclosure Audit, script, tests, hook wiring, CI workflow, and PR body authored by Claude (claude-opus-4-7) under human direction. Human reviewed the design decision to compare `last-revised` against today's date rather than against the base ref, and approved the backfill date choices.
… cohort bands (#39) ## Summary Introduces the spec's scoring methodology, which was previously undefined. `principles/scoring.md` becomes the single source of truth for how a per-requirement scorecard collapses into the `score_pct` behind the `anc.dev` leaderboard and badge. The score reflects shipped-binary behavior only. Source-code and repository checks do not contribute to the public score; they are reserved for a future advisory mode. The formula is a credit-weighted ratio (pass 1.0, warn 0.5, fail and opt_out 0.0) over the rows whose status is pass/warn/fail/opt_out, with n_a/skip/error excluded. `opt_out` counts in the denominator so deliberate non-adoption is reflected. Tier weights are a tunable parameter, published flat (MUST = SHOULD = MAY = 1). `docs/badge.md` now references `scoring.md` for the formula rather than restating it, lowers the eligibility floor from 80% to 70% so the badge can spread the standard, and replaces the three-color threshold with four cohort bands that carry the exclusivity signal. ## Changelog ### Added - Add `principles/scoring.md` defining the leaderboard scoring formula: a binary-behavior, credit-weighted ratio with `opt_out` counted and `n_a`/`skip`/`error` excluded, plus four badge cohort bands. ### Changed - Lower the badge eligibility floor from 80% to 70%. - Replace the badge's three-color threshold with four cohort bands (Exemplary >= 85, Strong 80-84, Solid 75-79, Qualified 70-74). ## Linked check review no check changes needed in this PR. U3 documents the formula; implementing `score_pct` against it in the CLI is the separate follow-on unit (the CLI currently ships a transitional formula and is unchanged here). ## Human reviewer **Reviewer:** @brettdavies ## AI disclosure `scoring.md` and the `badge.md` edits were AI-drafted from a 95-tool binary-behavior rescore analysis and the formula, floor, and cohort-band decisions Brett directed interactively. Pending Brett's review on this PR.
This PR brings the spec's conformance vocabulary in line with the CLI's `check` to `audit` rename. The net change versus `dev`: the conditional-antecedent frontmatter field is renamed `check_id` to `audit_id` across the principle files and the validator that enforces it, and the human-facing vocabulary shifts from "check"/"checker" to "audit"/"auditor" throughout the standard's prose, the PR template, and the historical plans. Unrelated uses of the word "check" are deliberately preserved: the prose-check (Vale/LanguageTool) pipeline, CI status checks, the repo's own `check-links`/`check-last-revised` tooling, and plain-English usage. This is a coupled, breaking change. The companion rename in `agentnative-cli` parses `audit_id` and emits `schema_version: 2.0`. Do not merge until the companion CLI PR is linked below and both can land together; shipping `audit_id` in the spec ahead of the CLI would break the vendored-frontmatter parser. - Rename the conditional-antecedent frontmatter field `check_id` to `audit_id`. This is a breaking change to the principle-frontmatter shape: consumers that parse `applicability.antecedent` must read `audit_id`. - Rename the standard's conformance vocabulary from `check` to `audit` (the `anc audit` subcommand, "audit IDs", "auditor") across principle prose and governance docs. Companion rename in progress on `brettdavies/agentnative-cli` (`refactor/check-to-audit`): `build_support/parser.rs` parses `antecedent.audit_id` under the v1-strict schema, and `coverage/matrix.json` carries `audit_id` with `schema_version: 2.0`. The PR URL will be added here before merge. This PR must not merge until that companion PR is open and ready to land in lockstep. **Reviewer:** @brettdavies AI (Claude) executed the mechanical `check` to `audit` rename, updated the validator, fixtures, and tests, and authored this PR; the scope decisions (maximal rename, hold-the-release, rewriting historical plans) and the review are human (@brettdavies).
…erator (#32) Launch polish for the spec's consumer-facing docs (README and BRAND), plus a correction and guard for the changelog tooling. README, leading with the standard and deferring implementation artifacts: - Each P1–P8 row links to its principle file, and a new "Reading the spec" section documents the machine-readable `requirements[]` contract (`id`, `level`, `applicability`, `summary`) auditors pin against, pointing to `principles/AGENTS.md` for the full governance contract. - The sample scorecard becomes a pointer (anc's README and anc.dev), the Scoring section becomes a pointer to `principles/scoring.md`, and the embedded Live leaderboard table is removed. Those are artifacts of the linter and site, not the canonical principle text. - Badge section states the 70% eligibility floor, matching `scoring.md` and `docs/badge.md`. Command references use `anc audit`, `anc emit schema`, `--principle <1-8>`. - Related is consolidated into sibling repos plus an in-repo doc map. BRAND: - Marks every channel as PRODUCT.md-earned and sharpens the prose-tooling sync note. Adds `ripgrep` to the brand Vale vocabulary. Changelog tooling: - Collapse a duplicate `## [0.4.0]` section. A re-prepend had left a second block with a broken `v0.4.0...v0.4.0` self-compare above the canonical `v0.3.1...v0.4.0` one; the blocks were byte-identical and the bullets match PR #25, release PR #26, and the published GitHub Release, so no content changed. - Guard `generate-changelog.sh` against prepending a version whose section already exists, so the duplicate cannot recur. _Documentation and release-tooling only: no changes to the standard's requirements, tiers, applicability gates, or requirement IDs._ No audit changes needed. This PR touches `README.md`, `BRAND.md`, the brand Vale vocabulary, `CHANGELOG.md` (de-dup), and `scripts/generate-changelog.sh` (guard); it changes no principle text, tier, applicability gate, or requirement frontmatter. **Reviewer:** @brettdavies AI-assisted: the README rework, the "Reading the spec" section, the BRAND edits, the changelog de-dup, and the generator guard were AI-drafted from the maintainer's direction and the repo's own sources (PR #25/#26, `principles/scoring.md`, `principles/AGENTS.md`), then reviewed by @brettdavies.
…n doc references (#41) ## Summary Pre-release hygiene surfaced by a readiness audit of the `dev` → `main` delta. No principle requirements change tier, ID, or applicability shape. - `check-last-revised.yml` now triggers only on PRs targeting `dev`. The discipline is enforced when a principle change lands on `dev`; a release PR to `main` replays those files unchanged, and comparing them against `main`, which legitimately lags `dev`, flagged every principle revised on a prior day as "date isn't today". The pre-push hook (which always compares against `origin/dev`) still backstops a fresh principle edit authored directly on a release branch. - `principles/AGENTS.md` § Validation attributed the frontmatter validation to a `.github/workflows/validate-principles.yml` workflow that does not exist. Validation runs in the pre-push hook via `scripts/validate-principles.mjs`; the text now says so. - `RELEASES.md` § Branch protection listed a `ci` required status check that does not exist and omitted `guard-provenance`. The required checks are now stated as `guard-docs`, `guard-release`, `guard-provenance`. - Pressure-test notes in P3, P4, P5, and P7 deferred several still-open findings to "a v0.4.0 PR". v0.4.0 has shipped, so those disposition labels now read "a future PR"; the deferred findings themselves remain open and their verbatim quotes are untouched. ## Changelog ### Fixed - The `last-revised` discipline check runs only on PRs targeting `dev`, so release PRs to `main` no longer fail it for principles revised on an earlier day. ## Linked audit review No audit changes needed: prose-only pressure-test-note edits, a CI trigger scope fix, and documentation corrections. No `requirements[]` entry is added, removed, or re-tiered. ## Human reviewer **Reviewer:** @brettdavies ## AI disclosure AI-authored under human direction and review: the readiness audit, the workflow scope fix, the documentation corrections, and the de-versioning.
`PRODUCT.md`, `RELEASES.md`, and `RELEASES-RATIONALE.md` ship to `main` but markdown-linked to `docs/architecture/`, which is dev-only (blocked from `main` by `guard-main-docs.yml`). On a release branch those six links resolve to nothing and fail `check-links`. Each link is now a plain code-span path mention; the `(dev-only)` annotation and the path itself stay, so the reference is still discoverable without a target that breaks on `main`. `dev` and `main` now carry identical text for these files, so no future release has to strip the links by hand. No audit changes needed: documentation-only edit, no `requirements[]` entry added, removed, or re-tiered. **Reviewer:** @brettdavies AI-authored under human direction and review.
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
v0.5.0 of the agent-native CLI standard. Two principles gain normative content: p3 acquires a universal
--versionMUST plus a short-alias SHOULD; p8's machine-checkable applicability gains a typed{kind: conditional, antecedent: {audit_id: <id>}}shape that supersedes the prose-only{if: <reason>}form (p2 migrates as well). The standard's conformance vocabulary renames fromchecktoauditacross principle prose, theaudit_idfrontmatter field, and theanc auditsubcommand. A leaderboard scoring formula lands inprinciples/scoring.mdwith a binary-behavior, credit-weighted ratio plus four cohort bands (Exemplary / Strong / Solid / Qualified) and a 70% eligibility floor. Governance gains the three-tier contribution framework (Signal / Proposal / Code), thelast-reviseddiscipline check now stamps any frontmatter mutation, andRELEASES.mdsplits into a runbook plus a companion rationale doc.Changelog
Added
CONTRIBUTING.mdwith a "Where to file what" routing table covering all four repos by @brettdavies in #3000-blank.ymlissue template, sort-prefixed to the top of the picker, with an agent-facing footer redirecting to structured templatescontact_linkin.github/ISSUE_TEMPLATE/config.ymlrouting skill-bundle issues to the bundle repop3-must-version(universal MUST): top-level--versionprints a non-empty version line and exits 0. by @brettdavies in #33p3-should-version-short(universal SHOULD): a short alias (-Vper clap default;-vper Node/npm/Bun/Yarn/Make convention;-versionper Go'sflagpackage) accompanies--version. Any of the three forms is sufficient.{kind: conditional, antecedent: {check_id: <id>}}for machine-checkable conditionals. Thecheck_idis a verifier identifier, not a requirementid; the v1 schema is single-antecedent only, with compound antecedents (op/checks) deferred to v2 and rejected by the validator. by @brettdavies in #34pass,warn,fail,opt_out,n_a,skip,error) to the consequent's emission, including the inheritance rules forskipanderror.principles/scoring.mddefining the leaderboard scoring formula: a binary-behavior, credit-weighted ratio withopt_outcounted andn_a/skip/errorexcluded, plus four badge cohort bands. by @brettdavies in #39Changed
grade-a-cli.ymlrenamed tograding-finding.yml, withname,description, andlabelsupdated to match the actual purpose by @brettdavies in #30RELEASES.mdreduced from runbook-plus-rationale (339 lines) to runbook-only (201 lines), cross-linking the new rationale docAGENTS.mdupdated from three-repo to four-repo ecosystem; template references updatedscripts/prose-check.shdefaultLANGUAGETOOL_URLis nowhttp://languagetool:8081(service-name default; consumers override via env var)p2-must-schema-print,p2-should-schema-file) and p8 (p8-must-bundle-install,p8-may-install-all,p8-may-bundle-update) applicability from{if: <reason>}to the new shape. Antecedent for p2 isp2-json-output; for p8 isp8-bundle-exists. No tier changes. by @brettdavies in #34last-reviseddiscipline tightened: any frontmatter mutation (summary rewrites, applicability shape migrations, tier changes, requirement add/remove, status flips, reordering) stamps today's date. Prose-only edits below the closing---fence remain exempt. Enforced byscripts/check-last-revised.mjsat pre-push and PR CI. by @brettdavies in #38check_idtoaudit_id. This is a breaking change to the principle-frontmatter shape: consumers that parseapplicability.antecedentreadaudit_idinstead ofcheck_id. by @brettdavies in #40checktoaudit(theanc auditsubcommand, "audit IDs", "auditor") across principle prose and governance docs.Fixed
last-revisedon p1, p2, p4, p5, p6, p7, p8 to match each file's most recent substantive frontmatter change. p3 was already correct. by @brettdavies in #38last-reviseddiscipline check runs only on PRs targetingdev, so release PRs tomainno longer fail it for principles revised on an earlier day. by @brettdavies in #41Removed
docs/architecture/languagetool-deployment.md(deployment knowledge compounded into the sharedsolutions-docsrepo asself-hosted-languagetool-for-prose-check-stacks-2026-05-20.md) by @brettdavies in #30Linked audit review
no audit changes needed — the
ancrepo is pinned at vendored spec v0.4.0 and re-vendors on the v0.5.0 tag; a verifier forp3-must-version(the only new MUST) is a downstream follow-up, not a spec-release blocker.Human reviewer
Reviewer: @brettdavies
AI disclosure
Cherry-pick assembly, conflict resolution, CHANGELOG generation, and PR-body drafting performed by Claude (Opus 4.7) under direct supervision; all normative principle content and PR-body Changelog bullets originate from human-authored upstream PR bodies.