Crosswalk Runbook: Selecting, Sourcing, and Drafting a Concept¶

Status: Accepted, in active use Date: 2026-07-04 (non-distinct-candidate off-ramp added 2026-07-06, corrected same day after its first real application surfaced two gaps; a lesson-learned subsection added to Step 1 the same day, on not pre-ranking unverified candidates by "evidentiary strength"; a governing principle added the same day, above Step 1, stating explicitly that a crosswalk maps the territory rather than judging it — added after this specific lesson had to be repeated more than once in one session; a symmetric check added 2026-07-07 after the governing principle itself was misapplied in the opposite direction — manufacturing an open maintainer-decision question for a fact-and-existing-rule-determined finding — during the Ontological Level / Stratum pass; a "Reviewed-eligibility criterion" section added 2026-07-07, same day, stating explicitly that a single core term (per ADR-0020/ADR-0021's definition) from one authoritative source is sufficient for reviewed — extending ADR-0021's existing existential core-placement logic rather than introducing a new principle, corrected same day from an initial draft that used "primitive/upper-level," a label ADR-0011 already rejected — and the Off-ramp section's trigger condition tightened the same day to require a source's own explicit alternate/equivalence assertion, not an XwkOnt-side read of evidentiary overlap; Step 4 corrected 2026-07-08 — it had said to fill in TEMPLATE.md directly, which by then meant writing into docs/crosswalks/concepts/, a directory ADR-0024 had since made generated-only; a new Step 5 added the same day making the draft-to-YAML-to-generated-Markdown conversion an explicit step rather than an undocumented gap, and subsequent steps renumbered) Related specification: docs/methodology/crosswalk-methodology.md, docs/methodology/primary-source-verification.md, docs/governance/contributing.md, docs/crosswalks/concepts/TEMPLATE.md, _private/codex-delegation-process.md, ADR-0015, ADR-0018, ADR-0024

Purpose¶

This is the step-by-step procedure for taking a concept from "candidate" to a draft crosswalk ready for maintainer review. It doesn't introduce new rules — it sequences the rules that already exist across crosswalk-methodology.md (mapping categories), primary-source-verification.md (fetch/extraction technique), contributing.md (workflow and evidence expectations), and TEMPLATE.md (the artifact shape) into one ordered checklist, because those documents are each correct on their own topic but none of them says "do X, then Y, then Z." This is the process every 0.1.0 and 0.2.0 concept crosswalk actually followed; new concepts (starting with 0.3.0) should follow the same sequence.

Governing principle: a crosswalk maps the territory, it does not judge it¶

This principle sits above every step below and applies to all of them, not just admission (Step 1) or the Off-ramp. Stated directly, per explicit maintainer direction (2026-07-06), after this same lesson had to be repeated more than once in a single session:

A crosswalk's job is to capture the lay of the land — what each source ontology actually says, verified against its own primary artifact, and how the sources relate to or diverge from each other. If two sources' evidence overlaps, say it overlaps. If a comparison is genuinely uncertain or vague, say it is uncertain or vague. Do not resolve that overlap or vagueness into a confident conclusion. That resolution — deciding what the overlap or vagueness means for XwkOnt's own structure (how many documents to use, whether a candidate is distinct, which of two plausible readings is correct) — is an editorial/scope judgment, and per this repository's standing practice, that judgment belongs to the maintainer, not to whoever is drafting or verifying the crosswalk.

Three concrete failures from real sessions prompted this section, worth reading as worked examples of what NOT to do — the first two show overclaiming certainty (stating a judgment as if it were settled), the third shows the opposite and equally real failure, manufacturing false uncertainty (escalating something the evidence and existing project rules had already settled):

Quality Space/Quale was first recorded as "resolved... not a distinct concept" — stating a scope conclusion as if it were a settled fact, when only the underlying source-evidence finding (quality.md already contains this content) was actually settled. Corrected to "recommended, pending maintainer confirmation" and only marked settled after the maintainer explicitly confirmed it. See this file's own Off-ramp section.
Symbol/Sign/Representation's scope-overlap check read information-artifact.md's prose summary and concluded "distinct" — but a second, more mechanical check (comparing the new draft's actual cited evidence against information-artifact.md's own Source Definitions/Correspondences tables) found the two crosswalks share the same primary-source quotation as their respective strongest evidence. That fact is now recorded in both crosswalks' YAML as an explicit, unresolved uncertainty item — not narrowed, not off-ramped, not left ambiguous either. Stated as a fact, on both sides, with the resolution left open.
Ontological Level/Stratum (2026-07-07) first recorded UFO's UFO-A/UFO-B/UFO-C partition as a "second source, pending a maintainer scope decision" — even though independent verification had already fully settled the two facts underneath it (the source text uses zero stratification vocabulary; the partition's substance duplicates content already crosswalked in continuant-occurrent.md/role.md), and this repository's own already-decided batch-admission record (2026-07-06: this candidate was admitted on explicit single-source, GFO-only terms) meant excluding UFO didn't even change the candidate's accepted scope. There was no second legitimate resolution to preserve — the "open question" was manufactured by treating "this touches source inclusion" as automatically maintainer territory, without first checking whether the facts plus an already-decided project rule had already collapsed it to one answer. Corrected to explicit-non-equivalence, uncertainty marked resolved: true, with the settled reasoning recorded as a fact.

