@afokapu/atdd-bun 0.1.0

package/planner-nodes/nodes/planner.coverage.bidirectional-coverage-between-wagons.convention.yaml

@@ -0,0 +1,33 @@
+schema_version: 1.1.0
+rule_id: planner.coverage.bidirectional-coverage-between-wagons
+kind: rule
+status: active
+name: Wagon - Feature Coverage
+statement: A wagon and its features must reference each other bidirectionally (feature->wagon and wagon->feature).
+source:
+  legacy_path: src/atdd/planner/conventions/coverage.convention.yaml
+  legacy_section: rules
+  legacy_sha: 27e800378c584902
+  extraction_mode: high_fidelity
+  legacy_rule_id: planner.coverage.bidirectional-coverage-between-wagons
+bidirectional:
+- direction: feature -> wagon
+  requirement: Every feature file must be referenced by its wagon manifest
+  exceptions: features_orphaned allow-list
+  validator: test_all_features_in_wagon_manifest
+- direction: wagon -> feature
+  requirement: Every features[] entry must have corresponding YAML file
+  validator: test_all_wagon_feature_refs_exist
+metadata:
+  aliases:
+  - COVERAGE-PLAN-2.2
+  disposition: documentation-only
+parity:
+  source_fragments_preserved: true
+  examples_preserved: false
+  implementation_preserved: true
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: wagon_feature_coverage
+  text: each feature is referenced by its wagon and vice versa.

package/planner-nodes/nodes/planner.coverage.coverage-graph.convention.yaml

@@ -0,0 +1,31 @@
+schema_version: 1.1.0
+rule_id: planner.coverage.coverage-graph
+kind: family
+status: active
+name: Planner coverage graph
+statement: 'The planner coverage graph ensures traceability from trains down to acceptances: Train ->
+  Wagon -> Feature -> WMBT -> Acceptance, each level guarded by coverage validators.'
+source:
+  legacy_path: src/atdd/planner/conventions/coverage.convention.yaml
+  legacy_section: coverage_graph + rollout
+  legacy_sha: 27e800378c584902
+  extraction_mode: high_fidelity
+content:
+  normative_text: Section 2 of the ATDD Hierarchy Coverage Spec v0.1. Validators become strict in Phase
+    2 (PLANNER_TESTER_ENFORCEMENT).
+parity:
+  source_fragments_preserved: true
+  examples_preserved: false
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: coverage_level
+  label: Coverage levels
+  text: level -> {contains, validators}.
+  values:
+    Train: contains Wagons (via participants) — COVERAGE-PLAN-2.1
+    Wagon: contains Features (via features[]) — 2.1, 2.2
+    Feature: contains WMBTs (via wmbts[]) — 2.2, 2.3
+    WMBT: contains Acceptances (via acceptances[]) — 2.3, 2.4
+    Acceptance: contains Test criteria — 2.4

package/planner-nodes/nodes/planner.coverage.every-wmbt-must-be.convention.yaml

@@ -0,0 +1,29 @@
+schema_version: 1.1.0
+rule_id: planner.coverage.every-wmbt-must-be
+kind: rule
+status: active
+name: WMBT - Feature Coverage
+statement: Every WMBT must be referenced by at least one feature (wmbt->feature).
+source:
+  legacy_path: src/atdd/planner/conventions/coverage.convention.yaml
+  legacy_section: rules
+  legacy_sha: 27e800378c584902
+  extraction_mode: high_fidelity
+  legacy_rule_id: planner.coverage.every-wmbt-must-be
+bidirectional:
+- direction: wmbt -> feature
+  requirement: Every WMBT file must appear in at least one feature's wmbts list
+  validator: test_all_wmbts_in_at_least_one_feature
+metadata:
+  aliases:
+  - COVERAGE-PLAN-2.3
+  disposition: documentation-only
+parity:
+  source_fragments_preserved: true
+  examples_preserved: false
+  implementation_preserved: true
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: wmbt_feature_coverage
+  text: every WMBT file appears in at least one feature's wmbts list.

