fix(spec): every occurrence of a term is a link, and a term link is no escape

CHANGELOG.md

@@ -38,6 +38,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 - Resolve a term link through its page's `iri`, or through the tag when the page is absent. Plain italics are emphasis and are not checked.
 - Report `spec-term-undefined` when a link names no term, including a reference tag with no definition in the file, and `spec-term-draft` (warning) when the term is a draft.
 - Report `spec-term-first-use` when the first use of a term in a file is not emphasized, or a later use is.
+- Report `spec-term-unlinked` when a file links a term and writes it plain elsewhere, and link every occurrence in `rune spec fix --links`; where two terms start at one word, the longer wins.
 - Report `spec-term-legacy` (warning) on the old `*term* [TAG]` form or an IRI definition, naming the new form. A delta gets `delta-` twins of every term code.
 - Apply the term link rules in `rune validate` to `docs/decisions` and `runes` of a deck, and to the record and rune directories of a module, when the root has an ontology.
 - Add `rune spec fix --terms`: adds a draft ontology entry for every term link that names no term and writes its page.
@@ -227,6 +228,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
 ### Fixed
 
+- Fix the bundle check to accept a full reference-style term link (`[text][TAG]`) into the repository's glossary, the one form the assembler strips before deployment.
+- Check a collapsed or shortcut reference into the glossary like any other reference, because assembly does not strip it.
+- Strip a term link whatever the case of its tag, and leave a fenced block or a code span untouched, so an example of the syntax survives assembly.
 - Read the comment of an ontology term whose closing quote directly precedes the terminating period. The reader dropped that quote, so `rune spec glossary` listed the term with no definition.
 - Fix `rune run --clean` for codex: the clean `config.toml` keeps every `[model_providers.*]` table with its `auth` and names the one custom provider as the route.
 - Fix `rune run grok@grok --clean-harness-state` exiting 127 through the `harness-run` shim: the clean run names the real `~/.grok/bin` in `HARNESS_REAL_BIN_DIR` before it moves `HOME`.

docs/changes/every-term-cites-definition/design.md

@@ -2,7 +2,7 @@
 
 ## Approach
 
-A term is marked by a Markdown link to its generated glossary page. The *[validator][VALIDATOR]* reads the term address from the page and matches it to the ontology, so the link text and the tag carry no meaning of their own. This beat the italics model, which marked a term with a form no reader could tell from emphasis, and it beat a parenthetical definition at first use, which copies the definition into every file. The fixer is a separate step, because a validator that edits files is no longer a validator.
+A term is marked by a Markdown link to its generated glossary page. The *[validator][VALIDATOR]* reads the term address from the page and matches it to the ontology, so the link text and the tag carry no meaning of their own. This beat the italics model, which marked a term with a form no reader could tell from emphasis, and it beat a parenthetical definition at first use, which copies the definition into every file. The fixer is a separate step, because a [validator][VALIDATOR] that edits files is no longer a [validator][VALIDATOR].
 
 ## Structure
 
@@ -21,7 +21,7 @@ One row per requirement of the delta. The requirement names a role. This table n
 | Defined terms link to the ontology | validate | `rune-spec-doctor` | `spec-term-undefined`, `delta-term-undefined` | 1 |
 | The ontology is the term source | validate. The ontology is `ontology/rune.ttl` unless `deck.yaml` names another path under `ontology` | | `spec-term-draft`, `delta-term-draft` (warning) | 0 on a warning alone |
 | A broken ontology fails validation | validate | | none. The error carries no id and names the ontology path | 1 |
-| First use of a term is emphasized | validate | | `spec-term-first-use`, `delta-term-first-use` | 1 |
+| Every occurrence of a term is a link | validate; `rune spec fix --links` links the plain occurrences | | `spec-term-unlinked`, `spec-term-first-use`, and their `delta-` twins | 1 |
 | Term pages back every link | validate. Pages live under `docs/specs/glossary/` | `glossary-current` (deck) | `spec-term-page`, `delta-term-page` | 1 |
 | The legacy form warns | validate | | `spec-term-legacy`, `delta-term-legacy` (warning) | 0 |
 | Reference definitions follow Markdown | validate | | none | |

