@afokapu/atdd-bun 0.1.0

package/planner-schemas/author/issue.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "atdd:author:issue:1.0.0",
+  "title": "ATDD issue body (#1223 — the issue artifact joins the author substrate)",
+  "description": "Canonical schema for an ATDD GitHub issue body. Peer of convention-node/gate/relationship/scope. The `required` list is the set of section HEADINGS (verbatim `## …` H2 / `### …` H3 markdown strings) an issue body must contain — exactly the H2 sections of PARENT-ISSUE-TEMPLATE.md (minus the optional `## Rule Wiring`) plus the two mandatory H3 subsections `### Graph Context` / `### Mirror Across Agents` that #682 lifted from advisory to mandatory. Modeling `required` as the heading strings (rather than abstract keys) keeps the schema, the `atdd author issue` generator, and the coach E019 gate mechanically drift-checked against one another (C011). The `status`/`type` properties carry the Metadata enums; `status` derives its vocabulary from src/atdd/coach/conventions/phase_machine.convention.yaml (single shared vocabulary — the #1203 State-Store work-item record reuses it, no fork).",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "## Issue Metadata",
+    "## Scope",
+    "## Context",
+    "## Architecture",
+    "### Graph Context",
+    "### Mirror Across Agents",
+    "## Phases",
+    "## Validation",
+    "## Decisions",
+    "## Activity Log",
+    "## Artifacts",
+    "## Release Gate",
+    "## Notes"
+  ],
+  "properties": {
+    "## Issue Metadata": {"type": "string", "description": "Metadata table: Date, Status (enum), Type (enum), Branch, Archetypes, Train, Feature."},
+    "## Scope": {"type": "string", "description": "In Scope / Out of Scope / Dependencies / Done-when."},
+    "## Context": {"type": "string", "description": "Problem Statement, User Impact, Root Cause."},
+    "## Architecture": {"type": "string", "description": "Design, including the two mandatory H3 subsections below."},
+    "### Graph Context": {"type": "string", "description": "How this issue sits in the dependency/issue graph (mandatory, #682)."},
+    "### Mirror Across Agents": {"type": "string", "description": "Per-archetype current/target/action table (mandatory, #682)."},
+    "## Phases": {"type": "string", "description": "Sequenced phases with deliverables and files."},
+    "## Validation": {"type": "string", "description": "Gate Tests + Success Criteria."},
+    "## Decisions": {"type": "string", "description": "Resolved questions and their rationale."},
+    "## Activity Log": {"type": "string", "description": "Dated progress entries."},
+    "## Artifacts": {"type": "string", "description": "Created / Modified / Deleted artifacts, as `- ` bullets under the three H3 subsections. Every bullet is an `artifactEntry` (see definitions): either a repo-relative path the COMPLETE gate can resolve against git, or the explicit-empty placeholder `(none yet)` for a section that has nothing to declare yet. Prose is neither — a bullet like `- The artifact this issue lands.` reads as a claim, resolves against nothing, and fails `coach.issue.artifact-claims-must-resolve` (#1726)."},
+    "## Release Gate": {"type": "string", "description": "Version bump + publish checklist."},
+    "## Notes": {"type": "string", "description": "Additional context that does not fit elsewhere."},
+    "status": {
+      "type": "string",
+      "description": "Work-item phase. Vocabulary is the single shared phase-machine vocabulary (src/atdd/coach/conventions/phase_machine.convention.yaml); the #1203 State-Store work-item record reuses these exact values (no fork).",
+      "enum": ["INIT", "PLANNED", "RED", "GREEN", "SMOKE", "REFACTOR", "COMPLETE", "BLOCKED", "OBSOLETE"]
+    },
+    "type": {
+      "type": "string",
+      "description": "Issue type classification.",
+      "enum": ["implementation", "bug", "feature", "refactor", "docs", "chore", "devops"]
+    }
+  },
+  "definitions": {
+    "artifactEntry": {
+      "description": "One `- ` bullet under `## Artifacts` → `### Created` / `### Modified` / `### Deleted`. The `## Artifacts` section was the one part of the body the COMPLETE gate resolves as REAL FILE PATHS while the schema typed it as an unconstrained string, so prose was as valid as a path right up until the gate rejected it (#1726). This definition is what lets the authoring path tell the two apart; `coach.issue.artifact-claims-must-resolve` is what enforces it. A subsection with nothing to declare yet carries NO bullet at all — see emptyDeclaration.",
+      "oneOf": [
+        {"$ref": "#/definitions/repoRelativePath"},
+        {"$ref": "#/definitions/placeholderBullet"}
+      ]
+    },
+    "repoRelativePath": {
+      "type": "string",
+      "description": "A path relative to the repo root, as git names it: no whitespace, carrying a `/` or an extension, and not ending in `.` (which is how a prose sentence ends). Matches `src/atdd/cli.py`, `.github/workflows/atdd-validate.yml`, `CLAUDE.md`; rejects `The artifact this issue lands.`, `None so far.`, `drift-guard test`. Globs, URLs and external artefacts are deliberately out of scope — #1726 declared redefining what counts as an artifact out of scope, so the vocabulary stays exactly the set git can answer for.",
+      "pattern": "^(?=.*[./])[^\\s]*[^\\s.]$"
+    },
+    "placeholderBullet": {
+      "type": "string",
+      "description": "A parenthesised bullet, which the body parser skips rather than reading as a claim (`IssueManager._artifact_path`). Accepted so a hand-written `- (pending)` is not mistaken for a file, but NOT what the generator emits: strings like `(none yet)` are declared unfilled-template placeholders that the E019 gate rejects.",
+      "pattern": "^\\(.*\\)$"
+    },
+    "emptyDeclaration": {
+      "type": "string",
+      "description": "The explicit-empty form for a subsection with nothing to declare yet: NO bullet at all, and an italic note saying how to fill it. Not a bullet, because every bullet is read as a claim about a file; not `(none yet)`, because that is a declared unfilled-template placeholder the E019 gate rejects. It parses as zero artifacts — valid at INIT, and a `coach.issue.artifacts-must-be-declared` violation at COMPLETE. This is what `atdd author issue` emits, replacing the prose scaffold (`- The artifact this issue lands.`) that parsed as three claims and failed the gate it was destined for (#1726).",
+      "pattern": "^_.*_$"
+    }
+  }
+}

