@hellraisercenobit/ai-engineering-gate 0.8.0

package/contracts/schemas/decision-envelope.schema.json

@@ -0,0 +1,215 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/hellraisercenobit/skills/blob/main/contracts/schemas/decision-envelope.schema.json",
+  "title": "Decision record envelope 1.0.0",
+  "description": "The outer shape every dimension's decision record shares. Enforcement validates a record against this envelope and against the dimension's own schema; the dimension-specific body stays opaque here. Applicability is not a record field: it lives in the declaration.",
+  "type": "object",
+  "required": [
+    "dimension",
+    "schemaVersion",
+    "catalogVersion",
+    "contractVersions",
+    "need",
+    "scope",
+    "base",
+    "revision",
+    "cites",
+    "plans"
+  ],
+  "properties": {
+    "dimension": {
+      "type": "string",
+      "minLength": 1
+    },
+    "schemaVersion": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "catalogVersion": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "contractVersions": {
+      "description": "The contract versions this record's member supports.",
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^\\d+\\.\\d+\\.\\d+$"
+      }
+    },
+    "need": {
+      "type": "string",
+      "minLength": 1
+    },
+    "scope": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "base": {
+      "type": "string",
+      "minLength": 1
+    },
+    "revision": {
+      "$ref": "#/$defs/revision"
+    },
+    "cites": {
+      "description": "Artifacts and evidence sources that exist when the record is validated. A dangling path refuses the record; every cited path is hashed with the revision.",
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/citation"
+      }
+    },
+    "plans": {
+      "description": "Artifacts the record commits to produce. Not checked when the record is written, so a record can precede the first affected write; required to exist before a review begins, is filed or is dispatched.",
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/plan"
+      }
+    }
+  },
+  "$defs": {
+    "citation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "path",
+        "checkedAt",
+        "claim",
+        "covers"
+      ],
+      "properties": {
+        "path": {
+          "description": "A repository-relative path, or a path under the task's evidence. Both are checked for existence.",
+          "type": "string",
+          "minLength": 1
+        },
+        "checkedAt": {
+          "type": "string",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+        },
+        "claim": {
+          "type": "string",
+          "minLength": 1
+        },
+        "covers": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "searched": {
+          "description": "Paths consulted and not found. Present when the citation supports a claim of unknown about a checkable fact.",
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "plan": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "path",
+        "role"
+      ],
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "role": {
+          "description": "A role the dimension defines. Testing patterns uses `test` and `production` so a replay knows which files stand alone.",
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "revision": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "number",
+        "previous",
+        "reason"
+      ],
+      "properties": {
+        "number": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "previous": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "minLength": 1
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 1
+        },
+        "changed": {
+          "description": "The cited paths this revision changed. Enforcement verifies their hashes differ from the previous revision's snapshot; absent, at least one cited path must differ.",
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "addresses": {
+          "description": "Finding identifiers this revision closes. A judgment finding is closed by a revision that cites it together with a moved state.",
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "number": {
+                "type": "integer",
+                "minimum": 2
+              }
+            },
+            "required": [
+              "number"
+            ]
+          },
+          "then": {
+            "properties": {
+              "previous": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          },
+          "else": {
+            "properties": {
+              "previous": {
+                "type": "null"
+              }
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/contracts/schemas/declaration.schema.json

@@ -0,0 +1,190 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/hellraisercenobit/skills/blob/main/contracts/schemas/declaration.schema.json",
+  "title": "Dimension declaration 1.0.0",
+  "description": "One per registered dimension per task, written through `declare` before any decision record. It states whether the dimension applies, on which paths, for which request and under which constraints. A non-applicable dimension has a declaration and nothing else.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "document",
+    "documentVersion",
+    "dimension",
+    "applicability",
+    "reason",
+    "request",
+    "constraints",
+    "revision"
+  ],
+  "properties": {
+    "document": {
+      "const": "declaration"
+    },
+    "documentVersion": {
+      "const": "1.0.0"
+    },
+    "dimension": {
+      "description": "A dimension identifier the member manifest registers.",
+      "type": "string",
+      "minLength": 1
+    },
+    "applicability": {
+      "enum": [
+        "applicable",
+        "non-applicable"
+      ]
+    },
+    "reason": {
+      "description": "Why the dimension applies, or why it does not. Never empty: skipping a dimension is a recorded decision.",
+      "type": "string",
+      "minLength": 1
+    },
+    "request": {
+      "description": "The requester's own wording, without builder choices or rationale. The neutral brief is rendered from it.",
+      "type": "string",
+      "minLength": 1
+    },
+    "constraints": {
+      "description": "Factual constraints only: project targets, public contracts, independent sources. When tests are TypeScript, name the ES/compiler target as a factual string (example: compiler: TypeScript 4.0.5, target ES2015, lib es2015, strict off). A tsconfig path in scope.configuration is not a substitute. PHP and other non-TypeScript suites omit this constraint rather than invent one.",
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "base": {
+      "$ref": "#/$defs/base"
+    },
+    "scope": {
+      "$ref": "#/$defs/scope"
+    },
+    "revision": {
+      "$ref": "#/$defs/revision"
+    }
+  },
+  "$defs": {
+    "base": {
+      "description": "The comparison base. Required when the dimension applies; the change set is the diff from its merge-base with HEAD.",
+      "type": "string",
+      "minLength": 1
+    },
+    "scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "paths"
+      ],
+      "properties": {
+        "paths": {
+          "description": "Repository-relative file paths or directory prefixes the dimension protects.",
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "configuration": {
+          "description": "Repository-relative configuration files the decisions depend on. They enter the source fingerprint.",
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "revision": {
+      "description": "Same shape as a decision record's revision: revision 1 has no previous, a later one names it.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "number",
+        "previous",
+        "reason"
+      ],
+      "properties": {
+        "number": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "previous": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "minLength": 1
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "number": {
+                "type": "integer",
+                "minimum": 2
+              }
+            },
+            "required": [
+              "number"
+            ]
+          },
+          "then": {
+            "properties": {
+              "previous": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          },
+          "else": {
+            "properties": {
+              "previous": {
+                "type": "null"
+              }
+            }
+          }
+        }
+      ]
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "applicability": {
+            "const": "applicable"
+          }
+        },
+        "required": [
+          "applicability"
+        ]
+      },
+      "then": {
+        "required": [
+          "scope",
+          "base"
+        ],
+        "properties": {
+          "scope": {
+            "$ref": "#/$defs/scope"
+          },
+          "base": {
+            "$ref": "#/$defs/base"
+          }
+        }
+      },
+      "else": {
+        "properties": {
+          "scope": false,
+          "base": false
+        }
+      }
+    }
+  ]
+}

