@evolith/core-domain 1.0.0 → 1.0.1

package/rulesets/schema/evolith-user-story.schema.json

@@ -0,0 +1,105 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://evolith.dev/schema/evolith-user-story.schema.json",
+  "title": "User Story Evolith",
+  "description": "JSON Schema for validating Evolith User Story artifacts. Atomic business-readable behavior specifications with BDD acceptance criteria.",
+  "type": "object",
+  "required": ["storyId", "title", "role", "action", "benefit", "acceptanceCriteria"],
+  "additionalProperties": false,
+  "properties": {
+    "storyId": {
+      "type": "string",
+      "pattern": "^(US|TS|EN|DEBT)-\\d{3}$",
+      "description": "Story ID following pattern: US-XXX (User Story), TS-XXX (Technical), EN-XXX (Enabler), DEBT-XXX (Debt)."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 10,
+      "description": "User-facing title in business language."
+    },
+    "type": {
+      "type": "string",
+      "enum": ["Functional", "Technical", "Enabler", "Debt"],
+      "default": "Functional"
+    },
+    "role": {
+      "type": "string",
+      "description": "Actor or persona who performs the action (As a...)."
+    },
+    "action": {
+      "type": "string",
+      "description": "Action to perform (I want to...)."
+    },
+    "benefit": {
+      "type": "string",
+      "description": "Business value or benefit (So that...)."
+    },
+    "epic": {
+      "type": "string",
+      "description": "Parent epic or initiative this story belongs to."
+    },
+    "boundedContext": {
+      "type": "string",
+      "description": "Domain bounded context this story belongs to."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+$",
+      "default": "1.0"
+    },
+    "acceptanceCriteria": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["scenario", "given", "when", "then"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string" },
+          "scenario": { "type": "string" },
+          "given": { "type": "string" },
+          "when": { "type": "string" },
+          "then": { "type": "string" }
+        }
+      },
+      "minItems": 1,
+      "description": "BDD-format acceptance criteria (Given/When/Then)."
+    },
+    "technicalRequirements": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "boundedContext": { "type": "string" },
+        "dependencies": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "External APIs, databases, or services this story depends on."
+        },
+        "nonFunctionalRequirements": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "status": {
+      "type": "string",
+      "enum": ["Draft", "Ready", "In Progress", "Done", "Blocked"],
+      "default": "Draft"
+    },
+    "priority": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 5,
+      "description": "Priority: 1 = highest priority."
+    },
+    "storyPoints": {
+      "type": "string",
+      "enum": ["S", "M", "L", "XL"],
+      "description": "T-Shirt size estimation."
+    },
+    "relatedADRs": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "ADR IDs that constrain or enable this story."
+    }
+  }
+}

package/rulesets/schema/evolith-yaml.schema.json