package/planner-nodes/nodes/planner.coverage.every-wmbt-must-have.convention.yaml

@@ -0,0 +1,33 @@
+schema_version: 1.1.0
+rule_id: planner.coverage.every-wmbt-must-have
+kind: rule
+status: active
+name: WMBT - Acceptance Coverage
+statement: Every WMBT must have at least one acceptance criterion (except status:draft).
+implementation:
+  type: validator
+  ref: conventions/coverage/test_hierarchy_coverage::test_fault_injection_convention_catches
+source:
+  legacy_path: src/atdd/planner/conventions/coverage.convention.yaml
+  legacy_section: rules
+  legacy_sha: 27e800378c584902
+  extraction_mode: high_fidelity
+  legacy_rule_id: planner.coverage.every-wmbt-must-have
+content:
+  normative_text: 'Requirement: every WMBT must have at least one acceptance (except status:draft).'
+  exceptions:
+  - wmbts_without_acceptance allow-list
+metadata:
+  aliases:
+  - COVERAGE-PLAN-2.4
+  severity: 3
+  disposition: strict
+parity:
+  source_fragments_preserved: true
+  examples_preserved: false
+  implementation_preserved: true
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: wmbt_acceptance_coverage
+  text: every non-draft WMBT carries at least one acceptance.

package/planner-nodes/nodes/planner.coverage.exception-handling.convention.yaml

@@ -0,0 +1,32 @@
+schema_version: 1.1.0
+rule_id: planner.coverage.exception-handling
+kind: principle
+status: active
+name: Coverage exception handling
+statement: Coverage exceptions are declared via config allow-lists and status exemptions (draft artifacts
+  are exempt from 2.1 and 2.4).
+source:
+  legacy_path: src/atdd/planner/conventions/coverage.convention.yaml
+  legacy_section: exception_handling
+  legacy_sha: 27e800378c584902
+  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: allow_list
+  label: Allow-lists
+  text: allow-list -> config path + use case.
+  values:
+    wagons_not_in_train: coverage.exceptions.wagons_not_in_train — utility/shared/under-development wagons
+    features_orphaned: coverage.exceptions.features_orphaned — deprecated/experimental features
+    wmbts_without_acceptance: coverage.exceptions.wmbts_without_acceptance — draft/placeholder WMBTs
+- term_id: status_exemption
+  text: draft artifacts are exempt from full coverage.
+  values:
+    draft_exempt_from:
+    - COVERAGE-PLAN-2.1
+    - COVERAGE-PLAN-2.4

package/planner-nodes/nodes/planner.criteria.defaults.convention.yaml

@@ -0,0 +1,30 @@
+schema_version: 1.1.0
+rule_id: planner.criteria.defaults
+kind: rule
+status: active
+name: Criteria given defaults
+statement: Acceptance given sections default to empty auth scopes, no builders, no time, strict stubbing
+  policy, and no knobs.
+source:
+  legacy_path: src/atdd/planner/conventions/criteria.convention.yaml
+  legacy_section: defaults
+  legacy_sha: db262e7f5fb06226
+  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: given_defaults
+  text: the default given block.
+  values:
+    auth:
+      scopes: []
+    builders: []
+    time: {}
+    stubbing:
+      policy: strict
+      overrides: []
+    knobs: {}

package/planner-nodes/nodes/planner.criteria.harness-templates.convention.yaml