package/planner-schemas/author/relationship.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "atdd:author:relationship:1.0.0",
+  "title": "ATDD relationship edge (spec §6)",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["source_ref", "type", "target_ref"],
+  "properties": {
+    "source_ref": {"type": "string"},
+    "target_ref": {"type": "string"},
+    "type": {"enum": ["requires", "blocks", "enables", "follows", "awaits", "triggered_by", "starts_with", "runs_alongside", "finishes_with", "relieves"]},
+    "foundation": {"enum": ["finish_to_start", "start_to_start", "finish_to_finish", "start_to_finish"]},
+    "constraint": {"enum": ["mandatory", "discretionary", "conditional"]},
+    "control": {"enum": ["internal", "external", "autonomous"]},
+    "strength": {"enum": ["critical", "important", "minor"]},
+    "reason": {"type": "string"},
+    "confidence": {"type": "number"}
+  }
+}

package/planner-schemas/author/scope.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "atdd:author:scope:1.0.0",
+  "title": "ATDD scope / selector (spec §7) — V1: scope primary, selectors embedded",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["scope_id", "selectors"],
+  "properties": {
+    "scope_id": {"type": "string", "pattern": "^[a-z][a-z0-9_-]*(?:\\.[a-z0-9_-]+)+$"},
+    "artifact_kind": {"enum": ["source_file", "test_file", "plan_file", "contract_file", "pull_request", "issue", "remote_resource", "runtime_evidence"]},
+    "runtime": {"enum": ["python", "typescript", "supabase", "flutter", null]},
+    "platform": {"enum": ["github", "local_fs", "supabase", "vercel", "convex", null]},
+    "selectors": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["selector_id", "type", "include"],
+        "properties": {
+          "selector_id": {"type": "string", "pattern": "^[a-z][a-z0-9_-]*(?:\\.[a-z0-9_-]+)+$"},
+          "type": {"enum": ["path_glob", "git_path_prefix", "header_scan", "manifest_query", "github_pr", "github_issue", "remote_resource", "runtime_evidence"]},
+          "include": {"type": "array", "minItems": 1, "items": {"type": "string"}},
+          "exclude": {"type": "array", "items": {"type": "string"}}
+        }
+      }
+    }
+  }
+}

