@afokapu/atdd-bun 0.1.0

package/planner-nodes/nodes/planner.feature.verb-selection-by-artifact-type.convention.yaml

@@ -0,0 +1,264 @@
+schema_version: 1.1.0
+rule_id: planner.feature.verb-selection-by-artifact-type
+kind: family
+status: active
+name: Verb selection by artifact type
+statement: The artifact type (event, state, data, config) determines the appropriate
+  verbs for the feature name.
+terms:
+- term_id: verbs_by_type
+  label: Verbs by artifact type
+  text: artifact type -> verbs.
+  values:
+    events:
+    - publish
+    - emit
+    - start
+    - close
+    - trigger
+    - notify
+    states:
+    - track
+    - monitor
+    - maintain
+    - update
+    - manage
+    data:
+    - create
+    - manage
+    - process
+    - handle
+    - make
+    - generate
+    configs:
+    - configure
+    - setup
+    - initialize
+    - define
+    - establish
+  examples:
+    positive:
+    - match:started -> start-match
+    - session:active -> maintain-session
+    - player:profile -> manage-profile
+    - match:config -> configure-match
+- term_id: additional_verbs
+  label: Verb-object enforcement allowlist
+  text: "The explicit allowlist of leading verbs a planner artifact slug may use,\
+    \ beyond the by_artifact_type suggestion verbs. planner.feature.name-is-verb-object\
+    \ and planner.wagon.name-is-verb-object accept a slug iff its leading token is\
+    \ in the union of this allowlist and verbs_by_type. The suggestion table alone\
+    \ is insufficient as an enforcement basis \u2014 it rejects even the convention's\
+    \ own examples (#1276)."
+  values:
+    additional_verbs:
+    - admit
+    - aggregate
+    - allocate
+    - annotate
+    - apply
+    - archive
+    - assign
+    - attach
+    - authenticate
+    - author
+    - bind
+    - bootstrap
+    - bridge
+    - broadcast
+    - build
+    - calculate
+    - cancel
+    - capture
+    - check
+    - classify
+    - collect
+    - commit
+    - compare
+    - compose
+    - compute
+    - connect
+    - consolidate
+    - convert
+    - copy
+    - correct
+    - count
+    - credit
+    - decode
+    - decommission
+    - delegate
+    - deliver
+    - deploy
+    - derive
+    - describe
+    - detach
+    - detect
+    - disable
+    - discover
+    - dispatch
+    - download
+    - drive
+    - elicit
+    - enable
+    - encode
+    - enforce
+    - enrich
+    - ensure
+    - escalate
+    - estimate
+    - evaluate
+    - expire
+    - export
+    - expose
+    - extract
+    - fetch
+    - filter
+    - finalize
+    - fix
+    - flush
+    - forward
+    - freeze
+    - gather
+    - govern
+    - guard
+    - hydrate
+    - implement
+    - import
+    - index
+    - inject
+    - inspect
+    - integrate
+    - invoke
+    - isolate
+    - judge
+    - launch
+    - link
+    - lint
+    - list
+    - load
+    - lock
+    - log
+    - map
+    - mark
+    - match
+    - measure
+    - mediate
+    - merge
+    - migrate
+    - mint
+    - normalize
+    - observe
+    - open
+    - orchestrate
+    - parse
+    - partition
+    - pause
+    - persist
+    - ping
+    - place
+    - plan
+    - poll
+    - populate
+    - post
+    - prepare
+    - preview
+    - prioritize
+    - produce
+    - project
+    - promote
+    - prompt
+    - propagate
+    - provision
+    - prune
+    - pull
+    - purge
+    - push
+    - queue
+    - rank
+    - read
+    - rebuild
+    - reconcile
+    - record
+    - redirect
+    - refine
+    - refresh
+    - register
+    - reject
+    - release
+    - reload
+    - remove
+    - rename
+    - render
+    - replay
+    - replicate
+    - report
+    - request
+    - resolve
+    - respond
+    - restore
+    - resume
+    - retrieve
+    - retry
+    - review
+    - revoke
+    - rollback
+    - route
+    - run
+    - sample
+    - save
+    - scaffold
+    - scan
+    - schedule
+    - score
+    - search
+    - seed
+    - select
+    - send
+    - serve
+    - show
+    - sign
+    - simulate
+    - snapshot
+    - spawn
+    - split
+    - stop
+    - store
+    - stream
+    - submit
+    - subscribe
+    - summarize
+    - surface
+    - suspend
+    - swap
+    - sync
+    - tag
+    - teardown
+    - throttle
+    - toggle
+    - trace
+    - transform
+    - translate
+    - trim
+    - tune
+    - unlock
+    - unsubscribe
+    - upgrade
+    - upload
+    - validate
+    - verify
+    - visualize
+    - warn
+    - watch
+    - wire
+    - wrap
+source:
+  legacy_path: src/atdd/planner/conventions/feature.convention.yaml
+  legacy_section: artifact_seeds.verb_selection.by_artifact_type
+  legacy_sha: 4a95544261fb9541
+  extraction_mode: high_fidelity
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'

package/planner-nodes/nodes/planner.feature.wagon-link.convention.yaml

@@ -0,0 +1,27 @@
+schema_version: 1.1.0
+rule_id: planner.feature.wagon-link
+kind: rule
+status: active
+name: Feature wagon link
+statement: Each feature is registered under exactly one wagon's _features.yaml manifest.
+source:
+  legacy_path: src/atdd/planner/conventions/feature.convention.yaml
+  legacy_section: rules
+  legacy_sha: 4a95544261fb9541
+  extraction_mode: high_fidelity
+  legacy_rule_id: planner.feature.wagon-link
+metadata:
+  aliases:
+  - PLANNER-FEATURE-WAGON-LINK-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: wagon_manifest
+  text: the wagon's _features.yaml that lists its features.

package/planner-nodes/nodes/planner.interface.api-mapping.convention.yaml

@@ -0,0 +1,70 @@
+schema_version: 1.1.0
+rule_id: planner.interface.api-mapping
+kind: rule
+status: active
+name: 'Interface: Api Mapping'
+statement: Artifact names map to REST API endpoints of the form /{domain}s/{id}/{resource}[/{category}],
+  with the resource term selecting the HTTP verb (POST/GET/PUT/DELETE) and category
+  facets adding path segments.
+implementation:
+  type: none
+source:
+  legacy_path: src/atdd/planner/conventions/interface.convention.yaml
+  legacy_sha: sha256:3415a521b5eec18b
+  extraction_mode: high_fidelity
+  legacy_section: api-mapping
+content:
+  summary: A deterministic artifact-to-REST mapping lets external consumers address
+    wagon artifacts over HTTP, and choosing the verb from the resource keyword keeps
+    the API surface consistent with the artifact's lifecycle semantics.
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: true
+  fix_hint_preserved: true
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: endpoint_pattern
+  label: REST endpoint pattern
+  text: Artifact names map to REST API endpoints for external consumption following
+    /{domain}s/{id}/{resource}[/{category}]. Category facets add path segments.
+  values:
+    pattern: /{domain}s/{id}/{resource}[/{category}]
+    description: Artifact names map to REST API endpoints for external consumption.
+      Category facets add path segments.
+  examples:
+    positive:
+    - ux:foundations -> GET /uxs/{id}/foundations
+    - ux:foundations.colors -> GET /uxs/{id}/foundations/colors
+    - match:result -> GET /matches/{id}/result
+    - session:new -> POST /sessions
+    - player:identity -> GET /players/{id}
+- term_id: verb_mapping
+  label: Resource-keyword to HTTP verb table
+  text: The resource keyword selects the HTTP method. Creation keywords map to POST,
+    read keywords to GET, mutation keywords to PUT, and removal keywords to DELETE.
+  values:
+    POST:
+    - new
+    - created
+    - registered
+    - started
+    GET:
+    - result
+    - active
+    - config
+    - events
+    - foundations
+    PUT:
+    - updated
+    - closed
+    - completed
+    DELETE:
+    - terminated
+    - deleted
+  examples:
+    positive:
+    - 'session:new -> POST /sessions  # new -> POST'
+    - 'match:result -> GET /matches/{id}/result  # result -> GET'
+    negative:
+    - 'session:closed mapped to POST  # closed -> PUT, not POST'