What this means in practice, at every step of this runbook:

Mapping categories and confidence levels (crosswalk-methodology.md) are themselves evidence-based classifications, not free interpretive choices — but the categories unknown and explicit-non-equivalence exist precisely so that genuine uncertainty or genuine non-overlap can be stated as such rather than forced into a stronger claim the evidence doesn't support. Reaching for unknown is not a failure to reach a conclusion; recording the actual state of the evidence is the conclusion.
When a scope-overlap check is required (see the Off-ramp section), it must compare the new draft's actual cited evidence against the existing crosswalk's actual tables — not just its Scope Note or summary prose. A topical read is not the same check as an evidentiary one.
When independent verification finds a fact that has more than one legitimate resolution (a candidate might be distinct, or might not; a batch composition question could reasonably go either way), record the fact, cite the evidence, and stop. Do not pick the resolution that seems most reasonable and present it as decided. This is not a failure of judgment — it is the correct scope of what a crosswalk-drafting or verification pass is for.
If you find yourself writing a sentence that reads as a conclusion ("X is/is not a distinct concept," "candidate A is weaker than candidate B," "this exclusion is justified because...") without a cited piece of evidence directly supporting that specific conclusion, stop and ask whether it belongs in an Uncertainty item addressed to the maintainer instead.
The symmetric check, going the other direction (added after worked example 3 above): before recording an Uncertainty item as an open question for the maintainer, verify it actually has more than one legitimate resolution — don't assume it does just because it involves source inclusion, scope, or comparison. Concretely: (a) confirm the underlying evidence is itself ambiguous or genuinely admits more than one reading, not just that a comparison/categorization judgment is involved (every crosswalk involves comparison — that's the descriptive job, not a reason to escalate); (b) check whether an already-decided project rule (a batch's stated admission threshold, an ADR, a prior maintainer confirmation on a related candidate) already determines the outcome once the facts are established — if so, apply that rule and record the result as a settled finding, don't re-open it as a fresh decision; (c) if, after (a) and (b), exactly one answer follows mechanically from verified facts and existing rules, that is not an editorial judgment — write the resolution (non-equivalence/explicit-non-equivalence, resolved: true), not the question. A crosswalk is descriptive: recording an unnecessary open question is itself a failure to describe what the evidence and the project's own already-decided rules actually show, just as much as overclaiming a conclusion the evidence doesn't support is.

Reviewed-eligibility criterion: core in ≥1 source, verified against an authoritative source¶

Stated directly, per explicit maintainer direction (2026-07-07): a candidate concept term earns reviewed status when (1) it is classified as part of any one of the 8 source ontologies' own core/base module (per ADR-0020/ADR-0021's already-established, precisely-defined sense of "core" — not a domain-tier claim, not an informal "feels foundational" read), and (2) that classification is directly verified against an authoritative primary source (the source's own artifact, not a secondary description). Nothing more is required. Cross-source convergence is interesting content when it exists — a crosswalk should say so when it does — but it was never the bar for reviewed, and this section exists so that stops being ambiguous.

Terminology note: this section originally used "primitive/upper-level" for this test. Corrected (2026-07-07, same day, per maintainer feedback): ADR-0011 already explicitly rejected "primitive" as XwkOnt vocabulary ("XwkOnt SHALL NOT introduce a project-specific label... where 'Concept' — already adopted via SKOS... — is sufficient"), and ADR-0020/ADR-0021 already define exactly the needed test under the name "core." Reusing that existing, precisely-defined term rather than inventing new near-synonym vocabulary is itself an instance of "Reuse Before Introduce" — the same governing rule this correction is applying to the runbook's own prose.

This is not a new principle. It is the same existential-quantifier logic ADR-0021 already established for core placement ("a concept qualifies as XwkOnt-core if any one contributing source ontology classifies it as part of that source's own core/base module, no cross-source majority or popularity filter on top"), extended to reviewed eligibility itself — a single, genuinely core term from one authoritative source is real, documentable content regardless of whether any other source has a parallel term, disagrees, or is silent on it. Ontological Level / Stratum (2026-07-07) is the first concrete case: single-source (GFO only), advanced straight to reviewed once all 8 sources were independently verified — no multi-source requirement blocked it, because there never was one.

Operationalize this the same way ADR-0021 already does, rather than inventing a new subjective test: a term qualifies if it is declared in that source's own base/core module (per docs/methodology/source-ontology-module-conventions.md), not a leaf/domain/extension module. "Does this feel foundational" is not the test; "does this source's own module structure place it at that altitude" is. GFO's Stratum/Level pass this mechanically — both are declared directly in gfo-base.owl, GFO's base module, not an extension.

Framing note, per ADR-0019: this criterion is stated at the level of a source term's status, not a claim that "the concept" (XwkOnt's own working-label heading) is itself validated by that status. ADR-0019's Decision section is explicit that mapping assertions run source-term-to-source-term and "XwkOnt's Concept is the human-readable heading a cluster of those correspondences is filed under, not a third node they pass through." A single core, verified term filed under a heading is exactly as sound a basis for reviewed as five terms would be — the heading was never carrying evidentiary weight on its own.

