okstra 0.1.0

package/runtime/validators/lib/validate-prompt-metadata.sh

@@ -0,0 +1,267 @@
+# shellcheck shell=bash
+
+validate_worker_prompt_metadata() {
+  local task_group="$1"
+  local task_id="$2"
+  local expected_task_manifest_relative_path=""
+
+  expected_task_manifest_relative_path="$(task_manifest_relative_path "$task_group" "$task_id")"
+
+  python3 - "$PROJECT_ROOT" "$expected_task_manifest_relative_path" <<'PY'
+from pathlib import Path
+import json
+import sys
+
+project_root = Path(sys.argv[1])
+task_manifest_path = project_root / sys.argv[2]
+errors = []
+
+
+def load_json(path: Path) -> dict:
+    return json.loads(path.read_text())
+
+
+def validate_prompt_contract(
+    prefix: str,
+    worker_ids: list[str],
+    prompt_dir: str,
+    prompt_map: object,
+    required_worker_roles: object,
+) -> None:
+    if not prompt_dir:
+        errors.append(f"{prefix} is missing worker prompt directory metadata")
+    if not isinstance(prompt_map, dict):
+        errors.append(f"{prefix} worker prompt map is missing or invalid")
+        prompt_map = {}
+    if not isinstance(required_worker_roles, list):
+        errors.append(f"{prefix} requiredWorkerRoles is missing or invalid")
+        required_worker_roles = []
+
+    expected_dir_prefix = prompt_dir.rstrip("/") + "/" if prompt_dir else ""
+    for worker_id in worker_ids:
+        if worker_id not in prompt_map:
+            errors.append(f"{prefix} worker prompt map is missing selected worker: {worker_id}")
+
+    for worker in required_worker_roles:
+        if not isinstance(worker, dict):
+            errors.append(f"{prefix} requiredWorkerRoles contains a non-object entry")
+            continue
+        worker_id = str(worker.get("workerId", "")).strip()
+        prompt_relative = str(worker.get("promptPath", "")).strip()
+        if not worker_id:
+            errors.append(f"{prefix} requiredWorkerRoles contains an entry without workerId")
+            continue
+        if not prompt_relative:
+            errors.append(
+                f"{prefix} required worker is missing promptPath: {worker_id}"
+            )
+            continue
+        if prompt_map.get(worker_id) != prompt_relative:
+            errors.append(
+                f"{prefix} worker prompt map does not match requiredWorkerRoles for {worker_id}"
+            )
+        if expected_dir_prefix and not prompt_relative.startswith(expected_dir_prefix):
+            errors.append(
+                f"{prefix} worker prompt path is outside the prompt directory: {prompt_relative}"
+            )
+
+
+if not task_manifest_path.is_file():
+    errors.append(f"task manifest is missing: {task_manifest_path}")
+else:
+    task_manifest = load_json(task_manifest_path)
+    selected_workers = task_manifest.get("recommendedWorkers", [])
+    if not isinstance(selected_workers, list):
+        errors.append("task manifest recommendedWorkers is missing or invalid")
+        selected_workers = []
+
+    task_prompt_dir = str(task_manifest.get("latestRunPromptsPath", "")).strip()
+    if not task_prompt_dir:
+        errors.append("task manifest is missing latestRunPromptsPath")
+
+    task_artifacts = task_manifest.get("artifacts", {})
+    if not isinstance(task_artifacts, dict):
+        errors.append("task manifest artifacts is missing or invalid")
+        task_artifacts = {}
+
+    validate_prompt_contract(
+        "task manifest",
+        selected_workers,
+        str(task_artifacts.get("workerPromptsDirectoryPath", "")).strip(),
+        task_artifacts.get("workerPromptPathByWorkerId"),
+        task_manifest.get("resultContract", {}).get("requiredWorkerRoles"),
+    )
+
+    if (
+        task_prompt_dir
+        and str(task_artifacts.get("workerPromptsDirectoryPath", "")).strip()
+        and task_prompt_dir
+        != str(task_artifacts.get("workerPromptsDirectoryPath", "")).strip()
+    ):
+        errors.append(
+            "task manifest latestRunPromptsPath does not match artifacts.workerPromptsDirectoryPath"
+        )
+
+    timeline_relative_path = str(
+        task_manifest.get("historyTimelinePath", "")
+    ).strip()
+    if not timeline_relative_path:
+        errors.append("task manifest is missing historyTimelinePath")
+    else:
+        timeline_path = project_root / timeline_relative_path
+        if not timeline_path.is_file():
+            errors.append(f"timeline file is missing: {timeline_path}")
+        else:
+            timeline = load_json(timeline_path)
+            runs = timeline.get("runs", [])
+            latest_run = None
+            if isinstance(runs, list):
+                for item in reversed(runs):
+                    if isinstance(item, dict):
+                        latest_run = item
+                        break
+            if latest_run is None:
+                errors.append("timeline does not contain a latest run entry")
+            else:
+                latest_run_prompt_dir = str(
+                    latest_run.get("workerPromptDirectoryPath", "")
+                ).strip()
+                if not latest_run_prompt_dir:
+                    errors.append(
+                        "latest timeline entry is missing workerPromptDirectoryPath"
+                    )
+                if task_prompt_dir and latest_run_prompt_dir and task_prompt_dir != latest_run_prompt_dir:
+                    errors.append(
+                        "timeline latest run prompt directory does not match task manifest latestRunPromptsPath"
+                    )
+                prompt_map = latest_run.get("workerPromptPathByWorkerId")
+                if not isinstance(prompt_map, dict):
+                    errors.append(
+                        "latest timeline entry is missing workerPromptPathByWorkerId"
+                    )
+                else:
+                    for worker_id in selected_workers:
+                        if worker_id not in prompt_map:
+                            errors.append(
+                                f"latest timeline entry is missing worker prompt path for {worker_id}"
+                            )
+
+                run_manifest_relative_path = str(
+                    latest_run.get("runManifestPath", "")
+                ).strip()
+                if not run_manifest_relative_path:
+                    errors.append(
+                        "latest timeline entry is missing runManifestPath"
+                    )
+                else:
+                    run_manifest_path = project_root / run_manifest_relative_path
+                    if not run_manifest_path.is_file():
+                        errors.append(f"latest run manifest is missing: {run_manifest_path}")
+                    else:
+                        run_manifest = load_json(run_manifest_path)
+                        run_prompt_dir = str(
+                            run_manifest.get("workerPromptsDirectoryPath", "")
+                        ).strip()
+                        if task_prompt_dir and run_prompt_dir and task_prompt_dir != run_prompt_dir:
+                            errors.append(
+                                "run manifest workerPromptsDirectoryPath does not match task manifest latestRunPromptsPath"
+                            )
+                        validate_prompt_contract(
+                            "run manifest",
+                            selected_workers,
+                            run_prompt_dir,
+                            run_manifest.get("workerPromptPathByWorkerId"),
+                            run_manifest.get("teamContract", {}).get("requiredWorkerRoles"),
+                        )
+
+                        team_state_relative_path = str(
+                            run_manifest.get("teamStatePath")
+                            or task_manifest.get("teamStatePath", "")
+                        ).strip()
+                        if not team_state_relative_path:
+                            errors.append(
+                                "team state relative path is missing from run/task manifest"
+                            )
+                        else:
+                            team_state_path = project_root / team_state_relative_path
+                            if not team_state_path.is_file():
+                                errors.append(f"team-state file is missing: {team_state_path}")
+                            else:
+                                team_state = load_json(team_state_path)
+                                team_artifacts = team_state.get("artifacts", {})
+                                if not isinstance(team_artifacts, dict):
+                                    errors.append(
+                                        "team-state artifacts is missing or invalid"
+                                    )
+                                    team_artifacts = {}
+                                team_prompt_dir = str(
+                                    team_artifacts.get(
+                                        "workerPromptsDirectoryPath", ""
+                                    )
+                                ).strip()
+                                if run_prompt_dir and team_prompt_dir and run_prompt_dir != team_prompt_dir:
+                                    errors.append(
+                                        "team-state worker prompt directory does not match run manifest"
+                                    )
+                                workers = team_state.get("workers", [])
+                                if not isinstance(workers, list):
+                                    errors.append("team-state workers is missing or invalid")
+                                else:
+                                    team_workers = {}
+                                    for worker in workers:
+                                        if not isinstance(worker, dict):
+                                            errors.append(
+                                                "team-state workers contains a non-object entry"
+                                            )
+                                            continue
+                                        worker_id = str(worker.get("workerId", "")).strip()
+                                        if not worker_id:
+                                            errors.append(
+                                                "team-state workers contains an entry without workerId"
+                                            )
+                                            continue
+                                        team_workers[worker_id] = worker
+
+                                    run_prompt_map = run_manifest.get(
+                                        "workerPromptPathByWorkerId", {}
+                                    )
+                                    if not isinstance(run_prompt_map, dict):
+                                        run_prompt_map = {}
+
+                                    for worker_id in selected_workers:
+                                        worker = team_workers.get(worker_id)
+                                        if worker is None:
+                                            errors.append(
+                                                f"team-state is missing selected worker entry: {worker_id}"
+                                            )
+                                            continue
+                                        prompt_relative = str(
+                                            worker.get("promptPath", "")
+                                        ).strip()
+                                        if not prompt_relative:
+                                            errors.append(
+                                                f"team-state worker is missing promptPath: {worker_id}"
+                                            )
+                                            continue
+                                        if run_prompt_map.get(worker_id) != prompt_relative:
+                                            errors.append(
+                                                f"team-state worker prompt path does not match run manifest for {worker_id}"
+                                            )
+                                        expected_dir_prefix = (
+                                            run_prompt_dir.rstrip("/") + "/"
+                                            if run_prompt_dir
+                                            else ""
+                                        )
+                                        if expected_dir_prefix and not prompt_relative.startswith(
+                                            expected_dir_prefix
+                                        ):
+                                            errors.append(
+                                                f"team-state worker prompt path is outside the run prompt directory: {prompt_relative}"
+                                            )
+
+if errors:
+    for error in errors:
+        print(error, file=sys.stderr)
+    sys.exit(1)
+PY
+}

