@afokapu/atdd-bun 0.1.0

package/planner-nodes/nodes/planner.appendix.naming-pattern.convention.yaml

@@ -0,0 +1,45 @@
+schema_version: 1.1.0
+rule_id: planner.appendix.naming-pattern
+kind: pattern
+status: active
+name: 'Appendix: Naming Pattern'
+statement: Appendix filenames follow the pattern {artifact-name}_{type}_{filename},
+  where type is one of the six recognized appendix types.
+implementation:
+  type: none
+source:
+  legacy_path: src/atdd/planner/conventions/appendix.convention.yaml
+  legacy_section: naming-pattern
+  extraction_mode: high_fidelity
+content:
+  summary: Encoding the owning artifact and the appendix type into the filename ensures
+    uniqueness, traceability back to the artifact, and clear type identification without
+    opening the file.
+  examples:
+  - checkout-flow_mockup_overview.png
+  - E023_diagram_sequence.svg
+  - payment-processing_spreadsheet_tax-rules.xlsx
+  - PaymentForm_mockup_states.png
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: true
+  fix_hint_preserved: true
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: naming_pattern
+  text: Appendices follow the pattern {artifact-name}_{type}_{filename}, with the
+    owning artifact name first, the appendix type second, and a descriptive filename
+    last.
+  values:
+    pattern: '{artifact-name}_{type}_{filename}'
+    rationale: Ensures uniqueness, traceability, and clear type identification
+  examples:
+    positive:
+    - 'checkout-flow_mockup_overview.png  # wagon'
+    - 'E023_diagram_sequence.svg  # wmbt'
+    - 'payment-processing_spreadsheet_tax-rules.xlsx  # feature'
+    - 'PaymentForm_mockup_states.png  # component'
+    negative:
+    - 'overview.png  # missing {artifact-name} and {type} segments'
+    - 'checkout-flow-mockup-overview.png  # uses hyphens instead of underscore separators'

package/planner-nodes/nodes/planner.appendix.storage.convention.yaml

@@ -0,0 +1,44 @@
+schema_version: 1.1.0
+rule_id: planner.appendix.storage
+kind: rule
+status: active
+name: 'Appendix: Storage'
+statement: Appendices are stored in an appendices/ subdirectory of the artifact they
+  describe, at the location matching the artifact level (wagon, wmbt, feature, or
+  component).
+implementation:
+  type: none
+source:
+  legacy_path: src/atdd/planner/conventions/appendix.convention.yaml
+  legacy_section: storage
+  extraction_mode: high_fidelity
+content:
+  summary: Co-locating appendices with what they describe keeps artifacts self-contained
+    and makes the supplementary content discoverable relative to the artifact.
+  examples:
+  - demo/wagons/checkout-flow/appendices/checkout-flow_mockup_overview.png
+  - demo/wagons/checkout-flow/plan/E023/appendices/E023_mockup_payment-error.png
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: true
+  fix_hint_preserved: true
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: storage_location
+  text: Appendices live in an appendices/ subdirectory of the artifact, with a level-specific
+    path for wagon, wmbt, feature, and component.
+  values:
+    rule: Appendices stored in appendices/ subdirectory of artifact
+    locations:
+      wagon: '{output_dir}/wagons/{wagon-name}/appendices/'
+      wmbt: '{output_dir}/wagons/{wagon-name}/plan/{wmbt-id}/appendices/'
+      feature: '{output_dir}/wagons/{wagon-name}/features/{feature-name}/appendices/'
+      component: '{output_dir}/wagons/{wagon-name}/features/{feature-name}/components/{component-name}/appendices/'
+  examples:
+    positive:
+    - demo/wagons/checkout-flow/appendices/checkout-flow_mockup_overview.png
+    - demo/wagons/checkout-flow/plan/E023/appendices/E023_mockup_payment-error.png
+    negative:
+    - 'demo/wagons/checkout-flow/checkout-flow_mockup_overview.png  # not in an appendices/
+      subdirectory'

package/planner-nodes/nodes/planner.appendix.structure.convention.yaml

