willtools-demo/docs/knowledge-override.md

# When a higher layer contradicts a lower one

Ruled by the engineer 2026-08-30:

> 我需要不同级别的知识之间矛盾的碾压。高级别的知识（job）总是修正低级别
> （plant）的知识。

The precedence itself already works: DEFAULTS, catalogue, plant, job, project
config, each overriding the one before. What does not exist is any way to tell
a **contradiction** apart from a **completion**, and the two mean opposite
things.

## The case that forced this

    plant.rails.left_rail_is_fixed = null      "this plant has a fixed rail,
                                                but which side is not stated"
    job.rails.left_rail_is_fixed   = false     the current job

The plant manual documents a fixed rail on its beam beds (section 6141.0 /
6142.0, left rail labelled FIXED RAIL). Its wall-panel beds never say. This
job's panels are not cast on any bed in that manual, and **have no fixed rail
at all.**

So the job value is not filling in a blank. It is overruling the plant's own
practice, for a stated reason -- different beds -- and a reader of either file
alone cannot tell. Today the merged tree just says `false` and no output
mentions that anything was overridden.

## Correction, same day: no fourth state is needed

This document first argued that `left_rail_is_fixed` needed a fourth value
meaning "neither rail is fixed", on the reasoning that `false` asserts the
right rail is fixed instead. **That reasoning was mine and it was wrong.**

Will: "为啥左轨不是固定的，就是右轨是固定的？...这个行业里压根就没有固定右轨
的说法。" There is no such thing as a fixed right rail. So `false` already
means exactly what this job needs -- the left rail is not fixed, full stop,
and there is nothing else for it to imply.

The code was already right. `aiextract._rail_sentence` renders `false` as
"That rail is NOT the bed's fixed rail on this job, so do not assume
dimensions accumulate away from it" -- no inference about the other side.
the current job's `false` is correct as it stands and needs no change.

What was genuinely wrong was a comment, and it sat in the worst possible
place: `knowledge.py`'s `PLANT_STARTER` template, which is what every new
plant reads when its configuration is first written. It said some plants cast
against a fixed left rail "and others do the opposite" -- stating a fixed
right rail as ordinary practice. Corrected 2026-08-30, along with a note that
`false` and `null` stop the same reasoning for opposite reasons: `null` is
"we do not know", `false` is "we know, and there is none".

**And a second correction, from the same exchange.** I also wrote that `false`
and `null` both stop the reasoning. They do not. Will, quoting his own earlier
ruling: "false 不应该让推理停手。false 的意思是允许 bed_offset，并且需要读
max_bed_width，等等的一系列逻辑." Found in the transcript of an earlier session,
in his words:

> left rail 不一定是 fixed rail，所以实际 wall 的 strand pattern 会有出入，
> 但是所有的出入都是 bed offset.

> 这个参数用就是 false。厂层面添加一个 max_bed_width 参数，并且这个厂
> 这个参数是 12'-0"。这个参数决定了我最大的 offset。如果我的 panel_width 是
> 11'-11"，那么我的 offset 就不能超过 1".

So `false` **starts** a reasoning rather than stopping one: with no fixed rail
the piece may sit anywhere across the bed, the pattern slides, and the slack is
exactly `max_bed_width_in - panel width`. The spacings between strands must
still be reproduced exactly -- only the rail-to-first-strand distance moves.
`null` is the only value that stops anything.

All of this is already implemented and correct: `_check_bed_offset` in
`ticketchecks.py` runs it, and the plant file carries `max_bed_width_in: 144`.
Only the comment was wrong.

**Known gap found while checking this -- CLOSED 2026-08-30.** As first
written, `_check_bed_offset` never read `left_rail_is_fixed` and allowed the
pattern to slide unconditionally: right for `false`, wrong for `true`, and a
plant that set `true` would have been quietly ignored.

**That is no longer the case, and the two paragraphs that followed here said
so wrongly until 2026-08-31.** The flag is wired and it does three different
things. `_check_bed_offset` (in `ticketchecks.py`, called from 4.4's
`check_strand_layout`) reads it and hands it to `ticketpage.bed_offset_status`,
which branches on all three values:

| value | what BED-OFFSET does |
| --- | --- |
| `false` | the bed has no fixed rail: the piece may sit anywhere across it, and the ceiling is `bed width - panel width`. Over that is a FAIL, under it an OK. |
| `true` | the left rail IS fixed, so the slack is not slack. Reports the offset as a **WARN** and says plainly that it was **not judged** -- because what a fixed-rail plant should tolerate is still an open engineering question (see "Not settled" below). It deliberately does not fall through to the `false` path, which would spend slack that is not there. |
| `null` | nobody recorded it. Verdicts are the `false` ones, but every message carries "`rails.left_rail_is_fixed` is unrecorded; this reads the bed as having no fixed rail", so the assumption is visible rather than silent. |

So the flag is **read by a check, not only by a prompt**. `aiextract` still
renders it into prompt text as well (`_rail_sentence`), but that is now the
second reader, not the only one. `tools/knowledge_drift.py` grades it the same
way -- its header says this key "HAD a reader ... and was still drift", in the
past tense, and cites it as the shape a surface-only key takes rather than as
a current example.

What has *not* changed: `check_strand_layout` still measures the strand chain
from both edges and keeps the better fit. It does not use the flag to choose
an edge; it uses it, through `_check_bed_offset`, to decide whether the
resulting offset is slack or a finding.

## What is required

1. **A value that means "no fixed rail on this job."** Distinct from null.
2. **An override must be able to declare itself** -- carry a note saying what
   it sets aside and why. `knowledge.py`'s own module docstring has argued for
   this since it was written: an override "should have to declare itself ...
   and the tool should say, in its output, that one is in force. Not refuse
   it. Just never let it happen silently."
3. **The report must say an override is in force**, and say which. A merged
   value that contradicts the layer below it is a fact about the run, and a
   reviewer asking what a piece was checked against deserves to see it.

Note the mechanism must survive the merge's own rule: maps deep-merge, **lists
replace**. A declared override on a list key is a replacement whether or not
its author knew it -- which is how this job silently dropped five of the
plant's exempt families earlier today.

## Not settled

Two questions, both engineering rather than coding, and both the owner's:

1. What a check should do when the answer is "neither rail is fixed" -- stand
   down and report NOT RUN, or run in some reduced form. It decides whether
   4.4 runs at all on this job.
2. **What a fixed-rail plant should tolerate.** With `left_rail_is_fixed: true`
   the pattern cannot slide, so the bed-width ceiling is not the right test and
   no other number has been chosen. BED-OFFSET therefore reports the offset as
   a WARN and says it was not judged (chosen 2026-08-30). Until a tolerance is
   given, that WARN is the honest answer; do not invent one.

---

# One plant layer per plant, and the job names which

Added 2026-08-30, with the face-designation and rebar-stock work.

Until now the plant layer was a **single file per machine** --
`%APPDATA%\WillTools\knowledge.yaml`, or whatever `WILLTOOLS_KNOWLEDGE`
pointed at. One machine, one plant, forever. It is now **one folder per
plant**, and a job says which plant it is produced at:

```yaml
# <model>/_ticketqc/knowledge.yaml -- the JOB layer
job:
  plant: northgate
```

resolving to `<root>/northgate/knowledge.yaml`. **A second plant is a new
folder, never an edit to the first one's file.**

## Where `<root>` is, and why nothing had to be reconfigured

The root has always been "the folder the machine-wide `knowledge.yaml` is
in", and that relationship is what makes the variable keep meaning what it
always meant:

| `WILLTOOLS_KNOWLEDGE` | root | no plant named | plant named |
| --- | --- | --- | --- |
| unset | `%APPDATA%\WillTools` | `<root>\knowledge.yaml` | `<root>\<plant>\knowledge.yaml` |
| a **file** | that file's directory | **that file** -- untouched | `<root>\<plant>\knowledge.yaml` |
| a **directory** | that directory | `<root>\knowledge.yaml` | `<root>\<plant>\knowledge.yaml` |

Reading the root backwards off a variable that names a file is the definition
read backwards, not a guess. So a machine already pointing at one file picks
up per-plant folders as **siblings of the file it already names**, with no
change to the variable -- and a machine that never names a plant reads exactly
the file it always read. That backwards compatibility is not a nicety: the
single-file arrangement is what every machine but the author's is set up for,
and a silent break there would cost more than the feature is worth.

The per-plant folder and the machine-wide file share a root and cannot
collide: one is a directory, the other is called `knowledge.yaml`.

## The ordering trap, and the two-pass that solves it

`knowledge.load()` merges DEFAULTS then catalogue then **plant** then **job**
then project config. But `job.plant` -- the key that *chooses the plant file*
-- lives in the job layer, which merges **after** the plant layer. The
dependency runs backwards through the merge order and no reordering of those
lines fixes it.

So the job file, and the project config above it, are read **once, on their
own, before anything is merged**, purely to answer "which plant".
`knowledge.plant_id(doc)` does that and nothing else.

**Do not simplify it back into one pass.** Deleting the pre-pass makes the
tool read the machine-wide plant file while the job file plainly says which
plant it is for, and every report still looks entirely normal. There is a
tripwire for exactly that: after the merge, the plant the file was chosen by
is compared against the plant the finished tree names, and a disagreement is
recorded as `_plant_layer_stale` and printed by `config_problems`.

## What is loud, what is quiet, and why

| situation | behaviour |
| --- | --- |
| job names a plant with **no file** | `_plant_missing`, a sentence from `config_problems`, and **no fallback**. Running one plant's job on another plant's rules is worse than not running. |
| job names a plant whose id is **not a folder name** (`../x`, `a/b`) | refused outright, `_plant_missing` with a null path. A malformed name scrubbed into a nearby folder is how a run ends up on the wrong plant looking normal. |
| `WILLTOOLS_KNOWLEDGE` set, file **gone** | `_plant_env_missing` and a sentence. Somebody pointed the tool at a file and the tool did not read it; nothing else would say so. |
| job names **no plant at all** | **quiet, deliberately.** The machine-wide file is read, exactly as before this key existed, and that is the state every install that predates it is in. A warning on every run of every install is a warning that stops being read. It is still on the record: `_plant_id` is `None` and `knowledge.sources(doc)` names the file that was read. |

## Face designations: a library published once, selected per plant

`knowledge/catalogue.yaml` -- the public layer -- now carries a library of
**face-designation vocabularies**: the parenthetical suffix on a call-out,
`SR324 (F.F.)`, `SR310 (E.L.)`, `P76 W/ SR5602 (S.I.F.)`. The abbreviations
are the trade's and identify nobody, which is exactly why they are
publishable.

**Which set a producer uses is plant knowledge**, so the plant layer selects
by id and never copies the tokens down:

```yaml
face_designations:
  use: [near_far, in_form]        # a LIST -- it replaces, it does not merge
```

`use` being a list is the right semantics, not an accident: what a layer names
is exactly what is in force. A vocabulary left quietly selected from the layer
underneath would resolve tokens in a frame nobody chose. A plant using a token
nobody published adds its own under `vocabularies` -- a **map**, so it
deep-merges and the published ones survive.

### Why each vocabulary declares its frame of reference

Two families of terms, measured from different things, not interchangeable:

* **`frame: view`** -- near / far. Measured from **the viewing direction**. It
  flips when the view flips. An elevation that looks at the panel from the
  opposite side than was assumed makes every `N.F.`/`F.F.` on that sheet
  backwards, and each one individually still reads perfectly normal.
  **This is the *published* near/far vocabulary and it is not universal --
  see "Two corrections" at the end of this file: at the plant in front of us
  `N.F.` is anchored to the FORM and *is* `T.I.F.`.**
* **`frame: form`** -- top / bottom in form. Measured from **the casting bed**.
  Absolute for the piece; a flipped view does not touch it.

Flattening both into one token-to-meaning map throws away exactly the
distinction that makes checklist 5.3 decidable. So the frame is structural,
and `knowledge.face_designation()` returns it with **every** lookup: `side`
alone is not an answer, because `'near'` only means something once you know it
is read off the view.

A plant commonly uses **both at once** -- near/far names a layer position and
in-form names a casting orientation, and one ticket prints both. Two selected
vocabularies claiming the same token in *different* frames is the one
genuinely undecidable case, and `config_problems` reports it.

## Rebar stock: per size, with "not stocked" as its own fact

`catalogue.rebar.stock_length_ft` is **one number for every size**, and
checklist 5.7 ("no bar longer than the stock it is cut from") compared against
it. Real stock is per bar size and the small sizes are commonly nothing like
40 ft, so a 30 ft `#4` at a plant that stocks `#4` in 20 ft lengths **passed**.
A false OK on a real defect class.

The per-size table is `catalogue.rebar.stock_by_size` and it is **plant
knowledge** -- what a producer stocks is that producer's, so it is never in
this repository. Resolution, in `knowledge.rebar_stock()`:

1. the per-size entry, if there is one -- `basis: 'by_size'`
2. otherwise the generic number -- `basis: 'generic'`, and the sentence says
   the number is not size specific
3. otherwise **nothing** -- `basis: None`, both lengths `None`, and the check
   must stand down and print `why`. It never assumes.

Three shape decisions worth keeping:

* **A map keyed by the printed size** (`'#4'`), so the layers deep-merge: a
  job that special-orders one size adds one key and inherits the rest. As a
  list, a job adding one bar would delete the plant's whole stock table with
  nothing anywhere saying so. The cost, stated rather than hidden: a higher
  layer can override a size but cannot *remove* one -- and removal is not what
  anyone means, because a size the plant stopped stocking is `stocked: false`,
  which is a fact worth printing.
* **Integer inches.** Two common stock lengths are not whole feet -- 23 ft 4 in
  is 23.3333... ft -- and a bar cut to exactly that would fail a comparison
  against a decimal-foot copy of its own stock length. `rebar_stock()` returns
  both units so no caller ever converts.
* **`stocked` is its own fact, separate from the length.** A size can be
  listed with a length *and* marked not stocked: the length is what would
  arrive if it were ordered, and "not stocked" is why a ticket calling for one
  deserves a human. Neither is modelled as the absence of the other.

### An ASTM designation is not a grade

`catalogue.rebar.astm_grades` is public -- it is what the standard says. It
exists to stop anything reading a designation as a strength:

| | |
| --- | --- |
| **A615** | Grades 60, 80 and 100 (historically 40 and 75). **`default_fy_ksi: null`** -- no default is defensible. |
| **A706** | Grades 60 and 80. `default_fy_ksi: 60`, recorded **as a default**, with who ruled it and when. |

`knowledge.rebar_fy()` always returns *where its answer came from* --
`'stated'`, `'astm default'`, or `None` -- so a default can never be read as a
measurement. Nothing anywhere quietly falls back to 60.

### Present-but-empty is a third state

A producer's stock section may **name** a designation and list nothing under
it. That is a fact, and a different fact from never mentioning it, so
`catalogue.rebar.astm_designations` and `knowledge.rebar_astm()` keep three
states apart: `sizes_listed: true`, `sizes_listed: false` (named, nothing
under it -- **not** "the plant has none"), and no entry at all.

## Which families are reinforcing: a rule, not an enumeration

`drawings.reinforcing_families` is a **list of family names**, and checklist
5.6 and 5.7 rest entirely on it. An enumeration goes stale in silence: the day
a bar family is added and nobody re-lists it, both checks stop seeing those
bars and report nothing -- which reads exactly like nothing being wrong.

So the same fact can now be stated as a **rule**: a category to look in, plus
a token to find in the family name.

```yaml
drawings:
  reinforcing_rule:
    category: Generic Models       # VERIFY IT AGAINST A MODEL FIRST
    category_verified: true
    name_contains: [rebar]
```

`knowledge.reinforcing_family_verdict(know, family, category)` resolves it and
returns **`True` / `False` / `None`** with a sentence. `None` is a real answer
and callers must keep it: it means nothing here can judge, which is *not* the
same as `False`. Reporting "not a bar" for a family nobody has described is
how these checks went quiet in the first place.

Order of resolution:

1. **`drawings.reinforcing_family_overrides`** -- exact name, case-insensitive,
   mapped to `true`/`false`. Definitive and first, so a job adds or excludes
   one family without restating a list or a pattern. A **map**, so a job's
   correction is added to the plant's rather than replacing them.
2. **`drawings.reinforcing_families`**, if set -- substring match, existing
   semantics unchanged. **It wins where it is set**: a plant that would rather
   name its families one by one must be able to, and being overtaken by a
   pattern it did not write would be worse than the pattern is worth. Empty
   the list to hand over to the rule.
3. **the rule** -- the category must match **and** the family name must carry a
   token. Both, never one: a token swept across every category would call
   anything named that way a bar, mesh and detail components included.
4. otherwise `None`.

**SUPERSEDED THE SAME DAY — the rule is a PARAMETER, not a category. The
section below is kept because the reason it was wrong is worth more than the
text was; the correction is at the end of this file under "The reinforcing
rule was the right shape around the wrong field".**

### `category: null` is not "no category"

It means **nobody has verified what that category is really called in the
model**, and that has to stay a distinct state, because guessing it wrong
un-recognises every bar at once -- silently -- which is the exact dormancy the
rule exists to end. So a category that has only been described in conversation
is written down as described and left unverified:

```yaml
  reinforcing_rule:
    category: null
    category_as_stated: <what you were told>
    category_verified: false
    category_unverified_because: <what is missing>
    name_contains: [rebar]
```

`knowledge.reinforcing_mode()` then reports the rule as unrunnable **and names
the reason**, quoting the words that were used. Dormant, out loud.

---

# Two corrections, same day, and what they changed in the shape

Both of these arrived after the sections above were written. They are kept as
corrections rather than edited away, because the *reason* the schema survived
them is the point: each one changed a value, and neither changed the shape.

## 1. Near/far is anchored to the FORM at this plant

The section above says near/far is view-relative. **That is the published
`near_far` vocabulary, and it is not universal.** Owner, 2026-08-30:

> NF 就是 top in form, ticket detail view: elevation top 里面, 如果是 embed,
> 那么就应该是实线, 如果 embed 但是 FF, 那么应该是虚线. rebar 无论如何都是
> 虚线, 因为 rebar 不会 expose, 总在水泥里面.

So at this plant **`N.F.` *is* `T.I.F.`** — near/far names the casting
orientation, not the viewing direction. The two vocabularies are not two
frames here; they are two names for one anchor.

**What that proves about the schema, and what it changed:**

* `frame` **stays**, and is now doing exactly the job it was added for. A
  producer that anchors near/far to the view is still a real possibility, and
  only the frame field can say which one you are looking at. Had near/far been
  hard-coded as view-relative — the obvious flattening — this correction would
  have needed a code change instead of a data change.
* The plant declares **its own form-anchored vocabulary** and selects that.
  It does **not** half-edit the published `near_far`: flipping a published
  vocabulary's `frame` to `form` while leaving `side: near` behind produces
  something that parses, resolves, and answers nonsense. `frames` now
  publishes **the sides each frame can name**, and `config_problems` reports
  a token whose side does not belong to its vocabulary's frame — that exact
  half-edit.
* The equivalence is recorded **structurally, not in a comment**. A face's
  identity is the pair **`(frame, side)`**: this plant's `N.F.` is
  `(form, top)` and the trade's `T.I.F.` is `(form, top)`, so
  `knowledge.same_face()` answers "yes, one face" from the data, and neither
  vocabulary has to mention the other.
* The equivalence is **not** generalised into the catalogue. It is this
  plant's convention; the public layer must assume nothing.

`same_face()` returns `None` — not `False` — when either token cannot be
resolved, and `False` across two different frames. Two frames is not a
failure: the question genuinely has no answer until something resolves the
view against the form, and that is a fact about the piece, not the vocabulary.

**Kept apart, deliberately, in the plant file:** `N.F. = top in form` was
stated outright. `F.F. = bottom in form` follows from the same sentence's
drawing rule (an `F.F.` embed is *dashed* in the elevation-top detail — hidden
— therefore down in the form). Both are written down; which is which is
written down too.

## 2. A706 60 ksi is the stock; A615 is a job-level exception

The manual's page 5301 files every stock length under **A615** and shows an
**A706** heading with nothing under it. Owner, 2026-08-30:

> 备的，默认就是 A706，60ksi。
>
> 老手册了。。。实际上现在已经没有 A615 了。如果又有了，那也是特例了，应该是
> job 级别知识，不应该继续放在 plant 级别了。

**This is the "present but empty" state paying for itself.** `A706` with
`sizes_listed: false` said *nothing is known about A706 here*. Had that been
collapsed into "the plant has no A706" — the tempting reading — the data would
now be flatly wrong. Read as written, it was right, and the owner's sentence
simply answers it.

What changed, and what did not:

* **The lengths survive; the ASTM label on them does not.** The size rows now
  carry no `astm` field at all. Binding a live stock length to a retired
  designation is how a stale label outlives the page it came from.
* **The material is stated once**, in `catalogue.rebar.stock_material`:
  `{astm: A706, fy_ksi: 60, basis: stated}`, with who said it and when.
  `basis: stated` **outranks** the catalogue's published A706 default, and
  `rebar_fy()` reports `'plant stock'` rather than `'astm default'` when it
  answers from it. Same number, different strength of claim, and the basis is
  what keeps them apart.
* **A615 leaves the plant layer entirely.** An A615 bar is now a *job-level
  exception*, and `stock_by_size` being a **map** is what makes that
  expressible: the job adds one size (or overrides one, with its own `astm`)
  and every plant size survives. As a list, declaring the exception would have
  deleted the plant's stock table. That case is no longer hypothetical.
* **A615 stays in the public `astm_grades` table**, which is *published
  standards data*, not a plant fact: it is what makes a job's A615 exception
  stand down correctly and say *why* (`A615 covers 60, 80 and 100 ksi — the
  designation does not imply a grade`). Removing it would leave A615 an
  unknown designation, which stands down too, but with a weaker sentence.
* **The manual's headings are kept as provenance**, each marked
  `superseded: true`. The page said what it said, and a record that changes
  silently is not a record.

## 3. Mesh is absent on this job — declared, not silenced

Owner: *WWF 在这个项目里不存在，别纠结了。这玩意儿在这个 job 里面应该默认不检查。*

Checklist **5.4** is muted in the **job** layer, through the existing
`checks.muted` map, with his sentence as the mandatory reason and the date.
Job layer and not plant: other jobs at this plant may well use mesh.

Muting is the **declared third state**, not a silence — a muted item stays on
the checklist table, repainted grey as `MUTED` with the note saying what the
check really reported, because the check still runs every time and only the
presentation changes — and the existing invariant that a mute can never
silence a **FAIL** is untouched.