This does not relax verification. Step 3 through Step 6 below still apply in full — every claim still needs direct primary-source verification, every absence still needs to be checked across all 8 sources, and the Off-ramp below still applies where relevant. What this section settles is narrower: ADR-0018's per-batch source-count thresholds (0.2.0's ≥3 sources, 0.3.0's 2-then-1-source rungs) are a batch-sequencing device — which candidates get worked on, and in what order, within a given release — not a quality gate on what "reviewed" means. A candidate meeting a batch's admission threshold and a candidate's eventual source count once actually verified are two different numbers, and only the second one (verified content) has ever mattered for whether a finished crosswalk is sound.

Step 1 — Confirm the concept is admissible¶

Check TODO.md's queue and docs/evaluations/foundational-ontology-concept-terms-matrix.md for the candidate's source-count evidence.
Per ADR-0018, a candidate's matrix source-count ranking is the primary admission evidence for a batch; the original seven-point selection checklist (source accessibility, session-sized scope, likelihood of revealing real semantic differences, citability, template fit) is secondary, per-concept scoping guidance — it decides when a matrix-justified candidate is ready to work, not whether it belongs in the candidate space.
Record the batch's admission threshold (e.g. 0.2.0 used ≥3 sources) and confirm the candidate meets it before starting research — but treat the seed's source list and count as a hypothesis to verify, not a settled fact (every 0.2.0 concept's seed count changed at least slightly after direct verification; see Step 3).
Verification can also show the candidate isn't distinct at all, rather than just changing its source count — see "Off-ramp" below, which applies once Step 3's research is underway, not as a substitute for starting it.

Do not rank candidates by "evidentiary strength" before any of them have been verified¶

Lesson learned (2026-07-06): when expanding the 0.3.0 batch from four two-source candidates to include six 1-source ones, two (Non-physical/Social Object, List/Sequence) were excluded as "weakest/least-verified" based on a subjective read of TODO.md's existing hedge-language ("not yet checked elsewhere," "genuinely untested"). On direct comparison, that classification did not survive scrutiny: two of the four candidates that were kept (Change, Modality) carry essentially identical hedge-language ("not yet checked whether any other source draws this same distinction," "untested elsewhere"), and a third kept candidate (Ontological Level/Stratum) is explicitly flagged "weak" in TODO.md's own pre-existing text — a stronger admission of uncertainty than either excluded candidate had. The exclusion was reversed once this was pointed out.

The mistake was not "using judgment" — pre-verification candidates necessarily carry uncertainty, and that's expected. The mistake was treating an unsystematic impression of hedge-language as if it were a considered comparison, arriving at a two-tier split that didn't actually track any consistent criterion across all six candidates it was supposedly applied to. This is a source-strength judgment call, of exactly the kind that Step 1's own admission-threshold logic already governs: at this stage, no candidate at or above the batch's stated threshold (source count, matrix ranking) has actually been through Step 3's verification yet, so nothing is known about their relative strength beyond the threshold itself — only Step 3's actual fetch-and-verify work can surface that.

Rule going forward: do not exclude a candidate from a batch on a "this one seems weaker" basis unless every candidate at the same nominal tier (e.g. all six 1-source candidates, not just some of them) is compared against the same explicit, stated criteria, with the comparison shown, not asserted. Default to admitting every candidate that meets the batch's stated threshold. If a real resource constraint later requires cutting the batch down, that's a distinct, explicit decision (capacity, not quality) and should be presented to the maintainer as exactly that, not disguised as an evidentiary judgment made before the evidence-gathering step has even run. Genuine evidentiary differences between candidates are a legitimate output of Step 3's verification pass for each concept — that's where "which of these is actually thinner" gets answered, and that answer should inform future batch prioritization, not gate entry into the current one.

Step 2 — Create or confirm the session branch¶

Following the project's session-based workflow: check out a dedicated working branch from current main before drafting. All of this concept's commits happen on that branch.

Step 3 — Fetch and verify all 8 sources directly¶

Per ADR-0015, every crosswalk checks all 8 source ontologies (BFO, DOLCE, SUMO, UFO, GFO, YAMATO, TUpper, GUM) — not just the sources the seed named. This is where most of the actual work happens:

Reuse cached artifacts first. By the time a batch is a few concepts in, most sources' primary files (bfo-core.ttl, DOLCE-Lite.owl, Merge.kif, the UFO 2021 paper's extracted text, modules/gfo-base.owl, the YAMATO 2010 report, TUpper-Terms.html, GUM-31.owl) are already fetched from prior concepts in the same batch — re-grep those rather than re-fetching.
For sources not yet fetched, use the PDF-extraction technique in primary-source-verification.md for paper/report sources (regex stream...endstream, zlib-decompress, extract Tj/TJ text-showing operators) — OWL/RDF files don't need this, fetch and read them directly.
Full-text search each source for the concept, don't assume the seed's claimed term is right — grep case-insensitively for the working label and plausible synonyms. Confirmed absences are recorded as findings (non-equivalence claim type), not silently skipped.
Use each source's own identifier convention (opaque BFO_XXXXXXX/IAO_XXXXXXX IDs, DOLCE-Lite's kebab-case names, SUMO's term-name-as-identifier, UFO's "no IRI scheme" for the 2021 paper vs. OntoUML's real IRIs, GFO's w3id.org/gfo/... IRIs, YAMATO's identifier-free prose, TUpper's PSL/COLORE term names, GUM's PascalCase) — see primary-source-verification.md's table. Don't invent a placeholder scheme.
Watch for citation-precision traps: name collisions across sources (e.g. UFO's category vs. GFO's Category denoting different things), secondary-source misattributions, and a source's own prose discussing a concept informally without reifying it as a class (check whether the real formal treatment lives in a separate, not-yet-adopted module, e.g. DOLCE's DnS) before claiming an absence.

