Add a versioned invariant summary contract

pyproject.toml

@@ -10,7 +10,7 @@ requires-python = ">=3.10"
 dependencies = []
 
 [project.optional-dependencies]
-dev = ["pytest>=8.0"]
+dev = ["jsonschema>=4.23", "pytest>=8.0"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

skills/invariant-computation/README.md

@@ -111,6 +111,14 @@ outputs/<run_id>/
 └── RUN_SUMMARY.md
 ```
 
+The JSON summary has a
+[versioned schema](schema/invariant_summary.schema.json) and a
+[known-answer example](examples/invariant_summary.example.json).
+The schema requires either `classification_caveat` or
+`classification_theorem_evidence`. Heuristic, partial, and failed results must
+also record remaining uncertainty and a next repair route. Every result other
+than `failed` must provide a non-null `invariant.value`.
+
 Only create the files that the task needs.
 
 ## Safety And Review Rules
@@ -131,8 +139,10 @@ skills/
     README.md
     SKILL.md
     agents/openai.yaml
+    examples/
     manifest.yaml
     references/
+    schema/
 tests/
 ```
 
@@ -141,6 +151,7 @@ tests/
 Run:
 
 ```bash
+python3 -m pip install -e '.[dev]'
 python <path-to-skill-creator>/scripts/quick_validate.py skills/invariant-computation
 python3 -m unittest discover -s tests -v
 ```
@@ -149,4 +160,4 @@ Then check that repository docs point back to the package Skill and that no loca
 
 ## License
 
-See [LICENSE](LICENSE).
+See [LICENSE](../../LICENSE).

skills/invariant-computation/README.zh-CN.md

@@ -97,6 +97,13 @@ outputs/<run_id>/
 └── RUN_SUMMARY.md
 ```
 
+`invariant_summary.json` 提供
+[版本化 schema](schema/invariant_summary.schema.json)和
+[已知答案示例](examples/invariant_summary.example.json)。
+Schema 要求 `classification_caveat` 与 `classification_theorem_evidence`
+至少存在一项。启发式、部分完成和失败结果还必须记录剩余不确定性与下一步修复
+路线。除 `failed` 外，所有结果都必须提供非空的 `invariant.value`。
+
 只创建当前任务真正需要的文件。
 
 ## 安全与审查规则
@@ -117,8 +124,10 @@ skills/
     README.md
     SKILL.md
     agents/openai.yaml
+    examples/
     manifest.yaml
     references/
+    schema/
 tests/
 ```
 
@@ -127,6 +136,7 @@ tests/
 运行：
 
 ```bash
+python3 -m pip install -e '.[dev]'
 python <path-to-skill-creator>/scripts/quick_validate.py skills/invariant-computation
 python3 -m unittest discover -s tests -v
 ```
@@ -135,4 +145,4 @@ python3 -m unittest discover -s tests -v
 
 ## 许可证
 
-见 [LICENSE](LICENSE)。
+见 [LICENSE](../../LICENSE)。

skills/invariant-computation/SKILL.md

@@ -85,6 +85,11 @@ outputs/<run_id>/
 └── RUN_SUMMARY.md
 ```
 
+The JSON summary should validate against the
+[versioned schema](schema/invariant_summary.schema.json). Use the
+[known-answer example](examples/invariant_summary.example.json) as a shape
+reference, not as evidence for a new computation.
+
 9. Validate results using `references/validation_checks.md`.
 10. Report the invariant, assumptions, checks passed, checks failed, software versions, and what the invariant does not prove.
 
@@ -148,6 +153,7 @@ Every final report should include:
 - coefficient ring or field and conventions;
 - backend route and version evidence;
 - exact command or code path used;
+- a non-null invariant value unless the computation failed;
 - validation checks and their results;
 - unresolved ambiguity and next repair route;
-- a classification caveat unless classification is theorem-backed.
+- either a classification caveat or explicit theorem evidence supporting its omission.

skills/invariant-computation/examples/invariant_summary.example.json

@@ -0,0 +1,51 @@
+{
+  "schema_version": 1,
+  "object": {
+    "source": "Known-answer fixture: the boundary of a 2-simplex.",
+    "representation": "The maximal simplices are [0, 1], [1, 2], and [0, 2], with all faces included."
+  },
+  "invariant": {
+    "requested": "Betti numbers over Q",
+    "computed": "Betti numbers in degrees 0 and 1",
+    "value": {
+      "0": 1,
+      "1": 1
+    },
+    "result_quality": "exact"
+  },
+  "coefficient_ring_or_field": "Q",
+  "conventions": [
+    "unreduced homology",
+    "degrees not listed are zero"
+  ],
+  "backend": {
+    "route": "finite_complexes",
+    "name": "documented exact chain-complex reduction",
+    "version_evidence": "known-answer schema fixture version 1"
+  },
+  "command_or_code_path": "not applicable: format-only known-answer fixture",
+  "validation_checks": [
+    {
+      "name": "simplicial closure",
+      "kind": "structural",
+      "status": "passed",
+      "evidence": "All vertices of the three edges are included."
+    },
+    {
+      "name": "boundary-map ranks",
+      "kind": "invariant_cross_check",
+      "status": "passed",
+      "evidence": "Over Q, rank d_1 = 2 and rank d_2 = 0, so b_0 = 3 - 2 = 1 and b_1 = (3 - 2) - 0 = 1."
+    },
+    {
+      "name": "Euler characteristic",
+      "kind": "invariant_cross_check",
+      "status": "passed",
+      "evidence": "3 vertices - 3 edges = 0 = b_0 - b_1 = 1 - 1."
+    }
+  ],
+  "remaining_uncertainty": [],
+  "next_repair_route": null,
+  "classification_caveat": "Betti numbers alone do not classify finite simplicial complexes up to homotopy equivalence.",
+  "fixture_note": "This file demonstrates the result shape and is not evidence from a computation run."
+}