okstra 0.1.0

package/runtime/python/lib/okstra/cli.sh

@@ -0,0 +1,227 @@
+# shellcheck shell=bash
+
+collect_required_arguments() {
+  local missing_required=""
+
+  missing_required="$(missing_required_arguments_summary)"
+  if [[ -z "$missing_required" ]]; then
+    return 0
+  fi
+  if [[ "$ASSUME_YES" == "true" ]]; then
+    printf '%s\n' "--yes requires all required arguments. Missing: $missing_required" >&2
+    usage
+    exit 1
+  fi
+
+  if ! is_interactive_session; then
+    printf 'missing required arguments: %s\n' "$missing_required" >&2
+    usage
+    exit 1
+  fi
+
+  printf 'okstra is missing required arguments. Please provide the following values.\n' >&2
+  prompt_for_required_argument PROJECT_ID "Project ID"
+  prompt_for_required_argument TASK_GROUP "Task Group"
+  prompt_for_required_argument TASK_ID "Task ID"
+  prompt_for_required_argument ANALYSIS_TYPE "Task Type"
+  prompt_for_required_argument BRIEF_PATH "Task Brief Path"
+}
+
+confirm_execution_plan() {
+  local confirmation=""
+  local normalized_confirmation=""
+  if [[ "$ASSUME_YES" == "true" ]]; then
+    return 0
+  fi
+
+  if ! is_interactive_session; then
+    return 0
+  fi
+
+  cat >&2 <<CONFIRM_EOF
+okstra execution summary:
+  render only: ${RENDER_ONLY}
+  task type: ${ANALYSIS_TYPE}
+  project id: ${PROJECT_ID}
+  task group: ${TASK_GROUP}
+  task id: ${TASK_ID}
+  task brief path: ${BRIEF_FILE_PATH}
+  clarification response: ${CLARIFICATION_RESPONSE_FILE:-None}
+  related tasks: ${RELATED_TASKS_INLINE}
+  recommended workers: ${SELECTED_REVIEWERS}
+  lead model: ${LEAD_MODEL_DISPLAY}
+  worker models: claude=${CLAUDE_WORKER_MODEL_DISPLAY}, codex=${CODEX_WORKER_MODEL_DISPLAY}, gemini=${GEMINI_WORKER_MODEL_DISPLAY}, report-writer=${REPORT_WRITER_MODEL_DISPLAY}
+  task key input: ${TASK_KEY_INPUT:-None}
+  task key: ${TASK_KEY}
+  task root: ${TASK_ROOT}
+  run dir: ${RUN_DIR}
+  final report path: ${FINAL_REPORT_FILE}
+  final report template: ${FINAL_REPORT_TEMPLATE_FILE}
+CONFIRM_EOF
+
+  printf 'Continue? [y/yes]: ' >&2
+  if ! IFS= read -r confirmation; then
+    printf 'confirmation cancelled\n' >&2
+    exit 1
+  fi
+
+  normalized_confirmation="$(trim_whitespace "$confirmation")"
+  normalized_confirmation="$(printf '%s' "$normalized_confirmation" | tr '[:upper:]' '[:lower:]')"
+
+  if [[ "$normalized_confirmation" != "y" && "$normalized_confirmation" != "yes" ]]; then
+    printf 'okstra cancelled before execution\n' >&2
+    exit 1
+  fi
+}
+require_option_value() {
+  local option_name="$1"
+  local option_value="${2-}"
+
+  if [[ -z "$option_value" ]]; then
+    printf 'missing value for %s\n' "$option_name" >&2
+    usage
+    exit 1
+  fi
+
+  printf '%s' "$option_value"
+}
+
+parse_cli_arguments() {
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --render-only)
+      RENDER_ONLY="true"
+      shift
+      ;;
+    --resume-clarification)
+      RESUME_CLARIFICATION_MODE="true"
+      shift
+      ;;
+    --yes)
+      ASSUME_YES="true"
+      shift
+      ;;
+    --refresh-assets)
+      printf 'warning: --refresh-assets is deprecated. okstra now installs into ~/.claude and ~/.okstra via okstra-install.sh.\n' >&2
+      printf '         re-run "%s/scripts/okstra-install.sh --refresh" to refresh installed assets.\n' "$WORKSPACE_ROOT" >&2
+      REFRESH_OKSTRA_ASSETS="true"
+      shift
+      ;;
+    --workers)
+      WORKERS_OVERRIDE="$(require_option_value --workers "${2-}")"
+      shift 2
+      ;;
+    --lead-model)
+      LEAD_MODEL_OVERRIDE="$(require_option_value --lead-model "${2-}")"
+      shift 2
+      ;;
+    --claude-model)
+      CLAUDE_MODEL_OVERRIDE="$(require_option_value --claude-model "${2-}")"
+      shift 2
+      ;;
+    --codex-model)
+      CODEX_MODEL_OVERRIDE="$(require_option_value --codex-model "${2-}")"
+      shift 2
+      ;;
+    --gemini-model)
+      GEMINI_MODEL_OVERRIDE="$(require_option_value --gemini-model "${2-}")"
+      shift 2
+      ;;
+    --report-writer-model)
+      REPORT_WRITER_MODEL_OVERRIDE="$(require_option_value --report-writer-model "${2-}")"
+      shift 2
+      ;;
+    --related-tasks)
+      RELATED_TASKS_RAW="$(require_option_value --related-tasks "${2-}")"
+      shift 2
+      ;;
+    --task-type)
+      ANALYSIS_TYPE="$(require_option_value --task-type "${2-}")"
+      shift 2
+      ;;
+    --project-id)
+      PROJECT_ID="$(require_option_value --project-id "${2-}")"
+      shift 2
+      ;;
+    --project-root)
+      PROJECT_ROOT_OVERRIDE="$(require_option_value --project-root "${2-}")"
+      shift 2
+      ;;
+    --task-group)
+      TASK_GROUP="$(require_option_value --task-group "${2-}")"
+      shift 2
+      ;;
+    --task-id)
+      TASK_ID="$(require_option_value --task-id "${2-}")"
+      shift 2
+      ;;
+    --task-brief)
+      BRIEF_PATH="$(require_option_value --task-brief "${2-}")"
+      shift 2
+      ;;
+    --directive)
+      DIRECTIVE="$(require_option_value --directive "${2-}")"
+      shift 2
+      ;;
+    --clarification-response)
+      CLARIFICATION_RESPONSE_PATH="$(require_option_value --clarification-response "${2-}")"
+      shift 2
+      ;;
+    --task-key)
+      TASK_KEY_INPUT="$(require_option_value --task-key "${2-}")"
+      shift 2
+      ;;
+    --approved-plan)
+      APPROVED_PLAN_PATH="$(require_option_value --approved-plan "${2-}")"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    -*)
+      __unknown_opt="$1"
+      __opt_name="${__unknown_opt%%=*}"
+      printf 'unknown option: %s\n' "$__unknown_opt" >&2
+      case "$__opt_name" in
+        --phase|--phases|--lifecycle-phase)
+          printf '  hint: --phase is not a valid flag. Use --task-type <requirements-discovery|error-analysis|implementation-planning|implementation|final-verification>.\n' >&2
+          printf '        "phase" is a manifest lifecycle field name, not a CLI option.\n' >&2
+          ;;
+        --brief|--task-brief)
+          printf '  hint: did you mean --task-brief?\n' >&2
+          ;;
+        --analysis-target|--target|--review-target)
+          printf '  hint: --analysis-target was removed. Put supplementary materials inside the task brief itself.\n' >&2
+          ;;
+        --project|--proj)
+          printf '  hint: did you mean --project-id?\n' >&2
+          ;;
+        --group)
+          printf '  hint: did you mean --task-group?\n' >&2
+          ;;
+        --id)
+          printf '  hint: did you mean --task-id?\n' >&2
+          ;;
+      esac
+      printf '  valid options: --render-only --resume-clarification --yes --refresh-assets --workers --lead-model --claude-model --codex-model --gemini-model --report-writer-model --related-tasks --task-type --project-id --project-root --task-group --task-id --task-brief --directive --clarification-response --approved-plan -h|--help\n' >&2
+      usage
+      exit 1
+      ;;
+    *)
+      printf 'unexpected positional argument: %s\n' "$1" >&2
+      if [[ "$1" == *:*:* ]]; then
+        __key_proj="${1%%:*}"
+        __key_rest="${1#*:}"
+        __key_group="${__key_rest%%:*}"
+        __key_id="${__key_rest#*:}"
+        printf '  hint: looks like a manifest taskKey (project:group:id). Pass it via --task-key, e.g. --task-key %s:%s:%s\n' "$__key_proj" "$__key_group" "$__key_id" >&2
+      else
+        printf '  hint: all inputs must be passed as named flags. See usage below.\n' >&2
+      fi
+      usage
+      exit 1
+      ;;
+  esac
+done
+}

