Skip to content

Retire "declaring spec" from functional-spec prose in favour of "declaration" #323

Description

@vjovanov

What is missing

The functional spec still says declaring spec where §FS-terms.terms.1 says declaration. Sweep it, in one pull request that answers for this word and for nothing else.

  • Row: §FS-terms.terms.1 — "declaration — A heading or doc-comment line that introduces an ID. Its body is the fact. Displaces spec, fact and declaring spec."
  • Size: 1 occurrences across 1 functional-spec file(s), 0 of them in a heading title. Measured at 4b2b647aaa. The raw grep -c is 2 and is not the number to plan from. Per file: FS-examples.md (1).
  • Carve-outs: One occurrence. The bare word spec is bucket C and is not part of this issue — rewrite the compound only.
  • Heading titles this renames: None. No heading title carries the word, so no anchor moves and no link fragment is invalidated by this change.
  • Also in scope: whatever this change breaks, wherever it lives, including README.md (§FS-examples.4 → §REQ-readme.2). Prose in docs/architecture/, in a released changelog under docs/changelog/, and in the frozen GOAL, REQ and decision-record texts is not — those keep the words they have (§FS-terms, FS-terms.md:38-45); grund fmt --write still repairs their link fragments.
  • Claims: this word and nothing else. It makes no claim about any other retired word, and certifying the completeness of unchanged prose beyond it is not part of the review (§FS-terms, FS-terms.md:62-64).
  • Bucket: A — mechanical: a distinctive compound with no competing sense. A sed and a reading pass.

Why it belongs in this tool

§FS-terms is grund's own specification of what its words mean, and a grund spec that uses a word it retired is the drift that declaration exists to close. FS-terms.md:38-45 says a commissioned pass is a permitted way to pay this debt and that it answers for the words it names — this is one such pass, for one word.

Two things a reviewer should not mistake. grund check exits 0 over every stale link fragment a heading rename leaves behind — an anchor is not a coordinate — so "grund check is green, therefore nothing broke" is wrong here. grund fmt --check names them, --write repairs them, and lychee reports Cannot find fragment independently. And a raw grep -c overstates this sweep by roughly 3× overall (37× on ref), which is why the size above is the measured residual.

What you do today instead

Nothing: the word is retired on paper and stands in the prose. A reader who takes the cheap lead read of a section gets a word the shared vocabulary says is not the word, and has to open FS-terms to find that out — the second file §GOAL-token-economy.1 charges for, and the exact failure §FS-terms says it exists to close.

Worked example: PR #306 (point size → coordinate-size: 11 files, +20/−18, including the heading rename, the nine fragment repairs and README.md). Parent: #291.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions