commit a5d09c4d0ef9568c8b1145dc6030d77f44850cbb
parent 9ce167cf9425465bec77c86bdbb8f01ae577b396
Author: triesap <tyson@radroots.org>
Date: Mon, 21 Sep 2026 03:47:51 +0000
spec: establish per-step evidence reporting
Diffstat:
4 files changed, 119 insertions(+), 0 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
@@ -13,3 +13,23 @@
- if validation cannot run, report the blocker clearly instead of guessing past it
- toolchain: Mojo via the locally installed Modular toolchain
- prefer explicit typed models, deterministic behavior, and direct service boundaries over stringly or implicit behavior
+
+## hyf_v1_jev specification execution
+
+- Execute the owner-approved `hyf_v1_jev` handoff as a multi-RCLD sequence: one
+ active slice at a time, one tested/reviewed/known-good commit per step. Do not
+ merge, skip, reorder, broaden or auto-split steps.
+- The durable governing document, decision register, step ledger and step
+ evidence live under the parent monorepo `docs/` tree, not in this capsule:
+ `docs/execution/rcl/hyf-v1-jev-multi-rcld-sequence.md`,
+ `docs/execution/evidence/hyf_v1_jev/`.
+- Per step record a report; allowed result states are `PLANNED`, `IN_PROGRESS`,
+ `PASSED`, `FAILED`, `BLOCKED`, `NOT_RUN`, `NOT_APPLICABLE`. A step is `PASSED`
+ only with executed evidence; never label an unrun source/model/provider check
+ as passed.
+- A deviation requires repository evidence recorded in the deviation ledger
+ before proceeding; never silently skip or reorder.
+- Conditional Cargo is `N/A — Mojo core` unless a real relevant Rust workspace
+ is discovered.
+- Stage only owned paths; never `git add -A`; never stage `secrets.txt`.
+- Use `pixi run --frozen` for repo-owned tasks to avoid incidental lock rewrite.
diff --git a/tests/fixture_validator.mojo b/tests/fixture_validator.mojo
@@ -319,3 +319,68 @@ def validate_requirement_traceability(
)
return issues^
+
+
+def validate_step_states(path: String) raises -> List[FixtureValidationIssue]:
+ var issues = List[FixtureValidationIssue]()
+ var doc = loads(Path(path).read_text())
+ if not _has_key(doc, "states"):
+ issues.append(
+ FixtureValidationIssue(
+ case_id="", rule="missing_states", detail="no states declared"
+ )
+ )
+ return issues^
+
+ var states = List[String]()
+ for entry in doc["states"].array_items():
+ var state = entry.string_value()
+ var duplicate = False
+ for prior in states:
+ if prior == state:
+ duplicate = True
+ if duplicate:
+ issues.append(
+ FixtureValidationIssue(
+ case_id="", rule="duplicate_state", detail=state
+ )
+ )
+ states.append(String(state))
+
+ for required in ["PASSED", "NOT_RUN", "NOT_APPLICABLE"]:
+ var found = False
+ for state in states:
+ if state == required:
+ found = True
+ if not found:
+ issues.append(
+ FixtureValidationIssue(
+ case_id="", rule="missing_state", detail=required
+ )
+ )
+
+ if (
+ not _has_key(doc, "passed_requires_executed_evidence")
+ or not doc["passed_requires_executed_evidence"].bool_value()
+ ):
+ issues.append(
+ FixtureValidationIssue(
+ case_id="",
+ rule="passed_without_evidence",
+ detail="PASSED must require executed evidence",
+ )
+ )
+
+ if (
+ not _has_key(doc, "rules")
+ or len(doc["rules"].array_items()) == 0
+ ):
+ issues.append(
+ FixtureValidationIssue(
+ case_id="",
+ rule="missing_state_rules",
+ detail="state rules must be documented",
+ )
+ )
+
+ return issues^
diff --git a/tests/requirements/hyf_v1_jev.step_states.json b/tests/requirements/hyf_v1_jev.step_states.json
@@ -0,0 +1,11 @@
+{
+ "states": ["PLANNED", "IN_PROGRESS", "PASSED", "FAILED", "BLOCKED", "NOT_RUN", "NOT_APPLICABLE"],
+ "terminal_states": ["PASSED", "FAILED", "BLOCKED", "NOT_APPLICABLE"],
+ "passed_requires_executed_evidence": true,
+ "rules": [
+ "A step is PASSED only when its verification commands executed and passed.",
+ "NOT_RUN and NOT_APPLICABLE are never PASSED.",
+ "BLOCKED names the blocking external gate or missing authority.",
+ "A step is not counted in the pass total unless it is PASSED."
+ ]
+}
diff --git a/tests/test_traceability.mojo b/tests/test_traceability.mojo
@@ -7,6 +7,7 @@ from std.testing import TestSuite, assert_equal, assert_true
from fixture_validator import (
FixtureValidationIssue,
validate_requirement_traceability,
+ validate_step_states,
)
@@ -91,5 +92,27 @@ def test_requirement_traceability_accepts_registry_and_rejects_dangling() raises
)
+def test_step_state_contract_is_valid_and_rejects_corruption() raises:
+ var path = _dir_of_current_file() / "requirements" / "hyf_v1_jev.step_states.json"
+ assert_equal(len(validate_step_states(path.__fspath__())), 0)
+
+ with TemporaryDirectory() as temp_dir:
+ var base = Path(temp_dir)
+ _write(
+ base / "states.json",
+ '{"states":["PASSED","PASSED","NOT_RUN","NOT_APPLICABLE"],'
+ '"passed_requires_executed_evidence":true,"rules":["x"]}',
+ )
+ assert_true(len(validate_step_states((base / "states.json").__fspath__())) > 0)
+ with TemporaryDirectory() as temp_dir:
+ var base = Path(temp_dir)
+ _write(
+ base / "states.json",
+ '{"states":["PASSED","NOT_RUN","NOT_APPLICABLE"],'
+ '"passed_requires_executed_evidence":false,"rules":["x"]}',
+ )
+ assert_true(len(validate_step_states((base / "states.json").__fspath__())) > 0)
+
+
def main() raises:
TestSuite.discover_tests[__functions_in_module()]().run()