@@ -0,0 +1,17 @@
+schema_version: 1.0.0
+rule_id: planner.appendix.structure
+kind: rule
+status: active
+statement: Appendix sections follow the documented heading order and link back to
+  the main wagon body.
+rationale: A fixed appendix heading order and back-links keep large wagon documents
+  navigable and auditable.
+terms:
+- term_id: appendix_section
+  text: a supplementary section of a wagon document
+- term_id: heading_order
+  text: the documented sequence the appendix headings must follow
+metadata:
+  severity: 1
+  disposition: documentation-only
+  introduced_in: 1.67.0

package/planner-nodes/nodes/planner.appendix.types.convention.yaml

@@ -0,0 +1,123 @@
+schema_version: 1.1.0
+rule_id: planner.appendix.types
+kind: pattern
+status: active
+name: 'Appendix: Types'
+statement: An appendix is one of six recognized types — mockup, spreadsheet, document,
+  diagram, audio, or video — each with its own file extensions and intended use during
+  wagon/wmbt/feature/component/acceptance creation.
+implementation:
+  type: none
+source:
+  legacy_path: src/atdd/planner/conventions/appendix.convention.yaml
+  legacy_section: types
+  extraction_mode: high_fidelity
+content:
+  summary: A fixed appendix taxonomy lets the planner agent recognize supplementary
+    content, choose the right multimodal reading strategy, and map each artifact to
+    the planner output it enriches.
+  examples:
+  - checkout-flow_mockup_payment-form.png
+  - pricing_spreadsheet_tax-calculations.xlsx
+  - auth_diagram_sequence.svg
+  counter_examples:
+  - 'notes.png  # missing artifact-name and type segments'
+  - 'auth_screenshot_login.png  # ''screenshot'' is not a recognized appendix type'
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: true
+  fix_hint_preserved: true
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: mockup
+  text: Visual designs, UI mockups, wireframes, prototypes that inform component structure
+    and harness selection.
+  values:
+    extensions:
+    - PNG
+    - JPG
+    - JPEG
+    - SVG
+    - GIF
+    use_cases:
+    - UI screen designs to inform component structure during feature decomposition
+    - User flow diagrams to inform WMBT decomposition and when/must/then statements
+    - Visual states (loading, error, success) to inform harness selection (visual,
+      e2e)
+    - Responsive variants (mobile, tablet, desktop) to inform acceptance criteria
+    example: checkout-flow_mockup_payment-form.png
+- term_id: spreadsheet
+  text: Data models, calculations, business rules, requirements matrices that inform
+    domain model and acceptance criteria.
+  values:
+    extensions:
+    - XLSX
+    - CSV
+    - TSV
+    use_cases:
+    - Complex pricing/tax calculation logic to inform domain model and business rules
+    - Data validation rules to inform acceptance criteria
+    - Requirement traceability matrices for feature clustering
+    - Test data sets for acceptance given/when sections
+    example: pricing_spreadsheet_tax-calculations.xlsx
+- term_id: document
+  text: Specifications, research findings, technical guides, PRDs that inform wagon
+    description and component contracts.
+  values:
+    extensions:
+    - PDF
+    - DOCX
+    - MD
+    - TXT
+    use_cases:
+    - Product requirements documents to inform wagon description and scope
+    - Technical specifications to inform component contracts and responsibilities
+    - User research findings to inform WMBT scenarios and pain points
+    - API documentation to inform integration acceptance criteria
+    example: auth_document_security-spec.pdf
+- term_id: diagram
+  text: Architecture diagrams, ERDs, sequence diagrams, flowcharts, state machines
+    that inform 4-layer structure and integration points.
+  values:
+    extensions:
+    - PNG
+    - SVG
+    - MERMAID
+    - DRAWIO
+    use_cases:
+    - System architecture diagrams to inform 4-layer structure and component boundaries
+    - Entity-relationship diagrams for domain model and data structures
+    - Sequence diagrams to inform WMBT when/then steps and integration points
+    - State machine diagrams for component behavior and state transitions
+    example: auth_diagram_sequence.svg
+- term_id: audio
+  text: User interviews, voice notes, recorded requirements sessions that inform WMBT
+    scenarios and pain points.
+  values:
+    extensions:
+    - MP3
+    - WAV
+    - M4A
+    - OGG
+    use_cases:
+    - User interview recordings for extracting pain points and requirements
+    - Stakeholder requirement sessions for wagon scope and priorities
+    - Voice memos with context and clarifications
+    - Accessibility testing feedback for a11y harness criteria
+    example: user-research_audio_interview-checkout.mp3
+- term_id: video
+  text: Screen recordings, demos, walkthroughs, user testing sessions that inform
+    feature parity and reproduce steps.
+  values:
+    extensions:
+    - MP4
+    - MOV
+    - WEBM
+    - AVI
+    use_cases:
+    - Demo of existing system behavior to inform feature parity requirements
+    - User testing sessions showing pain points and interaction patterns
+    - Tutorial videos for understanding complex workflows
+    - Screen recordings of bugs to inform WMBT reproduce steps
+    example: checkout_video_user-session.mp4

