Skip to content

Condense SPEC.md - #29

Merged
BY571 merged 1 commit into
masterfrom
docs/condense-spec
Aug 19, 2026
Merged

Condense SPEC.md#29
BY571 merged 1 commit into
masterfrom
docs/condense-spec

Conversation

@BY571

@BY571 BY571 commented Aug 19, 2026

Copy link
Copy Markdown
Owner

456 → 402 lines, 3,599 → 3,188 words.

A smaller cut than the README's 48%, and deliberately so. Most of SPEC's length is
evidence and recorded decisions — the prior-art table, the 2019 survey finding that no
research ontology models hypothesis death, the seven-hypotheses-six-died dogfood result —
and cutting those would delete the reason the code is shaped the way it is. What came out
is duplication and staleness.

What was actually redundant

§8 stated the same ~2,340-token measurement twice — once under "The measurement" and
again in the paragraph explaining the deletion. Each was written at a different moment
(demotion, then removal) and each appended rather than edited, so the section had become
three layers of sediment arguing one point. It now reads as one argument.

§5's table had two columns that paraphrased each otherno_signal was glossed as
"the effect is not there" and "a signal that wasn't there" — and it re-printed two rule
blocks that §6 already carries in full. It keeps the vocabulary and the argument for why
the core must not enforce it; §6 keeps the rules.

§6 merged two example rules that differed only in which key they demonstrated. The key
table — the section's actual reference value — is untouched.

§4's derivation subsection and §8.1 lost restatements, not content: both had grown a
paragraph re-making the point the paragraph above already made.

Two stale things fixed in passing

  • §11's open question 4 asked whether a closed cause vocabulary should become a rule
    primitive. require_field_one_of shipped some time ago and a second graph did want it —
    struck through and answered, like question 2 beside it.
  • §3's node-type paragraph had accumulated a run-on sentence across two edits.

Verified

285 passed. test_docs.py still extracts and executes every node and rules block from
SPEC against the real example graph — the merge of two rule examples into one is why the
count moved from 286.

456 -> 402 lines, 3,599 -> 3,188 words. A smaller cut than the README's, and
deliberately so: most of SPEC's length is evidence and recorded decisions rather than
repetition, and deleting that would be deleting the reason the code is shaped this way.
What came out was duplication and staleness.

§8 stated the same ~2,340-token measurement TWICE — once under "The measurement" and
again in the paragraph explaining the deletion — because the second was written when
the surface was demoted and the third when it was removed, each appending rather than
editing. One statement now, and the reversal reads as one argument instead of three
layers of sediment.

§5's table had two right-hand columns that paraphrased each other (`no_signal` = "the
effect is not there" / "a signal that wasn't there") and re-printed two rule blocks
that §6 already carries in full. It keeps the vocabulary and the argument for why the
core must not enforce it; §6 keeps the rules.

§6 merged two example rules that differed only in which key they demonstrated, and
tightened the prose around the key table — which is the section's actual reference
value and is untouched.

§4's derivation subsection and §8.1 lost restatements, not content: both had grown a
paragraph re-making a point the paragraph above already made.

Two stale things fixed while in there. §11's open question 4 asked whether a closed
`cause` vocabulary should become a rule primitive — `require_field_one_of` shipped some
time ago and a second graph did want it, so it is struck through and answered like
question 2 beside it. And §3's node-type paragraph had accumulated a run-on sentence
across two edits.
@BY571
BY571 merged commit f84b093 into master Aug 19, 2026
2 checks passed
@BY571
BY571 deleted the docs/condense-spec branch August 19, 2026 15:52
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