[nissa-seru]

This keeps only five kinds of comment in conformance/ and conformance-uri-reference.js:

• legal or license headers;
• non-obvious behaviour forced by a dependency, platform or protocol that the code can't be reshaped to make clear;
• directives;
• doc comments that define a public API contract;
• issue or RFC links that explain a constraint the code can't express.

Every other comment goes. Where a cut would leave the code unclear, the code is reshaped instead. Comments only change, apart from those reshapes.

What stays

• Outside behaviour: Bun 1.3.14 omitting ServerResponse.close on a client abort; fetch()'s decoding of data: URLs; the process-global Host caches keyed by URI; git's --untracked-files override; realpath on both sides of the main-module check; the URL parser dropping leading spaces and reading a scheme in any case; Agent Framework's MAX_RECORDS behind registryQuota; the URL constructor rejecting an invalid port or host; the generator's ECMAScript/JCS escaping, -0 and shortest-digit notes.
• A directive: the generator's shebang.
• Links: RFC-005 for the 16-code-unit rejected-value rule, row 18's label characters and §11's rule for a label's tabs and line breaks, and why the adapter binds each reference before rendering; SPEC §19.6.1 for the credential policy; RFC 8785 §3.2.2 and JCS's member order in the cross-check; RFC-003 §3.1 and §3, and SPEC §17.2, for the set and identifier positions and totality; mcpl-core-ts#6 and MCPL 0.5: RFC-001 tags, capability paths, inference/lifecycle, and the RFC-003 manifest digest Anarchid/mcpl-core#3 for the totality vectors.

Most of what the checker's and adapter's comments said is in RFC-005 §11 ("Running and consuming the executable vectors" and "Vector and adapter contract"), so those comments go and the adapter keeps a one-line link to it.

Reshapes

• crosscheck.mjs and generate_vectors.py name the list-index path segment LIST_INDEX. generate_vectors.py also names MEMBER_NAMES ("#key") and ELEMENTS ("[]").
• The display-profile test names its label letter letterInNoStubOrMarker.

Checks at 515dea2

• Strip check: stripping every comment but directives from main and from this branch leaves exactly those renames. The JavaScript is stripped with an oxc-based comment stripper that keeps directives, and generate_vectors.py with Python's tokenizer, dropping its # comments; the trees are compared with git diff --no-index.
• Runs, on Linux with Node 24.22.1, Bun 1.4.4 and Python 3.13.5:
  • python3 conformance/generate_vectors.py --check reproduces the committed vectors (25 vectors, 4 sort vectors);
  • node conformance/crosscheck.mjs passes its 24 checks;
  • bun test passes the runner and fixture tests, 46 of 46;
  • node conformance-uri-reference.js runs to the end.
• Not run: the checker's command line, the adapter and the isolation test, whose code is byte-identical to main's once comments are stripped. The runner tests exercise the checker's module.

Where a comment disagreed with the code, this leaves the code as it is.

Written by Petra-1012 (Claude Opus 5.5). Ogden-2688 (Claude Opus 5.5) read the change before it opened.

[github-actions]

Automated review

Recommendation: merge. The review found nothing of medium or high severity.

Reviewed commit 58e0d23 with claude-opus-5-5, by reading the code. It did not run the code or look at the checks.

Does this change belong in the project?

It fits the project. This PR only trims comments and renames a few constants in the existing conformance suite, and it changes no behavior, so it fits. The project has no comment policy to judge it against, and the explanations it removes are still in RFC-005 §11 and conformance/README.md.

5 reasons with sources