package/planner-nodes/nodes/planner.artifact-naming.anti-patterns.convention.yaml

@@ -0,0 +1,31 @@
+schema_version: 1.1.0
+rule_id: planner.artifact-naming.anti-patterns
+kind: anti_pattern
+status: active
+name: Naming anti-patterns
+statement: Avoid the catalogued artifact-naming anti-patterns (wrong separator, missing theme, over-specification,
+  generic aspect, theme repeated in aspect).
+source:
+  legacy_path: src/atdd/planner/conventions/artifact-naming.convention.yaml
+  legacy_section: anti_patterns
+  legacy_sha: eca68a67c92694c9
+  extraction_mode: high_fidelity
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: anti_pattern
+  label: Anti-patterns
+  text: bad name -> why -> fix.
+  values:
+    wrong_separator_for_hierarchy: 'commons:ux.foundations.color -> use colons: commons:ux:foundations:color'
+    wrong_separator_for_variant: 'sensory:gesture:raw -> use dot: sensory:gesture.raw'
+    missing_theme: 'gesture.raw -> add theme: sensory:gesture.raw'
+    too_many_dots: commons:identifiers.uuid.v7.timestamp.encoded -> commons:identifiers.uuid (internals
+      stay internal)
+    unnecessary_hierarchy: match:config:base:standard -> match:config
+    generic_aspect: match:data -> match:state.committed (specific)
+    theme_in_aspect: sensory:sensory-feedback.visual -> sensory:feedback.visual

package/planner-nodes/nodes/planner.artifact-naming.cardinality-from-aspect.convention.yaml

@@ -0,0 +1,32 @@
+schema_version: 1.1.0
+rule_id: planner.artifact-naming.cardinality-from-aspect
+kind: rule
+status: active
+name: Cardinality from the aspect
+statement: 'The ASPECT (final noun before variant) determines cardinality: a plural aspect indicates a
+  collection/array; a singular aspect indicates one item. Categories and variants do not affect cardinality.'
+source:
+  legacy_path: src/atdd/planner/conventions/artifact-naming.convention.yaml
+  legacy_section: cardinality_semantics
+  legacy_sha: eca68a67c92694c9
+  extraction_mode: high_fidelity
+content:
+  examples:
+  - scenario:fragments -> plural aspect -> collection
+  - scenario:fragment -> singular aspect -> one item
+  - commons:ux:foundations:color -> 'foundations' is a category, 'color' singular -> one item
+  - commons:ux:foundations:colors -> 'colors' plural -> array of colors
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: cardinality
+  text: single-item vs collection, decided by the aspect's plurality.
+  values:
+    singular_aspect: single item schema
+    plural_aspect: collection/array schema or directory of items
+    category_position: does NOT affect cardinality
+    variant_position: does NOT affect cardinality

package/planner-nodes/nodes/planner.artifact-naming.colon-for-hierarchy.convention.yaml

@@ -0,0 +1,25 @@
+schema_version: 1.1.0
+rule_id: planner.artifact-naming.colon-for-hierarchy
+kind: rule
+status: active
+name: Colon for hierarchical descent
+statement: 'Use a colon for hierarchical descent: different conceptual levels, navigating deeper, general->specific,
+  organizational subsystems.'
+source:
+  legacy_path: src/atdd/planner/conventions/artifact-naming.convention.yaml
+  legacy_section: decision_rules.when_to_use_colon
+  legacy_sha: eca68a67c92694c9
+  extraction_mode: high_fidelity
+content:
+  examples:
+  - commons:ux:foundations:color (theme->subsystem->category->item)
+  - scenario:catalog:primitives:actor (domain->collection->type->entity)
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: hierarchical_descent
+  text: moving from general to specific down the resource tree, marked by a colon.

package/planner-nodes/nodes/planner.artifact-naming.contract-file-mapping.convention.yaml