docs/changes/every-term-cites-definition/proposal.md

@@ -14,7 +14,7 @@ CLI-0040 made an italic term an error unless `docs/specs/glossary.md` defines it
 
 - A term is a Markdown link to its glossary page: emphasized at the first use in a file, plain after it, with a reference definition at the end of the file that points at the page by relative path. Plain italics are emphasis and are not checked.
 - The term source is the ontology. A repository without one has no terms, so the glossary fallback goes away. A term may carry a draft status.
-- The validator reports a link that names no term, a draft term, a first use that is not emphasized or a later use that is, a page that is missing or stale, and the legacy italics form, which still resolves and warns with the new form to write. The design's Commands table names the diagnostic ids. rumdl MD052 and MD053 keep reporting an undefined and an unused tag.
+- The validator reports a link that names no term, a draft term, a plain occurrence of a linked term, a first use that is not emphasized or a later use that is, a page that is missing or stale, and the legacy italics form, which still resolves and warns with the new form to write. The design's Commands table names the diagnostic ids. rumdl MD052 and MD053 keep reporting an undefined and an unused tag.
 - `rune spec glossary` prints the term list with tags and page definitions.
 - `rune spec fix --terms` adds a draft entry and a page for every link that names no term. `rune spec fix --links` migrates the legacy form in every Markdown file. Both change nothing on a second run.
 - `rune spec archive` refuses a change whose files link to a draft term or to no term.

docs/changes/every-term-cites-definition/specs/lifecycle-of-a-change/spec.md