@@ -0,0 +1,159 @@
+schema_version: 1.1.0
+rule_id: planner.criteria.harness-templates
+kind: family
+status: active
+name: Harness scaffolding templates
+statement: Reusable given/when/then scaffolding template per harness, with the layers it typically exercises.
+source:
+  legacy_path: src/atdd/planner/conventions/criteria.convention.yaml
+  legacy_section: harnesses
+  legacy_sha: db262e7f5fb06226
+  extraction_mode: high_fidelity
+content:
+  summary: '13 harness templates: http, unit, event, ws, e2e, a11y, visual, metric, job, db, sec, load,
+    script.'
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: harness_template
+  label: Harness templates
+  text: harness -> {layers, given/when/then scaffold} (verbatim).
+  values:
+    http:
+      layers:
+      - presentation
+      - application
+      - domain
+      - integration
+      given:
+        auth:
+          scopes:
+          - purchase:create
+      when:
+        method: POST
+        path: /api/example
+        headers:
+          Content-Type: application/json
+        body:
+          sample: true
+      then:
+      - kind: status
+        expect: 200
+      - kind: body
+        expect:
+          ok: true
+    unit:
+      layers:
+      - application
+      - domain
+      when:
+        target: Service.method
+        args:
+          payload:
+            sample: true
+      then:
+      - kind: result
+        expect:
+          ok: true
+    event:
+      layers:
+      - application
+      - integration
+      when:
+        topic: sample.event
+        payload:
+          sample: true
+      then:
+      - kind: event
+        expect: sample.event
+    ws:
+      layers:
+      - integration
+      when:
+        url: ws://example/events
+        subscribe_msg:
+          action: subscribe
+          channel: updates
+      then:
+      - kind: message
+        expect:
+          frame: connected
+    e2e:
+      layers:
+      - presentation
+      - application
+      - domain
+      - integration
+      when:
+        url: http://example/ui
+        actions:
+        - 'fill #field'
+        - 'click #submit'
+      then:
+      - kind: visual
+        expect: success-banner
+    a11y:
+      layers:
+      - presentation
+      when: {}
+      then:
+      - kind: a11y
+        expect: passes
+    visual:
+      layers:
+      - presentation
+      when: {}
+      then:
+      - kind: snapshot
+        expect: unchanged
+    metric:
+      layers:
+      - application
+      - integration
+      when: {}
+      then:
+      - kind: metric
+        expect: metric:placeholder
+    job:
+      layers:
+      - application
+      - integration
+      when: {}
+      then:
+      - kind: status
+        expect: completed
+    db:
+      layers:
+      - integration
+      - domain
+      when: {}
+      then:
+      - kind: rows
+        expect: updated
+    sec:
+      layers:
+      - application
+      - integration
+      when: {}
+      then:
+      - kind: security
+        expect: granted
+    load:
+      layers:
+      - integration
+      - application
+      when: {}
+      then:
+      - kind: metrics
+        expect: within_limits
+    script:
+      layers:
+      - application
+      when: {}
+      then:
+      - kind: status
+        expect: 0

package/planner-nodes/nodes/planner.criteria.metric-mapping.convention.yaml

