@afokapu/atdd-bun 0.1.0

package/planner-nodes/nodes/planner.acceptance.given-when-then-structure.convention.yaml

@@ -0,0 +1,53 @@
+schema_version: 1.1.0
+rule_id: planner.acceptance.given-when-then-structure
+kind: rule
+status: active
+name: Given/When/Then structure
+statement: given declares only required preconditions; when declares the single harness-specific trigger
+  (REQUIRED); then is an array of assertions (REQUIRED).
+source:
+  legacy_path: src/atdd/planner/conventions/acceptance.convention.yaml
+  legacy_section: gherkin_structure
+  legacy_sha: 027e2d86ff127550
+  extraction_mode: high_fidelity
+content:
+  operational_guidance: 'given fields: auth, builders, time, stubbing, knobs. when is harness-specific
+    (http: method/path; unit: target; event: topic; ws/e2e: interactions). then.assertion_kinds: status,
+    body, headers, error, event_published, state_changed, metric.'
+  examples:
+  - when.http:
+      method: POST
+      path: /api/users
+      body:
+        name: John
+  - when.unit:
+      target: UserService.createUser
+      args:
+        userData:
+          name: John
+  - then:
+    - kind: status
+      expect: 200
+    - kind: error
+      expect:
+        code: USER_EXISTS
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: given_fields
+  text: 'preconditions: auth, builders, time, stubbing, knobs.'
+- term_id: assertion_kind
+  text: a then assertion kind.
+  values:
+    allowed:
+    - status
+    - body
+    - headers
+    - error
+    - event_published
+    - state_changed
+    - metric

package/planner-nodes/nodes/planner.acceptance.harness-vocabulary.convention.yaml

@@ -0,0 +1,99 @@
+schema_version: 1.1.0
+rule_id: planner.acceptance.harness-vocabulary
+kind: family
+status: active
+name: Harness vocabulary (codes + catalog)
+statement: 'The authoritative harness vocabulary: each harness name maps to an UPPERCASE code and a typical-layer
+  catalog entry.'
+source:
+  legacy_path: src/atdd/planner/conventions/acceptance.convention.yaml
+  legacy_section: harness_codes + harness_types
+  legacy_sha: 027e2d86ff127550
+  extraction_mode: high_fidelity
+content:
+  summary: Authoritative name->CODE mapping plus per-harness description and typical layers.
+parity:
+  source_fragments_preserved: true
+  examples_preserved: false
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: harness_code
+  label: Harness code map
+  text: name -> UPPERCASE code (authoritative).
+  values:
+    unit: UNIT
+    http: HTTP
+    event: EVENT
+    ws: WS
+    e2e: E2E
+    a11y: A11Y
+    visual: VIS
+    metric: METRIC
+    job: JOB
+    db: DB
+    sec: SEC
+    load: LOAD
+    script: SCRIPT
+    widget: WIDGET
+    golden: GOLDEN
+    bloc: BLOC
+    integration: INTEGRATION
+    rls: RLS
+    edge_function: EDGE
+    realtime: REALTIME
+    storage: STORAGE
+    smoke: SMOKE
+- term_id: harness_type
+  label: Harness type catalog
+  text: per-harness description and typical layers.
+  values:
+    unit:
+    - domain
+    - application
+    http:
+    - integration
+    - application
+    event:
+    - application
+    - integration
+    ws:
+    - integration
+    e2e:
+    - presentation
+    a11y:
+    - presentation
+    visual:
+    - presentation
+    metric:
+    - application
+    - integration
+    job:
+    - application
+    db:
+    - integration
+    sec:
+    - application
+    - integration
+    load:
+    - integration
+    script:
+    - application
+    widget:
+    - presentation
+    golden:
+    - presentation
+    - application
+    bloc:
+    - application
+    integration:
+    - integration
+    rls:
+    - integration
+    edge_function:
+    - integration
+    realtime:
+    - integration
+    storage:
+    - integration

package/planner-nodes/nodes/planner.acceptance.harness.convention.yaml

