release: PRODUCT.md migration + channel artifact stack docs#29
Merged
Conversation
## Summary Broadens the existing **Summary** bullet in RELEASES.md `## PR body` to **No explainer prose anywhere in the body**, applying the same do-not-paste guidance (workflow recap, triple-diff output, pre-push gate results, CI status, exclusion rationale, verification artifacts) to every section of the PR template rather than just `## Summary`. The narrower scoping was producing the anti-pattern in `## Linked check review` and `## Human reviewer` where authors were padding the actual answer with justification prose; the broader rule names the pattern once and covers every section. Adds a new **No hard line wraps** bullet covering PR bodies, heredoc-composed commit messages, and any markdown that ships verbatim to GitHub. Paragraphs and bullets are authored as one logical line because GitHub soft-wraps for display and hard wraps within prose produce visible mid-sentence breaks in some renderers, while also defeating the prose-check pipeline: Vale's line-anchored output reports findings against split lines, and LanguageTool's input handling can choke on certain control-char interactions across wrapped boundaries. Both bullets are themselves authored one-logical-line-per-paragraph; the rule applies first to the PR that documents it. The scope is the GitHub API surface (PR bodies, commit message subjects/bodies, release notes); in-repo markdown still wraps at 120 cols via `md-wrap.py`, which is why this PR's RELEASES.md additions are themselves wrapped while the rule they document covers content that bypasses that wrapping step. `styles/config/vocabularies/brand/accept.txt`: adds `heredoc`, `renderer`, `renderers` so the new RELEASES.md prose passes pre-push Vale.Spelling. No other prose touched these words yet; additions support the new paragraph and are not a broader vocabulary expansion. ## Changelog ### Changed - Document **No explainer prose anywhere in the body** as a body-wide PR-authoring rule, replacing the narrower `## Summary`-only bullet; the same do-not-paste guidance now covers every section of the PR template. - Document **No hard line wraps** as the PR-body, heredoc-commit-message, and ship-verbatim-markdown authoring rule, with rationale (GitHub soft-wrap, prose-check pipeline interactions) named in-line. ## Linked check review no check changes needed. RELEASES.md is governance prose, not a `requirements[]` add/remove/re-tier. ## Human reviewer **Reviewer:** @brettdavies ## AI disclosure Rule wording and PR body drafted by Claude (Opus 4.7) in Claude Code under @brettdavies's direction; Brett authored the underlying working-tree edits to RELEASES.md and reviewed the commit, vocab additions, and PR body before push.
Migrates the channel-design context filename from the legacy `.impeccable.md` to the canonical `PRODUCT.md` expected by the `/impeccable` skill loader, and adds architectural self-documentation that was previously implicit. Four commits, scoped to docs only (no principle/requirement changes): 1. **`ee675f7`** — Rename `.impeccable.md` → `PRODUCT.md` across live references (BRAND.md, AGENTS.md, CONTRIBUTING.md, README.md, the pack-README generator, Vale rule packs and YAML examples). Historical artifacts under `docs/brainstorms/` and `docs/plans/` intentionally keep the legacy spelling. 2. **`efeb3d8`** — Documents the channel artifact stack: BRAND.md gains a `## Channel artifacts` table, a vendoring-source header that travels into consumer repos, and a tier-3 location convention. PRODUCT.md gains an `## Inheritance` section. CONTRIBUTING.md gains a one-line canonical-filename policy. 3. **`d367f42`** — Finishes the rename sweep across `principles/AGENTS.md` and `docs/architecture/voice-enforcement.md` (the two stragglers M1 flagged but skipped). 4. **`5af8b30`** — Fixes a dangling markdown link to `scripts/sync-prose-tooling.sh` in BRAND.md's source-of-truth blockquote (the script lives in consumer repos, not spec). - Channel artifact stack documented in `BRAND.md`: `## Channel artifacts` table, vendoring-source header that travels into consumer repos, and a tier-3 location convention note. - `PRODUCT.md` gains an `## Inheritance` section naming the spec channel's three-tier waterfall (universal `BRAND.md`, channel-delta `PRODUCT.md`, authoritative principles/architecture/decisions). - `CONTRIBUTING.md` gains a one-line policy: `PRODUCT.md` is the canonical channel-design context filename; `.impeccable.md` is migrated atomically with no backward-compatibility shim. - Rename `.impeccable.md` → `PRODUCT.md` across the spec repo. Consumers vendoring `BRAND.md` pick up the rename on their next `sync-prose-tooling.sh` run. no check changes needed — this PR is documentation-only and does not add, remove, or move any MUST/SHOULD/MAY tier on any principle. **Reviewer:** @brettdavies Drafted with Claude Code (Opus 4.7) under Brett's direction; commit-by-commit guidance and final wording were human-reviewed. The rename sweep, BRAND.md additions, and dangling-link fix were generated by the assistant from explicit instructions; Brett reviewed every diff before commit.
The `## Inheritance` section added in PR #28 linked to docs/architecture/ relatively. That path exists on dev only; main excludes it via the guard-main-docs workflow, so check-links rejected the push. Same pattern as 819b1b8. Replace the broken link with plain backticks. The prose still names the path as part of the three-tier waterfall; consumers reading on main just don't get a click-through (which would 404 anyway). BRAND.md line 87 already references docs/architecture/ in plain backticks (no link), so no fix needed there.
Merged
18 tasks
brettdavies
added a commit
to brettdavies/agentnative-site
that referenced
this pull request
May 14, 2026
## Summary Reconciles the site to spec v0.4.0 (eight principles; the new P8 covers Discoverable Through Agent Skill Bundles), migrates the channel-context filename to the canonical `PRODUCT.md` expected by the `/impeccable` skill loader, hoists `DESIGN.md` from `docs/` to the repo root for the same reason, and refreshes the vendored `BRAND.md` plus Vale stack from spec `main` HEAD. Decouples `sync-prose-tooling.sh` from spec release tags (now tracks `main` so prose-tooling iterates on its own cadence), un-vendors `scripts/prose-check.sh` (consumer-owned now; ends the regression where every sync clobbered the SITE-LOCAL DIVERGENCE block), and decouples the OG image's version footer from anc's binary so social shares show the spec version the site currently presents. ## Changelog ### Added - New principle **P8: Discoverable Through Agent Skill Bundles** at `/p8` and `/p8.md`, plus card on the homepage index. Cites `p8-must-bundle-install`, `p8-should-bundle-exists`, `p8-may-install-all`, `p8-may-bundle-update` from spec v0.4.0. - `## Inheritance` section in `PRODUCT.md` self-documenting the three-tier waterfall (BRAND.md universal, PRODUCT.md channel delta, DESIGN.md visual system). - `## Channel artifacts` table and "Source of truth" header arrive in `BRAND.md` from spec main. - Voice docs (`docs/research/VOICE.md`) codify Register 1a (homepage lede) vs 1b (principle page) split, with surface-specific notes for both. - `Definition-as-card coupling` documented in `content/principles/README.md`: the Definition first paragraph is also the homepage card and budgets to 2-3 sentences. ### Changed - "Seven principles" sweeps to "Eight principles" across `_intro.md`, `about.md`, `check.md`, `install.md`, `methodology.md`, `scorecard-schema.md`, build comments, leaderboard hero, AI-summary prompt. - OG image decoupled from per-feature couplings on two axes: card text no longer cites the principle count (now reads "a standard for CLIs that agents can operate"), and the version footer now reads from `content/principles/VERSION` (SITE_SPEC_VERSION, what the site presents) instead of the highest `scorecards/anc-v*.json` (what anc was last compiled against). The OG and in-page footer now always agree on the version. Per-tool badge SVGs continue to use each scorecard's own `spec_version` since they describe the binary that scored each tool. - Rename `.impeccable.md` to `PRODUCT.md` (canonical filename for the `/impeccable` skill loader's `load-context.mjs`). - Hoist `docs/DESIGN.md` to `DESIGN.md` (root) so the loader finds it without `IMPECCABLE_CONTEXT_DIR=docs/`. - `scripts/sync-prose-tooling.sh` tracks spec `main` HEAD instead of latest `v*` tag. The principle contract still pins to tags via `sync-spec.sh`; tooling iterates faster than the contract and does not need release ceremony. - Re-sync `BRAND.md` and Vale stack (`scripts/generate-pack-readme.mjs`, `styles/brand/README.md`, `styles/site/README.md`, `styles/config/vocabularies/brand/accept.txt`) from spec main HEAD `1625416`. - `content/principles/p8-discoverable-skill-bundle.md` Definition compressed from 4 sentences to 2 so the homepage card matches P1-P7 weight. ### Fixed - `scripts/prose-check.sh` un-vendored (consumer-owned). The SITE-LOCAL DIVERGENCE block (consumer-specific path exclusions and LT denylist additions for `IN_PRINCIPAL`, `CONTRACT_CONTACT`, `TO_DO_HYPHEN`) was being clobbered on every prose-tooling sync. Long-term sidecar-config fix tracked at `agentnative-spec/.context/compound-engineering/todos/012-pending-p3-prose-check-sidecar-config-and-revendor.md`. - Vale file-pattern exemptions in `.vale.ini` updated for the renamed paths (`PRODUCT.md`, `DESIGN.md`) so the policy docs that legitimately enumerate banned fonts and aesthetics stop firing the rules they define. - Stale `.impeccable.md` references swept across `styles/site/BannedFonts.yml`, `styles/site/BannedAesthetics.yml`, `styles/site/README.md`, `scripts/check-banned-fonts.sh`. - Pre-existing biome and markdownlint blockers cleared (do.ts suppression named the wrong rule; vendored `coverage-matrix.json` flagged for format; one over-long bullet in `RELEASES.md`). ### Documentation - Broaden `RELEASES.md` "no explainer prose" rule from `## Summary` only to the entire PR body. Same do-not-paste guidance now covers every section. ## Type of Change - [x] `feat`: New feature (P8 + Inheritance section + Channel artifacts table) - [x] `refactor`: Code refactoring (PRODUCT.md / DESIGN.md renames, sync-prose-tooling.sh main-tracking, prose-check.sh un-vendor, OG version-source decoupling) - [x] `docs`: Documentation update (Voice register codification, Definition-as-card coupling note, RELEASES.md prose rule) - [ ] `BREAKING CHANGE`: not breaking (anchor slugs preserved, all `/p<n>` URLs stable, internal renames only) ## Related Issues/Stories - Story: None. - Issue: None. - Architecture: spec PR [#29](brettdavies/agentnative#29) (`release: PRODUCT.md migration + channel artifact stack docs`) merged to spec `main` 2026-05-13. - Related PRs: cli `docs/migrate-impeccable-to-product` and skill `docs/migrate-impeccable-to-product` (parallel migrations, not yet PRed). ## Testing - [x] Unit tests added/updated - [ ] Integration tests added/updated - [x] Manual testing completed - [x] All tests passing **Test Summary:** - Unit tests: 315 passing (regression #1 LOCKED_SLUGS extended to include `p8-discoverable-skill-bundle`; regression #2 llms.txt bullet count assertion updated to 8 in p1..p8 order; build.test.ts OG alt-text snapshot updated to the count-decoupled string) - Pre-push hook: passes (md-wrap, markdownlint 35 files / 0 errors, check-links 48 files, validate-principles 8 files / 57 IDs, pack-README drift, prose-check 0 blocking / 1100 warning) - Coverage: not measured for site (no coverage tool wired) ## Files Modified **Modified:** - Content: `content/_intro.md`, `content/about.md`, `content/check.md`, `content/install.md`, `content/methodology.md`, `content/scorecard-schema.md`, `content/changelog.md`, `content/principles/README.md`, `content/principles/VERSION` (and all `content/principles/p1-*.md` through `p7-*.md` reconciled to spec v0.4.0) - Build: `src/build/build.mjs`, `src/build/coverage.mjs`, `src/build/llms.mjs`, `src/build/scorecards-render.mjs`, `src/build/shell.mjs` - Voice docs: `docs/research/VOICE.md` - Scripts: `scripts/sync-prose-tooling.sh`, `scripts/SYNCS.md`, `scripts/og/og.html`, `scripts/og/generate.ts`, `scripts/check-banned-fonts.sh`, `scripts/design/generate-palette.mjs`, `scripts/prose-check.sh` - Styles: `styles/site/README.md`, `styles/site/BannedFonts.yml`, `styles/site/BannedAesthetics.yml`, `styles/brand/README.md`, `styles/config/vocabularies/brand/accept.txt`, `styles/config/vocabularies/site/accept.txt` - Vendored: `BRAND.md`, `scripts/generate-pack-readme.mjs`, `src/data/spec/` (vendored to v0.4.0), `src/data/coverage-matrix.json` - Top-level: `AGENTS.md`, `RELEASES.md`, `.vale.ini`, `biome.json` - Tests: `tests/build.test.ts`, `tests/regression.test.ts` - Worker: `src/worker/score/do.ts` - Public: `public/og-image.png` **Created:** - `content/principles/p8-discoverable-skill-bundle.md` **Renamed:** - `.impeccable.md` to `PRODUCT.md` - `docs/DESIGN.md` to `DESIGN.md` **Deleted:** - None. ## Breaking Changes - [x] No breaking changes. - [ ] Breaking changes described below. Anchor slugs preserved (`#p1-non-interactive-by-default` through `#p8-discoverable-skill-bundle` are permanent). Per-principle URLs unchanged for `/p1` through `/p7`; `/p8` is new. The `.impeccable.md` to `PRODUCT.md` and `docs/DESIGN.md` to `DESIGN.md` renames are source-tree paths, not user-facing URLs. ## Deployment Notes - [x] No special deployment steps required. - [ ] Deployment steps documented below. OG image regenerated as part of this PR (`public/og-image.png`). Cloudflare Worker deployment proceeds normally on merge. Social-share platforms cache OG previews aggressively; expect Twitter, Slack, etc. to keep showing the v0.3.0 card until they re-scrape `https://anc.dev/`. ## Checklist - [x] Code follows project conventions and style guidelines - [x] Commit messages follow Conventional Commits - [x] Self-review of code completed - [x] Tests added/updated and passing - [x] No new warnings or errors introduced - [x] Changes are backward compatible ## Additional Context This PR completes the site-side half of the cross-repo migration coordinated with `agentnative-spec`. Parallel work on `agentnative-cli` and `agentnative-skill` is staged on `docs/migrate-impeccable-to-product` branches in those repos pending separate PRs. The un-vendoring of `scripts/prose-check.sh` is a workaround. The long-term sidecar-config fix (Option C in the cross-repo migration analysis) is tracked upstream at `agentnative-spec/.context/compound-engineering/todos/012-pending-p3-prose-check-sidecar-config-and-revendor.md` (P3). When that lands, this site can re-vendor the script and drop the CONSUMER-OWNED header. The OG version-source decoupling is symmetric in spirit to the prose-tooling decoupling: both sever a coupling that made the site lag behind a downstream binary release. Per-tool badge SVGs intentionally remain coupled to each scorecard's `spec_version` since they describe the binary that scored that specific tool.
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
Ships PR #27 and PR #28 from
dev. No principle changes, noVERSIONbump; this release lands onmainwithout producing a tag, GitHub Release, or downstream dispatch (perRELEASES.md § Release gating).PR #27 broadens the No explainer prose anywhere in the body rule from
## Summaryto the whole template and adds a new No hard line wraps rule covering PR bodies, heredoc commit messages, and any markdown that ships verbatim to GitHub.PR #28 migrates the channel-design context filename from the legacy
.impeccable.mdto the canonicalPRODUCT.mdexpected by the/impeccableskill loader, and adds previously-implicit architectural self-documentation: a## Channel artifactstable inBRAND.md, a vendoring-source header that travels into consumer repos, a tier-3 location convention, an## Inheritancesection inPRODUCT.md, and a one-line canonical-filename policy inCONTRIBUTING.md. Theprinciples/AGENTS.mdreference sweep finished along with it;docs/architecture/voice-enforcement.mdupdates from the same PR stay ondev(guarded out ofmain).Changelog
Added
BRAND.md:## Channel artifactstable, vendoring-source header that travels into consumer repos, and a tier-3 location convention note.PRODUCT.mdgains an## Inheritancesection naming the spec channel's three-tier waterfall (universalBRAND.md, channel-deltaPRODUCT.md, authoritative principles/architecture/decisions).CONTRIBUTING.mdgains a one-line policy:PRODUCT.mdis the canonical channel-design context filename;.impeccable.mdis migrated atomically with no backward-compatibility shim.Changed
.impeccable.md→PRODUCT.mdacross the spec repo. Consumers vendoringBRAND.mdpick up the rename on their nextsync-prose-tooling.shrun.## Summary-only bullet; the same do-not-paste guidance now covers every section of the PR template.Linked check review
no check changes needed. This release ships only documentation and governance prose; no
requirements[]entry is added, removed, or re-tiered.Human reviewer
Reviewer: @brettdavies
AI disclosure
Cherry-picks, conflict resolution (dropping
docs/architecture/voice-enforcement.mdper the guard), triple-diff verification, and PR body drafted by Claude (Opus 4.7) in Claude Code under @brettdavies's direction. Upstream PR #27 and #28 bodies were human-reviewed at merge; the release-PR body repeats their## Changelogentries verbatim perRELEASES.md.