package/runtime/validators/lib/validate-tasks.sh

@@ -0,0 +1,335 @@
+# shellcheck shell=bash
+
+validate_reference_expectations() {
+  local brief_path="$1"
+  local reference_expectations_file="$2"
+  local expected_task_key="$3"
+
+  python3 - "$brief_path" "$reference_expectations_file" "$expected_task_key" <<'PY'
+from pathlib import Path
+import sys
+
+brief_path = Path(sys.argv[1])
+reference_path = Path(sys.argv[2])
+expected_task_key = sys.argv[3]
+brief_lines = brief_path.read_text().splitlines()
+section_map = {
+    "Configuration References and Expected Values": "config",
+    "Deployment Manifests and Expected Values": "deployment",
+}
+captured = {"config": [], "deployment": []}
+current_section = None
+
+for line in brief_lines:
+    if line.startswith("## "):
+        current_section = section_map.get(line[3:].strip())
+        continue
+    if current_section and line.strip():
+        captured[current_section].append(line)
+
+errors = []
+
+if not reference_path.is_file():
+    errors.append(f"reference expectations file is missing: {reference_path}")
+    reference_content = ""
+else:
+    reference_content = reference_path.read_text()
+
+for line in captured["config"] + captured["deployment"]:
+    if line not in reference_content:
+        errors.append(f"reference expectations file is missing brief line: {line}")
+
+if f"- Task Key: `{expected_task_key}`" not in reference_content:
+    errors.append("reference expectations file is missing the task key header")
+
+if errors:
+    for error in errors:
+        print(error, file=sys.stderr)
+    sys.exit(1)
+PY
+}
+
+validate_task_artifacts() {
+  local task_group="$1"
+  local task_id="$2"
+  local expected_task_key=""
+  local expected_task_manifest_relative_path=""
+  local expected_reference_relative_path=""
+
+  expected_task_key="$(task_key "$task_group" "$task_id")"
+  expected_task_manifest_relative_path="$(task_manifest_relative_path "$task_group" "$task_id")"
+  expected_reference_relative_path="$(reference_expectations_relative_path "$task_group" "$task_id")"
+
+  python3 - "$PROJECT_ROOT" "$expected_task_key" "$expected_task_manifest_relative_path" "$expected_reference_relative_path" "$TASK_CATALOG_RELATIVE_PATH" <<'PY'
+from pathlib import Path
+import json
+import sys
+
+project_root = Path(sys.argv[1])
+expected_task_key = sys.argv[2]
+task_manifest_relative_path = sys.argv[3]
+expected_reference_relative_path = sys.argv[4]
+expected_task_catalog_relative_path = sys.argv[5]
+errors = []
+
+task_manifest_path = project_root / task_manifest_relative_path
+if not task_manifest_path.is_file():
+    errors.append(f"task manifest is missing: {task_manifest_path}")
+else:
+    task_manifest = json.loads(task_manifest_path.read_text())
+
+    if task_manifest.get("taskKey") != expected_task_key:
+        errors.append("task manifest does not contain the expected task key")
+
+    if task_manifest.get("referenceExpectationsPath") != expected_reference_relative_path:
+        errors.append("task manifest does not expose referenceExpectationsPath")
+
+    if task_manifest.get("taskCatalogPath") != expected_task_catalog_relative_path:
+        errors.append("task manifest does not expose taskCatalogPath")
+
+    if (
+        task_manifest.get("artifacts", {}).get("referenceExpectationsPath")
+        != expected_reference_relative_path
+    ):
+        errors.append("task manifest artifacts do not expose referenceExpectationsPath")
+
+    timeline_relative_path = task_manifest.get("historyTimelinePath", "")
+    if not timeline_relative_path:
+        errors.append("task manifest is missing historyTimelinePath")
+    else:
+        timeline_path = project_root / timeline_relative_path
+        if not timeline_path.is_file():
+            errors.append(f"timeline file is missing: {timeline_path}")
+        else:
+            timeline = json.loads(timeline_path.read_text())
+            runs = timeline.get("runs", [])
+            latest_run = None
+            if isinstance(runs, list):
+                for item in reversed(runs):
+                    if isinstance(item, dict):
+                        latest_run = item
+                        break
+            if latest_run is None:
+                errors.append("timeline does not contain a latest run entry")
+            else:
+                run_manifest_relative_path = latest_run.get("runManifestPath", "")
+                if not run_manifest_relative_path:
+                    errors.append("latest timeline entry is missing runManifestPath")
+                else:
+                    run_manifest_path = project_root / run_manifest_relative_path
+                    if not run_manifest_path.is_file():
+                        errors.append(f"latest run manifest is missing: {run_manifest_path}")
+                    else:
+                        run_manifest = json.loads(run_manifest_path.read_text())
+                        if run_manifest.get("taskKey") != expected_task_key:
+                            errors.append("run manifest does not contain the expected task key")
+                        if (
+                            run_manifest.get("referenceExpectationsPath")
+                            != expected_reference_relative_path
+                        ):
+                            errors.append(
+                                "run manifest does not expose referenceExpectationsPath"
+                            )
+                        if (
+                            run_manifest.get("taskCatalogPath")
+                            != expected_task_catalog_relative_path
+                        ):
+                            errors.append("run manifest does not expose taskCatalogPath")
+
+if errors:
+    for error in errors:
+        print(error, file=sys.stderr)
+    sys.exit(1)
+PY
+}
+
+validate_latest_task_pointer() {
+  local task_group="$1"
+  local task_id="$2"
+  local expected_task_key=""
+  local expected_task_manifest_relative_path=""
+  local expected_reference_relative_path=""
+
+  expected_task_key="$(task_key "$task_group" "$task_id")"
+  expected_task_manifest_relative_path="$(task_manifest_relative_path "$task_group" "$task_id")"
+  expected_reference_relative_path="$(reference_expectations_relative_path "$task_group" "$task_id")"
+
+  python3 - "$PROJECT_ROOT" "$DISCOVERY_FILE" "$expected_task_key" "$expected_task_manifest_relative_path" "$expected_reference_relative_path" "$TASK_CATALOG_RELATIVE_PATH" <<'PY'
+from pathlib import Path
+import json
+import sys
+
+project_root = Path(sys.argv[1])
+discovery_path = Path(sys.argv[2])
+expected_task_key = sys.argv[3]
+expected_task_manifest_relative_path = sys.argv[4]
+expected_reference_relative_path = sys.argv[5]
+expected_task_catalog_relative_path = sys.argv[6]
+errors = []
+
+if not discovery_path.is_file():
+    errors.append(f"latest-task discovery file is missing: {discovery_path}")
+else:
+    discovery = json.loads(discovery_path.read_text())
+
+    if discovery.get("taskKey") != expected_task_key:
+        errors.append("latest-task discovery does not point to the expected task key")
+
+    if discovery.get("taskManifestPath") != expected_task_manifest_relative_path:
+        errors.append("latest-task discovery does not point to the expected task manifest")
+
+    if discovery.get("referenceExpectationsPath") != expected_reference_relative_path:
+        errors.append("latest-task discovery does not expose the expected reference expectations path")
+
+    if discovery.get("taskCatalogPath") != expected_task_catalog_relative_path:
+        errors.append("latest-task discovery does not expose taskCatalogPath")
+
+    latest_run_prompts_relative_path = discovery.get("latestRunPromptsPath", "")
+    if not latest_run_prompts_relative_path:
+        errors.append("latest-task discovery is missing latestRunPromptsPath")
+
+    latest_run_manifest_relative_path = discovery.get("latestRunManifestPath", "")
+    if not latest_run_manifest_relative_path:
+        errors.append("latest-task discovery is missing latestRunManifestPath")
+    else:
+        latest_run_manifest_path = project_root / latest_run_manifest_relative_path
+        if not latest_run_manifest_path.is_file():
+            errors.append(f"latest run manifest is missing: {latest_run_manifest_path}")
+        else:
+            run_manifest = json.loads(latest_run_manifest_path.read_text())
+            if (
+                latest_run_prompts_relative_path
+                and run_manifest.get("workerPromptsDirectoryPath")
+                != latest_run_prompts_relative_path
+            ):
+                errors.append(
+                    "latest-task discovery latestRunPromptsPath does not match the latest run manifest"
+                )
+
+if errors:
+    for error in errors:
+        print(error, file=sys.stderr)
+    sys.exit(1)
+PY
+}
+
+validate_task_catalog() {
+  local expected_latest_task_key="$1"
+  shift
+  local expected_task_keys=("$@")
+
+  python3 - "$PROJECT_ROOT" "$CATALOG_FILE" "$expected_latest_task_key" "$LATEST_TASK_RELATIVE_PATH" "${expected_task_keys[@]}" <<'PY'
+from pathlib import Path
+import json
+import sys
+
+project_root = Path(sys.argv[1])
+catalog_path = Path(sys.argv[2])
+expected_latest_task_key = sys.argv[3]
+expected_latest_task_relative_path = sys.argv[4]
+expected_task_keys = sys.argv[5:]
+errors = []
+
+if not catalog_path.is_file():
+    errors.append(f"task catalog is missing: {catalog_path}")
+else:
+    catalog = json.loads(catalog_path.read_text())
+    tasks = catalog.get("tasks", [])
+
+    if catalog.get("latestTaskKey") != expected_latest_task_key:
+        errors.append("task catalog does not record the expected latestTaskKey")
+
+    if catalog.get("latestTaskDiscoveryPath") != expected_latest_task_relative_path:
+        errors.append("task catalog does not expose latestTaskDiscoveryPath")
+
+    if catalog.get("taskCount") != len(expected_task_keys):
+        errors.append("task catalog taskCount does not match the expected number of tasks")
+
+    if not isinstance(tasks, list):
+        errors.append("task catalog tasks entry is not a list")
+    else:
+        catalog_by_key = {}
+        for entry in tasks:
+            if not isinstance(entry, dict):
+                errors.append("task catalog contains a non-object entry")
+                continue
+            task_key = entry.get("taskKey", "")
+            if not task_key:
+                errors.append("task catalog contains an entry without taskKey")
+                continue
+            if task_key in catalog_by_key:
+                errors.append(f"task catalog contains a duplicate task key: {task_key}")
+                continue
+            catalog_by_key[task_key] = entry
+
+        for expected_task_key in expected_task_keys:
+            entry = catalog_by_key.get(expected_task_key)
+            if entry is None:
+                errors.append(f"task catalog is missing task key: {expected_task_key}")
+                continue
+            task_key_parts = expected_task_key.split(":", 2)
+            if len(task_key_parts) != 3:
+                errors.append(f"expected task key is malformed: {expected_task_key}")
+                continue
+            _, expected_task_group, expected_task_id = task_key_parts
+
+            if entry.get("taskGroup") != expected_task_group:
+                errors.append(f"task catalog entry is missing the expected taskGroup: {expected_task_key}")
+
+            if entry.get("taskId") != expected_task_id:
+                errors.append(f"task catalog entry is missing the expected taskId: {expected_task_key}")
+
+            task_manifest_relative_path = entry.get("taskManifestPath", "")
+            if not task_manifest_relative_path:
+                errors.append(f"task catalog entry is missing taskManifestPath: {expected_task_key}")
+            else:
+                task_manifest_path = project_root / task_manifest_relative_path
+                if not task_manifest_path.is_file():
+                    errors.append(f"task catalog points to a missing task manifest: {task_manifest_path}")
+
+            reference_relative_path = entry.get("referenceExpectationsPath", "")
+            if not reference_relative_path:
+                errors.append(
+                    f"task catalog entry is missing referenceExpectationsPath: {expected_task_key}"
+                )
+            else:
+                reference_path = project_root / reference_relative_path
+                if not reference_path.is_file():
+                    errors.append(
+                        f"task catalog points to a missing reference expectations file: {reference_path}"
+                    )
+
+            latest_run_manifest_relative_path = entry.get("latestRunManifestPath", "")
+            if not latest_run_manifest_relative_path:
+                errors.append(
+                    f"task catalog entry is missing latestRunManifestPath: {expected_task_key}"
+                )
+            else:
+                latest_run_manifest_path = project_root / latest_run_manifest_relative_path
+                if not latest_run_manifest_path.is_file():
+                    errors.append(
+                        f"task catalog points to a missing latest run manifest: {latest_run_manifest_path}"
+                    )
+                else:
+                    run_manifest = json.loads(latest_run_manifest_path.read_text())
+                    latest_run_prompts_relative_path = entry.get(
+                        "latestRunPromptsPath", ""
+                    )
+                    if not latest_run_prompts_relative_path:
+                        errors.append(
+                            f"task catalog entry is missing latestRunPromptsPath: {expected_task_key}"
+                        )
+                    elif (
+                        run_manifest.get("workerPromptsDirectoryPath")
+                        != latest_run_prompts_relative_path
+                    ):
+                        errors.append(
+                            f"task catalog entry latestRunPromptsPath does not match the latest run manifest: {expected_task_key}"
+                        )
+
+if errors:
+    for error in errors:
+        print(error, file=sys.stderr)
+    sys.exit(1)
+PY
+}