package/planner-schemas/binding-lock.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ATDD Binding Lock Schema",
+  "description": "Resolved substrate binding plan (.atdd/binding.lock.yaml). Keyed to a substrate-lock digest; records, per convention, whether gating is bound-owned by an admitted implementation/workspace or left to a legacy-fallback validator. Produced by the binder (atdd bind --check); never executes implementation code to build it.",
+  "type": "object",
+  "required": ["schema_version", "substrate_lock_digest", "conventions"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
+    "substrate_lock_digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "conventions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["convention_id", "disposition"],
+        "additionalProperties": false,
+        "properties": {
+          "convention_id": { "type": "string", "minLength": 1 },
+          "disposition": { "type": "string", "enum": ["bound", "legacy-fallback"] },
+          "package_id": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The admitted package that OWNS this rule, i.e. the substrate.lock.yaml artifact whose implementation realizes it. Without it a bound rule cannot be traced back to an installed package, and the substrate coherence invariant (no rule may be bound to a package absent from substrate.lock.yaml) is unprovable. Optional in the schema only so a lock written by an older core still parses; the binder always writes it, and `atdd substrate remove` refuses to report success without it."
+          },
+          "implementation_id": { "type": "string", "minLength": 1 },
+          "workspace_id": { "type": "string", "minLength": 1 },
+          "contract_version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" }
+        },
+        "if": {
+          "properties": { "disposition": { "const": "bound" } }
+        },
+        "then": {
+          "required": ["implementation_id", "workspace_id", "contract_version"]
+        }
+      }
+    }
+  }
+}

package/planner-schemas/component.schema.json

@@ -0,0 +1,114 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Component Schema",
+  "description": "Schema for component YAML files",
+  "type": "object",
+  "required": ["urn", "parentFeature", "description"],
+  "properties": {
+    "urn": {
+      "type": "string",
+      "pattern": "^component:[a-z][a-z0-9-]*:[a-z][a-z0-9-]*:[a-zA-Z0-9.]+:(frontend|backend|fe|be):(presentation|application|domain|integration|assembly)$",
+      "description": "Component URN: component:{wagon}:{feature}:{name}:{side}:{layer}"
+    },
+    "parentFeature": {
+      "type": "string",
+      "pattern": "^feature:[a-z][a-z0-9-]*:[a-z][a-z0-9-]*$",
+      "description": "Parent feature URN in format feature:{wagon}:{feature}"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 10,
+      "maxLength": 200,
+      "description": "Purpose of the component"
+    },
+    "inputs": {
+      "type": "array",
+      "description": "Component inputs with references to feature ioSeeds",
+      "items": {
+        "type": "object",
+        "required": ["name", "urn"],
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[a-z]+:[a-z][a-z0-9-]*$",
+            "description": "Input name in typed format"
+          },
+          "urn": {
+            "type": "string",
+            "pattern": "^feature:[a-z][a-z0-9-]*:[a-z][a-z0-9-]*#[a-z]+:[a-z][a-z0-9-]*$",
+            "description": "Reference to feature ioSeed URN (feature:wagon:feature#name:item)"
+          }
+        }
+      }
+    },
+    "outputs": {
+      "type": "array",
+      "description": "Component outputs with references to feature ioSeeds",
+      "items": {"$ref": "#/properties/inputs/items"}
+    },
+    "dependencies": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^component:[a-z][a-z0-9-]*:[a-z][a-z0-9-]*:[a-zA-Z0-9.]+:(frontend|backend|fe|be):(presentation|application|domain|integration|assembly)$"
+      },
+      "description": "Component dependencies"
+    },
+    "events": {
+      "type": "object",
+      "properties": {
+        "consumes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["event"],
+            "properties": {
+              "event": {
+                "type": "string",
+                "description": "Event name"
+              }
+            }
+          },
+          "maxItems": 3,
+          "description": "Events this component consumes"
+        },
+        "produces": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["event"],
+            "properties": {
+              "event": {
+                "type": "string",
+                "description": "Event name"
+              }
+            }
+          },
+          "maxItems": 3,
+          "description": "Events this component produces"
+        }
+      }
+    },
+
+    "componentType": {
+      "type": "string",
+      "description": "Component type from coder conventions catalog",
+      "enum": [
+        "controllers", "routes", "serializers", "validators", "middleware", "guards", "views",
+        "use_cases", "handlers", "ports", "dtos", "policies", "workflows",
+        "entities", "value_objects", "aggregates", "services", "specifications", "events", "exceptions",
+        "repositories", "clients", "caches", "engines", "formatters", "notifiers", "queues", "stores", "mappers", "schedulers", "monitors",
+        "components", "containers", "layouts", "styles", "animations", "forms", "hooks", "directives", "filters",
+        "interceptors", "synchronizers", "validators", "workers", "connectors"
+      ]
+    },
+    "appendices": {
+      "type": "array",
+      "description": "Supplementary files for this component",
+      "items": {
+        "$ref": "appendix.schema.json#/definitions/appendix_reference"
+      }
+    }
+  }
+}

