okstra 0.1.0

package/runtime/validators/lib/fixtures.sh

@@ -0,0 +1,322 @@
+# shellcheck shell=bash
+
+write_validation_brief() {
+  local brief_path="$1"
+  local brief_title="$2"
+  local task_group="$3"
+  local task_id="$4"
+  local validation_focus="$5"
+  local task_key_value=""
+
+  task_key_value="$(task_key "$task_group" "$task_id")"
+
+  cat >"$brief_path" <<EOF
+# Cross Verify Task Brief
+
+## Brief Identity
+
+- Brief Title: $brief_title
+- Project ID: \`okstra-validation\`
+- Task Group: \`$task_group\`
+- Task ID: \`$task_id\`
+- Task Key: \`$task_key_value\`
+- Related Tasks:
+- Task Type: \`$TASK_TYPE\`
+- Requested Outcome: validate asset seeding, refresh behavior, and discovery catalog integrity
+- Owner: \`Oz\`
+
+## Problem or Request Summary
+
+- Verify that okstra seeds all Claude Markdown assets into the target project on first run.
+- Verify that refresh is optional and only forced with the refresh option.
+- Verify that config and deployment expected states are discoverable by task bundle artifacts.
+- Validation focus: $validation_focus
+
+## Source Materials
+
+- Primary problem statement: \`validation\`
+- Existing analysis or notes:
+- Related raw samples or logs:
+- Related code paths: \`scripts/okstra.sh\`
+- Related tickets or docs: \`OKSTRA_USAGE_MANUAL.md\`
+- Previous reports in the same task history:
+
+## Constraints and Assumptions
+
+- Known constraints: validation must stay inside the temporary project root
+- Known assumptions: task bundle artifacts are the canonical source for skill loading
+- Things that are still uncertain: none
+
+## Configuration References and Expected Values
+
+- Config file: \`.claude/settings.json\`
+  - Expected values:
+    - project-local okstra Claude assets must remain discoverable under \`.claude/skills/\` and \`.claude/agents/\`
+    - refresh should occur only when \`--refresh-assets\` is used
+- Config file: \`.project-docs/okstra/discovery/latest-task.json\`
+  - Expected values:
+    - latest prepared task pointer must include the current task key
+    - task catalog path must be present
+- Config file: \`.project-docs/okstra/discovery/task-catalog.json\`
+  - Expected values:
+    - task catalog must preserve prepared task bundles by task key
+    - task catalog must allow task-group and task-id level distinction
+
+## Deployment Manifests and Expected Values
+
+- Manifest file: \`deploy/values.yaml\`
+  - Expected values:
+    - image tag should match the validated release candidate for this task
+    - rollout-specific values must be verified against the task brief before final approval
+- Manifest file: \`k8s/deployment.yaml\`
+  - Expected values:
+    - env and image settings must match the task brief requirements
+    - missing deployment expectations must be reported as missing information
+
+## Questions for Workers
+
+1. Are all required Claude assets seeded into the temporary target project?
+2. Do the generated task artifacts preserve config and deployment expected states?
+3. Does refresh remain optional rather than automatic?
+4. Does the discovery catalog preserve distinct task entries?
+
+## Expected Outputs
+
+- Asset seed verification:
+- Missing information:
+- Risks:
+- Recommended next actions:
+EOF
+}
+
+write_worker_prompt_history_fixture() {
+  local task_group="$1"
+  local task_id="$2"
+  local worker_id="$3"
+  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" "$worker_id" <<'PY'
+from pathlib import Path
+import json
+import sys
+
+project_root = Path(sys.argv[1])
+task_manifest_path = project_root / sys.argv[2]
+target_worker_id = sys.argv[3]
+task_manifest = json.loads(task_manifest_path.read_text())
+team_state_path = project_root / task_manifest["teamStatePath"]
+team_state = json.loads(team_state_path.read_text())
+
+target_worker = None
+for worker in team_state.get("workers", []):
+    if isinstance(worker, dict) and worker.get("workerId") == target_worker_id:
+        target_worker = worker
+        break
+
+if target_worker is None:
+    raise SystemExit(f"worker not found in team-state: {target_worker_id}")
+
+prompt_relative = str(target_worker.get("promptPath", "")).strip()
+if not prompt_relative:
+    raise SystemExit(f"worker promptPath is missing: {target_worker_id}")
+
+prompt_path = project_root / prompt_relative
+prompt_path.parent.mkdir(parents=True, exist_ok=True)
+prompt_path.write_text(
+    "\n".join(
+        [
+            f"# {target_worker.get('role', target_worker_id)} Prompt Snapshot",
+            "",
+            f"Assigned worker prompt history path: {prompt_relative}",
+            f"Task Key: {task_manifest.get('taskKey', '')}",
+            "Validation fixture prompt body.",
+        ]
+    )
+    + "\n"
+)
+PY
+}
+
+prepare_run_validator_fixture() {
+  local task_group="$1"
+  local task_id="$2"
+  local omitted_worker_id="$3"
+  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" "$omitted_worker_id" <<'PY'
+from pathlib import Path
+import json
+import sys
+
+project_root = Path(sys.argv[1])
+task_manifest_path = project_root / sys.argv[2]
+omitted_worker_id = sys.argv[3]
+
+
+def load_json(path: Path) -> dict:
+    return json.loads(path.read_text())
+
+
+def write_json(path: Path, payload: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n")
+
+
+task_manifest = load_json(task_manifest_path)
+timeline_path = project_root / task_manifest["historyTimelinePath"]
+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:
+    raise SystemExit("timeline does not contain a latest run entry")
+
+run_manifest_path = project_root / latest_run["runManifestPath"]
+run_manifest = load_json(run_manifest_path)
+team_state_path = project_root / run_manifest["teamStatePath"]
+team_state = load_json(team_state_path)
+report_path = project_root / run_manifest["expectedReportPath"]
+final_status_path = project_root / run_manifest["expectedStatusPath"]
+
+status_by_worker_id = {
+    "claude": "completed",
+    "codex": "timeout",
+    "gemini": "error",
+    "report-writer": "completed",
+}
+reason_by_worker_id = {
+    "claude": "",
+    "codex": "Validation fixture timeout",
+    "gemini": "Validation fixture execution error",
+    "report-writer": "",
+}
+
+for worker in team_state.get("workers", []):
+    if not isinstance(worker, dict):
+        continue
+    worker_id = str(worker.get("workerId", "")).strip()
+    if not worker_id:
+        continue
+    worker["status"] = status_by_worker_id.get(worker_id, "not-run")
+    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:
+        prompt_path = project_root / prompt_relative
+        prompt_path.parent.mkdir(parents=True, exist_ok=True)
+        prompt_path.write_text(
+            "\n".join(
+                [
+                    f"# {worker.get('role', worker_id)} Prompt Snapshot",
+                    "",
+                    f"Assigned worker prompt history path: {prompt_relative}",
+                    f"Task Key: {task_manifest.get('taskKey', '')}",
+                    "Validation fixture prompt body.",
+                ]
+            )
+            + "\n"
+        )
+
+    result_relative = str(worker.get("resultPath", "")).strip()
+    if worker["status"] == "completed" and result_relative:
+        result_path = project_root / result_relative
+        result_path.parent.mkdir(parents=True, exist_ok=True)
+        result_path.write_text(
+            "\n".join(
+                [
+                    "# Findings",
+                    "- Validation fixture finding.",
+                    "",
+                    "# Missing Information or Assumptions",
+                    "- None.",
+                    "",
+                    "# Safe or Reasonable Areas",
+                    "- Fixture output format is valid.",
+                    "",
+                    "# Uncertain Points",
+                    "- None.",
+                    "",
+                    "# Recommended Next Actions",
+                    "- Continue validator coverage.",
+                ]
+            )
+            + "\n"
+        )
+
+lead = team_state.get("lead")
+if isinstance(lead, dict):
+    lead["status"] = "completed"
+team_state["workflowState"] = "worker-results-collected"
+
+# Phase 7 token-usage collection is normally produced by okstra-token-usage.py.
+# The validator (`team-state.usageSummary is empty`) treats absence as a contract
+# violation, so the fixture must mirror that step with a synthetic-but-valid object.
+team_state["usageSummary"] = {
+    "leadTotalTokens": 0,
+    "workerTotalTokens": 0,
+    "grandTotalTokens": 0,
+    "leadBillableEquivalentTokens": 0,
+    "workerBillableEquivalentTokens": 0,
+    "grandBillableEquivalentTokens": 0,
+    "estimatedCostUsd": {
+        "lead": 0.0,
+        "claudeWorkers": 0.0,
+        "cliWorkers": 0.0,
+        "grandTotal": 0.0,
+    },
+    "collectedAt": "1970-01-01T00:00:00Z",
+    "teamName": team_state.get("teamName", "validation-fixture"),
+    "sessionsFound": 0,
+    "definitions": {
+        "totalTokens": "Validation fixture placeholder.",
+        "billableEquivalentTokens": "Validation fixture placeholder.",
+        "estimatedCostUsd": "Validation fixture placeholder.",
+    },
+    "intake": {
+        "totalTokens": 0,
+        "billableEquivalentTokens": 0,
+        "estimatedCostUsd": 0,
+    },
+}
+
+required_status_entries = run_manifest.get("teamContract", {}).get(
+    "requiredAgentStatusEntries", []
+)
+if not isinstance(required_status_entries, list):
+    required_status_entries = []
+
+report_lines = [
+    "# Validation Fixture Report",
+    "",
+    "## Agent Execution Status",
+]
+for label in required_status_entries:
+    if isinstance(label, str) and label.strip():
+        report_lines.append(f"- {label}: fixture status recorded")
+report_lines.extend(
+    [
+        "",
+        "## Final Verdict",
+        "- Validation fixture report generated.",
+    ]
+)
+report_path.parent.mkdir(parents=True, exist_ok=True)
+report_path.write_text("\n".join(report_lines) + "\n")
+
+if final_status_path.exists():
+    final_status_path.unlink()
+
+write_json(team_state_path, team_state)
+write_json(run_manifest_path, run_manifest)
+write_json(task_manifest_path, task_manifest)
+PY
+}

package/runtime/validators/lib/paths.sh

@@ -0,0 +1,44 @@
+# shellcheck shell=bash
+
+validate_project_root_safety() {
+  if [[ -z "${PROJECT_ROOT:-}" ]]; then
+    fail "PROJECT_ROOT is not defined"
+  fi
+
+  if [[ "$PROJECT_ROOT" != /tmp/okstra-validate.* ]]; then
+    fail "Refusing to reset unexpected PROJECT_ROOT: $PROJECT_ROOT"
+  fi
+}
+
+reset_validation_root() {
+  rm -rf "$PROJECT_ROOT"
+  mkdir -p "$PROJECT_ROOT"
+}
+
+task_key() {
+  local task_group="$1"
+  local task_id="$2"
+
+  printf '%s:%s:%s\n' "$PROJECT_ID" "$task_group" "$task_id"
+}
+
+task_root() {
+  local task_group="$1"
+  local task_id="$2"
+
+  printf '%s/.project-docs/okstra/tasks/%s/%s\n' "$PROJECT_ROOT" "$task_group" "$task_id"
+}
+
+task_manifest_relative_path() {
+  local task_group="$1"
+  local task_id="$2"
+
+  printf '.project-docs/okstra/tasks/%s/%s/task-manifest.json\n' "$task_group" "$task_id"
+}
+
+reference_expectations_relative_path() {
+  local task_group="$1"
+  local task_id="$2"
+
+  printf '.project-docs/okstra/tasks/%s/%s/instruction-set/reference-expectations.md\n' "$task_group" "$task_id"
+}

package/runtime/validators/lib/runners.sh

@@ -0,0 +1,140 @@
+# shellcheck shell=bash
+
+run_okstra() {
+  local task_group="$1"
+  local task_id="$2"
+  local brief_filename="$3"
+  shift 3
+
+  if (($# > 0)); then
+    local -a extra_args=("$@")
+    bash "$OKSTRA_SCRIPT" \
+      --render-only \
+      --yes \
+      --task-type "$TASK_TYPE" \
+      --project-id "$PROJECT_ID" \
+      --project-root "$PROJECT_ROOT" \
+      --task-group "$task_group" \
+      --task-id "$task_id" \
+      --task-brief "$brief_filename" \
+      "${extra_args[@]}"
+    return
+  fi
+
+  bash "$OKSTRA_SCRIPT" \
+    --render-only \
+    --yes \
+    --task-type "$TASK_TYPE" \
+    --project-id "$PROJECT_ID" \
+    --project-root "$PROJECT_ROOT" \
+    --task-group "$task_group" \
+    --task-id "$task_id" \
+    --task-brief "$brief_filename"
+}
+
+run_validator_expectation() {
+  local task_group="$1"
+  local task_id="$2"
+  local expected_status="$3"
+  local expected_failure_substring="${4-}"
+  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" "$RUN_VALIDATOR_SCRIPT" "$expected_status" "$expected_failure_substring" <<'PY'
+from pathlib import Path
+import json
+import subprocess
+import sys
+
+project_root = Path(sys.argv[1])
+task_manifest_path = project_root / sys.argv[2]
+validator_script = Path(sys.argv[3])
+expected_status = sys.argv[4]
+expected_failure_substring = sys.argv[5]
+
+task_manifest = json.loads(task_manifest_path.read_text())
+timeline_path = project_root / task_manifest["historyTimelinePath"]
+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:
+    raise SystemExit("timeline does not contain a latest run entry")
+
+run_manifest_path = project_root / latest_run["runManifestPath"]
+run_manifest = json.loads(run_manifest_path.read_text())
+team_state_path = project_root / run_manifest["teamStatePath"]
+report_path = project_root / run_manifest["expectedReportPath"]
+final_status_path = project_root / run_manifest["expectedStatusPath"]
+
+process = subprocess.run(
+    [
+        sys.executable,
+        str(validator_script),
+        "--team-state",
+        str(team_state_path),
+        "--report",
+        str(report_path),
+        "--run-manifest",
+        str(run_manifest_path),
+        "--task-manifest",
+        str(task_manifest_path),
+        "--final-status",
+        str(final_status_path),
+    ],
+    capture_output=True,
+    text=True,
+)
+
+if not process.stdout.strip():
+    raise SystemExit("validator did not produce JSON output")
+
+payload = json.loads(process.stdout)
+actual_status = payload.get("validationStatus")
+if actual_status != expected_status:
+    raise SystemExit(
+        f"validator status mismatch: expected {expected_status}, got {actual_status}"
+    )
+
+if expected_status == "passed" and process.returncode != 0:
+    raise SystemExit(f"validator returned non-zero on success: {process.stderr}")
+if expected_status == "failed" and process.returncode == 0:
+    raise SystemExit("validator unexpectedly succeeded")
+
+if expected_failure_substring:
+    failures = payload.get("failures", [])
+    if not isinstance(failures, list) or not any(
+        expected_failure_substring in str(item) for item in failures
+    ):
+        raise SystemExit(
+            f"validator failure output did not include expected text: {expected_failure_substring}"
+        )
+
+if not final_status_path.is_file():
+    raise SystemExit(f"validator did not write final status file: {final_status_path}")
+
+final_status = final_status_path.read_text().strip()
+expected_final_status = "completed" if expected_status == "passed" else "contract-violated"
+if final_status != expected_final_status:
+    raise SystemExit(
+        f"final status file mismatch: expected {expected_final_status}, got {final_status}"
+    )
+
+updated_run_manifest = json.loads(run_manifest_path.read_text())
+updated_task_manifest = json.loads(task_manifest_path.read_text())
+updated_team_state = json.loads(team_state_path.read_text())
+
+if updated_run_manifest.get("validation", {}).get("status") != expected_status:
+    raise SystemExit("run manifest validation status was not updated correctly")
+if updated_task_manifest.get("contractValidation", {}).get("status") != expected_status:
+    raise SystemExit("task manifest validation status was not updated correctly")
+if updated_team_state.get("validator", {}).get("status") != expected_status:
+    raise SystemExit("team-state validator status was not updated correctly")
+PY
+}

package/runtime/validators/lib/summary.sh

@@ -0,0 +1,15 @@
+# shellcheck shell=bash
+
+print_summary() {
+  cat <<EOF
+
+Validation completed successfully.
+- Validation root: $PROJECT_ROOT
+- Latest-task discovery file: $DISCOVERY_FILE
+- Task catalog file: $CATALOG_FILE
+- Primary task root: $(task_root "$PRIMARY_TASK_GROUP" "$PRIMARY_TASK_ID")
+- Secondary task root: $(task_root "$SECONDARY_TASK_GROUP" "$SECONDARY_TASK_ID")
+
+You can inspect the generated artifacts directly under the validation root.
+EOF
+}

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

@@ -0,0 +1,44 @@
+# shellcheck shell=bash
+
+validate_seeded_assets() {
+  local validation_mode="$1"
+
+  python3 - "$SOURCE_ASSET_ROOT" "$PROJECT_ROOT/.claude" "$validation_mode" <<'PY'
+from pathlib import Path
+import sys
+
+source_root = Path(sys.argv[1])
+target_root = Path(sys.argv[2])
+validation_mode = sys.argv[3]
+errors = []
+
+for source_path in sorted(source_root.rglob("*.md")):
+    relative_path = source_path.relative_to(source_root)
+    parts = relative_path.parts
+
+    if relative_path.as_posix() == "SKILL.md":
+        target_path = target_root / "skills" / "okstra" / "SKILL.md"
+    elif parts[0] == "skills":
+        target_path = target_root / "skills" / Path(*parts[1:])
+    elif parts[0] == "workers":
+        # `agents/workers/<name>.md` 는 `.claude/agents/<name>.md` 로 시드된다.
+        # seeding.sh 의 분기와 동일하게 유지해야 한다.
+        target_path = target_root / "agents" / Path(*parts[1:])
+    elif parts[0] == "agents":
+        target_path = target_root / "agents" / Path(*parts[1:])
+    else:
+        target_path = target_root / "skills" / "okstra" / relative_path
+
+    if not target_path.is_file():
+        errors.append(f"missing seeded asset: {target_path}")
+        continue
+
+    if validation_mode == "match" and target_path.read_bytes() != source_path.read_bytes():
+        errors.append(f"seeded asset content does not match source: {target_path}")
+
+if errors:
+    for error in errors:
+        print(error, file=sys.stderr)
+    sys.exit(1)
+PY
+}