okstra 0.173.0 → 0.174.0

package/runtime/templates/reports/settings.template.json

@@ -52,36 +52,12 @@
     "SessionEnd": [
       {
         "hooks": [
-          {
-            "type": "command",
-            "command": "$HOME/.okstra/bin/okstra-trace-cleanup.sh --reap"
-          },
           {
             "type": "command",
             "command": "$HOME/.okstra/bin/okstra-team-reconcile.sh --session-end"
           }
         ]
       }
-    ],
-    "SubagentStop": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "$HOME/.okstra/bin/okstra-subagent-reclaim.sh"
-          }
-        ]
-      }
-    ],
-    "TaskCompleted": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "$HOME/.okstra/bin/okstra-subagent-reclaim.sh"
-          }
-        ]
-      }
     ]
   }
 }

package/runtime/validators/lib/fixtures.sh

@@ -428,7 +428,7 @@ if WORKSPACE_ROOT:
     task_type = str(task_manifest.get("taskType", ""))
     sample_path = (
         Path(WORKSPACE_ROOT)
-        / "tests" / "fixtures" / "final-report-data"
+        / "tests" / "fixtures" / "final-report-data-v2"
         / f"{task_type}-001.data.json"
     )
     if sample_path.is_file():
@@ -439,6 +439,25 @@ if WORKSPACE_ROOT:
         sample["frontmatter"]["projectId"] = str(task_manifest.get("projectId", ""))
         sample["header"]["taskKey"] = str(task_manifest.get("taskKey", ""))
         sample["header"]["taskType"] = task_type
