Skip to content

Release policy: AGENTS.md and CONTRIBUTING.md are release-neutral - #68

Merged
Deicyde merged 1 commit into
mainfrom
claude/release-neutral-agent-docs
Oct 17, 2026
Merged

Deicyde merged 1 commit into
mainfrom
claude/release-neutral-agent-docs

Conversation

@Deicyde

@Deicyde Deicyde commented Oct 17, 2026

Copy link
Copy Markdown
Owner

Problem

site/ops/brain_release_authority.py decides whether main may move past a built release's authority commit. Under its rule that non-README Markdown is release-affecting by default, AGENTS.md and CONTRIBUTING.md currently count as release-affecting. docs/BRAIN-ACTIVATION-2026-10-04.md:132-133 records this. Both files are agent and contributor guidance:

  • No build, reducer, public-asset, or Worker step reads either file. Code in brain/, site/, wiki/scripts, wiki/src, wiki/assets and catalog/ never opens them. No brain/*_profiles.json or attestation pins them.
  • CLAUDE.md and HANDOFF.md are already neutral, and AGENTS.md mirrors CLAUDE.md.

As things stand, a docs-only edit to AGENTS.md blocks promotion of an already-built release. The open PRs #50 and #54 both edit AGENTS.md.

Change

  • Add AGENTS.md and CONTRIBUTING.md to NEUTRAL_FILES.
  • Tests in site/ops/test_brain_release_authority.py:
    • Assert that both root files are neutral.
    • Assert that same-named files elsewhere (brain/AGENTS.md, wiki/src/CONTRIBUTING.md) stay release-affecting.
    • New test_neutral_files_are_outside_the_nightly_source_check. The policy's comment says it must agree with site/ops/brain-nightly.sh's own release-affecting source check: the git status --porcelain -- … list at line 824, plus the reducer scope that list expands from brain/authority/reducer-inputs-v1.json. The test parses that list and fails if any explicitly neutral file falls inside it. It handles bare and quoted paths, directories, globs, and .. It also fails if the parse finds the wrong command.

Agreement with the nightly

I checked this before editing anything. Neither file is in the nightly's watched list (wiki/, site/assets, the named brain/ and site/ops/ files, the reducer scope). So the two policies agree on these files, and brain-nightly.sh needs no edit. No Brain profile registry (brain/*_profiles.json) pins either file or brain_release_authority.py.

The policy id wikilean.release-neutral-paths/v1 stays the same. It is held in memory only; promotion intents record just the neutral_changes list. Widening the set never invalidates a list recorded earlier.

How tested

  • python3 site/ops/test_brain_release_authority.py: 8 tests pass locally (Python 3.12).
  • Mutation checks:
    • Adding CLAUDE.md, "AGENTS.md", '*.md' or . to the nightly's watched list in a temp copy makes the new test fail.
    • Adding wiki/AGENTS.md to NEUTRAL_FILES makes it fail.
  • CI does not run this test file yet. The companion PR "CI: run every tracked test file" adds it to scripts/ci-python.sh. Until both merge, the local run is the evidence.

Risks

  • The new test reads the formatting of brain-nightly.sh. If that command is reformatted beyond recognition, the test fails loudly rather than passing.
  • These are pre-existing and this PR does not change them, so I'm flagging them for a decision:
    • bot/ is a neutral directory, but brain/authority/reducer-inputs-v1.json:36-40 declares bot/state/{cut_log,seed_queue,recycle_queue,brain_queue,pool_candidates}.json as curated_git_input that brain/build_cells.py reads. A main that changed only those files would pass the neutral check, even though a rebuild would produce different cells. (bot/state/ on main is a frozen snapshot now, which limits how often this can happen.)
    • The nightly watches site/ops/brain-canary.py and all of wiki/, while the policy treats brain-canary.py, wiki/README.md, wiki/test/ and wiki/e2e/ as neutral. That looks deliberate: those paths affect validation, not release bytes. But it means the module's "the two policies must agree" comment holds only for AFFECTING_EXCEPTIONS.

What Jack must do

  • Nothing operational.
  • After merge, docs/BRAIN-ACTIVATION-2026-10-04.md:125-133 will be out of date. It lists the neutral set without these two files and says they "are currently release-affecting". That doc is handled separately.

Release-neutral (per site/ops/brain_release_authority.py): the PR changes only site/ops/.

Both are contributor/agent guidance that no build, reducer, or Worker step
reads, but as non-README Markdown at the root they were release-affecting by
default, so a docs-only edit (for example the AGENTS.md changes in open PRs)
would block promotion of an already-built release. Neither file is in
brain-nightly.sh's release-affecting source check or the reducer scope, so the
two policies still agree; a new test parses that check and fails if any
explicitly neutral file falls inside it.
@Deicyde

Deicyde commented Oct 17, 2026

Copy link
Copy Markdown
Owner Author

Verdict: ready to merge. CI is green. One doc follow-up is needed after merge.

  • The pre-push review confirmed that nothing in brain/, site/, wiki/ or catalog/ reads either file, and no profile registry pins them. So brain-nightly.sh needs no edit.
  • The review also showed the first version of the new agreement test missed quoted paths, globs and .. I fixed that before pushing, and checked the fix with mutations.
  • CI doesn't run site/ops/test_brain_release_authority.py until CI: run every tracked test file #70 merges. Until then, the local run (8 tests OK) is the evidence.
  • After merge, docs/BRAIN-ACTIVATION-2026-10-04.md:125-133 still says these two files are release-affecting. It needs a one-line update.
  • Open for a decision, not fixed here: the policy treats bot/ as neutral, but five bot/state/*.json files are inputs to the Brain build (see Risks).

@Deicyde
Deicyde merged commit a359fd0 into main Oct 17, 2026
4 checks passed
Deicyde added a commit that referenced this pull request Oct 17, 2026
Review fixes:
- The AFFECTING_EXCEPTIONS comment called brain-nightly.sh's
  uncommitted-source check "broader". It is a different set: it watches
  code, not curated inputs, so it covers Worker tests, READMEs and the
  canary but never bot/state/ or catalog/data/. The comment also gave a
  reason for site/test_frontier_page.py that other neutral gating tests
  contradict; it now just names the file.
- The curated-input test reads every brain/authority/reducer-inputs-v*.json,
  not only v1.
- The canary test's comment says it checks only the files the nightly names
  explicitly.
- docs/BRAIN-ACTIVATION-2026-10-04.md is a record checkable at 37b7036, so
  its neutral list is restored and one sentence notes #68's and this PR's
  changes. The operator runbook's neutral list gains the bot/state
  exception instead.
Deicyde added a commit that referenced this pull request Oct 17, 2026
Release policy: AGENTS.md and CONTRIBUTING.md are release-neutral
Deicyde added a commit that referenced this pull request Oct 17, 2026
brain/authority/reducer-inputs-v1.json declares five bot/state/*.json
files as curated_git_input, read by brain/build_cells.py, but bot/ is a
neutral directory, so a commit changing one let main move past a release
built from the old bytes. They are now affecting exceptions, and a test
checks every reducer scope file and curated input against the policy.

The comment on AFFECTING_EXCEPTIONS claimed the list must agree with
brain-nightly.sh's uncommitted-source check. That check is broader: it also
refuses local edits to Worker tests, READMEs and site/ops/brain-canary.py,
none of which reach release bytes. The comment now says so, and a test pins
the canary as the only file the nightly names that the policy leaves
neutral. docs/BRAIN-ACTIVATION-2026-10-04.md's copy of the neutral list
picks up these exceptions and #68's AGENTS.md and CONTRIBUTING.md.
Deicyde added a commit that referenced this pull request Oct 17, 2026
Review fixes:
- The AFFECTING_EXCEPTIONS comment called brain-nightly.sh's
  uncommitted-source check "broader". It is a different set: it watches
  code, not curated inputs, so it covers Worker tests, READMEs and the
  canary but never bot/state/ or catalog/data/. The comment also gave a
  reason for site/test_frontier_page.py that other neutral gating tests
  contradict; it now just names the file.
- The curated-input test reads every brain/authority/reducer-inputs-v*.json,
  not only v1.
- The canary test's comment says it checks only the files the nightly names
  explicitly.
- docs/BRAIN-ACTIVATION-2026-10-04.md is a record checkable at 37b7036, so
  its neutral list is restored and one sentence notes #68's and this PR's
  changes. The operator runbook's neutral list gains the bot/state
  exception instead.
@Deicyde

Deicyde commented Oct 19, 2026

Copy link
Copy Markdown
Owner Author

Re-review on main (eaa5950b): fine. No code or config reads AGENTS.md or CONTRIBUTING.md into release, public-asset or Worker bytes. I grepped about 690 code and config files at main. The only mentions are prose, one comment and one error message. wiki/src imports no Markdown, and pipeline agents run outside the checkout with setting_sources=[]. The NEUTRAL_FILES test catches a broken policy.

Stale, small:

  • site/ops/brain_release_authority.py:68 still says "Markdown is neutral only as a README or under a neutral directory". Four root Markdown files are in NEUTRAL_FILES.
  • The module docstring's "a new file or directory is never silently neutral" doesn't hold for new files under a neutral directory, or for new README.md and test_*.py files. That gap is how the bot/state issue (site/ops: the reducer's bot/state inputs are release-affecting #75) arose.

Pre-existing, your call: .gitattributes is in NEUTRAL_FILES, but a root .gitattributes with eol rules would change how wiki/src checks out without showing up as a release-affecting diff. It doesn't exist on main, so dropping it costs nothing.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant