create-ccc-tutor 0.1.0

package/template/.harness/scripts/checkpoint-write.sh

@@ -0,0 +1,281 @@
+#!/usr/bin/env bash
+# checkpoint-write.sh — atomic writer for .harness/state/workflow-checkpoints/<feature>.json
+#
+# Called by every stage skill at its successful completion. Centralizes the
+# checkpoint schema (single source of truth — change schema here, all skills
+# inherit it). Per Phase 5 (Session resume) of the v0.9.0 release.
+#
+# USAGE:
+#   checkpoint-write.sh --feature <slug> [options]
+#
+# OPTIONS:
+#   --feature <slug>                  Required. Feature slug (matches branch name suffix).
+#   --branch <name>                   Override detected branch (default: current git branch).
+#   --mode <new-feature|audit>        Workflow mode (default: new-feature).
+#   --lane <full|stability-fix|trivial>  Workflow lane (default: full).
+#   --stage <N>                       Set current_stage to N.
+#   --stage-complete <N>              Mark stage N as complete (append to stages_completed).
+#   --stage-skip <N> --skip-reason <text>  Mark stage N as skipped with reason.
+#   --artifact-spec <path>            Record spec artifact path (computes sha256).
+#   --artifact-implementation <path>  Record implementation-doc artifact path.
+#   --artifact-plan <path>            Record execution-plan artifact path.
+#   --artifact-schema <path>          Record schema artifact path.
+#   --append-audit '<json>'           Append one audit entry. JSON: {"stage":N,"verdict":"...","risk":N,"at":"<iso>"}
+#   --stage-in-progress '<json>'      Replace stage_in_progress block. JSON: {"stage_number":N,"files_total":N,...}
+#   --file-done <path>                Append one path to stage_in_progress.files_done_list (idempotent: dedupe).
+#   --append-decision '<json>'        Append one decision entry. JSON: {"at":"...","stage":N,"by":"CEO","decision":"..."}
+#   --archive                         Move checkpoint to _archived/<feature>-<timestamp>.json (used by /commit).
+#   --create-if-missing               Create a minimal checkpoint if file doesn't exist (used by /feature-draft as first stage).
+#
+# OUTPUT:
+#   - On success: prints "✓ checkpoint updated: <path>" to stdout, exits 0.
+#   - On error:   prints error to stderr, exits 1.
+#
+# DESIGN NOTES:
+#   - Atomic write: tmp + rename (won't leave half-written checkpoint).
+#   - Idempotent: rerunning the same call doesn't duplicate stages/files.
+#   - Schema versioning: bumps schema_version if needed, refuses to write older schema over newer.
+#   - jq is required.
+
+set -euo pipefail
+export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "checkpoint-write.sh requires jq. Install with: brew install jq" >&2
+  exit 1
+fi
+
+# ─── Defaults / state ──────────────────────────────────────────────────
+SCHEMA_VERSION=1
+FEATURE=""
+BRANCH=""
+MODE=""
+LANE=""
+SET_STAGE=""
+COMPLETE_STAGE=""
+SKIP_STAGE=""
+SKIP_REASON=""
+ARTIFACT_SPEC=""
+ARTIFACT_IMPL=""
+ARTIFACT_PLAN=""
+ARTIFACT_SCHEMA=""
+APPEND_AUDIT=""
+STAGE_IN_PROGRESS=""
+FILE_DONE=""
+APPEND_DECISION=""
+ARCHIVE=false
+CREATE_IF_MISSING=false
+
+# ─── Parse args ────────────────────────────────────────────────────────
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --feature)              FEATURE="$2"; shift 2 ;;
+    --branch)               BRANCH="$2"; shift 2 ;;
+    --mode)                 MODE="$2"; shift 2 ;;
+    --lane)                 LANE="$2"; shift 2 ;;
+    --stage)                SET_STAGE="$2"; shift 2 ;;
+    --stage-complete)       COMPLETE_STAGE="$2"; shift 2 ;;
+    --stage-skip)           SKIP_STAGE="$2"; shift 2 ;;
+    --skip-reason)          SKIP_REASON="$2"; shift 2 ;;
+    --artifact-spec)        ARTIFACT_SPEC="$2"; shift 2 ;;
+    --artifact-implementation) ARTIFACT_IMPL="$2"; shift 2 ;;
+    --artifact-plan)        ARTIFACT_PLAN="$2"; shift 2 ;;
+    --artifact-schema)      ARTIFACT_SCHEMA="$2"; shift 2 ;;
+    --append-audit)         APPEND_AUDIT="$2"; shift 2 ;;
+    --stage-in-progress)    STAGE_IN_PROGRESS="$2"; shift 2 ;;
+    --file-done)            FILE_DONE="$2"; shift 2 ;;
+    --append-decision)      APPEND_DECISION="$2"; shift 2 ;;
+    --archive)              ARCHIVE=true; shift ;;
+    --create-if-missing)    CREATE_IF_MISSING=true; shift ;;
+    *)
+      echo "Unknown arg: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+if [ -z "$FEATURE" ]; then
+  echo "checkpoint-write.sh: --feature <slug> required" >&2
+  exit 1
+fi
+
+CHECKPOINT_DIR=".harness/state/workflow-checkpoints"
+CHECKPOINT_FILE="$CHECKPOINT_DIR/${FEATURE}.json"
+mkdir -p "$CHECKPOINT_DIR"
+
+NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+# Detect branch if not provided
+if [ -z "$BRANCH" ]; then
+  BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null || echo "(no branch)")
+fi
+
+# ─── Archive mode (used by /commit at Stage 8) ─────────────────────────
+if [ "$ARCHIVE" = "true" ]; then
+  if [ ! -f "$CHECKPOINT_FILE" ]; then
+    echo "✓ checkpoint not found for $FEATURE (already archived or never created); no-op"
+    exit 0
+  fi
+  ARCHIVE_DIR="$CHECKPOINT_DIR/_archived"
+  mkdir -p "$ARCHIVE_DIR"
+  ARCHIVED_FILE="$ARCHIVE_DIR/${FEATURE}-$(date -u +%Y%m%dT%H%M%SZ).json"
+  mv "$CHECKPOINT_FILE" "$ARCHIVED_FILE"
+  echo "✓ checkpoint archived: $ARCHIVED_FILE"
+  exit 0
+fi
+
+# ─── Create-if-missing (initial checkpoint from /feature-draft Stage 1) ───
+if [ ! -f "$CHECKPOINT_FILE" ]; then
+  if [ "$CREATE_IF_MISSING" = "true" ]; then
+    INIT_MODE="${MODE:-new-feature}"
+    INIT_LANE="${LANE:-full}"
+    INIT_STAGE="${SET_STAGE:-1}"
+    jq -n \
+      --argjson schema_version "$SCHEMA_VERSION" \
+      --arg feature "$FEATURE" \
+      --arg branch "$BRANCH" \
+      --arg started_at "$NOW" \
+      --arg last_at "$NOW" \
+      --arg mode "$INIT_MODE" \
+      --arg lane "$INIT_LANE" \
+      --argjson stage "$INIT_STAGE" \
+      '{
+         schema_version: $schema_version,
+         feature: $feature,
+         feature_slug: $feature,
+         branch: $branch,
+         started_at: $started_at,
+         last_activity_at: $last_at,
+         mode: $mode,
+         lane: $lane,
+         current_stage: $stage,
+         stages_completed: [],
+         stages_skipped: [],
+         stages_skipped_reasons: {},
+         artifacts: { spec: null, implementation: null, plan: null, schema: null },
+         audits: [],
+         stage_in_progress: null,
+         decisions: [],
+         session_chain: []
+       }' > "$CHECKPOINT_FILE"
+    # Fall through to apply any additional updates from this call
+  else
+    echo "checkpoint-write.sh: $CHECKPOINT_FILE does not exist. Use --create-if-missing to bootstrap." >&2
+    exit 1
+  fi
+fi
+
+# ─── Atomic update via tmp + rename ────────────────────────────────────
+TMP_FILE=$(mktemp "${CHECKPOINT_FILE}.tmp.XXXXXX")
+trap 'rm -f "$TMP_FILE"' EXIT
+
+# Build a jq filter chain that applies all requested mutations
+JQ_FILTER='. | .last_activity_at = $now'
+
+# Mode / lane updates
+[ -n "$MODE" ] && JQ_FILTER="$JQ_FILTER | .mode = \$mode"
+[ -n "$LANE" ] && JQ_FILTER="$JQ_FILTER | .lane = \$lane"
+[ -n "$BRANCH" ] && JQ_FILTER="$JQ_FILTER | .branch = \$branch"
+
+# Stage current
+[ -n "$SET_STAGE" ] && JQ_FILTER="$JQ_FILTER | .current_stage = (\$set_stage | tonumber)"
+
+# Complete stage (dedupe via unique)
+[ -n "$COMPLETE_STAGE" ] && JQ_FILTER="$JQ_FILTER | .stages_completed = ((.stages_completed + [(\$complete_stage | tonumber)]) | unique)"
+
+# Skip stage
+if [ -n "$SKIP_STAGE" ]; then
+  JQ_FILTER="$JQ_FILTER | .stages_skipped = ((.stages_skipped + [(\$skip_stage | tonumber)]) | unique)"
+  if [ -n "$SKIP_REASON" ]; then
+    JQ_FILTER="$JQ_FILTER | .stages_skipped_reasons[\$skip_stage] = \$skip_reason"
+  fi
+fi
+
+# Portable sha256 (Mac uses shasum, Linux/Git-Bash use sha256sum)
+portable_sha256() {
+  local path="$1"
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$path" 2>/dev/null | awk '{print $1}' | head -c 16
+  elif command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 "$path" 2>/dev/null | awk '{print $1}' | head -c 16
+  elif command -v openssl >/dev/null 2>&1; then
+    openssl dgst -sha256 "$path" 2>/dev/null | awk '{print $NF}' | head -c 16
+  else
+    echo ""
+  fi
+}
+
+# Artifact paths (compute sha256 if file exists)
+compute_artifact_block() {
+  local path="$1"
+  if [ -f "$path" ]; then
+    local sha
+    sha=$(portable_sha256 "$path")
+    jq -n --arg p "$path" --arg s "$sha" '{path: $p, sha256: $s, exists: true}'
+  else
+    jq -n --arg p "$path" '{path: $p, sha256: null, exists: false}'
+  fi
+}
+
+if [ -n "$ARTIFACT_SPEC" ]; then
+  ART_SPEC_JSON=$(compute_artifact_block "$ARTIFACT_SPEC")
+  JQ_FILTER="$JQ_FILTER | .artifacts.spec = \$art_spec"
+fi
+if [ -n "$ARTIFACT_IMPL" ]; then
+  ART_IMPL_JSON=$(compute_artifact_block "$ARTIFACT_IMPL")
+  JQ_FILTER="$JQ_FILTER | .artifacts.implementation = \$art_impl"
+fi
+if [ -n "$ARTIFACT_PLAN" ]; then
+  ART_PLAN_JSON=$(compute_artifact_block "$ARTIFACT_PLAN")
+  JQ_FILTER="$JQ_FILTER | .artifacts.plan = \$art_plan"
+fi
+if [ -n "$ARTIFACT_SCHEMA" ]; then
+  ART_SCHEMA_JSON=$(compute_artifact_block "$ARTIFACT_SCHEMA")
+  JQ_FILTER="$JQ_FILTER | .artifacts.schema = \$art_schema"
+fi
+
+# Append audit entry
+if [ -n "$APPEND_AUDIT" ]; then
+  JQ_FILTER="$JQ_FILTER | .audits = (.audits + [\$append_audit])"
+fi
+
+# Replace stage_in_progress (full block)
+if [ -n "$STAGE_IN_PROGRESS" ]; then
+  JQ_FILTER="$JQ_FILTER | .stage_in_progress = \$stage_in_progress"
+fi
+
+# Append single file to files_done_list (idempotent dedupe)
+if [ -n "$FILE_DONE" ]; then
+  JQ_FILTER="$JQ_FILTER | .stage_in_progress = (.stage_in_progress // {stage_number: .current_stage, files_total: 0, files_done_list: [], files_remaining_list: [], last_action: null, resume_hint: null}) | .stage_in_progress.files_done_list = ((.stage_in_progress.files_done_list + [\$file_done]) | unique) | .stage_in_progress.last_action = (\"Wrote \" + \$file_done)"
+fi
+
+# Append decision entry
+if [ -n "$APPEND_DECISION" ]; then
+  JQ_FILTER="$JQ_FILTER | .decisions = (.decisions + [\$append_decision])"
+fi
+
+# Build the jq invocation with all required --arg / --argjson
+JQ_ARGS=(--arg now "$NOW")
+
+[ -n "$MODE" ]           && JQ_ARGS+=(--arg mode "$MODE")
+[ -n "$LANE" ]           && JQ_ARGS+=(--arg lane "$LANE")
+[ -n "$BRANCH" ]         && JQ_ARGS+=(--arg branch "$BRANCH")
+[ -n "$SET_STAGE" ]      && JQ_ARGS+=(--arg set_stage "$SET_STAGE")
+[ -n "$COMPLETE_STAGE" ] && JQ_ARGS+=(--arg complete_stage "$COMPLETE_STAGE")
+[ -n "$SKIP_STAGE" ]     && JQ_ARGS+=(--arg skip_stage "$SKIP_STAGE")
+[ -n "$SKIP_REASON" ]    && JQ_ARGS+=(--arg skip_reason "$SKIP_REASON")
+[ -n "$FILE_DONE" ]      && JQ_ARGS+=(--arg file_done "$FILE_DONE")
+
+[ -n "$ARTIFACT_SPEC" ]   && JQ_ARGS+=(--argjson art_spec "$ART_SPEC_JSON")
+[ -n "$ARTIFACT_IMPL" ]   && JQ_ARGS+=(--argjson art_impl "$ART_IMPL_JSON")
+[ -n "$ARTIFACT_PLAN" ]   && JQ_ARGS+=(--argjson art_plan "$ART_PLAN_JSON")
+[ -n "$ARTIFACT_SCHEMA" ] && JQ_ARGS+=(--argjson art_schema "$ART_SCHEMA_JSON")
+[ -n "$APPEND_AUDIT" ]      && JQ_ARGS+=(--argjson append_audit "$APPEND_AUDIT")
+[ -n "$STAGE_IN_PROGRESS" ] && JQ_ARGS+=(--argjson stage_in_progress "$STAGE_IN_PROGRESS")
+[ -n "$APPEND_DECISION" ]   && JQ_ARGS+=(--argjson append_decision "$APPEND_DECISION")
+
+jq "${JQ_ARGS[@]}" "$JQ_FILTER" "$CHECKPOINT_FILE" > "$TMP_FILE"
+mv "$TMP_FILE" "$CHECKPOINT_FILE"
+trap - EXIT
+
+echo "✓ checkpoint updated: $CHECKPOINT_FILE"

package/template/.harness/scripts/decision-log-append.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# decision-log-append.sh — appends a human-readable row to .harness/memory/decision-log.md
+#
+# Per BMAD-style decision-log pattern (the v0.9.0 "memory layer upgrade").
+# Each call appends one line; file is gitignored (per-developer record).
+#
+# USAGE:
+#   decision-log-append.sh \
+#     --feature <slug> \
+#     --stage <N> \
+#     --by <CEO|MAGI-Core|MAGI-Verdict|MAGI-Planner|MAGI-Programmer|MAGI-Tester|MAGI-Reviewer|MAGI-Archivist|system> \
+#     --decision "<short prose>"
+#
+# OPTIONS:
+#   --feature <slug>     Required. Feature slug.
+#   --stage <N>          Required. Stage number (1-9) or word ("init", "audit", "config").
+#   --by <actor>         Required. Who made the decision.
+#   --decision "<text>"  Required. One-line description. ≤120 chars recommended.
+#   --evidence "<text>"  Optional. Brief evidence / link / commit / verdict file.
+#
+# OUTPUT:
+#   - On success: prints "✓ decision logged" to stdout, exits 0.
+#   - On error:   prints error to stderr, exits 1.
+
+set -euo pipefail
+export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
+
+FEATURE=""
+STAGE=""
+BY=""
+DECISION=""
+EVIDENCE=""
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --feature)   FEATURE="$2"; shift 2 ;;
+    --stage)     STAGE="$2"; shift 2 ;;
+    --by)        BY="$2"; shift 2 ;;
+    --decision)  DECISION="$2"; shift 2 ;;
+    --evidence)  EVIDENCE="$2"; shift 2 ;;
+    *)
+      echo "Unknown arg: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+if [ -z "$FEATURE" ] || [ -z "$STAGE" ] || [ -z "$BY" ] || [ -z "$DECISION" ]; then
+  echo "decision-log-append.sh: --feature, --stage, --by, --decision all required" >&2
+  exit 1
+fi
+
+LOG_FILE=".harness/memory/decision-log.md"
+mkdir -p "$(dirname "$LOG_FILE")"
+
+# Initialize file with header if missing
+if [ ! -f "$LOG_FILE" ]; then
+  cat > "$LOG_FILE" <<'HEADER'
+# Decision Log
+
+> Per-developer chronological log of workflow decisions. Each row captures
+> WHO decided WHAT at WHICH stage of WHICH feature. Maintained automatically
+> by stage skills + MAGI Archivist. Gitignored — your private project diary.
+>
+> Use cases:
+> - Release-note source ("why we chose Redis over Memcached")
+> - Onboarding new teammates (paste relevant rows into Slack/Wiki)
+> - Post-mortem after incidents ("what did MAGI Verdict flag, did CEO accept?")
+> - Quarterly review of personal decision quality
+
+| Timestamp (UTC) | Feature | Stage | Actor | Decision | Evidence |
+|-----------------|---------|-------|-------|----------|----------|
+HEADER
+fi
+
+NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+# Escape pipe characters in text fields so they don't break the markdown table
+escape_pipes() {
+  echo "$1" | sed 's/|/\\|/g'
+}
+
+DECISION_ESC=$(escape_pipes "$DECISION")
+EVIDENCE_ESC=$(escape_pipes "${EVIDENCE:-—}")
+
+printf "| %s | %s | %s | %s | %s | %s |\n" \
+  "$NOW" "$FEATURE" "$STAGE" "$BY" "$DECISION_ESC" "$EVIDENCE_ESC" \
+  >> "$LOG_FILE"
+
+echo "✓ decision logged to $LOG_FILE"

package/template/.harness/scripts/env-check.sh

@@ -0,0 +1,286 @@
+#!/usr/bin/env bash
+# env-check.sh — environment / dependency detector for CCC-MAGI
+#
+# Called by MAGI Core (via Bash tool) during the bootstrap S1 phase to detect
+# what's installed. Outputs structured JSON that MAGI Core parses to guide
+# the user through installation of any missing dependencies conversationally.
+#
+# USAGE:
+#   env-check.sh                          # Detect + output JSON to stdout, exit 0
+#   env-check.sh --finalize               # Detect; if all required deps OK, write env-check.json. Exit 0 on success, 1 if blockers remain.
+#   env-check.sh --install-jq-vendored    # Download jq binary to .harness/bin/jq (no sudo needed)
+#
+# OUTPUT JSON SCHEMA:
+#   {
+#     "detected_at": "<iso>",
+#     "platform": "darwin|linux|windows-wsl|windows-git-bash|unknown",
+#     "shell": "bash <version>",
+#     "required": {
+#       "git":  {"installed": true,  "version": "2.39.5"},
+#       "jq":   {"installed": false, "install_hints": [...]}
+#     },
+#     "ai_clis": {
+#       "claude": {"installed": true,  "path": "..."},
+#       "codex":  {"installed": true,  "path": "..."},
+#       "gemini": {"installed": false}
+#     },
+#     "tier": "1-claude-codex|1-codex-claude|2-single-claude|2-single-codex|3-other|0-none",
+#     "recommendation": "<human-readable>",
+#     "all_required_ok": true|false,
+#     "blockers": ["jq"]
+#   }
+
+set -eu
+export PATH="/opt/homebrew/bin:/usr/local/bin:.harness/bin:$PATH"
+
+MODE="${1:-detect}"
+
+# ─── Platform detection ────────────────────────────────────────────────
+detect_platform() {
+  case "$(uname -s)" in
+    Darwin*) echo "darwin" ;;
+    Linux*)
+      # WSL?
+      if grep -qi microsoft /proc/version 2>/dev/null || [ -n "${WSL_DISTRO_NAME:-}" ]; then
+        echo "windows-wsl"
+      else
+        echo "linux"
+      fi
+      ;;
+    MINGW*|MSYS*|CYGWIN*) echo "windows-git-bash" ;;
+    *) echo "unknown" ;;
+  esac
+}
+
+PLATFORM=$(detect_platform)
+
+# ─── Helpers ───────────────────────────────────────────────────────────
+detect_tool() {
+  local name="$1"
+  if command -v "$name" >/dev/null 2>&1; then
+    local path version
+    path="$(command -v "$name")"
+    version="$("$name" --version 2>/dev/null | head -1 | sed 's/"/\\"/g' || echo "unknown")"
+    printf '{"installed":true,"path":"%s","version":"%s"}' "$path" "$version"
+  else
+    printf '{"installed":false}'
+  fi
+}
+
+# Install hints for jq, per platform
+jq_install_hints() {
+  case "$PLATFORM" in
+    darwin)
+      if command -v brew >/dev/null 2>&1; then
+        cat <<'EOF'
+[
+  {"method":"brew","cmd":"brew install jq","sudo":false,"speed":"~10s"},
+  {"method":"vendored","cmd":".harness/scripts/env-check.sh --install-jq-vendored","sudo":false,"speed":"~5s"}
+]
+EOF
+      else
+        cat <<'EOF'
+[
+  {"method":"brew","cmd":"/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\" && brew install jq","sudo":false,"speed":"~5min"},
+  {"method":"vendored","cmd":".harness/scripts/env-check.sh --install-jq-vendored","sudo":false,"speed":"~5s","recommended":true}
+]
+EOF
+      fi
+      ;;
+    linux|windows-wsl)
+      if [ -f /etc/debian_version ]; then
+        cat <<'EOF'
+[
+  {"method":"apt","cmd":"sudo apt install -y jq","sudo":true,"speed":"~10s"},
+  {"method":"vendored","cmd":".harness/scripts/env-check.sh --install-jq-vendored","sudo":false,"speed":"~5s"}
+]
+EOF
+      elif [ -f /etc/redhat-release ]; then
+        cat <<'EOF'
+[
+  {"method":"yum","cmd":"sudo yum install -y jq","sudo":true,"speed":"~15s"},
+  {"method":"vendored","cmd":".harness/scripts/env-check.sh --install-jq-vendored","sudo":false,"speed":"~5s"}
+]
+EOF
+      elif [ -f /etc/arch-release ]; then
+        cat <<'EOF'
+[
+  {"method":"pacman","cmd":"sudo pacman -S --noconfirm jq","sudo":true,"speed":"~10s"},
+  {"method":"vendored","cmd":".harness/scripts/env-check.sh --install-jq-vendored","sudo":false,"speed":"~5s"}
+]
+EOF
+      else
+        cat <<'EOF'
+[
+  {"method":"vendored","cmd":".harness/scripts/env-check.sh --install-jq-vendored","sudo":false,"speed":"~5s","recommended":true}
+]
+EOF
+      fi
+      ;;
+    windows-git-bash)
+      cat <<'EOF'
+[
+  {"method":"scoop","cmd":"scoop install jq","sudo":false,"speed":"~15s","precondition":"requires Scoop package manager"},
+  {"method":"chocolatey","cmd":"choco install jq -y","sudo":true,"speed":"~30s","precondition":"requires Chocolatey package manager"},
+  {"method":"vendored","cmd":".harness/scripts/env-check.sh --install-jq-vendored","sudo":false,"speed":"~5s","recommended":true}
+]
+EOF
+      ;;
+    *)
+      echo '[{"method":"manual","cmd":"Install jq from https://jqlang.github.io/jq/download/","sudo":false}]'
+      ;;
+  esac
+}
+
+# ─── Vendored jq install ───────────────────────────────────────────────
+install_jq_vendored() {
+  local arch url
+  arch="$(uname -m)"
+  case "$PLATFORM-$arch" in
+    darwin-arm64)         url="https://github.com/jqlang/jq/releases/latest/download/jq-macos-arm64" ;;
+    darwin-x86_64)        url="https://github.com/jqlang/jq/releases/latest/download/jq-macos-amd64" ;;
+    linux-x86_64|windows-wsl-x86_64) url="https://github.com/jqlang/jq/releases/latest/download/jq-linux-amd64" ;;
+    linux-aarch64|windows-wsl-aarch64) url="https://github.com/jqlang/jq/releases/latest/download/jq-linux-arm64" ;;
+    windows-git-bash-*)   url="https://github.com/jqlang/jq/releases/latest/download/jq-windows-amd64.exe" ;;
+    *) echo "Unsupported platform/arch combo: $PLATFORM-$arch" >&2; exit 1 ;;
+  esac
+
+  mkdir -p .harness/bin
+  TARGET=".harness/bin/jq"
+  [ "$PLATFORM" = "windows-git-bash" ] && TARGET=".harness/bin/jq.exe"
+
+  echo "Downloading jq from: $url"
+  if command -v curl >/dev/null 2>&1; then
+    curl -fsSL "$url" -o "$TARGET" || { echo "Download failed"; exit 1; }
+  elif command -v wget >/dev/null 2>&1; then
+    wget -q "$url" -O "$TARGET" || { echo "Download failed"; exit 1; }
+  else
+    echo "Neither curl nor wget found" >&2
+    exit 1
+  fi
+  chmod +x "$TARGET" 2>/dev/null || true
+
+  echo "✓ jq installed to $TARGET"
+  echo "  Verify: $TARGET --version"
+}
+
+# ─── Mode dispatch ─────────────────────────────────────────────────────
+case "$MODE" in
+  --install-jq-vendored)
+    install_jq_vendored
+    exit 0
+    ;;
+  detect|--finalize)
+    ;;
+  *)
+    echo "Unknown mode: $MODE" >&2
+    echo "Usage: $0 [--finalize | --install-jq-vendored]" >&2
+    exit 1
+    ;;
+esac
+
+# ─── Build detection JSON ──────────────────────────────────────────────
+GIT_INFO=$(detect_tool git)
+JQ_INFO=$(detect_tool jq)
+CLAUDE_INFO=$(detect_tool claude)
+CODEX_INFO=$(detect_tool codex)
+GEMINI_INFO=$(detect_tool gemini)
+
+# Bash version (just for info)
+BASH_VER="${BASH_VERSION:-unknown}"
+SHELL_DESC="bash $BASH_VER"
+
+# Determine tier
+HAS_CLAUDE=$(printf '%s' "$CLAUDE_INFO" | grep -q '"installed":true' && echo yes || echo no)
+HAS_CODEX=$(printf '%s' "$CODEX_INFO" | grep -q '"installed":true' && echo yes || echo no)
+HAS_GEMINI=$(printf '%s' "$GEMINI_INFO" | grep -q '"installed":true' && echo yes || echo no)
+
+if [ "$HAS_CLAUDE" = "yes" ] && [ "$HAS_CODEX" = "yes" ]; then
+  TIER="1-claude-codex"
+  RECOMMENDATION="Tier 1 ideal: Claude writes code, Codex audits. Cross-model bias cancellation active."
+elif [ "$HAS_CLAUDE" = "yes" ]; then
+  TIER="2-single-claude"
+  RECOMMENDATION="Tier 2: Claude only. Audit will use fresh-context Claude (same model, weaker bias cancellation). Install Codex for Tier 1."
+elif [ "$HAS_CODEX" = "yes" ]; then
+  TIER="2-single-codex"
+  RECOMMENDATION="Tier 2: Codex only. Audit will use fresh-context Codex. Install Claude for Tier 1."
+elif [ "$HAS_GEMINI" = "yes" ]; then
+  TIER="3-other"
+  RECOMMENDATION="Tier 3: Gemini detected but untested. Install Claude or Codex for Tier 1 support."
+else
+  TIER="0-none"
+  RECOMMENDATION="No supported AI CLI detected. This is unusual — you must have at least one (Claude/Codex) to be talking to MAGI Core right now. Check PATH."
+fi
+
+# Determine blockers (jq is the only true required blocker)
+JQ_OK=$(printf '%s' "$JQ_INFO" | grep -q '"installed":true' && echo yes || echo no)
+GIT_OK=$(printf '%s' "$GIT_INFO" | grep -q '"installed":true' && echo yes || echo no)
+
+BLOCKERS="["
+ALL_OK="true"
+if [ "$GIT_OK" = "no" ]; then
+  BLOCKERS="${BLOCKERS}\"git\","
+  ALL_OK="false"
+fi
+if [ "$JQ_OK" = "no" ]; then
+  BLOCKERS="${BLOCKERS}\"jq\","
+  ALL_OK="false"
+fi
+BLOCKERS="${BLOCKERS%,}]"  # strip trailing comma
+
+NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+# Build JQ install hints if needed
+JQ_HINTS="[]"
+if [ "$JQ_OK" = "no" ]; then
+  JQ_HINTS=$(jq_install_hints)
+fi
+
+# ─── Assemble output JSON ──────────────────────────────────────────────
+OUTPUT=$(cat <<EOF
+{
+  "detected_at": "$NOW",
+  "platform": "$PLATFORM",
+  "shell": "$SHELL_DESC",
+  "required": {
+    "git": $GIT_INFO,
+    "jq":  $JQ_INFO
+  },
+  "jq_install_hints": $JQ_HINTS,
+  "ai_clis": {
+    "claude": $CLAUDE_INFO,
+    "codex":  $CODEX_INFO,
+    "gemini": $GEMINI_INFO
+  },
+  "tier": "$TIER",
+  "recommendation": "$RECOMMENDATION",
+  "all_required_ok": $ALL_OK,
+  "blockers": $BLOCKERS
+}
+EOF
+)
+
+# Pretty-print if jq available (recursive bootstrap problem: if jq isn't installed yet, we just output raw)
+if command -v jq >/dev/null 2>&1; then
+  echo "$OUTPUT" | jq .
+else
+  echo "$OUTPUT"
+fi
+
+# ─── Finalize mode: write env-check.json if all required deps OK ──────
+if [ "$MODE" = "--finalize" ]; then
+  if [ "$ALL_OK" != "true" ]; then
+    echo "" >&2
+    echo "✗ Cannot finalize — blockers remain: $BLOCKERS" >&2
+    echo "  Install the missing dependency, then re-run env-check.sh --finalize" >&2
+    exit 1
+  fi
+
+  mkdir -p .harness/state
+  echo "$OUTPUT" > .harness/state/env-check.json
+  echo "" >&2
+  echo "✓ Environment check finalized: .harness/state/env-check.json" >&2
+  echo "  Phase 1 complete. Next: project deployment via /init" >&2
+fi
+
+exit 0