Skip to content

Retire "batch mode" from functional-spec prose in favour of "batch query" #322

Description

@vjovanov

What is missing

The functional spec still says batch mode where §FS-show.terms says batch query. Sweep it, in one pull request that answers for this word and for nothing else.

  • Row: §FS-show.terms — "batch query — One --batch invocation answering an ordered stream of coordinates, or every coordinate in scope, from a single load. (A spec-local label, already defined in FS-show's Terms chapter — the word is defined and the prose has not followed.)"

  • Size: 4 occurrences across 1 functional-spec file(s), 1 of them in a heading title. Measured at 4b2b647aaa. The raw grep -c is 4 and is not the number to plan from. Per file: FS-show.md (4).

  • Carve-outs: The --batch flag name is frozen, and so is the JSON shape §FS-output-shapes.4.1 pins. FS-show.md:38 says "the two --batch forms", which is the flag and is already right.

  • Heading titles this renames:

    • FS-show.md:453: ### 3.3 Batch mode

    Each one invalidates every Markdown link fragment reaching it. grund fmt --write repairs them in the same change (§FS-fmt.6.3). No coordinate moves — no retired word appears in a named section handle — so every §ID.section citation still resolves.

  • 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