@@ -0,0 +1,36 @@
+schema_version: 1.1.0
+rule_id: planner.acceptance.harness
+kind: rule
+status: active
+name: Acceptance declares a harness
+statement: Each acceptance criterion declares a harness type (UNIT, INTEGRATION, SMOKE, etc.).
+source:
+  legacy_path: src/atdd/planner/conventions/acceptance.convention.yaml
+  legacy_section: rules
+  legacy_sha: 027e2d86ff127550
+  extraction_mode: high_fidelity
+  legacy_rule_id: planner.acceptance.harness
+metadata:
+  aliases:
+  - PLANNER-ACCEPTANCE-HARNESS-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: harness
+  text: the test layer that exercises the acceptance; one of the codes in the harness vocabulary.
+  examples:
+    positive:
+    - UNIT
+    - HTTP
+    - E2E
+    - SMOKE
+    negative:
+    - functional
+    - manual

package/planner-nodes/nodes/planner.acceptance.hermetic-fake-contract.convention.yaml

@@ -0,0 +1,35 @@
+schema_version: 1.1.0
+rule_id: planner.acceptance.hermetic-fake-contract
+kind: constraint
+status: active
+name: Hermetic fake-contract declaration
+statement: When execution_kind is hermetic_integration AND permitted_fakes is non-empty, the acceptance
+  MUST declare the hermetic fake-contract block — the declaration IS the contract.
+implementation:
+  type: validator
+  ref: tester.acceptance-violation.hermetic-fake-must-declare-contract
+source:
+  legacy_path: src/atdd/planner/conventions/acceptance.convention.yaml
+  legacy_section: hermetic
+  legacy_sha: 027e2d86ff127550
+  extraction_mode: high_fidelity
+content:
+  normative_text: Required when execution_kind == hermetic_integration AND permitted_fakes is non-empty.
+  constraints:
+  - 'exercised_boundaries: list[boundary_kind] — controlled-vocab surfaces exercised (required).'
+  - 'permitted_fakes: list[str] — named fakes/cassettes substituted for live infra (may be empty; when
+    empty the fidelity rule does not apply).'
+  - 'fake_contract_fidelity: list of {name, fidelity, known_gaps:list[str] required} — one per permitted
+    fake (required when permitted_fakes non-empty).'
+  - 'live_smoke_required: bool — true when a paired execution_kind: live_smoke sibling must exist under
+    the same WMBT (required).'
+  - 'live_smoke_reason: str — optional rationale when live_smoke_required is true.'
+parity:
+  source_fragments_preserved: true
+  examples_preserved: false
+  implementation_preserved: true
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: fake_contract
+  text: 'the declared fidelity contract for each permitted fake: name, fidelity, and required known_gaps.'

package/planner-nodes/nodes/planner.acceptance.id-pattern.convention.yaml

@@ -0,0 +1,34 @@
+schema_version: 1.1.0
+rule_id: planner.acceptance.id-pattern
+kind: rule
+status: active
+name: Legacy acceptance id pattern
+statement: The legacy acceptance id is AC-{STEP}-{NNN} (kept for backward compatibility in identity.id).
+source:
+  legacy_path: src/atdd/planner/conventions/acceptance.convention.yaml
+  legacy_section: id_pattern + id_mapping
+  legacy_sha: 027e2d86ff127550
+  extraction_mode: high_fidelity
+content:
+  examples:
+  - AC-EXEC-201
+  - AC-CONF-004
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: step_code
+  text: step-name -> id code.
+  values:
+    define: DEF
+    locate: LOC
+    prepare: PREP
+    confirm: CONF
+    execute: EXEC
+    monitor: MON
+    modify: MOD
+    resolve: RES
+    conclude: CONC

package/planner-nodes/nodes/planner.acceptance.max-per-wmbt.convention.yaml

@@ -0,0 +1,29 @@
+schema_version: 1.1.0
+rule_id: planner.acceptance.max-per-wmbt
+kind: constraint
+status: active
+name: Acceptance cap per WMBT
+statement: Keep acceptances <=5 per WMBT; if more are needed, split the WMBT into clearer outcomes.
+source:
+  legacy_path: src/atdd/planner/conventions/acceptance.convention.yaml
+  legacy_section: max_per_wmbt + guidelines + expected_ratios
+  legacy_sha: 027e2d86ff127550
+  extraction_mode: high_fidelity
+content:
+  constraints:
+  - 'max_per_wmbt: 5'
+  - acceptance_to_test ratio 1:1 (one acceptance -> one test)
+  - test_to_component ratio N:1
+  operational_guidance: 'Each acceptance maps to exactly one metric_id (no mixed measures). Respect WMBT
+    rules: one dimension and one lens_ref per WMBT; acceptances inherit context from the parent WMBT.'
+parity:
+  source_fragments_preserved: true
+  examples_preserved: false
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: acceptance_cap
+  text: the per-WMBT ceiling on acceptances.
+  values:
+    max: 5

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