Note what this does *not* settle: `families.wwf_prefix` has two readers
disagreeing about what unset means (`''` in `takeoffgather._is_mesh`,
`'WWF'` in `ticketqc`). A job having no mesh is not a statement about what a
null prefix should mean plant-wide, so that inconsistency is deliberately left
alone and stays an open question.

### A stored reason RENDERS, so it is written in the report's language (2026-08-31)

Owner, after reading a live run: ***"ticket qc 3.3 notes are still in
chinese."*** That closes a question this file had left implicit — a mandatory
reason is not an annotation, it is **product text**. It reaches the checklist
row itself, the folded muted section, `last-ticketqc.txt` and
`qc-run.json`, verbatim and uncut, on every press.

The report surface is English, so **a reason is stored in English**. That
applies to every reason string in the knowledge layers, not only
`checks.muted`: `checks.not_applicable`'s `not_applicable_because`,
`checks.only_applies_to`'s `scoped_because`, `scope.note`, and any
`*_because` / `*_unverified_because` sentence a layer supplies.

And the verbatim ruling is still kept, because **this project keeps
provenance** — as a **YAML comment above the entry, dated**:

```yaml
checks:
  muted:
    # Will 2026-08-30, verbatim: 本项目所有 panel 都没有 release ratio 要求 ...
    '3.3': "no panel on this job carries a release-ratio requirement, so the
            row would read NOT RUN forever (Will 2026-08-30)"
```

**A comment never reaches the report; a value always does.** That is the
whole rule, and it is the reason the two can be different without either one
being lost. The job layer's `3.3`, `5.4` and `1.4` mutes were rewritten this
way on 2026-08-31; a scan of both YAML files found no other rendered value in
another language.

**Still open, and it is not in this file's gift:** the Project Config window
stores what the user *types* into the mandatory-reason box, and it is the
natural place for him to type Chinese. Nothing there says the box is product
text. Either the box says so, or something normalises on the way in — and
which of those is right is a decision about the editor, not about the
knowledge shape.


---

# Which end of a piece is up: a fact that moved LAYERS, not a fact that changed

Ruled by the owner 2026-08-30, when he was asked whether to wire or delete two
plant keys:

> 哪头朝上取决于 assembly origin。也就是 TOT。写入公共知识。assembly origin
> 里面有一个朝上的头。

Which end is up depends on the **assembly origin** -- he calls it TOT -- and
that is **public knowledge**. The origin carries an up end.

## Why the placement is the whole ruling

The plant layer carried:

```yaml
orientation:
  top_is_higher_global_z: true
  top_end_families: [<an embed family>]   # a cross-check, not the definition
```

Both were settable, displayed by the config screen, and inert:
`liftexport.erected_orientation()` solved which end was up from geometry and
never read either. That is the shape `rails.left_rail_is_fixed` **had** before
it was wired on 2026-08-30 (see the correction above), and the obvious repairs
are "wire it" or "delete it".

Neither was the answer. **The fact is not a producer's to declare.** An
assembly origin is placed as part of making the assembly, and placing it *is*
the statement of which end goes up -- so it is how precast is built, not a
house habit, and it belongs in `knowledge/catalogue.yaml` beside the face
designations and the ASTM grades: the layer that ships in the repository and
identifies nobody. A key that asks a plant to declare it is not an unread key.
It is **the wrong question**, and wiring it would have made every plant answer
a question that has one answer everywhere.

## What a higher layer may override, and what it may not

`orientation.up_end` is a **map**, so it deep-merges: a producer whose
assemblies genuinely carry no usable origin corrects one field and inherits the
rest. That is the ordinary override this document is about.

What a layer may **not** do is name a different **mechanism**. And that is
exactly what `top_is_higher_global_z` was: not a different *answer* to "which
end is up" but a different *way of finding out* -- compare the two ends'
elevations in the model. The two are not equivalent, which is why the ruling
matters rather than merely tidying:

* global elevation answers this for a wall panel erected on end;
* it is **meaningless** for a piece erected long-ways, where both ends sit at
  the same height and the winner is whatever the model's rounding happens to
  be;
* an origin has a direction either way.

So a mechanism is code, and a layer that could swap it could quietly reroute
every answer in the tool. `up_end_rule()` reads exactly the fields the
catalogue documents and stands down on a `source` nobody implemented, quoting
it back rather than falling through to a guess.

`top_end_families` was not an override either. Its own comment said it was "a
cross-check, not the definition" -- and there was no check. An inert
cross-check is precisely the shape the drift report flagged, so it was deleted
too, with the family name kept in a comment in the plant file so the day
somebody builds the cross-check it comes back as data.

Both keys are gone. `liftexport.erected_orientation()` is no longer the only
place in the codebase that knows the answer.

## Dormant and loud, then live -- as data

The rule shipped with its model-reading half **null, unverified, and saying
why**, which is the `drawings.reinforcing_rule` idiom reused rather than
reinvented: `origin_up: null`, `origin_up_verified: false`, plus the words the
owner used and the reason nobody had checked them.

It went live the same day on bridge evidence:
`AssemblyInstance.GetTransform().BasisY` is the erected up direction,
correlated against extents unioned from `GetMemberIds()` member boxes across
282 assemblies. **Turning it on changed no code** -- two fields in a YAML file.
That is the return on writing a dormant fact as a shape instead of as an `if`.

What *did* need code is the three ways the reading is wrong on real pieces, and
all three **decline** rather than clamping or picking a nearest axis:

| | |
| --- | --- |
| one assembly in 282 | its `BasisY` points sideways and its face normal is up. On that piece every reading off the frame is wrong, so the check is an assertion, not a preference. |
| vertical panels | the frame is confirmed for horizontal panels; the owner has said vertical ones work differently and has not yet said how. Standing down costs one fallback; assuming costs an erection. |
| near-square pieces | long-versus-up separates cleanly at aspect ratios 1.7 and up, and two pieces sit at 1.00 and 0.92. The threshold is 1.25, chosen to sit clear of both edges of the evidence. |

## The fallback is named, every time

When the origin cannot answer, `erected_orientation()` reads which end is up
the way it always has -- world up in the panel's own axes -- and **says so**.
`basis` and `basis_why` come back with every call and ride out in the job
file's `source` block as `up_end_basis` / `up_end_basis_why`.

That is the same discipline `_plant_id: None` gets: quiet on the console,
never absent from the record. Falling back is not the failure; falling back
where no report can say it happened is. A reviewer asking what a piece was
checked against can now see which of the two mechanisms answered, which was
impossible while the answer lived only inside one function.

---

# `dimension_lines`: deleted, and what went with it

Owner, 2026-08-30, asked to keep or delete: **不要.**

The job layer carried counts of dimension strings per ticket page, measured off
139 archived tickets, so that an outlier check could one day flag a page with
too few. Nothing read it. It was declared in the job layer only -- not in
`DEFAULTS`, not in a starter, not on the drift allowlist -- so the deletion is
the key, its commented section, and nothing else.

**What is lost, stated rather than quietly kept:** page 1 min 30 / max 71 /
median 38, page 2 min 21 / max 55 / median 37, n=139 each, and the observation
that neither distribution is a single hump (page 1 clusters at 37 and again at
43; page 2 at 37-38 and again at 42). The 5th-95th percentile bounds that were
written into the key were derived from those numbers. Two clusters usually mean
two kinds of piece or two drafting habits, and which it is was always a
question for the detailer -- the key's own `source` line said so.

Worth keeping in view as a general point about this layer stack: **a
measurement is not knowledge until somebody rules on what it means.** These
numbers described what the plant ships, not what it should ship, and a check
built on them would have flagged unusual rather than wrong. That is a WARN at
best, and the owner decided it was not worth carrying a declared key for.


---

# The reinforcing rule was the right shape around the wrong field

Corrected 2026-08-30, hours after the section above was written. It is the
sharpest example in this document of the difference between a **shape** being
wrong and a **value** being wrong, because this time the shape really was
wrong -- and the way it failed is the argument for everything else here.

## What it said, and what was actually true

The rule was **a Revit CATEGORY to look in plus a TOKEN to find in the FAMILY
name**. The owner's words were "family 里面找到 manufacture_component，里面写着
rebar 的，就是 rebar" -- and `manufacture_component` was read as naming a
category. It could never be verified, so the rule shipped dormant with
`category: null`, `category_verified: false`, and the reason.

It is a shared **parameter**. It carries a short phrase per element -- `REBAR
CUSTOM REINFORCING`, `BEARING TIE`, `BLOCKOUT`, `EMBED` -- and the census that
failed to verify it read `FamilySymbol` **types** only. This plant writes the
value on the **instance**, so the census saw no reinforcing at all. Scoped to
real assemblies the bars were never hiding: 112 members on one piece, 84 on
another.

Three facts, measured, that the new shape has to carry:

* the parameter exists on **both the instance and the type, mutually
  exclusively per element** -- where the instance has a value the type is
  empty, and vice versa. `read_from: [instance, type]` is that, and a reader
  that takes only one of the two finds nothing on half the model **and returns
  a result that looks perfectly clean**;
* the plant has **already encoded this rule in the model**. Thirteen view
  filters key on the same parameter, and every string rule among them is
  `FilterStringContains` -- substring, not equality. `value_contains` is not an
  invention, it is a transcription;
* the parameter is named in this repository as a **role**
  (`member.manufacture_component`), so the office's own parameter name stays in
  the plant layer. Optional, so a plant without it is not nagged: the rule
  stands down with its own sentence.

## What the dormancy bought, and what it did not

`category_verified: false` did its job exactly: the rule never ran, so nothing
was ever mis-decided, and the report said the rule was unrunnable and named the
reason. **Had the category been guessed, every bar in the job would have been
silently un-recognised** -- which is what the flag exists to prevent and what it
prevented.

What the flag could not do is notice that the field was the wrong *kind* of
thing. A verified-false key says "nobody has checked this"; it cannot say
"this is not a category at all". The only thing that catches that is somebody
reading the model, and the shape's contribution is that when they did, the fix
was an edit rather than an excavation.

## The part that stays undecided, on purpose

The token is **not a clean boundary in either direction**, and both exceptions
are real pieces:

* `REBAR CUSTOM LIFTING` and `REBAR CUSTOM ERECTION` carry the token and are
  bar-formed **hardware** -- one is a strand loop. It has no bar mark and no
  stock length, so 5.6 ("every bar is marked") and 5.7 ("no bar exceeds its
  stock") may want it out;
* `BEARING TIE`, `RA EMBED CUSTOM` and `TRUSS CUSTOM` are reinforcement and
  carry **no token at all**.

So 5.6 and 5.7 may legitimately want different populations. `scopes` is keyed
by checklist item so they can differ, and it ships **empty with the reason
recorded** -- with nothing in it both rows see the same population, which is
today's behaviour exactly. Guessing a scope here would answer an open
engineering question silently, which is the one thing this whole document is
against.

The merge cost is stated rather than hidden, as it must be for every list in
this stack: `scopes` is a map so a job can add one row's scope without
restating the other's, but `also` and `except` are **lists inside it**, and a
layer that sets one replaces it whole.


---

# A bar's size: two structured fields, and the trap of calling one weaker

Landed 2026-08-31, closing the open question that had kept checklist 5.7's
per-size stock table dormant since the table was built.

## Two readers, two populations — not a fallback chain

Censused over a whole job (282 wall panels, 38,662 members, 24,539 of them
rebar in 13 families):

| population | field | coverage |
| --- | --- | --- |
| the one **straight** family | a dedicated String parameter, on the **type**, holding exactly the printed size | that family, and no bent one |
| all twelve **bent** families | the **family's** part description, shape `#N BENT BAR (<code>)` | 100% on the type, instance count zero; 7,405 of 7,405 parse |

**The two sets are disjoint.** No bar carries both, so `bar_size_of()` tries
one first only because something has to be first, and that order has never
decided anything. Reading it as a ranking is the mistake this section exists
to prevent — see below.

Both are declared through **roles**, so no parameter name enters this
repository: `parameters.member.bar_size` for the first and
`drawings.bar_size_rule` (naming `member.identity_description`) for the
second.

**The straight half needed no code change.** `ticketchecks._bar_size` already
read the instance and then `el.Symbol`, and the value is on the Symbol. That
is the return on having written the reader as a role lookup instead of a
parameter name: the fact arrived and one line of YAML turned the row on.

## The correction that is worth more than the code

This document, and the plant file, said for part of one day that a size parsed
out of a description was a **weaker claim** than one read from a dedicated
parameter — on the grounds that the description field is the owner's freeform
notes, the standing example being a fixed token sitting inside otherwise free
text.

**That is true of the ASSEMBLY's field and false of the FAMILY's.** Owner,
2026-08-31: *"assembly 的 identity description 是我的随笔。family 的不是。"*
Two different fields, on two different kinds of element, sharing one name —
the exact collision this codebase keeps paying for. The assembly's is running
notes; the family's is structured plant data describing the part.

The measured evidence had already said so and was overridden by the bad
premise: 7,405 of 7,405 members parsing in one uniform shape is not what
freeform prose looks like. So `description_read_from: [type]` is now a
declared key rather than an assumption, because reading the wrong one of the
two gets prose where structure was expected and looks fine doing it.

**What survived the correction unchanged is the strictness**, and the reason
for it changed rather than the rule: the parse requires the `#N BENT BAR`
shape and returns nothing otherwise — not because the field is unreliable, but
because **the shape IS the evidence** that the leading token is a bar size. A
description that stops having the shape stops being evidence, so the bar goes
**unjudged** rather than mis-sized. A leading *bare* number is refused for the
same reason: nothing marks it as a size.

`basis` is still recorded — `'parameter'` / `'description'` / `None` — not
because one is weaker but because a verdict that cannot say what it read
cannot be audited. Same discipline as `rebar_stock`'s basis and `rebar_fy`'s.

## A live defect the census turned up, in the strong source

The size parameter's distinct values included one that is **not a bare size**:
a size with a parenthesised grade after it. `rebar_size()` required the whole
string to be the size, so it returned `None`, and **every bar of that size
went unjudged by 5.7 — silently.** An unreadable size is a stand-down, and a
stand-down on one value out of five looks exactly like a working check. It was
also, almost certainly, the one bar the owner had specifically told us existed
on this job.

The fix is deliberately narrow: a **parenthesised** trailing group is a
qualifier and is tolerated; anything else trailing is not a size. Widening it
to "a size followed by whatever" would make a part description read as a bare
size, and a plant that mapped the size role at that field would then be
parsing prose with the strong reader.

And the qualifier is **kept rather than discarded**, because at least one of
them is a grade. `rebar_fy()`'s provenance chain has `'stated'` as its
strongest rung and had nothing in the model to fill it from — every bar
answered from a plant or ASTM default even where the model said otherwise.
`bar_size_of()` now hands the number out as `qualifier_fy_ksi`; nothing
applies it behind a caller's back, and a number outside every published rebar
grade is not read as a strength at all.

## The alternative, considered and rejected — with the reason

A bar-diameter parameter plus a diameter-to-size map covers straight and bent
bars in one reader, and it was the obvious answer before the census. It is
**not universal**: four bent families (534 members, 7.2% of bent bars) carry
no diameter on any member, and all four parse cleanly from their description.
So the map would have had a hole the description route does not — on top of
needing nominal diameters, a tolerance band per size, and a ruling for a
diameter landing between two bands.

Recorded as rejected rather than merely not built, because "why not just read
the diameter" is the first thing the next reader will ask.

## What stayed open

The straight family's shape token is a single letter. If that letter denotes a
*bent* shape then 17,134 members are bent in fact and described as straight,
and the split this reader rests on is not the split it thinks it is. Nobody
guessed; it is with the owner.


---

# The face a part goes on: the model records it, and the drawing renders it

Landed 2026-08-31. It is the field the face-designation vocabulary work of
2026-08-30 was waiting for, and it landed as **data plus lookups**, with no
check built — `ticketchecks` and `ticketpage` belong to other work.

## Why not read the line on the sheet

The plant's rule is about the drawing: on the elevation-top detail an embed on
the near face draws solid and one on the far face draws dashed. So the first
instinct is to read the line, and the question "what makes the line dashed"
sat open for two days. The answer is Object Styles — per subcategory, project
wide, no view filter and no view override involved.

**But the line is a rendering of a fact the model already holds**, one layer
further from the data, and reading a render to recover a fact is not merely
the long way round. It is unsound here: the same view carries 57 hand-drafted
detail curves with line styles of their own, so some of what reads dashed on a
sheet is not derived from any model member at all.

The face is a String shared parameter on the element **instance**. That is
what was landed.

## Four shape decisions, each one a failure avoided

**1. The join is its own key, not an alias on a published token.** The model
writes a token without dots where the ticket prints one with them. The obvious
move is to add an alias to the published vocabulary — and a vocabulary's
`tokens` is a **list**, so lists replace: a plant adding one alias would
replace the entire published vocabulary. That is precisely the half-edit
`face_designation_problems` already refuses. So the plant states a **map** from
what its model writes to what its ticket prints, the map deep-merges, and the
printed token then resolves through the machinery that was already there. Two
facts, two keys.

**2. It reads the INSTANCE, and `read_from` is `[instance]`, not
`[instance, type]`.** This is the one place the shape differs from
`drawings.reinforcing_rule`, where both really are right because the two are
mutually exclusive per element. Measured over 180 real tickets: the **same
part code carries different face tokens on different sheets** — 24 codes do,
six of them carry three. The face is a property of the **placement**. A type
read is therefore not a weaker version of an instance read; it collapses
distinct facts onto one answer and returns something that looks perfectly
clean.

**3. A modifier is not a face.** A call-out can stack two parenthesised
groups, the second saying something orthogonal to the face axis — it does not
say *which* face, so it has no `(frame, side)` and cannot be a vocabulary
entry at all. A reader expecting exactly one parenthesised group **mis-parses
the pair**. Modifiers are their own declared set; `split_face_callout()`
strips them and resolves the face underneath, which needs no meaning at all —
and the meaning is recorded as an **inference, unverified**, with the owner.

The negative is declared beside it: one group pattern-matches a face
designation exactly and qualifies a *dimension* instead. Without somewhere to
record "this is not one" it returns forever as a false positive or an
unexplained unknown, and neither is a state anyone can act on.

**4. Which member kinds a token may attach to is DATA.** Measured over the
whole ticket corpus without exception: the side-in-form token attaches to an
embed 177 times out of 177 and never to a bar; the each-layer token attaches
only to bars. So one on the wrong kind is **wrong by construction**, which is
a real finding waiting for somebody to write the check — and a fact that would
rot inside one if it were written there. `face_attachment_verdict()` answers
True / False / **None**, where None is "no rule recorded" and is never False.

## Absence is not a value, on either side, and no key may say it is

Measured in the model: the kinds that use the field write the near-face token
**explicitly 163 times** and still hold 1,304 blanks. If blank meant near
face, near face would never need writing. Measured on paper: 933 call-outs
carry a token and 461 do not, and **219 of those 461 use a code that is tagged
elsewhere on the same sheet** — an unmarked call-out is annotation that was
not repeated.

So there are **three states**, and a report owes each a different sentence:

| | |
| --- | --- |
| a recorded token | resolves to a `(frame, side)` |
| blank on a kind that **does** record faces | **unknown**, and not near |
| blank on a kind that **never** records one | the field does not apply |

Telling the second from the third needs the list of kinds that record a face.
The census established that exactly five do and that every other kind is 100%
blank, but not *which* five — so `recorded_on` ships **empty with the reason
written down**, and the reader says a blank cannot be told from a
does-not-apply rather than picking one. `same_face()` returning `None` rather
than `False` is the instrument for all of this and it already did the right
thing.

## Lifting hardware is its own stand-down, and it is not a corner case

The ticket prints the near-face token **829 times** — the most common face
call-out in the job — and the part those call-outs most often name is the face
lifter, whose face field is blank on **all 1,931** of its instances, with no
face token on any other string parameter on the instance or the type. A part
that is on a face **by definition**, with a model that does not say which, is
evidence to decline on and never a disagreement.

`face_from_model_token()` takes the family name and stands down on anything
`families.lifter_include` matches, with its own sentence. That is deliberately
in the knowledge layer rather than left to the check: a stand-down a check has
to remember is a stand-down that gets forgotten in the next check.

## The per-piece fact that would have inverted half the job

The design output carries, **per panel**, which building face ends up on top
in the form — and **it varies panel to panel**. This does not contradict the
owner's `near face = top in form`; it confirms the frame is form-anchored and
supplies the bridge that was missing. But it means **the top-in-form face is
not a fixed building face**, and a check that resolves a printed designation
to interior or exterior without reading this piece's own value is not slightly
wrong. It is **inverted on every panel of the opposite handedness**, one
normal-looking verdict at a time.

It is neither plant nor job knowledge — it is a value to be *read* off each
piece, like a design number — so what a knowledge layer holds is only the
**label to look for**, and it ships **dormant and loud**: `verified: false`
with the reason, the `drawings.reinforcing_rule` idiom. `building_face_of()`
refuses without the value and quotes that reason back. It also refuses to
*invert* a stated face: a piece has more than two faces, so "the opposite of
interior" is not derivable from "interior is top in form". Read it, do not
invert it.

## What the paper cannot settle

There is **no abbreviation legend on any ticket** in the corpus — the tokens
are never spelled out. What they mean rests entirely on the owner's statement
of 2026-08-30, which is quoted verbatim above the vocabulary in the plant
file. If that is ever in doubt, the tickets cannot resolve it, and the
vocabulary's provenance now says so.

## What a 5.3 check would call

Not built here, deliberately. Per member:

1. read the role `member.face_designation` off the **instance** (never the
   type — `face_read_from()` says so as data);
2. hand the raw value to `face_from_model_token(know, value, component=...,
   family=...)`, which returns the resolved face or a `why` naming exactly
   which of the states it stopped in;
3. split the ticket's call-out with `split_face_callout()`, which strips
   modifiers, reports a declared non-face as such, and **keeps** anything
   unrecognised rather than dropping it;
4. compare with `same_face(know, printed, model_token)` — True / False /
   **None**, where None is never a disagreement;
5. check `face_attachment_verdict()` independently: a token on the wrong kind
   of member is its own finding and does not need the comparison to succeed;
6. never resolve to a building face without the piece's own top-in-form value.

A face of `None` owes the row a NOT RUN carrying the `why`.


---

# Which part plays a role depends on the panel type

Landed 2026-08-31, urgently, and it is the **second time** the same failure has
happened in this file's history.

## What happened

The owner said the face lifter on an insulated wall panel is a different part
from the one on a solid wall panel. That part was named in **no knowledge
layer at all** — not in `families.lifter_include`, not in
`handling.lifter_groups.face.families`. So on every insulated panel the tool
found **zero face lifters**, and:

* **6.1** insert capacity found nothing to price and passed;
* **6.2** insert edge distance found nothing to measure and passed;
* **6.3** and the handling result behind it were computed for a piece the tool
  believed had no face lifters;
* **Panel Lift Check** had nothing to analyse in the face-lifting stages.

All green, all meaningless, all on safety checks. And it is not a marginal
population: a ticket census found 15 of 107 pieces are insulated.

**The plant file already carried the post-mortem of the first occurrence**,
directly above the list that was wrong again: the built-in lifter list matched
none of this plant's inserts, so the same checks found zero lifters on *every*
piece and passed in silence. That comment was kept because the lesson was
worth more than the fix. It was kept, and it happened anyway — in a population
nobody had thought to separate.

## Why the fix is a shape and not two more list entries

Adding one family name would close today's hole and leave the next panel type
to rediscover it the same way. So what landed is the general fact:
**which family plays a role depends on the panel type**, expressed once.

```yaml
panel_types:
  types: {solid: {}, insulated: {...}}
  default: null                  # and it must stay null -- see below
  detect_verified: false
  detect_unverified_because: <what is missing>

handling:
  lifter_groups:
    face:
      families: [<both>]                 # the union: what every reader uses today
      families_by_panel_type:            # the same fact, narrowed
        solid: [<one>]
        insulated: [<the other>]
```

`families_for(know, path, panel_type)` resolves the pair and returns
`(families, basis, why)`. A **third panel type is one added key** in one map,
and a job may add one without restating the plant's — which is the only test
that matters for a shape landed under time pressure.

## The asymmetry the whole design rests on

The two ways of being wrong here are **not** symmetric, and which one is safe
depends on what the caller is doing with the answer:

| | a family left OUT | a family wrongly IN |
| --- | --- | --- |
| **recognising** a part ("is this a face lifter?") | the check finds nothing and **passes in silence** — the failure above | a visible finding about a real insert |
| **counting** one (row 6.6's parity) | wrong count | **wrong count**, and a wrong parity is a wrong verdict with nothing on the report to show for it |

So an unclassified piece resolves to the **union**, which is right for
recognition and wrong for counting — and `basis` comes back with every answer
precisely so the two callers can differ. A counting caller must refuse
anything but `'panel_type'`, and the `why` says so in as many words rather
than leaving it to be inferred.

That is why row 6.6's `parity_note_rule` ships **dormant** with the reason
written down, even though the per-type breakdown beside it is fully stated:
nothing can yet establish a piece's panel type from the model, and whether the
two parts ever co-occur on one piece is unmeasured. A flat list of both would
have been the obvious fill-in and would have been a silent miscount.

## `panel_types.default` is null and should stay null

A default is the tempting fix and it is the one that caused this. Reading an
unclassified piece as *the ordinary type* is exactly how an insulated panel
came to be checked for a lifter it does not carry — on every lifting check at
once, all of them green. `panel_type_of()` returns `None` with the reason
instead, and `None` is a real answer here, not a missing one.

## What was deliberately NOT extended, and why the direction is the argument

The face lifter on solid panels is exempt from interference twice over — the
crew rotates the disk anchor on the form, and its own bars are found by a
symmetry rule whose tolerances were measured on a piece carrying those
anchors. The insulated panel's lifter is modelled with a family name that says
outright that it has bars, so the temptation to extend both exemptions is
real.

**Neither was extended.** Nobody has said the other insert has the same
rotation freedom, and the symmetry tolerances are measurements of a different
part. Extending them would **suppress** findings; leaving them alone at worst
produces noisy ones. Suppression is silent and noise is not, so noise wins
until somebody measures it.

The same reasoning governs the missing catalogue alias. The new lifter has no
published ratings behind it, so capacity resolves to nothing (the insert is
named, nothing is claimed) and edge distance falls back to the plant-wide
minimum with a WARN saying the number may not be that part's. Both are
**louder than yesterday**, when the answer was nothing at all — and a guessed
alias would have been quieter and wrong, which is the standing lesson from the
part that was listed as a lifter and was not one.

## Matching mode: the part that had to be got right

Both lists that recognise a face lifter are matched as **case-insensitive
substrings**, and the job contains two different families carrying the same
part number — the wall-panel lifter, and a **job special plate** on slab
pieces. A bare token would sweep the second in and treat it as something a
piece hangs from, which is the standing cautionary tale in that very file
happening again.

Scope saves it today, because the slab pieces are outside the declared prefix.
**A matcher that is correct only because scope rescues it is not correct**, so
the token is written long enough to be unambiguous — which is what the file
already did for the edge anchor, for exactly this reason, and what it does not
need to do for the solid-panel lifter because that token appears in only one
family name in the whole job. The two long names are irregularly formatted
against each other, so no rule derives one from the other; stopping the token
before the differing suffix is what makes one form work for both.

**Row 6.6 uses whole-name EXACT matching instead, and the difference is the
point.** Counting is not recognising: an over-broad match in a recognition
list produces a visible finding about a real insert, while an over-broad match
in a *count* is a wrong parity — a wrong verdict with nothing on the report to
show for it. Exactness also makes the "a longer name contains this token" trap
impossible rather than merely absent today.

## The part-number grammar, and why it is data

Owner, 2026-08-31: `P` is a standard plate, looked up in plant knowledge; `SP`
is a special plate made for one job. **A layer-placement rule expressed in the
part number itself** — everything else in this stack has to be *told* which
layer owns a fact, and here the name says it. It corroborates the manual's own
custom-numbering panel, which files the special prefixes under "Non Standard
Material Job Specific": the same rule stated from the other direction.

It is a key rather than a comment because of what it makes decidable. **A part
printed on a ticket that nothing can resolve is two different problems with
two different owners**: a standard-plate number nobody can look up is a gap in
plant knowledge, and a special-plate number nobody can look up is a gap in the
job file. Reporting both as "unknown part" is right half the time and sends
the other half to the wrong desk. `part_defining_layer()` answers whose
question it is; nothing here decides a checklist row.

**Longest prefix wins**, and that is the safety rather than a tie-break: read
the short way round, a job's special plate is filed in the plant's
standard-plate namespace — precisely the merge a substring match on a bare
part number makes, and precisely what it cost on the face lifter. A prefix
whose meaning came off a manual carries `verified: false` and names the
source, because a reading is not a ruling. A prefix nobody can describe at all
is **left out** rather than given a placeholder: an entry in this table is a
claim about whose desk a missing definition belongs on.

## A note that is present and worded wrongly

Row 6.6 demands one phrase, and one real piece carries a near-miss of it. The
tempting fix is to accept both wordings; that would quietly overrule an owner
who named one phrase, so it was not done — the piece **fails**.

But it fails for a *different reason* than a piece with no note at all: one
needs a wording corrected and the other needs a note written, and a report
that reads identically for both sends the reader to the wrong job. So the
near-miss wording is recorded in its own key, **reported and never accepted**,
whose entries must be wordings actually seen in a model rather than guesses at
what somebody might type. Accepting one is a one-line change *and an owner's
decision*, which is the state it should be in.



---

# Which checks apply is itself plant knowledge

Commissioned 2026-08-31. The owner, reading insulated panels:

> *"ticketqc 检查的内容需要进行分级。根据 plant 和 ticket 的具体内容进行分级。。。
> 我正在查 insulated panels，发现这个工具在 insulated panels 几乎没用。我估计换另
> 一家 plant 也是无用。所以把 ticketqc rules 写进厂知识，让 ticketqc 工具读取厂知识
> 来得知啥需要检查，啥不用检查。"*

Two claims, and the design serves both. Applicability varies along **two
axes** — the plant, and the piece's own nature — and neither belongs in code.

## The fifth state, and where it sits among the four that existed

This project had already accumulated four ways for a checklist row to be
quiet. The commission is a fifth, and the whole value of writing it down is
that none of the five may drift into another's job.

| | what it says | granularity | does the check run? | voluntary? |
| --- | --- | --- | --- | --- |
| **`checks.muted`** | "I know, stop telling me" | per **job**, per row | **yes** — repainted grey | yes, stated |
| **declared scope** (`scope.mark_prefixes`) | "that piece is somebody else's" | per **piece**, never a row | the piece is never read | yes, stated |
| **dormant check** | "the fact that would enable me is unset" | per check | no — stands down with a reason | **no** — cured by supplying a fact |
| **grades A–D** | "*who* answers this" | per row | yes | n/a |
| **`checks.not_applicable`** | "this question is not about **this kind of piece** at this plant" | per **row × panel type**, per **plant** | **no — not at all** | yes, stated and dated |

The three distinguishing features of the new one, each chosen against one of
the other four:

* **Voluntary and stated**, unlike dormancy. A dormant check is an admission;
  this is a ruling, so it carries a reason, a date and a declarer.
* **Plant-level and conditional on the piece**, unlike a job mute. A mute is
  one job saying "not here"; this is a plant saying "not on this kind of
  thing", and the condition is a *measurable piece fact*.
* **The check does not run**, unlike a mute. Muting is a volume control; this
  is the question not being asked.

The nearest precedent in spirit is the **3.3 mute** — *"no panel on this job
ever has a release ratio"* is an applicability fact wearing a mute's clothes.
It was **not** migrated, and the reason is in its own words: it says
*本项目*, **this job**. A plant-level declaration would be a claim the owner
did not make. The same question now stands over the **1.4** mute landed
2026-08-31 (a shared jacking-force legend carries another design's name):
that may well be a plant fact rather than a job annoyance, and moving it is
his call, not a reader's.

## The shape, and the wipe-the-table trap

```yaml
checks:
  not_applicable:                   # the row is NOT asked on this kind of piece
    '3.3':                          # a ticket-checklist number
      insulated:                    # a declared panel type id, or `any`
        applies: false
        not_applicable_because: <why the question is not about this piece>
        not_applicable_since: '2026-08-31'
        declared_by: <who ruled it>
  only_applies_to:                  # the row is ONLY asked on this kind of piece
    '6.7':
      insulated:
        scoped: true
        scoped_because: <why the question does not exist elsewhere>
        scoped_since: '2026-08-31'
        declared_by: <who ruled it>
```

**There is not a list anywhere in it, and that is the whole design.** Lists
replace across the layers and maps deep-merge (§2.3). A list of switched-off
row numbers in the job file would **delete the plant's whole table** the
moment a job wanted to add one entry — the rebar stock-length trap, on a
safety switch this time. With maps all the way down:

* a job **narrows** one entry by writing `applies: true` under exactly that
  `(row, panel type)` pair, and
* a job **extends** by adding a pair,

and in both cases every other entry the plant declared survives untouched.
The wipe is not guarded against; **it is unspellable**.

### Why the reason key is named for the value it justifies

After the merge, nothing can tell which layer wrote which key. A single
`because:` would let a job flip `applies: true` and silently inherit the
plant's sentence written for the **opposite** ruling — a reason that now
reads backwards, over a re-enabled safety check. So turning a row back on
needs `applicable_because`, which the plant's switch-off entry does not
carry: the narrowing states its own case, dated, or it is refused.

`declared_by` says who **ruled**. The **layer** is computed separately, from
`configdump.layer_values(doc)`, and printed on every line — because a plant
rule copied into a job file still names the plant's engineer, while the file
somebody has to open to change it is the job file.

## The two axes, and what each one costs

`any` is the **plant axis**: "we do not do that here". It needs no
classification, so it works the day it is written.

A key that names a panel type is the **piece axis**, and it needs a
classification. While `panel_types.detect_verified` is false, such a
declaration is **REFUSED and the row RUNS**, and the refusal is printed —
because an owner who wrote a rule believes that row is off, and a refusal
nobody reports is that person never finding out it is on.

## How a piece is classified, and when it declines

`panel_types.types.<id>.signals` is a map of **measurable facts**, evaluated
by `knowledge.classify_panel(know, facts)`. The prose `model_signals` beside
it is for a reader and is never evaluated — a sentence somebody wrote is not
a predicate, and a file that let one masquerade as the other would classify a
piece off a description.

```yaml
signals:
  body_family_contains: [<token>]        # case-insensitive substring
  thickness_in: {min: <n>, max: <n>}     # inclusive, INCHES
  member_family_contains: [<token>]      # a member only this type has
min_signals: 2
```

The rule, and each half of it was chosen against a specific failure:

* **Every signal that could be evaluated must agree, and at least
  `min_signals` of them must have been evaluable.** Two, not one: the plant
  file's own note says any single signal could be a coincidence of how one
  job was modelled, and that it is three *mutually independent* ones that
  make it a convention.
* **A fact nobody measured makes its signal unevaluable, never `False`.**
* **A type that declares no signals can never be classified into.**
  Recognising `solid` as "not insulated" is the default this branch exists to
  refuse — reading an unclassified piece as the ordinary type is exactly how
  an insulated panel came to be checked for a lifter it does not carry.
* **Two types satisfied at once, or none, is a decline** — said out loud,
  naming every signal and what it said.

**A piece that declines gets the full checklist.** The asymmetry is the whole
argument: running a check that turns out not to apply is noise; skipping one
that did apply is a **silent pass**, and those are not symmetric.

`classify_panel` takes a plain dict built by `knowledge.panel_facts()`, and
is deliberately Revit-free so a second caller measuring the same facts —
`liftexport`, which needs "sum both wythes on an insulated body" — hands over
the same dict rather than inventing its own key names. `thickness_in` says
its unit in the key: the ticket carries Revit's internal **feet**, and a 16
that meant feet would match no band any plant writes, on every piece, and
report a whole job as unclassifiable with no error anywhere.

### The one place "decline → full checklist" needed refining

A row declared with `only_applies_to` exists **only** for one kind of piece —
the owner's insulated-only solid-zone check is the live example: on a solid
panel there is no insulation for a solid zone to interrupt, so the question
is not quiet, it is meaningless. Such a row has three answers, and the third
is the one that had to be thought about:

| the piece | the row |
| --- | --- |
| is one of the scoped types | asked, normally |
| is another type | **NOT APPLICABLE**, in blue, naming both types |
| **could not be classified** (or nothing can classify) | **NOT RUN, in red** |

Running it would answer an insulated question about a piece that may not be
one. Calling it NOT APPLICABLE would claim the piece is **not** that type —
precisely what could not be established. So **nobody could ask it**, which is
NOT RUN, which is red and loud, and which is cured by making the
classification work rather than by anybody's ruling. That is the dormant-check
shape arrived at from the other side, and it keeps §3.1 intact in both
directions: silence is never a pass.

## What the report renders, and why it is as loud as the scope line

`NOT APPLICABLE` is its own state word, its own machine key
(`state_key == 'not_applicable'`), `judged: false`, and **its own colour** —
blue, never a reuse of the muted grey. A reader who has to work out which
kind of quiet a grey row is has stopped trusting the table.

Blue is calm, and calm is only safe here because the declaration is loud
somewhere else. The report carries, once per run per piece:

> **PNL101** classified as **insulated** — 3 row(s) declared not applicable:
> 3.3, 5.4, 6.6
> *this piece is insulated. insulated: 2 signal(s) agree (…)*

and then every switched-off row with its reason, its date, its declarer and
**the layer that declared it**. The section **opens itself whenever anything
was switched off** — unlike muting, which folds when it is tidy — because a
mute leaves the check running and this stops it. A mistaken applicability
rule is a safety check disabled in silence, and the only thing between that
and a signed report is this section.

Two invariants survive intact:

* **A row that FAILED is never switched off.** The declaration is recorded as
  DECLINED, exactly as a mute over a failure is. The case is real rather than
  theoretical: 4.4 and 4.6 both name `check_strand_layout`, so a check kept
  alive for the row that still applies can put a finding on the row that does
  not.
* **A check is skipped only when no row it answers can be asked.** Skipping
  `check_strand_layout` because 4.4 was switched off would take 4.6 with it —
  a row nobody disabled, going quiet, because of a declaration about a
  different row.

`qc-run.json` is bumped to **`qc-run/2`** and carries all of it: the new state
in the published vocabulary, a `panel_type` block per piece (the type, the
basis, every signal's verdict, the facts, and `used_for_applicability` so
nobody may infer that an unverified classification switched something off),
and a `not_applicable` block on any row it switched off. The evidence file is
bumped to **`ticketqc/2`** and carries the facts and the classification as
what they are — inputs. Rule 1 of the file contract is discard **whole** on
mismatch, so a shape change is a bump and never a migration.

## What was seeded, and what was deliberately left empty

**Nothing is switched off.** Both tables ship empty, in `DEFAULTS` and in the
plant file, and a test pins that. The plant file carries the template and the
evidence beside it.

The first evidence run (2026-08-31, four live presses on insulated pieces)
found **the opposite of the intuition that commissioned this**, and the
template says so, so that whoever fills it in starts from the measured truth:

* the "nearly useless" wall was **already gone, and not by applicability** —
  running Extract Design took NOT RUN from 15 to 0 and OK from 11 to 22
  between two presses an hour apart, and the face-lifter knowledge fix took
  6.1, 6.2 and 6.6 from NOT RUN to OK in the same run;
* of the 13 remaining non-OK rows, **four trace to known bugs**, two are
  declared mutes, two are FOR ENGINEER by design, and five are genuine
  judgements with real arithmetic;
* **not one** non-OK row fired because the check does not apply to an
  insulated panel.

### The four things that must never be declared here

Each was a real row on that run, and each would look perfectly reasonable as
an entry:

1. **A check that is *broken* on a panel type.** Row 2.2's weight sum reads
   ~65% of the printed weight on 16" insulated bodies — a wythe or an
   insulation layer missing from the sum, which also gates 6.3.
2. **A parser missing *vocabulary*.** Row 8.1 has no words for `TOP WYTHE` or
   `HK ST100'S`.
3. **A *category confusion*.** Row 5.6 read hardware part numbers as bar
   marks (fixed 2026-08-31 — see below).
4. **Landed knowledge with no reader.** Row 5.6's other half: the owner had
   recorded that `SR4996` ships inside SP29/SP30 and is covered by their
   callout, in three places, and the check read none of them. *"我记得我增加过
   这条知识了，为什么还在 WP117 报 warn？"* — and he was right.

The test is: **does the question stop being about this kind of piece, or does
the tool stop being able to answer it?** Only the first belongs here. The
second is a bug, and a bug behind a declaration is a safety check switched
off with a signature on it — the exact failure the report contract exists to
surface.

The fourth is the one to watch, because it is the most persuasive. A row that
fires on knowledge the owner has already written down *looks* exactly like a
row that does not apply — the difference is that somebody has already made
the ruling and the tool cannot see it. Declaring it inapplicable would
"work", and it would put a second, weaker copy of a fact next to the good
one. **Before writing an entry here, grep the knowledge layers for the thing
the row is complaining about.** If it is already in there, the bug is the
missing reader.

And the counterexample arrived the same day, which is the cleanest possible
illustration: the owner's insulated-only solid-zone check is a **question
that only exists for a panel type**. It is reserved as the worked example of
`only_applies_to` and is **not built** — the population is still being
measured and the comparison it would make is undetermined.

## A new *question* is still a code change, and why the boundary is there

A plant declares applicability **over** the rows in
`ticketpage.CHECKLIST_ITEMS`. It cannot define a new row.

The rows are the universe because each one is a *claim the tool makes about a
ticket*, and a claim needs code that can be wrong in a reviewable way: a check
function, a skip probe that says why it stayed silent, a grade recording who
answers it, an owner finding code, a place in the numbering that a reader
navigates by, and a test. A YAML-defined row would have a number and a
sentence and **no way to be wrong** — it could never fail, never stand down
with a reason, and never appear in `qc-run.json` as anything but present.
That is a checklist row that always looks fine, which is this project's
cardinal failure with a friendly editor on top.

So the split is: **what to ask is code; whether to ask it, of what, is
knowledge.** A plant that needs a genuinely new question gets a code change —
and gets the probe, the grade and the test that come with it.


---

# A bar that ships inside another part, and a token that is not a bar

Landed 2026-08-31, on a live complaint:

> *"SR4996 是 SP29/30 的附属 rebar，我记得我增加过这条知识了，为什么还在 WP117
> 报 warn？"*

He was right on both counts. **The knowledge existed and one check could not
see it.**

## Landed knowledge with no reader

`SR4996` is the *"(4) #4 X 1'-6" BENT BARS"* written into the SP29 and SP30
descriptions — the angles arrive with them. He had recorded that three times:
in `interference.exempt_families` with his dated comment, in
`interference.component_groups`, and in
`drawings.annotation_covered_by_parent`. The plant file's
`rebar_must_appear_on` block states the rule in full, and it is the
specification of the fix nearly verbatim:

> *"a bar that is PART OF another item on the BOM is covered by that item's
> callout and is never drawn on its own… Looking for SR4996 as an independent
> bar and failing the ticket when it is not found would be the checker
> misreading the BOM, not the ticket being wrong."*

Checklist **5.2** read the key. The **takeoff** read the key.
**5.6 did not** — its "modelled, never printed" leg compared modelled marks
against printed text with no concept of a covered bar. So a bar that is *by
design* never drawn on its own was reported as never printed, on every piece
carrying one.

That is the drift detector's oldest category — **a key that is written,
merged, and read by nobody** — showing up live on a check rather than in a
report. It is worth naming as its own failure mode, because it does not look
like one: the report was wrong in a way that reads exactly like the tool
working.

**The fix is a named accessor, not a third inline `get()`.**
`knowledge.attached_parents()` returns `{BAR MARK: [parent, ...]}`, uppercased
and shape-normalised, and 5.6 takes it as an argument. Three readers spelling
one fact three ways is how the fourth comes to disagree with the other three.

## What the coverage produces — two outcomes, never a silence

The narrowing touches **only** the never-printed leg, and it never removes a
row's answer:

| the covered bar's parent | 5.6 |
| --- | --- |
| **is printed** | the bar is accounted for. Said out loud: *"SR4996 is attached to SP29/SP30"*, in the sentence, on the report and in `qc-run.json` |
| **is not printed** | **still a finding, and now it is about the PARENT.** The bar is unaccounted for either way; what changed is whose callout is missing |
| **cannot be read at all** | **no claim either way.** Nothing in the parent's name is shaped like a part number, so whether the ticket calls it out could not be established |

The second row is the one that keeps this honest. A narrowing that turned
"bar not printed" into silence would be muting with extra steps; what it
actually does is **re-address the finding to the right desk**. A report that
named the bar would send the reader to fix the wrong thing.

The third exists because of a real inconsistency, found by running the merged
layers rather than by reading them: **a parent is named in two vocabularies.**
The plant file names one by its FAMILY (`<vendor>_EMBED_P76`); the job file
names one by its PART NUMBER (`SP29`); the ticket prints the part number. So
the part number is extracted from whatever the key holds — the same thing
`check_bed_plan_reverse` has done with family names since 08-28. Demanding one
spelling would have turned every plant-declared parent into a finding nobody
could act on: **a false finding invented by the fix.**

That extraction needs its own regex and cannot reuse `mark_tokens`, and the
difference is exactly one `\b`. In regex `_` is a **word character**, so
`\bP76\b` never matches `<vendor>_EMBED_P76` — the same blindness that let the
scrub gate miss `PREFIX_TERM` (§3.4). `mark_tokens` keeps its boundary because
it reads printed call-outs, where it is what stops `SR1` being read out of
`SR1101`. Two functions, two regexes, and `part_numbers_in()` carries the
reason so the third caller does not reinvent it with a `\b` in it.

## Should `interference.exempt_families` derive from this key?

**Recommendation: no — and the fact that it looks like it should is worth
writing down rather than acting on.** Not rewired; 7.1 is untouched.

The two keys are close enough that the job file already tells a reader to keep
them in sync: *"These two facts travel together… if it appears in only one of
the two lists, one of the checks is wrong about it."* But they are **not the
same claim**, and deriving one from the other would assert the second wherever
somebody stated the first:

* `annotation_covered_by_parent` is about **drawing**: this bar is never
  called out on its own, because its parent's callout covers it.
* `exempt_families` is about **geometry**: this bar does not count as an
  interference, because it ships fixed to its parent and the crew can work it
  clear.

A bar can be the first without being the second. A bar drawn only as part of
its parent may still be modelled somewhere it genuinely clashes — and 7.1
exists to find exactly that. Deriving would make every drawing declaration
silently suppress a clash, which is a **suppression**, and this file's
standing rule is that suppression is silent while noise is not.

There is also a shape argument: `exempt_families` is a **list**, so it
replaces across the layers and the job file carries a restated block for the
plant's entries; `annotation_covered_by_parent` is a **map** and deep-merges.
Deriving a replacing list from a merging map would give the derived half
different override semantics from the half beside it, and the two would
disagree the first time a job overrode either.

**What is worth building instead is a consistency check, not a derivation:**
something that reports a bar present in one and absent from the other, as a
question for a person. That is the job file's own instruction turned into
code, and it neither suppresses nor invents. It is not built here.

## Is a printed token a bar mark at all?

The same run's other defect. 5.6 took **every** mark-shaped token on the sheet
for a candidate bar mark, so WP115 reported `P78`, `P114`, `SP29`, `SP30` and
`SP31` as *"printed bar marks matching no bar in the model"*. They match no
bar because they are **hardware**.

The grammar to tell them apart landed the day before —
`part_numbers.prefixes`, longest-prefix-wins — but it records what a prefix
MEANS as **prose** (`means: standard plate`). **Prose is not a predicate**, and
parsing `means` to decide would be the same mistake as classifying a panel off
`model_signals`. So the population is its own declared field:

```yaml
part_numbers:
  prefixes:
    P:  { means: standard plate,  kind: hardware, verified: true }
    SP: { means: special plate,   kind: hardware, verified: true }
    SR: { means: reinforcing mark, kind: bar_mark, verified: false }
    MK: { means: erection / site mark }        # no kind: nobody has said
```

### The two values are not symmetric, and only one of them is gated

| | effect | if it is wrong |
| --- | --- | --- |
| `kind: bar_mark` | **adds** the token to the comparison | a visible finding about something that is not a bar |
| `kind: hardware` | **removes** the token from the comparison | a real printed bar mark stops being compared — **5.6 goes quiet on the exact defect it exists to find** |

So **`kind: hardware` is honoured only on an entry that is
`verified: true`.** An unverified hardware claim is refused at run time and
the token is reported as unplaceable instead. *A reading is not a ruling, and
a reading may not switch a comparison off.* `bar_mark` needs no such gate,
which is why `SR` carries it although the `SR` entry is itself an unverified
reading — the worst that direction can do is add noise.

Three more properties, each chosen against a way this could have gone quiet:

* **A token the grammar cannot place is its own finding** — could-not-judge,
  never a quiet drop. A printed `MK12` says the grammar has a hole and names
  the hole, which is why `MK` deliberately carries no `kind`.
* **When no layer declares the grammar at all**, this stands down to
  *ungoverned* and every token stays a candidate — exactly what 5.6 did
  before any of this existed. Standing down here has to mean *do not narrow*;
  the other reading would empty the comparison for every plant that has not
  written a grammar yet. **Noisy, never quiet.**
* **"Is this mark printed anywhere" is answered from every token**, not from
  the narrowed candidates. A bar mark the grammar misfiled as hardware is
  still ink on the sheet, and the never-printed leg must not go on to report
  it as unprinted — a finding invented by the narrowing itself.

### And no `W/` splitter

`P78 W/ SR5502 (S.I.F.) (E.S.)` carries both populations. It needs no special
parsing: the grammar answers **per token**, so the part is set aside and the
bar after it is compared. A `W/` splitter beside the grammar would be a
second, weaker mechanism that can disagree with the first — and the two would
be discovered disagreeing on a ticket, not in a test.

## What this looked like, measured

Against the real merged layers, on the WP115/WP117 call-out shape:

**Before** — two WARNs, both wrong:

> 5 printed bar mark(s) match no bar in the model: P114, P78, SP29, SP30, SP31
> 1 modelled bar mark(s) are never printed on this ticket: SR4996

**After** — one OK, with everything it set aside named in it:

> all 3 modelled bar mark(s) are accounted for … ; 1 bar(s) are never drawn on
> their own because a parent item callout covers them, and that parent IS
> printed: SR4996 is attached to SP29/SP30; 5 printed token(s) are hardware
> part numbers by the plant part-number grammar, not bar marks, and were not
> looked for among the bars: P114, P78, SP29, SP30, SP31

**Both narrowings are stated, not silent.** They are named on a green row and
on a red one — a narrowing visible only when everything else passed is a
narrowing nobody audits on the runs that matter.


---

# One checklist per plant-member, and the identity that survives renumbering

Landed 2026-08-31, on the owner's ruling:

> *"按照 plant-member 这种级别，给 ticketqc 的 item 重新编号，让 ticketqc 自动识别
> plant-member, 并且做正确的 check。"*

and, on where each half lives:

> *"就是得重新编号。以后引用需要前面加 plant-member。静音系统应该是 job 级别的东西，
> plant 级别的东西就是对应的 member 有不同的 check-list. 我之前没意识到不同的 member
> 需要不同的 check-list 这件事儿。做一个总的 checklist 放 public knowledge 里面，
> 然后 plant 里面做一层映射，job 里面用静音按键去控制"*

## Three layers, and each owns exactly one thing

| layer | owns | where |
| --- | --- | --- |
| **public** | **what the questions ARE** — the universe, trade-wide | `checklist.master` in `knowledge/catalogue.yaml` |
| **plant** | **which of them it asks of which kind of member**, in what order, under what numbers | `checklists.profiles` |
| **job** | **the mute buttons** — presentation, per job | `checks.muted` |

What did **not** move is the check *functions*. A row is a claim the tool
makes, and a claim has to be able to be **wrong in a reviewable way**: a skip
probe that says why it stayed silent, a finding code, a grade, a test. A
YAML row with no function behind it would have a number, a sentence and no
way to fail — a checklist row that always looks fine.

## The trap the whole design is built around

`CHECKLIST_ITEMS` was a tuple in `ticketpage.py`. Every number in it is
named by something else: the owner's mutes (`3.3`, `5.4`, `1.4`),
`checks.not_applicable`, `checks.only_applies_to`, the QNA records,
`qc-run.json` and its consumers, `docs/checklist-code-map.md`, and the
suite. **If a number became profile-relative, every one of those would
either break or — far worse — keep working while pointing at a different
question.**

So: **the number is frozen as the STABLE ID, and the profile supplies a
DISPLAY NUMBER.** Internally everything resolves through master ids; the
qualified number is how humans and reports say it.

*Why the id is the old number rather than a new slug:* minting slugs means
translating every existing reference at once, and a mass rename is exactly
the orphaning risk this design exists to remove — paid on day one, for a
tidier spelling. The number is already unique, already tested unique, and
already what everyone writes. The cost is that an id *looks* like a display
number, which is how it would get renumbered by accident — so
`test_the_master_ids_are_frozen` compares the table against a **typed-out
golden**. A pin that recomputes both sides pins nothing.

## The reference grammar

Two forms, and only two:

| written | means |
| --- | --- |
| `3.3` | a **master id**. Every ruling written before 2026-08-31 is this form and every one still means what it meant. |
| `sample_plant-wall_panel 3.3` | **qualified**: `<plant>-<member kind> <number>`, a position on *that* plant's board for *that* member kind. |

The qualifier and the number split on **whitespace** (a display number has
dots, a member kind has underscores; a space is the one character neither
has). The qualifier splits on its **last hyphen**, so a plant whose own id
carries one still resolves.

**A qualified reference is resolved at read time and stored as a master id.**
That is the whole reason the grammar exists rather than the numbers simply
changing: a mute written as `sample_plant-wall_panel 3.3` becomes master id
`3.3` the moment it is read, so everything downstream speaks about the same
question whatever was typed.

### The limit, stated rather than papered over

A qualified reference is a position, resolved against the board **as it is
now**. If the plant moves that question from `2.1` to `7.4`, an old
reference to `2.1` has two possible fates:

* silently resolve to whatever sits at `2.1` today — a ruling now quietening
  a **different** question. This is the ambush, and it is impossible: the
  resolution is honest, so it returns whatever `2.1` genuinely is now, and
  the report prints the mute's resolved target on every run.
* fail to resolve, and be **reported** as a reference nobody can place.

So a renumbering can **cost** a reference and can never **corrupt** one —
and a bare master id, which is what every existing mute uses, cannot even be
cost. **That is why the durable form is the bare id and the qualified form
is for citing.**

### A rule for whoever writes the next example

**The qualified form contains a plant name by construction.** That is fine
in the gitignored layers and in QNA, where real references live, and never
fine in tracked code, docs or comments. Every example in a tracked file uses
a placeholder plant (`sample_plant-wall_panel 3.3`).

This was learned the direct way, the day the grammar landed: the first
examples used the real plant's name and took the scrub gate from 2 hits to
7 across three tracked files. The tension is permanent — every future
example writer meets it — so it is written beside the grammar in
`knowledge.py` as well as here. (`CLAUDE.md`'s placeholder table has rows
for a client and a job; **it needs one for a plant**, and that file is not
this work's to edit.)

## Recognising the member, and the panel type within it

Two signals, and they compose rather than compete:

* **member kind ← the mark prefix** (`nomenclature.member_kinds`, a map).
  The prefix is read by **`scope.prefix_of`** — the whole leading letter
  run, exact match — and that is the reconciliation: `scope.py` already owns
  "what is the prefix of this mark" and argues at length against matching a
  declared prefix *as* a prefix. Two readers with two rules would disagree
  about which pieces the declared scope covers versus which checklist they
  get, silently, and only on the pieces where it matters.
* **panel type ← measured signals** (`classify_panel`), refining *within* a
  member kind. An insulated wall panel is a wall panel first.
* **the profile is selected on the pair**, and a profile naming both beats
  one naming only the kind.

A piece whose member kind cannot be read gets **no profile**, and therefore
the full master checklist under its own numbering — more questions, not
fewer, on a piece nobody has calibrated for. That is also what a column
gets, honestly, if somebody runs one through: the owner's scope is cladding
only, so the first real profiles are wall-panel ones.

## Compatibility, and the hole a closed board would open

**No profile declared → the full master checklist, in master order, under
master numbers, byte-identical to what the tool printed before profiles
existed.** A test pins it, comparing the rendered text both ways.

And within a profile: **`unlisted` defaults to `ask`.** A board names the
questions that existed when somebody wrote it; the code universe grows. With
a closed list and no policy, **the next check anybody builds would be
silently unasked at every plant that has ever written a profile** — a new
safety check, shipped, running nowhere, with nothing on the report saying
so. A check the board does not name is asked anyway, under its own master
id, and the report says the board has not caught up with the code.
`unlisted: not_applicable` is the deliberate closed board and needs a reason
and a date, because it is a standing promise about checks nobody has written
yet.

## Precedence: the board, then the switch

`checklists.profiles` says what is **on the board**;
`checks.not_applicable` says whether a question that *is* on the board
applies to **this piece**. A question that was never put up cannot be
switched off, and does not need to be — so a profile should not restate what
`not_applicable` already says. Both render as the same `NOT APPLICABLE`
state and `source` on the decision names which of the two did it.

## The new failure mode, and the guard that replaces the tuple

A tuple could not disagree with the functions beside it. A YAML list can, in
**two directions, both silent**:

* a master entry naming a function nobody wrote — the row is NOT RUN forever
  and reads like an unbuilt feature rather than a typo;
* a registered check function no master entry names — the check **runs**,
  spends the time, and can never reach a row.

Three tests pair them. **The second one found two real orphans on the day it
was written**: `check_bom_strand_count` (emits `BOM-STRAND`) and
`check_picking_match` (emits `PICK-STATIONS`/`PICK-UNREADABLE`). Neither is
named by a master entry and neither emits a code any entry owns, so both run
and can never turn a row red — `check_bom_strand_count` can even FAIL while
row 4.1, which asks the same question through a different code, stays green.
They are recorded in `ROWLESS_CHECKS` with that reasoning; wiring them up is
a decision about what the report claims, and it is the owner's.

And the loader **refuses rather than degrades**: a missing or malformed
catalogue takes the button down with a sentence naming the file, because the
alternative is a tool that starts with a shorter checklist and reports every
ticket it looks at as fine.

## `5.10` is not `5.1`: a coercion trap that cost a row

`_coerce` gives YAML scalars their intended types, and it runs on **values**.
A number in a value position is numified — so a board line written
`{number: 5.10, check: 5.10}` arrives as the **float 5.1**, which is a
master id that really exists. The board silently lost a question and gained
a duplicate. It was caught by reading the resolved board back, not by
review.

It is the leading-zero lesson (`0010001` is a part mark, not a number) with
the zero at the other end, and it is **worse**: a leading zero at least
changes the text, while `5.10 → 5.1` lands on something real. Quoting does
not save it, for the reason `_coerce`'s own docstring gives — coercion
happens after parsing.

So a board line is written **`'2.1 = 5.10'`**, which never parses as a
number whatever anybody quoted; and the map form **refuses** a non-string
number rather than accepting a value that may already have been mangled,
because nothing can tell `5.1` from a flattened `5.10` after the fact.

## What was seeded

The plant file declares one member kind (the cladding prefix — the only one
whose checklist has been validated, because every check here was written
against wall panels) and one board: **the identity board**, every master id
in master order under its own number, `unlisted: ask`. So nothing about any
report changes, and the thing that gets *edited* is visible in one place.

A second board for insulated wall panels is **deliberately not declared**,
and the reason is the asymmetry: it would have to restate every question the
first one asks, and any question missed in the copying would go quiet on
exactly the pieces the owner is reviewing right now. The insulated-only
*questions* do not need one — they sit on the wall-panel board like
everything else and `checks.only_applies_to` scopes them.


---

# Connectors: the first questions added under the three-layer architecture

Commissioned 2026-08-31:

> *"insulated panel 加一个 check，检查 connector 是不是存在，以及够不够。增加一个公共
> 知识，connector 指的是穿越 insulation, 把两层混凝土链接起来的东西 ... 公共知识应该有
> connector 包含：HK Composites (ST50)，而厂知识应该有 R80=HK Composites (ST50)。"*

and, the same day: *"再增加 connector edge distance 的 check"*.

## The procedure, because every future question follows it

Adding a **question** — not a plant's opinion about a question — took
exactly four things:

1. **Three entries in the public master** (`checklist.master`): `5.8` exist,
   `5.9` sufficient, `5.10` edge distance. New ids are **minted**, never
   reused, and added to the frozen golden in the same commit.
2. **Three check functions** in `vibe.ticketchecks`, bound by those ids, each
   with a skip probe. The pairing tests fail loudly if either half is
   missing — which is what makes step 1 safe now that the list is data.
3. **Public product knowledge** where it belongs: what a connector *is*, and
   which products exist.
4. **Plant knowledge**: this plant's part numbers, the mapping onto those
   products, and one `only_applies_to` entry scoping the rows.

Nothing about the questions is plant-specific except the part numbers, which
live in the plant layer where part numbers belong. **No board had to be
edited**: `unlisted: ask` means a new master entry is asked everywhere until
somebody decides otherwise, which is exactly the property that policy exists
for — and this was its first real exercise.

## Public: the concept and the products

A connector crosses the insulation of a sandwich panel and ties the two
concrete wythes together. Without enough of them the wythes are two slabs
travelling in company — a structural condition, not a drafting one.

`catalogue.connectors.products` carries `HK Composites (ST50)` and
`HK Composites (ST100)`, each with `capacity_lb: null` and
`min_edge_distance_in: null` **and a reason beside each null**. The owner
said he will supply the datasheets; a rating nobody has read is not a
rating. **ST50 and ST100 are not folded together** — a capacity that arrives
for one may not be read onto the other.

The minimum edge distance sits **beside the capacity, in the public layer**,
because it is a property of the *product*. Resolution is **product-first**
through the plant's alias; a plant-wide fallback is second-class and the
finding **names which it used**, because *"6 inches"* and *"6 inches for
this product"* are different claims. That is 6.2's lesson carried one part
along. No published minimum and no fallback → the row stands down naming the
missing datum, and **never borrows another product's number**.

## Plant: recognition by mark on the type, and two traps that shaped it

Measured over the whole model, 2026-08-31: **1,951 connector instances**,
every one on the 27 insulated pieces, **zero on the five solid controls**,
per-piece counts 15–115 tracking piece size.

Two traps, either of which a family-name rule falls into:

1. **The part number is absent from the family name entirely** — the exact
   inverse of the face-lifter lesson, where the family name was the *only*
   place the part number appeared. A family-name key finds nothing.
2. **A decoy family exists, literally named for the part number**, carrying
   the same mark and the same component value, with **zero instances**. A
   family-name matcher finds the decoy and misses all 1,951 real pins — a
   silent **zero** on the one check whose entire job is to notice zero, and
   `5.8` FAILs on zero. That is the worst outcome available here.

So the mark is read off the **type**, through the ordinary `member.mark`
role, and the check **counts instances**. Counting instances is immune to the
decoy, which contributes none; anything enumerating *types* would
double-count. An optional `component_gate` narrows a match the mark already
made — and what it excluded is counted and named in the failure, because
"this piece has untied wythes" and "your gate is wrong" are different
problems for different people.

Two product pairings, and they are recorded **differently on purpose**:
`R80 = ST50` is the owner's own words; `R82 = ST100` is measured off the
model's own type description. The other nine numbers are **null with a
reason** — a guessed pairing would give a real connector another product's
capacity and another product's edge distance.

## Edge distance: the thickness axis is excluded, and that is not a detail

Every pin sits at exact mid-depth. A three-axis minimum therefore reports
**half the panel thickness** as an "edge distance" on every connector of
every piece — a number that is real, constant, and about nothing. An edge
distance is a distance to an **edge**; the two faces are not edges. A first
pass made exactly that mistake and would have reported 8.0 in where the true
in-plane minimum is 6.0.

The thickness axis is **derived** — the local span closest to the panel's own
thickness — rather than assumed to be an index. That is `strand_layout_of`'s
idiom, reused for the reason it exists there: a nearly square piece defeats
any shortcut. And the positions come from the same measurement path the
lifters already use; there is no second geometry reader.

**The calibration to keep:** the smallest edge distance actually built on the
measured piece is **6.0 in** (four pins; median 23 in) and the owner has
raised nothing about that piece. So a published minimum above 6 would fire on
work he accepts — **a finding to surface when the datasheet lands, never a
reason to quietly set the limit at 6.**

## Sufficiency: a real requirement the parser cannot read yet

The design summary states it — WP115 carries `HK ST100'S @1'-4" O.C.`, and
8.1 lists that line among the ones it **cannot interpret**, the same wythe
vocabulary gap that also costs 8.1 `TOP WYTHE`. The model honours it exactly:
measured 16.0 in field spacing, which *is* 1'-4".

So 5.9 has a calibrated example and no readable requirement. It returns
**(no verdict, a reason)** rather than an OK — a count on its own is a
number, not a judgement, and printing OK because nobody stated a requirement
is the silent pass this table exists to refuse. **What it needs is one
parser extension**: the design-summary reader learning the connector line
(`<product> @<spacing> O.C.`) and writing `connector_spacing_in` into the
intent. That is not built here; it belongs with the wythe-vocabulary work on
8.1, and doing it blind would be inventing a grammar for one observed line.

**End densification is normal and must not be flagged.** The measured piece
runs 16.0 in in the field with tighter 9.5/6.5 pairs at the ends, so the
comparison is against the **widest** gap: a gap tighter than required is
never the defect.

## Why all three read NOT RUN today, and what arms them

All three are scoped insulated-only through `checks.only_applies_to`. On a
solid panel the question is not quiet, it is **meaningless** — there is no
insulation to cross. On a piece nothing could classify they read **NOT RUN,
in red**, because calling them not-applicable would claim the piece is not
insulated, which is precisely what nothing has established.

And nothing has: `panel_types.detect_verified` is **false**. The connector
recognition is verified (measured, and the rule was written *from* the
measurement), but the *panel-type classifier* has still never been run
against the model. So on every piece today these three rows are red with the
reason spelled out.

**That is one press from green.** Confirm the classifier against one known
insulated and one known solid piece, set `detect_verified: true`, and all
three arm at once — `5.8` immediately (recognition is verified and a zero is
a FAIL), `5.10` when a datasheet lands, `5.9` when the summary parser learns
the line.

## One fact recorded and deliberately unread

The insulation type describes itself as *EPS with holes for **non-composite**
pins*. That is the plant's own words saying these panels are not designed to
act as a composite section — a fact with engineering weight that Ticket QC
does not act on. It is quoted and dated in the plant layer under
`connectors.insulation_note`, with an allowlist entry saying it is read by
nothing on purpose, and it must not become a check without the owner's word.