package/planner-nodes/nodes/planner.interface.artifact-transformation.convention.yaml

@@ -0,0 +1,103 @@
+schema_version: 1.1.0
+rule_id: planner.interface.artifact-transformation
+kind: rule
+status: active
+name: 'Interface: Artifact Transformation'
+statement: Produce/consume artifacts (WHAT) seed feature names (HOW) by combining
+  a verb with the domain or resource - {verb}-{domain} when the domain is the focus,
+  {verb}-{resource} when the resource is the focus - with verb choice driven by the
+  artifact type (event, state, data, or config).
+implementation:
+  type: none
+source:
+  legacy_path: src/atdd/planner/conventions/interface.convention.yaml
+  legacy_sha: sha256:3415a521b5eec18b
+  extraction_mode: high_fidelity
+  legacy_section: artifact-transformation
+content:
+  summary: Artifacts describe WHAT is produced/consumed (entities, states, events)
+    while features describe HOW to work with them (actions, capabilities). A consistent
+    transformation makes feature names derivable from artifacts so the plan stays
+    coherent.
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: true
+  fix_hint_preserved: true
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: object_rules
+  label: Domain-as-object vs resource-as-object
+  text: 'Two transformation rules: {verb}-{domain} when the domain is the primary
+    focus (feature acts on the entire domain), and {verb}-{resource} when the resource
+    is the primary focus (feature acts on a specific resource within the domain).'
+  values:
+    domain_as_object_pattern: '{verb}-{domain}'
+    domain_as_object_when: Domain is the primary focus of the feature
+    domain_as_object_rationale: Feature acts on the entire domain
+    resource_as_object_pattern: '{verb}-{resource}'
+    resource_as_object_when: Resource is the primary focus of the feature
+    resource_as_object_rationale: Feature acts on specific resource within domain
+- term_id: events_transformation
+  label: Events -> features
+  text: Past-tense artifacts (ended, started, closed) use verbs like publish, emit,
+    start, close, trigger.
+  values:
+    description: Past tense artifacts (ended, started, closed)
+    typical_verbs:
+    - publish
+    - emit
+    - start
+    - close
+    - trigger
+  examples:
+    positive:
+    - match:started (domain match, resource started) -> start-match
+    - session:closed (domain session, resource closed) -> close-session
+- term_id: states_transformation
+  label: States -> features
+  text: Adjective artifacts (remaining, active, current) use verbs like track, monitor,
+    maintain, update.
+  values:
+    description: Adjective artifacts (remaining, active, current)
+    typical_verbs:
+    - track
+    - monitor
+    - maintain
+    - update
+  examples:
+    positive:
+    - mechanic:timebank.remaining (domain timebank, resource remaining) -> track-timebank
+    - session:active (domain session, resource active) -> maintain-session
+- term_id: data_transformation
+  label: Data -> features
+  text: Noun artifacts (choice, identity, profile) use verbs like create, manage,
+    process, handle, make.
+  values:
+    description: Noun artifacts (choice, identity, profile)
+    typical_verbs:
+    - create
+    - manage
+    - process
+    - handle
+    - make
+  examples:
+    positive:
+    - 'mechanic:decision.choice (domain decision, resource choice) -> make-choice  #
+      verb make + resource choice'
+    - player:identity (domain player, resource identity) -> identify-player
+- term_id: configs_transformation
+  label: Configs -> features
+  text: Configuration artifacts (config, settings, agreement) use verbs like configure,
+    setup, initialize, define.
+  values:
+    description: Configuration artifacts (config, settings, agreement)
+    typical_verbs:
+    - configure
+    - setup
+    - initialize
+    - define
+  examples:
+    positive:
+    - match:config (domain match, resource config) -> configure-match
+    - league:config (domain league, resource config) -> define-league

