Repository navigation
feat(prose-check): move stack to dev-only (docs, hook, guard, dev-direct note) - #45
Merged
Merged
Conversation
The Vale rule packs and the prose-check orchestrator are contributor tooling that enforces voice on PR work. They live on the dev branch and never need to ship to main: sync-spec.sh does not vendor them, nobody scores or audits against them, and downstream consumers have no use for them. Reframe the references in PRODUCT.md, BRAND.md, AGENTS.md, principles/AGENTS.md, and CONTRIBUTING.md so the narrative tier (BRAND.md, PRODUCT.md) is named as the authoritative voice contract and the packs are described as enforcement tooling on dev.
The same hook ships to main and dev (per the project's keep-hooks- in-sync convention), but the prose-check stack itself is moving to dev-only. Detect the absence of styles/, .vale.ini, or the orchestrator at hook time and skip the stage with a warning rather than fail — normal on main, abnormal on dev.
The reusable guard-main-docs workflow hardcodes the engineering-docs path list. Until it accepts an extra_paths input, enforce the spec-repo-specific dev-only paths (styles/, .vale.ini, scripts/prose-check.sh) inline alongside the reusable caller. Retire when the reusable workflow gains parameterization.
Engineering docs (docs/architecture/, docs/plans/, etc.) and the prose-check stack (styles/, .vale.ini, scripts/prose-check.sh) live only on dev and are blocked from main by guard-main-docs. Document that they may be committed directly to dev without a feature branch or PR; the standard PR flow remains required for everything else.
brettdavies/.github PR #30 added an extra_paths input to the reusable guard-main-docs workflow. Drop the local inline guard-prose-check-stack job in favor of passing styles/,.vale.ini,scripts/prose-check.sh through that input. Pinned at @dev as a smoke test until the .github repo cuts its own release carrying the input; flip to @main after that release lands.
brettdavies
added a commit
that referenced
this pull request
May 30, 2026
…to dev-only (#46) ## Summary Move the prose-check stack (Vale rule packs at `styles/`, `.vale.ini`, the `scripts/prose-check.sh` orchestrator) off `main` entirely. The packs and the orchestrator are contributor tooling that govern how the spec is authored on `dev`; nothing downstream consumes them. `sync-spec.sh` vendors only `principles/p*-*.md`, `VERSION`, and `CHANGELOG.md`, and the standard's contract is the principles, not the rules that gate prose-about-the-principles. PR #45 (already on `dev`) landed the evergreen half: doc repoints in `PRODUCT.md`, `BRAND.md`, `AGENTS.md`, `principles/AGENTS.md`, and `CONTRIBUTING.md` to name `BRAND.md` and `PRODUCT.md` as the authoritative voice contract; pre-push hook graceful skip when the stack is absent; dev-direct commit exception in `RELEASES.md` for engineering docs and the prose-check stack; and `.github/workflows/guard-main-docs.yml` switching from a local inline guard to the reusable `brettdavies/.github` guard-main-docs workflow's new `extra_paths` input (`styles/,.vale.ini,scripts/prose-check.sh`). This release branch carries those evergreen changes plus the actual file deletions. After this lands, the global guard blocks `styles/`, `.vale.ini`, and `scripts/prose-check.sh` from ever being re-added to `main` via a PR. No `VERSION` bump and no `CHANGELOG` entry: the standard's contract (principles, requirement IDs, tiers) is unchanged; `publish.yml` does not fire because neither `principles/p*-*.md` nor `VERSION` is touched. ## Changelog ## Linked audit review no audit changes needed. Repository-hygiene change with no `requirements[]` impact and no consumer-facing surface affected. ## Human reviewer **Reviewer:** @brettdavies ## AI disclosure Cherry-pick, deletion staging, triple-diff verification, commit messages, and this PR body were AI-drafted (Claude Opus 4.7) from the maintainer's directives; the architecture call (move the prose-check stack to dev-only) is human (@brettdavies).
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
Reposition the prose-check stack (Vale rule packs at
styles/,.vale.ini, thescripts/prose-check.shorchestrator) as dev-only contributor tooling. The narrative tier (BRAND.md,PRODUCT.md) is named as the authoritative voice contract; the packs encode the literal phrases for enforcement on contributor PRs againstdev. Five shipped-to-main docs (PRODUCT.md,BRAND.md,AGENTS.md,principles/AGENTS.md,CONTRIBUTING.md) lose their "executable contract atstyles/spec/" framing in favor of the new narrative-is-canonical phrasing. The pre-push hook gains a graceful skip so the same hook ships to bothdev(stack present, runs) andmain(stack absent, warn + skip). A local guard step in.github/workflows/guard-main-docs.ymlblocksstyles/,.vale.ini, andscripts/prose-check.shfrom being added to or modified onmainPRs, alongside the reusable engineering-docs guard.RELEASES.mddocuments the dev-direct commit exception (same treatmentdocs/plans/already enjoys) for both engineering docs and the prose-check stack.This is the evergreen half of the architecture correction. The actual file deletions on
main(styles/,.vale.ini,scripts/prose-check.sh) happen in a follow-up branch cut frommainonce this lands.Changelog
Changed
styles/brand/,styles/spec/),.vale.ini, andscripts/prose-check.share now dev-only contributor tooling.BRAND.mdandPRODUCT.mdare named as the authoritative voice contract in their place; the packs enforce on contributor PRs againstdevand do not ship tomain.scripts/hooks/pre-pushgracefully skips the prose-check stage with a warning when the stack is absent (normal onmain), instead of failing..github/workflows/guard-main-docs.ymlpassesstyles/,.vale.ini,scripts/prose-check.shasextra_pathsto the reusablebrettdavies/.githubguard-main-docs workflow (@main, afterbrettdavies/.githubPR chore(launch): spec polish — prose tooling, plan close-outs, README version pin #31 released the input). The prose-check stack is now blocked frommainPRs by the global guard rather than a local inline job.RELEASES.mddocuments the dev-direct commit exception covering engineering docs (docs/architecture/,docs/plans/, etc.) and the prose-check stack.Linked audit review
no audit changes needed. Repositioning of dev tooling and supporting governance prose; no
requirements[]changes, no tier moves, no frontmatter shape changes.Human reviewer
Reviewer: @brettdavies
AI disclosure
The styles/ reference rewrites, the pre-push graceful skip, the local guard step, the dev-direct exception note, and this PR body were AI-drafted (Claude Opus 4.7) from the maintainer's directives; the architecture decision (move the stack to dev-only) is human (@brettdavies).