@afokapu/atdd-bun 0.1.0

package/planner-nodes/nodes/planner.interface.ownership-rules.convention.yaml

@@ -0,0 +1,54 @@
+schema_version: 1.1.0
+rule_id: planner.interface.ownership-rules
+kind: rule
+status: active
+name: 'Interface: Ownership Rules'
+statement: The wagon that declares an artifact in produce[] is its producer and generates
+  the artifact contract; a wagon that declares the same artifact in consume[] is a
+  consumer and references the existing contract. An optional contract field on each
+  entry points to the contract path.
+implementation:
+  type: none
+source:
+  legacy_path: src/atdd/planner/conventions/interface.convention.yaml
+  legacy_sha: sha256:3415a521b5eec18b
+  extraction_mode: high_fidelity
+  legacy_section: ownership-rules
+content:
+  summary: Producer/consumer roles assign single ownership of each contract to the
+    producing wagon while letting consumers reference it, which is what makes bidirectional
+    coverage and orphan detection possible.
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: true
+  fix_hint_preserved: true
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: producer_consumer
+  label: Producer and consumer roles
+  text: A producer generates the artifact contract - it is the wagon that declares
+    the artifact in produce[]. A consumer references an existing contract - it is
+    the wagon that declares the artifact in consume[].
+  values:
+    producer: Generates artifact contract (wagon that declares artifact in produce[])
+    consumer: References existing contract (wagon that declares artifact in consume[])
+  examples:
+    positive:
+    - 'producer wagon resolve-dilemmas: produce name mechanic:decision.choice, to
+      external, contract contracts/artifacts/decision/choice.json'
+    - 'consumer wagon commit-state: consume name mechanic:decision.choice, from wagon:resolve-dilemmas,
+      contract contracts/artifacts/decision/choice.json'
+- term_id: contract_field
+  label: Optional contract field
+  text: The contract field is optional for backward compatibility but recommended
+    for the artifact-centric contract system. Existing wagons work without a contract
+    field (implicit contracts); new wagons should add explicit contract references.
+  values:
+    required: false
+    recommended: true
+    rationale: Optional for backward compatibility; recommended for artifact-centric
+      contract system
+    migration: Transition from implicit contracts (no contract field) to explicit
+      contracts (with contract field). Existing wagons work without contract field;
+      new wagons should add explicit contract references

package/planner-nodes/nodes/planner.interface.structure-rules.convention.yaml