@@ -0,0 +1,136 @@
+schema_version: 1.1.0
+rule_id: planner.criteria.metric-mapping
+kind: family
+status: active
+name: Dimension -> metric mapping
+statement: Each WMBT dimension+direction maps to a default metric_id (e.g. time/minimize -> metric:latency_p50), or is explicitly declared unmapped. The table is total over wmbt.schema.json's dimension x direction enums; nothing falls through it silently.
+notes: "#1958: the node declared a dimension->metric contract and bound nothing \u2014\
+  \ no implementation, no validation, and `metric_id` in no schema and no validator,\
+  \ the same shape as #1548. Measured over 472 WMBTs, 368 carry a dimension+direction\
+  \ this table maps and NOT ONE states an executable bar; the single bar in the corpus\
+  \ (govern_lifecycle/D010) is quantity/minimize, which this table does not map. It\
+  \ is now bound to a real validator, ADVISORY: all 368 would fail on day one, and\
+  \ the remedy is not yet affordable because no error_ratio, success_ratio or\
+  \ occurrence_rate module exists for runners/metric_runner.py to resolve \u2014 so it\
+  \ reports a count and lets the debt be paid deliberately (issue Decision #2: phase\
+  \ it, never fail 368 at once). Before #1925 a threshold reached passes() stringified\
+  \ and every comparison was swallowed, so binding this node would have enforced a bar\
+  \ that was never evaluated; that constraint is gone."
+implementation:
+  type: validator
+  ref: test_metric_mapping_corpus_drift::test_mapped_wmbts_without_an_executable_bar_are_reported
+metadata:
+  severity: 2
+  disposition: advisory
+source:
+  legacy_path: src/atdd/planner/conventions/criteria.convention.yaml
+  legacy_section: metrics
+  legacy_sha: db262e7f5fb06226
+  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: dimension_metric
+  label: Dimension metrics
+  text: >-
+    dimension -> direction -> metric_id. Keyed on wmbt.schema.json's `dimension`
+    and `direction` enums and TOTAL over their product (6 x 4 = 24 pairs): every
+    legal pair a WMBT can carry has a row here. A pair with no default metric
+    carries the `unmapped` sentinel and states its reason under `unmapped_pairs`,
+    so a reader can tell a deliberate omission from a missing row. The schema
+    owns both vocabularies — key this table at its exact spelling.
+    Pinned by test_metric_mapping_matches_the_wmbt_enums (#1959).
+  values:
+    time:
+      minimize: metric:latency_p50
+      decrease: metric:latency_p50
+      maximize: metric:latency_increase
+      increase: metric:latency_increase
+    effort:
+      minimize: metric:user_steps
+      decrease: metric:user_steps
+      maximize: unmapped
+      increase: unmapped
+    likelihood:
+      minimize: metric:error_ratio
+      decrease: metric:error_ratio
+      maximize: metric:success_ratio
+      increase: metric:success_ratio
+    frequency:
+      minimize: metric:occurrence_rate
+      decrease: metric:occurrence_rate
+      maximize: unmapped
+      increase: unmapped
+    quantity:
+      minimize: metric:scrap_rate
+      decrease: metric:scrap_rate
+      maximize: metric:throughput
+      increase: metric:throughput
+    financial value:
+      minimize: metric:cost_per_unit
+      decrease: metric:cost_per_unit
+      maximize: metric:net_margin
+      increase: metric:net_margin
+- term_id: direction_synonyms
+  label: Direction synonyms
+  text: >-
+    The `direction` enum carries two spellings of each intent. `minimize` and
+    `decrease` both mean "less of this is better"; `maximize` and `increase`
+    both mean "more of this is better". A dimension resolves both spellings of
+    one intent to the same metric_id — before #1959 it did not, and 102 of the
+    472 authored WMBTs mapped to nothing because they wrote `minimize` where the
+    table had written `decrease`.
+  values:
+    downward:
+    - minimize
+    - decrease
+    upward:
+    - maximize
+    - increase
+- term_id: unmapped_pairs
+  label: Deliberately unmapped pairs
+  text: >-
+    The pairs carrying the `unmapped` sentinel in `dimension_metric`, with the
+    reason each has no default. Every dimension here names a downward metric
+    only; the table's other dimensions pair each intent with a DIFFERENT metric
+    (error_ratio vs success_ratio, scrap_rate vs throughput, cost_per_unit vs
+    net_margin), so an upward default cannot be the downward metric reused —
+    it would have to be a metric that was never chosen. A WMBT on one of these
+    pairs is legal and must state its own metric rather than inherit a default.
+  values:
+    effort:
+      maximize: >-
+        No upward default. `metric:user_steps` counts steps and the criteria
+        vocabulary optimises for fewer; no metric was ever chosen for wanting
+        more effort. Carried by wmbt:implement-code:E001.
+      increase: >-
+        No upward default; same as effort/maximize, which is its synonym.
+    frequency:
+      maximize: >-
+        No upward default. `metric:occurrence_rate` is paired with the downward
+        intent — the rate of an occurrence you want less of; no metric was
+        chosen for an occurrence you want more of. Carried by
+        wmbt:integrate-end-to-end:M001.
+      increase: >-
+        No upward default; same as frequency/maximize, which is its synonym.
+validation:
+  family: presence
+  template: required_field_presence
+  variant: planner_criteria_metric_mapping_corpus
+  phase: SMOKE
+  enforcement: advisory
+  subject_kind: wmbt
+  selector: WMBT files under plan/ whose dimension+direction this node maps to a metric_id
+  traversal: wmbt file -> acceptances[] -> signal.metric / signal.threshold
+  invariant: a WMBT the mapping covers states an executable bar naming the metric_id
+    the mapping assigns it
+  failure_evidence:
+  - wmbt_urn
+  - dimension
+  - direction
+  - metric_id
+  - cause

package/planner-nodes/nodes/planner.criteria.plane-keywords.convention.yaml

@@ -0,0 +1,53 @@
+schema_version: 1.1.0
+rule_id: planner.criteria.plane-keywords
+kind: family
+status: active
+name: Plane keyword routing
+statement: Keyword cues route an acceptance to a layer plane (presentation, application, domain, integration).
+source:
+  legacy_path: src/atdd/planner/conventions/criteria.convention.yaml
+  legacy_section: planes.keywords
+  legacy_sha: db262e7f5fb06226
+  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: plane_keywords
+  label: Plane keywords
+  text: layer -> routing keywords.
+  values:
+    presentation:
+    - display
+    - visible
+    - screen
+    - render
+    - animation
+    - button
+    - form
+    - modal
+    application:
+    - workflow
+    - orchestrate
+    - use case
+    - policy
+    - state
+    - saga
+    domain:
+    - rule
+    - validate
+    - aggregate
+    - entity
+    - invariant
+    - business
+    integration:
+    - database
+    - persist
+    - external
+    - queue
+    - api
+    - webhook
+    - repository

package/planner-nodes/nodes/planner.criteria.sequence-routing.convention.yaml

@@ -0,0 +1,26 @@
+schema_version: 1.1.0
+rule_id: planner.criteria.sequence-routing
+kind: rule
+status: active
+name: Layer sequence routing
+statement: 'Each layer maps to a default action in the route sequence: presentation.command, application.use_case,
+  domain.validate, integration.persist.'
+source:
+  legacy_path: src/atdd/planner/conventions/criteria.convention.yaml
+  legacy_section: planes.sequence
+  legacy_sha: db262e7f5fb06226
+  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: layer_action
+  text: layer -> default action.
+  values:
+    presentation: command
+    application: use_case
+    domain: validate
+    integration: persist

package/planner-nodes/nodes/planner.criteria.shape.convention.yaml

@@ -0,0 +1,27 @@
+schema_version: 1.1.0
+rule_id: planner.criteria.shape
+kind: rule
+status: active
+name: Criteria shape
+statement: 'Criteria entries follow the documented shape: id, description, harness, and expected_outcome.'
+source:
+  legacy_path: src/atdd/planner/conventions/criteria.convention.yaml
+  legacy_section: rules
+  legacy_sha: db262e7f5fb06226
+  extraction_mode: high_fidelity
+  legacy_rule_id: planner.criteria.shape
+metadata:
+  aliases:
+  - PLANNER-CRITERIA-SHAPE-001
+  severity: 2
+  disposition: documentation-only
+  introduced_in: 1.67.0
+parity:
+  source_fragments_preserved: true
+  examples_preserved: false
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: documented_shape
+  text: the required fields id, description, harness, expected_outcome.

package/planner-nodes/nodes/planner.decomposition.canonical-steps.convention.yaml

@@ -0,0 +1,14 @@
+schema_version: 1.0.0
+rule_id: planner.decomposition.canonical-steps
+kind: principle
+status: active
+statement: 'Job steps use the canonical step vocabulary owned by steps.convention:
+  Define, Locate, Prepare, Confirm, Execute, Monitor, Modify, Resolve, Conclude. This
+  protocol references those steps; it does not re-enumerate or redefine them.'
+terms:
+- term_id: canonical_steps
+  text: "Define/Locate/Prepare/Confirm/Execute/Monitor/Modify/Resolve/Conclude \u2014\
+    \ owned by steps.convention."
+- term_id: reference_not_restate
+  text: the protocol points at steps.convention by reference; copying its content
+    is drift.

package/planner-nodes/nodes/planner.decomposition.document-trouble-obligation.convention.yaml

@@ -0,0 +1,12 @@
+schema_version: 1.0.0
+rule_id: planner.decomposition.document-trouble-obligation
+kind: constraint
+status: active
+statement: "If the agent cannot adequately parse, analyze, or review a source document,\
+  \ it must inform the operator \u2014 stating what it could not extract or understand\
+  \ and asking how to proceed \u2014 rather than planning from a partial reading."
+terms:
+- term_id: document_trouble
+  text: any source the agent cannot fully parse/analyze/review.
+- term_id: inform_not_guess
+  text: surface the gap and ask the operator; never silently plan from a partial reading.

package/planner-nodes/nodes/planner.decomposition.domain-vs-technology.convention.yaml

@@ -0,0 +1,13 @@
+schema_version: 1.0.0
+rule_id: planner.decomposition.domain-vs-technology
+kind: principle
+status: active
+statement: Plan decomposes what the system does (user-facing jobs), not how it is
+  built. Implementation-flavored sources are reframed to user-facing jobs or routed
+  to tests/ADRs (e.g. 'use redis for caching' becomes 'browse catalog pages with instant
+  response').
+terms:
+- term_id: domain_capability
+  text: a user-facing job the system performs.
+- term_id: technology_choice
+  text: an implementation decision; reframed to the job it serves or routed to tests/ADRs.

package/planner-nodes/nodes/planner.decomposition.jtbd-vs-odi-grammar.convention.yaml

@@ -0,0 +1,18 @@
+schema_version: 1.0.0
+rule_id: planner.decomposition.jtbd-vs-odi-grammar
+kind: principle
+status: active
+statement: 'Keep two grammars separate: the main job uses JTBD job-statement grammar
+  (verb + object + contextual clarifier); WMBTs use ODI outcome grammar (direction
+  + dimension + object_of_control + context_clarifier). Collapsing job into outcome
+  too early produces malformed plan/.'
+terms:
+- term_id: jtbd
+  text: 'Jobs-To-Be-Done job statement: verb + object + contextual clarifier (e.g.
+    ''Listen to music while commuting'').'
+- term_id: odi
+  text: "Outcome-Driven Innovation outcome: direction + dimension + object_of_control\
+    \ + context_clarifier \u2014 the wmbt.schema fields."
+- term_id: premature_collapse
+  text: stating the main job as an outcome too early; forbidden because it yields
+    malformed plan artifacts.

package/planner-nodes/nodes/planner.decomposition.keep-pivot-kill.convention.yaml

@@ -0,0 +1,23 @@
+schema_version: 1.0.0
+rule_id: planner.decomposition.keep-pivot-kill
+kind: pattern
+status: active
+statement: 'Decomposition advances by per-unit keep/pivot/kill: the operator keeps,
+  pivots (names a modification), or kills each candidate (heuristic, analog, main
+  job, wagon, feature, WMBT, acceptance); an artifact is written only after a final-granularity
+  keep.'
+terms:
+- term_id: keep
+  text: accept the candidate as-is and proceed.
+- term_id: pivot
+  text: accept with a named modification, then re-confirm.
+- term_id: kill
+  text: reject the candidate; on all-killed, re-propose.
+- term_id: final_granularity
+  text: 'the granularities that resolve to an atdd author writer: wagon, feature, WMBT,
+    train, interlocking, contract, acceptance. Heuristic, analog and main job are REASONING
+    granularities — real candidates the operator decides on, but they author nothing,
+    so keeping one records a decision and writes no artifact. Made explicit by #1929:
+    the author dispatch used to RAISE on a kept heuristic, which left kill — the verdict
+    that records the opposite of what happened — as the only one that kept a session
+    authorable.'