okstra 0.173.0 → 0.175.1

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/templates/worker-prompt-preamble.md

@@ -2,6 +2,8 @@
 
 This file is the audience-specific contract for initial `analysis` workers. Read it end-to-end from the path selected by the dispatch prompt. Before doing work, also read the shared file named by `**Worker Error Contract Path:**`; that file is the only source for error-sidecar rules.
 
+Your identity is the stored role execution (`executionLabel`). Canonical roles are `leader`, `analyser`, `critic`, `designer`, `planner`, `implementer`, `verifier`, `report-writer`, and `translator`. `lead` and `executor` are compatibility aliases only.
+
 ## Required reading
 
 Read `analysis-packet.md`, the primary compact input, end-to-end. Source files named as fallback/evidence paths are read only when a finding needs to verify a citation, fill a packet gap, or resolve ambiguity. Do not read `final-report-template.md` or `final-report-schema.json`; analysis workers produce findings, not the final report.
@@ -27,7 +29,9 @@ Append one canonical JSON row to the audit sidecar for each command that produce
 
 - Evidence command: {"command":"npm run check","cwd":"<project-root>","exitCode":0,"outputSummary":"all checks passed"}
 
-Do not record commands used only to explore, including `rg`, `ls`, and file-opening commands. Do not record environment variable values, tokens, credentials, or authorization headers. `okstra worker-audit-check` rejects malformed command rows and rows containing potential sensitive material through `okstra_ctl.worker_audit_ledger`.
+Do not record commands used only to explore, including `rg`, `ls`, and file-opening commands. `okstra worker-audit-check` rejects malformed command rows through `okstra_ctl.worker_audit_ledger`.
+
+Write the command as you ran it. Nothing scans these rows for secrets, so a row is never refused for how a setting is named — `AUTH_MODE=off` and `TOKEN_TTL=60` record verbatim. What the row needs to carry is the command's shape, its keys; a value that must not be written down is yours to leave out or pass as a `$VAR` reference, and at execution time that value comes from the environment or from the person running the command.
 
 ## Anchor headers (lead-injected, BLOCKING)
 
@@ -50,7 +54,7 @@ Every initial analysis prompt begins with these generated anchors in this exact
 
 ## Worker output sections
 
-Every analysis result starts with YAML frontmatter containing the task identity and `workerId`, followed by a header with the actual `**Model:**` value. Then emit these sections in exact order:
+Every analysis result starts with YAML frontmatter containing the task identity, `participantRef`, `roleExecutionRef`, `executionLabel`, `invocationRef`, and `attempt`, followed by a header with the actual `**Model:**` value. Copy these execution fields from the generated prompt metadata; do not derive them from the provider or model name. Legacy v1 prompts may expose only `workerId`, which is a read-only compatibility projection and must not be written into a v2 result. Then emit these sections in exact order:
 
 1. Findings
 2. Missing Information or Assumptions

package/runtime/validators/lib/fixtures.sh