• It works on code the project already has and adds no new feature, file, dependency or interface. The diff only touches comments in conformance/*.mjs, generate_vectors.py and conformance-uri-reference.js. It also adds LIST_INDEX, MEMBER_NAMES, ELEMENTS and letterInNoStubOrMarker in place of literal values. The vectors and the checker's behavior are unchanged. (conformance/README.md)
• The project says nothing about comment style, so the five-kinds rule is the contributor's choice and not something the project asked for. There are no contributor or agent instruction files, and neither README sets a comment policy. Nothing in the project argues against this cleanup either, so a maintainer may want to say whether this style is wanted from now on. (README.md)
• The removed checker and adapter explanations are already written down in RFC-005 §11. §11 covers several things the removed comments said: the 16-code-unit rejected-value rule, the label's tab and line-break context, the meaning of $ORIGIN/$CASE/$LOCAL_PAYLOAD, the settle window, and the fact that the display profile is a policy rather than a protocol limit. The adapter now links to §11. The RFC also says "The supplied adapter documents the observation shape in code." The object the adapter returns still shows that shape, so removing these comments only loosely touches that sentence and does not break it. (RFC-005-bulk-content-references.md §11 "Vector and adapter contract")
• The rule that the crosscheck shares no code with the generator is still stated in the conformance README. The README describes crosscheck.mjs as an "Independent Node verifier, sharing no code with the generator" and explains its JCS approach. Removing the header comment from the file therefore does not lose that design rule from the project. (conformance/README.md (file table and §2))
• It is one coherent change, not a bundle of unrelated work. Every edit removes or rewords a comment or names a literal value, and all of them are in the conformance suite. (conformance/)

Findings

No findings of medium or high severity.

10 more findings, less severe

• Low severity, maintainability, conformance/crosscheck.mjs:1-6. Cross-checker loses its in-file note that it must share no code with the generator. The removed header said that crosscheck.mjs deliberately shares no code with generate_vectors.py, and that it builds JCS from JavaScript's own JSON.stringify plus a key sort. That independence is the whole value of the script (conformance/README.md §2 counts it as one of "three implementations that share no code"). Nothing in the file says so any more. A maintainer could reasonably deduplicate LIST_INDEX/SET_PATHS with the generator, or swap in a JCS library, without knowing that this would defeat the cross-check. A one-line pointer to the README would preserve the constraint.
• Low severity, maintainability, conformance/crosscheck.mjs:78-81. The naive-sort 'DIVERGES' note is now unexplained output. The block that sorts with default sort() and prints "(note) ... DIVERGES" does not affect fails. The removed comment explained that it is there to show the UTF-8 sort vector bites, meaning the vector catches a naive UTF-16 comparator. Without it, the block looks like leftover debug output that a maintainer might delete, losing the evidence that README §2 quotes.
• Low severity, documentation, conformance/generate_vectors.py:150-151. IDENT_PATHS comment claims to be SPEC §17.2's identifier positions but leaves out capability member names. The new comment calls IDENT_PATHS "SPEC §17.2's identifier positions, and each tag's facet". SPEC.md §17.2 (around line 2187) lists "capability member names at every depth" first among the identifier positions. IDENT_PATHS does not include them; they are checked separately by _is_capability_member_name_path in normalize. The old comment said only "positions whose string values are IDENTIFIERS", so it made no claim to be the full list. A maintainer who trusts the new wording could add capability paths here as well, or could think they are not checked at all.
• Low severity, documentation, conformance/generate_vectors.py:187-190. _path_matches comment now mentions only set paths, though it also matches identifier paths. The rewritten comment says "SPEC §17.2's set paths are written against the object-keyed featureSets shape ... so '*' never matches a list index". _path_matches is also used by _is_ident_path against IDENT_PATHS, and the old comment said "set/identifier paths". Readers are no longer told that the list-index exclusion also turns off identifier checks inside an array-shaped featureSets. That is a deliberate totality rule (SPEC §17.2: no identifier check on non-conforming shapes).
• Low severity, documentation, conformance/generate_vectors.py:943-945. SORT_VECTORS comment trimmed so it no longer says why the vectors exist. The comment now says only that no set-valued array in the 0.5 shape can hold a non-ASCII string. The removed sentence was the one that justified SORT_VECTORS: they test the comparator directly so the UTF-8 rule stays pinned for future set-valued fields. Without it, the comment reads as an argument that these vectors are unreachable and could be deleted, which is the opposite of what it meant.
• Low severity, maintainability, conformance/agent-framework-bulk-references.mjs:72-73. Conditional dispatch of the evicted lookup is left unexplained after its comment was removed. evictedError calls viaTool only when evicted === null and otherwise returns a { notDispatched: ... } placeholder. The removed comment gave the reason: this lookup has no fetcher, so a Host that kept the id should fail on the eviction assertion and not on a dispatch that cannot answer. The PR says code is reshaped wherever a cut would leave it unclear, but this branch got neither a reshape nor a link to RFC-005, and its purpose cannot be worked out from the code.
• Low severity, documentation, conformance/agent-framework-bulk-references.mjs:49-57. RFC-005 says the supplied adapter documents the observation shape in code, but those comments were removed. RFC-005 §11 (RFC-005-bulk-content-references.md line 534) tells adapter authors that "The supplied adapter documents the observation shape in code." This change removes the adapter's explanations of what each lane is and what the fetch dispatch observes. Examples are "The history lane is the tool-history serializer applied to the blocks", the wake-predicate note, and the description of what viaTool exercises and what the adapter supplies. What remains is only the return-object literals, so the RFC now points other implementers at documentation that is no longer there. Either keep these as contract doc comments (one of the kinds the PR says to keep) or update the RFC sentence.
• Low severity, documentation, conformance/check-bulk-references.mjs:17. Exported expand loses the comment that defines its placeholder contract. expand is exported and used by the tests and by other consumers. The removed comment defined what $ORIGIN, $CASE (URL-encoded id) and $LOCAL_PAYLOAD stand for. The PR says doc comments that define a public API contract stay, but this one was deleted with no link to RFC-005 §11, where the contract is now written down only in prose. The same applies to the exported semanticStrings: its comment said object keys count because a Host can put a value in a key, and RFC-005 does not state that rule anywhere.
• Low severity, maintainability, conformance/check-bulk-references.mjs:230-262. Unexplained difference: hidden values are matched across joined pieces, but includes only within one piece. checkHidden joins the pieces before searching, so a hidden value split across two pieces is still caught. The includes check uses pieces.some(piece => piece.includes(...)), so an expected text must appear inside a single piece. The two removed comments were the only record that this difference is deliberate. A maintainer "harmonizing" the two checks would weaken the hidden-value check or make the includes check looser.
• Low severity, maintainability, conformance/bulk-reference-runner.test.mjs:73-75. Sizes in the unreadable-local-URI test cases are now unexplained. The loop over [['...;base64,AA-_', 3], ['data:audio/wav;case=11-data-refused', 30], ['file://exa mple/x.wav', 19]] declares a specific sizeBytes for each URI. The removed comment said each size is what a looser reading would give, which is what makes the test bite. Without it, the 3/30/19 values look arbitrary, and a maintainer could change them so that the test no longer catches a lenient localPayload implementation.