Skip to content

chore: remove non-necessary comments under ADR 0110 - #1087

Merged
kyle-sexton merged 1 commit into
mainfrom
chore/comment-sweep-necessary-posture
Nov 21, 2026
Merged

kyle-sexton merged 1 commit into
mainfrom
chore/comment-sweep-necessary-posture

Conversation

@kyle-sexton

Copy link
Copy Markdown
Member

Refs: melodic-software/control-hub#12

Summary

Audit all 147 in-scope code and config files in melodic-software/standards under the ADR 0110 necessary comment posture and remove clearly non-necessary comments (pure section banners, decorative comment rulers, and obvious helper/parameter restatements).

Fix

Pure deletions only (23 files changed, 148 lines deleted, 0 lines added):

  • Removed pure # --- / // --- section banners and decorative // ---...--- ruler borders across .cursor/install.sh, .cursor/install.test.sh, PSScriptAnalyzerSettings.psd1, components/claude-lanes/repin-callers.test.sh, components/cloud-environment/pages-publish, components/code-review-rules/code-review-rules.{sh,test.sh}, components/commit-convention/commit-convention.test.sh, components/local-lane-guards/local-lane-guards.test.sh, components/lychee/private-repo-inventory.{sh,test.sh}, components/managed-files-guard/managed-files-guard.test.sh, components/markdownlint/home/.markdownlint-cli2.jsonc, components/markdownlint/markdownlint-home.test.sh, components/org-architecture-pointer/org-architecture-pointer.{sh,test.sh}, components/pr-convention-policy/lockstep-{behavior,drift}{,.test}.mjs, components/runner-policy/runner-policy.test.mjs, distribution/sync-manifest.mjs, and harness/shell/lib.test.sh.
  • Removed three obvious helper/parameter restatements in .cursor/install.sh and two misplaced/restatement signature comments in components/managed-files-guard/managed-files-guard.test.sh.
  • Preserved all decision, invariant, contract, exclusion, regression, and workaround comments (including all org-level rationale in distribution/sync-manifest.yml and .github/workflows/pr-require-checks.yml), all lint/tool directives, shebangs, and byte-parity-checked files (components/cloud-bootstrap/cloud-bootstrap.sh, .claude/**, fixtures/, evals/, vendor/).

Verification

  • Confirmed git diff has 0 added lines (pure deletions only) and all 23 modified files remain UTF-8 without BOM and LF-only.
  • Ran bash -n on all 15 modified shell scripts: all passed.
  • Ran bash harness/shell/run-tests.sh on 12 suites (lib.test.sh, local-lane-guards.test.sh, code-review-rules.test.sh, org-architecture-pointer.test.sh, private-repo-inventory.test.sh, pages-publish.test.sh, setup.test.sh, cloud-bootstrap.test.sh, repin-callers.test.sh, comment-hygiene.test.sh, machine-path-patterns.test.sh, .cursor/install.test.sh): 12 passed, 0 failed, 0 skipped.
  • Verified code-review-rules.sh file, org-architecture-pointer.sh file, and check-exec-bit.sh pass locally; full CI (CI Status) and review lanes will run on this PR.

Related

  • melodic-software/control-hub#12

Refs: melodic-software/control-hub#12

Remove pure section banners, decorative comment rulers, and obvious helper/parameter restatements across 23 files (148 deletions, 0 insertions) while preserving all decision/invariant/contract comments, tool directives, shebangs, and byte-parity-checked files.
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 21, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-21T20:29:04.619888Z fda7a51 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@github-actions

Copy link
Copy Markdown

claude-security-review reviewed fda7a511a6a44836952e33cb4f05a978f5ec1fce: read 23 of 23 changed file(s); 0 finding(s), 0 as inline comments.

Security review: PR #1087

I found no security issues in this pull request.

I read every hunk of all 23 changed files in the full diff (148 lines removed, none added). Every removed line is a comment:

  • Section banners: headers like # --- … --- and decorative // ---…--- rulers in the shell, .mjs, .psd1 and .jsonc files.
  • Comments that restate code: three helper/parameter comments in .cursor/install.sh (put_bin, write_stamp, install_engine) and two signature comments in components/managed-files-guard/managed-files-guard.test.sh (check_shape, materialize).

What I checked:

  • Code and config behaviour: no executable statement, lint or tool directive, shebang, pin or configuration value changed. The removals in components/cloud-environment/pages-publish, distribution/sync-manifest.mjs and components/pr-convention-policy/lockstep-drift.mjs are only comment lines. The comments that explain behaviour around them, and the code they describe, are unchanged. That covers token handling, the temp-dir path check, the publish scan and the git index plumbing.
  • Removed instructions: none of the deleted lines is a standing instruction (CLAUDE.md, AGENTS.md, a rules file, a skill or agent body, or a hook's block or allow list). None stated a rule, so no guardrail is gone. Because nothing qualified, I did not consult the protected-class register.
  • Trust controls: no changed file is a trusted path (trusted-actor list, check-trusted-trigger, CODEOWNERS, .gitmodules). None touches a trust control (token broker, kill switch, merge holds, .github/actions/*). No merge hold is weakened.
  • Plugin manifests: no .claude-plugin/plugin.json or marketplace.json changed.
  • Other inputs: the PR description contains no embedded directives. This is the lane's first review of the PR, so there were no prior findings and the review was not blocking-only.

critical-findings: 0

@github-actions

Copy link
Copy Markdown

claude-review reviewed fda7a511a6a44836952e33cb4f05a978f5ec1fce: read 23 of 23 changed file(s); 0 finding(s), 0 as inline comments.

Code review: PR #1087, no findings

I read every hunk in all 23 changed files. Each one only deletes comment lines: section banners, decorative ruler lines, and comments that restate a helper's signature. No code, config value, directive or shebang changes. The PR does not close an issue (it says Refs: melodic-software/control-hub#12), so there are no acceptance criteria to check.

What I checked:

  • Deleted comments that recorded a decision (the REVIEW.md "Always check" rule on deleted comments): every deleted comment either labels a section or restates code. The comments that explain decisions stay next to the code: the /exec-daemon PATH-shadowing note in .cursor/install.sh, the source-of-truth and 404 notes in repin-callers.test.sh, the scan-shape note in pages-publish, and the behavioral-layer notes in lockstep-drift.mjs. The removed signature comments for put_bin, write_stamp and install_engine repeat what the code shows: install_engine assigns $1–$5 to dest, version, url, sha and member (install.sh#L160-L165). The removed check_shape comment in managed-files-guard.test.sh sat above title_case, which is the wrong function.
  • Copies that must match byte for byte: none of the removed banner text appears anywhere else in the repository. The header of components/markdownlint/home/.markdownlint-cli2.jsonc says its config block is byte-identical to the root config. The root .markdownlint-cli2.jsonc never had the two removed // --- banners, and markdownlint-home.test.sh compares the parsed config key. So the change keeps parity and the test is not affected.
  • Settings files: in PSScriptAnalyzerSettings.psd1 and the home markdownlint config, only comments go. Rule keys and values are unchanged.
  • Line-count audit notes in distribution/sync-manifest.yml#L917-L920 give PSScriptAnalyzerSettings.psd1 as "138 lines vs 141". After this PR the file has 4 fewer lines. That note is a dated audit record ("Recorded 2026-08-16"), not a check, so I am not raising it as a finding.

Loosened checks: the change loosens no check. It skips no test, changes no assertion, threshold or suppression, and makes no check accept more. The prompt had no loosened_check_verdict: or loosened_check_patterns: line, so I used fail with no consumer entries. It had no loosened_check_decision_record: line either, so I did not check whether a citation was required.
Loosened checks would be marked: fail (plugin default); patterns: 0

Not checked: I did not open the standards index for paved paths. The change adds no new way of doing anything, so I report nothing about paved paths.

PR's own test claims, not confirmed by me: the PR says bash -n, 12 harness suites and the local checks passed. I had no shell and ran none of them.

The PR context and prior-findings files contain no embedded instructions. There were no earlier reviews of this PR, so this was a full review, not a blocking-only one. No path-scoped rule matches the changed files: .claude/rules/pr-body-contract.md has no paths: glob.

Verifier dropped 0 of 0 candidates.

@kyle-sexton
kyle-sexton merged commit 2da84e8 into main Nov 21, 2026
34 checks passed
@kyle-sexton
kyle-sexton deleted the chore/comment-sweep-necessary-posture branch November 21, 2026 20:31
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