Skip to content

README: a cross-reference to a section that was never written, and a gate for the class - #943

Merged
tannevaled merged 1 commit into
mainfrom
readme-dangling-divergences
Nov 15, 2026
Merged

tannevaled merged 1 commit into
mainfrom
readme-dangling-divergences

Conversation

@tannevaled

Copy link
Copy Markdown
Contributor

README: a cross-reference to a section that was never written, and a gate for the class

Under Kernel#fork the README said:

fork { ... } *does* exist and runs the block in the same process -- see the
table under *Known divergences*, because code that forks to isolate or to
drop privileges gets neither here.

⛔ There is no "Known divergences" table. git grep -i divergenc over every
markdown file in the repository returns that citation and nothing else.

The sentence names the stake exactly right -- a program that forks to drop
privileges drops none here -- and then sends the reader to the one place that
would have told them what to do about it, which does not exist.

The fix says the thing instead of promising it

The divergence is now inline, with the measurement: x = 1; fork { x = 99 }
leaves the parent's x at 99 where MRI 4.0.7 leaves it at 1 (measured today
through cmd/oracle), and the Integer returned is indistinguishable from a real
pid. The reason it exists -- Puppet::Util::Execution.execute is built on it --
is stated, and the open questions point at #774 and the parity plan #941.

The gate, measured before it was written

A guard on prose is worthless if it fires on prose that is fine, so the
population came first. TestReadmeCrossReferencesResolve finds every italic
phrase introduced by "see" or "under" and requires a heading or a bold run-in
item to name it:

*Set*  *Supported today* (x3)  *Running Puppet*  *Runtime conformance*
*Status*   -- and, until this change, *Known divergences*

8 before, 7 after, and NO false positives: emphasis such as fork { ... } *does* exist is not matched, because the italic has to follow "see" or "under"
immediately.

⛔ Proved by mutation, not by passing: putting the dangling reference back makes
it fail by assertion, naming Known divergences.

Two things the writing of it taught, both recorded in the test:

  • I counted the population BY HAND first and got 4. The regexp finds 8 -- my
    grep pattern only matched capitalised titles in one phrasing and silently
    missed three repeats and Status. A population counted by eye is what this
    test replaces.
  • The first draft logged "all resolve" unconditionally, and printed it directly
    under a failure it had just reported. A summary that contradicts its own
    output is how a reader learns to stop reading summaries; it now prints the
    dangling tally.

⛔ It also flattens the README before matching, because "see Set under
\nSupported today" wraps across two source lines and a line-based check sees
neither half.

Refs #774, #941

Co-Authored-By: Claude Opus 5 noreply@anthropic.com

…gate for the class

Under Kernel#fork the README said:

    fork { ... } *does* exist and runs the block in the same process -- see the
    table under *Known divergences*, because code that forks to isolate or to
    drop privileges gets neither here.

⛔ There is no "Known divergences" table. `git grep -i divergenc` over every
markdown file in the repository returns that citation and nothing else.

The sentence names the stake exactly right -- a program that forks to drop
privileges drops none here -- and then sends the reader to the one place that
would have told them what to do about it, which does not exist.

## The fix says the thing instead of promising it

The divergence is now inline, with the measurement: `x = 1; fork { x = 99 }`
leaves the parent's x at 99 where MRI 4.0.7 leaves it at 1 (measured today
through cmd/oracle), and the Integer returned is indistinguishable from a real
pid. The reason it exists -- Puppet::Util::Execution.execute is built on it --
is stated, and the open questions point at #774 and the parity plan #941.

## The gate, measured before it was written

A guard on prose is worthless if it fires on prose that is fine, so the
population came first. TestReadmeCrossReferencesResolve finds every italic
phrase introduced by "see" or "under" and requires a heading or a bold run-in
item to name it:

    *Set*  *Supported today* (x3)  *Running Puppet*  *Runtime conformance*
    *Status*   -- and, until this change, *Known divergences*

8 before, 7 after, and NO false positives: emphasis such as `fork { ... } *does*
exist` is not matched, because the italic has to follow "see" or "under"
immediately.

⛔ Proved by mutation, not by passing: putting the dangling reference back makes
it fail by assertion, naming *Known divergences*.

Two things the writing of it taught, both recorded in the test:

- I counted the population BY HAND first and got 4. The regexp finds 8 -- my
  grep pattern only matched capitalised titles in one phrasing and silently
  missed three repeats and *Status*. A population counted by eye is what this
  test replaces.
- The first draft logged "all resolve" unconditionally, and printed it directly
  under a failure it had just reported. A summary that contradicts its own
  output is how a reader learns to stop reading summaries; it now prints the
  dangling tally.

⛔ It also flattens the README before matching, because "see *Set* under
\n*Supported today*" wraps across two source lines and a line-based check sees
neither half.

Refs #774, #941

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@tannevaled
tannevaled merged commit 4b0256e into main Nov 15, 2026
26 checks passed
@tannevaled
tannevaled deleted the readme-dangling-divergences branch November 15, 2026 12:29
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