@@ -0,0 +1,87 @@
+schema_version: 1.1.0
+rule_id: planner.acceptance.plane-keywords
+kind: family
+status: active
+name: Plane keyword cues
+statement: Keyword cues for selecting the test-layer plane when routing an acceptance.
+source:
+  legacy_path: src/atdd/planner/conventions/acceptance.convention.yaml
+  legacy_section: planes
+  legacy_sha: 027e2d86ff127550
+  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
+  text: keyword -> plane routing table.
+  values:
+    ui:
+    - display
+    - visible
+    - screen
+    - render
+    - animation
+    ux:
+    - understand
+    - clarity
+    - steps
+    - easy
+    - confusing
+    be:
+    - validate
+    - apply
+    - compute
+    - reconcile
+    - rule
+    nw:
+    - request
+    - response
+    - timeout
+    - websocket
+    - stream
+    db:
+    - query
+    - index
+    - transaction
+    - lock
+    - row
+    st:
+    - asset
+    - download
+    - upload
+    - cache
+    - blob
+    - cdn
+    tm:
+    - event
+    - metrics
+    - trace
+    - ingest
+    - drop
+    sc:
+    - schema
+    - contract
+    - version
+    - field
+    - json
+    au:
+    - login
+    - token
+    - permission
+    - rate-limit
+    - '403'
+    fn:
+    - price
+    - balance
+    - payout
+    - token
+    if:
+    - cpu
+    - memory
+    - pod
+    - node
+    - gpu

package/planner-nodes/nodes/planner.acceptance.route-construction.convention.yaml

@@ -0,0 +1,55 @@
+schema_version: 1.1.0
+rule_id: planner.acceptance.route-construction
+kind: rule
+status: active
+name: Route sequence construction
+statement: route.sequence is built as ordered {layer}.{action} transitions flowing presentation -> application
+  -> domain -> integration as needed.
+source:
+  legacy_path: src/atdd/planner/conventions/acceptance.convention.yaml
+  legacy_section: route_construction + layer_routing
+  legacy_sha: 027e2d86ff127550
+  extraction_mode: high_fidelity
+content:
+  examples:
+  - presentation_flow:
+    - presentation.command
+    - application.use_case
+    - domain.validate
+    - integration.persist
+  - query_flow:
+    - presentation.query
+    - application.query
+    - integration.read
+  - event_flow:
+    - integration.call_external
+    - application.aggregate
+    - domain.mutate
+    - integration.persist
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: route_step
+  text: one {layer}.{action} transition in a route sequence.
+  values:
+    presentation:
+    - presentation.command
+    - presentation.query
+    - presentation.display
+    application:
+    - application.use_case
+    - application.query
+    - application.aggregate
+    domain:
+    - domain.create
+    - domain.validate
+    - domain.mutate
+    - domain.policy
+    integration:
+    - integration.read
+    - integration.persist
+    - integration.call_external

package/planner-nodes/nodes/planner.acceptance.signal-telemetry-naming.convention.yaml

@@ -0,0 +1,61 @@
+schema_version: 1.1.0
+rule_id: planner.acceptance.signal-telemetry-naming
+kind: rule
+status: active
+name: Telemetry signal naming
+statement: Each acceptance declares telemetry signals (metrics, traces, logs, events) using artifact-based
+  telemetry URNs (REQUIRED).
+source:
+  legacy_path: src/atdd/planner/conventions/acceptance.convention.yaml
+  legacy_section: gherkin_structure.signal
+  legacy_sha: 027e2d86ff127550
+  extraction_mode: high_fidelity
+content:
+  normative_text: Derive metrics from 'then' quantifiable expectations; derive events from 'when' user
+    actions. Operations/wagons go in attributes, NOT in the URN.
+  operational_guidance: 'metric: telemetry:metric:{plane}:{artifact}[.{category}]:{measure}; trace: telemetry:trace:{plane}:{artifact}[.{category}]
+    (no measure); log: optional telemetry:log:...; event: telemetry:event:... or Title Case analytics
+    name. Resource must be a past-tense verb from the lexicon.'
+  constraints:
+  - 'Entity artifacts (nouns) use measures: count, size, age, staleness, freshness.'
+  - 'Event artifacts (past-tense verbs) use: latency, duration, throughput, error_rate, success_rate.'
+  examples:
+  - metric: telemetry:metric:be:order:created:duration (histogram, p95, 200ms)
+  - trace: telemetry:trace:be:order:created (server)
+  - event: telemetry:event:be:order:created  /  'Order Created'
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: measure
+  text: the trailing measure segment of a metric URN.
+  values:
+    allowed:
+    - latency
+    - duration
+    - throughput
+    - error_rate
+    - success_rate
+    - count
+    - size
+    - age
+    - staleness
+    - freshness
+- term_id: plane
+  text: the leading plane segment.
+  values:
+    allowed:
+    - ui
+    - ux
+    - be
+    - db
+    - nw
+    - st
+    - tm
+    - sc
+    - au
+    - fn
+    - if