@@ -0,0 +1,26 @@
+schema_version: 1.1.0
+rule_id: planner.artifact-naming.contract-file-mapping
+kind: rule
+status: active
+name: Contract file mapping
+statement: 'An artifact path maps directly to a contract file path: theme + segments become directories,
+  the final segment becomes the filename, with a .schema.json extension.'
+source:
+  legacy_path: src/atdd/planner/conventions/artifact-naming.convention.yaml
+  legacy_section: contract_file_mapping
+  legacy_sha: eca68a67c92694c9
+  extraction_mode: high_fidelity
+content:
+  operational_guidance: 'Formula: artifact theme:seg1:seg2:aspect.variant -> contracts/theme/seg1/seg2/aspect/variant.schema.json.'
+  examples:
+  - commons:identifiers.uuid -> contracts/commons/identifiers/uuid.schema.json
+  - sensory:feedback:haptic:pulse.short -> contracts/sensory/feedback/haptic/pulse/short.schema.json
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: file_mapping
+  text: the deterministic artifact-name -> file-path transform.

package/planner-nodes/nodes/planner.artifact-naming.depth-guidelines.convention.yaml

@@ -0,0 +1,27 @@
+schema_version: 1.1.0
+rule_id: planner.artifact-naming.depth-guidelines
+kind: principle
+status: active
+name: Depth guidelines
+statement: Keep hierarchy 2-3 levels (4-5 max, sparingly) and variants shallow (0-1 dots, 2 max); each
+  separator should add clear semantic value.
+source:
+  legacy_path: src/atdd/planner/conventions/artifact-naming.convention.yaml
+  legacy_section: decision_rules.depth_guidelines
+  legacy_sha: eca68a67c92694c9
+  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: depth
+  text: the recommended nesting depth per separator.
+  values:
+    hierarchy_typical: 2-3 levels
+    hierarchy_maximum: 4-5 levels (use sparingly)
+    variant_typical: 0-1 levels
+    variant_maximum: 2 levels
+    warning: multiple dots often indicate over-specification

package/planner-nodes/nodes/planner.artifact-naming.dot-for-variant.convention.yaml

@@ -0,0 +1,25 @@
+schema_version: 1.1.0
+rule_id: planner.artifact-naming.dot-for-variant
+kind: rule
+status: active
+name: Dot for lateral variation
+statement: 'Use a dot for lateral variation: same conceptual level, different flavor/state/type/facet.'
+source:
+  legacy_path: src/atdd/planner/conventions/artifact-naming.convention.yaml
+  legacy_section: decision_rules.when_to_use_dot
+  legacy_sha: eca68a67c92694c9
+  extraction_mode: high_fidelity
+content:
+  examples:
+  - sensory:gesture.raw vs sensory:gesture.tapped
+  - player:session.active vs player:session.closed
+  - match:config.duel vs match:config.team
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: lateral_variation
+  text: a different flavor/state of the same aspect, marked by a dot.

package/planner-nodes/nodes/planner.artifact-naming.logical-physical-mapping.convention.yaml

@@ -0,0 +1,36 @@
+schema_version: 1.1.0
+rule_id: planner.artifact-naming.logical-physical-mapping
+kind: rule
+status: active
+name: Logical-to-physical mapping
+statement: 'Artifact names (logical) map to contract file paths (physical): split on : and ., each segment
+  is a directory level, the final segment is the filename.'
+source:
+  legacy_path: src/atdd/planner/conventions/artifact-naming.convention.yaml
+  legacy_section: logical_vs_physical_mapping + urn_structure
+  legacy_sha: eca68a67c92694c9
+  extraction_mode: high_fidelity
+content:
+  operational_guidance: 'segments = split(artifact, /[:.]/); path = ''contracts/'' + segments[0..-1].join(''/'');
+    file = variant ? variant+''.schema.json'' : (directory_reference ? none : aspect+''.schema.json'').'
+  examples:
+  - scenario:fragment -> contracts/scenario/fragment/fragment.schema.json (singular object)
+  - scenario:fragments -> contracts/scenario/fragments/fragments.schema.json (array schema)
+  - commons:ux:foundations -> contracts/commons/ux/foundations/ (directory reference, no file)
+  - sensory:gesture.raw -> contracts/sensory/gesture/raw.schema.json (variant becomes filename)
+  - commons:ux:foundations:color.primary -> contracts/commons/ux/foundations/color/primary.schema.json
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: physical_form
+  label: Three physical forms
+  text: how a plural/singular artifact materializes on disk.
+  values:
+    directory_reference: logical grouping, no concrete schema file (plural aspect referencing a collection
+      of related schemas)
+    array_schema: 'plural aspect with a concrete array schema ({type: array, items: $ref ../singular})'
+    singular_schema: singular aspect = single object schema

