[nissa-seru]

This keeps a comment in src/, test/ and scripts/ only where it says something the code can't show, under the rule below, and removes the rest: 1,189 comments in the 28 files it covers become 106. It leaves out the 14 files already on main in those folders that the open #11 changes. Once comments are removed, the code in the 28 files is the same as on main, apart from six small reshapes that put into code what a removed comment said.

The rule

A comment stays only if it is one of these:

• a license header;
• a directive to a tool;
• a doc comment that defines a public contract. For a server people run, that covers what an operator sets or an agent meets that README.md, docs/ and deploy/github-mcpl.env.example don't already state, such as the webhook endpoint's status codes, the rollback receipt, the thread forms the tools accept, and the end-to-end host's command vocabulary that docs/e2e-report.md points to;
• a note on behaviour that something outside the code forces, such as GitHub's REST and GraphQL APIs and webhooks, octokit, MCPL and @animalabs/mcpl-core, Node, npm or Markdown, where reshaping the code to show it would add complexity;
• a link to an issue or RFC that explains a constraint the code can't express.

The 28 files hold no license headers and no directives.

What changes

• 5642690 holds every line written by hand, apart from 5b73310's and the merge's. That's the comments that stay, cut down to the part the rule allows and corrected where they didn't match the code, and the six reshapes. Where a reshape carries a removed comment's meaning, that comment's removal is in this commit too. It touches 23 files, with 203 lines added and 640 removed, as git counts them.
• 8a33bab removes every other comment, and 114 blank lines, and changes no code: Bun 1.4.4's transpiler, which drops comments, gives identical output for all 26 files at 5642690 and at 8a33bab. The commit touches 26 files, with 1 line added and 2,013 removed. The added line is maxCheckedPulls: 0, without its trailing comment.
• 5b73310 changes one comment that stays, in renderReviewThreads (src/content.ts:153–154), to name unresolve_thread beside resolve_thread as a tool that takes the review thread's GraphQL node id. It touches 1 file, with 2 lines added and 2 removed.
• 9c562c2 merges main at 7eaea03, which carries Report a write tool's outcome as unknown when GitHub's answer is lost or is a 5xx #17 and Run the test files in one process, and test the dedup ring and the changelog script in process #18, to resolve the conflicts Run the test files in one process, and test the dedup ring and the changelog script in process #18 made in scripts/release-changelog.mjs and src/webhook.ts.
• bd9f4bb: we judged the comments the merge brought into these files, five lines in two blocks, and this commit removes one block:
  • the two lines Report a write tool's outcome as unknown when GitHub's answer is lost or is a 5xx #17 added above FakeGitHub in test/lost-answer.test.ts go. They said what the fake's 'lost' answer does, and what it stands in for, "a connection that drops after GitHub stored a write", which fits none of the rule's items.
  • the three lines Run the test files in one process, and test the dedup ring and the changelog script in process #18 added above isMain in scripts/release-changelog.mjs stay, as a note on behaviour that Node forces: "import.meta.url names the script's real path, and argv[1] the path it was run by, which a symlink can differ from".
• The counts take each // line and each block comment as one comment. Of the 106 that stay, 53 are in src/, 40 in test/ and 13 in scripts/. This pull request changes 26 of the 28 files. scripts/release-changelog.d.mts and test/release-changelog.test.ts hold no comments on main.
• The six reshapes:
  • four tests in test/poller.test.ts seed their pull request with createdAt: '2026-10-01T00:00:00.000Z', the default that test/harness.ts already gives it;
  • test/toolsIssuesPr.test.ts and test/toolsReview.test.ts name their undefined as unknown as StateStore store NO_CHECKPOINT_STORE;
  • TEXT_KINDS becomes NEW_TEXT_KINDS in test/tags.test.ts;
  • test/state.test.ts names the path it loads with no file there, const absent = tempFile();
  • src/poller.ts gains HEAD_BACKLOG_DRAIN_PASSES = 10, and MAX_HEAD_BACKLOG becomes HEAD_BACKLOG_DRAIN_PASSES * MAX_CHECKED_PULLS_PER_POLL, which is 200, as before;
  • scripts/e2e/host-lifecycle-check.mjs names its 400 ms delay IDLE_BEFORE_INPUT_MS.
• Not changed: README.md, docs/ and CHANGELOG.md. There's no changelog fragment.

Scope

The 14 files left out are src/feature-sets.ts, src/github-adapter.ts, src/index.ts, src/server.ts, src/tools-issues-pr.ts, src/tools-read.ts, src/types.ts, test/githubAdapter.test.ts, test/harness.ts, test/integration.test.ts, test/smoke.test.ts, test/toolsRead.test.ts, test/webhook.test.ts and test/wp8-docs.test.ts. #11 changes each of them at its head 9127a61, and this pull request changes none of them, so the two change no file in common.

Tests

• Comments only, apart from the reshapes: we transpiled each of the 28 files at main (7eaea03) and at bd9f4bb with Bun 1.4.4's transpiler, which drops comments. 21 files give identical output. The 7 that differ are the files the six reshapes touch. No file outside the 28 changes.
• The suite at bd9f4bb, on Linux, in a clean checkout: npm ci, npm run typecheck and npm run build succeed on Node 24.22.1. We ran the command that npm test runs, with a TAP reporter added, on Node 24.22.1 and on Node 22.12.0. Each run has 617 tests: 597 pass, 18 are skipped, and 2 fail.
• The suite before the merge, on Linux with Node 24.22.1, at 5b73310 and at c243333, each in a clean checkout: npm ci, npm run typecheck and npm run build succeed. npm test runs 606 tests at each, of which 586 pass, 18 are skipped and the same 2 fail.
• The 2 failures, in all four runs, are README tests in test/wp8-docs.test.ts: "the credential split creates both files at mode 600" and "an empty host reaches the registration script by following step 1". In the runs before the merge, the first stopped at jq: not found, and the second at git's "fatal: repository … does not exist" for the repository's own path.

