chore: publish from main

2026-08-15 05:36:57 +00:00 · 2026-08-12 00:18:34 +00:00
parent f23628ead6
commit 6bee42c094
6 changed files with 398 additions and 0 deletions
@@ -0,0 +1,40 @@
+# Machine-readable receipt contract
+
+Use JSON only when the user, CI, or another tool needs a structured artifact. Keep the normal final answer human-readable.
+
+## Required fields
+
+- `version`: integer `1`.
+- `status`: `verified`, `partial`, or `blocked`.
+- `problem`: concise defect and intended behavior.
+- `baseline`: object with `command`, `result`, and `evidence`.
+- `rootCause`: object with `summary` and at least one evidence item for `verified`.
+- `changes`: array of `{ "file", "summary" }` objects.
+- `verification`: array of `{ "command", "result", "evidence" }` objects.
+- `gaps`: array of explicit missing proof statements.
+
+Baseline results are `failed`, `observed`, or `not-run`. Verification results are `passed`, `failed`, or `not-run`.
+
+## Status invariants
+
+For `verified`:
+
+- Require an observed baseline: `failed` or `observed`, never `not-run`.
+- Require at least one concrete root-cause evidence item with `location` and `observation`.
+- Require at least one changed file or artifact.
+- Require at least one verification item.
+- Require every verification result to be `passed`.
+- Require `gaps` to be empty.
+
+For `partial`:
+
+- Preserve all evidence obtained.
+- Put every missing or inconclusive proof layer in `gaps`.
+- Never convert an unrun check into `passed`.
+
+For `blocked`:
+
+- Require at least one gap naming the external blocking condition.
+- Leave unperformed work empty or mark it `not-run`; do not speculate about the result.
+
+Validate against [receipt.schema.json](receipt.schema.json), run `node scripts/validate-receipt.mjs <file>` from the skill directory, or pipe JSON to `node scripts/validate-receipt.mjs - --json`.
@@ -0,0 +1,91 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://lmysticl.github.io/bug-receipt/receipt.schema.json",
+  "title": "Bug Receipt",
+  "description": "A machine-readable evidence receipt for a software bug fix.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "status", "problem", "baseline", "rootCause", "changes", "verification", "gaps"],
+  "properties": {
+    "version": { "const": 1 },
+    "status": { "enum": ["verified", "partial", "blocked"] },
+    "problem": { "$ref": "#/$defs/nonEmptyString" },
+    "baseline": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["command", "result", "evidence"],
+      "properties": {
+        "command": { "$ref": "#/$defs/nonEmptyString" },
+        "result": { "enum": ["failed", "observed", "not-run"] },
+        "evidence": { "$ref": "#/$defs/nonEmptyString" }
+      }
+    },
+    "rootCause": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["summary", "evidence"],
+      "properties": {
+        "summary": { "$ref": "#/$defs/nonEmptyString" },
+        "evidence": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["location", "observation"],
+            "properties": {
+              "location": { "$ref": "#/$defs/nonEmptyString" },
+              "observation": { "$ref": "#/$defs/nonEmptyString" }
+            }
+          }
+        }
+      }
+    },
+    "changes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["file", "summary"],
+        "properties": {
+          "file": { "$ref": "#/$defs/nonEmptyString" },
+          "summary": { "$ref": "#/$defs/nonEmptyString" }
+        }
+      }
+    },
+    "verification": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["command", "result", "evidence"],
+        "properties": {
+          "command": { "$ref": "#/$defs/nonEmptyString" },
+          "result": { "enum": ["passed", "failed", "not-run"] },
+          "evidence": { "$ref": "#/$defs/nonEmptyString" }
+        }
+      }
+    },
+    "gaps": { "type": "array", "items": { "$ref": "#/$defs/nonEmptyString" } }
+  },
+  "$defs": {
+    "nonEmptyString": { "type": "string", "minLength": 1, "pattern": "\\S" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "status": { "const": "verified" } }, "required": ["status"] },
+      "then": {
+        "properties": {
+          "baseline": { "type": "object", "properties": { "result": { "enum": ["failed", "observed"] } } },
+          "rootCause": { "type": "object", "properties": { "evidence": { "type": "array", "minItems": 1 } } },
+          "changes": { "type": "array", "minItems": 1 },
+          "verification": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "result": { "const": "passed" } } } },
+          "gaps": { "type": "array", "maxItems": 0 }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "status": { "enum": ["partial", "blocked"] } }, "required": ["status"] },
+      "then": { "properties": { "gaps": { "type": "array", "minItems": 1 } } }
+    }
+  ]
+}