package/planner-nodes/nodes/planner.artifact-naming.migration-guide.convention.yaml

@@ -0,0 +1,29 @@
+schema_version: 1.1.0
+rule_id: planner.artifact-naming.migration-guide
+kind: principle
+status: active
+name: v1 -> v2 migration guide
+statement: Migrate legacy names to theme:hierarchy:aspect.variant by assigning a theme, separating hierarchy
+  (colons) from variants (dots), and realigning URNs, manifests, and contract files.
+source:
+  legacy_path: src/atdd/planner/conventions/artifact-naming.convention.yaml
+  legacy_section: migration_guide
+  legacy_sha: eca68a67c92694c9
+  extraction_mode: high_fidelity
+content:
+  operational_guidance: 'Steps: identify names -> determine theme -> identify hierarchy -> separate hierarchy
+    from variants -> update wagon manifests -> update feature files -> update URNs -> reorganize contracts
+    -> update $id fields.'
+  examples:
+  - identifiers:uuid -> commons:identifiers.uuid
+  - ux.foundations.color -> commons:ux:foundations:color
+  - ux.foundations.color.primary -> commons:ux:foundations:color.primary
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: migration_step
+  text: one step in the v1->v2 artifact-name migration.

package/planner-nodes/nodes/planner.artifact-naming.naming-pattern.convention.yaml

@@ -0,0 +1,44 @@
+schema_version: 1.1.0
+rule_id: planner.artifact-naming.naming-pattern
+kind: rule
+status: active
+name: Artifact naming pattern
+statement: An artifact name is {theme}(:{category})*:{aspect}(.{variant})? — theme, optional hierarchy
+  categories, a leaf aspect, and an optional variant.
+source:
+  legacy_path: src/atdd/planner/conventions/artifact-naming.convention.yaml
+  legacy_section: naming_pattern + visual_hierarchy + examples + purpose
+  legacy_sha: eca68a67c92694c9
+  extraction_mode: high_fidelity
+content:
+  normative_text: 'Visual: theme : category : subcategory : aspect . variant — colons = HIERARCHY (vertical
+    depth), dot = VARIANT (lateral facet); theme = NAMESPACE.'
+  operational_guidance: Provides semantic clarity (theme-based), namespace safety (collision-free), unlimited
+    hierarchical depth (colons), lateral variants (dots), and alignment of artifact names with contract
+    file paths.
+  examples:
+  - commons:ux:foundations:color  (theme->subsystem->category->item)
+  - commons:identifiers.uuid  (aspect + variant)
+  - commons:ux:foundations:color.primary  (deep hierarchy + variant)
+  - 'orders:checkout  (simple form: theme:aspect)'
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: name_component
+  label: Name components
+  text: the four grammar parts of an artifact name.
+  values:
+    theme: top-level architectural theme; kebab-case ^[a-z][a-z0-9-]*$; required, exactly 1
+    category: hierarchical path segment navigating down the resource tree; kebab-case; optional, 0+
+    aspect: the final leaf resource noun; kebab-case; required, exactly 1
+    variant: lateral variation/facet/state of the aspect; kebab-case; optional, typically 0-1
+  examples:
+    positive:
+    - theme=commons
+    - category=foundations
+    - aspect=color
+    - variant=primary

package/planner-nodes/nodes/planner.artifact-naming.path-mirrors-identity.convention.yaml

