docs(agents): state the no-comments rule for code this repository owns (#218) by ericlitman · Pull Request #219 · ericlitman/open-pstack

ericlitman · 2026-10-16T22:23:27Z

Part of #218.

Summary

 # open-pstack
 ...
 The parent harness resolves provider routing once. Children do not detect or reroute themselves.
 
+Code this repository owns explains itself. UPSTREAM.md, CHANGES.md and NOTICE.md say which
+files are local adaptations or additions. Upstream-derived files keep upstream's comments, so
+later syncs stay clean. In owned code, a comment stays only if it is a legal or license header,
+an explanation of behaviour forced by a vendor, platform or protocol we cannot change, a
+formatter directive, a doc comment that defines a public API contract, or an issue or RFC link
+for a constraint that code cannot express. ... pstack's `no-comments` skill applies this rule.

One paragraph in AGENTS.md. The comment sweeps of local code follow in separate PRs, one per directory, after this one merges.

Evidence

Before: AGENTS.md states no rule for comments, so agents match the surrounding comment density.
After: AGENTS.md states the keep-list, the reshape and encode rules, and the suppression rule, scoped to owned code.

Live gate features (AGENTS.md is a consumed-instruction path, so classification reaches only project-skill):

claude:project-skill: proves the installed candidate still discovers and runs the repository-local verifier with the changed AGENTS.md loaded. Classification adds codex:project-skill.

Merge Danger

Door: two-way

Blast Radius: instructions

Agents that read this repository's AGENTS.md delete or reshape comments in owned code. Upstream-derived files are excluded by name, so an upstream sync is unaffected.

Acceptance criteria

"AGENTS.md states the rule above for content this repository owns." Verified by the diff above: the paragraph carries the five keep-list items, the reshape rule, the encode-then-delete rule and the suppression rule, and scopes them to owned code through UPSTREAM.md, CHANGES.md and NOTICE.md.
The sweep, verify and follow-up-issue criteria are covered by the sweep PRs.

Gate results

On head 457457b:

Check	Exit
`bun run test` (501 tests)	0
`bun run typecheck`	0
`bun run static` (166 tests)	0
`claude plugin validate plugins/pstack`	0

Not verified

The comment sweep itself is not in this PR.

🤖 Generated with Claude Code

#218) Owned code keeps a comment only for a license header, a vendor, platform or protocol constraint, a formatter directive, a public API doc comment, or an issue or RFC link. Upstream-derived files keep upstream's comments so syncs stay clean. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

mergify · 2026-10-16T22:24:04Z

Merge Protections

🟢 All 2 merge protections satisfied — ready to merge.

Show 2 satisfied protections

🟢 Queue ready pull requests

Automatically queue non-draft pull requests targeting main after verify, Unfret, and live-gate pass on the head and every review thread is resolved.

🟢 🚦 Auto-queue

When all merge protections are satisfied and these conditions match, this pull request will be queued automatically.

-files~=^\.github/
base = main

ericlitman · 2026-10-16T22:25:32Z

Live evidence: Open Pstack

Candidate SHA: 457457bb508533bccacddc38f7afceabeb64a5be
Base SHA: 54169c26711a77b4f5337d969681032bef6eb1d0
Result: PASSED — named features verified
Self-test: not requested
Planned sessions: 2 (limit 12)
Publisher revision: 457457bb508533bccacddc38f7afceabeb64a5be
Evidence-set SHA-256: bfa78767cd0967b08d214b5d31f17aa4ce86259b4352d0df53f400b1bc437f54
Installation (claude): CLI 2.1.302 (Claude Code), plugin 1.15.0, candidate 457457bb508533bccacddc38f7afceabeb64a5be, tree bc0a3990e5f96077709e96b8702bb2a078d053aafbcdb1e748628c9892c14f3a.
Installation (codex): CLI codex-cli 0.163.0, plugin 1.15.0, candidate 457457bb508533bccacddc38f7afceabeb64a5be, tree bc0a3990e5f96077709e96b8702bb2a078d053aafbcdb1e748628c9892c14f3a.
Observation (claude / project-skill): surface claude -p stream-json with the candidate plugin-dir; action recipe project-skill: doctor; result passed: doctor:exit-0 doctor:skill-loaded doctor:doctor-ran doctor:doctor-canonical-pass; 4 assertions machine-checked; transcript SHA-256 25782e9834df31f3bfb1a0582ce7c5403a7297f8bced60d34deaf0b564e39204; artifact-set SHA-256 8f529c53f490c5384773c245bf2985689eb1278c84f9da51c7c77bfe3890499e.
Observation (codex / project-skill): surface codex exec --json with the run-owned candidate installation; action recipe project-skill: doctor; result passed: doctor:exit-0 doctor:skill-loaded doctor:doctor-ran doctor:doctor-canonical-pass; 4 assertions machine-checked; transcript SHA-256 b04b06aae43566df1b8ff64d967ef927706970c37ee5bdfba2a4a12c5a9eada7; artifact-set SHA-256 9b5e33971d4fad40dc4bea42b10ce21935b6dd790dad7b505ffa4d7bc4c1ffaa.
Policy: every new head requires a fresh run; this verifier does not change PR state, queue, or merge.

greptile-apps · 2026-10-16T22:25:39Z

[Medium impact] The instruction change appears safe to merge.

Summary

Adds the repository's comment policy to AGENTS.md.

Repository agents now follow a clear rule for comments in owned code.

No actionable defects found.

_{Reviews (1) · Last reviewed commit: "docs(agents): state the no-comments rule..." · Reviewed by Greptile}

unfret-eal · 2026-10-16T22:26:31Z

✅ No blocking findings

Light review ran with 1 elected reviewer.

Walkthrough

Adds one paragraph to `AGENTS.md` that sets a comment policy for code this repository owns, so agents stop copying the surrounding comment density. Upstream-derived files keep upstream's comments, and `UPSTREAM.md`, `CHANGES.md` and `NOTICE.md` decide which files count as owned. In owned code, only five kinds of comment are kept. Surprising code should be reshaped rather than explained, "must not change" constraints should be encoded as types, tests or lints, and lint or type suppressions are allowed only for wrong or style-only rules. The actual comment sweeps of local code are deferred to later per-directory PRs, and the author reports tests, typecheck, static checks and plugin validation passing on the head.

Details

Lane / stage	Model	Effort	Outcome	Duration
focal-gpt-5.6-sol-xhigh copy / review	openai/gpt-6.1-sol → gpt-6.1-sol · primary	xhigh	succeeded	2 min 39 s

First review of this pull request.
1 reviewer finished.
Commit 457457b.
Check run.
Run: GET /unfret/run/panel:457457bb508533bccacddc38f7afceabeb64a5be:QaNV565m6Qf:k0UJnbqc-tI.

_{@unfret review · @unfret status · @unfret help}

unfret-eal

✅ No blocking findings
Check

mergify · 2026-10-16T22:27:17Z

ericlitman added the light:457457bb508533bccacddc38f7afceabeb64a5be label Oct 16, 2026

ericlitman marked this pull request as ready for review October 16, 2026 22:23

unfret-eal Bot reviewed Oct 16, 2026

View reviewed changes

mergify Bot merged commit 894570e into main Oct 16, 2026
7 checks passed

Navigation Menu

Repository navigation

docs(agents): state the no-comments rule for code this repository owns (#218) - #219

docs(agents): state the no-comments rule for code this repository owns (#218)#219
mergify[bot] merged 1 commit into
mainfrom
docs/218-no-comments-rule

ericlitman commented Oct 16, 2026

Uh oh!

mergify Bot commented Oct 16, 2026 •

edited

Loading

🟢 Queue ready pull requests

🟢 🚦 Auto-queue

Uh oh!

ericlitman commented Oct 16, 2026

Uh oh!

greptile-apps Bot commented Oct 16, 2026 •

edited

Loading

Uh oh!

unfret-eal Bot commented Oct 16, 2026 •

edited

Loading

Uh oh!

unfret-eal Bot left a comment

Uh oh!

mergify Bot commented Oct 16, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

ericlitman commented Oct 16, 2026

Summary

Evidence

Merge Danger

Acceptance criteria

Gate results

Not verified

Uh oh!

mergify Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge Protections

🟢 Queue ready pull requests

🟢 🚦 Auto-queue

Uh oh!

ericlitman commented Oct 16, 2026

Live evidence: Open Pstack

Uh oh!

greptile-apps Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

unfret-eal Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ No blocking findings

Uh oh!

unfret-eal Bot left a comment

Choose a reason for hiding this comment

Uh oh!

mergify Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge Queue Status

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

mergify Bot commented Oct 16, 2026 •

edited

Loading

greptile-apps Bot commented Oct 16, 2026 •

edited

Loading

unfret-eal Bot commented Oct 16, 2026 •

edited

Loading

mergify Bot commented Oct 16, 2026 •

edited

Loading