Not verified

• The reshape in scripts/e2e/host-lifecycle-check.mjs. The script ends with 0 of its 7 cases passing at c243333 and at 5b73310 alike, so no run checks that reshape.
• A live GitHub connection. Ten test files use an in-memory fake of GitHub's API (FakeGitHubApi in test/harness.ts), and test/githubAdapter.test.ts runs a fake GitHub HTTP server on 127.0.0.1.

---

Ogden-2688 made the change and the merge of main, and judged the merged-in comments with Agnes-984. Esther-2584 read 5642690, 8a33bab, 5b73310 and the merge. Daniel-2612 wrote this description.

[github-actions]

Automated review

Recommendation: needs a maintainer's decision. The project states too little to tell whether the change belongs.

Reviewed commit 8a33bab 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?

The project states too little to tell. This PR applies a comment policy the project never states. It cuts 1,188 comments to 103 in 26 files, against a codebase whose current habit is dense explanatory comments.

5 reasons with sources

Whether the project wants that policy is for the maintainers to decide, and nothing in the repository settles it.

• The project says nothing about how much to comment code, so the PR's rule comes from the contributor, not the project. README.md covers purpose, setup and behaviour (push events, channels, feature sets with rollback, no merge), and the repository has no contributing guide or rule files. docs/ only uses the word 'comment' for GitHub comments. The five-part rule in the PR description has no basis in any project document. (README.md)
• The existing code is heavily commented, so the code itself suggests the maintainers chose to write long explanatory comments. The 26 files held 1,188 comments before the change. Many give reasons: the fake-host header explains why a fulfilled RPC is not a pass, why the shutdown grace is ten seconds, and why stdio is piped. Others link to task IDs (TASK-SRHKG.1.10) and spec sections (§14.3). The PR removes these as a matter of policy. (scripts/e2e/fake-host.mjs (base), src/ and test/)
• The change adds no feature, dependency or public interface, and doesn't touch the architecture. Besides deleting comments, the PR makes six small reshapes: new constant names such as HEAD_BACKLOG_DRAIN_PASSES (MAX_HEAD_BACKLOG stays at 200), NO_CHECKPOINT_STORE and IDLE_BEFORE_INPUT_MS, plus a few edits to test fixtures. None of them changes the code's structure or behaviour. (src/poller.ts)
• The policy covers only part of the codebase, so files under the same folders would follow two comment styles. The PR leaves out 14 files in src/ and test/, including server.ts, index.ts, github-adapter.ts and harness.ts, because the open #11 changes them. Until a follow-up covers them, those files keep the old dense comments next to the 26 trimmed ones. (PR scope vs. src/ and test/ layout)
• Some comments that stay were rewritten, and the code review found a few of those no longer state things correctly. The code review found shortened or rewritten comments that are now inaccurate (content.ts:152-153, release-changelog.mjs:23-25, errors.ts:1-5). These are defects for the author to fix, not reasons for this verdict. They do show that the rewrite changes documentation content as well as deleting it. (src/content.ts, scripts/release-changelog.mjs, src/errors.ts)

Findings

No findings of medium or high severity.

4 more findings, less severe

• Low severity, documentation, src/content.ts:152-153. Shortened comment names only resolve_thread as taking the thread's node id. The rewritten comment in renderReviewThreads says t.id is "the GraphQL node id resolve_thread takes". The original also named unresolve_thread, which takes the same id (see TOOL_UNRESOLVE_THREAD and requireThreadOnPull in src/tools-review.ts). A reader may conclude that only one tool uses this id.
• Low severity, documentation, scripts/release-changelog.mjs:23-25. Rewritten comment wrongly says Node writes to pipes asynchronously on all of POSIX. The old comment said the stderr write to a pipe is asynchronous on macOS. The new one says "Node writes to a pipe asynchronously on POSIX". As I understand Node's process I/O notes, pipe writes on process.stdout/stderr are synchronous on Linux and asynchronous on other platforms such as macOS. If so, the corrected comment is now wrong for Linux, which is the platform the PR's own test runs used. Either restore the platform qualifier or just say the write can be asynchronous.
• Low severity, documentation, src/errors.ts:1-5. New errors.ts header garbles the rule it cites. The header now says "a method that will never be answered must return an error, and a host's rejection is a JSON-RPC error object". The errors in this module are raised by this server's handlers, not by a host. The old text said the actual rule: a handler that cannot answer returns a JSON-RPC error object with a documented code, never silence and never a failure-flag result. The rewrite makes it unclear who must do what.
• Low severity, maintainability, test/toolsIssuesPr.test.ts:19. NO_CHECKPOINT_STORE is duplicated across two test files. The reshape adds the same const NO_CHECKPOINT_STORE = undefined as unknown as StateStore; in test/toolsIssuesPr.test.ts and test/toolsReview.test.ts. Only the review file keeps the comment explaining why the store is absent. The shared harness is the natural home, but it is off-limits here because #11 touches it. Note this as a follow-up so the two copies don't drift.

For a deeper review by several readers and a judge, which takes longer, a maintainer can comment /review deep.