Skip to content

AGENTS.md follow-up: apply the #3785 review points that did not land - #3912

Open
mcfnord wants to merge 6 commits into
jamulussoftware:mainfrom
mcfnord:agents-3785-followup
Open

AGENTS.md follow-up: apply the #3785 review points that did not land#3912
mcfnord wants to merge 6 commits into
jamulussoftware:mainfrom
mcfnord:agents-3785-followup

Conversation

@mcfnord

@mcfnord mcfnord commented Aug 18, 2026

Copy link
Copy Markdown
Contributor

🤖 AI: Follow-up to #3785, on the invitation there. Six one-line changes; each traces to a point raised in that review, each stands alone, and any can be dropped if it fails the stable-and-general bar. Cost, measured: AGENTS.md 651 → 740 words.

Short description of changes

AGENTS.md:

  • Testing names the build it needs. The Build line's CONFIG+=headless serveronly binary rejects the Testing line's client — built from 11a28d57 and run: ./Jamulus -n -c localhostClient only option(s) '--connect' used. See '--help' for help, exit 1. One clause closes the contradiction (raised in review, pljones preferring the plain build).
  • Never Do gains the wire-format contract: never renumber PROTMESSID_* or alter an existing message layout — retired IDs stay reserved as OLD in src/protocol.h, exactly the invariant an agent breaks while tidying "unused" enums.
  • Always gains the rule the file's evidence lines rest on: test a claim before writing it, or cut it — a hedge (should, presumably, likely) is an untested claim in disguise, and comments, docs and commit messages are claims too. A wrong doc paragraph outlives a wrong assertion in a PR thread, because it is what the next reader trusts.
  • Style surfaces the trap Jamulus.pro's own clang_format note documents: a new source directory or file extension needs CLANG_FORMAT_SOURCES, coding-style-check.yml and .clang-format-ignore updated together, or local make clang_format and CI check different files.
  • Duplicates cut, per the 2026-07-28 brevity pass: "One logical change per PR" and "Builds? Tested? Smallest change possible?" repeat line 5 and the Testing/Always lines in a file prepended to every prompt.

docs/agents/COMMENTING.md: the first bullet keeps only its posting-specific half, deferring the general test-or-cut rule to the always-loaded file; the last bullet was the fragment "Disclose AI-generated text" and now carries the form.

CHANGELOG: SKIP

Context: Fixes an issue?

Follow-up to #3785.

Does this change need documentation? What needs to be documented and how?

No — it is documentation.

Status of this Pull Request

Ready for review. One commit per change, so any line is droppable in isolation.

What is missing until this pull request can be merged?

Maintainer judgment on which lines clear the "stable and general" bar.

Checklist

  • I've verified that this Pull Request follows the general code principles
  • I tested my code and it does what I want — the one testable claim (a serveronly binary rejects -c) was built and run; output above. No code is changed.
  • My code follows the style guide — Markdown only.
  • I waited some time after this Pull Request was opened and all GitHub checks completed without errors.
  • I've filled all the content above

🤖 This message was written by AI and reviewed by @mcfnord.

jrd and others added 6 commits August 18, 2026 07:38
"Always" tells an agent to attach evidence and to disclose what it did not
verify, but not what to do with a claim it cannot test. One line closes that,
names the hedge words as the detectable symptom, and extends the rule to code
comments, docs and commit messages.

docs/agents/COMMENTING.md opened with the same rule scoped to posting; with the
general form in the always-loaded file, that bullet keeps only its posting half.

CHANGELOG: SKIP

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The Build line offers a CONFIG+=headless serveronly build; the Testing line
then connects a client. That binary rejects -c:

    $ ./Jamulus -n -c localhost
    ./Jamulus: Client only option(s) '--connect' used.  See '--help' for help
    (exit 1; built from 11a28d5)

One clause closes the contradiction.

CHANGELOG: SKIP

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Retired message IDs are kept reserved in src/protocol.h (seven OLD entries,
one marked 'needed for compatibility to old servers >= 3.4.6 and <= 3.5.12')
rather than reclaimed — the invariant an agent breaks while cleaning up
unused enums. Stated as one Never Do bullet.

CHANGELOG: SKIP

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Jamulus.pro (clang_format target), coding-style-check.yml, and
.clang-format-ignore each carry a comment telling the editor to update the
other two; none of the three is a file an agent reads before it bites.
One Style bullet surfaces it.

CHANGELOG: SKIP

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
'One logical change per PR' and 'smallest change' are line 5, bold, above the
fold; 'Builds? Tested?' are the Testing and Always lines. This file is
prepended to every prompt, so each repeat costs context on every call.
'See CONTRIBUTING.md' stays in Read when relevant, where it carries a
when-to-read note.

CHANGELOG: SKIP

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The last bullet was the fragment 'Disclose AI-generated text' — no form, no
example, while AGENTS.md carries the complete rule. Give it the form and
point at the canonical statement.

CHANGELOG: SKIP

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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