okstra 0.130.1 → 0.130.3

package/runtime/python/okstra_ctl/convergence_migration.py

@@ -10,6 +10,7 @@ from typing import Any, Literal, Mapping
 
 from .convergence_engine import (
     ConvergenceContractError,
+    FINAL_SCHEMA_VERSION,
     grouped_input_digest,
     validate_final_state,
     validate_working_state,
@@ -45,7 +46,14 @@ def decide_seed_action(
     digest = grouped_input_digest(grouped_input)
     final_status, final_value = _inspect_final(final_state_path)
     if final_status == "terminal":
-        return SeedDecision("reuse-final", None, None, "valid terminal final state")
+        assert final_value is not None
+        version = final_value.get("schemaVersion")
+        reason = (
+            f"valid historical final {version} reused without rewrite"
+            if version != FINAL_SCHEMA_VERSION
+            else "valid terminal final state"
+        )
+        return SeedDecision("reuse-final", None, None, reason)
 
     work_status, work_value = _inspect_work(work_state_path)
     invalid_final = final_status == "invalid"

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -21,12 +21,15 @@ from .worker_prompt_headers import WorkerPromptHeaderError, worker_prompt_header
 from .worker_prompt_body import analysis_prompt_body
 from .worker_prompt_contract import PromptRecord, validate_initial_prompt_records
 from .worker_prompt_policy import resolve_prompt_plan_for_manifest
+from .worker_artifact_paths import audit_sidecar_rel
 from .wrapper_status import read_wrapper_status, status_path_for_prompt
 
 
 BACKEND_CLI_WRAPPER = "cli-wrapper"
 BACKEND_TMUX_PANE = "tmux-pane"
 BACKEND_MIXED = "mixed"
+LIVENESS_AUDIT_HEARTBEAT = "audit-heartbeat"
+LIVENESS_WRAPPER_STATUS = "wrapper-status"
 MAX_WORKER_ATTEMPTS = 2
 REPORT_WRITER_WORKER_ID = "report-writer"
 TERMINAL_DISPATCH_STATUSES = {"completed", "timeout", "error", "not-run"}
@@ -556,6 +559,10 @@ def _dispatch_record(
         "promptPath": str(job.prompt_path),
         "resultPath": str(job.result_path),
         "workerResultPath": str(job.worker_result_path),
+        "auditSidecarPath": audit_sidecar_rel(str(job.worker_result_path)),
+        "livenessMode": _liveness_mode(
+            BACKEND_CLI_WRAPPER if degraded_from else job.backend
+        ),
         "statusSidecarPath": str(status_path_for_prompt(job.prompt_path)),
         "degradedFrom": degraded_from,
         "reason": reason,
@@ -566,6 +573,12 @@ def _dispatch_record(
     }
 
 
+def _liveness_mode(backend: str) -> str:
+    if backend in (BACKEND_CLI_WRAPPER, BACKEND_TMUX_PANE):
+        return LIVENESS_WRAPPER_STATUS
+    return LIVENESS_AUDIT_HEARTBEAT
+
+
 def _update_dispatch_status(
     team_state_path: Path, worker_id: str, kind: str, attempt: int, status: str, reason: str
 ) -> None:

package/runtime/python/okstra_ctl/plan_items.py

@@ -0,0 +1,203 @@
+"""Deterministic extraction of implementation-planning verification items."""
+from __future__ import annotations
+
+from collections.abc import Mapping
+from copy import deepcopy
+from typing import Any
+
+from .design_surfaces import (
+    DesignSurfaceError,
+    detect_design_surfaces,
+    expected_prep_plan_item_id,
+)
+
+
+class PlanItemContractError(ValueError):
+    """The implementation-planning body cannot produce exact plan items."""
+
+
+PLAN_ITEM_SOURCES = (
+    ("optionCandidates", "P-Opt", "4.5.1"),
+    ("stepwiseExecution", "P-Step", "4.5.4"),
+    ("dependencyMigrationRisk", "P-Dep", "4.5.5"),
+    ("validationChecklist", "P-Val", "4.5.6"),
+    ("rollbackStrategy", "P-Rb", "4.5.7"),
+    ("requirementCoverage", "P-Req", "4.5.8"),
+)
+
+_SUBJECT_FIELDS = {
+    "optionCandidates": ("subject", "name", "title", "action"),
+    "stepwiseExecution": ("subject", "action", "title", "name"),
+    "dependencyMigrationRisk": ("subject", "item", "title", "name", "action"),
+    "validationChecklist": ("subject", "check", "title", "name", "action"),
+    "rollbackStrategy": ("subject", "action", "title", "name"),
+    "requirementCoverage": ("subject", "requirement", "title", "name", "action"),
+}
+
+
+def _non_empty_string(value: object) -> str | None:
+    if isinstance(value, str) and value.strip():
+        return value
+    return None
+
+
+def _subject(row: Mapping[str, Any], source: str) -> str:
+    for field in _SUBJECT_FIELDS[source]:
+        value = _non_empty_string(row.get(field))
+        if value is not None:
+            return value
+    raise PlanItemContractError(f"{source} row has no non-empty subject candidate")
+
+
+def _ticket_id(row: Mapping[str, Any]) -> str:
+    return _non_empty_string(row.get("ticketId")) or ""
+
+
+def _row_payload(row: Mapping[str, Any], **coordinates: int) -> dict[str, Any]:
+    payload = deepcopy(dict(row))
+    for field, value in coordinates.items():
+        existing = payload.get(field)
+        if field in payload and existing != value:
+            raise PlanItemContractError(
+                f"row {field} coordinate {existing!r} conflicts with {value!r}"
+            )
+        payload[field] = value
+    return payload
+
+
+def _add_item(items: list[dict[str, Any]], item: dict[str, Any]) -> None:
+    if any(existing["id"] == item["id"] for existing in items):
+        raise PlanItemContractError(f"duplicate plan item ID: {item['id']}")
+    items.append(item)
+
+
+def _rows(planning: Mapping[str, Any], source: str) -> list[Mapping[str, Any]]:
+    value = planning.get(source, [])
+    if value is None:
+        return []
+    if not isinstance(value, list):
+        raise PlanItemContractError(f"{source} must be an array")
+    rows: list[Mapping[str, Any]] = []
+    for row in value:
+        if not isinstance(row, Mapping):
+            raise PlanItemContractError(f"{source} row must be an object")
+        rows.append(row)
+    return rows
+
+
+def _coordinate(value: object, field: str) -> int:
+    if not isinstance(value, int) or isinstance(value, bool) or value < 1:
+        raise PlanItemContractError(f"{field} must be a positive integer")
+    return value
+
+
+def _extract_standard_items(planning: Mapping[str, Any]) -> list[dict[str, Any]]:
+    items: list[dict[str, Any]] = []
+    for source, prefix, section in PLAN_ITEM_SOURCES:
+        if source == "stepwiseExecution":
+            _extract_step_items(planning, items, prefix, section)
+            continue
+        for index, row in enumerate(_rows(planning, source), start=1):
+            _add_item(
+                items,
+                {
+                    "id": f"{prefix}-{index}",
+                    "subject": _subject(row, source),
+                    "sourceSection": section,
+                    "ticketId": _ticket_id(row),
+                    "payload": _row_payload(row),
+                },
+            )
+    return items
+
+
+def _extract_step_items(
+    planning: Mapping[str, Any],
+    items: list[dict[str, Any]],
+    prefix: str,
+    section: str,
+) -> None:
+    if "stages" not in planning:
+        for index, row in enumerate(_rows(planning, "stepwiseExecution"), start=1):
+            _add_item(
+                items,
+                {
+                    "id": f"{prefix}-{index}",
+                    "subject": _subject(row, "stepwiseExecution"),
+                    "sourceSection": section,
+                    "ticketId": _ticket_id(row),
+                    "payload": _row_payload(row),
+                },
+            )
+        return
+    stages = planning["stages"]
+    if not isinstance(stages, list):
+        raise PlanItemContractError("stages must be an array")
+    for stage in stages:
+        if not isinstance(stage, Mapping):
+            raise PlanItemContractError("stages row must be an object")
+        stage_number = _coordinate(stage.get("stage"), "stage")
+        for row in _rows(stage, "stepwiseExecution"):
+            step_number = _coordinate(row.get("step"), "step")
+            _add_item(
+                items,
+                {
+                    "id": f"{prefix}-{stage_number}.{step_number}",
+                    "subject": _subject(row, "stepwiseExecution"),
+                    "sourceSection": section,
+                    "ticketId": _ticket_id(row),
+                    "payload": _row_payload(
+                        row,
+                        stage=stage_number,
+                        step=step_number,
+                    ),
+                },
+            )
+
+
+def _extract_prep_items(
+    planning: Mapping[str, Any], items: list[dict[str, Any]]
+) -> None:
+    if not planning.get("stages"):
+        return
+    try:
+        triggers = detect_design_surfaces(planning)
+    except (DesignSurfaceError, TypeError, AttributeError) as exc:
+        raise PlanItemContractError(f"design-surface detection failed: {exc}") from exc
+    for trigger in triggers:
+        item_id = expected_prep_plan_item_id(trigger.stage, trigger.kind)
+        _add_item(
+            items,
+            {
+                "id": item_id,
+                "subject": f"Stage {trigger.stage} {trigger.kind} design preparation",
+                "sourceSection": "5.5.10",
+                "ticketId": "",
+                "payload": {
+                    "stage": trigger.stage,
+                    "kind": trigger.kind,
+                    "evidence": [
+                        {
+                            "step": evidence.step,
+                            "field": evidence.field,
+                            "match": evidence.match,
+                        }
+                        for evidence in trigger.evidence
+                    ],
+                },
+            },
+        )
+
+
+def extract_plan_items(implementation_planning: Mapping[str, Any]) -> list[dict[str, Any]]:
+    """Return deterministic, lossless P-* items in contract order."""
+    if not isinstance(implementation_planning, Mapping):
+        raise PlanItemContractError("implementationPlanning must be an object")
+    items = _extract_standard_items(implementation_planning)
+    _extract_prep_items(implementation_planning, items)
+    return items
+
+
+def expected_plan_item_ids(implementation_planning: Mapping[str, Any]) -> list[str]:
+    """Return the exact ordered IDs produced by extract_plan_items()."""
+    return [item["id"] for item in extract_plan_items(implementation_planning)]

package/runtime/python/okstra_ctl/plan_items_cli.py

@@ -0,0 +1,81 @@
+"""CLI adapter for deterministic implementation-planning item extraction."""
+from __future__ import annotations
+
+import argparse
+import json
+from collections.abc import Mapping
+from pathlib import Path
+import sys
+from typing import Any
+
+from .convergence_store import write_json_atomic
+from .plan_items import PlanItemContractError, extract_plan_items
+
+
+def _load_json_object(path: Path) -> dict[str, Any]:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise PlanItemContractError(f"cannot read JSON object {path}: {exc}") from exc
+    if not isinstance(value, dict):
+        raise PlanItemContractError(f"JSON input must be an object: {path}")
+    return value
+
+
+def _planning(data: Mapping[str, Any]) -> Mapping[str, Any]:
+    planning = data.get("implementationPlanning")
+    if not isinstance(planning, Mapping):
+        raise PlanItemContractError("implementationPlanning must be an object")
+    return planning
+
+
+def _envelope(data: Mapping[str, Any]) -> dict[str, Any]:
+    return {
+        "schemaVersion": "1.0",
+        "taskType": "implementation-planning",
+        "items": extract_plan_items(_planning(data)),
+    }
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="okstra plan-items",
+        description="Extract and validate deterministic plan-body items.",
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+    extract = commands.add_parser("extract")
+    extract.add_argument("--data", type=Path, required=True)
+    extract.add_argument("--output", type=Path, required=True)
+    validate = commands.add_parser("validate")
+    validate.add_argument("--data", type=Path, required=True)
+    validate.add_argument("--items", type=Path, required=True)
+    return parser
+
+
+def _extract(args: argparse.Namespace) -> dict[str, Any]:
+    envelope = _envelope(_load_json_object(args.data))
+    write_json_atomic(args.output, envelope)
+    return {"ok": True, "operation": "extract", "path": str(args.output)}
+
+
+def _validate(args: argparse.Namespace) -> dict[str, Any]:
+    expected = _envelope(_load_json_object(args.data))
+    actual = _load_json_object(args.items)
+    if actual != expected:
+        raise PlanItemContractError("plan items envelope does not match deterministic extraction")
+    return {"ok": True, "operation": "validate", "path": str(args.items)}
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        result = _extract(args) if args.command == "extract" else _validate(args)
+    except (PlanItemContractError, OSError, ValueError) as exc:
+        print(f"plan-items: {exc}", file=sys.stderr)
+        return 2
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/python/okstra_ctl/report_finalize.py

@@ -121,19 +121,21 @@ def task_manifest_path(project_root: Path, manifest: Mapping[str, Any]) -> Path:
 
 
 def resolve_workspace_script(workspace_root: Path, script_name: str) -> Path:
-    return _resolve_workspace_file(workspace_root, "scripts", script_name)
+    # The build lands helper scripts under `bin/`; `scripts/` is the repo layout.
+    return _resolve_workspace_file(workspace_root, ("bin", "scripts"), script_name)
 
 
 def resolve_workspace_validator(workspace_root: Path, validator_name: str) -> Path:
-    return _resolve_workspace_file(workspace_root, "validators", validator_name)
+    return _resolve_workspace_file(workspace_root, ("validators",), validator_name)
 
 
 def _resolve_workspace_file(
     workspace_root: Path,
-    subdir: str,
+    subdirs: tuple[str, ...],
     name: str,
 ) -> Path:
-    candidates = [workspace_root / subdir / name, workspace_root / name]
+    candidates = [workspace_root / subdir / name for subdir in subdirs]
+    candidates.append(workspace_root / name)
     for candidate in candidates:
         if candidate.is_file():
             return candidate.resolve()

package/runtime/python/okstra_ctl/worker_artifact_paths.py

@@ -0,0 +1,23 @@
+"""Canonical worker artifact path derivation."""
+from __future__ import annotations
+
+
+class WorkerArtifactPathError(ValueError):
+    """Raised when a worker artifact path is not canonical."""
+
+
+def audit_sidecar_rel(worker_result_rel: str) -> str:
+    """Insert `-audit-` after the first canonical `-worker-` token."""
+    if not worker_result_rel.endswith(".md"):
+        raise WorkerArtifactPathError(
+            f"worker result path must end with .md: {worker_result_rel}"
+        )
+    directory, slash, filename = worker_result_rel.rpartition("/")
+    basename = filename if slash else worker_result_rel
+    prefix, separator, suffix = basename.partition("-worker-")
+    if not separator:
+        raise WorkerArtifactPathError(
+            f"worker result path has no canonical -worker- token: {worker_result_rel}"
+        )
+    audit_filename = f"{prefix}-worker-audit-{suffix}"
+    return f"{directory}{slash}{audit_filename}" if slash else audit_filename

package/runtime/python/okstra_ctl/worker_liveness.py

@@ -12,9 +12,9 @@ verdict and spends its existing one-retry budget.
 
 Two probes, matching the two ways a pending worker goes quiet:
 
-* ``--audit`` — a `claude-worker` audit sidecar. Stale past the heartbeat
-  cadence (or present with no heartbeat at all) means the in-process worker
-  hung. Uses the same line shape and budget the Phase 7 validator applies.
+* ``--audit`` — an in-process worker audit sidecar. Stale past the heartbeat
+  cadence (or present with no heartbeat at all) means the worker hung. Uses
+  the same line shape and budget the Phase 7 validator applies.
 * ``--prompt`` — a CLI-wrapper prompt-history path. Neither `<prompt>.log` nor
   `<prompt>.status.json` past the launch grace means the wrapper never ran —
   the dispatch itself failed, which no artifact otherwise distinguishes from a
@@ -110,7 +110,7 @@ def main(argv: list[str] | None = None) -> int:
         description="Report whether pending workers are still alive (read-only).",
     )
     parser.add_argument("--audit", action="append", default=[],
-                        help="in-process claude-worker audit sidecar path (repeatable)")
+                        help="in-process worker audit sidecar path (repeatable)")
     parser.add_argument("--prompt", action="append", default=[],
                         help="CLI-wrapper (codex/antigravity) prompt-history path "
                              "(repeatable). Only the wrappers write the artifacts "

package/runtime/python/okstra_ctl/worker_prompt_body.py

@@ -47,7 +47,7 @@ def analysis_prompt_body(
         "## Output Contract",
         "- Read the Worker Preamble Path end-to-end before analysis.",
         "- Write the worker result to Result Path and no other canonical result path.",
-        "- Write the audit sidecar and any tool-failure entries as the preamble requires.",
+        "- Write the audit sidecar to Audit sidecar path as the preamble requires.",
         "- Cite evidence with file paths and line numbers whenever you make a claim.",
     ]
 

package/runtime/python/okstra_ctl/worker_prompt_contract.py

@@ -32,6 +32,7 @@ _NON_BODY_PREFIXES = (
     "**Project Root:**",
     "**Prompt History Path:**",
     "**Result Path:**",
+    "**Audit sidecar path:**",
     "Assigned worker prompt history path:",
     "**Worker Preamble Path:**",
     "**Errors log path:**",
@@ -55,6 +56,7 @@ _REQUIRED_TARGET_PREFIXES = (
 _WORKER_SPECIFIC_PREFIXES = (
     "**Prompt History Path:**",
     "**Result Path:**",
+    "**Audit sidecar path:**",
     "Assigned worker prompt history path:",
     "**Errors sidecar path:**",
     "**Worker Result Path:**",
@@ -135,7 +137,6 @@ def normalise_analysis_prompt(text: str) -> str:
             "",
         )
         if prefix:
-            normalized.append(f"{prefix} <worker-specific>")
             continue
         normalized.append(_WORKER_LABEL_RE.sub("<analysis-worker>", line.rstrip()))
     return "\n".join(normalized).strip() + "\n"

package/runtime/python/okstra_ctl/worker_prompt_headers.py

@@ -5,6 +5,7 @@ from pathlib import Path
 from typing import Any, Mapping
 
 from .paths import okstra_home
+from .worker_artifact_paths import WorkerArtifactPathError, audit_sidecar_rel
 from .worker_prompt_policy import (
     GRILLING_LOG_HEADER,
     PromptPlan,
@@ -42,6 +43,7 @@ def worker_prompt_headers(
     project_root: Path,
     prompt_rel: str,
     result_rel: str,
+    audit_source_rel: str | None = None,
     worker_id: str,
     dispatch_kind: str,
     manifest: Mapping[str, Any],
@@ -49,6 +51,10 @@ def worker_prompt_headers(
 ) -> list[str]:
     """Render the team-contract worker prompt anchor headers."""
     prompt_path = _resolve_project_path(project_root, prompt_rel)
+    audit_sidecar_path = _audit_sidecar_path(
+        project_root,
+        audit_source_rel or result_rel,
+    )
     errors_log_path = _errors_log_path(project_root, manifest, active_context)
     errors_sidecar_path = _worker_errors_sidecar_path(
         project_root,
@@ -61,6 +67,7 @@ def worker_prompt_headers(
         f"**Project Root:** {project_root}",
         f"**Prompt History Path:** {prompt_rel}",
         f"**Result Path:** {result_rel}",
+        f"**Audit sidecar path:** {audit_sidecar_path}",
         f"Assigned worker prompt history path: {prompt_path}",
         f"**Worker Preamble Path:** {_worker_preamble_path(plan, active_context)}",
         f"**Worker Error Contract Path:** {_worker_error_contract_path(active_context)}",
@@ -235,6 +242,13 @@ def _resolve_project_path(project_root: Path, value: str) -> Path:
     return path if path.is_absolute() else project_root / path
 
 
+def _audit_sidecar_path(project_root: Path, worker_result_rel: str) -> Path:
+    try:
+        return _resolve_project_path(project_root, audit_sidecar_rel(worker_result_rel))
+    except WorkerArtifactPathError as exc:
+        raise WorkerPromptHeaderError(str(exc)) from exc
+
+
 def _require_string(payload: Mapping[str, Any], key: str) -> str:
     value = payload.get(key)
     if not isinstance(value, str) or not value.strip():

package/runtime/schemas/convergence-critic-results-v1.0.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://okstra.dev/schemas/convergence-critic-results-v1.0.json",
+  "title": "OKSTRA Convergence Critic Results (v1.0)",
+  "type": "object",
+  "required": ["schemaVersion", "taskKey", "mode", "provider", "terminalStatus", "durationMs", "candidates"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": "1.0" },
+    "taskKey": { "type": "string", "pattern": "\\S" },
+    "mode": { "enum": ["coverage", "acceptance-devils-advocate"] },
+    "provider": { "type": "string", "pattern": "\\S" },
+    "terminalStatus": { "enum": ["completed", "timeout", "error", "not-run"] },
+    "durationMs": { "type": "integer", "minimum": 0 },
+    "candidates": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/Candidate" }
+    }
+  },
+  "$defs": {
+    "Candidate": {
+      "type": "object",
+      "required": ["candidateId", "summary", "category", "ticketIds", "originEvidence"],
+      "additionalProperties": false,
+      "properties": {
+        "candidateId": { "type": "string", "pattern": "\\S" },
+        "summary": { "type": "string", "pattern": "\\S" },
+        "category": { "type": "string", "pattern": "\\S" },
+        "ticketIds": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "\\S" }
+        },
+        "originEvidence": { "type": "string", "pattern": "\\S" },
+        "severity": { "enum": ["critical", "major", "minor"] },
+        "evidenceArtifacts": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/EvidenceArtifact" }
+        }
+      }
+    },
+    "EvidenceArtifact": {
+      "type": "object",
+      "required": ["path", "sha256", "command", "environment"],
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "type": "string",
+          "pattern": "^\\.okstra/(?!\\.{1,2}(?:/|$))(?!.*?/\\.{1,2}(?:/|$))[^/\\\\\\r\\n]+(?:/[^/\\\\\\r\\n]+)*$"
+        },
+        "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "command": { "type": "string", "pattern": "\\S" },
+        "environment": { "type": "string", "pattern": "\\S" }
+      }
+    }
+  }
+}

package/runtime/schemas/convergence-groups-v1.0.schema.json

@@ -0,0 +1,109 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://okstra.dev/schemas/convergence-groups-v1.0.json",
+  "title": "OKSTRA Convergence Grouped Input (v1.0)",
+  "type": "object",
+  "required": ["schemaVersion", "taskKey", "config", "workers", "groups"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": "1.0" },
+    "taskKey": { "type": "string", "pattern": "\\S" },
+    "config": { "$ref": "#/$defs/Config" },
+    "workers": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/Worker" }
+    },
+    "groups": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/Group" }
+    }
+  },
+  "$defs": {
+    "Config": {
+      "type": "object",
+      "required": ["enabled", "adversarial", "maxRounds", "effectiveMaxRounds", "verificationMode"],
+      "additionalProperties": false,
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "adversarial": { "type": "boolean" },
+        "maxRounds": { "type": "integer", "minimum": 1, "maximum": 3 },
+        "effectiveMaxRounds": { "type": "integer", "minimum": 1, "maximum": 3 },
+        "verificationMode": { "enum": ["lightweight", "full-reanalysis"] }
+      }
+    },
+    "Worker": {
+      "type": "object",
+      "required": ["workerId", "audience"],
+      "additionalProperties": false,
+      "properties": {
+        "workerId": { "type": "string", "pattern": "\\S" },
+        "audience": { "enum": ["analysis", "report-writer"] }
+      }
+    },
+    "Group": {
+      "type": "object",
+      "required": ["findingId", "summary", "category", "ticketIds", "originWorker", "originEvidence", "discoveredBy", "sourceItems"],
+      "additionalProperties": false,
+      "properties": {
+        "findingId": { "type": "string", "pattern": "\\S" },
+        "summary": { "type": "string", "pattern": "\\S" },
+        "category": { "type": "string", "pattern": "\\S" },
+        "ticketIds": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "pattern": "\\S" }
+        },
+        "originWorker": { "type": "string", "pattern": "\\S" },
+        "originEvidence": { "type": "string", "pattern": "\\S" },
+        "evidenceArtifacts": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/EvidenceArtifact" }
+        },
+        "discoveredBy": {
+          "type": "object",
+          "minProperties": 1,
+          "additionalProperties": { "$ref": "#/$defs/Discovery" }
+        },
+        "sourceItems": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/SourceItem" }
+        }
+      }
+    },
+    "EvidenceArtifact": {
+      "type": "object",
+      "required": ["path", "sha256", "command", "environment"],
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "type": "string",
+          "pattern": "^\\.okstra/(?!\\.{1,2}(?:/|$))(?!.*?/\\.{1,2}(?:/|$))[^/\\\\\\r\\n]+(?:/[^/\\\\\\r\\n]+)*$"
+        },
+        "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "command": { "type": "string", "pattern": "\\S" },
+        "environment": { "type": "string", "pattern": "\\S" }
+      }
+    },
+    "Discovery": {
+      "type": "object",
+      "required": ["itemId", "evidence"],
+      "additionalProperties": false,
+      "properties": {
+        "itemId": { "type": "string", "pattern": "\\S" },
+        "evidence": { "type": "string", "pattern": "\\S" }
+      }
+    },
+    "SourceItem": {
+      "type": "object",
+      "required": ["worker", "itemId"],
+      "additionalProperties": false,
+      "properties": {
+        "worker": { "type": "string", "pattern": "\\S" },
+        "itemId": { "type": "string", "pattern": "\\S" }
+      }
+    }
+  }
+}