@@ -0,0 +1,112 @@
+schema_version: 1.1.0
+rule_id: planner.interface.structure-rules
+kind: rule
+status: active
+name: 'Interface: Structure Rules'
+statement: An artifact's contract directory layout follows one of three structures
+  - FLAT, FACETED, or COLLECTION - determined by whether the name has a dot facet
+  and whether the resource holds multiple schema files.
+implementation:
+  type: none
+source:
+  legacy_path: src/atdd/planner/conventions/interface.convention.yaml
+  legacy_sha: sha256:3415a521b5eec18b
+  extraction_mode: high_fidelity
+  legacy_section: structure-rules
+content:
+  summary: A deterministic mapping from artifact name to physical layout lets the
+    contract path be derived from the logical name and keeps simple resources flat
+    while supporting faceted and multi-schema resources without ambiguity.
+  examples:
+  - 'ux:foundations.color -> contracts/commons/ux/foundations/color.schema.json  #
+    faceted, alternative to collection'
+  counter_examples:
+  - 'fragment:pool -> contracts/fragment/pool/pool.schema.json  # over-nested; single
+    resource must be flat'
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: true
+  fix_hint_preserved: true
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: structure_determination
+  label: How structure is determined
+  text: 'Structure is determined by: (1) a dot (.) indicates faceted, (2) multiple
+    schema files indicate collection, (3) otherwise flat.'
+  values:
+    flat: 'Simple resources use FLAT structure: contracts/{domain}/{resource}.schema.json'
+    faceted: 'Resources with category facet use NESTED structure: contracts/{domain}/{resource}/{category}.schema.json'
+    collection: 'Resources containing MULTIPLE schemas use COLLECTION structure: contracts/{domain}/{resource}/*.schema.json'
+    determination: 'Structure determined by: (1) dot (.) indicates faceted, (2) multiple
+      schema files indicate collection, (3) otherwise flat'
+- term_id: flat_pattern
+  label: FLAT structure
+  text: A single schema file for a single resource. Artifact name {domain}:{resource}
+    maps to contracts/{domain}/{resource}.schema.json with tests at contracts/{domain}/tests/{resource}_schema_test.*.
+  values:
+    description: Single schema file for single resource
+    structure: contracts/{domain}/{resource}.schema.json
+    tests: contracts/{domain}/tests/{resource}_schema_test.*
+    artifact_name: '{domain}:{resource}'
+  examples:
+    positive:
+    - 'match:dilemma.current -> contracts/dilemma/current.schema.json  # singular
+      noun -> flat (NOT dilemma/current/current.schema.json)'
+    - 'fragment:pool -> contracts/fragment/pool.schema.json  # single resource ->
+      flat (NOT fragment/pool/pool.schema.json)'
+    - 'mechanic:decision.choice -> contracts/decision/choice.schema.json  # single
+      resource -> flat'
+- term_id: faceted_pattern
+  label: FACETED structure
+  text: A nested schema using dot notation for a category facet. Artifact name {domain}:{resource}.{category}
+    maps to contracts/{domain}/{resource}/{category}.schema.json; the category is
+    expressed as a dot facet in the artifact name.
+  values:
+    description: Nested schema using dot notation for category facet
+    structure: contracts/{domain}/{resource}/{category}.schema.json
+    tests: contracts/{domain}/{resource}/tests/{category}_schema_test.*
+    artifact_name: '{domain}:{resource}.{category}'
+    note: Category expressed as dot facet in artifact name
+  examples:
+    positive:
+    - 'ux:foundations.color -> contracts/commons/ux/foundations/color.schema.json  #
+      has dot facet -> nested'
+    - ux:primitives.icon
+- term_id: collection_pattern
+  label: COLLECTION structure
+  text: A directory containing multiple related schemas for a single resource. Artifact
+    name {domain}:{resource} maps to contracts/{domain}/{resource}/*.schema.json;
+    a single wagon artifact maps to MULTIPLE schema files and may include an optional
+    catalog.schema.json master index. Each schema carries metadata distinguishing
+    its member from the shared resource.
+  values:
+    description: Directory containing multiple related schemas for a single resource
+    structure: contracts/{domain}/{resource}/*.schema.json
+    tests: contracts/{domain}/{resource}/tests/*_schema_test.*
+    artifact_name: '{domain}:{resource}'
+    note: Single wagon artifact maps to MULTIPLE schema files; may include optional
+      catalog.schema.json as master index
+    metadata_collection: true
+    metadata_member: Identifies specific schema (e.g., 'color', 'spacing')
+    metadata_resource: Same for all schemas in collection (e.g., 'foundations')
+    metadata_example: '{"domain": "ux", "resource": "foundations", "collection": true,
+      "member": "color"}'
+  examples:
+    positive:
+    - 'ux:foundations -> contracts/commons/ux/foundations/*.schema.json  # plural
+      noun -> collection (color, spacing, typography)'
+    - 'ux:primitives -> contracts/commons/ux/primitives/*.schema.json  # plural noun
+      -> collection (icon, shape, mask)'
+- term_id: logical_physical_naming
+  label: Logical and physical naming patterns
+  text: The logical pattern is {domain}:{resource}[.{category}] and the physical pattern
+    is contracts/{domain}/{resource}[/{category}].json. Domain-based organization
+    enables REST API mapping and clear ownership; the colon separator denotes hierarchy
+    and the dot separator denotes a facet; optional category supports nested resources.
+  values:
+    logical_pattern: '{domain}:{resource}[.{category}]'
+    physical_pattern: contracts/{domain}/{resource}[/{category}].json
+    rationale: Domain-based organization enables REST API mapping and clear ownership.
+      Colon separator denotes hierarchy, dot separator denotes facet. Optional category
+      supports nested resources.

package/planner-nodes/nodes/planner.interface.tests-subdirectory.convention.yaml

@@ -0,0 +1,61 @@
+schema_version: 1.1.0
+rule_id: planner.interface.tests-subdirectory
+kind: constraint
+status: active
+name: 'Interface: Tests Subdirectory'
+statement: Every leaf directory under contracts/ or telemetry/ (one containing .schema.json
+  or signal .json files) must contain a tests/ subdirectory.
+terms:
+- term_id: tests_required_rule
+  label: Leaf directories must have tests/
+  text: Leaf directories (containing .schema.json or signal .json files) must have
+    a tests/ subdirectory. Both contracts/ and telemetry/ follow the pattern {domain}/{resource}[/{category}]/
+    with a required tests/ at the leaf.
+  values:
+    rule: Leaf directories (containing .schema.json or signal .json files) must have
+      tests/
+    contracts_pattern: contracts/{domain}/{resource}[/{category}]/
+    contracts_tests_pattern: contracts/{domain}/{resource}[/{category}]/tests/
+    telemetry_pattern: telemetry/{domain}/{resource}[/{category}]/
+    telemetry_tests_pattern: telemetry/{domain}/{resource}[/{category}]/tests/
+    tests_required: true
+  examples:
+    positive:
+    - contracts/commons/ux/foundations/ with color.schema.json, spacing.schema.json,
+      tests/color_schema_test.json, tests/spacing_schema_test.json
+    - contracts/commons/ux/primitives/icons/ with icon.schema.json, tests/icon_schema_test.json
+    - telemetry/ux/foundations/ with metric.ui.duration.json, event.ux.json, tests/metric_ui_duration_test.json
+    - telemetry/ux/primitives/icons/ with event.ui.json, tests/event_ui_test.yaml
+    negative:
+    - contracts/commons/ux/foundations/ with color.schema.json but no tests/ subdirectory
+- term_id: platform_validation_tests
+  label: Enforcing platform validation tests
+  text: Enforcement lives in src/atdd/planner/validators/test_contract_tests_subdirectory.py.
+    One validator covers both leaf rules — its _ROOTS is ("contracts", "telemetry")
+    — so there is no separate telemetry validator to run.
+  values:
+    enforcement: src/atdd/planner/validators/test_contract_tests_subdirectory.py
+    validator: test_contract_tests_subdirectory
+    covers_roots: contracts, telemetry
+implementation:
+  type: validator
+  ref: test_contract_tests_subdirectory::test_contract_tests_subdirectory
+source:
+  legacy_path: src/atdd/planner/conventions/interface.convention.yaml
+  legacy_sha: sha256:3415a521b5eec18b
+  extraction_mode: high_fidelity
+  legacy_section: tests-subdirectory
+content:
+  summary: Contracts and telemetry follow a flexible directory pattern, but each leaf
+    holding a schema or signal must ship its conformance tests alongside it so platform
+    validation can verify the artifact against fixtures.
+metadata:
+  severity: 2
+  disposition: advisory
+  introduced_in: 4.28.0
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: true
+  fix_hint_preserved: true
+  reviewed_at: '2026-06-16'

package/planner-nodes/nodes/planner.interlocking.definition.convention.yaml

@@ -0,0 +1,36 @@
+schema_version: 1.1.0
+rule_id: planner.interlocking.definition
+kind: family
+status: draft
+name: Interlocking — advisory semantic anchor
+statement: An interlocking is the domain-decomposition artifact for a diverging journey
+  — it declares WHICH train is selected next when a journey branches, keyed by a produced
+  artifact (the divergence signal), composing multiple strictly-linear trains into a
+  branching journey-of-journeys. It is a declared routing registry (artifact_urn ->
+  train_id), not an imperative map. This names the routing DECISION; the runtime that
+  resolves and executes it (the route-control runner and its dispatcher) is a coder/tester
+  concern. This node is an advisory semantic anchor — it enforces nothing directly;
+  the enforceable parts of this meaning are decomposed into the constraint/rule nodes
+  that require it.
+terms:
+- term_id: semantic_anchor
+  label: Advisory semantic anchor
+  text: a definitional node that gives the artifact a stable meaning but is not itself
+    bound to a validator; it is transitively protected by the enforceable constraint/rule
+    nodes that require it.
+- term_id: interlocking
+  label: Interlocking
+  text: interlocking -> {routing-decision, artifact-keyed, declared-registry, train-composing}.
+  values:
+    routing-decision: selects the next train when a journey diverges, rather than branching
+      inside a train (trains stay linear, see planner.train.linearity).
+    artifact-keyed: dispatch is keyed by a produced artifact URN; a composite (urn,
+      discriminant) key is exceptional (see planner.train.dispatch-map-is-registry,
+      planner.train.dispatch-composite-key-exceptional).
+    declared-registry: the dispatch map is a declared, schema-valid registry the domain
+      owns, not code.
+    train-composing: sequences multiple linear trains into a branching journey-of-journeys.
+  note: Enforcers for the runtime realization (route-control runner exists / delegates
+    execution / carries no cargo / bilateral binding) live in the coder+tester layer
+    (atdd.extension.coder.train-interlocking and atdd.extension.tester.train-interlocking) and are related to this domain anchor
+    by cross-persona traceability, tracked as a separate follow-up, not authored here.

package/planner-nodes/nodes/planner.interlocking.registry-mirrors-document.convention.yaml

@@ -0,0 +1,38 @@
+schema_version: 1.0.0
+rule_id: planner.interlocking.registry-mirrors-document
+kind: rule
+status: active
+name: The interlocking registry agrees with the documents it indexes
+statement: Every entry in plan/_trains/_interlockings.yaml must agree with the document
+  it points at on every field it mirrors — theme, status and surfaces. The document
+  is authoritative; the registry is discovery metadata, so a disagreement is always
+  the registry being wrong.
+terms:
+- term_id: mirrored_field
+  text: a field the registry denormalises from the document it indexes — theme, status,
+    surfaces
+- term_id: authoritative_document
+  text: plan/_trains/_interlockings/<id>.yaml, which the registry entry's path names;
+    on disagreement the document wins and the registry entry is the defect
+implementation:
+  type: validator
+  ref: test_interlocking_registry_coherence::test_live_registry_agrees_with_every_document_it_indexes
+metadata:
+  severity: 3
+  disposition: strict
+  introduced_in: '1855'
+  core_design_refs:
+  - afokapu/atdd#1818
+  - afokapu/atdd#1846
+validation:
+  family: coherence
+  template: cross_artifact_field_agreement
+  variant: planner_interlocking_registry_mirror
+  phase: CONFIRM
+  enforcement: confirm-blocking
+  subject_kind: interlocking
+  failure_evidence:
+  - interlocking_id
+  - field
+  - registry_value
+  - document_value

package/planner-nodes/nodes/planner.issue-body.dependency-entries-must-be-classified.convention.yaml

@@ -0,0 +1,21 @@
+schema_version: 1.0.0
+rule_id: planner.issue-body.dependency-entries-must-be-classified
+kind: rule
+status: active
+statement: 'Every #N entry in an issue body''s Dependencies section must carry a classification
+  tag: prereq, merged, sibling, or parallel.'
+rationale: Classifying each dependency prevents the session-template merge-wait loop
+  from hanging on sibling or parallel work.
+terms:
+- term_id: dependency_entry
+  text: a '#N' reference in the Dependencies section of an issue body
+- term_id: classification_tag
+  text: a trailing prereq/merged/sibling/parallel marker on the entry
+implementation:
+  type: validator
+  ref: test_issue_deps_have_classification_tags::test_issue_deps_have_classification_tags
+metadata:
+  severity: 2
+  disposition: advisory
+  introduced_in: 3.81.0
+  suppression_deadline: "2026-12-31"

package/planner-nodes/nodes/planner.issue-body.graph-context-required.convention.yaml

@@ -0,0 +1,21 @@
+schema_version: 1.0.0
+rule_id: planner.issue-body.graph-context-required
+kind: rule
+status: active
+statement: Every parent issue body must carry a populated Graph Context section, neither
+  missing nor left as the injection placeholder.
+rationale: A populated Graph Context section forces each issue to state where it sits
+  in the dependency graph before work starts.
+terms:
+- term_id: parent_issue_body
+  text: the body of an atdd parent issue
+- term_id: graph_context_section
+  text: the populated Graph Context subsection of the issue body
+implementation:
+  type: validator
+  ref: test_issue_body_has_graph_context::test_issue_body_has_graph_context
+metadata:
+  severity: 3
+  disposition: suppress-and-clean
+  introduced_in: 3.50.0
+  suppression_deadline: "2026-12-31"

package/planner-nodes/nodes/planner.journey.continuation-closure.convention.yaml

@@ -0,0 +1,51 @@
+schema_version: 1.0.0
+rule_id: planner.journey.continuation-closure
+kind: constraint
+status: active
+name: Journey continuation closure
+statement: >-
+  Starting from a journey's entrypoint interlocking, every reachable interlocking route must have a
+  unique route_id and be accounted for exactly once by either a continuation or a terminal. A continuation's source route
+  must exist, its declared artifact must occur in the linear train selected by that route, and its
+  destination interlocking must exist. Continuation or terminal declarations whose source interlocking
+  is unreachable from the journey entrypoint are invalid. Continuation cycles are rejected until an
+  explicit loop construct defines bounded/intentional repetition.
+rationale: >-
+  Interlocking bilateral binding closes declaration -> runtime -> trace for one routing decision, but
+  without a higher-order closure rule one interlocking can hand off to another only implicitly in code.
+  This rule makes the journey-of-journeys topology explicit and prevents silent gaps, duplicate
+  continuations, disconnected topology fragments, and artifact-free handoffs.
+terms:
+  - term_id: route_key
+    text: the pair (interlocking_id, route_id); route_id must be unique inside each reachable interlocking so the topology key is unambiguous.
+  - term_id: accounted_route
+    text: a reachable route with exactly one outgoing declaration — continuation or terminal, never both.
+  - term_id: artifact_handoff
+    text: >-
+      a continuation artifact that appears in the selected train's declared sequence, proving the
+      cross-interlocking edge is anchored in the plan rather than invented by runtime code.
+  - term_id: acyclic_topology
+    text: >-
+      continuation edges may not form a cycle in this version; looping behavior requires a future
+      explicit loop construct so termination and proof obligations are not implicit.
+implementation:
+  type: validator
+  ref: planner.static.validators.bun::journeyContinuationFindings
+metadata:
+  severity: 4
+  disposition: strict
+  introduced_in: 0.1.0
+validation:
+  family: closure
+  template: graph_route_space_closure
+  variant: planner_journey_continuation
+  phase: CONFIRM
+  enforcement: confirm-blocking
+  subject_kind: journey
+  failure_evidence:
+    - journey_id
+    - interlocking_id
+    - route_id
+    - artifact
+    - destination_interlocking_id
+    - reason

package/planner-nodes/nodes/planner.journey.definition.convention.yaml

@@ -0,0 +1,39 @@
+schema_version: 1.0.0
+rule_id: planner.journey.definition
+kind: family
+status: active
+name: Journey topology — composition above interlockings
+statement: >-
+  A journey is the declarative topology that composes routing decisions across interlockings.
+  Interlockings remain local decision boundaries: each selects exactly one linear train. An exposed
+  journey declares the Station Master actions that start it and its first interlocking. The journey
+  owns what happens AFTER that selected train completes: a route may terminate explicitly, or a named
+  artifact produced by the selected train may continue control at another interlocking. A journey
+  therefore composes interlocking -> train -> interlocking without making interlockings recursive and
+  without moving wagon execution out of TrainRunner.
+terms:
+  - term_id: journey
+    label: Journey topology
+    text: journey -> {station-entrypoint, entrypoint-interlocking, route-continuations, explicit-terminals}.
+  - term_id: station_entrypoint
+    text: >-
+      exposed journeys declare Station Master actions and consumer surfaces; Bun binds those actions
+      to {journeyId, path} through coder.bun.station-master-journey-routing.
+  - term_id: continuation
+    text: >-
+      a binding from one (interlocking_id, route_id) pair, through an artifact produced by that
+      route's selected train, to the next interlocking.
+  - term_id: terminal
+    text: an explicit declaration that a route ends the journey rather than continuing to another interlocking.
+  - term_id: ownership_boundary
+    text: >-
+      Interlocking owns train selection; TrainRunner owns linear wagon execution; Journey owns
+      continuation between routing decisions. None of the three absorbs the others.
+notes: >-
+  The canonical document shape is planner-schemas/journey.schema.json. Journey artifacts are planner
+  data; a Bun runtime realization may introduce a JourneyRunner, but runtime execution is deliberately
+  separate from this semantic definition.
+metadata:
+  severity: 3
+  disposition: advisory
+  introduced_in: 0.1.0

package/planner-nodes/nodes/planner.plan.confirm-before-author.convention.yaml

@@ -0,0 +1,28 @@
+schema_version: 1.1.0
+rule_id: planner.plan.confirm-before-author
+kind: rule
+status: active
+statement: 'Nothing is authored before the operator confirms the locked decomposition.
+  The Ratify gate is the conversational-to-deterministic boundary: only on ratification
+  does atdd plan (the system, not the agent) invoke atdd author <kind> per locked
+  unit.'
+implementation:
+  type: validator
+  ref: test_plan_confirm_before_author::test_confirm_before_author_is_enforced
+content:
+  normative_text: The session machine's author pass MUST refuse to invoke any atdd
+    author writer until the session is locked by the operator's ratification.
+  fix_hint: 'PlanSession.author() must raise SessionGateError when self.locked is
+    False, before calling any author writer. Keep the lock guard as the first
+    statement of author().'
+metadata:
+  severity: 4
+  disposition: strict
+  introduced_in: 3.124.0
+terms:
+- term_id: confirm_boundary
+  text: the point at which LLM/operator judgment ends and deterministic authoring
+    begins.
+- term_id: author_on_confirm
+  text: on confirm, atdd plan deterministically invokes atdd author per locked unit
+    (complete, atomic, idempotently replayable).

package/planner-nodes/nodes/planner.plan.confirm-binds-an-issue.convention.yaml

@@ -0,0 +1,39 @@
+schema_version: 1.1.0
+rule_id: planner.plan.confirm-binds-an-issue
+kind: rule
+status: active
+statement: 'An atdd plan decomposition needs no PRE-EXISTING issue or up-front ceremony,
+  but it MUST be bound to a local ATDD issue record before Ratify: on Ratify, atdd plan
+  binds the locked decomposition to a target issue (or mints one from the main job) and
+  authors the plan as that issue''s PLANNED-phase substrate on its registered branch +
+  worktree. The binding identity is the LOCAL manifest/State Store record (its slug; #945/#1168),
+  not a GitHub issue number — GitHub is a downstream extension that syncs the number after
+  install, so the iron rule (issue + branch + worktree per repo modification) holds even
+  with no GitHub. The session removes the up-front ceremony, not the issue.'
+implementation:
+  type: validator
+  ref: test_plan_confirm_binds_issue::test_confirm_binds_an_issue_is_enforced
+content:
+  normative_text: The session must refuse to lock (confirm) a decomposition that is
+    not bound to an ATDD issue, so plan substrate is never authored on an untracked branch.
+  fix_hint: 'Bind before ratify — atdd plan session bind-issue --id <sess> --issue <slug>
+    (the local manifest/State Store slug of a target issue), or mint one from the main job
+    (run `atdd coach issues open` to list bindable issue slugs).
+    PlanSession.confirm() raises until self.issue_ref is set. The slug is GitHub-agnostic; the
+    GitHub number is a synced projection. Corrects the earlier in-session-no-issue framing,
+    which wrongly read as ''no issue at all''.'
+metadata:
+  severity: 4
+  disposition: strict
+  introduced_in: 3.128.0
+  supersedes: planner.plan.in-session-no-issue
+terms:
+- term_id: no_upfront_ceremony
+  text: the session needs no pre-existing issue or brief; it starts conversationally
+    and decomposes before any issue paperwork.
+- term_id: bind_or_mint
+  text: on Ratify the plan binds to a target issue or mints one; the iron rule
+    (issue + branch + worktree per repo modification) always holds.
+- term_id: modify_loop
+  text: a post-commit validator failure re-opens the session for operator adjustment
+    and re-author.

package/planner-nodes/nodes/planner.plan.confirm-requires-interlocking-sanity.convention.yaml

@@ -0,0 +1,30 @@
+schema_version: 1.0.0
+rule_id: planner.plan.confirm-requires-interlocking-sanity
+kind: policy
+status: active
+name: Confirm requires interlocking sanity
+statement: Ratify cannot lock a train-bearing plan when required interlocking sanity
+  fails.
+terms:
+- term_id: confirm_gate
+  text: Ratify refuses to lock a train-bearing plan when required interlocking sanity
+    fails, and a failure leaves the session unlocked
+implementation:
+  type: validator
+  ref: test_confirm_interlocking_sanity::test_confirm_requires_interlocking_sanity
+metadata:
+  severity: 4
+  disposition: strict
+validation:
+  family: presence
+  template: conditional_requirement
+  variant: planner_plan_confirm_requires_interlocking_sanity
+  phase: CONFIRM
+  enforcement: confirm-blocking
+  subject_kind: plan-session
+  failure_evidence:
+  - session_id
+  - train_id
+  - interlocking_id
+  - route_id
+  - failed_rule

package/planner-nodes/nodes/planner.plan.granularity-completeness.convention.yaml

@@ -0,0 +1,38 @@
+schema_version: 1.0.0
+rule_id: planner.plan.granularity-completeness
+kind: policy
+status: active
+name: Ratify reports the dangling granularity ladder
+statement: Ratify names the rungs of the granularity ladder a decomposition did not
+  descend, so an operator is told that a locked plan is not testable end to end rather
+  than having to notice it.
+terms:
+- term_id: ladder
+  text: 'the rungs a decomposition descends: wagon, feature, WMBT, acceptance. A plan
+    that keeps wagons and nothing else has named a shape but nothing testable.'
+- term_id: reports_not_blocks
+  text: Advisory by default, and deliberately so. A plan session must allow incremental
+    composition and planner.decomposition.local-scope scopes each run to a slice, so
+    refusing to lock eight wagons until their features exist would make the session
+    unusable. The failure being closed is DETECTION — an operator holding the protocol
+    in memory was the only thing that noticed a wagons-only plan had locked.
+- term_id: strict_opt_in
+  text: '`atdd plan ratify --strict` turns the report into a refusal for a repo that
+    wants the hard gate; it unlocks before raising, so the refusal is atomic.'
+implementation:
+  type: validator
+  ref: test_plan_unit_spec_schema::test_ratify_reports_the_dangling_ladder
+metadata:
+  severity: 2
+  disposition: advisory
+validation:
+  family: presence
+  template: conditional_requirement
+  variant: planner_plan_granularity_completeness
+  phase: CONFIRM
+  enforcement: advisory
+  subject_kind: plan-session
+  failure_evidence:
+  - session_id
+  - kept_kinds
+  - dangling_rungs

package/planner-nodes/nodes/planner.plan.session-lifecycle.convention.yaml

@@ -0,0 +1,23 @@
+schema_version: 1.0.0
+rule_id: planner.plan.session-lifecycle
+kind: policy
+status: active
+statement: 'atdd plan runs a gated decomposition session: Intent -> Attach -> Compose
+  -> Ratify, then author -> verify -> modify. The stages name what the OPERATOR is
+  deciding, not what the tool is doing. Stages are gates not scripts (free dialogue
+  within a stage; backtracking allowed); a stage advances only when its exit condition
+  (proper state) holds. These are the SESSION stages, and they are a separate
+  vocabulary from the WMBT job steps owned by steps.convention — do not read the two
+  as one system.'
+terms:
+- term_id: session_stages
+  text: 'the four session gates: Intent (main job kept), Attach (sources + plan/ state
+    captured), Compose (candidate decomposition convention-shaped), Ratify (decomposition
+    locked by the operator).'
+- term_id: gate_not_script
+  text: within a stage the conversation is dynamic; the gate only defines the exit
+    state; a pivot may reopen an earlier stage.
+- term_id: ratify_before_author
+  text: the Ratify gate is the conversational->deterministic boundary; nothing is authored
+    before it. Its rule keeps the name planner.plan.confirm-before-author — the stage
+    is Ratify, the rule is confirm-before-author.