package/planner-nodes/nodes/planner.interface.contract-urn.convention.yaml

@@ -0,0 +1,119 @@
+schema_version: 1.1.0
+rule_id: planner.interface.contract-urn
+kind: rule
+status: active
+name: 'Interface: Contract Urn'
+statement: Wagon artifacts carry a stable URN of the form contract:{domain}:{resource}[.{category}]
+  that links the artifact to its contract independently of contract version, and the
+  graph maintains bidirectional linkage between wagon URNs and contract IDs.
+implementation:
+  type: none
+source:
+  legacy_path: src/atdd/planner/conventions/interface.convention.yaml
+  legacy_sha: sha256:3415a521b5eec18b
+  extraction_mode: high_fidelity
+  legacy_section: contract-urn
+content:
+  summary: URNs decouple wagon artifacts from contract versioning. URNs remain stable
+    while contract versions evolve (v1->v2) without requiring wagon YAML changes;
+    wagons declare WHAT (URN) while contracts define HOW (version, schema, API). This
+    loose coupling keeps domain language human-readable and free of version noise.
+  examples:
+  - 'mechanic:decision.choice -> contract:mechanic:decision.choice  # category preserved
+    as dot facet'
+  counter_examples:
+  - 'contract:mechanic.decision.choice  # legacy dot-for-hierarchy -> contract:mechanic:decision.choice'
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: true
+  fix_hint_preserved: true
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: urn_pattern
+  label: The contract URN format
+  text: A contract URN is contract:{domain}:{resource}[.{category}]. Domain is the
+    first part of the artifact name (before the first colon); resource is the second
+    part (after the first colon, before the dot if present); category is the optional
+    third part (after the dot). The colon is kept for hierarchy (domain:resource)
+    and the category is preserved as a dot facet when present.
+  values:
+    format: contract:{domain}:{resource}[.{category}]
+    domain: First part of artifact name (before first colon)
+    resource: Second part of artifact name (after first colon, before dot if present)
+    category: Optional third part (after dot)
+    conversion_rule: Keep colon for hierarchy (domain:resource); preserve category
+      as dot facet when present
+  examples:
+    positive:
+    - ux:foundations -> contract:ux:foundations
+    - ux:foundations.colors -> contract:ux:foundations.colors
+    - mechanic:decision.choice -> contract:mechanic:decision.choice
+    - match:result -> contract:match:result
+    - player:identity -> contract:player:identity
+- term_id: wagon_artifact_urn
+  label: URN field on wagon produce/consume entries
+  text: Artifacts in wagon YAML manifests (plan/{wagon}/*.yaml) carry an urn field
+    added to each produce/consume entry, linking the wagon artifact to a contract
+    without version coupling.
+  values:
+    urn_field: urn
+    location: Added to each produce/consume entry
+    purpose: Links wagon artifact to contract without version coupling
+  examples:
+    positive:
+    - 'maintain-ux produce: name ux:foundations, urn contract:ux:foundations, to external'
+    - 'maintain-ux produce: name ux:foundations.colors, urn contract:ux:foundations.colors,
+      to external'
+    - 'stage-characters consume: name ux:foundations, urn contract:ux:foundations,
+      from wagon:maintain-ux'
+- term_id: contract_artifact_id
+  label: Contract definition ID with version
+  text: Contract definitions in contracts/_artifacts.yaml carry an id of the form
+    {domain}:{resource}[.{category}]:v{version} as the authoritative source for schema,
+    version and API. A version-agnostic URN contract:{domain}:{resource}[.{category}]
+    maps to any version of the matching id.
+  values:
+    id_field: 'id: {domain}:{resource}[.{category}]:v{version}'
+    purpose: Authoritative source for contract schema, version, API
+    urn_mapping: URN contract:{domain}:{resource}[.{category}] maps to any version
+      of id {domain}:{resource}[.{category}]:v*
+  examples:
+    positive:
+    - id ux:foundations:v1 (version 1.0.0, path ux/foundations.json, producer wagon:maintain-ux)
+      matches urn contract:ux:foundations
+    - id ux:foundations.colors:v1 matches urn contract:ux:foundations.colors (category
+      preserved in both URN and ID)
+- term_id: bidirectional_linkage
+  label: Wagon<->contract linkage
+  text: Wagon URN resolves to a Contract ID via domain.resource matching, and a contract
+    producer field resolves back to a wagon name. A URN must resolve to a contract
+    in the registry.
+  values:
+    wagon_to_contract: Wagon URN -> Contract ID lookup via domain.resource matching
+    contract_to_wagon: Contract producer field -> Wagon name
+    validation: URN must resolve to contract in registry
+- term_id: urn_purpose
+  label: Why URNs exist
+  text: URNs decouple wagon artifacts from contract versioning so URNs stay stable
+    while contract versions evolve, separating WHAT (URN) from HOW (version, schema,
+    API) and keeping names human-readable.
+  values:
+    rationale: Decouple wagon artifacts from contract versioning
+    stability: URNs remain stable while contract versions evolve
+    separation_of_concerns: Wagons declare WHAT (URN), contracts define HOW (version,
+      schema, API)
+    loose_coupling: Contract evolution (v1->v2) doesn't require wagon YAML changes
+    human_readable: Clear domain language without version noise
+- term_id: legacy_urn_migration
+  label: Legacy URN separator refactor
+  text: Legacy URNs of the form contract:{domain}.{resource} migrate to contract:{domain}:{resource};
+    the category stays as a dot facet, i.e. contract:{domain}:{resource}.{category}.
+    The URN field is optional initially but required for new wagons.
+  values:
+    refactor_note: 'Legacy URNs contract:{domain}.{resource} -> contract:{domain}:{resource};
+      category stays as a dot facet: contract:{domain}:{resource}.{category}'
+    backward_compatibility: URN field optional initially, required for new wagons
+    phase1: Add urn field to all wagon artifacts (this upgrade)
+    phase2: Validate all URNs resolve to contracts
+    phase3: Generate missing contracts for orphaned URNs

package/planner-nodes/nodes/planner.interface.naming-patterns.convention.yaml

@@ -0,0 +1,73 @@
+schema_version: 1.1.0
+rule_id: planner.interface.naming-patterns
+kind: rule
+status: active
+name: 'Interface: Naming Patterns'
+statement: Produce and consume artifacts are named domain:activity-verb for signals/events
+  and domain:data-noun for state/data, where events are past-tense verbs, state is
+  nouns/adjectives, and collections are plural.
+implementation:
+  type: none
+source:
+  legacy_path: src/atdd/planner/conventions/interface.convention.yaml
+  legacy_sha: sha256:3415a521b5eec18b
+  extraction_mode: high_fidelity
+  legacy_section: naming-patterns
+content:
+  summary: A consistent produce/consume naming convention makes an artifact's nature
+    (event vs state vs collection) legible from its name alone, so consumers know
+    whether they are reacting to a signal or reading data.
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: true
+  fix_hint_preserved: true
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: naming_convention
+  label: Event vs state vs collection naming
+  text: Events = past tense verbs; State = nouns/adjectives; Collections = plural.
+    Use domain:activity-verb for signals/events (e.g. match:started, pacing:exhausted)
+    and domain:data-noun for state/data (e.g. player:identity, match:config).
+  values:
+    naming_convention: Events = past tense verbs, State = nouns/adjectives, Collections
+      = plural
+    signal_event_pattern: domain:activity-verb (e.g. match:started, pacing:exhausted)
+    state_data_pattern: domain:data-noun (e.g. player:identity, match:config)
+  examples:
+    positive:
+    - 'match:started  # activity-verb pattern for signal'
+    - 'pacing:exhausted  # activity-verb signal'
+    - 'player:identity  # data-noun pattern for state'
+    - 'match:config  # data-noun state'
+- term_id: produce_naming
+  label: Produce-side naming
+  text: The produce block lists artifacts this wagon creates and owns, each an array
+    entry {name 'domain:artifact-name', to 'internal|external'} with visibility specified
+    via 'to'. Naming follows domain:activity-verb for signals/events and domain:data-noun
+    for state/data.
+  values:
+    prompt: 'What artifacts does this wagon create and own? Specify visibility with
+      ''to''. Follow naming pattern: domain:activity-verb for signals/events, domain:data-noun
+      for state/data'
+    pattern: 'array of {name: ''domain:artifact-name'', to: ''internal|external''}'
+  examples:
+    positive:
+    - 'decision:chosen, to external  # data-noun pattern'
+    - 'match:started, to external  # activity-verb pattern for signal'
+    - 'player:identity, to external  # data-noun pattern for state'
+- term_id: consume_naming
+  label: Consume-side naming
+  text: The consume block lists artifacts this wagon consumes, each an array entry
+    {name 'domain:artifact-name', from 'wagon:slug|system:external|internal'}. Naming
+    follows domain:activity-verb for signals/events and domain:data-noun for state/data.
+  values:
+    prompt: 'What artifacts does this wagon consume? Follow naming pattern: domain:activity-verb
+      for signals/events, domain:data-noun for state/data'
+    pattern: 'array of {name: ''domain:artifact-name'', from: ''wagon:slug|system:external|internal''}'
+  examples:
+    positive:
+    - 'match:dilemma.current, from wagon:pace-dilemmas  # data-noun'
+    - 'time:remaining, from wagon:burn-timebank  # data-noun'
+    - 'match:started, from wagon:play-match  # activity-verb signal'
+    - 'player:identity, from system:external  # data-noun from external train'

package/planner-nodes/nodes/planner.interface.orphan-detection.convention.yaml

@@ -0,0 +1,46 @@
+schema_version: 1.1.0
+rule_id: planner.interface.orphan-detection
+kind: constraint
+status: active
+name: 'Interface: Orphan Detection'
+statement: A wagon artifact URN that has no matching contract in the registry is a
+  violation (an orphaned URN).
+implementation:
+  type: none
+source:
+  legacy_path: src/atdd/planner/conventions/interface.convention.yaml
+  legacy_sha: sha256:3415a521b5eec18b
+  extraction_mode: high_fidelity
+  legacy_section: orphan-detection
+content:
+  summary: URNs are the bidirectional link between wagon artifacts and contracts.
+    A URN that resolves to no contract breaks that linkage, leaving the artifact's
+    schema, version and API undefined; orphan detection surfaces these gaps so missing
+    contracts can be generated.
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: true
+  fix_hint_preserved: true
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: orphan_violation
+  label: Orphaned URN definition
+  text: A wagon URN without a matching contract in the registry is a violation. The
+    URN must resolve to a contract; an unresolved URN is an orphan.
+  values:
+    orphan_detection: Wagon URN without matching contract = violation
+    validation: URN must resolve to contract in registry
+  examples:
+    positive:
+    - 'contract:ux:foundations resolves to id ux:foundations:v1  # linked, not orphan'
+    negative:
+    - 'contract:ux:phantom with no contract id ux:phantom:v* in registry  # orphan
+      = violation'
+- term_id: orphan_remediation
+  label: Resolving orphaned URNs
+  text: Orphaned URNs are remediated by generating the missing contracts for them
+    (migration phase3), after first validating that all URNs resolve (phase2).
+  values:
+    phase2: Validate all URNs resolve to contracts
+    phase3: Generate missing contracts for orphaned URNs