@afokapu/atdd-bun 0.1.0

package/planner-schemas/train.schema.json

@@ -0,0 +1,361 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Train Schema",
+  "description": "Schema for train definitions orchestrating multi-wagon workflows with typed identities",
+  "type": "object",
+  "additionalProperties": false,
+  "$comment": "Trains carry the typed identity `train:<subject>:<slug>`. Classification rides as fields — `themes`, `category` (nominal|error|alternate|exception), and `sort_key` — so reclassification edits metadata instead of identity.",
+  "required": [
+    "train_id",
+    "title",
+    "description",
+    "themes",
+    "participants",
+    "sequence"
+  ],
+  "properties": {
+    "train_id": {
+      "type": "string",
+      "pattern": "^train:[a-z][a-z0-9-]*:[a-z][a-z0-9-]*$",
+      "description": "Typed train identity: train:<subject>:<slug> (for example, train:artifact-identity:migrate-with-alias). `category` is a validated field, not an identity digit."
+    },
+    "category": {
+      "type": "string",
+      "enum": ["nominal", "error", "alternate", "exception"],
+      "description": "Train variant category: a validated field, never part of the identity."
+    },
+    "sort_key": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Optional ordinal used to order trains within a subject/category bucket."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 3,
+      "description": "Human-readable display name for the train"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 10,
+      "description": "Concise description of the train's purpose and workflow"
+    },
+    "family": {
+      "type": "string",
+      "enum": ["behavior", "delivery"],
+      "description": "Train family (planner.train.family): behavior (express/exercise a capability, no authority commit) or delivery (commits accepted-system state via an Acceptance Authority commit, terminating in platform:acceptance:commit-receipt). Orthogonal to the variant category; derived from the declared terminal contract; never encoded in the train id. Optional during the #1083 transition; to become required."
+    },
+    "path": {
+      "type": "string",
+      "description": "Canonical path to the train YAML file relative to repo root"
+    },
+    "file": {
+      "type": "string",
+      "description": "DEPRECATED: Use 'path' instead. Alias for backward compatibility",
+      "deprecated": true
+    },
+    "themes": {
+      "type": "array",
+      "description": "Theme categories this train belongs to",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]*$",
+        "description": "Repository-defined kebab-case theme declared in plan/_themes.yaml. The only reserved registry value is index 0: commons."
+      }
+    },
+    "primary_wagon": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "The primary wagon responsible for this train's core functionality"
+    },
+    "dependencies": {
+      "type": "array",
+      "description": "Other trains that must run before this train",
+      "items": {
+        "type": "string",
+        "pattern": "^train:[a-z][a-z0-9-]*:[a-z][a-z0-9-]*$",
+        "description": "Train reference: train:<subject>:<slug>."
+      }
+    },
+    "source_interlocking": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["interlocking_id", "route_id"],
+      "description": "OPTIONAL back-reference to the interlocking route this train was generated from or justified by (issue #1248). Pure traceability — it must NOT alter train linearity and is NOT a second execution source. The interlocking remains authoritative for the guarded route space; this train remains the single runtime-executable linear path.",
+      "properties": {
+        "interlocking_id": {
+          "type": "string",
+          "pattern": "^interlocking:[a-z][a-z0-9-]*$",
+          "description": "The owning interlocking (interlocking:<kebab-name>)."
+        },
+        "route_id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$",
+          "description": "The route within the interlocking that maps to this train."
+        },
+        "projection_digest": {
+          "type": "string",
+          "description": "Optional sha256 of the normalized route projection for drift detection."
+        }
+      }
+    },
+    "route_space": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["classification", "basis"],
+      "description": "Typed single-route assessment (issue #1554). A train is admitted to the route space one of two ways: it is targeted by exactly one registered interlocking route, or it declares this block. The two are mutually exclusive — declaring this block on a route-targeted train is a contradiction, and declaring neither is an omission. This exists because the ABSENCE of a route used to read as a positive assertion that route analysis had been performed and concluded `direct`; it no longer does. This block does NOT reference an interlocking: the route -> train edge is authoritative and lives on the interlocking, and `source_interlocking` remains optional traceability that is never consulted as an authority.",
+      "properties": {
+        "classification": {
+          "type": "string",
+          "enum": ["single-route"],
+          "description": "The classification this train asserts. Only `single-route` is declarable — being route-targeted is DERIVED from the interlocking registry and must never be self-declared here, which would make the train a second source of truth for its own routing."
+        },
+        "basis": {
+          "type": "string",
+          "enum": ["sole-terminal-outcome", "externally-routed", "not-yet-assessed"],
+          "description": "Why this train has a single route, drawn from a CLOSED vocabulary. Prose is deliberately not accepted: a free-text reason is an escape hatch that erodes, because it gets copy-pasted until every train carries one. `sole-terminal-outcome` = no alternative/error/exception path exists to route. `externally-routed` = the path is selected outside this plan's route space. `not-yet-assessed` = TRANSITIONAL; route analysis has not been performed, and `retires_with` must name the issue that will retire it."
+        },
+        "retires_with": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Issue number that will retire a `not-yet-assessed` basis. REQUIRED when basis is `not-yet-assessed` and forbidden otherwise, so the transitional basis is an owned obligation with a named retirer rather than a permanent resting place."
+        }
+      },
+      "allOf": [
+        {
+          "if": {"properties": {"basis": {"const": "not-yet-assessed"}}, "required": ["basis"]},
+          "then": {"required": ["retires_with"]},
+          "else": {"not": {"required": ["retires_with"]}}
+        }
+      ]
+    },
+    "participants": {
+      "type": "array",
+      "description": "Wagons, users, and systems involved in this train",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "pattern": "^(wagon|user|system):[a-z][a-z0-9-]*$",
+        "description": "Participant reference: wagon:{wagon-id}, user:{role}, system:{source}"
+      }
+    },
+    "test": {
+      "oneOf": [
+        {
+          "type": "string",
+          "description": "Single backend test file path"
+        },
+        {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "List of backend test file paths"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "backend": {
+              "oneOf": [
+                { "type": "string" },
+                { "type": "array", "items": { "type": "string" } }
+              ],
+              "description": "Backend test file path(s)"
+            },
+            "frontend": {
+              "oneOf": [
+                { "type": "string" },
+                { "type": "array", "items": { "type": "string" } }
+              ],
+              "description": "Frontend (web) test file path(s)"
+            },
+            "frontend_python": {
+              "oneOf": [
+                { "type": "string" },
+                { "type": "array", "items": { "type": "string" } }
+              ],
+              "description": "Frontend Python (Streamlit) test file path(s)"
+            }
+          },
+          "additionalProperties": false,
+          "description": "Test files organized by platform"
+        }
+      ],
+      "description": "Test file references for this train (string, array, or object with backend/frontend/frontend_python)"
+    },
+    "code": {
+      "oneOf": [
+        {
+          "type": "string",
+          "description": "Single backend implementation file path"
+        },
+        {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "List of backend implementation file paths"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "backend": {
+              "oneOf": [
+                { "type": "string" },
+                { "type": "array", "items": { "type": "string" } }
+              ],
+              "description": "Backend implementation file path(s)"
+            },
+            "frontend": {
+              "oneOf": [
+                { "type": "string" },
+                { "type": "array", "items": { "type": "string" } }
+              ],
+              "description": "Frontend (web) implementation file path(s)"
+            },
+            "frontend_python": {
+              "oneOf": [
+                { "type": "string" },
+                { "type": "array", "items": { "type": "string" } }
+              ],
+              "description": "Frontend Python (Streamlit) implementation file path(s)"
+            }
+          },
+          "additionalProperties": false,
+          "description": "Implementation files organized by platform"
+        }
+      ],
+      "description": "Implementation file references for this train (string, array, or object with backend/frontend/frontend_python)"
+    },
+    "expectations": {
+      "type": "object",
+      "properties": {
+        "backend": {
+          "type": "boolean",
+          "description": "Whether backend implementation is expected"
+        },
+        "frontend": {
+          "type": "boolean",
+          "description": "Whether frontend (web) implementation is expected"
+        },
+        "frontend_python": {
+          "type": "boolean",
+          "description": "Whether frontend Python (Streamlit) implementation is expected"
+        }
+      },
+      "additionalProperties": false,
+      "description": "Explicit expectations for which platforms this train should be implemented on"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["planned", "tested", "implemented"],
+      "default": "planned",
+      "description": "Current implementation status of the train"
+    },
+    "sequence": {
+      "type": "array",
+      "description": "Ordered linear steps defining the train workflow. Trains are strictly linear: no loops or routes. New journeys require new trains.",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/definitions/step"
+      }
+    },
+    "acceptances": {
+      "type": "array",
+      "description": "Train-level acceptance criteria. Mirror of the WMBT acceptance shape (substrate spec v12 §5.2). Each entry contributes a derived rule to the registry via the repo-rule walker — the rule-id derives from identity.urn per §3.3, so the acceptance block MUST NOT include an id: field at the top level (the per-acceptance identity.id field is allowed for human reference).",
+      "items": {
+        "$ref": "#/definitions/acceptance"
+      }
+    }
+  },
+  "definitions": {
+    "acceptance": {
+      "type": "object",
+      "required": ["identity"],
+      "additionalProperties": true,
+      "properties": {
+        "identity": {
+          "type": "object",
+          "required": ["urn", "purpose", "phase"],
+          "additionalProperties": true,
+          "properties": {
+            "urn": {
+              "type": "string",
+              "description": "Acceptance URN: acc:<train-id>:<acceptance-slug>"
+            },
+            "id": {
+              "type": "string",
+              "description": "Optional human-facing label (e.g. AC-SMOKE-001). NOT used for rule-id derivation."
+            },
+            "purpose": {
+              "type": "string",
+              "minLength": 5,
+              "description": "One-line statement of what this acceptance enforces (becomes RuleMetadata.description)."
+            },
+            "phase": {
+              "type": "string",
+              "enum": ["RED", "GREEN", "SMOKE", "REFACTOR"],
+              "description": "ATDD lifecycle phase the acceptance dispatches to."
+            }
+          }
+        },
+        "harness": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "type": {"type": "string"},
+            "category": {"type": "string"}
+          }
+        },
+        "given": {"type": "object"},
+        "when": {"type": "object"},
+        "then": {"type": "object"},
+        "signal": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "metric": {"type": "string"},
+            "threshold": {}
+          }
+        },
+        "metadata": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "author": {"type": "string"},
+            "created": {"type": "string"}
+          }
+        }
+      }
+    },
+    "step": {
+      "type": "object",
+      "required": ["step", "intent", "from", "to", "artifact"],
+      "additionalProperties": false,
+      "properties": {
+        "step": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Step number in sequence"
+        },
+        "intent": {
+          "type": "string",
+          "minLength": 5,
+          "description": "What this step accomplishes"
+        },
+        "from": {
+          "type": "string",
+          "pattern": "^(wagon|user|system):[a-z][a-z0-9-]*$",
+          "description": "Source participant"
+        },
+        "to": {
+          "type": "string",
+          "pattern": "^(wagon|user|system):[a-z][a-z0-9-]*$",
+          "description": "Destination participant"
+        },
+        "artifact": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*(?::[a-z][a-z0-9-]*)+(?:\\.[a-z][a-z0-9-]*)?$",
+          "$comment": "Widened from the two-segment `^[a-z][a-z0-9-]*:[a-z][a-z0-9.-]*$` by #1929. That pattern contradicted planner.artifact-naming, whose identity grammar is theme-first `{theme}(:{category})*:{aspect}(.{variant})?` — `is_valid_artifact_identity('commons:admit:admission-cli')` returns True while the old pattern rejected it, so 7 of 21 in-repo trains failed their own schema on identities the naming authority accepts. Kept byte-compatible with _CONTRACT_IDENTITY_RE in planner/commands/author.py.",
+          "description": "Artifact passed between participants; a theme-first identity, `{theme}(:{category})*:{aspect}(.{variant})?`"
+        }
+      }
+    }
+  }
+}

