Skip to content

docs: pinned numbers may move either way with a stated reason - #767

Merged
dean0x merged 3 commits into
mainfrom
docs/766-ratchet-either-way
Nov 5, 2026
Merged

dean0x merged 3 commits into
mainfrom
docs/766-ratchet-either-way

Conversation

@dean0x

@dean0x dean0x commented Nov 5, 2026

Copy link
Copy Markdown
Owner

Summary

The ratchet rule said a floor may only rise and a ceiling may only fall, with one exception for a prompt's compiled-size ceiling. The guard can not see a direction. It checks that each pinned value is present in its source file at the recorded number of sites. This PR makes the written rule match what the guard enforces, and it names the record that a move needs.

  • Any floor or ceiling may move up or down.
  • The entry's description and the PR body give the old value, the new value and the reason.
  • The lean-prompts goal stays: the bytes that a typical run reads should not grow. A ceiling rise states its reason.
  • An older description or test comment that states a one-way rule is history. This rule replaces it.

Changes

  • CLAUDE.md (Test Ratchets): the one-line rule. The file stays at 13,069 chars, under its 13,071 ceiling.
  • docs/reference/lean-prompts.md: rule 1 of "Rules for every target" and step 5 of "Cut rules".
  • docs/reference/file-organization.md: the tree note of the manifest.
  • tests/fixtures/numeric-floors.json: the top comment only.
  • tests/guards/numeric-floor-manifest.test.ts: the header, the comments, the failure message and the test titles. The non-vacuity probe now moves one site one step down and one step up for every entry. So it shows that a change in only one file fails in both directions.
  • tests/docs/lean-prompts-guide.test.ts: the wording pins follow the new text.

Pinned values

No pinned value changes. A jq comparison of every entry (id, value, pattern, occurrences, description) against origin/main shows no difference.

Known Limits

  • About 180 older lines in test comments and in entry descriptions of numeric-floors.json still say that a value may only rise or only fall. They stay as history, as the issue says. The rule text in each of the five places, except the short CLAUDE.md line, says that the new rule replaces them.

Tests

  • tests/docs, tests/guards and the files that read CLAUDE.md: 96 files, 2,514 passed, 1 skipped.

Related Issues

Closes #766

The ratchet rule said a floor may only rise and a ceiling may only fall,
with one exception for a prompt's compiled-size ceiling. The guard can
not see a direction: it checks that each pinned value is present in its
source file at the recorded number of sites. The rule now says what the
guard enforces, plus the record that a move needs.

- Any floor or ceiling may move up or down. The entry's description and
  the PR body give the old value, the new value and the reason.
- The lean-prompts goal stays: the bytes that a typical run reads should
  not grow. A ceiling rise states its reason.
- An older description or test comment that states a one-way rule is
  history. This rule replaces it.

Places: CLAUDE.md (Test Ratchets), docs/reference/lean-prompts.md (Rules
for every target, rule 1, and Cut rules step 5),
docs/reference/file-organization.md, the comment of
tests/fixtures/numeric-floors.json and the header of
tests/guards/numeric-floor-manifest.test.ts.

The guard's non-vacuity probe now moves one site one step down and one
step up for every entry, so it shows that a one-file change fails in both
directions. The wording pins in tests/docs/lean-prompts-guide.test.ts
follow the new text. No pinned value changes.

Closes #766
- The manifest comment covers older test comments too, not only
  descriptions, as the other places say.
- The equality-baseline sentence no longer implies that registered
  entries ratchet in one direction.
- The goal lines state the goal as an end state.
- The guard failure message names a manifest-only change too.
- The file-organization tree note uses full articles and points to the
  lean-prompts rule, which states the goal.

Refs #766
@dean0x

dean0x commented Nov 5, 2026 •

Copy link
Copy Markdown
Owner Author

Evidence: independent audit and resolution

Head: 3faee861b56147f9f697bcc1bb9df0bf204bc4b4. One independent agent audited commit b72d675 against the issue. It read the diff and the code and changed no file.

Audit result

Question Result
1. The five places state the same meaning 4 findings: 2 MEDIUM, 2 LOW
2. The guard fails when a value or its site count changes in only one file PASS, both directions. 2 files, 33 tests passed
3. No current text states a one-way rule PASS, with 2 LOW notes
4. No pinned value changes PASS. Only the comment line of the manifest changed
5. Other faults 4 LOW findings

Resolution

Finding Action
MEDIUM: the CLAUDE.md line does not state the typical-run goal Not changed. The maintainer confirmed this exact line. CLAUDE.md is at its size ceiling. The line points to numeric-floors.json, and rule 1 of lean-prompts.md states the goal in full.
MEDIUM: the file-organization.md note does not state the goal Fixed. The note now points to rule 1 of lean-prompts.md.
LOW: the manifest comment said "description" only Fixed: "description or test comment", as in the other places.
LOW: only rule 1 names turns per run Accepted. The pins measure bytes.
LOW: "at least occurrences" while the probe makes the count exact Fixed in 3faee86: the manifest comment and the guard comment say "exactly".
LOW: "ratchet in neither direction" implies a direction for registered entries Fixed: "are exact baselines, pinned in that file".
LOW: two knowledge-base files state the old rule Fixed in 3faee86: tracker-references-guards (KB-INV-9 and the floors list) and test-harness-goldens-budgets (Counts) state the either-way rule.
LOW: missing articles in the file-organization.md note Fixed. The CLAUDE.md line stays as confirmed.
LOW: the guard message named only the assertion Fixed: "An assertion or its manifest entry".
LOW: "The goal stays" is change wording Fixed: "The goal:".
LOW: one old wording pin replaced Accepted. The issue asks for the new text.

Tests at the head

  • numeric-floor-manifest, kb-shape, no-ledger-citations, retired-wording, agent-name-guards and tests/docs: 11 files, 332 passed.
  • At 69b2973: numeric-floor-manifest, lean-prompts-guide, claude-md-tracker-section, architecture-move, agent-name-guards and retired-wording: 6 files, 175 passed.
  • At b72d675: tests/docs, tests/guards and the files that read CLAUDE.md: 96 files, 2,514 passed, 1 skipped.
  • No pinned value changed: a jq comparison of every entry against origin/main shows no difference.

…site count

The tracker-references-guards and test-harness-goldens-budgets knowledge bases now state the either-way rule. The guard header and the manifest comment say exactly, because the presence check and the single-site probe together make the site count exact. No pinned value changes.

Refs #766
@dean0x
dean0x merged commit f71d227 into main Nov 5, 2026
3 checks passed
@dean0x
dean0x deleted the docs/766-ratchet-either-way branch November 5, 2026 19: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.

Ratchet rule: pinned numbers may move either way with a stated reason

1 participant