+        # The shipped fixture carries its own roster; this run's contract names
+        # a different one, and the validator compares the report's agent rows
+        # against that contract. Restate the rows under the contract's names so
+        # the fixture exercises the check instead of tripping over it.
+        _required = (
+            (run_manifest.get("teamContract") or {}).get("requiredAgentStatusEntries")
+            or (task_manifest.get("resultContract") or {}).get(
+                "requiredAgentStatusEntries"
+            )
+            or []
+        )
+        _rows = sample.get("executionStatus") or []
+        if _required and _rows:
+            # `agent` is the runtime (a schema enum); `role` carries the label the
+            # validator looks for in the rendered markdown.
+            sample["executionStatus"] = [
+                {**_rows[min(i, len(_rows) - 1)], "role": role}
+                for i, role in enumerate(_required)
+            ]
         name = report_path.name
         data_path = (
             report_path.with_name(name[:-3] + ".data.json")
@@ -452,23 +471,36 @@ if WORKSPACE_ROOT:
 
     import sys as _sys
     _sys.path.insert(0, str(Path(WORKSPACE_ROOT) / "scripts"))
-    try:
-        from okstra_ctl.report_views import RunMeta, render_html_view
-        css = (Path(WORKSPACE_ROOT) / "templates" / "reports" / "report.css").read_text(encoding="utf-8")
-        js = (Path(WORKSPACE_ROOT) / "templates" / "reports" / "report.js").read_text(encoding="utf-8")
-        render_html_view(
-            report_path,
-            run_meta=RunMeta(
-                task_key=str(task_manifest.get("taskKey", "validation/fixture")),
-                task_type=str(task_manifest.get("taskType", "validation")),
-                seq="001",
-                source_report=report_path.name,
-            ),
-            css=css,
-            js=js,
+    # The markdown seeded above this block predates the data.json contract, so
+    # re-render it from the data.json the fixture just wrote. Otherwise the pair
+    # disagrees and the validator's AI-handoff heading scan fails on a fixture
+    # that never claimed to be hand-authored.
+    if sample_path.is_file():
+        try:
+            from okstra_ctl.render_final_report import render_to_file
+
+            render_to_file(data_path, report_path)
+        except Exception as exc:  # pragma: no cover — fixture path only
+            raise SystemExit(f"failed to render final report in fixture: {exc}")
+    # Go through the same CLI the run uses, so the fixture picks the schema's
+    # own view (v2 task template) rather than a second copy of that choice.
+    import subprocess as _subprocess
+    _views = _subprocess.run(
+        [
+            _sys.executable,
+            str(Path(WORKSPACE_ROOT) / "scripts" / "okstra-render-report-views.py"),
+            str(report_path),
+            "--task-key", str(task_manifest.get("taskKey", "validation/fixture")),
+            "--task-type", str(task_manifest.get("taskType", "validation")),
+            "--seq", "001",
+        ],
+        capture_output=True,
+        text=True,
+    )
+    if _views.returncode != 0:
+        raise SystemExit(
+            f"failed to render report views in fixture: {_views.stderr or _views.stdout}"
         )
-    except Exception as exc:  # pragma: no cover — fixture path only
-        raise SystemExit(f"failed to render report views in fixture: {exc}")
 
 if final_status_path.exists():
     final_status_path.unlink()

package/runtime/validators/validate-implementation-plan-stages.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""S1–S11 checks for the Stage Map structure of an approved
+"""S1–S13 checks for the Stage Map structure of an approved
 implementation-planning final-report.md. Run from prepare_task_bundle
 of `implementation` task or standalone."""
 
@@ -43,9 +43,26 @@ EXIT_CONTRACT_HEADING = re.compile(r"^###\s+Stage Exit Contract\b", re.M)
 PATH_TOKEN = re.compile(r"(?:[\w.@-]+/)+[\w.@-]+")
 
 
+# S12 — a step command that reads an okstra artifact back out of a git object
+# (`git cat-file -e <rev>:.okstra/...`, `git show <rev>:.okstra/...`). `.okstra/**`
+# is never committed: `_implementation-executor.md` forbids `git add -f` and makes
+# a staged ignored path abort the commit, and `_implementation-verifier.md` reports
+# a committed `.okstra` path as a branch defect. A verification step built on such
+# a read can never pass, whatever the stage does.
+GIT_OBJECT_OKSTRA_READ = re.compile(
+    r"\bgit\b[^&|;]*?\b(?:cat-file|show|ls-tree|archive|grep)\b[^&|;]*?"
+    r"(?<![\w./@'\"-])[\w./@{}~^-]+:\.okstra/"
+)
+# S13 — a clean-worktree assertion built on a bare `git status`. okstra provisions
+# `.okstra`, the configured sync entries, and (for implementation) a nested stage
+# worktree into every task worktree, so a bare status is never empty there.
+BARE_GIT_STATUS = re.compile(r"\bgit\b[^&|;]*?\bstatus\b[^&|;]*?--(?:porcelain|short)\b")
+CLEAN_GATE_COMMAND = "okstra worktree-status --check-clean"
+
+
 @dataclass
 class ValidationError:
-    code: str   # S1..S11
+    code: str   # S1..S13
     stage: int  # 0 = global
     message: str
 
@@ -92,10 +109,14 @@ def _slice_stage_section(text: str, stage_number: int) -> str:
     return text[start: start + nxt.start()] if nxt else text[start:]
 
 
+STEP_COMMAND_CELL = 3
+
+
 def _effective_step_rows(section: str) -> List[List[str]]:
     """Effective (non header/divider/comment) rows of the `### Stepwise
     Execution Order` table, each as a list of stripped cells. Columns are
-    `step | action | files | command | expected`, so action is index 1."""
+    `step | action | files | command | outcome | expected`, so action is
+    index 1, command index 3, outcome index 4."""
     m = re.search(r"^###\s+Stepwise Execution Order\b", section, re.M)
     if not m:
         return []
@@ -267,6 +288,40 @@ def _check_red_green_steps(section: str, stage_number: int) -> List[ValidationEr
     return errs
 
 
+def _check_step_command(command: str, stage_number: int) -> List[ValidationError]:
+    """S12 / S13 over one step's `command` cell.
+
+    The command cell is what actually closes a step, so it has to be runnable
+    inside the worktree layout okstra provisions. Both rules reject a command
+    that can never pass there, regardless of what the stage implements.
+    """
+    errs: List[ValidationError] = []
+    if GIT_OBJECT_OKSTRA_READ.search(command):
+        errs.append(ValidationError("S12", stage_number,
+            "S12: step command reads an `.okstra/` path out of a git object — "
+            "`.okstra/**` is gitignored and never committed, so the read can "
+            "never resolve. Pass the artifact forward through the stage carry "
+            "sidecar / verifier result, or read it from the working tree"))
+    if BARE_GIT_STATUS.search(command):
+        errs.append(ValidationError("S13", stage_number,
+            "S13: step command asserts a clean worktree with a bare `git status` — "
+            "okstra provisions `.okstra`, the synced entries, and any nested stage "
+            f"worktree there, so it is never empty. Use `{CLEAN_GATE_COMMAND}`"))
+    return errs
+
+
+def _check_markdown_step_commands(
+    text: str, stages: List[StageMapStage]
+) -> List[ValidationError]:
+    """S12 / S13 over the rendered `### Stepwise Execution Order` rows."""
+    errs: List[ValidationError] = []
+    for s in stages:
+        for row in _effective_step_rows(_slice_stage_section(text, s.stage_number)):
+            if len(row) > STEP_COMMAND_CELL:
+                errs.extend(_check_step_command(row[STEP_COMMAND_CELL], s.stage_number))
+    return errs
+
+
 def _check_conformance_declaration(
     text: str, stages: List[StageMapStage]
 ) -> List[ValidationError]:
@@ -383,6 +438,7 @@ def collect_validation_errors(text: str) -> List[ValidationError]:
     if stages:
         errors.extend(_check_each_stage_section(text, stages))
         errors.extend(_check_slice_tdd(text, stages))
+        errors.extend(_check_markdown_step_commands(text, stages))
         errors.extend(_check_conformance_declaration(text, stages))
         errors.extend(_check_depends_on(stages))
         errors.extend(_check_parallel_safety(text, stages))
@@ -605,6 +661,10 @@ def collect_data_validation_errors(planning: dict) -> List[ValidationError]:
     }))
     for stage in stages:
         errors.extend(_check_data_slice_tdd(stage))
+        number = stage.get("stage") if isinstance(stage.get("stage"), int) else 0
+        for step in stage.get("stepwiseExecution") or []:
+            if isinstance(step, dict):
+                errors.extend(_check_step_command(str(step.get("command") or ""), number))
     return errors