package/planner-nodes/nodes/planner.acceptance.urn-generation.convention.yaml

@@ -0,0 +1,39 @@
+schema_version: 1.1.0
+rule_id: planner.acceptance.urn-generation
+kind: rule
+status: active
+name: Acceptance URN generation
+statement: An acceptance URN is acc:{wagon}:{wmbt_id}-{harness}-{NNN}[-{slug}], built via URNBuilder.acceptance.
+source:
+  legacy_path: src/atdd/planner/conventions/acceptance.convention.yaml
+  legacy_section: urn_generation
+  legacy_sha: 027e2d86ff127550
+  extraction_mode: high_fidelity
+content:
+  normative_text: Colon = hierarchy (acc:wagon:wmbt_id); dash = facet cluster (-harness-NNN[-slug]). Makes
+    the WMBT tie explicit, bakes in harness visibility for routing, keeps per-harness sequence and an
+    optional readability slug.
+  operational_guidance: URNBuilder.acceptance(wagon_id, wmbt_id, harness_code, seq, slug=None).
+  examples:
+  - URNBuilder.acceptance("authenticate-user", "C004", "E2E", "019") -> acc:authenticate-user:C004-E2E-019
+  - URNBuilder.acceptance("maintain-ux", "C004", "E2E", "019", "user-connection") -> acc:maintain-ux:C004-E2E-019-user-connection
+  counter_examples:
+  - acc:authenticate-user:001:AC-EXEC-201  (legacy format acc:{wagon}:{nnn}:{acceptance_id} — being migrated)
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: acceptance_urn
+  label: Acceptance URN
+  text: the canonical id of an acceptance.
+  values:
+    pattern: ^acc:[a-z][a-z0-9-]*:[DLPCEMYRK][0-9]{3}-(UNIT|HTTP|EVENT|WS|E2E|A11Y|VIS|METRIC|JOB|DB|SEC|LOAD|SCRIPT|WIDGET|GOLDEN|BLOC|INTEGRATION|RLS|EDGE|REALTIME|STORAGE|SMOKE)-[0-9]{3}(?:-[a-z0-9-]+)?$
+    parts:
+      wagon: kebab-case wagon
+      wmbt_id: step code + seq (C004)
+      harness: UPPERCASE harness code
+      NNN: per-harness 001-999
+      slug: optional kebab descriptor

package/planner-nodes/nodes/planner.acceptance.well-formed.convention.yaml

@@ -0,0 +1,57 @@
+schema_version: 1.0.0
+rule_id: planner.acceptance.well-formed
+kind: rule
+status: active
+name: Acceptance is well-formed
+statement: Each acceptance criterion has Given/When/Then prose and a verifiable outcome.
+rationale: An acceptance whose narrative is missing, empty, or states no assertable
+  outcome cannot be turned into a test, so the WMBT it belongs to is unverifiable
+  in practice while appearing covered on paper.
+terms:
+- term_id: given_when_then
+  text: structured prose stating preconditions, the trigger action, and the expected
+    observable outcomes.
+- term_id: verifiable_outcome
+  text: an outcome a generated test can assert; a bare placeholder token (TBD, TODO,
+    N/A) is not one.
+notes: "Local shape only. This says nothing about whether a WMBT's acceptance SET\
+  \ is complete \u2014 that floor is planner.coverage.every-wmbt-must-have. The former\
+  \ name (planner.acceptance.complete) overstated the guarantee, which is why it was\
+  \ renamed; the old id is retained as an alias."
+implementation:
+  type: validator
+  ref: conventions/presence/test_acceptance_well_formed::test_fault_injection_missing_gwt_prose_is_caught
+source:
+  legacy_path: src/atdd/planner/conventions/acceptance.convention.yaml
+  legacy_section: rules
+  legacy_rule_id: planner.acceptance.complete
+  legacy_sha: 027e2d86ff127550
+  extraction_mode: high_fidelity
+metadata:
+  aliases:
+  - planner.acceptance.complete
+  - PLANNER-ACCEPTANCE-COMPLETE-001
+  severity: 3
+  disposition: strict
+  introduced_in: 1.67.0
+parity:
+  source_fragments_preserved: true
+  examples_preserved: false
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-07-19'
+validation:
+  family: presence
+  template: required_field_presence
+  variant: acceptance_well_formed
+  phase: CONFIRM
+  enforcement: confirm-blocking
+  subject_kind: acceptance
+  selector: every acceptance declared under a wmbt node
+  traversal: wmbt -> acceptances[] -> given/when/then.abstract
+  invariant: given/when/then abstract prose is present and non-empty, and at least
+    one then line states a verifiable outcome
+  failure_evidence:
+  - node_id
+  - missing_field
+  - node_location