@@ -0,0 +1,191 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://evolith.dev/schema/evolith-yaml.schema.json",
+  "title": "Evolith Satellite Contract",
+  "description": "JSON Schema for validating satellite repository evolith.yaml files. This is the federated governance contract.",
+  "type": "object",
+  "required": ["apiVersion", "kind", "metadata", "spec"],
+  "additionalProperties": false,
+  "properties": {
+    "apiVersion": {
+      "type": "string",
+      "const": "evolith.dev/v1",
+      "description": "Evolith API version. Must be evolith.dev/v1."
+    },
+    "kind": {
+      "type": "string",
+      "const": "Satellite",
+      "description": "Kind of Evolith resource. Must be Satellite."
+    },
+    "metadata": {
+      "type": "object",
+      "required": ["name", "phase", "architectureVersion"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z0-9-]+$",
+          "description": "Satellite repository name. kebab-case, lowercase."
+        },
+        "phase": {
+          "type": "string",
+          "enum": ["F1", "F2", "F3"],
+          "description": "Current progressive-axis compatibility phase: F1=modular-monolith, F2=distributed-modules, F3=microservices. Other topology dimensions are resolved through topology manifests."
+        },
+        "architectureVersion": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$",
+          "description": "Satellite's own semantic version for tracking architectural changes."
+        }
+      }
+    },
+    "spec": {
+      "type": "object",
+      "required": ["coreRef", "runtime", "sdlc", "compliance"],
+      "additionalProperties": false,
+      "properties": {
+        "coreRef": {
+          "type": "object",
+          "required": ["version", "rulesetVersion"],
+          "additionalProperties": false,
+          "properties": {
+            "version": {
+              "type": "string",
+              "pattern": "^\\d+\\.\\d+\\.\\d+$",
+              "description": "Evolith Core version this satellite inherits from."
+            },
+            "rulesetVersion": {
+              "type": "string",
+              "pattern": "^\\d+\\.\\d+\\.\\d+$",
+              "description": "Specific ruleset version from Core that this satellite pins to."
+            },
+            "inheritancePath": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Chain of inheritance if satellite extends another satellite."
+            }
+          }
+        },
+        "runtime": {
+          "type": "object",
+          "required": ["language", "framework"],
+          "additionalProperties": false,
+          "properties": {
+            "language": {
+              "type": "string",
+              "enum": ["TypeScript", "CSharp", "Kotlin", "Go", "Python"],
+              "description": "Primary implementation language."
+            },
+            "framework": {
+              "type": "string",
+              "description": "Framework used (e.g., NestJS, ASP.NET Core, Spring Boot)."
+            },
+            "runtimeVersion": {
+              "type": "string",
+              "description": "Runtime version (e.g., Node 20, .NET 8, Android API 34)."
+            }
+          }
+        },
+        "sdlc": {
+          "type": "object",
+          "required": ["currentPhase", "gates"],
+          "additionalProperties": false,
+          "properties": {
+            "currentPhase": {
+              "type": "integer",
+              "enum": [1, 2, 3, 4, 5],
+              "description": "Current SDLC phase (1=Conception, 2=Design, 3=Construction, 4=Validation, 5=Delivery)."
+            },
+            "gates": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "businessSignOff": { "type": "string", "format": "date" },
+                "designBaseline": { "type": "string", "format": "date" },
+                "successfulBuild": { "type": "string", "format": "date" },
+                "rcStamped": { "type": "string", "format": "date" },
+                "productionLive": { "type": "string", "format": "date" }
+              }
+            }
+          }
+        },
+        "boundedContexts": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "phase"],
+            "additionalProperties": false,
+            "properties": {
+              "name": { "type": "string" },
+              "phase": { "type": "string", "enum": ["F1", "F2", "F3"] },
+              "persistence": {
+                "type": "string",
+                "enum": ["PostgreSQL", "MongoDB", "SQLServer", "SQLite"]
+              }
+            }
+          },
+          "description": "Bounded contexts defined in this satellite."
+        },
+        "compliance": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "adrRegistry": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Local ADRs maintained by this satellite (not yet promoted to Core). Each ADR file must have 'EvolithSatellite' in frontmatter tags to distinguish from Core ADRs."
+            },
+            "localAdrTagEnforcement": {
+              "type": "string",
+              "enum": ["enforced", "documented"],
+              "default": "enforced",
+              "description": "Whether local ADR tag enforcement is automated (enforced) or documented only. Defaults to enforced."
+            },
+            "coverageTarget": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 100,
+              "description": "Coverage target for this satellite (minimum 80)."
+            },
+            "qualityWaivers": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "criterion": { "type": "string" },
+                  "justification": { "type": "string" },
+                  "expires": { "type": "string", "format": "date" }
+                }
+              },
+              "description": "Active quality waivers with expiration dates."
+            }
+          }
+        },
+        "governance": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "executiveSponsor": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "name": { "type": "string" },
+                "role": { "type": "string" },
+                "email": { "type": "string", "format": "email" },
+                "lastReviewDate": { "type": "string", "format": "date" }
+              },
+              "description": "Executive sponsor responsible for quarterly governance review. Required for SPACE-05 metric compliance."
+            },
+            "nextReviewDate": {
+              "type": "string",
+              "format": "date",
+              "description": "Date of next scheduled governance review."
+            }
+          },
+          "description": "Executive governance metadata for scorecard metrics."
+        }
+      }
+    }
+  }
+}

package/rulesets/schema/functional-story.schema.json

@@ -0,0 +1,111 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://evolith.dev/schema/functional-story.schema.json",
+  "title": "Functional Story",
+  "description": "JSON Schema for validating Evolith Functional Story artifacts. Business-readable behavior specs separate from implementation.",
+  "type": "object",
+  "required": ["id", "title", "type", "version", "boundedContext", "actors", "businessRules", "acceptanceCriteria"],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^FS-\\d{3}$",
+      "description": "Functional Story ID following pattern FS-XXX."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 10,
+      "description": "User-facing title describing the capability in business language."
+    },
+    "type": {
+      "type": "string",
+      "enum": ["Functional", "Technical", "Enabler", "Debt"],
+      "description": "Story type classification."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semantic version of this story document."
+    },
+    "status": {
+      "type": "string",
+      "enum": ["Draft", "Ready", "In Progress", "Done", "Blocked"],
+      "default": "Draft"
+    },
+    "boundedContext": {
+      "type": "string",
+      "description": "Domain bounded context this story belongs to."
+    },
+    "epic": {
+      "type": "string",
+      "description": "Epic or initiative this story belongs to."
+    },
+    "actors": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["actor", "role"],
+        "additionalProperties": false,
+        "properties": {
+          "actor": { "type": "string" },
+          "role": { "type": "string" },
+          "goal": { "type": "string" }
+        }
+      },
+      "minItems": 1,
+      "description": "Primary and secondary actors interacting with this capability."
+    },
+    "businessRules": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Invariant business rules that must always hold."
+    },
+    "acceptanceCriteria": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["criteria", "given", "when", "then"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string" },
+          "criteria": { "type": "string" },
+          "given": { "type": "string" },
+          "when": { "type": "string" },
+          "then": { "type": "string" }
+        }
+      },
+      "minItems": 1,
+      "description": "BDD-format acceptance criteria (Given/When/Then)."
+    },
+    "nonFunctionalExpectations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["category", "expectation"],
+        "additionalProperties": false,
+        "properties": {
+          "category": {
+            "type": "string",
+            "enum": ["Performance", "Security", "Scalability", "Observability"]
+          },
+          "expectation": { "type": "string" }
+        }
+      },
+      "description": "NFE expectations from SDLC Quality Gates that apply to this story."
+    },
+    "relatedADRs": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "ADRs that constrain or enable this story."
+    },
+    "technicalStories": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^TS-\\d{3}$" },
+      "description": "Technical Story IDs that trace back to this Functional Story."
+    },
+    "parentPRD": {
+      "type": "string",
+      "description": "Parent PRD ID that authorized this story."
+    }
+  }
+}

package/rulesets/schema/gate-evidence.schema.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://evolith.dev/schema/gate-evidence.schema.json",
+  "title": "Gate Evidence",
+  "description": "Structured evidence returned by every phase-gate evaluation, as ratified by core/ADR-0073. This is the canonical `data` payload for gate evaluation across CLI, MCP, and REST surfaces.",
+  "type": "object",
+  "required": [
+    "gateId",
+    "phase",
+    "verdict",
+    "rulesetRef",
+    "rulesetVersion",
+    "violations",
+    "evaluatedAt",
+    "evaluatedBy"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "gateId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Stable identifier of the evaluated gate (e.g. 'design-baseline-approved')."
+    },
+    "phase": {
+      "type": "string",
+      "enum": ["discovery", "design", "construction", "qa", "release"],
+      "description": "SDLC phase the gate belongs to."
+    },
+    "verdict": {
+      "type": "string",
+      "enum": ["passed", "failed", "skipped"],
+      "description": "Evaluation outcome. 'failed' is mandatory when any violation has severity 'error'."
+    },
+    "rulesetRef": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Reference to the Evolith Core ruleset evaluated (e.g. 'rulesets/sdlc/phase-gates.rules.json')."
+    },
+    "rulesetVersion": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Version of the referenced ruleset at evaluation time, taken from its 'version' field."
+    },
+    "violations": {
+      "type": "array",
+      "description": "Every rule violation found. Empty array when the gate passes cleanly.",
+      "items": {
+        "type": "object",
+        "required": ["ruleId", "severity", "location", "message"],
+        "additionalProperties": false,
+        "properties": {
+          "ruleId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Identifier of the violated rule within the referenced ruleset."
+          },
+          "severity": {
+            "type": "string",
+            "enum": ["error", "warning"],
+            "description": "'error' blocks the gate; 'warning' is advisory."
+          },
+          "location": {
+            "type": "string",
+            "description": "Where the violation was found (file path, artifact name, or logical location)."
+          },
+          "message": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Actionable human-readable explanation of the violation."
+          }
+        }
+      }
+    },
+    "evaluatedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of the evaluation."
+    },
+    "evaluatedBy": {
+      "type": "string",
+      "enum": ["human", "agent", "ci"],
+      "description": "Actor class that triggered the evaluation."
+    }
+  }
+}