package/planner-schemas/contract-registry.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Planner contract registry",
+  "description": "The authored registry for contract identity, path, theme, producers, and consumers.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contracts"],
+  "properties": {
+    "contracts": {
+      "oneOf": [
+        { "type": "array", "items": { "$ref": "#/definitions/listEntry" } },
+        {
+          "type": "object",
+          "patternProperties": {
+            "^[a-z][a-z0-9-]*(?::[a-z][a-z0-9-]*)+(?:\\.[a-z][a-z0-9-]*)?$": { "$ref": "#/definitions/keyedEntry" }
+          },
+          "additionalProperties": false
+        }
+      ]
+    }
+  },
+  "definitions": {
+    "baseEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "identity": { "type": "string", "pattern": "^[a-z][a-z0-9-]*(?::[a-z][a-z0-9-]*)+(?:\\.[a-z][a-z0-9-]*)?$" },
+        "path": { "type": "string", "pattern": "^contracts/[a-z][a-z0-9-]*(?:/[a-z][a-z0-9-]*)*\\.schema\\.json$" },
+        "theme": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+        "producers": { "type": "array", "items": { "type": "string", "pattern": "^wagon:[a-z][a-z0-9-]*$" } },
+        "consumers": { "type": "array", "items": { "type": "string", "pattern": "^wagon:[a-z][a-z0-9-]*$" } }
+      }
+    },
+    "listEntry": {
+      "allOf": [
+        { "$ref": "#/definitions/baseEntry" },
+        { "required": ["identity", "path", "theme", "producers", "consumers"] }
+      ]
+    },
+    "keyedEntry": {
+      "allOf": [
+        { "$ref": "#/definitions/baseEntry" },
+        { "required": ["path", "theme", "producers", "consumers"] }
+      ]
+    }
+  }
+}

package/planner-schemas/feature.schema.json

