Repository navigation
docs: every occurrence of a term is a link, and the records in the plain register - #76
runewright[bot] wants to merge 8 commits into
Conversation
A defined term is a link to its glossary page at every occurrence in a file: the first emphasized, every later one plain, so a copied paragraph keeps its links. The foundations spec, the ConsultTheOntology rule, the fallback check-terms and fix-terms, and check-coverage all say or do so. Six foundation requirements that crossed the 500-character cap with their links split into pairs, and the physics framing of projections moved to the glossary page. Nine review-ceremony terms join the ontology. Co-Authored-By: Martin Zeman <N4M3Z@users.noreply.github.com>
Every decision record leads with the point, names an actor, keeps one idea per sentence, links each ontology term at every occurrence, and carries one rewrite note. Rewritten from the voice review of 2026-10-18 over three agent passes with a verifier after each; the verifiers' remaining judgements are in the workshop under docs/specs/2026-10-18-foundations-landing/reports/records-open-judgements.md. Co-Authored-By: Martin Zeman <N4M3Z@users.noreply.github.com>
The first push of a branch checks every file, and three items on main failed there: the idea snapshot check needs the Obsidian CLI, which no runner has, so the commit stage skips it on CI and it stays a local gate; a table in the agentic-first-pipeline-rules design had no blank line after it; and two delta specs carried front matter above their first heading, which the current OpenSpec refuses in strict mode while every other delta spec goes without it. Co-Authored-By: Martin Zeman <N4M3Z@users.noreply.github.com>
github-actions
Bot
added
size:xlarge
|
review/correctness stood down on |
N4M3Z
changed the title
…ree":"866617e821e044c4cf3e03af762cbb3df1fae204","nonce":"53c75b736e91701aa68c288f9d10212a93871e9347e845eaddadac4790e611ab"}
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6eeaa49111
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - A verdict binds to the [requirement][REQUIREMENT]'s current text. When the owner [changes][CHANGE] the text, say what the new text claims before you move on. | ||
| - When a decision [changes][CHANGE] during the walk, the readback states only the final decision and marks the reversal where it matters. |
There was a problem hiding this comment.
Here changes is an ordinary verb, but the new links resolve it to the glossary's Change class, which specifically means a spec-driven directory under docs/changes/. This gives the agent the wrong definition while executing a review, and the same incorrect verb link recurs elsewhere in this skill and in the modified proposals. Reword these uses as alters or leave them unlinked, as the updated ontology rule itself requires.
Useful? React with 👍 / 👎.
| linked = termlib.linked_terms(text, resolved, index) | ||
| for start, end, name, tag in termlib.term_occurrences(text, linked, index): |
There was a problem hiding this comment.
On a developer machine with the previously supported rune revision, the existing hook skips this fallback whenever any rune executable is present, and rune_has_link_model() treats the already-existing rune spec fix command as proof that the CLI implements this newly added term-unlinked behavior. Consequently this loop is never reached and local checks accept plain occurrences until the user happens to upgrade rune; gate delegation on the required CLI capability/version or run the fallback check as well.
Useful? React with 👍 / 👎.
|
review/correctness stood down on |
…sary links The contract workflow pins its own cli candidate, and that pin still built the rune that reports a term link into the repository glossary as an escape. It now builds the signed head that strips term links in assembly and accepts the reference form. The ReviewChange canon named one harness tool by its literal name in two places, which the same check refuses; it now says the harness choice prompt. Co-Authored-By: Martin Zeman <N4M3Z@users.noreply.github.com>
ApprovabilityVerdict: Needs Human Approval Macroscope's review found this PR requires human approval — This is a large cross-cutting behavior change, not a documentation-only update: it changes default term validation and rewriting, agent-facing instructions, ontology data, tests, and CI gates. The implementation spans files owned by another maintainer, with unresolved comments identifying concrete semantic-link and fallback-validation risks. Notes:
You can add or adjust custom eligibility rules. Learn more. |
|
review/correctness stood down on |
…be that reads the help Review findings on the pull request. The fallback matcher built only `capabilitys` and `capabilityes` for a label that ends in y, so `capabilities` and `repositories` passed unlinked; it now takes `ies`. A term inside a bare URL, an autolink, or an HTML tag counted as prose and the fixer would have rewritten the address; both are masked now. The two scripts handed over to any installed rune that had `spec fix`, including the older build without the every-occurrence rule; they now hand over only when that rune's own help says it links every occurrence. The ReviewChange skill wrote the verb "changes" as a link to the change term; the sentence now names the owner reversing a decision. Co-Authored-By: Martin Zeman <N4M3Z@users.noreply.github.com>
|
review/correctness stood down on |
The SafetyFirst policy test pins a digest of the workflow bytes. The policy changed on 2026-09-22, when deletion moved to the shared trash script, and the pin stayed at the 2026-09-14 bytes; the contract job hid it behind the harness-symbol findings the same job reported. The pin now names the current policy. Co-Authored-By: Martin Zeman <N4M3Z@users.noreply.github.com>
|
review/correctness stood down on |
|
review/correctness round 1 started on |
Runeseer review — 2 open findings
Request changes. Two earlier notes still hold: the new every-occurrence term check never runs on a machine where any
2 open · Reviewed |
|
@N4M3Z, the following findings block this head:
Choose one action:
|
github-actions
Bot
removed
the
review:runeseer
The reviewer found a verb still linked to the change term on line 25, which the first fix had missed one line above its own. Two more everyday uses in the same file went the same way: edits to the ontology and the proposed edits in a choice prompt are not changes in the spec-driven sense, so they are now called edits. Co-Authored-By: Martin Zeman <N4M3Z@users.noreply.github.com>
|
review/correctness stood down on |
1 participant
Plan
The voice review of 2026-10-18 decided that a defined term is a link to its glossary page at every occurrence in a file, and that every decision record reads in the plain spoken register. This pull request applies both to the deck and brings the tooling that checks them.
Changes
docs/changes/plain-text-first-principlesand its ten delta specs, the proposal, the design, and the proof README; split six requirements that crossed the 500-character cap with their links into pairs.docs/decisions/in the plain spoken register with every term linked; the verifiers' remaining judgements are listed in the workshop, not in the records.runes/core/rules/ConsultTheOntology.md.term-unlinkedinscripts/fallback/check-terms, link it inscripts/fallback/fix-terms, and skip front matter, headings, code, definition lines, and inline-link destinations inscripts/fallback/termlib.py; the longer term wins at an overlap.scripts/check-coverage.Core.UndefinedTermfromscripts/generate-vale-style.pyso a hyphenated name, a multi-word link, and a plural count as defined; exempt roman numerals inCore.UnexplainedAbbreviation.ontology/rune.ttland their glossary pages.RUNE_CLI_REVin.github/workflows/quality.yamlto the cli head that carries the every-occurrence validator, run the fixture tests after the tool installs, and skip the Obsidian-only snapshot check on the runner.docs/changes/agentic-first-pipeline-rules/design.mdand drop the front matter from two delta specs, which the current OpenSpec refuses in strict mode.Testing
bash .githooks/pre-commit --all-fileswith the pinned cli build on PATH: exit 0.python3 scripts/fallback/check-terms .: 0 findings; parity withrune spec fix --linksproven on a scratch copy.REQUIRE_GATES=1 python3 -m unittest tests.test_check_scriptsandpython3 -m unittest tests.test_fallback_terms: OK.openspec validate --all --strict: 51 passed.2cf42a3a: exit 0; the draft-open run on it passed.Release Notes
Open-Seal-Nonce: 53c75b736e91701aa68c288f9d10212a93871e9347e845eaddadac4790e611ab
Note
Require glossary links on every term occurrence and rewrite decision records in plain prose
check-termsreports plain occurrences asterm-unlinkederrors, andfix-termsinserts reference links automatically (check-terms, fix-terms).Core.UndefinedTermnow accepts plural, link-ending, bold, underline, and code definitions while avoiding hyphenated-name false positives;Core.UnexplainedAbbreviationignores Roman numerals.ReviewController,ReviewFunnel,OpenSeal,MergeSeal,WorkItem, and others) to rune.ttl with generated glossary pages.fix-termsto auto-repair. TheCore.UndefinedTermrule no longer treats single-marker emphasis as a definition.Macroscope summarized 213a386.