Off-ramp — when verification shows the candidate isn't distinct¶

Step 3's verification sometimes shows the candidate doesn't merit its own crosswalk at all: the source terms named in the seed turn out to be already fully covered by an existing reviewed concept's own Source Definitions, Comparison Notes, and Mapping Assertions, rather than describing a genuinely separate category. Quality Space / Quale (evaluated 2026-07-06, 0.3.0 batch) is the first worked example: its seed terms (DOLCE quale/quality-space, GFO Property_value/Value_space) were already directly quoted and mapped inside quality.md, and its remaining candidate-concepts.md rows (DOLCE temporal-location_q/spatial-location_q, YAMATO quality value/categorical) turned out on direct verification to be genuine subtypes/subdivisions of already-covered material, not a distinct "quality space" category.

Trigger condition, tightened (2026-07-07, per explicit maintainer direction): the only off-ramp is a source ontology's own explicit alternate/equivalence assertion. Concretely: an owl:equivalentClass declaration, an explicit "AKA"/synonym statement in the source's own documentation, or an equally direct source-side marker that one term is another term by a different name. Quality Space / Quale satisfies this narrower rule too — DOLCE's own DOLCE-Lite.owl directly declares quale and quality-space owl:equivalentClass to region-branch constructs already covered in quality.md, a source-side fact, not an XwkOnt-side read of similarity. What does NOT qualify for this off-ramp: XwkOnt itself noticing that two crosswalks' cited evidence overlaps, or judging that a candidate's content "seems already covered," without a source-side equivalence marker backing that specific claim. Symbol / Sign / Representation's finding that it shares its strongest primary-source quotation with information-artifact.md is the worked example of the correct alternative: real evidentiary overlap, but no source-side synonym declaration behind it, so it was recorded as an unresolved uncertainty on both crosswalks — not off-ramped. This reuses the same "map, don't judge" logic above: a crosswalk can and should report that two sources' content overlaps; deciding that overlap means "collapse to one document" is an editorial call, and per this rule that call requires the source itself to have already made it, not XwkOnt inferring it from a comparison.

