docs: sync the context-first policy with the ecosystem canonical - #1091
Merged
Merged
Conversation
Two corrections, one of which was actively costing time. The per-class OCCT reference manual IS indexed, as occt-refman, 37,008 sections. This repo's okf copy said it was not, which sent an agent to the bundled headers or to WebFetch as a first resort rather than a last one. This repo's own CLAUDE.md already documented occt-refman correctly, so the two disagreed, and the policy was the one an agent is told to treat as binding. And context query is now a lookup step in its own right: get_docs takes its library from an enum fixed when the MCP server connected, so anything installed by context add is invisible to it for the rest of the session while the CLI sees it immediately. Fixed upstream in neuledge/context#117. Copied verbatim from SecondMouseAU/ecosystem okf/policies/context-first.md.
Contributor
Code Review SummaryStatus: No Issues Found | Recommendation: Merge Files Reviewed (1 file)
Reviewed by nemotron-3-ultra-550b-a55b:free · Input: 196.6K · Output: 1.7K · Cached: 259.2K |
4 tasks
kilo-code-bot Bot
added a commit
that referenced
this pull request
Aug 25, 2026
…-backlog ## What & why Nine merges landed with a CHANGELOG entry written in the PR body that nobody copied into `docs/CHANGELOG.md`. `okf/policies/changelog-on-merge.md` names this as the failure the policy introduces, and names a batch transcription PR as the repair route, subject to two conditions this PR meets: it transcribes and does nothing else, and it was the only open PR touching the file when it was opened (checked against every open PR's file list, not assumed). Transcribed, newest merge first: #1122, #1112, #1097, #1079, #1069, #1053, #1043, #961, #870. #961 and #963 carry byte-identical entries, since #963 is the reapply of #961, so they land as one. After this the audit reports **0** entries in a PR body but not in the file, down from 9. Closes #1125 ## CHANGELOG entry None, this PR is the transcription. Adding an entry describing the act of transcribing entries would be the loop the policy's "the PR must transcribe and nothing else" condition exists to prevent. `docs/CHANGELOG.md` is expected in this diff: `changelog-on-merge.md` lists a batch transcription PR as one of its three exceptions. ## SemVer impact NONE. Documentation and one report script. No `Sources/` change, nothing a consumer can observe. ## Checklist - [x] New or changed behavior is covered by a unit test in the same PR (not just manual verification), see [SecondMouseAU/OCCTReconstruct#397](SecondMouseAU/OCCTReconstruct#397) for the ecosystem-wide test-coverage standard this is piloting. - [x] Every new test and every new `--self-test` case was run once with its subject broken, and the failure is reported here, see [okf/policies/prove-the-test-fails.md](../okf/policies/prove-the-test-fails.md). - [x] The CHANGELOG entry above is complete, and `docs/CHANGELOG.md` is **not** in this diff. **This is the batch-transcription exception**, named in `changelog-on-merge.md`; the file is in the diff by design and the section above says why there is no entry of its own. - [x] The SemVer impact above is stated, and `docs/SEMVER.md` is **not** in this diff. ## The two entries that could not be copied verbatim **#870 and #961 carry 17 em-dashes between them.** `okf/policies/writing-style.md` bans em-dashes "in every code comment, doc comment, markdown doc, **changelog**, commit message, and PR body", and instructs clearing them from any file you are already editing. `docs/CHANGELOG.md` contains **zero** today, so a verbatim transcription would have introduced the file's first ones. Each was repunctuated individually rather than by blanket substitution, using the replacements the policy itself names: a comma where the clause is parenthetical, a colon where it expands on what precedes it, a semicolon where both halves stand alone, and real parentheses for the one interrupted clause in #870. **Two headings were normalised.** #961/#963 led with a bold line where every entry in the file uses a `###` heading, which is what the page navigation keys on. #870's heading had no issue number and, after the em-dash repair, read with two colons; the trailing clause became its own sentence. The issue numbers added to both (`#382`, `#384`) come from the branch names the merges themselves record (`refactor/382-pass2a`, `reapply/384-pass3`), not from a guess. These are the only departures from verbatim, and they are the reason this PR touches the detector as well. ## The detector fix, and why it belongs here `entry_is_present()` matches an entry by looking for its first `###` or `- ` line as a substring of the changelog. Repunctuating a heading is therefore indistinguishable from never transcribing it, so **#870 would have been reported as missing forever, for having been transcribed correctly**. That is a report that cries wolf, and the next person either re-transcribes #870 (producing a duplicate) or starts ignoring the report. `entry_is_present()` now falls back to the part of the line before the first em-dash, and only when the PR body's own line contains one. The prefix must be at least 24 characters after the marker to count, so a heading that is mostly em-dash clause does not qualify and is still reported: a stub prefix would match almost anything and turn the relaxation into a rubber stamp. ## Prove-the-test-fails Two `--self-test` cases added, 23 to 25, both run with their subject broken: | Injected defect | Result | |---|---| | the em-dash fallback removed entirely | `FAIL #1125: a heading repunctuated to drop a banned em-dash is still found` (22/25) | | `MIN_DISTINCTIVE_PREFIX` dropped to 0, so any stub matches | `FAIL #1125: a heading with nothing distinctive before the em-dash is still MISSING` (22/25) | Each injection also trips the two pre-existing bucket-membership assertions, which is correct: those assert the exact contents of the `late` and `missing` sets, so a misclassified fixture has to show up in both places. 25/25 with neither defect. `Scripts/git-hooks/pre-commit` (every gate, both censuses, and the clang-format check) exits 0. ## Verification of the transcription itself The entries were extracted from the PR bodies programmatically rather than retyped, then checked: - no assembled heading duplicates one already in `docs/CHANGELOG.md` - triple-backtick fences balanced across the assembled block - em-dash count in `docs/CHANGELOG.md` after the change: **0**, unchanged - the resulting `## Unreleased` heading order is reverse-chronological by merge Spot-checked against the shipped tree rather than trusting the prose, since a wrong entry is worse than a missing one: `Shape.selfIntersects` exists and carries `@available(*, deprecated)` naming #1088 (`Shape+Topology.swift:92`), `Surface.nlPlateDeformed` and its siblings exist, and `Tests/OCCTXCAFTests/Issue1030DatumLookupGuardTests.swift` exists. ## Notes for the reviewer **16 merges have no entry section in the PR body at all**, so there is nothing to transcribe and they are deliberately not in this PR. Writing those is drafting, which `changelog-on-merge.md` explicitly assigns to the PR author rather than the merger ("The merger transcribes; they do not draft"). Classified, for whoever picks it up: - **9 legitimately None**: #858, #856, #874, #1091, #1120, #1114 (docs and okf policy), #907 (report-only script), #939 (SEMVER table plus an orphaned doc comment), #1115 (test-only). - **1 already covered**: #1103 is the merge of #1023 and #1068, whose entries are both in the file. - **5 internal refactors**, the same family that #870 and #961 did get entries for: #932, #934, #935, #937, #940. - **1 real behaviour change with no entry anywhere**: **#1113**, null-wire guards on 19 `ShapeAnalysis_Wire` bridge functions, a refusal where there was a crash. This one should not ship in a release with no entry. **6 more are "transcribed late"** and are correct in the file; the commit-level check asks what the merge did, so they are not retroactively fixable and need nothing. **1 is unverifiable**: `e6fdb4e8` has no PR number in its subject.
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.
Docs only, one file, copied verbatim from the ecosystem canonical (
fa596b5). The other 21 active repos took the same change directly; this repo requires a PR for thegate-scriptscheck.Two corrections
The per-class OCCT reference manual IS indexed, as
occt-refman, 37,008 sections, verified answering onBRepAlgoAPI_Fuseandgp_Pnt. This repo'sokfcopy said it was not, which sent an agent to the bundled headers or to WebFetch as a first resort rather than a last one.Worth noting for this repo specifically: its own
CLAUDE.mdalready documentedocct-refmancorrectly, so the two disagreed, and the policy is the one an agent is told to treat as binding.context queryis now a lookup step in its own right.get_docstakes itslibraryfrom an enum fixed when the MCP server connected, and the server rebuilds that list only for packages arriving through its owndownload_packagetool. Anything installed bycontext addis therefore invisible toget_docsfor the rest of the session, while the CLI sees it immediately. The failure reads as "package missing", which an agent takes at face value and escalates on, so the policy now says plainly that it means "not in the list I was handed". Fixed upstream in neuledge/context#117.Also records that the
ecosystempackage is now indexed, so the standard and every shared policy are themselves queryable, and what a version in the cache means: a package is pinned to a release and does not follow its repo.