package/planner-nodes/nodes/planner.appendix.llm-guidelines.convention.yaml

@@ -0,0 +1,81 @@
+schema_version: 1.1.0
+rule_id: planner.appendix.llm-guidelines
+kind: rule
+status: active
+name: 'Appendix: Llm Guidelines'
+statement: When creating outputs the planner agent detects, reads, analyzes-by-type,
+  and references appendices to enrich outputs; during disambiguation it reads appendices
+  to ask grounded clarification questions instead of abstract ones.
+implementation:
+  type: none
+source:
+  legacy_path: src/atdd/planner/conventions/appendix.convention.yaml
+  legacy_section: llm-guidelines
+  extraction_mode: high_fidelity
+content:
+  summary: Appendices only reduce ambiguity if the planner agent actually consumes
+    them — both to enrich generated artifacts and to ground routing questions in concrete
+    content.
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: true
+  fix_hint_preserved: true
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: during_creation
+  text: 'How the planner agent processes appendices when creating outputs: detect,
+    read multimodally, analyze by type, enrich the output, and reference the appendix
+    in the manifest.'
+  values:
+    workflow:
+    - step: Detect appendix in user input
+      pattern: User includes file path, mentions 'appendix:', or provides file URL
+    - step: Use Read tool to consume appendix content
+      capability: Claude can read PNG, JPG, SVG, PDF, audio, video as multimodal input
+    - step: Analyze appendix based on type
+      analysis:
+        mockup: Identify UI components, layouts, flows, states, interactions, responsive
+          variants
+        spreadsheet: Extract business rules, calculations, data models, validation
+          constraints
+        document: Extract requirements, constraints, specifications, acceptance criteria
+        diagram: Understand architecture, entities, sequences, state transitions,
+          relationships
+        audio: Transcribe and extract user pain points, requirements, context, clarifications
+        video: Analyze workflows, interactions, pain points, existing behavior patterns
+    - step: Enrich output with extracted context
+      enrichment:
+        wagon: More accurate description, domain model informed by diagrams/docs
+        wmbt: Better when/must/then statements informed by flows/interactions
+        acceptance: Accurate harness selection (mockup->visual, diagram->integration)
+        feature: Better component clustering based on mockup sections
+        component: Accurate props/state/behavior from mockups and diagrams
+    - step: Reference appendix in manifest
+      note: Manifest structure defined in schema, not convention
+- term_id: during_disambiguation
+  text: 'How appendices help the planner agent ask better clarifying questions during
+    routing: read the appendix, then ask a grounded question referencing the concrete
+    artifact.'
+  values:
+    scenario: User provides appendix without clear intent keyword (no 'wagon', 'wmbt',
+      etc.)
+    workflow:
+    - step: LLM uses Read tool to view appendix
+      analysis: Understand what the appendix shows (multi-screen flow, single component,
+        architecture, etc.)
+    - step: Ask grounded clarification question
+      examples:
+      - input: mockup showing 3-screen checkout flow
+        question: I see your mockup shows a multi-screen checkout flow. What would
+          you like to create?
+      - input: ERD diagram with 5 entities
+        question: Your ERD shows 5 entities. Are you creating a new wagon, adding
+          a feature, or defining component data structures?
+    benefit: Questions grounded in concrete artifact reduce confusion and back-and-forth
+  examples:
+    positive:
+    - I see your mockup shows a login form - are you creating a wagon or adding a
+      feature?
+    negative:
+    - 'What do you want to build?  # abstract question that ignores the provided appendix'