Correction (2026-07-06, same day): this section's first version got two things wrong when actually applied to Quality Space / Quale, both fixed below and folded into the required steps so they don't recur:

It called the outcome "resolved," implying the scoping question ("does this need its own document?") had been decided. Only the underlying source-evidence finding ("quality.md already contains this content") is a settled fact; whether that finding means "no separate crosswalk" is an editorial judgment about how XwkOnt organizes its own artifacts, and this repo's own precedent (situation-state-of-affairs.md's scope-instability question, left open for maintainer review rather than self-decided) says that judgment belongs to the maintainer, not to whoever ran the verification pass — even when that verification was thorough and independently re-checked. Every disposition recorded this way is a recommendation pending maintainer confirmation, not a closure, until the maintainer actually says so.
Retagging candidate-concepts.md's rows away from the original bucket name lost the literal search term ("Quality Space / Quale" no longer appeared anywhere in the file) — exactly backwards for a public contribution backlog whose whole purpose is being searched. The fix is Step 3 below: the original term must survive in the retagged text itself, and the covering concept's own YAML must gain a real, structured pointer back to it (an actual Alternate Label row, not just prose), not only a note in a secondary tracking file.

Do not force a redundant crosswalk document into existence just because a batch slot was assigned to a candidate. Per "Reuse Before Introduce," concluding "not a distinct concept" is itself a legitimate, useful outcome — the honest alternative to inventing a document whose content just restates what already exists elsewhere. When this happens:

Do not create docs/crosswalks/concepts/<slug>.md or a YAML SSOT. There is nothing to encode that isn't already encoded under the covering concept's own identifier.
Record the disposition in TODO.md's batch item as a recommendation, not a closure — leave the checkbox unchecked ([ ], not [x]) and say explicitly "recommended NOT a distinct concept, pending maintainer confirmation," stating which existing concept covers it and why, so the reasoning is auditable later and the maintainer has something concrete to confirm or reject.
Retag every docs/crosswalks/candidate-concepts.md row that fed the now-closed candidate bucket, pointing it at the concept that actually covers it, using the form <Concept> (was tagged "<original bucket name>"; recommended YYYY-MM-DD, pending maintainer confirmation: <one-line reason>) — the original bucket name must appear verbatim in the retagged text so a literal search for it still finds this row. This file is the public contribution backlog — a row that drops the searched-for term, or that reads as a closed decision, would either send a contributor to a dead end silently or invite them to redo the same investigation.
Add a real Alternate Label to the covering concept's own YAML (LabelEntry with role: Alternate label, label_source: XwkOnt), naming the resolved-away candidate, plus a Future Work note cross-referencing the evaluation and marking it pending confirmation. This is what makes the covering concept's own canonical file directly searchable by the old candidate name, not just the backlog file — don't rely on prose alone when the schema already has a structured field for exactly this (docs/crosswalks/concepts/TEMPLATE.md's "Alternate label" role).
Update any release/batch tracking (wherever running totals and batch queues are maintained) so running-total arithmetic doesn't keep counting a still-pending candidate as if it might still ship as its own concept, but without asserting the disposition as final there either.
State a concrete revisit condition, not a vague one, wherever the disposition is recorded. "Revisit later" is not actionable; "revisit if a source is found that reifies the value-space/quality-space layer as an entity independent of a specific quality" is. Source ontologies gain new modules, this repo's own source list can grow (ADR-0015 already extended it from 4 to 8 sources once), and a candidate recommended as non-distinct today is not settled forever even after maintainer confirmation — record what evidence would change the determination, the same way uncertainty items elsewhere record impact and follow-up rather than a bare open flag.

This disposition is a distinct third state from two others already in use, and the terminology should not be conflated:

Ungrouped (docs/crosswalks/candidate-concepts.md's own term) — not yet triaged into any bucket at all. No investigation has happened.
"likely NOT core" (TODO.md's existing flag, e.g. for GUM's fine-grained linguistic leaf classes) — a real, distinct class, judged too fine-grained or source-specific to warrant its own XwkOnt concept, independent of whether it overlaps another concept's content.
Recommended non-distinct, pending maintainer confirmation (this section) — the candidate WAS investigated at crosswalk-attempt depth (Step 3's actual fetch-and-verify work), the finding is that its content is already inside an existing concept, and that finding has been handed to the maintainer as a recommendation, not silently enacted.

Step 4 — Fill in the template, section by section¶

Author into _private/<slug>-draft.md, shaped like docs/crosswalks/concepts/TEMPLATE.md — never directly into docs/crosswalks/concepts/<slug>.md. Since ADR-0024, that directory is a generated-only projection of each concept's YAML record (see docs/crosswalks/concepts/README.md); a hand-authored file placed there risks being mistaken for canonical content or silently overwritten by the next regeneration. TEMPLATE.md still supplies the section shape — it is a shape reference, not itself the file to edit. See _private/codex-delegation-process.md for the fuller rationale (written for the Codex-delegation case, but the generated-directory rule applies to any contributor). Populate in this order (later sections depend on earlier ones):

Scope Note — selection rationale with real source-count evidence (not backfilled from the seed), what the concept covers and excludes, cross-cutting findings established this session, and whether core.ttl placement is an open question (it almost always is at draft stage — a class is only added to data/ontology/core.ttl once the crosswalk reaches reviewed).
Labels, Alternate Labels, and Source Terminology — one row per source, including explicit "no class found" rows for confirmed absences.
Source Definitions and Contextual Notes — the actual quotes/paraphrases, one row per source term, each with claim type (direct quotation/paraphrase/editorial observation/inference), reference, and locator recording exactly how it was verified (**verified**: <file>, fetched and read directly <date>).
Source Ontology Correspondences — one row per source with a real correspondence, IRI or "not applicable" per that source's own convention, and an inclusion rationale.
Semantic Comparison Notes — the cross-cutting philosophical/technical findings, each with a confidence level and supporting references.
Mapping Assertions — per crosswalk-methodology.md's categories (exact-equivalence-candidate, close-match, broader-than, narrower-than, related, overlap, incompatible, unknown, explicit-non-equivalence). Reserve close-match for pairs that are the same formal kind differing only in scope/axioms/usage; use overlap when the divergence is structural (different formal kind, e.g. a region vs. a quantity, or an abstract vs. a physical classification) — this distinction has been under-applied at least twice (see the 2026-07-04 review-response fixes to time.md/space.md), so check it explicitly rather than defaulting to close-match for anything that seems similar.
Uncertainty, Non-Equivalence, and Open Questions — every open question, including ones with a recommended resolution — record the recommendation and rationale, but leave the actual decision for maintainer review if it affects core.ttl structure. Don't convert unresolved uncertainty into an equivalence claim for convenience.
Provenance and References — one line per source, stating verification status (verified, verified absence, verified absence, scoped, etc.) and date.
Review History — leave as *(unreviewed)* with a summary of what this drafting pass found, corrected, or left open.
Future Work — concrete, actionable follow-ups (which uncertainty items to resolve, what to fetch next, what the next concept in the batch should be).

Step 5 — Convert the draft to the YAML SSOT and generate the real Markdown¶

The _private/<slug>-draft.md from Step 4 is not itself a deliverable — it is superseded once this step is done, and can be left in place afterward as a historical record (same spirit as the Codex evaluation notes), not deleted.

Run python3 scripts/crosswalk-draft-md-to-yaml.py <slug> to mechanically transcribe the draft into data/crosswalks/<slug>/<slug>.yaml. This is a deterministic field transcription, not a verification step.
Independently re-verify every citation against its primary source and hand-edit the YAML directly — the YAML, not the draft Markdown, is the record that gets trusted from here on (ADR-0024).
Validate: linkml-validate -s data/crosswalks/schema/crosswalk-concept.yaml data/crosswalks/<slug>/<slug>.yaml.
Generate the real Markdown: python3 scripts/crosswalk-yaml-to-md.py --write <slug>, and the machine-readable exports: python3 scripts/crosswalk-to-sssom-tsv.py and python3 scripts/sssom-tsv-to-ttl.py.

Step 6 — Self-check before committing¶

Re-read docs/INFORMATION_ARCHITECTURE.md's slug/filename rules, local identifier patterns (xwkont:concept:<slug>, xwkont:mapping:..., xwkont:ref:...), and claim-typing rules if this is a new contributor's first crosswalk in a session — don't assume they're memorized.
Run docs/governance/contributing.md's Review Checklist and the validation commands relevant to the artifact class (crosswalk = the YAML SSOT plus its generated Markdown/TSV/Turtle; no core.ttl touch expected at draft).
Confirm every reference used has a docs/references/ref-*.md record (or reuses an existing one) per ADR-0012.
git status --short clean check before calling the concept done.

Commit the YAML, the generated Markdown/TSV/Turtle, and the superseded _private/<slug>-draft.md together, with a feat: (new concept) or fix:/docs: (correction) Conventional Commits message.
Update TODO.md's batch item with a per-concept findings summary, and docs/crosswalks/README.md's index if this is a new file.

Step 8 — Batch-level review¶

Once every concept in the batch is drafted, an external or maintainer review pass checks the batch as a whole — cross-crosswalk consistency (does one crosswalk's finding correct another's, and has that correction actually been applied?), mapping-category strictness, and whether any concept's evidentiary base is too thin to advance with the rest of the batch (HOLD) versus ready with targeted fixes (PASS WITH FIXES) versus ready as-is (PASS). Apply mechanical fixes directly; record scope/structure decisions (e.g. "model as one class or two") as maintainer-confirmable recommendations in the crosswalk's own Uncertainty section rather than silently deciding core.ttl structure. A concept that gets a genuine HOLD should stay at draft, not be pushed to reviewed by lowering the evidentiary bar — see docs/crosswalks/concepts/situation-state-of-affairs.md's uncertainty-001 for a worked example of a concept that failed its own admission bar on direct verification and was left open rather than forced through.

What this runbook does not cover¶

The mapping-category definitions and confidence vocabulary themselves — see crosswalk-methodology.md.
The PDF-extraction technique's implementation details — see primary-source-verification.md.
The final sign-off act itself, once the "Reviewed-eligibility criterion" section above's bar is met — recording the review pass and advancing editorial_status is a maintainer-confirmable step per docs/governance/contributing.md and docs/governance/release-versioning-policy.md, even though the substantive criterion for whether a candidate qualifies is now specified above.