@afokapu/atdd-bun 0.1.0

package/planner-nodes/nodes/planner.train.interlocking-payload-contract-registered.convention.yaml

@@ -0,0 +1,31 @@
+schema_version: 1.0.0
+rule_id: planner.train.interlocking-payload-contract-registered
+kind: rule
+status: active
+name: Interlocking payload contract registered
+statement: A payload contract identity referenced by an interlocking message must
+  resolve to an authored/registered contract in the contracts registry, not merely
+  a file that glob-matches.
+terms:
+- term_id: registered_contract
+  text: a payload contract identity must be a member of the authored contracts
+    registry (contracts/_contracts.yaml), the single source of truth for
+    identity -> path -> theme -> producers -> consumers (#1330 / #1332)
+implementation:
+  type: validator
+  ref: test_sequence_diagram_sanity::test_payload_contracts_are_registered
+metadata:
+  severity: 3
+  disposition: strict
+validation:
+  family: resolution
+  template: artifact_reference_resolution
+  variant: planner_train_interlocking_payload_contract_registered
+  phase: CONFIRM
+  enforcement: confirm-blocking
+  subject_kind: interlocking
+  failure_evidence:
+  - interlocking_id
+  - message_id
+  - contract
+  - registry_path

package/planner-nodes/nodes/planner.train.interlocking-projection-equivalence.convention.yaml

@@ -0,0 +1,32 @@
+schema_version: 1.0.0
+rule_id: planner.train.interlocking-projection-equivalence
+kind: constraint
+status: active
+name: Interlocking projection equivalence
+statement: A referenced train sequence must equal the interlocking route projection
+  by step, intent, from, to, and artifact.
+terms:
+- term_id: projection_equivalence
+  text: the referenced train sequence equals the route projection by step, intent,
+    from, to, and artifact
+implementation:
+  type: validator
+  ref: test_sequence_diagram_sanity::test_train_sequence_matches_interlocking_projection
+metadata:
+  severity: 4
+  disposition: strict
+validation:
+  family: coherence
+  template: resolved_fact_agreement
+  variant: planner_train_interlocking_projection_equivalence
+  phase: CONFIRM
+  enforcement: confirm-blocking
+  subject_kind: interlocking
+  failure_evidence:
+  - interlocking_id
+  - route_id
+  - train_id
+  - step
+  - field
+  - expected
+  - actual

package/planner-nodes/nodes/planner.train.interlocking-route-category-matches-train-id.convention.yaml

@@ -0,0 +1,32 @@
+schema_version: 1.0.0
+rule_id: planner.train.interlocking-route-category-matches-train-id
+kind: constraint
+status: active
+name: Interlocking route category matches train id
+statement: Every interlocking route declares nominal/error/alternate/exception and
+  that category must equal the `category` field of the target train it selects
+  (issue #1421 — category is a validated field, not an identity digit).
+terms:
+- term_id: category_field_agreement
+  text: route.category must equal the target train's `category` field (nominal/error/alternate/exception);
+    the legacy identity digit is retired and no longer parsed
+implementation:
+  type: validator
+  ref: test_sequence_diagram_sanity::test_interlocking_route_category_matches_train_id
+metadata:
+  severity: 4
+  disposition: strict
+validation:
+  family: coherence
+  template: resolved_fact_agreement
+  variant: planner_train_interlocking_route_category_matches_train_id
+  phase: CONFIRM
+  enforcement: confirm-blocking
+  subject_kind: interlocking
+  failure_evidence:
+  - interlocking_id
+  - route_id
+  - category
+  - train_id
+  - train_category
+  - train_path

package/planner-nodes/nodes/planner.train.interlocking-route-resolution-deterministic.convention.yaml

@@ -0,0 +1,30 @@
+schema_version: 1.0.0
+rule_id: planner.train.interlocking-route-resolution-deterministic
+kind: constraint
+status: active
+name: Interlocking route resolution deterministic
+statement: Route resolution strategy is explicit and deterministic; ambiguous matching
+  routes fail closed unless unique priority is declared.
+terms:
+- term_id: route_resolution
+  text: allowed strategies are fail_on_multiple_match, or first_priority with unique
+    integer priorities
+implementation:
+  type: validator
+  ref: test_sequence_diagram_sanity::test_interlocking_route_resolution_strategy_declared
+metadata:
+  severity: 4
+  disposition: strict
+validation:
+  family: coherence
+  template: resolved_fact_agreement
+  variant: planner_train_interlocking_route_resolution_deterministic
+  phase: CONFIRM
+  enforcement: confirm-blocking
+  subject_kind: interlocking
+  failure_evidence:
+  - interlocking_id
+  - strategy
+  - route_ids
+  - priorities
+  - reason

package/planner-nodes/nodes/planner.train.interlocking-structural-residual-explicit.convention.yaml

@@ -0,0 +1,30 @@
+schema_version: 1.0.0
+rule_id: planner.train.interlocking-structural-residual-explicit
+kind: rule
+status: active
+name: Interlocking structural residual explicit
+statement: Structural residuals must be explicit, narrow, and bound to an acceptance
+  and validator.
+terms:
+- term_id: residual_explicit
+  text: structural residuals are explicit and narrow and bound to an acceptance and
+    a validator
+implementation:
+  type: validator
+  ref: test_sequence_diagram_sanity::test_structural_residuals_have_acceptance_and_validator
+metadata:
+  severity: 3
+  disposition: strict
+validation:
+  family: presence
+  template: conditional_requirement
+  variant: planner_train_interlocking_structural_residual_explicit
+  phase: CONFIRM
+  enforcement: confirm-blocking
+  subject_kind: interlocking
+  failure_evidence:
+  - interlocking_id
+  - residual_id
+  - acceptance_ref
+  - validator_ref
+  - reason

package/planner-nodes/nodes/planner.train.interlocking-wmbt-surface-or-residual.convention.yaml

@@ -0,0 +1,30 @@
+schema_version: 1.0.0
+rule_id: planner.train.interlocking-wmbt-surface-or-residual
+kind: constraint
+status: active
+name: Interlocking WMBT surface or residual
+statement: Every WMBT obligation surfaces as message, self-message, guard, fragment,
+  invariant, or explicit structural residual.
+terms:
+- term_id: wmbt_surface
+  text: every WMBT obligation surfaces as a message/self-message/guard/fragment/invariant
+    or an explicit structural residual
+implementation:
+  type: validator
+  ref: test_sequence_diagram_sanity::test_every_wmbt_surfaces_or_is_structural_residual
+metadata:
+  severity: 4
+  disposition: strict
+validation:
+  family: coverage
+  template: projection_covers_source
+  variant: planner_train_interlocking_wmbt_surface_or_residual
+  phase: CONFIRM
+  enforcement: confirm-blocking
+  subject_kind: interlocking
+  failure_evidence:
+  - interlocking_id
+  - wmbt_ref
+  - surface_kind
+  - residual_id
+  - coverage_status

package/planner-nodes/nodes/planner.train.linearity.convention.yaml

@@ -0,0 +1,28 @@
+schema_version: 1.1.0
+rule_id: planner.train.linearity
+kind: constraint
+status: active
+name: Trains are strictly linear
+statement: 'Trains are strictly linear: sequences contain steps only — no loops, routes, or branching;
+  new paths MUST become new trains.'
+source:
+  legacy_path: src/atdd/planner/conventions/train.convention.yaml
+  legacy_section: urn_naming.linearity_rule
+  legacy_sha: 825602729f11a3a4
+  extraction_mode: high_fidelity
+content:
+  normative_text: 'Enforcement: loop and route sequence elements are forbidden; sequential step numbering
+    must have no gaps; each step has exactly one from and one to.'
+  constraints:
+  - loop and route sequence elements are forbidden
+  - Sequential step numbering must have no gaps
+  - Each step has exactly one from and one to
+parity:
+  source_fragments_preserved: true
+  examples_preserved: false
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: linearity
+  text: the no-loops/no-routes/no-branching rule for train sequences.

package/planner-nodes/nodes/planner.train.naming.convention.yaml

@@ -0,0 +1,26 @@
+schema_version: 1.1.0
+rule_id: planner.train.naming
+kind: rule
+status: active
+name: Train naming
+statement: train_id is the typed identity train:{subject}:{descriptive-name}, with
+  kebab-case subject and descriptive name; title is Title Case; files are flat at
+  plan/_trains/{train_id}.yaml.
+source:
+  legacy_path: src/atdd/planner/conventions/train.convention.yaml
+  legacy_section: naming
+  legacy_sha: 825602729f11a3a4
+  extraction_mode: high_fidelity
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: train_naming
+  text: train_id, title, and file naming.
+  values:
+    train_id: 'train:{subject}:{descriptive-name}, kebab-case'
+    title: Title Case
+    file: plan/_trains/{train_id}.yaml (flat)

package/planner-nodes/nodes/planner.train.participants.convention.yaml

@@ -0,0 +1,27 @@
+schema_version: 1.1.0
+rule_id: planner.train.participants
+kind: family
+status: active
+name: Train participants
+statement: 'Participants are the actors in a train workflow: wagon:{id}, user:{role}, or system:{source};
+  each listed once.'
+source:
+  legacy_path: src/atdd/planner/conventions/train.convention.yaml
+  legacy_section: participants
+  legacy_sha: 825602729f11a3a4
+  extraction_mode: high_fidelity
+parity:
+  source_fragments_preserved: true
+  examples_preserved: false
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: participant_type
+  label: Participant types
+  text: type -> pattern.
+  values:
+    wagon: wagon:{wagon-id} (performs processing)
+    user: user:{role} (human actor)
+    system: system:{source} (external system/data source)
+    validation: ^(wagon|user|system):[a-z][a-z0-9-]*$

package/planner-nodes/nodes/planner.train.production-implementation.convention.yaml

@@ -0,0 +1,24 @@
+schema_version: 1.1.0
+rule_id: planner.train.production-implementation
+kind: principle
+status: active
+name: Trains are production orchestration
+statement: Trains are production orchestration (not test infrastructure), executed by TrainRunner under
+  python/trains/.
+source:
+  legacy_path: src/atdd/planner/conventions/train.convention.yaml
+  legacy_section: production_implementation
+  legacy_sha: 825602729f11a3a4
+  extraction_mode: high_fidelity
+content:
+  operational_guidance: location python/trains/; executor TrainRunner (python/trains/runner.py); implementation
+    patterns in atdd/coder/conventions/train.convention.yaml (SESSION-12).
+parity:
+  source_fragments_preserved: true
+  examples_preserved: false
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: train_runner
+  text: the production executor of a train.

package/planner-nodes/nodes/planner.train.registry-coherence.convention.yaml

@@ -0,0 +1,69 @@
+schema_version: 1.0.0
+rule_id: planner.train.registry-coherence
+kind: rule
+status: active
+name: The train registry and the documents it indexes both exist
+statement: Every row in plan/_trains.yaml must name a path that is a file on disk, and
+  every per-train document under plan/_trains must be named by a registry row. Coherence
+  is bidirectional - a row naming an absent document is a dangling pointer consumers
+  resolve through, and a document no row names is an orphan.
+terms:
+- term_id: dangling_row
+  text: a plan/_trains.yaml entry whose path does not resolve to a file. The residue create_train
+    left when it wrote the registry before the document (#1942); every consumer that walks
+    the registry resolves through it, and test_route_space_admission dies on it with a bare
+    FileNotFoundError rather than reporting it.
+- term_id: orphan_document
+  text: a per-train document under plan/_trains that no registry row names. Inert - nothing
+    resolves through it - and it is the residue create_train's document-before-registry
+    ordering deliberately leaves, so it must be reportable or that choice is unsupported.
+- term_id: registry_sidecar
+  text: an underscore-prefixed name under plan/_trains - _aliases.yaml, the _interlockings
+    subtree - which is not a per-train document. The _interlockings subtree has its own
+    coherence rules (planner.interlocking.registry-mirrors-document,
+    planner.train.interlocking-home).
+implementation:
+  type: validator
+  ref: test_train_registry_coherence::test_every_registry_row_resolves_and_every_document_is_registered
+metadata:
+  severity: 3
+  # strict from the start: measured at authoring time, the corpus carries 21 registry
+  # rows and 21 per-train documents with zero violations in either direction, so there
+  # is no debt to ratchet down and no reason to land this advisory.
+  disposition: strict
+  introduced_in: '1942'
+  core_design_refs:
+  - afokapu/atdd#1942
+  - afokapu/atdd#1915
+validation:
+  family: coherence
+  template: cross_artifact_existence_agreement
+  variant: planner_train_registry_existence
+  phase: CONFIRM
+  enforcement: confirm-blocking
+  subject_kind: train
+  failure_evidence:
+  - train_id
+  - direction
+  - registry_value
+  - document_value
+notes: |
+  Why this is a NEW node rather than a validator hung on planner.train.registry.
+
+  planner.train.registry already claims, at disposition: strict, that "every registry
+  entry MUST have a corresponding spec file" - the dangling direction of this rule. It
+  has never been able to enforce it: its implementation.ref names the Y003 sweep's
+  convention variant conventions/resolution/test_train_validation, which instantiates
+  direct_reference_resolution and checks that a train's participant references resolve
+  to existing wagons. It never reads a path. The reverse-coherence binder
+  (coach/validators/test_rule_validator_binding.py) exempts convention-variant refs from
+  the bind_rule callsite requirement, so the gap drew no complaint.
+
+  Repointing that node here was the first attempt and is wrong: the Y003 guard
+  (validators/conventions/tests/test_y003_sweep_coverage_guards.py, SWEPT_RULE_TO_VARIANT)
+  deliberately pins planner.train.registry to a conventions/ variant, so the ref is an
+  architectural decision owned by the sweep, not an oversight to undo from here.
+
+  So the claim is enforced under its own id, and closing the gap on
+  planner.train.registry - by giving its swept variant a real path-existence check, or by
+  folding that node into this one - stays with the conventions-sweep owners.

package/planner-nodes/nodes/planner.train.registry.convention.yaml

@@ -0,0 +1,39 @@
+schema_version: 1.1.0
+rule_id: planner.train.registry
+kind: rule
+status: active
+name: Train registry (two-file pattern)
+statement: 'Each train needs two files: a registry entry in plan/_trains.yaml and a full spec at plan/_trains/{train_id}.yaml;
+  every registry entry MUST have a corresponding spec file.'
+implementation:
+  type: validator
+  ref: conventions/resolution/test_train_validation::test_fault_injection_and_legacy_parity
+source:
+  legacy_path: src/atdd/planner/conventions/train.convention.yaml
+  legacy_section: registry
+  legacy_sha: 825602729f11a3a4
+  extraction_mode: high_fidelity
+content:
+  normative_text: Registry is theme-category-grouped (nominal/error/alternate/exception). Validator SPEC-TRAIN-VAL-0003;
+    planner phase gate fails if a spec file is missing.
+  examples:
+  - 'registry: plan/_trains.yaml (train_id, description, path, wagons summary)'
+  - 'spec: plan/_trains/{train_id}.yaml (full workflow)'
+metadata:
+  severity: 3
+  # strict: the planner phase gate fails when a registry entry has no spec file
+  # (content.normative_text / SPEC-TRAIN-VAL-0003). Backfilled to complete this
+  # single-node authoring so the disposition gate manages it (#1225).
+  disposition: strict
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: true
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: two_file_pattern
+  text: registry entry + spec file per train.
+  values:
+    registry: plan/_trains.yaml
+    spec: plan/_trains/{train_id}.yaml

package/planner-nodes/nodes/planner.train.route-category-assessment.convention.yaml

@@ -0,0 +1,43 @@
+schema_version: 1.0.0
+rule_id: planner.train.route-category-assessment
+kind: constraint
+status: active
+name: Route category assessment
+statement: 'Every interlocking must assess each route category: nominal requires one
+  or more routes, and alternate/error/exception each require routes or a typed not-applicable
+  basis from a closed vocabulary (issue #1554).'
+rationale: A check satisfied by 'at least one non-nominal route' is gamed by adding
+  a token alternate while error and exception behaviour go unwritten. Assessing every
+  category individually forces the author to state what happens on each, and a typed
+  not-applicable keeps the escape from eroding into copy-pasted prose.
+terms:
+- term_id: category_space
+  text: the closed set nominal, alternate, error, exception; no category may be silently
+    omitted
+- term_id: nominal_requires_routes
+  text: nominal is the executed path and can never be typed not-applicable
+- term_id: typed_not_applicable
+  text: alternate, error and exception may be discharged by a basis drawn from a closed
+    vocabulary, never by free prose
+- term_id: no_contradiction
+  text: declaring a not-applicable basis for a category that already carries routes
+    is a contradiction, so stale assessments cannot survive
+implementation:
+  type: validator
+  ref: test_route_space_admission::test_every_category_is_assessed_or_typed_not_applicable
+metadata:
+  severity: 4
+  disposition: strict
+validation:
+  family: presence
+  template: conditional_requirement
+  variant: planner_train_route_category_assessment
+  phase: CONFIRM
+  enforcement: confirm-blocking
+  subject_kind: interlocking
+  failure_evidence:
+  - interlocking_id
+  - category
+  - route_ids
+  - not_applicable_basis
+  - assessment_status

package/planner-nodes/nodes/planner.train.route-space-admission.convention.yaml

@@ -0,0 +1,41 @@
+schema_version: 1.0.0
+rule_id: planner.train.route-space-admission
+kind: constraint
+status: active
+name: Route-space admission
+statement: 'Every registered train must be targeted by exactly one registered interlocking
+  route, or declare a typed single-route assessment; absence of a route no longer
+  implies direct dispatch (issue #1554).'
+rationale: Route-space was modelled as optional metadata, so a train with no route
+  analysis was indistinguishable from a train whose analysis concluded single-route.
+  Silence read as a positive assertion that analysis happened; this rule makes the
+  classification explicit and forces the omission to surface at planning time.
+terms:
+- term_id: route_targeted
+  text: the train is selected by exactly one route across every registered interlocking
+- term_id: typed_single_route
+  text: the train declares route_space.classification single-route with a basis drawn
+    from a closed vocabulary; free prose is never a basis
+- term_id: exactly_one
+  text: route-targeted and typed-single-route are mutually exclusive; declaring both
+    is a contradiction, declaring neither is an omission
+implementation:
+  type: validator
+  ref: test_route_space_admission::test_every_train_is_route_targeted_or_typed_single_route
+metadata:
+  severity: 4
+  disposition: strict
+validation:
+  family: coverage
+  template: source_has_required_target
+  variant: planner_train_route_space_admission
+  phase: CONFIRM
+  enforcement: confirm-blocking
+  subject_kind: train
+  failure_evidence:
+  - train_id
+  - train_path
+  - route_ids
+  - classification
+  - basis
+  - admission_status

package/planner-nodes/nodes/planner.train.scope.convention.yaml

@@ -0,0 +1,38 @@
+schema_version: 1.1.0
+rule_id: planner.train.scope
+kind: rule
+status: active
+name: Train scope and sizing
+statement: 'A train tells ONE coherent journey: 3-7 wagons (sweet spot), 2 minimum, 8-12 review, 13+ decompose;
+  if you can''t state the outcome in one sentence without ''and'', split it.'
+source:
+  legacy_path: src/atdd/planner/conventions/train.convention.yaml
+  legacy_section: scope
+  legacy_sha: 825602729f11a3a4
+  extraction_mode: high_fidelity
+content:
+  normative_text: 'one_journey_test: can you state the outcome in ONE sentence without ''and''?'
+  constraints:
+  - recommended 3-7 wagons
+  - minimum 2
+  - warning 8-12 (multiple journeys?)
+  - antipattern 13+ (decompose)
+  examples:
+  - 'good: train:decision:standard (5 wagons, one outcome)'
+  - 'bad: train:match:solo-match-complete (16 wagons, multiple journeys)'
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: decomposition_signal
+  text: signals a train is multiple journeys.
+  values:
+    signals:
+    - Outcome description contains multiple 'AND' conjunctions
+    - Train has both setup AND teardown (match lifecycle)
+    - Mix of exploratory (gesture) AND core mechanic flows
+    - Multiple independent feedback loops
+    - Participants from 3+ different themes

package/planner-nodes/nodes/planner.train.sequence.convention.yaml

@@ -0,0 +1,34 @@
+schema_version: 1.1.0
+rule_id: planner.train.sequence
+kind: family
+status: active
+name: Train sequence elements
+statement: A sequence is ordered workflow steps; each step transfers one artifact (step, intent, from,
+  to, artifact). (Loop/route elements are documented but forbidden under the linearity rule.)
+source:
+  legacy_path: src/atdd/planner/conventions/train.convention.yaml
+  legacy_section: sequence
+  legacy_sha: 825602729f11a3a4
+  extraction_mode: high_fidelity
+content:
+  normative_text: 'step required fields: step, intent, from, to, artifact. loop (name, condition, steps)
+    and route (name, branches) are described here but FORBIDDEN by planner.train.linearity.'
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: sequence_element
+  label: Sequence elements
+  text: element -> required fields.
+  values:
+    step:
+    - step
+    - intent
+    - from
+    - to
+    - artifact
+    loop: FORBIDDEN by linearity (name, condition, steps)
+    route: FORBIDDEN by linearity (name, branches)

package/planner-nodes/nodes/planner.train.terminal-contract.convention.yaml

@@ -0,0 +1,10 @@
+schema_version: 1.1.0
+rule_id: planner.train.terminal-contract
+kind: principle
+status: draft
+name: Train terminal contract
+statement: A train's terminal step declares exactly one primary artifact. That terminal contract is the source of truth for the train's family - if it requires an Acceptance Authority commit and terminates in platform:acceptance:commit-receipt the train is delivery, otherwise it is behavior.
+terms:
+- term_id: terminal_contract
+  label: Terminal contract
+  text: the declared primary artifact of a train's final step; family (behavior|delivery) is derived from it, never from the train id.

package/planner-nodes/nodes/planner.train.theme-alignment.convention.yaml

@@ -0,0 +1,25 @@
+schema_version: 1.1.0
+rule_id: planner.train.theme-alignment
+kind: rule
+status: active
+name: Train theme alignment
+statement: A train declares its themes explicitly; most wagons should match the primary declared theme; secondary
+  themes are allowed when a train spans multiple themes.
+source:
+  legacy_path: src/atdd/planner/conventions/train.convention.yaml
+  legacy_section: theme_alignment
+  legacy_sha: 825602729f11a3a4
+  extraction_mode: high_fidelity
+content:
+  examples:
+  - train:orders:checkout -> themes:[orders] (all wagons orders)
+  - train:commerce:fulfilment -> themes:[orders, inventory]
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: theme_alignment
+  text: primary theme is the first declared theme; most wagons match it.

package/planner-nodes/nodes/planner.train.theme-orchestrator-urn.convention.yaml

@@ -0,0 +1,27 @@
+schema_version: 1.1.0
+rule_id: planner.train.theme-orchestrator-urn
+kind: rule
+status: active
+name: Theme orchestrator URN
+statement: Theme orchestrator files (python/trains/orchestrators/{theme}.py) carry train:{theme}:{train_id}
+  URN lines, one per implemented train.
+source:
+  legacy_path: src/atdd/planner/conventions/train.convention.yaml
+  legacy_section: urn_naming.theme_orchestrator_urn
+  legacy_sha: 825602729f11a3a4
+  extraction_mode: high_fidelity
+content:
+  examples:
+  - train:mechanic:decision-standard -> python/trains/orchestrators/mechanic.py
+  - 'multiple # urn: lines for files implementing multiple trains'
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: orchestrator_urn
+  text: the theme-prefixed train URN on an orchestrator file.
+  values:
+    pattern: train:{theme}:{train_id}

package/planner-nodes/nodes/planner.train.theme-ranges.convention.yaml

@@ -0,0 +1,28 @@
+schema_version: 1.1.0
+rule_id: planner.train.theme-ranges
+kind: family
+status: active
+name: Train theme taxonomy
+statement: Each train declares one or more named themes. Themes classify the journey; they are not encoded in the train identity.
+source:
+  legacy_path: src/atdd/planner/conventions/train.convention.yaml
+  legacy_section: numbering.theme_ranges + numbering.capacity
+  legacy_sha: 825602729f11a3a4
+  extraction_mode: high_fidelity
+content:
+  normative_text: 'Themes are named metadata. Train identity remains train:{subject}:{slug}.'
+parity:
+  source_fragments_preserved: false
+  examples_preserved: false
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-09-22'
+  divergence_note: The retired numeric theme-range system is deliberately excluded from the typed-identity convention.
+terms:
+- term_id: theme_taxonomy
+  label: Themes
+  text: themes are repository-defined plan metadata.
+  values:
+    source: plan/_themes.yaml
+    reserved_zero: commons
+    other_values: repository-defined