@@ -0,0 +1,208 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Feature Schema",
+  "description": "Schema for feature YAML files",
+  "type": "object",
+  "required": ["urn", "wagon", "description", "sizing", "wmbts", "components"],
+  "properties": {
+    "urn": {
+      "type": "string",
+      "pattern": "^feature:[a-z][a-z0-9-]*:[a-z][a-z0-9-]*$",
+      "description": "Feature URN: feature:{wagon}:{feature}"
+    },
+    "wagon": {
+      "type": "string",
+      "pattern": "^wagon:[a-z][a-z0-9-]*$",
+      "description": "Parent wagon URN (e.g., wagon:burn-timebank)"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 10,
+      "maxLength": 200,
+      "description": "One-liner describing feature purpose"
+    },
+    "sizing": {
+      "type": "object",
+      "required": ["wmbts", "footprint_score", "footprint_size"],
+      "additionalProperties": false,
+      "properties": {
+        "wmbts": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "WMBT count covered by this feature"
+        },
+        "footprint_score": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Calculated footprint complexity score"
+        },
+        "footprint_size": {
+          "type": "string",
+          "enum": ["XS", "S", "M", "L", "XL"],
+          "description": "Footprint size category based on score"
+        }
+      },
+      "description": "Feature sizing metrics combining WMBT coverage and architectural footprint"
+    },
+    "wmbts": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^wmbt:[a-z][a-z0-9-]*:[DLPCEMYRK][0-9]{3}$"
+      },
+      "description": "WMBTs covered by this feature (e.g., wmbt:burn-timebank:E001)"
+    },
+    "components": {
+      "type": "object",
+      "description": "Component enumeration using URN references to component types from coder conventions",
+      "additionalProperties": false,
+      "properties": {
+        "backend": {
+          "type": "object",
+          "description": "Backend components grouped by architectural layer",
+          "additionalProperties": false,
+          "properties": {
+            "presentation": {
+              "type": "array",
+              "items": {"$ref": "#/definitions/componentEntry"}
+            },
+            "application": {
+              "type": "array",
+              "items": {"$ref": "#/definitions/componentEntry"}
+            },
+            "domain": {
+              "type": "array",
+              "items": {"$ref": "#/definitions/componentEntry"}
+            },
+            "integration": {
+              "type": "array",
+              "items": {"$ref": "#/definitions/componentEntry"}
+            },
+            "assembly": {
+              "type": "array",
+              "items": {"$ref": "#/definitions/componentEntry"},
+              "description": "Assembly layer for composition/orchestration above the 4 layers"
+            }
+          }
+        },
+        "frontend": {
+          "type": "object",
+          "description": "Frontend components grouped by architectural layer",
+          "additionalProperties": false,
+          "properties": {
+            "presentation": {
+              "type": "array",
+              "items": {"$ref": "#/definitions/componentEntry"}
+            },
+            "application": {
+              "type": "array",
+              "items": {"$ref": "#/definitions/componentEntry"}
+            },
+            "domain": {
+              "type": "array",
+              "items": {"$ref": "#/definitions/componentEntry"}
+            },
+            "integration": {
+              "type": "array",
+              "items": {"$ref": "#/definitions/componentEntry"}
+            },
+            "assembly": {
+              "type": "array",
+              "items": {"$ref": "#/definitions/componentEntry"},
+              "description": "Assembly layer for composition/orchestration above the 4 layers"
+            }
+          }
+        }
+      },
+      "anyOf": [
+        {"required": ["backend"]},
+        {"required": ["frontend"]}
+      ]
+    },
+    "ioSeeds": {
+      "type": "object",
+      "description": "I/O seeds that propagate to child components with explicit wagon references",
+      "required": ["consume", "produce"],
+      "additionalProperties": false,
+      "properties": {
+        "consume": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "contract"],
+            "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)?"
+              },
+              "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-z][a-z0-9-]+\\.json)$",
+                "description": "Contract URN per artifact-naming.convention.yaml (e.g., contract:commons:ux:foundations, contract:match:result) or legacy path. 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 per artifact-naming.convention.yaml (e.g., telemetry:mechanic:decision.choice). Use null if telemetry not tracked."
+              },
+              "derived": {
+                "type": "boolean",
+                "description": "True if this is a new internal seed not in parent wagon"
+              }
+            }
+          },
+          "description": "Input seeds consumed by this feature"
+        },
+        "produce": {
+          "type": "array",
+          "items": {"$ref": "#/properties/ioSeeds/properties/consume/items"},
+          "description": "Output seeds produced by this feature"
+        }
+      }
+    },
+
+    "appendices": {
+      "type": "array",
+      "description": "Supplementary files for this feature",
+      "items": {
+        "$ref": "appendix.schema.json#/definitions/appendix_reference"
+      }
+    }
+  },
+
+  "definitions": {
+    "componentEntry": {
+      "type": "object",
+      "required": ["type", "count", "rationale"],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "controllers", "routes", "serializers", "validators", "middleware", "guards", "views",
+            "use_cases", "handlers", "ports", "dtos", "policies", "workflows",
+            "entities", "value_objects", "aggregates", "services", "specifications", "events", "exceptions",
+            "repositories", "clients", "caches", "engines", "formatters", "notifiers", "queues", "stores", "mappers", "schedulers", "monitors",
+            "components", "containers", "layouts", "styles", "animations", "forms", "hooks", "directives", "filters",
+            "interceptors", "synchronizers", "workers", "connectors"
+          ],
+          "description": "Component type from component.schema.json componentType enum. Side and layer inferred from YAML hierarchy."
+        },
+        "count": {
+          "type": "integer",
+          "minimum": 0,
+          "$comment": "Relaxed from minimum:1 by #1929. A zero count is a deliberate, informative declaration, not an empty one: the entry still carries a `rationale` saying WHY the layer needs nothing ('No new CLI commands — migration uses existing atdd commands'), which omitting the entry cannot distinguish from having forgotten it. 224 of 667 in-repo component entries are zero, so minimum:1 made the most informative form of the declaration unsayable.",
+          "description": "Number of components of this type; 0 declares the layer deliberately empty, with the reason in `rationale`."
+        },
+        "rationale": {
+          "type": "string",
+          "minLength": 10,
+          "maxLength": 200,
+          "description": "Brief explanation for why this component type is needed"
+        }
+      }
+    }
+  }
+}