package/contracts/schemas/dispute.schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/hellraisercenobit/skills/blob/main/contracts/schemas/dispute.schema.json",
+  "title": "Dispute 1.0.0",
+  "description": "The builder's second and only other response to a finding, beside addressing it. It contests one finding with a pointer to counter-evidence that already exists; a dispute without such a pointer is refused. It goes to the user and its only exit is an arbitration.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "document",
+    "documentVersion",
+    "dimension",
+    "report",
+    "finding",
+    "counterEvidence",
+    "position"
+  ],
+  "properties": {
+    "document": {
+      "const": "dispute"
+    },
+    "documentVersion": {
+      "const": "1.0.0"
+    },
+    "dimension": {
+      "type": "string",
+      "minLength": 1
+    },
+    "report": {
+      "description": "The identifier of the report that carries the contested finding.",
+      "type": "string",
+      "minLength": 1
+    },
+    "finding": {
+      "description": "The contested finding's identifier.",
+      "type": "string",
+      "minLength": 1
+    },
+    "counterEvidence": {
+      "description": "Pointers to artifacts that exist now. Each path is checked; a dangling pointer refuses the dispute.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "path",
+          "claim"
+        ],
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 1
+          },
+          "claim": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "position": {
+      "description": "The builder's position in one sentence.",
+      "type": "string",
+      "minLength": 1
+    }
+  }
+}

package/contracts/schemas/evidence-append.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/hellraisercenobit/skills/blob/main/contracts/schemas/evidence-append.schema.json",
+  "title": "Evidence append 1.0.0",
+  "description": "Append-only. Journal events, check outputs, snapshots and any artifact a record planned are filed through `evidence append`, never written into the gate's index by hand. The gate stamps every append with the content hashes of the record's planned artifacts, by role, so an event proves the state of test and production artifacts at the moment it was filed.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "document",
+    "documentVersion",
+    "dimension",
+    "record",
+    "kind",
+    "payload"
+  ],
+  "properties": {
+    "document": {
+      "const": "evidence-append"
+    },
+    "documentVersion": {
+      "const": "1.0.0"
+    },
+    "dimension": {
+      "type": "string",
+      "minLength": 1
+    },
+    "record": {
+      "description": "The decision record this evidence belongs to.",
+      "type": "string",
+      "minLength": 1
+    },
+    "kind": {
+      "description": "A kind the member's evidence schemas name, which then validates the payload, or one of the generic kinds.",
+      "type": "string",
+      "minLength": 1
+    },
+    "produces": {
+      "description": "The planned artifact this append produces or extends. A planned artifact is satisfied by a file in the worktree or by an append that names it here.",
+      "type": "string",
+      "minLength": 1
+    },
+    "payload": {
+      "description": "Opaque to the envelope. Validated against the member's evidence schema when its kind names one."
+    },
+    "filedAt": {
+      "description": "Stamped by the gate when the append is stored.",
+      "type": "string",
+      "minLength": 1
+    },
+    "artifactHashes": {
+      "description": "Stamped by the gate: the content hash of every artifact the record planned, grouped by role, at the moment of the append.",
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "builder": {
+      "description": "Stamped by the gate: the identity it captured for the caller.",
+      "type": "object"
+    },
+    "replayed": {
+      "description": "Stamped by the gate: `true` only when the gate itself ran the scenario through `replay`.",
+      "type": "boolean"
+    }
+  }
+}