@@ -7,16 +7,16 @@ A defined term MUST be a Markdown link to its glossary page. This holds in a *[c
 #### Scenario: Term link names no term
 
 - **WHEN** a specification links a term and no ontology term matches the page or the tag
-- **THEN** the validator reports the term, the file and line, and the ontology's location
+- **THEN** the [validator][VALIDATOR] reports the term, the file and line, and the ontology's location
 
 ### Requirement: The ontology is the term source
 
-The validator MUST read every labeled class, property, and concept from the repository's ontology. A repository without an ontology file has no defined terms. A reference link there is an ordinary link and MUST NOT be reported. A term MAY carry a draft status. The validator MUST warn once for each draft term a file links.
+The [validator][VALIDATOR] MUST read every labeled class, property, and concept from the repository's ontology. A repository without an ontology file has no defined terms. A reference link there is an ordinary link and MUST NOT be reported. A term MAY carry a draft status. The [validator][VALIDATOR] MUST warn once for each draft term a file links.
 
 #### Scenario: Repository without an ontology
 
 - **WHEN** the repository has no ontology file and a file carries a reference link
-- **THEN** the validator reports nothing for terms
+- **THEN** the [validator][VALIDATOR] reports nothing for terms
 
 ### Requirement: A broken ontology fails validation
 
@@ -32,32 +32,32 @@ An unreadable ontology, an undeclared prefix, or an ontology with no labeled ter
 - **WHEN** the class `Change` and the property `change` are both labeled `change`
 - **THEN** the property's page and tag take a key suffix, the class's stay plain, and each link resolves to the term its page names
 
-### Requirement: First use of a term is emphasized
+### Requirement: Every occurrence of a term is a link
 
-The first link to a term in a file MUST be emphasized. Every later link to the same term in that file MUST be plain. The validator MUST report a first use that is not emphasized and a later use that is, with the form to write. The link text MAY be the plural of the label. A file MUST define each tag it uses as a reference definition. The definition MUST point at the term's page by a path relative to the file. The file SHOULD hold each definition once, at its end.
+Once a file links a term, every occurrence of that term in the file MUST be a link, so a copied paragraph keeps its links. The first link MUST be emphasized and every later link MUST be plain. The [validator][VALIDATOR] MUST report a plain occurrence of a linked term, a first use that is not emphasized, and a later use that is, with the form to write. The link text MAY be the plural. A file SHOULD define each tag once, at its end, by a path relative to the file. The [validator][VALIDATOR] does not check the placement.
 
-#### Scenario: First use is plain
+#### Scenario: Linked term appears plain later
 
-- **WHEN** a record links a term twice and the first link is not emphasized
-- **THEN** the validator reports the line and prints the emphasized form to write
+- **WHEN** a record links a term and a later sentence writes the same term as a plain word
+- **THEN** the [validator][VALIDATOR] reports the line and prints the link to write
 
 ### Requirement: Term pages back every link
 
-Every term link MUST reach a glossary page whose bytes equal the generator's render of that term. The validator MUST report a page that is missing and a page whose bytes differ from the render. It MUST also report a tag the file uses but never defines. Each report MUST name the definition line or the regeneration step that repairs it.
+Every term link MUST reach a glossary page whose bytes equal the generator's render of that term. The [validator][VALIDATOR] MUST report a page that is missing and a page whose bytes differ from the render. It MUST also report a tag the file uses but never defines. Each report MUST name the definition line or the regeneration step that repairs it.
 
 #### Scenario: Page missing for a defined term
 
 - **WHEN** a file links a term the ontology defines and no page exists for it
-- **THEN** the validator names the page and the step that writes it
+- **THEN** the [validator][VALIDATOR] names the page and the step that writes it
 
 ### Requirement: The legacy form warns
 
-An italic term with its tag after it, and a definition that names the term address instead of a page, is the legacy form. The validator MUST still resolve it, MUST warn, and MUST name the link form and the relative page path to write. A link whose definition names the term address instead of a page MUST be treated the same way.
+An italic term with its tag after it, and a definition that names the term address instead of a page, is the legacy form. The [validator][VALIDATOR] MUST still resolve it, MUST warn, and MUST name the link form and the relative page path to write. A link whose definition names the term address instead of a page MUST be treated the same way.
 
 #### Scenario: Legacy form in a delta
 
 - **WHEN** a delta writes an italic term with its tag after it and defines the tag as the term address
-- **THEN** the validator warns and prints the emphasized link and the page definition to write
+- **THEN** the [validator][VALIDATOR] warns and prints the emphasized link and the page definition to write
 
 ### Requirement: Reference definitions follow Markdown
 
@@ -66,7 +66,7 @@ A tag MUST compare without case at its use and its definition. A definition dest
 #### Scenario: Lowercase tag with a bracketed destination
 
 - **WHEN** a record links a term with a lower-case tag and defines the tag with its destination in angle brackets
-- **THEN** the validator reports nothing for the term
+- **THEN** the [validator][VALIDATOR] reports nothing for the term
 
 ### Requirement: The generator lists every term
 
@@ -79,38 +79,38 @@ On request the generator MUST print one line per ontology term, sorted by label,
 
 ### Requirement: The fixer adds draft terms
 
-The fixer is a separate step the author invokes or a hook runs before the validator. It MUST add a draft entry to the ontology for every term link that names no term. The entry MUST be labeled with the link text and named by its upper camel case. The fixer MUST write the term's page. It MUST skip a link whose page names no term, whose text gives no name, or whose name already exists under another label. It MUST name the reason for each skip. A second run MUST change nothing.
+The fixer is a separate step the author invokes or a hook runs before the [validator][VALIDATOR]. It MUST add a draft entry to the ontology for every term link that names no term. The entry MUST be labeled with the link text and named by its upper camel case. The fixer MUST write the term's page. It MUST skip a link whose page names no term, whose text gives no name, or whose name already exists under another label. It MUST name the reason for each skip. A second run MUST *[change][CHANGE]* nothing.
 
 #### Scenario: Link names an undefined term
 
 - **WHEN** a record links a term the ontology lacks and the author runs the fixer
-- **THEN** the ontology holds a draft entry for the term, its page exists, and the validator warns on the draft instead of failing
+- **THEN** the ontology holds a draft entry for the term, its page exists, and the [validator][VALIDATOR] warns on the draft instead of failing
 
 ### Requirement: The fixer migrates the legacy form
 
-The fixer MUST rewrite the legacy form to the link form in every Markdown file of the repository. It MUST skip version control trees, archived changes, generated trees, and test fixtures. In each file it MUST emphasize the first use of a term and make later uses plain. It MUST point every definition at the term's page by relative path and add a missing definition. A converted file MUST be left unchanged by a second run.
+The fixer MUST rewrite the legacy form to the link form in every Markdown file of the repository. It MUST skip version control trees, archived [changes][CHANGE], generated trees, and test fixtures. In each file it MUST link every plain occurrence of a term the file links, emphasize the first link, and make the later links plain. It MUST point every definition at the term's page by relative path and add a missing definition. A converted file MUST be left unchanged by a second run.
 
 #### Scenario: Legacy file is migrated twice
 
 - **WHEN** the fixer runs twice over a file in the legacy form
-- **THEN** the first run rewrites it to the link form and the second run reports no change
+- **THEN** the first run rewrites it to the link form and the second run reports no [change][CHANGE]
 
 ### Requirement: Archive refuses unsettled terms
 
-The archiver MUST refuse to merge a *[change][CHANGE]* whose files link to a draft term or to no term. It MUST name each such link by file and line with the step that settles it. Abandoning a change MUST NOT be refused for its terms, because nothing reaches the canonical specifications.
+The archiver MUST refuse to merge a [change][CHANGE] whose files link to a draft term or to no term. It MUST name each such link by file and line with the step that settles it. Abandoning a [change][CHANGE] MUST NOT be refused for its terms, because nothing reaches the canonical specifications.
 
 #### Scenario: Change links a draft term
 
-- **WHEN** the owner archives a change and one of its files links a term whose entry is a draft
+- **WHEN** the owner archives a [change][CHANGE] and one of its files links a term whose entry is a draft
 - **THEN** the archiver refuses, names the file, the line, and the term, and the canonical specifications stay unchanged
 
 ### Requirement: Records and runes are checked
 
-The validator MUST apply the term rules to every Markdown file under the decision records and runes of a repository with a deck marker. In a module root it MUST cover the records, agents, rules, and skills. It MUST do so only when the root has an ontology. A root without one MUST report nothing for terms. It MUST skip provenance, archive, and build trees, fenced code, and a YAML front matter block.
+The [validator][VALIDATOR] MUST apply the term rules to every Markdown file under the [decision records][DECISIONRECORD] and [runes][RUNE] of a repository with a deck marker. In a module root it MUST cover the records, agents, rules, and skills. It MUST do so only when the root has an ontology. A root without one MUST report nothing for terms. It MUST skip provenance, archive, and build trees, fenced code, and a YAML front matter block.
 
 #### Scenario: Rule links an undefined term
 
-- **WHEN** a rule under the runes directory links a term the ontology lacks
+- **WHEN** a rule under the [runes][RUNE] directory links a term the ontology lacks
 - **THEN** artifact validation fails the terms item and names the file and line
 
 [CAPABILITY]: ../../../../specs/glossary/capability.md

docs/changes/glossary-renders-from-ontology/specs/glossary-renders-from-ontology/spec.md

@@ -2,7 +2,7 @@
 
 ### Requirement: The glossary is rendered from the ontology
 
-The glossary is a *[render][RENDER]* of the ontology. The generator MUST write one page per labeled ontology term and one index. They go into the glossary directory beside the canonical specifications, or into a directory the owner names. The index MUST list every page sorted by label with the term's comment. One ontology MUST produce the same bytes on every write. A write MUST remove the page of a term the ontology no longer defines and the single glossary file an older render wrote.
+The glossary is a *[render][RENDER]* of the ontology. The generator MUST write one page per labeled ontology term and one index. They go into the glossary directory beside the canonical specifications, or into a directory the owner names. The index MUST list every page sorted by label with the term's comment. One ontology MUST produce the same bytes on every write. A write MUST remove the page of a term the ontology no longer defines and the single glossary file an older [render][RENDER] wrote.
 
 #### Scenario: Two writes read one ontology