Skip to content

RFC-0045 — A refusal is declared, and a derivation is checked against it (refuses: and yidam derive check)

  • Status: Implemented
  • Track: I33
  • Commands: derive
  • Relates to:
    • RFC-0034 (whose package-less cites: entry is the citation this reuses, and whose "What this does not touch" declined to invent the document class this RFC invents)
    • RFC-0017 (whose claim model, through claims_in_node, is what a cited span's standing is read out of)
    • RFC-0031 (whose node prose model is why a span may sit in a property and not only in description)
    • RFC-0032 (the precedent for promoting a key that survived in extra to a named field, and the reason it was done)
    • RFC-0037 (the precedent for declaring a marker rather than inferring one, and for measuring the population before choosing its shape)
  • Versioning layers touched: template (agent-conduct.md's third outbound rule gains its grammar; GRAPH.md documents refuses:) / tooling (one derive check command, one yidam lint check) / SDK (refuses: becomes a named field on the node in all three SDKs — a yidam-core minor bump and a parity fixture). No MCP contract bump: no tool reads either field in this RFC.
  • Downstream reference case: five artifact layers in four derived repositories — 937 artifacts and 1,552 citations — and the tracked corpora of seven repositories, 4,630 nodes, measured read-only on 2026-09-29 at the commits in §2.

Summary

agent-conduct.md states three rules for a claim that leaves the repository, and nothing in the template runs them. So four derived repositories each built the gate themselves: two dossier/ directories, a platform/ and a ledger/, and a publish crate. All four agree on the first two rules. They share a citation model — a node, a verbatim span, the weakest tag beneath it — which RFC-0034 already gives yidam as a cites: entry.

They do not agree on the third rule, and they cannot: the third rule has no subject the tooling can read. A refusal is a sentence of English prose, and every repository that tried to find one wrote a lexicon. Measured against the only human rulings that exist, the detector one repository gates on finds 12 of 33 refusals. The widest finds 32 and flags 22 paragraphs that are not refusals. Another finds 0. A fourth repository declined to build the rule at all.

This RFC does two things.

  • It declares the refusal. A node lists the refusal sentences it carries under a refuses: key, each quoted verbatim from its own prose. A detector may propose one; only a declaration gates.
  • It runs the derivation. yidam derive check reads artifacts from declared paths and checks their cites: entries against the corpus. A span must be verbatim in one paragraph. The artifact's tier is computed as the weakest standing beneath its spans and held to the reach it declares. A declared refusal in a cited paragraph must be answered.

The rule's scope — the cited paragraph, not the whole node — is chosen by the population, and §4 is the measurement that chose it.

Problem

1.1 Four gates, one rule

directories.md says of a directory outside graph-check that "if what it holds derives from the corpus, the gate is the derivation". It names no tool that runs one. Four repositories wrote their own.

LayerRepositoryLanguageArtifactsCitation syntaxRefusal rule
dossier/corpus ARust4frontmatter rests_on: [{node, quote}]any refusal in a cited paragraph, detected by shape plus a file of human rulings
dossier/corpus BPython10YAML rests_on: [{node, span}]an uncited refusal sentence between two cited spans
platform/corpus CRust8<!-- cite: path [tag] --> then a blockquotenot implemented, deliberately
ledger/corpus CRust25YAML claims[].cites[]{node, tag, span}none
crates/publishgoedelsoup/allen-county-ohioRust890Rust constants, support!(path, span)any refusal in a cited node, answered by name

Four syntaxes, and one object underneath them: a node, a verbatim span, and the standing that span has. Every layer computes the tier as the minimum over the spans, weakest first.

1.2 Two of the filing issue's premises move

#1053 was written from a review. The measurement corrects it in two places. The correction changes how rule 3 is argued, not what is built.

#1053 saysMeasured
two repositories "re-implemented a YAML frontmatter reader in Python"One did. Corpus B's is Python. Corpus C's is a restricted YAML reader in Rust
three repositories record that refusal detection is "a lexicon, not a parser"One does. Corpus B's README and decision record say it. Corpus A argues the opposite: its detector's doc says "A refusal is a negation next to an epistemic verb, not a phrase from a list", and a human ruling overrides it in both directions. allen-county-ohio keeps a 12-phrase list with no record. Corpus C's decision record rejects a keyword list outright, because one matched "426 nodes on 'is not a' alone"

The disagreement is itself the evidence. Four teams read one sentence of the prelude and chose four detection methods. One of them chose not to detect.

1.3 No lexicon is a gate

Corpus A holds the only human rulings on refusals that exist: 62 paragraphs, 33 ruled a refusal and 29 ruled not one. Each repository's detector was reimplemented from its source and run over those paragraphs. Corpus A's own row reproduces the gap and false-positive counts its test suite pins (21 and 6), which is the check on the reimplementation.

DetectorFoundMissedFalsePrecisionRecall
corpus A, negation + epistemic verb122160.6670.364
corpus A, wide proposer (any negation in a tagged paragraph)321220.5930.970
corpus B, [open] sentence or cue regex258190.5680.758
corpus B, cue regex alone72670.5000.212
corpus B, [open] sentence alone2211150.5950.667
allen-county-ohio, 12 phrases0330—0.000

No row is usable as a gate. Every row that reaches three-quarters recall is wrong about more than two paragraphs in five. The row that is never wrong finds nothing, because its phrases were written against a different corpus's prose.

The sample is not a random one: it is the paragraphs someone proposed or cited, so it is biased toward hard cases. That makes these rates a statement about the paragraphs a gate actually has to decide, which is the population that matters.

1.4 The lexicons disagree with each other

Over every tracked node description in seven repositories, the three detectors do not flag the same sentences.

RepositorySentencesABallen-countyA ∩ BUnion
goedelsoup/allen-county-ohio17,1638081,2162143861,653
corpus C6,23125523616109383
corpus A3,85540546553173700
corpus B13,7001,0321,15987871,405
corpus D8,8161,0761,162503991,841
goedelsoup/ohio-education-funding1,7667388122139
corpus E7656387435116

Of the sentences A or B flags, the two agree on between 16% and 30% in six of seven corpora. Corpus B, whose detector was tuned on its own prose, is the exception, at 56%. A template that shipped any one of these would be shipping one corpus's idea of a refusal to all of them.

allen-county-ohio's own module comment names the failure that makes this matter: three of its twenty-six refusals were invisible to its detector because a phrase straddled a hard wrap, and "it failed silently, because a refusal nobody detects looks identical to a node with none."

2. The measurement

Read-only, through git ls-tree and git cat-file at pinned commits, so an untracked projection counts for nothing. HEAD moved in two repositories during the run; every figure is at these commits.

RepositoryCommitNodes
goedelsoup/allen-county-ohio7193553724
corpus C3ca97071,590
corpus Ac7b4dc8106
corpus Bafbc49f1,716
corpus D586640c303
goedelsoup/ohio-education-funding2016712129
corpus E43f886d62

A paragraph is a blank-line block of one field's prose, which is the definition every one of the four layers uses. A ruling in corpus A is keyed on the first 60 normalized characters of its paragraph, and all 62 matched a live paragraph. Sentences are split with corpus B's splitter, vendored unchanged, so the §1.4 columns count the same units.

The artifact inventory:

LayerArtifactsCitationsFound with whitespace collapse onlyIn a field other than descriptionCrosses a paragraphArtifact-to-artifact edges
corpus A dossier/41511000
corpus B dossier/106462200
corpus C platform/884846500
corpus C ledger/2580804000
allen-county-ohio publish8901,3091,309000
total9371,5521,54610700

Every citation resolves. The six that need more than whitespace collapse are four in corpus A that differ from the node by emphasis or link markup, and two in corpus B that carry a blockquote >. The 107 outside description are in properties, except corpus B's two, which quote source_note, a top-level key every one of its nodes carries.

Proposal

3.1 A refusal is declared on the node that makes it

# .yidam/corpus/period/depopulation.yml
class: period
label: Depopulation, 2020–2024
description: |
  Eleven of the county's thirteen civil subdivisions lost population between 2020 and 2024.
  [verified] It does not establish that the decline has ended. [open]
refuses:
  - span: >-                      # verbatim from this node's prose, compared as `cites:` compares
      It does not establish that the decline has ended.
    inference: the decline has ended    # optional; what the sentence declines to conclude

A declaration, not a detection. §1.3 is the case against detection. A refusal is a statement about what the node's own author declines to conclude, and the author is the only party who can make it. A declaration makes a refusal something the tooling can see, which a sentence of prose never was: it can be counted, reviewed in a diff, and held to its text by a lint check.

A span, not an index. The entry quotes the sentence rather than numbering it, for the reason local-citation-span-drift gives: a reference alone "rots invisibly, because the node keeps its name while its content is rewritten". A sentence number is such a reference. yidam lint gains refusal-span-drift (Error). A refuses: span no longer in its node's prose is a declaration about text that is gone. The population starts empty in every corpus, so the check can ship at Error without seeding a baseline.

A field, not a fourth tag. agent-conduct.md names three claim tags and pins that there is no fourth, and a refusal is not a standing. The sentence in the example is [open]: it is a claim with a standing, and it is also a refusal. Corpus B's detector treats every [open] sentence as a refusal, and 15 of the 37 it flags that way are ruled not to be (§1.3). The two properties are independent, so they are held in different places.

Named in the SDKs. refuses: already survives every parse through CorpusInstance.extra. It is promoted to a named field in the Rust, Python and TypeScript SDKs, as references: was, for the reason RFC-0032 gave: a field that is named is one a check can read and a migration can write.

3.2 An artifact is a file under a declared path, and cites as a node does

# .yidam/config.toml
[derive]
paths = ["dossier/**", "ledger/entries/**"]

An artifact is a .yml file, or a .md file with YAML frontmatter, under a [derive] paths glob. The globs take [object] paths' grammar. The fields are:

# dossier/decline-is-not-suburbanization.yml
claim: >-
  The suburban ring is shrinking too. Eleven of the county's thirteen civil subdivisions lost
  population between 2020 and 2024.
reach: public                     # public | attributed | internal
cites:
  - node: period/depopulation     # RFC-0034's entry: <class>/<name>, `.yml` optional
    tag: verified                 # optional; held to the standing the corpus gives the span
    span: >-
      Eleven of the county's thirteen civil subdivisions lost population between 2020 and 2024.
answers:
  - node: period/depopulation
    refusal: >-
      It does not establish that the decline has ended.
    answer: >-
      The assertion reports the loss and says nothing of its trend.

cites: is RFC-0034's entry, unchanged. It is one grammar for one object: a node, at a standing, by span. The predicate that checks a local citation — resolve, find the span, read its governing standing — is the predicate that checks this one. It is called, not copied. Three of the four layers call the list rests_on. It is renamed here because a second key name for the same entry would be a second grammar.

Every other key is ignored. Corpus A's examined_not_used, corpus C's figure and benchmarks, and allen-county-ohio's topic are theirs. An artifact is a document the repository owns. derive check reads the four fields above and asserts nothing about the rest.

reach:, not a declared tier. agent-conduct.md says the tier is "computed rather than declared", and names where each tier may go. So an artifact declares where it is going, and the check computes whether it may:

reach:Weakest standing admittedagent-conduct.md
publicverified"[verified] may reach public material"
attributedinference"[inference] reaches attributed memos and backgrounders"
internalopen"[open] does not leave the repository"

Each layer already has a field that says this, under its own name. Corpus A's messages carry publication_tier, corpus C's planks carry status: draft | publish, and allen-county-ohio holds its whole feed to an Inference ceiling. Corpus B writes the computed tier back into the file and checks the copy. A declared tier that must equal the computed one is a cache. A declared reach is a decision the tooling can hold the evidence to.

3.3 Where a span may be

In any string the node holds, not only description. Corpus C's planks cite a property in 65 of 84 citations, and its ledger in 40 of 80: fiscal_effect, authority_basis, counter_account. Corpus B cites its top-level source_note twice. A rule that read description alone would fail 107 citations that are correct. A span is found in description, in any string-valued property, or in any other top-level string. RFC-0031 is the argument that a node's prose is not one field, and this is that argument applied to a citation.

Within one paragraph of one field. A span that crosses a blank line has no single paragraph, so it has no single governing standing and no single refusal scope. Two layers already enforce this, and 0 of 1,552 citations cross one.

Compared after whitespace collapse, and nothing else. This is RFC-0034's rule and local-citation-span-drift's comparison. Case, punctuation, emphasis and markup are compared as written, because those are the changes a span exists to catch. 1,546 of 1,552 citations already pass it. The six that do not are listed in §2, and each one is a re-quote.

A span's standing is the weakest claim overlapping it, or open if none does. local_citations::governing already computes the first half. The second half is the direction that cannot flatter an artifact: corpus A reads an untagged paragraph as Open, and allen-county-ohio refuses one outright. The artifact's tier is the weakest over its spans.

3.4 A declared refusal in a cited paragraph must be answered

For each span an artifact cites, take the paragraph it sits in. Every refuses: entry of that node whose span lies in the same paragraph must be named by an answers: entry of the artifact, by node and by refusal text. An answer is prose, and the check does not read it. It checks that the answer exists — the prelude's "the author must answer it rather than route around it" — which puts the refusal and the reply beside each other where a reviewer reads both.

The scope is the paragraph because the prelude says "a refusal in the cited block", and §4 says the other two readings are worse.

A refusal the artifact itself quotes, inside one of its own spans, needs no answer. The artifact is then resting on the refusal, not routing around it, and the refusal travels with it.

An answer that names no refusal declared in a cited paragraph is a finding too. That is allen-county-ohio's StaleAnswer: an answer outliving its refusal is a caveat about text that is gone.

3.5 yidam derive check

A read-only gate in the "Checks and gates" group. It takes --format text | json like every report, and exits nonzero on any Error.

FindingSeverityFires when
derive-unresolvedErrora cites: entry names no node, or one this corpus does not hold
derive-span-driftErrorno span:, or the span is in no prose field of that node
derive-span-crosses-paragraphErrorthe span is found only across a blank line
derive-tag-driftErrora tag: is written, and the span's governing standing differs
derive-beyond-reachErrorthe computed tier is weaker than reach: admits
derive-unanswered-refusalErrora declared refusal in a cited paragraph has no answers: entry
derive-stale-answerErroran answers: entry names no declared refusal in a cited paragraph
derive-no-reachErrorthe artifact declares no reach:, or one outside the three
derive-refusal-candidateInfo§3.6

derive-unresolved, derive-span-drift and derive-tag-drift are local-citation-*'s predicate reached from a new caller. Their messages keep RFC-0034's wording, including "even ignoring line wrapping".

The JSON report lists every artifact with its computed tier, its reach, and each cited span's standing. Corpus B runs a separate task to write that tier back into each artifact. It can render the tier from the report instead, and stop storing a copy.

3.6 A detector proposes, and never gates

A cited paragraph that carries no refuses: declaration and matches a proposer is reported as derive-refusal-candidate (Info). The proposer is corpus A's wide shape: any negation in a paragraph tagged [inference] or [open]. §1.3 measures it at 0.970 recall and 0.593 precision. That precision disqualifies it as a gate. The recall is what an advisory needs, because an advisory that misses a refusal is the silent failure allen-county-ohio described.

It runs only over cited paragraphs, which bounds the noise to the paragraphs an artifact rests on. Measured over every field:

LayerCited paragraphsProposed
corpus A dossier/151
corpus B dossier/471
corpus C platform/8223
corpus C ledger/687
goedelsoup/allen-county-ohio1,269209

Each one is resolved by a declaration, or by reading it and moving on. It never changes the exit code. allen-county-ohio's 209 is the cost of a proposer tuned on a different corpus. A paragraph read and found not to refuse anything stays on the list, and that number is why "Open questions" asks whether it should be silenced.

This is corpus A's architecture, and the reason it is adopted rather than invented. Its detector's doc says "This proposes; data/refusal-adjudications.tsv decides." refuses: is that adjudication file, moved into the node, where every repository can read it and a diff shows who ruled.

4. Rule 3's scope, decided by the population

The three readings of "citing across a refusal", run over every citation in every layer with each layer's own detector. Each cell is failing citations over failing artifacts.

Layer(i) an uncited refusal between two cited spans(ii) a refusal in a cited paragraph(iii) a refusal anywhere in a cited node
corpus A, with its rulings0 / 00 / 013 / 4
corpus B, its detector, every field0 / 05 / 161 / 10
corpus C platform/, corpus A's detector, every field0 / 012 / 584 / 8
corpus C ledger/, corpus A's detector, every field0 / 011 / 563 / 17
allen-county-ohio, its detector, before answers0 / 09 / 9841 / 721

Reading (i) never fires. It needs one artifact citing two spans in one paragraph. That happens in 13 paragraphs across all five layers, and never with a refusal between the spans. It is corpus B's rule, and corpus B's own gate reports zero under it. A rule whose population is empty cannot be the one the prelude meant.

Reading (iii) fails nearly everything. Corpus C's planks would fail 84 of 84 citations. Every plank cites a node that refuses something somewhere, because refusing is what a careful node does. allen-county-ohio built (iii) and paid for it. Without its answers, 721 of its 890 assertions would fail. It wrote 771 answers: entries, and 749 of them — 97% — answer a refusal in a paragraph the assertion does not cite. 161 distinct answer strings do that work, copied from assertion to assertion. That is a rule producing boilerplate, and boilerplate is how a caveat stops being read.

Reading (ii) is the prelude's words and the one with a population. It fires on 0 to 12 citations per layer — not on none everywhere, and not on nearly all. It keeps the case the rule was written for — "a node stating a fact at [verified] and refusing the inference from it one sentence later" — because one sentence later is the same paragraph.

What this does not touch

Artifact-to-artifact chains. Two layers built one, and 0 edges exist in any layer: corpus A's messages and briefs are empty, and corpus B has written no {assertion:} edge. The prelude's "the whole supporting chain" is honoured one level down. A span's standing is already the weakest claim beneath it in the corpus. A chain between artifacts is left until something writes one, for the reason RFC-0037 declined to build for Article V: n = 0.

Figures. allen-county-ohio holds 2,012 figure literals to its cited spans, and corpus C checks 25 ledger figures against a node's stored value. Both are real checks of a different claim — this number is that number. RFC-0043's count generator and the numeric property type are where that belongs.

The selection ledger. Four of the five layers keep a list of what was examined and not used: corpus A's examined_not_used (48 entries), corpus B's not_asserted, corpus C's ## What was examined and not used and examined-and-not-used.yml (36). Three repositories invented one list. It is a candidate for the next RFC and not this one, because nothing in the three rules reads it.

Artifacts that are not files. allen-county-ohio's 890 assertions are Rust constants in a 16,000-line derived.rs, and a command that reads files cannot read them. That repository can emit its table as YAML under a [derive] path and let the command check it. Or it can keep its crate, which runs today. Nothing forces the move.

Normalization beyond whitespace. Corpus A strips emphasis and reduces a link to its text before matching, and refuses any quote containing a link. Adopting either would forgive the changes a span exists to catch. Four of corpus A's fifteen citations would need re-quoting from the node as written.

An MCP tool. A check_derivation tool is worth having, and a contract bump is not a local decision.

Migration & compatibility

Nothing breaks. A repository with no [derive] section has no artifacts, and a node with no refuses: declares nothing. derive check reports an empty set and exits zero. Every released SDK already carries refuses: through extra, so a corpus that writes one is readable by every binary that exists.

What a repository that moves pays:

  • Re-keying citations. rests_on → cites, and corpus A's quote → span. This is mechanical, one key per citation. Corpus C's ledger citations already have the entry's shape.
  • Re-quoting six spans (§2).
  • Declaring the refusals its artifacts rest on — not the corpus's. Declaring every refusal the detectors propose would mean 55 to 909 nodes per repository, and nothing requires it. Rule 3 reads only cited paragraphs, so the declarations a repository owes are the ones in §4's column (ii): from 0 to 12 per layer. The rest can be declared as they are cited. derive-refusal-candidate names each one as it becomes due.
  • Retiring an answers list. allen-county-ohio's 749 answers to refusals outside a cited paragraph are no longer owed. The 22 inside one carry over as answers: entries, fewer where the assertion's own span quotes the refusal (§3.4).

Corpus A's 62 paragraph rulings cannot become refuses: entries mechanically. A ruling covers a paragraph and a declaration quotes a sentence, so each of the 33 positive rulings needs one reading to pick its sentence.

The SDK change is additive: a new optional field, so a yidam-core minor bump under the semver gate, with a parity fixture so the three SDKs read refuses: identically.

Alternatives considered

Ship a lexicon. §1.3 and §1.4 are the case against. The best recall comes with 41% false positives. The one detector with no false positives has no recall. And the two detectors that find anything agree on at most 30% of what either flags, in every corpus except corpus B, whose own detector is one of the two.

[open] is the refusal marker. It needs no new syntax, and it is exact where it is written. Corpus B does this, and 15 of the 37 paragraphs it flags that way are ruled not to be refusals. It also misses the motivating case, a [verified] fact whose inference is refused without the refusal being [open]. A standing and a refusal are different properties.

A fourth inline tag, [refuses]. It is readable in place, but agent-conduct.md names three tags and pins the count. The tag parser would also need a narration rule to tell a mark from a mention, which corpus A had to build with its own override file. A structured key has neither problem.

Keep rests_on: as the key. Three of four layers use it. But a second name for RFC-0034's entry would make two grammars for one object. The migration cost is a key rename.

Reading (iii), refusal anywhere in the node. This is allen-county-ohio's rule. §4 is the case against: 97% of the answers it produced do not answer anything the assertion rests on.

A declared tier checked for equality. This is corpus B's rule. It stores what the check can compute, and it can only drift. Corpus C's check is closer to this RFC's: its declared rests_on may not be stronger than the weakest tag cited, which is a reach under another name. reach: stores the decision the check cannot make.

Open questions

Is derive the right word? "Derived repository" already means a fork of this template, and the help group "Deriving and maintaining a repository" uses that sense. agent-conduct.md and directories.md use "derivation" in this RFC's sense. #1053 asked for derive check. A reviewer who finds the collision worse than the fit should say so before the command ships, because the name is frozen once it does.

Should a candidate be silenced? §3.6 leaves an Info standing until a refusal is declared. A paragraph read and ruled not a refusal keeps reporting. Corpus A's rulings file carries both verdicts for this reason. A not_refusal: entry on the node would carry the negative ruling, and whether the noise earns a second key is a question for the first repository that adopts this.

Does anyone move? RFC-0034 recorded the honest risk: a grammar with no consumer is a surface with no subject. The falsifier is the same shape and just as cheap. One quarter after this ships, count the repositories with a [derive] section and the nodes with a refuses: entry. At zero, the four local gates were the right answer and this was a fifth.