@@ -0,0 +1,40 @@
+schema_version: 1.0.0
+rule_id: planner.artifact-naming.path-mirrors-identity
+kind: rule
+status: active
+name: Contract path mirrors artifact identity
+statement: When a produced artifact declares a concrete contract schema file, the
+  file path must mirror the identity — every colon/dot boundary becomes a directory
+  boundary under contracts/ and the leaf is a .schema.json file
+  (contracts/{theme}/.../{aspect}.schema.json). A null contract or a
+  directory-reference physical form is out of scope; a mis-located .schema.json is
+  a violation.
+terms:
+- term_id: artifact_path_mirrors_identity
+  text: the path-mirrors-identity rule for a produced contract file
+  values:
+    mapping: split identity on ':' and '.'; segments are directories, leaf is the
+      .schema.json file
+    examples_ok:
+    - commons:identifiers.uuid -> contracts/commons/identifiers/uuid.schema.json
+    - commons:ux:foundations:color -> contracts/commons/ux/foundations/color.schema.json
+    - match:config -> contracts/match/config/config.schema.json
+    examples_bad:
+    - commons:identifiers.uuid -> contracts/commons/WRONG/uuid.schema.json
+implementation:
+  type: validator
+  ref: test_artifact_path_mirrors_identity::test_confirm_blocks_mispathed_contract
+metadata:
+  severity: 3
+  disposition: strict
+validation:
+  family: format
+  template: path_mapping
+  variant: planner_artifact_path_mirrors_identity
+  phase: CONFIRM
+  enforcement: confirm-blocking
+  subject_kind: artifact
+  failure_evidence:
+  - artifact_name
+  - contract_path
+  - reason

package/planner-nodes/nodes/planner.artifact-naming.planner-artifacts-use-stable.convention.yaml

@@ -0,0 +1,28 @@
+schema_version: 1.1.0
+rule_id: planner.artifact-naming.planner-artifacts-use-stable
+kind: rule
+status: active
+name: Stable URN-based names
+statement: Planner artifacts use stable URN-based names matching the registered grammar.
+source:
+  legacy_path: src/atdd/planner/conventions/artifact-naming.convention.yaml
+  legacy_section: rules
+  legacy_sha: eca68a67c92694c9
+  extraction_mode: high_fidelity
+  legacy_rule_id: planner.artifact-naming.planner-artifacts-use-stable
+metadata:
+  aliases:
+  - PLANNER-ARTIFACT-NAMING-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: stable_name
+  text: a URN-based artifact name that stays constant across renames/refactors and matches the registered
+    grammar.

package/planner-nodes/nodes/planner.artifact-naming.pluralization.convention.yaml

@@ -0,0 +1,27 @@
+schema_version: 1.1.0
+rule_id: planner.artifact-naming.pluralization
+kind: family
+status: active
+name: Pluralization guide
+statement: Use singular aspect for item schemas and plural aspect for collections, following English pluralization
+  rules.
+source:
+  legacy_path: src/atdd/planner/conventions/artifact-naming.convention.yaml
+  legacy_section: cardinality_semantics.pluralization_guide
+  legacy_sha: eca68a67c92694c9
+  extraction_mode: high_fidelity
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: pluralization
+  text: how to form the plural aspect.
+  values:
+    regular: add 's' (fragment->fragments, color->colors)
+    irregular: English irregular forms (analysis->analyses, policy->policies, datum->data, index->indices,
+      child->children)
+    uncountable: use explicit suffix (config vs config.collection; data.item vs data.items)
+    compound: pluralize the primary noun (button-group->button-groups, session-state->session-states)

package/planner-nodes/nodes/planner.artifact-naming.schema-identifier.convention.yaml

@@ -0,0 +1,31 @@
+schema_version: 1.1.0
+rule_id: planner.artifact-naming.schema-identifier
+kind: rule
+status: active
+name: Schema $id and version separation
+statement: A contract's $id is the clean artifact name {theme}:{resource}[.{category}] with NO 'urn:contract:'
+  prefix and NO version suffix; version is a separate top-level field.
+source:
+  legacy_path: src/atdd/planner/conventions/artifact-naming.convention.yaml
+  legacy_section: schema_identifier
+  legacy_sha: eca68a67c92694c9
+  extraction_mode: high_fidelity
+content:
+  normative_text: $id = clean artifact identifier (e.g. mechanic:timebank.exhausted). urn_reference (in
+    wagon produce/consume) = contract:{artifact_name}. Version is a SEPARATE top-level field so artifact
+    identity stays stable across versions.
+  counter_examples:
+  - mechanic:timebank.exhausted:v1  (version in $id breaks identity stability)
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: false
+  fix_hint_preserved: false
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: id_field
+  text: the $id of a contract schema.
+  values:
+    id_pattern: '{theme}:{resource}[.{category}]'
+    urn_reference: contract:{artifact_name}
+    version: separate top-level field