package/planner-schemas/wagon.schema.json

@@ -0,0 +1,283 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Wagon Manifest Schema",
+  "description": "Minimal wagon header (1:1 fields) with step-coded WMBT registry and retired index.",
+  "type": "object",
+  "additionalProperties": false,
+  "$comment": "SPEC-COACH-UTILS-0281: Naming Conventions - URNs/slugs use kebab-case (wagon:maintain-ux, maintain-ux), directories use snake_case (plan/maintain_design/), manifest files use _{dirname}.yaml (_maintain_design.yaml). Conversion: slug.replace('-','_')→dirname, dirname.replace('_','-')→slug. Note: enforce total matches live WMBT entries in CI/code; draft-07 cannot express that constraint.",
+  "required": [
+    "wagon",
+    "description",
+    "subject",
+    "context",
+    "action",
+    "goal",
+    "outcome",
+    "produce",
+    "consume",
+    "wmbt"
+  ],
+  "properties": {
+    "wagon": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Wagon identifier in verb-object kebab-case (e.g., resolve-dilemmas, commit-state)."
+    },
+    "urn": {
+      "type": "string",
+      "pattern": "^wagon:[a-z][a-z0-9-]*$",
+      "description": "Optional URN for global addressing. Format: wagon:{slug}."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 3,
+      "description": "Optional human-readable display name (title-case allowed)."
+    },
+    "description": {
+      "type": "string",
+      "minLength": 10,
+      "description": "Concise one-liner explaining the wagon's purpose and scope."
+    },
+    "theme": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Repository-defined category for navigation and reporting. It must be a kebab-case value declared in plan/_themes.yaml; only index 0 is reserved as commons."
+    },
+
+    "subject": {
+      "type": "string",
+      "pattern": "^[a-z]+:[a-z][a-z0-9-]*$",
+      "description": "Who/what performs the action (typed identifier, e.g., player:active, engine:orchestrator)."
+    },
+    "context": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Situs/when/where as a short phrase (e.g., \"in-match, timebank-active\")."
+    },
+    "action":  {
+      "type": "string",
+      "minLength": 1,
+      "description": "Single present-tense phrase of what the subject does (e.g., \"applies the chosen option\")."
+    },
+    "goal":    {
+      "type": "string",
+      "minLength": 1,
+      "description": "Single intent that motivates the action (e.g., \"advance toward a stable business trajectory\")."
+    },
+    "outcome": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Single measurable progress statement (e.g., \"choice applied and state updated\")."
+    },
+    "produce": {
+      "type": "array",
+      "description": "Artifacts produced and owned by this wagon",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["name", "contract", "telemetry"],
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9\\-]*:[a-z][a-z0-9\\-:]*(\\.[a-z][a-z0-9\\-]+)?$",
+            "description": "Artifact name per artifact-naming.convention.yaml: domain(:category)*:aspect(.variant)? - supports hierarchy (colons) and facets (dots). Examples: match:started, commons:auth.claims, commons:ux:foundations:color"
+          },
+          "to": {
+            "type": "string",
+            "enum": ["internal", "external"],
+            "default": "external",
+            "description": "Optional visibility: internal (private to this wagon), external (public to all wagons including self). Defaults to external when omitted."
+          },
+          "version": {
+            "type": "string",
+            "pattern": "^v\\d+$",
+            "description": "Optional version (e.g., v1)"
+          },
+          "contract": {
+            "type": ["string", "null"],
+            "pattern": "^(contract:[a-z][a-z0-9\\-]*:[a-z][a-z0-9\\-:]*(\\.[a-z][a-z0-9\\-]+)?|contracts/[a-z][a-z0-9-]*(?:/[a-z][a-z0-9-]*)*\\.(?:schema\\.)?json)$",
+            "$comment": "Path arm widened by #1929. It was contracts/[a-z]+/[a-z][a-z0-9-]+.json — ONE segment, bare .json — which no path satisfying planner.artifact-naming.path-mirrors-identity can match: that rule mirrors {theme}(:{category})*:{aspect} onto contracts/<theme>/<category>/<aspect>.schema.json. The two were mutually exclusive, and the contradiction stayed latent only because every in-repo wagon uses the contract: URN arm (19) or null (164). Widening keeps BOTH gates reachable: a malformed segment is refused here, a well-formed path mirroring the wrong identity is refused by path-mirrors-identity with its own message. Traversal (..) and uppercase remain refused.",
+            "description": "Contract URN per artifact-naming.convention.yaml (e.g., contract:commons:ux:foundations, contract:commons:player.identity, contract:match:result) or legacy path (e.g., contracts/commons/ux/foundations.json). Required field, use null if no contract exists."
+          },
+          "telemetry": {
+            "type": ["string", "null"],
+            "pattern": "^telemetry:[a-z][a-z0-9\\-]*:[a-z][a-z0-9\\-:]*(\\.[a-z][a-z0-9\\-]+)?$",
+            "description": "Telemetry URN for observability and analytics per artifact-naming.convention.yaml (e.g., telemetry:commons:ux:foundations, telemetry:mechanic:decision.choice → telemetry/mechanic/decision/choice/). Maps to directory containing signal files: metric.{plane}.{measure}.json and event.{plane}.json. Manifest generated from source files. Required field, use null if telemetry not tracked."
+          }
+        }
+      }
+    },
+    "consume": {
+      "type": "array",
+      "description": "Artifacts consumed from other wagons",
+      "minItems": 0,
+      "items": {
+        "type": "object",
+        "required": ["name"],
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9\\-]*:[a-z][a-z0-9\\-:]*(\\.[a-z][a-z0-9\\-]+)?$",
+            "description": "Artifact name per artifact-naming.convention.yaml: domain(:category)*:aspect(.variant)? - supports hierarchy (colons) and facets (dots). Examples: match:started, match:dilemma.current, commons:player.identity, appendix:mockup. Pattern: Events = past tense verbs, State = nouns/adjectives, Collections = plural"
+          },
+          "from": {
+            "type": "string",
+            "pattern": "^((wagon|system|appendix):[a-z][a-z0-9-]*|internal)$",
+            "description": "Optional source: wagon:slug (external wagon), system:service (platform), appendix:type (supplementary), or 'internal' (same wagon). Can be omitted when source is inferred from contract URN."
+          },
+          "version": {
+            "type": "string",
+            "pattern": "^v\\d+$",
+            "description": "Optional version requirement"
+          },
+          "contract": {
+            "type": ["string", "null"],
+            "pattern": "^(contract:[a-z][a-z0-9\\-]*:[a-z][a-z0-9\\-:]*(\\.[a-z][a-z0-9\\-]+)?|contracts/[a-z][a-z0-9-]*(?:/[a-z][a-z0-9-]*)*\\.(?:schema\\.)?json)$",
+            "$comment": "Path arm widened by #1929. It was contracts/[a-z]+/[a-z][a-z0-9-]+.json — ONE segment, bare .json — which no path satisfying planner.artifact-naming.path-mirrors-identity can match: that rule mirrors {theme}(:{category})*:{aspect} onto contracts/<theme>/<category>/<aspect>.schema.json. The two were mutually exclusive, and the contradiction stayed latent only because every in-repo wagon uses the contract: URN arm (19) or null (164). Widening keeps BOTH gates reachable: a malformed segment is refused here, a well-formed path mirroring the wrong identity is refused by path-mirrors-identity with its own message. Traversal (..) and uppercase remain refused.",
+            "description": "Optional contract URN per artifact-naming.convention.yaml (e.g., contract:appendix:mockup, contract:match:dilemma.current, contract:match:result) or legacy path (e.g., contracts/appendix/mockup.json). Can be null if no contract exists."
+          },
+          "telemetry": {
+            "type": ["string", "null"],
+            "pattern": "^telemetry:[a-z][a-z0-9\\-]*:[a-z][a-z0-9\\-:]*(\\.[a-z][a-z0-9\\-]+)?$",
+            "description": "Optional telemetry URN for observability and analytics per artifact-naming.convention.yaml (e.g., telemetry:appendix:mockup, telemetry:mechanic:decision.choice → telemetry/mechanic/decision/choice/). Maps to directory containing signal JSON files. Can be null if telemetry not tracked."
+          }
+        }
+      }
+    },
+
+    "wmbt_step_codes": {
+      "type": "object",
+      "readOnly": true,
+      "const": {
+        "D": "Define",
+        "L": "Locate",
+        "P": "Prepare",
+        "C": "Confirm",
+        "E": "Execute",
+        "M": "Monitor",
+        "Y": "Modify",
+        "R": "Resolve",
+        "K": "Conclude"
+      }
+    },
+
+    "wmbt": {
+      "type": "object",
+      "minProperties": 0,
+      "additionalProperties": false,
+      "required": ["total"],
+      "properties": {
+        "total": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Total number of WMBTs in this wagon (sum across all steps). Can be 0 initially, populated via wmbt.action handoff."
+        },
+        "coverage": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100,
+          "description": "Optional WMBT coverage percentage (0-100). Measures completeness of WMBT planning and implementation."
+        }
+      },
+      "patternProperties": {
+        "^[DLPCEMYRK][0-9]{3}$": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+
+    "retired": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^[DLPCEMYRK][0-9]{3}$": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+
+    "features": {
+      "oneOf": [
+        {
+          "type": "object",
+          "description": "Legacy: Features as object with slug:description pairs",
+          "additionalProperties": false,
+          "patternProperties": {
+            "^[a-z]+-[a-z0-9-]+$": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 120
+            }
+          }
+        },
+        {
+          "type": "array",
+          "description": "Features as URN array (e.g., [{ urn: 'feature:maintain-ux.provide-foundations' }])",
+          "items": {
+            "type": "object",
+            "required": ["urn"],
+            "additionalProperties": false,
+            "properties": {
+              "urn": {
+                "type": "string",
+                "pattern": "^feature:[a-z][a-z0-9-]+:[a-z][a-z0-9-]+$",
+                "description": "Feature URN in format feature:wagon-slug:feature-name (e.g., feature:maintain-ux:provide-foundations)"
+              }
+            }
+          }
+        }
+      ]
+    },
+
+    "coverage": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional coverage counts by lens for planning/reporting.",
+      "properties": {
+        "functional": { "type": "integer", "minimum": 0, "description": "Count of functional/technical WMBTs." },
+        "emotional":  { "type": "integer", "minimum": 0, "description": "Count of emotional/UX WMBTs." },
+        "social":     { "type": "integer", "minimum": 0, "description": "Count of social/collaborative WMBTs." }
+      }
+    },
+
+    "metadata": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional metadata for versioning, dependencies, and timestamps.",
+      "properties": {
+        "version":  { "type": "string", "pattern": "^\\d+\\.\\d+(\\.\\d+)?$", "description": "Semantic version of this manifest." },
+        "dependencies": {
+          "type": "array",
+          "description": "Other wagon slugs this wagon depends on (planning view; interfaces are derived from artifacts).",
+          "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" }
+        },
+        "created": { "type": "string", "format": "date", "description": "Creation date (YYYY-MM-DD)." },
+        "updated": { "type": "string", "format": "date", "description": "Last updated (YYYY-MM-DD)." }
+      }
+    },
+
+    "appendices": {
+      "type": "array",
+      "description": "Supplementary files (mockups, diagrams, documents, etc.) that provide additional context for this wagon",
+      "items": {
+        "$ref": "appendix.schema.json#/definitions/appendix_reference"
+      }
+    }
+  },
+  "definitions": {
+    "wmbt_ids": {
+      "type": "array",
+      "description": "List of WMBT ids for a given step. Use 3-digit ids, optional slug suffix.",
+      "items": {
+        "oneOf": [
+          { "type": "integer", "minimum": 1, "maximum": 999, "description": "Numeric WMBT id (1..999 maps to 001..999)." },
+          { "type": "string", "pattern": "^\\d{3}(-[a-z][a-z0-9-]*)?$", "description": "String id with optional suffix (e.g., \"001\" or \"001-define-scope\")." }
+        ]
+      }
+    }
+  }
+}