package/rulesets/schema/integration-evidence.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://evolith.dev/schema/integration-evidence.schema.json",
+  "title": "Integration Evidence",
+  "description": "JSON Schema for the Integration Evidence artifact required by the RC Stamped gate (Phase 4). Demonstrates that every declared inter-component contract was exercised against a real or contract-tested counterpart.",
+  "type": "object",
+  "required": ["releaseCandidate", "evaluatedAt", "integrations", "result"],
+  "additionalProperties": false,
+  "properties": {
+    "releaseCandidate": { "type": "string" },
+    "evaluatedAt": { "type": "string", "format": "date-time" },
+    "evaluator": { "type": "string" },
+    "integrations": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "producer", "consumer", "contract", "testKind", "result"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string" },
+          "producer": { "type": "string", "description": "Service or component emitting the contract." },
+          "consumer": { "type": "string", "description": "Service or component consuming the contract." },
+          "contract": { "type": "string", "description": "Reference to the contract artifact (OpenAPI, AsyncAPI, GraphQL SDL, Avro/Proto schema)." },
+          "testKind": { "type": "string", "enum": ["contract", "consumer-driven", "end-to-end", "synthetic"] },
+          "result": { "type": "string", "enum": ["PASS", "FAIL", "WAIVED"] },
+          "evidence": { "type": "string", "description": "Link to the run log, test report, or contract verifier output." }
+        }
+      }
+    },
+    "result": { "type": "string", "enum": ["PASS", "FAIL", "WAIVED"] },
+    "waivers": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["integrationId", "justification", "owner", "expirationDate"],
+        "additionalProperties": false,
+        "properties": {
+          "integrationId": { "type": "string" },
+          "justification": { "type": "string" },
+          "owner": { "type": "string" },
+          "expirationDate": { "type": "string", "format": "date" }
+        }
+      }
+    }
+  }
+}

package/rulesets/schema/knowledge-intake.schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://evolith.dev/schema/knowledge-intake.schema.json",
+  "title": "External Knowledge Intake Candidate",
+  "type": "object",
+  "required": ["knowledge_id", "source", "assessment", "promotion", "review", "synthesis"],
+  "properties": {
+    "knowledge_id": { "type": "string", "pattern": "^KI-[A-Z0-9-]+$" },
+    "source_registry_id": { "type": "string", "pattern": "^SRC-[A-Z0-9-]+$" },
+    "source": {
+      "type": "object",
+      "required": ["class", "author", "work", "locator", "retrieved_at", "rights_status"],
+      "properties": {
+        "class": { "enum": ["book", "public-article", "official-docs"] },
+        "author": { "type": "string", "minLength": 1 },
+        "work": { "type": "string", "minLength": 1 },
+        "locator": { "type": "string", "minLength": 1 },
+        "retrieved_at": { "type": "string", "format": "date" },
+        "rights_status": { "enum": ["citation-and-synthesis-only", "public-reference", "official-documentation"] }
+      },
+      "additionalProperties": false
+    },
+    "assessment": {
+      "type": "object",
+      "required": ["trust_level", "portability", "topologies", "maturity", "concerns"],
+      "properties": {
+        "trust_level": { "enum": ["primary", "secondary"] },
+        "portability": { "enum": ["high", "medium", "low"] },
+        "topologies": { "type": "array", "minItems": 1, "items": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } },
+        "maturity": { "enum": ["standard", "emerging", "proven", "speculative"] },
+        "preconditions": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "anti_patterns": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "alternatives": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "related_topologies": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } },
+        "concerns": { "type": "array", "minItems": 1, "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "promotion": {
+      "type": "object",
+      "required": ["status"],
+      "properties": {
+        "status": { "enum": ["candidate", "evaluated", "accepted", "executable", "retired"] },
+        "promoted_at": { "type": ["string", "null"], "format": "date" },
+        "promoted_by": { "type": ["string", "null"] },
+        "adr": { "type": ["string", "null"] },
+        "native_rule": { "type": ["string", "null"] },
+        "opa_policy": { "type": ["string", "null"] },
+        "fixtures": { "type": "array", "items": { "type": "string" } },
+        "disposition": { "type": ["string", "null"] }
+      },
+      "additionalProperties": false
+    },
+    "review": {
+      "type": "object",
+      "required": ["owner", "next_review_at", "review_freshness"],
+      "properties": {
+        "owner": { "const": "@winston" },
+        "next_review_at": { "type": "string", "format": "date" },
+        "review_freshness": { "type": "string", "format": "date" }
+      },
+      "additionalProperties": false
+    },
+    "synthesis": { "type": "string", "minLength": 40, "maxLength": 3000 }
+  },
+  "additionalProperties": false
+}

package/rulesets/schema/knowledge-projection.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://evolith.dev/schema/knowledge-projection.schema.json",
+  "title": "Approved Knowledge Projection",
+  "description": "Explicit projection of KI-* candidates approved for RAG retrieval.",
+  "type": "object",
+  "required": ["projection_version", "approved_knowledge_ids", "generated_at"],
+  "properties": {
+    "projection_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "approved_knowledge_ids": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^KI-[A-Z0-9-]+$" },
+      "uniqueItems": true
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date"
+    }
+  },
+  "additionalProperties": false
+}