package/runtime/python/lib/okstra/globals.sh

@@ -0,0 +1,157 @@
+# shellcheck shell=bash
+
+PROFILE_DIR="$WORKSPACE_ROOT/prompts/profiles"
+PROMPT_TEMPLATE="$WORKSPACE_ROOT/prompts/launch.template.md"
+TASK_INDEX_TEMPLATE="$WORKSPACE_ROOT/templates/project-docs/task-index.template.md"
+FINAL_REPORT_TEMPLATE_SOURCE="$WORKSPACE_ROOT/templates/reports/final-report.template.md"
+RUN_VALIDATOR_SCRIPT="$WORKSPACE_ROOT/validators/validate-run.py"
+SOURCE_CLAUDE_OKSTRA_SKILL="$WORKSPACE_ROOT/agents/SKILL.md"
+OKSTRA_ROOT=""
+OKSTRA_TASKS_ROOT=""
+OKSTRA_DISCOVERY_DIR=""
+OKSTRA_DISCOVERY_RELATIVE_PATH=""
+OKSTRA_LATEST_TASK_FILE=""
+OKSTRA_LATEST_TASK_RELATIVE_PATH=""
+OKSTRA_TASK_CATALOG_FILE=""
+OKSTRA_TASK_CATALOG_RELATIVE_PATH=""
+RENDER_ONLY="false"
+ASSUME_YES="false"
+RESUME_CLARIFICATION_MODE="false"
+REFRESH_OKSTRA_ASSETS="false"
+WORKERS_OVERRIDE=""
+LEAD_MODEL_OVERRIDE=""
+CLAUDE_MODEL_OVERRIDE=""
+CODEX_MODEL_OVERRIDE=""
+GEMINI_MODEL_OVERRIDE=""
+REPORT_WRITER_MODEL_OVERRIDE=""
+RELATED_TASKS_RAW=""
+ANALYSIS_TYPE=""
+BRIEF_PATH=""
+PROJECT_ID=""
+TASK_GROUP=""
+TASK_ID=""
+TASK_KEY_INPUT=""
+TASK_KEY=""
+REVIEW_PROFILE=""
+DIRECTIVE=""
+CLARIFICATION_RESPONSE_PATH=""
+APPROVED_PLAN_PATH=""
+CLARIFICATION_RESPONSE_FILE=""
+CLARIFICATION_RESPONSE_RELATIVE_PATH=""
+PROJECT_ROOT=""
+PROJECT_ROOT_OVERRIDE=""
+PROFILE_FILE=""
+BRIEF_FILE_PATH=""
+REVIEW_MATERIAL=""
+PROFILE_CONTENT=""
+SELECTED_REVIEWERS=""
+BRIEF_RELATIVE_PATH=""
+TASK_GROUP_SEGMENT=""
+TASK_ID_SEGMENT=""
+TASK_ROOT=""
+TASK_MANIFEST_FILE=""
+TASK_INDEX_FILE=""
+INSTRUCTION_SET_DIR=""
+RUNS_DIR=""
+HISTORY_DIR=""
+TIMELINE_FILE=""
+RUN_DIR=""
+RUN_MANIFESTS_DIR=""
+RUN_STATE_DIR=""
+RUN_PROMPTS_DIR=""
+RUN_REPORTS_DIR=""
+RUN_STATUS_DIR=""
+RUN_SESSIONS_DIR=""
+RUN_LOGS_DIR=""
+RUN_MANIFEST_FILE=""
+RUN_MANIFEST_RELATIVE_PATH=""
+RUN_PROMPT_SNAPSHOT_FILE=""
+RUN_PROMPT_SNAPSHOT_RELATIVE_PATH=""
+CLAUDE_WORKER_PROMPT_FILE=""
+CLAUDE_WORKER_PROMPT_RELATIVE_PATH=""
+CODEX_WORKER_PROMPT_FILE=""
+CODEX_WORKER_PROMPT_RELATIVE_PATH=""
+GEMINI_WORKER_PROMPT_FILE=""
+GEMINI_WORKER_PROMPT_RELATIVE_PATH=""
+REPORT_WRITER_WORKER_PROMPT_FILE=""
+REPORT_WRITER_WORKER_PROMPT_RELATIVE_PATH=""
+FINAL_REPORT_FILE=""
+FINAL_STATUS_FILE=""
+FINAL_REPORT_RELATIVE_PATH=""
+FINAL_STATUS_RELATIVE_PATH=""
+FINAL_REPORT_TEMPLATE_FILE=""
+FINAL_REPORT_TEMPLATE_RELATIVE_PATH=""
+REFERENCE_EXPECTATIONS_FILE=""
+REFERENCE_EXPECTATIONS_RELATIVE_PATH=""
+TEAM_STATE_FILE=""
+TEAM_STATE_RELATIVE_PATH=""
+WORKER_RESULTS_DIR=""
+WORKER_RESULTS_RELATIVE_PATH=""
+RUN_VALIDATOR_RELATIVE_PATH=""
+CLAUDE_WORKER_RESULT_FILE=""
+CLAUDE_WORKER_RESULT_RELATIVE_PATH=""
+CODEX_WORKER_RESULT_FILE=""
+CODEX_WORKER_RESULT_RELATIVE_PATH=""
+GEMINI_WORKER_RESULT_FILE=""
+GEMINI_WORKER_RESULT_RELATIVE_PATH=""
+REPORT_WRITER_WORKER_RESULT_FILE=""
+REPORT_WRITER_WORKER_RESULT_RELATIVE_PATH=""
+CLAUDE_SESSION_ID=""
+CLAUDE_RESUME_COMMAND_FILE=""
+CLAUDE_RESUME_COMMAND_RELATIVE_PATH=""
+RUN_TIMESTAMP_ISO=""
+RUN_DATETIME_SEGMENT=""
+RUN_TIME_SEGMENT=""
+RUN_FILE_SUFFIX=""
+RUN_MANIFESTS_SEQ=""
+RUN_PROMPTS_SEQ=""
+RUN_REPORTS_SEQ=""
+RUN_STATUS_SEQ=""
+RUN_STATE_SEQ=""
+RUN_SESSIONS_SEQ=""
+WORKER_RESULTS_SEQ=""
+TASK_ROOT_RELATIVE_PATH=""
+TASK_MANIFEST_RELATIVE_PATH=""
+TASK_INDEX_RELATIVE_PATH=""
+INSTRUCTION_SET_RELATIVE_PATH=""
+RUNS_RELATIVE_PATH=""
+HISTORY_RELATIVE_PATH=""
+TIMELINE_RELATIVE_PATH=""
+RUN_DIR_RELATIVE_PATH=""
+RUN_MANIFESTS_RELATIVE_PATH=""
+RUN_STATE_RELATIVE_PATH=""
+RUN_PROMPTS_RELATIVE_PATH=""
+RUN_REPORTS_RELATIVE_PATH=""
+RUN_STATUS_RELATIVE_PATH=""
+RUN_SESSIONS_RELATIVE_PATH=""
+LATEST_RUN_PATH=""
+LATEST_RUN_RELATIVE_PATH=""
+LATEST_REPORT_PATH=""
+LATEST_REPORT_RELATIVE_PATH=""
+CURRENT_TASK_STATUS=""
+CURRENT_RUN_STATUS=""
+VALIDATION_STATUS="not-run"
+VALIDATION_UPDATED_AT=""
+VALIDATION_FAILURES_JSON="[]"
+RELATED_TASKS_JSON="[]"
+RELATED_TASKS_BULLETS="- None recorded"
+RELATED_TASKS_INLINE="None"
+PROMPT=""
+LEAD_MODEL_DISPLAY=""
+LEAD_MODEL_EXECUTION_VALUE=""
+CLAUDE_WORKER_MODEL_DISPLAY=""
+CLAUDE_WORKER_MODEL_EXECUTION_VALUE=""
+CODEX_WORKER_MODEL_DISPLAY=""
+CODEX_WORKER_MODEL_EXECUTION_VALUE=""
+GEMINI_WORKER_MODEL_DISPLAY=""
+GEMINI_WORKER_MODEL_EXECUTION_VALUE=""
+REPORT_WRITER_MODEL_DISPLAY=""
+REPORT_WRITER_MODEL_EXECUTION_VALUE=""
+DEFAULT_WORKERS="claude,codex,gemini,report-writer"
+DEFAULT_LEAD_MODEL_NAME="${OKSTRA_DEFAULT_LEAD_MODEL:-opus}"
+DEFAULT_CLAUDE_WORKER_MODEL_NAME="${OKSTRA_DEFAULT_CLAUDE_MODEL:-sonnet}"
+DEFAULT_CODEX_WORKER_MODEL_NAME="${OKSTRA_DEFAULT_CODEX_MODEL:-gpt-5.5}"
+DEFAULT_GEMINI_WORKER_MODEL_NAME="${OKSTRA_DEFAULT_GEMINI_MODEL:-auto}"
+DEFAULT_REPORT_WRITER_MODEL_NAME="${OKSTRA_DEFAULT_REPORT_WRITER_MODEL:-$DEFAULT_LEAD_MODEL_NAME}"
+DISPLAY_COMMAND_NAME="${OKSTRA_COMMAND_NAME:-$(basename "$0")}"
+DISPLAY_TOOL_NAME="${OKSTRA_TOOL_NAME:-okstra}"