@@ -138,6 +138,7 @@ prompt_path.write_text(
             f"{target_worker_id}-errors.json",
             f"Assigned worker prompt history path: {prompt_relative}",
             "**Prompt Delivery Mode:** eager-include",
+            f"**Model:** Fixture worker, {target_worker.get('modelExecutionValue', '')}",
             f"- Primary analysis packet: `{analysis_packet_path}`",
             "",
             "# Initial Analysis Prompt",
@@ -222,7 +223,7 @@ for worker in team_state.get("workers", []):
     worker["reason"] = reason_by_worker_id.get(worker_id, "Validation fixture not used")
 
     prompt_relative = str(worker.get("promptPath", "")).strip()
-    if prompt_relative and worker_id != omitted_worker_id:
+    if prompt_relative:
         prompt_path = project_root / prompt_relative
         prompt_path.parent.mkdir(parents=True, exist_ok=True)
         prompt_lines = [
@@ -232,6 +233,7 @@ for worker in team_state.get("workers", []):
             f"{worker_id}-errors.json",
             f"Assigned worker prompt history path: {prompt_relative}",
             "**Prompt Delivery Mode:** eager-include",
+            f"**Model:** Fixture worker, {worker.get('modelExecutionValue', '')}",
         ]
         if worker_id != "report-writer":
             prompt_lines.append(
@@ -428,7 +430,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 +441,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 +473,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()
@@ -538,6 +572,7 @@ if WORKSPACE_ROOT:
         AgentInstructionSource,
         AgentInvocationRequest,
         agent_model_assignment_from_payload,
+        invocation_execution_identity_from_manifest,
         prepare_agent_invocation,
     )
     from okstra_ctl.dispatch_state import (
@@ -570,7 +605,7 @@ if WORKSPACE_ROOT:
     contract = run_manifest["agentContract"]
     reservation_root = project_root / contract["invocationReservationRootPath"]
     for worker in team_state.get("workers", []):
-        if not isinstance(worker, dict) or worker.get("status") != "completed":
+        if not isinstance(worker, dict):
             continue
         worker_id = str(worker.get("workerId") or "").strip()
         prompt_relative = str(worker.get("promptPath") or "").strip()
@@ -583,18 +618,37 @@ if WORKSPACE_ROOT:
         assignment_ref = f"initial/{worker_id}"
         invocation_id = f"validation-fixture-{worker_id}"
         invocation_prompt = reservation_root / f"{invocation_id}.prompt.md"
+        audience = (
+            "report-writer" if worker_id == "report-writer"
+            else analysis_audience
+        )
+        assignment = agent_model_assignment_from_payload(
+            assignments[assignment_ref]
+        )
+        identity = invocation_execution_identity_from_manifest(
+            run_manifest,
+            assignment=assignment,
+            assignment_ref=assignment_ref,
+            duty_id=audience,
+        )
+        identity_args = {
+            "participant_ref": (
+                identity.participant_ref if identity is not None else None
+            ),
+            "role_execution_ref": (
+                identity.role_execution_ref if identity is not None else None
+            ),
+            "duty_id": identity.duty_id if identity is not None else None,
+            "invocation_ref": invocation_id if identity is not None else None,
+            "attempt": 1,
+        }
         prepared = prepare_agent_invocation(AgentInvocationRequest(
             invocation_id=invocation_id,
-            worker_id=worker_id,
-            audience=(
-                "report-writer" if worker_id == "report-writer"
-                else analysis_audience
-            ),
+            worker_id=worker_id if identity is None else None,
+            audience=audience,
             assignment_ref=assignment_ref,
             purpose=None,
-            assignment=agent_model_assignment_from_payload(
-                assignments[assignment_ref]
-            ),
+            assignment=assignment,
             instruction=AgentInstruction(
                 anchor_lines=(),
                 body=source_prompt.read_text(encoding="utf-8"),
@@ -610,6 +664,7 @@ if WORKSPACE_ROOT:
                 invocation_prompt.name + ".meta.json"
             ),
             dispatch_kind="validation-fixture",
+            **identity_args,
         ))
         dispatch = record_verified_agent_dispatch(
             project_root=project_root,
@@ -621,11 +676,21 @@ if WORKSPACE_ROOT:
                 else "core-pre-dispatch"
             ),
         )
-        link_agent_dispatch_result(
-            project_root=project_root,
-            run_manifest_path=run_manifest_path,
-            dispatch_id=dispatch["dispatchId"],
-            result_path=project_root / result_relative,
-        )
+        if worker.get("status") == "completed":
+            link_agent_dispatch_result(
+                project_root=project_root,
+                run_manifest_path=run_manifest_path,
+                dispatch_id=dispatch["dispatchId"],
+                result_path=project_root / result_relative,
+            )
+
+# Preserve the workflow's historical missing-prompt negative after the v2
+# invocation record has captured the prompt bytes that were actually sent.
+for worker in team_state.get("workers", []):
+    if isinstance(worker, dict) and worker.get("workerId") == omitted_worker_id:
+        omitted_prompt = str(worker.get("promptPath") or "").strip()
+        if omitted_prompt:
+            (project_root / omitted_prompt).unlink(missing_ok=True)
+        break
 PY
 }

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