[timeleft--]

Change

Documentation, tests, CI, repository metadata, and development checks alone no longer require product version bumps. The local updater classifies changed paths, so mixed product changes still bump the affected components. Explicit release_paths keep shipped Markdown, such as skills, prompts, templates, or rendered site pages, versioned where applicable.

The repository instructions and version-policy guide now match the checker. Product versions are unchanged by this policy update. Existing release controls and repository-specific version rules are preserved.

Existing product release paths cannot be removed or narrowed in a change PR.

Validation

Seven CLI regression scenarios pass: documentation and development-only changes, mixed code changes with a docs title, shipped Markdown, component isolation, removal of an unnecessary documentation bump, and malformed product-path configuration, and preservation of existing shipped-product paths. The current PR passes its local version check without a bump, and whitespace checks pass. The release-candidate channel behavior is preserved; all 35 release-channel tests pass.

[yia-mw-agent]

Helmet-Review-Request: #150 (comment)

Reviewed the full merge-base (f1c89ae, current main) to head 857d94d diff: 4 files, scripts/mw-version.py, .version-policy.json, docs/version-policy.md, AGENTS.md. No material defects.

Validation on the checked-out head:

• tests/test_release_channels.py: 35 passed.
• mw-version.py check on this PR: passes with no bump. The PR's CI checks (Version policy, both test jobs, CodeQL, Semantic PR) all pass.
• Throwaway-clone probes of the classifier. Docs/README-only, tests-only and .github/ changes need no bump. A stray unneeded bump on such a change is rejected. Product changes still require the bump: a src/** .py change, a src/** Markdown template, reader_templates/*.astro, AGENTS_USAGE_INSTRUCTIONS.md, a pyproject.toml dependency change, and scripts/bootstrap-data-repo.sh. Malformed release_paths fails with a clear PolicyError.

Non-blocking notes:

1. README.md is the PyPI long description and README.md, CHANGELOG.md, CONTRIBUTING.md and SECURITY.md are sdist inputs (pyproject.toml, [tool.hatch.build.targets.sdist]). They are exempt as *.md. If a README-only change should reach the PyPI page without a code change, add README.md to release_paths. Otherwise it ships with the next product release.
2. The existing guard rejects a PR that adds exclude_paths, but nothing stops a PR from removing release_paths. Doing so makes shipped Markdown under src/ exempt again (probe: passes with no bump). Mirroring the exclude_paths subset check for release_paths in evaluate (scripts/mw-version.py, near the exclude_paths guard) would close it. The checker script is itself PR-editable, so this is only defense in depth.
3. The six CLI regression scenarios in the PR description are not committed as tests; test_release_channels.py only covers the pre-existing channel behavior. Adding them to the test suite would protect the classifier against drift.
4. Pre-existing: if a configured mirror file such as uv.lock is deleted, the check fails with a raw [Errno 2] rather than a PolicyError. This PR does not change that.

[yia-mw-agent]

Helmet-Review-Request: #150 (comment)

Reviewed the full merge-base (f1c89ae, current main) to head 2642bb4 diff: 4 files, scripts/mw-version.py, .version-policy.json, docs/version-policy.md, AGENTS.md. No material defects.

What I checked:

• Read the diff against surrounding evaluate() logic. substantive_changes and release_changes run only when not promoting, so release promotion keeps its strict "version values only" rule. shared/unit-affected logic then sees only product changes.
• scripts/mw-version.py check --base origin/main on this head passes with no bump. This is correct, since the PR only changes policy, docs and the updater. The existing tests/test_release_channels.py passes: 35 passed with --noconftest, because pytest_asyncio isn't installed in this runtime. The PR's own Version policy and Validate PR checks pass. At review time only the test matrix jobs were still pending; I did not wait on them.
• Probe: temp git repos using this repo's real .version-policy.json, pyproject.toml, uv.lock and __init__.py, running check, update, then check again.
  • No bump (unchanged component): README, docs/, tests/, .github/, CHANGELOG.md, codev/*.md.
  • Bump to 0.8.6rc1, with the recheck passing: a new .py under src/ under a docs: title, src/fava_trails/**/*.md and src/fava_trails/docs/*, AGENTS_USAGE_INSTRUCTIONS.md, a pyproject.toml dependency change, and a uv.lock change.
  • Removing or narrowing release_paths against a base that already has it is rejected: "a change PR cannot remove release_paths that protect shipped product files".
  • The release_paths entries src/fava_trails/** and AGENTS_USAGE_INSTRUCTIONS.md match what the wheel and sdist ship from the repo (pyproject.toml force-include and sdist include). That also covers the *.md/docs/**/*.test.* defaults, which fnmatch would otherwise let swallow files under src/.
• The documentation, the AGENTS.md pointer, and the POINTER/WORKFLOW template in the script all agree. Version-only changes to mirror files are correctly not treated as substantive.

Non-blocking notes:

1. README.md and CHANGELOG.md are in the sdist, and README is the PyPI long description. Under this policy, edits to them no longer bump the version. That follows from the stated "documentation needs no bump" intent. If PyPI page freshness matters, add them to release_paths.
2. substantive_changes skips files that are missing at the base (new mirrors) and treats a deleted mirror file as an unhandled FileNotFoundError. The deleted-file crash predates this PR, so it is not a regression.
3. The new version_fields/configured_files overlap validation has no committed regression test. The PR description cites seven CLI scenarios, but none were added to the tests, so this behavior depends on future reviewers re-running probes.