Skip to content

Guard the telemetry disclosure, and unwind the README's em-dashes - #24

Merged
mattpodwysocki merged 2 commits into
mainfrom
telemetry-readme-guard
Sep 15, 2026
Merged

mattpodwysocki merged 2 commits into
mainfrom
telemetry-readme-guard

Conversation

@mattpodwysocki

Copy link
Copy Markdown
Contributor

Two things, both about the README saying what it means.

A guard, because the disclosure already drifted once

The Privacy section claimed we collect exit codes, which we never have; described the command/ marker as a command name when it's the service; and didn't mention the terminal markers at all, which go out on every request. Prose and code drifted because nothing compared them.

every_telemetry_marker_is_disclosed now does, in the blunt spirit of the other guards in that file. A table pairs each marker with the words in README.md that disclose it, and it fails in both directions:

# disclosure removed from the README
README.md's Privacy section no longer says "stdin and stdout are attached to a
terminal", which is what discloses the `stdin_tty/` marker. Either put it back
or update DISCLOSED.

# marker added to telemetry.rs
telemetry_markers gained or lost a marker. Add a DISCLOSED row and a sentence
in README.md's Privacy section, then update this count.

Both verified by making them happen, rather than trusting a green tick. It doesn't prove the disclosure is well written — only that nothing we send is missing from it, and that the sentence disclosing something can't quietly be edited away.

The prose

Twenty-nine em-dashes, nearly all the same sentence — explanatory clause habit. At that consistency it reads as machine-written, which it largely was. Gone, mostly by ending the sentence or using a colon where a list actually follows.

The densest paragraph got restructured rather than repunctuated. "Fifteen agents are known" now says supported, and the three flags that were buried in the same paragraph as a fifteen-item list are a table, which is how this README presents flags everywhere else:

Flag What it does
--agent <name> Install for one agent. Repeatable.
--global Write to the agent's home directory instead of this project.
--dir <path> Write to a directory you name, for a Dockerfile or a CI job.

Also unpicked two over-long sentences — the 40-word one about command groups versus spec files, and the 36-word one about signed builds.

One em-dash stays, deliberately

Dry run — nothing was sent. is quoted output, and executor.rs:606 prints it with the dash. I flattened it at first, which made the README misquote the binary, and reverted.

Worth knowing there are four more of those in agent_skills.rs (Dry run — nothing was written/changed/removed). Changing the strings the binary prints is a different decision from editing docs, so I left them; say the word if you want them too.

No fenced block changed at all — verified by diffing the set of code-block lines before and after, so every command and every sample output is byte-identical. Only prose moved.

602 tests, fmt and clippy clean, and no in-page anchor broken.

Two things, both about the README saying what it means.

**A guard, because the disclosure drifted once already.** The Privacy section
claimed we collect exit codes, which we never have; called the `command/`
marker a command name when it is the service; and did not mention the terminal
markers at all, which go out on every request. Prose and code drifted because
nothing compared them.

`every_telemetry_marker_is_disclosed` now does, in the blunt spirit of the
other guards here: a table pairs each marker with the words in README.md that
disclose it, and the test fails in both directions. Removing the terminal
sentence reports which marker it was disclosing; adding a marker fails a count
whose message names the README as the thing to update. It does not prove the
disclosure is *well* written, only that nothing we send is missing from it.
Both failures verified by making them happen.

**And the prose.** Twenty-nine em-dashes, nearly all of them the same
"sentence — explanatory clause" habit, which reads as machine-written when it
is that consistent. They are gone, mostly by ending the sentence or using a
colon where a list actually follows.

The densest paragraph got restructured rather than repunctuated. "Fifteen
agents are known" now says "supported", and the three flags that were buried
in the same paragraph as a fifteen-item list are a table, which is how this
README presents flags everywhere else.

Also unpicked a few over-long sentences: the 40-word one about command groups
and spec files, and the 36-word one about signed builds.

**One em-dash stays, deliberately.** `Dry run — nothing was sent.` is quoted
output, and `executor.rs:606` prints it with the dash. I had flattened it,
which made the README misquote the binary; reverted. No fenced block changed
at all — checked by diffing the set of code-block lines before and after, so
every command and every sample output is byte-identical.

596 tests, fmt and clippy clean, and no in-page anchor broken.
@mattpodwysocki
mattpodwysocki requested a review from a team as a code owner September 15, 2026 17:18
zmofei
zmofei previously approved these changes Sep 15, 2026
 was the last British spelling left in it.
@mattpodwysocki
mattpodwysocki merged commit 65a0105 into main Sep 15, 2026
8 checks passed
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.

2 participants