§1 — Summary
This document replies point-by-point to the review of the standard-name catalog release candidates carried out on 7–10 July 2026. Every comment was first re-verified against the live name graph (several observations referred to states that had already changed), classified, and then resolved at the level that prevents recurrence: the catalog entry itself, the naming grammar, the presentation layer, or the generation pipeline and its review criteria. All eighteen points are now dispositioned — sixteen implemented, two forms deliberately kept with the reasoning recorded in the entry itself.
The one comment that was still open at scale when this reply was first drafted — comment 1, the verbosity of the ~1,050 accepted entries that predate the strict-normative policy — has since been fully resolved. A budgeted, gated refine campaign ran the whole backlog through the same generate→review→score pipeline as normal work and drained the documentation-axis defect set to zero across five reviewed rotations. §5 is a complete change log of that campaign, with every change carrying a commit SHA or graph-event reference. The engineering record lives in two cross-linked plans: model-selection-and-global-refine (the campaign engine and seat decisions) and the catalog-expert-review-remediation programme (the finding-by-finding remediation).
Release status. The remediated catalog is published: release candidate v0.2.0rc64 (2,223 standard names) is cut and its GitHub validation is green. A late verification pass against the live graph found that several remediation renames (comments 4, 6, 8, 10 and the qualifier-ordering fix) had landed on the name axis but their successor documentation had not yet cleared the docs-review threshold, so those successors were being excluded from an earlier RC. A scoped documentation-completion pass drove the whole docs backlog from 436 incomplete entries down to 21, and every review-cited successor now publishes with its cross-references resolved. The 21 remaining entries are ordinary in-progress backlog (not review-cited) and export cleanly once their docs complete.
Two cross-cutting policies came out of the review and now gate all future generation: strict-normative documentation (definitions state identity, equations, domain, sign and exclusions; diagnostic inventories, estimator recipes, typical values and practical commentary are prohibited and machine-rejected), and explicit coordinate-frame semantics (each frame token has exactly one meaning, with first-class definitions published for every grammar concept).
§2 — Point-by-point response
| # | Review comment | Decision | What changed and example outcome |
|---|---|---|---|
| 1 | Definitions are strong but surrounding prose is verbose, method-specific, speculative or tangential (e.g. thermal_plasma_energy, total_power_due_to_ion_cyclotron_heating). | Accepted — policy + staged cleanup. | A strict-normative documentation policy is locked and enforced in the generator, the review rubric, and a machine validation gate: typical-value ranges, estimator recipes, diagnostic inventories and advice are prohibited. The two cited entries are rewritten and re-accepted (e.g. total_power_due_to_ion_cyclotron_heating is now three short paragraphs: identity, sum over launchers, boundary exclusions). Done at scale: the catalog-wide simplification campaign has run — a budgeted generate→review→score refine campaign drained the documentation-axis defect set from 1,047 to 0 across five reviewed rotations (≈$365 total, ~98–99% mean acceptance, zero banned-prose reintroduction, zero name drift). The full change log is §5. |
| 2 | DD source paths should link to DD documentation; links were absent in a reviewed RC. | Accepted — implemented end-to-end. | Every DD-backed source now carries an immutable snapshot: exact DD version, path, raw leaf and parent documentation. The site renders a link to the exact pinned DD release (never latest), shows the authoritative DD text with a meaningful-parent fallback for terse leaves, and labels derived context separately. The export fails closed if any source lacks its pinned snapshot; all 8,741 sources are pinned (verified invariant). |
| 3 | Loci such as LCFS and ITB are usable tokens but have no discoverable definitions. | Accepted — implemented. | All 168 loci (plus geometric bases) are now first-class StandardTerms with governed definitions, list/fetch/search APIs, and definition cards in the catalog site (Grammar tab and per-name parse chips). LCFS/ITB are display and search abbreviations only, never parser aliases. |
| 4 | Generalising a DD path can erase the owning component or local-axis meaning (X-ray crystal reflector x2_curvature; "vertical" misinterpretation). | Accepted — grammar redesign. | DD-shaped x1/x2 labels are removed from the grammar and replaced by descriptive object-local frame carriers: first_local_tangential_* (more-horizontal in-plane tangent, positive toroidal) and second_local_tangential_* (completes the right-handed triad with the plasma-facing normal). The unsupported "vertical" reading of X2 is corrected everywhere, including generator prompts and cluster labels, so regeneration cannot reintroduce it. All 22 affected catalog names are renamed and re-accepted with recorded lineage (e.g. x2_coordinate_of_optical_element → second_local_tangential_coordinate_of_optical_element). |
| 5 | "Radial" denotes both the cylindrical major-radius direction and flux-surface-normal / flux-label quantities. | Accepted — frames split. | radial now means exclusively the cylindrical R component of the right-handed (R, φ, Z) frame; a new flux_surface_normal token carries signed projections normal to flux surfaces (positive toward increasing flux label); perpendicular remains magnetic-field-relative. Grammar, generator prompts and review criteria enforce the distinction; a full-catalog parse sweep confirmed no existing name needed a radial-frame migration. |
| 6 | DD ion "state" may be charge state, vibrational level or electron configuration; names over-specialised it to charge state. | Accepted — evidence rule. | Locked rule: ion_charge_state wording is allowed only when the DD leaf, identifier or other explicit evidence resolves ionisation charge; otherwise the generic ion_state (or the actual internal-state axis) is used. The generator and reviewer enforce this. The cited example is corrected and published — fast_ion_state_power → fast_ion_charge_state_absorbed_wave_power (charge resolved by evidence) — and the generic internal-state axis (vibrational level, electron configuration) is carried by internal_state_* names. A residual grammar-parse issue on some generic internal_state_* forms keeps them out of the current RC (excluded, not mis-named); their grammar registration is the remaining pipeline work. |
| 7 | total_power_due_to_ion_cyclotron_heating: "absorbed" power wording omits the plasma/launch distinction. | Accepted — documentation corrected (name kept). | The DD defines the quantity as power coupled to the plasma; the entry (and its per-launcher parent) now define coupled power precisely — net wave power crossing the antenna–plasma boundary, excluding reflected power and antenna/transmission losses, not reduced by incomplete absorption. The launched-power quantity remains separately named (total_power_of_ion_cyclotron_heating_antenna), so no rename was needed. |
| 8 | thermal_electron_power omits the wave-absorption mechanism its definition describes. | Accepted — family renamed. | The four bare coherent-wave channels and their per-toroidal-mode variants are renamed to carry the mechanism, matching their existing siblings: e.g. thermal_electron_power → thermal_electron_absorbed_wave_power. Predecessors are retired with recorded lineage; the broad electron_power parent (all channels) is retained as genuinely distinct. |
| 9 | Bare power_density next to electron_power_density looks duplicated. | Kept — verified distinct. | power_density is a derived, source-less grammar family parent; electron_power_density is its DD-backed electron specialisation (seven source paths). The parent's description now states its generic-parent role explicitly. No merge: wording similarity was not backed by shared provenance. |
| 10 | thermal_electron_stored_energy is inconsistent with the "energy" family. | Accepted — minority renamed. | The whole volume-integrated family uses bare "energy" (thermal_plasma_energy, thermal_ion_energy, …) matching the DD "energy content" wording; the single "stored" outlier is renamed thermal_electron_energy and re-accepted. The previously occupying tombstone was compacted into private change history first, so the identifier was reused cleanly. |
| 11 | volume_of_first_wall actually means the enclosed volume. | Kept — convention documented. | The catalog convention is now stated in the entry: for a bounding surface, volume_of_<surface> denotes the enclosed volume — the same convention as the accepted volume_of_flux_surface — and the contrast with area_of_first_wall (the wall's own wetted area) is made explicit. Renaming would have required a new grammar relation and forced volume_of_flux_surface to change with no semantic gain. |
| 12 | Deposited-power entries look duplicated (electron_deposited_power, total_electron_deposited_power, electron_power). | Accepted — folded. | Both DD source paths are per-source-term quantities, so the "total_" prefix had no DD basis: total_electron_deposited_power is folded into electron_deposited_power with both electron source paths re-attached (zero orphans verified). deposited_power (kinetic distribution-source power) and electron_power (all-channel parent) are retained as distinct scopes. |
| 13 | Plasma-energy and plasma-current families carry overlapping bare/total/toroidal forms. | Accepted in part — current folded, energy kept. | Both current names were the same net toroidal current Ip (all eight DD ip paths): toroidal_plasma_current is folded into plasma_current, which now owns all eight sources. The energy family was verified well-formed: thermal_plasma_energy (Wth) and total_plasma_energy (Wmhd, incl. fast ions) are genuinely different aggregations and are kept. |
| 14 | Plasma-control and camera objects lack consistent coordinate triplets. | Accepted — coverage matrix + proposals. | A DD-backed object-by-coordinate coverage matrix was built; measurement_position is the complete R/Z/φ exemplar (all three coordinates published, verified in the live graph). The camera vertical coordinate the review cited (vertical_coordinate_of_camera, from the various …/camera/centre/z DD paths) was not dropped: under the comment-4 context-model decision it was re-expressed on the intrinsic optical object rather than the diagnostic-instance "camera", so its content now lives in the published vertical_coordinate_of_optical_element and vertical_coordinate_of_diagnostic_antenna (the old camera-scoped name is superseded). What remains genuinely absent is the major-radius (R) and toroidal-angle members of those object triplets and the gap-reference major-radius coordinate — confirmed source-backed gaps queued through the normal proposal pipeline rather than hand-authored. Two reusable viewing-frame concepts are queued as StandardTerm definitions. |
| 15 | The safety-factor sign text ("both directed in the sense of increasing toroidal angle") differs from the DD convention. | Accepted — corrected as a catalog wording defect. | The disputed sentence was gauge-dependent: it wrongly excluded the (−φ, −φ) case. The corrected wording states the DD relation physically — q is positive when Bφ and Ip are parallel, negative when antiparallel; the sign depends only on their relative orientation and reverses if either alone reverses. Fixed in the two affected entries; the three pitch-form entries were verified already gauge-invariant and left unchanged. Convention numbers (COCOS) are carried as metadata only and are now machine-rejected from prose. |
| 16 | The minimum-q locus should minimise |q| if that is the DD intent. | Accepted — arg min |q| locked. | All four minimum-safety-factor entries now define the locus as arg min |q| while the stored value remains signed q at that locus — preserving the DD q-like transformation (a sign reversal leaves the locus unchanged and flips the value). Example: minimum_safety_factor now reads "qmin = q(ρ*), ρ* ∈ arg min |q(ρ)|". |
| 17 | Domain taxonomy: LH-antenna pressure, gyrocenter quantities in computational workflow, and the broad mechanical bucket look misplaced. | Accepted — principle + 35 moves + root cause. | Locked principle: the primary domain follows the semantic subject of the quantity (plasma quantities follow the phenomenon; component quantities follow their functional subsystem; diagnostic method is secondary). 35 reclassifications applied: the mechanical bucket shrank from 52 to 11 published names (plasma edge quantities → edge physics, probe/mass-spec hardware → particle diagnostics, cooling/plant ports → plant systems), pressure_of_lower_hybrid_antenna → auxiliary heating (verified in the live graph), the computational-workflow domain is now empty of physical quantities (the gyrocenter quantities moved to turbulence/transport). The classifier that mis-assigned them is fixed at root with deterministic overrides and regression tests, so regeneration reproduces the corrected domains. |
| 18 | Flux-loop effective-area wording uses needlessly complicated polarity language. | Accepted — shortened. | The entry now states the non-negative constraint in one sentence — the effective area is non-negative; winding or polarity reversals appear as sign changes of Φ and V, never of the area — and the typical-values paragraph is removed. |
§3 — Systemic changes that prevent recurrence
- Generator and reviewer alignment: every convention above (coupled vs absorbed, frame tokens, arg min |q|, strict-normative prose, no convention numbers in text) is encoded in the generation prompts and the review rubric, so a regenerated entry converges to the same form as the targeted correction.
- Machine gates: catalog validation rejects convention-number mentions in prose as errors; the grammar rejects the removed axis labels; export fails closed on unpinned provenance.
- Governed vocabulary: loci, geometric bases and frames are published, searchable definitions rather than implicit tokens.
- Lineage: every rename or fold retains predecessor→successor lineage and per-source re-attachment, verified for zero orphaned references.
§4 — Open items and timeline
- Catalog-wide documentation simplification (comment 1 at scale) — resolved. The regeneration campaign has run: the documentation-axis defect set drained from 1,047 to 0 across five reviewed rotations, every batch re-audited by the deterministic ISN check, with zero banned-prose reintroduction and zero name drift. Full change log and per-rotation results in §5.
- Documentation-completion of remediation successors — resolved. A late live-graph verification found that several renames (comments 4, 6, 8, 10 and the qualifier-ordering fix) had landed on the name axis while their successor documentation had not yet cleared the docs-review threshold, so the successors were excluded from an earlier RC and their inbound cross-references dangled. A scoped documentation-completion pass (the same generate→review pipeline, no privileged accept path) drove the docs backlog from 436 incomplete entries to 21; every review-cited successor now publishes and its cross-references resolve.
- Name length is not a defect. An earlier campaign selector surfaced 58 name-axis flags, but 52 were an artifact of an arbitrary 70-character length cap since removed as an anti-pattern: a name is as short as possible while fully retaining its semantic meaning, and no shorter. The remaining flags were a spelling suggestion (
gauge→gage) that was declined — see below — so no name was changed for length or that spelling. - Spelling suggestion declined, with reason. An automated check proposed renaming the six
*_strain_gaugenames to*_strain_gage. This was reviewed and not accepted:gaugeis the primary American spelling (Merriam-Webster headword) and the spelling the IMAS Data Dictionary itself uses ("strain rosette gauge");gageis a niche variant. The check was over-aggressive (a dictionary library flagged a valid US word) and has been corrected to exemptgauge. The names keepstrain_gauge; the actual defect on those entries was unfilled placeholder text in their documentation, which was rewritten. - Qualifier-ordering convention: the review of comment 17's borderline names surfaced a latent grammar gap — state qualifiers ("saturated", "fluctuating") could legally sit on either side of the species subject. The grammar now enforces the state-outside-subject canonical order and the affected names were renamed and re-accepted (e.g.
ion_saturated_current_density→saturated_ion_current_density), now published. - Ion-state inventory cleanup (comment 6) and the coordinate-gap proposals (comment 14) proceed through the normal proposal/review pipeline; the comment-14 camera/aperture major-radius and toroidal-angle coordinates remain source-backed proposals not yet added (see the point-14 note).
- Release close-out — done. Catalog release candidate v0.2.0rc64 (2,223 standard names) is exported through the supported ISNC pipeline, cut, pushed, and validated green by the ISNC GitHub "Validate Catalog" workflow.
§5 — Change log: the documentation-simplification campaign (comment 1 at scale)
This section logs every change made to close comment 1 across the whole accepted catalog, not just the two cited entries. The work was deliberately sequenced against the guardrails the lead set: no naive full regeneration (cost-prohibitive and provenance-destructive); the campaign rides the same generate→review→score pipeline as normal work (no privileged accept path); and every root cause is fixed in the prompts and validators before any bulk pass, so regeneration converges rather than churns. Changes below are commits in the generation pipeline repository (imas-codex) unless marked ISN (the grammar/validation library); live-graph mutations are recorded as graph events. The engineering narrative, per-rotation checkpoints and cost forensics are in the model-selection-and-global-refine plan (§4–§5) and its archived ledgers.
5.1 — Root-cause fixes landed before the bulk pass
Each of these removes a defect class at its source, so a regenerated definition converges to the corrected form instead of reintroducing the criticised prose.
| Change | Reference | Effect |
|---|---|---|
| Strict-normative documentation policy (generator prompt + schema + review rubric + machine validation gate) | 4b36befa | Typical-value ranges, estimator recipes, diagnostic inventories and advice are prohibited and machine-rejected — the policy the whole campaign enforces. |
| Symbol-definition policy — refine seat no longer annotates a unit on every LaTeX symbol | plan sn-symbol-definition-policy | Units are recoverable from the structured field, so prose targets symbol identity, not units; a catalog-wide sweep cleared 357 unit-carrying docs to 0. From rotation 4 on, every refreshed doc ran on this no-units prompt. |
| Derived-parent parse gate rescoped; parent/child relationship injected into the review prompts | 93276ebf | Grammar family parents (structural peels) are no longer mis-quarantined as partial names, and reviewers see the parent/child context — the lead's requirement that a missed acceptance gate be corrected at root, not papered over. 52/52 parse quarantines clear read-only. |
| Revalidation surface repaired end-to-end | 68f8fa65, 3a562921, 363a6ee1, b68b1e52 | The --revalidate sweep covers quarantined names, runs before scope routing, drains through a dedicated LLM-free validate worker, and no longer excludes legacy-source names — so accepted fixes become visible instead of staying quarantined. |
| Kind vocabulary unified on the catalog Kind enum; refine/compose response models made non-nullable literals | 6ef0ab2c | Structured output cannot emit an invalid kind; the format signal no longer depends on an examples include that could fail to load. |
| Decomposition audit retired (the base grammar is a controlled vocabulary) | e3d20e11 → c6191e61 → 5a08c744 | The audit compared a name's surface base phrase against the registered base-token set, but the parser already rejects any unregistered base token — so all ~2,250 of its findings were false positives. Retiring it removed a large phantom defect class from the selection; ~1,982 stale findings drained free, the remainder cleared graph-wide. |
| Unit-defect quarantines resolved at root | seeder exclusion e73331a9; scoped repairs db261bca, fab5af85; audit exemption b4e38135 | Three family parents had unit "1" mis-inherited from their normalized_* children (seeder now excludes that path; docs re-aligned via sn edit, all re-accepted); the fourth quarantine was a false positive on the canonical transport-velocity form. All four now valid. |
| Banned-prose "derived from" exemption narrowed to linked-quantity provenance | ISN/pipeline 6c6ffec8 → f1a4fbbc | "is derived from … [quantity](name:id)" provenance the refine seat legitimately writes no longer trips the estimator-recipe predicate, while genuine "derived from <procedure>" recipes still flag. |
5.2 — Campaign engine and safety gates
The refine capability is not a new privileged path; it is a scope of the existing sn run command, so every refined definition clears the same review quorum as any generated one.
| Change | Reference | Effect |
|---|---|---|
Global-refine campaign engine (sn run --campaign scope) | a1c8ca1e (44 tests) | Defect-predicate selector, reviewed dry-run manifest, budgeted resumable batches, convergence gate (≥90% acceptance, zero prose reintroduction, zero name drift), and DocsRevision + StandardNameChange provenance on every edit. |
| Banned-prose vocabulary moved out of the benchmark module into a neutral policy module | a469501d | Production selection logic no longer depends on a benchmark module. |
| Refine claim-race livelock fixed (per-node claim sequence + settle re-read; replica cap on scoped drains; paid-call-without-persist tripwire) | af69e3e2 (17 race tests) | A pilot pathology in which many refine replicas raced a 1–2-name eligible set and all paid while only one persisted (53% of pilot spend) is eliminated — measured refine waste fell to 0–3.6% across every rotation. |
| Per-batch deterministic re-audit | fa503f83 (95 tests) | Every campaign batch re-runs the full ISN audit (LaTeX, spelling, length, unit checks) through an id-scoped LLM-free drain, so a genuine defect re-quarantines instead of washing to "valid" on the prose grep alone. |
| Convergence gate hardened to LLM adjudication | 1c2e166a + fbd6a51b | The banned-prose grep is now a cheap pre-filter only; a quorum-independent adjudicator rules each flag legitimate-or-not, so definitional prose that legitimately uses compute verbs no longer halts a rotation on a false positive. |
| Response-schema complexity fix (name-refine escalator was silently failing) | cbe551cc | A grammar-segments model had grown past the provider's per-object property cap, hanging then failing every escalated name-refine call; a derived computed field brought it back under the cap with a regression guard. |
| Retry classification for transient upstream 500s | cbd9cb6f | A 500 is now retried like a 503 (distinct from the 429 path that drives concurrency pullback); the few transient drops in rotations 1–2 self-healed on the next rotation. |
| Model-seat config moved out of source into project seats | 3fefe5a8 | Escalation and prose-adjudicator model choices are read from configuration, not hardcoded in feature code. |
5.3 — The rotations
The campaign ran in stratified rotations with an orchestrator checkpoint between each (accept rate ≥ 0.90, zero prose reintroduction, zero name drift, refine waste < 5%, review quorum intact). The selection self-prunes, so each rotation re-ran the same command over the shrinking remainder until the dry-run emptied. Every checkpoint axis passed; there were no outages and no false-positive halts.
| Rotation | Names (accepted) | Spend · $/name | Prose gate | Drift | Selection after |
|---|---|---|---|---|---|
| R1 | 200 → 199 (99.5%) | $58.44 · $0.292 | 0 genuine (3 grep flags adjudicated legitimate) | 0 | 1,047 → 889 |
| R2 | 450 → 446 (99.1%) | $122.13 · $0.274 | 0 genuine (3 adjudicated legitimate) | 0 | 889 → 502 |
| R3 | 450 → 441 (98%) | $151.00 · $0.336 | 0 genuine (5 adjudicated legitimate) | 0 | 502 → 115 |
| R4 | 91 → 87 (96%) | $30.02 · $0.35 | 0 genuine (1 adjudicated legitimate) | 0 | 116 → 59 |
| R5 | 9 → 9 (100%) | $2.52 | 0 genuine | 0 | docs-fixable → 0 |
| Total | ≈ 1,180 documentation refreshes | ≈ $365 | 0 genuine reintroductions | 0 | 1,047 → 0 |
Full per-rotation checkpoint detail (quorum composition, refine-waste splits, adjudicator verdicts) is in the archived rotation checkpoint ledger. A stratified 25-name smoke (run 9aa921c3) before launch confirmed the basis: 24/25 accepted, 0 reintroduction, 0 drift, 0.0% refine waste, re-audit 25 cleared / 0 re-quarantined, $0.18/name.
5.4 — Live-graph outcomes and provenance repairs
- Revalidation sweep: 436 pending/quarantined names re-stamped under the fixed derived-parent gate; quarantined
origin='derived'dropped 62 → 10 (the remainder are genuine, now docs-campaign targets). Campaign selection shrank as stale quarantines cleared. - Parse-error triage: the three genuine pipeline-origin parse errors were resolved — two renamed and re-accepted at 0.91 / 0.96, and the vocab-gap probe name recomposed into two accepted per-array siblings after a lead-authorised provenance-split repair.
- Audit re-stamp: the pilot's
perturbed_particle_energy, which had washed to "valid" on the prose grep, correctly re-quarantined on its unit defect once the per-batch deterministic re-audit landed — then resolved at root with the other three unit quarantines. - Decomposition findings drained: the retired audit's ~2,250 false-positive findings were cleared graph-wide (≈1,982 via the free drain, the balance graph-wide), removing a phantom defect class rather than "fixing" names that were never wrong.
- No name drift: across all five rotations
names_composed = 0— the campaign refined documentation on unchanged identifiers and never touched name identity, honouring the guardrail that docs campaigns never rename.
5.5 — Model seats used by the campaign
The seats were settled by a measured role-by-role benchmark before the campaign spent at scale (applied in ce0144e1): documentation generation on gpt-5.6-luna (rubric parity, zero banned prose vs 15%, cheaper), the refine seat held on gpt-5.5 (best resolution, lowest collateral), the review quorum on the resilient blind pair claude-sonnet-5 + grok-4.5, the name-refine escalator switched to gpt-5.6-fable (lowest do-no-harm collateral on the hard tail), and the prose adjudicator on gpt-5.6-luna. The lead accepted ≈ $0.29/name for the premium review pair after a per-model cost review. Benchmark tables: role-benchmark archive and the reviewer-resilience record in sn-model-selection-2026-07.
All three campaign guardrails held: no name was regenerated from scratch, every refined definition cleared the standing review quorum, and the criticised defect classes were fixed in prompts and validators before the bulk pass — so the documentation-axis defect set drained monotonically to zero across the five rotations with zero prose reintroduction and zero name drift. Comment 1 is closed at scale; only the release close-out (§4) remains.