@open-agent-toolkit/cli 0.2.36 → 0.2.37

package/assets/scripts/generate-oat-state.sh

@@ -0,0 +1,441 @@
+#!/usr/bin/env bash
+# generate-oat-state.sh - Generate OAT repo state dashboard
+# Usage: ./generate-oat-state.sh
+# Exit codes: 0 = Success, 1 = Error (only for real failures, not missing data)
+
+# Use -eu but NOT pipefail - we need graceful degradation for missing data
+set -eu
+
+# --- Configuration ---
+DASHBOARD_PATH=".oat/state.md"
+
+# --- Error Handling Pattern ---
+# For best-effort parsing, use:
+#   result=$(command 2>/dev/null || echo "")
+#   result=$(grep ... || true)
+# Never let missing frontmatter or files cause script exit.
+
+# --- Functions ---
+
+# Resolve PROJECTS_ROOT from env, file, or default
+resolve_projects_root() {
+  local root="${OAT_PROJECTS_ROOT:-}"
+  if [[ -z "$root" ]] && [[ -f ".oat/projects-root" ]]; then
+    root=$(cat ".oat/projects-root" 2>/dev/null || true)
+  fi
+  root="${root:-.oat/projects/shared}"
+  echo "${root%/}"  # Strip trailing slash
+}
+
+has_any_projects() {
+  local projects_root="$1"
+  local dir
+  [[ -d "$projects_root" ]] || return 1
+  for dir in "$projects_root"/*/; do
+    [[ -d "$dir" ]] || continue
+    return 0
+  done
+  return 1
+}
+
+# Read active project pointer (accepts path or name format)
+# Sets: PROJECT_NAME, PROJECT_PATH, PROJECT_STATUS
+read_active_project() {
+  local projects_root="$1"
+  local raw_value
+
+  PROJECT_NAME=""
+  PROJECT_PATH=""
+  PROJECT_STATUS="not set"
+
+  if [[ ! -f ".oat/active-project" ]]; then
+    return
+  fi
+
+  raw_value=$(cat ".oat/active-project" 2>/dev/null || true)
+  raw_value=$(echo "$raw_value" | tr -d '[:space:]')
+
+  if [[ -z "$raw_value" ]]; then
+    return
+  fi
+
+  # Detect format: path (contains /) or name-only
+  if [[ "$raw_value" == */* ]]; then
+    PROJECT_NAME=$(basename "$raw_value")
+    PROJECT_PATH="$raw_value"
+  else
+    PROJECT_NAME="$raw_value"
+    PROJECT_PATH="${projects_root}/${PROJECT_NAME}"
+  fi
+
+  # Validate directory exists
+  if [[ ! -d "$PROJECT_PATH" ]]; then
+    PROJECT_STATUS="directory missing"
+    return
+  fi
+
+  # Validate state.md exists
+  if [[ ! -f "${PROJECT_PATH}/state.md" ]]; then
+    PROJECT_STATUS="state.md missing"
+    return
+  fi
+
+  PROJECT_STATUS="active"
+}
+
+# Parse YAML frontmatter field from file (best-effort, never fails)
+# Usage: parse_frontmatter "file.md" "field_name"
+# Returns: Field value or empty string (never exits on missing data)
+parse_frontmatter() {
+  local file="$1"
+  local field="$2"
+  local content value
+
+  if [[ ! -f "$file" ]]; then
+    echo ""
+    return 0
+  fi
+
+  # Extract frontmatter block, then find field - use || true to prevent exit
+  content=$(sed -n '/^---$/,/^---$/p' "$file" 2>/dev/null) || true
+  if [[ -z "$content" ]]; then
+    echo ""
+    return 0
+  fi
+
+  # Find field value - grep returns 1 if no match, so use || true
+  value=$(echo "$content" | grep "^${field}:" | head -1 | sed "s/^${field}:[[:space:]]*//") || true
+  # Strip inline comments used by templates and trim trailing whitespace
+  value=$(echo "$value" | sed 's/[[:space:]]#.*$//' | sed 's/[[:space:]]*$//')
+  echo "$value"
+}
+
+# Read project state from state.md frontmatter
+# Sets: OAT_PHASE, OAT_PHASE_STATUS, OAT_CURRENT_TASK, OAT_LIFECYCLE, OAT_BLOCKERS,
+#       OAT_HIL_CHECKPOINTS, OAT_HIL_COMPLETED, OAT_HIL_STATUS
+read_project_state() {
+  local state_file="${PROJECT_PATH}/state.md"
+
+  OAT_PHASE=$(parse_frontmatter "$state_file" "oat_phase")
+  OAT_PHASE_STATUS=$(parse_frontmatter "$state_file" "oat_phase_status")
+  OAT_CURRENT_TASK=$(parse_frontmatter "$state_file" "oat_current_task")
+  OAT_LIFECYCLE=$(parse_frontmatter "$state_file" "oat_lifecycle")
+  OAT_BLOCKERS=$(parse_frontmatter "$state_file" "oat_blockers")
+  OAT_HIL_CHECKPOINTS=$(parse_frontmatter "$state_file" "oat_hil_checkpoints")
+  OAT_HIL_COMPLETED=$(parse_frontmatter "$state_file" "oat_hil_completed")
+  OAT_WORKFLOW_MODE=$(parse_frontmatter "$state_file" "oat_workflow_mode")
+
+  # Defaults
+  OAT_PHASE="${OAT_PHASE:-unknown}"
+  OAT_PHASE_STATUS="${OAT_PHASE_STATUS:-unknown}"
+  if [[ -z "${OAT_CURRENT_TASK:-}" ]] || [[ "${OAT_CURRENT_TASK}" == "null" ]]; then
+    OAT_CURRENT_TASK="-"
+  fi
+  OAT_LIFECYCLE="${OAT_LIFECYCLE:-active}"
+  OAT_BLOCKERS="${OAT_BLOCKERS:-[]}"
+  OAT_HIL_CHECKPOINTS="${OAT_HIL_CHECKPOINTS:-[]}"
+  OAT_HIL_COMPLETED="${OAT_HIL_COMPLETED:-[]}"
+  OAT_WORKFLOW_MODE="${OAT_WORKFLOW_MODE:-full}"
+
+  # Human-in-loop status for current phase
+  if phase_in_hil_list "$OAT_PHASE" "$OAT_HIL_CHECKPOINTS"; then
+    if phase_in_hil_list "$OAT_PHASE" "$OAT_HIL_COMPLETED"; then
+      OAT_HIL_STATUS="passed"
+    else
+      OAT_HIL_STATUS="pending"
+    fi
+  else
+    OAT_HIL_STATUS="n/a"
+  fi
+}
+
+# Check whether a phase token appears in a serialized YAML array string
+phase_in_hil_list() {
+  local phase="$1"
+  local list="$2"
+  [[ "$list" == *"\"${phase}\""* ]]
+}
+
+# Read knowledge index status
+# Sets: KNOWLEDGE_GENERATED_AT, KNOWLEDGE_MERGE_BASE_SHA, KNOWLEDGE_STATUS
+read_knowledge_status() {
+  local index_file=".oat/repo/knowledge/project-index.md"
+
+  KNOWLEDGE_GENERATED_AT=""
+  KNOWLEDGE_MERGE_BASE_SHA=""
+  KNOWLEDGE_STATUS="not generated"
+
+  if [[ ! -f "$index_file" ]]; then
+    return
+  fi
+
+  KNOWLEDGE_GENERATED_AT=$(parse_frontmatter "$index_file" "oat_generated_at")
+  KNOWLEDGE_MERGE_BASE_SHA=$(parse_frontmatter "$index_file" "oat_source_main_merge_base_sha")
+
+  if [[ -n "$KNOWLEDGE_GENERATED_AT" ]]; then
+    KNOWLEDGE_STATUS="generated"
+  fi
+}
+
+# Calculate knowledge staleness via git diff (best-effort, never fails)
+# Sets: FILES_CHANGED, KNOWLEDGE_AGE_DAYS, STALENESS_STATUS
+calculate_staleness() {
+  FILES_CHANGED=0
+  KNOWLEDGE_AGE_DAYS=0
+  STALENESS_STATUS="fresh"
+
+  if [[ -z "$KNOWLEDGE_MERGE_BASE_SHA" ]]; then
+    STALENESS_STATUS="unknown"
+    return 0
+  fi
+
+  # Count files changed since merge base - git diff may fail if SHA is invalid
+  local diff_output
+  diff_output=$(git diff --name-only "$KNOWLEDGE_MERGE_BASE_SHA" HEAD 2>/dev/null) || true
+  if [[ -n "$diff_output" ]]; then
+    FILES_CHANGED=$(echo "$diff_output" | wc -l | awk '{print $1}')
+  fi
+
+  # Calculate age in days - handle both macOS and Linux date formats
+  if [[ -n "$KNOWLEDGE_GENERATED_AT" ]]; then
+    local gen_epoch today_epoch
+    # Try macOS format first
+    if gen_epoch=$(date -j -f "%Y-%m-%d" "$KNOWLEDGE_GENERATED_AT" "+%s" 2>/dev/null); then
+      : # Success on macOS
+    # Then try Linux format
+    elif gen_epoch=$(date -d "$KNOWLEDGE_GENERATED_AT" "+%s" 2>/dev/null); then
+      : # Success on Linux
+    else
+      # Fallback: cannot parse date
+      gen_epoch=0
+    fi
+    today_epoch=$(date "+%s")
+    if [[ "$gen_epoch" -gt 0 ]]; then
+      KNOWLEDGE_AGE_DAYS=$(( (today_epoch - gen_epoch) / 86400 ))
+    fi
+  fi
+
+  # Determine staleness
+  if [[ "$FILES_CHANGED" -gt 20 ]] || [[ "$KNOWLEDGE_AGE_DAYS" -gt 7 ]]; then
+    STALENESS_STATUS="stale"
+  elif [[ "$FILES_CHANGED" -gt 5 ]] || [[ "$KNOWLEDGE_AGE_DAYS" -gt 3 ]]; then
+    STALENESS_STATUS="aging"
+  fi
+}
+
+# Compute recommended next step based on state
+# Sets: RECOMMENDED_STEP, RECOMMENDED_REASON
+compute_next_step() {
+  RECOMMENDED_STEP=""
+  RECOMMENDED_REASON=""
+
+  # No active project
+  if [[ "$PROJECT_STATUS" == "not set" ]]; then
+    if [[ "${HAS_PROJECTS:-false}" == "true" ]]; then
+      RECOMMENDED_STEP="oat-project-open"
+      RECOMMENDED_REASON="Select an existing project to continue work"
+    else
+      RECOMMENDED_STEP="oat-project-new"
+      RECOMMENDED_REASON="Create a new project to start work"
+    fi
+    return
+  fi
+
+  # Project has issues
+  if [[ "$PROJECT_STATUS" != "active" ]]; then
+    RECOMMENDED_STEP="oat-project-open"
+    RECOMMENDED_REASON="Current project has issues: $PROJECT_STATUS"
+    return
+  fi
+
+  # Respect configured human-in-the-loop checkpoints before advancing phase
+  if [[ "$OAT_PHASE_STATUS" == "complete" ]] &&
+    phase_in_hil_list "$OAT_PHASE" "$OAT_HIL_CHECKPOINTS" &&
+    ! phase_in_hil_list "$OAT_PHASE" "$OAT_HIL_COMPLETED"; then
+    case "$OAT_PHASE" in
+      "discovery") RECOMMENDED_STEP="oat-project-discover" ;;
+      "spec") RECOMMENDED_STEP="oat-project-spec" ;;
+      "design") RECOMMENDED_STEP="oat-project-design" ;;
+      "plan") RECOMMENDED_STEP="oat-project-plan" ;;
+      "implement") RECOMMENDED_STEP="oat-project-implement" ;;
+      *) RECOMMENDED_STEP="oat-project-progress" ;;
+    esac
+    RECOMMENDED_REASON="Complete ${OAT_PHASE} HiL approval before advancing"
+    return
+  fi
+
+  # Map phase + status to next skill by workflow mode
+  case "${OAT_WORKFLOW_MODE}:${OAT_PHASE}:${OAT_PHASE_STATUS}" in
+    # full mode
+    "full:discovery:in_progress") RECOMMENDED_STEP="oat-project-discover"; RECOMMENDED_REASON="Continue discovery phase" ;;
+    "full:discovery:complete") RECOMMENDED_STEP="oat-project-spec"; RECOMMENDED_REASON="Create specification from discovery" ;;
+    "full:spec:in_progress") RECOMMENDED_STEP="oat-project-spec"; RECOMMENDED_REASON="Continue specification phase" ;;
+    "full:spec:complete") RECOMMENDED_STEP="oat-project-design"; RECOMMENDED_REASON="Create design from specification" ;;
+    "full:design:in_progress") RECOMMENDED_STEP="oat-project-design"; RECOMMENDED_REASON="Continue design phase" ;;
+    "full:design:complete") RECOMMENDED_STEP="oat-project-plan"; RECOMMENDED_REASON="Create implementation plan from design" ;;
+
+    # quick mode
+    "quick:discovery:in_progress") RECOMMENDED_STEP="oat-project-discover"; RECOMMENDED_REASON="Continue quick discovery phase" ;;
+    "quick:discovery:complete") RECOMMENDED_STEP="oat-project-plan"; RECOMMENDED_REASON="Generate plan directly for quick workflow" ;;
+
+    # import mode
+    "import:plan:in_progress") RECOMMENDED_STEP="oat-project-import-plan"; RECOMMENDED_REASON="Continue import-plan normalization" ;;
+
+    # shared routing
+    *":plan:in_progress") RECOMMENDED_STEP="oat-project-plan"; RECOMMENDED_REASON="Continue planning phase" ;;
+    *":plan:complete") RECOMMENDED_STEP="oat-project-implement"; RECOMMENDED_REASON="Start implementation" ;;
+    *":implement:in_progress") RECOMMENDED_STEP="oat-project-implement"; RECOMMENDED_REASON="Continue implementation" ;;
+    *":implement:complete") RECOMMENDED_STEP="oat-project-pr-final"; RECOMMENDED_REASON="Generate final PR description (final review passed)" ;;
+    *) RECOMMENDED_STEP="oat-project-progress"; RECOMMENDED_REASON="Check current progress" ;;
+  esac
+}
+
+# List available projects with their phases
+# Output: Markdown formatted list
+list_available_projects() {
+  local projects_root="$1"
+  local project_dir project_name phase
+
+  if [[ ! -d "$projects_root" ]]; then
+    echo "*(No projects directory found)*"
+    return
+  fi
+
+  local found=false
+  for project_dir in "$projects_root"/*/; do
+    [[ -d "$project_dir" ]] || continue
+    project_name=$(basename "$project_dir")
+
+    if [[ -f "${project_dir}state.md" ]]; then
+      phase=$(parse_frontmatter "${project_dir}state.md" "oat_phase")
+      phase="${phase:-unknown}"
+      echo "- **${project_name}** - ${phase}"
+      found=true
+    fi
+  done
+
+  if [[ "$found" == "false" ]]; then
+    echo "*(No projects found)*"
+  fi
+}
+
+# Generate the complete dashboard markdown
+generate_dashboard() {
+  local projects_root="$1"
+  local timestamp
+  timestamp=$(date -u +"%Y-%m-%d %H:%M:%S UTC")
+
+  cat > "$DASHBOARD_PATH" << EOF
+---
+oat_generated: true
+oat_generated_at: $(date -u +"%Y-%m-%d")
+---
+
+# OAT Repo State Dashboard
+
+**Generated:** ${timestamp}
+
+## Active Project
+
+EOF
+
+  # Active project section
+  if [[ "$PROJECT_STATUS" == "not set" ]]; then
+    echo "*(not set)*" >> "$DASHBOARD_PATH"
+  else
+    echo "**${PROJECT_NAME}** (\`${PROJECT_PATH}\`)" >> "$DASHBOARD_PATH"
+  fi
+
+  echo "" >> "$DASHBOARD_PATH"
+
+  # Active project summary (thin; details live in project state.md)
+  if [[ "$PROJECT_STATUS" == "active" ]]; then
+    cat >> "$DASHBOARD_PATH" << EOF
+## Active Project Summary
+
+| Field | Value |
+|-------|-------|
+| Mode | ${OAT_WORKFLOW_MODE} |
+| Phase | ${OAT_PHASE} |
+| Status | ${OAT_PHASE_STATUS} |
+| HiL Gate | ${OAT_HIL_STATUS} |
+| Current Task | ${OAT_CURRENT_TASK} |
+
+EOF
+    echo "Details: \`${PROJECT_PATH}/state.md\`" >> "$DASHBOARD_PATH"
+    echo "" >> "$DASHBOARD_PATH"
+  elif [[ "$PROJECT_STATUS" != "not set" ]]; then
+    echo "**Warning:** ${PROJECT_STATUS}" >> "$DASHBOARD_PATH"
+    echo "" >> "$DASHBOARD_PATH"
+  fi
+
+  # Knowledge status section
+  cat >> "$DASHBOARD_PATH" << EOF
+## Knowledge Status
+
+| Field | Value |
+|-------|-------|
+| Generated | ${KNOWLEDGE_GENERATED_AT:-N/A} |
+| Age | ${KNOWLEDGE_AGE_DAYS} days |
+| Files Changed | ${FILES_CHANGED} |
+| Status | ${STALENESS_STATUS} |
+
+EOF
+
+  # Recommended next step
+  cat >> "$DASHBOARD_PATH" << EOF
+## Recommended Next Step
+
+**${RECOMMENDED_STEP}** - ${RECOMMENDED_REASON}
+
+## Quick Commands
+
+- \`oat-project-progress\` - Check current status
+- \`oat-repo-knowledge-index\` - Refresh knowledge base
+- \`oat-project-new\` - Create a full-lifecycle project
+- \`oat-project-quick-start\` - Create a quick workflow project
+- \`oat-project-import-plan\` - Import an external provider plan
+- \`oat-project-open\` - Switch active project
+- \`oat-project-clear-active\` - Clear active project
+- \`oat-project-complete\` - Mark project complete
+
+## Available Projects
+
+EOF
+
+  list_available_projects "$projects_root" >> "$DASHBOARD_PATH"
+}
+
+# --- Main ---
+main() {
+  # Validate we're in a git repo
+  if ! git rev-parse --git-dir > /dev/null 2>&1; then
+    echo "Error: Must be run from a git repository" >&2
+    exit 1
+  fi
+
+  local projects_root
+  projects_root=$(resolve_projects_root)
+
+  if has_any_projects "$projects_root"; then
+    HAS_PROJECTS="true"
+  else
+    HAS_PROJECTS="false"
+  fi
+
+  read_active_project "$projects_root"
+
+  if [[ "$PROJECT_STATUS" == "active" ]]; then
+    read_project_state
+  fi
+
+  read_knowledge_status
+  calculate_staleness
+  compute_next_step
+
+  generate_dashboard "$projects_root"
+
+  echo "Dashboard generated: $DASHBOARD_PATH"
+}
+
+main "$@"

package/assets/scripts/generate-thin-index.sh

@@ -0,0 +1,200 @@
+#!/usr/bin/env bash
+# generate-thin-index.sh - Generate thin project-index.md for quick orientation
+#
+# Usage: ./generate-thin-index.sh [HEAD_SHA] [MERGE_BASE_SHA]
+#
+# If SHAs not provided, computes them from current git state.
+# Output: Writes .oat/repo/knowledge/project-index.md
+
+set -euo pipefail
+
+# Get SHAs from args or compute
+HEAD_SHA="${1:-$(git rev-parse HEAD 2>/dev/null || echo "unknown")}"
+MERGE_BASE_SHA="${2:-$(git merge-base HEAD origin/main 2>/dev/null || git rev-parse HEAD 2>/dev/null || echo "unknown")}"
+
+# Current date (portable)
+DATE=$(date +%F)
+
+# Get repo name from package.json or directory (supports node, jq, or grep fallback)
+REPO_NAME=""
+if [ -f package.json ]; then
+  # Try node first
+  if command -v node >/dev/null 2>&1; then
+    REPO_NAME=$(node -pe "try{require('./package.json').name||''}catch(e){''}" 2>/dev/null)
+  # Try jq second
+  elif command -v jq >/dev/null 2>&1; then
+    REPO_NAME=$(jq -r '.name // ""' package.json 2>/dev/null)
+  # Fallback to grep
+  else
+    REPO_NAME=$(grep -m1 '"name"' package.json 2>/dev/null | sed 's/.*"name"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/')
+  fi
+fi
+if [ -z "$REPO_NAME" ]; then
+  REPO_NAME=$(basename "$(pwd)")
+fi
+
+# Quick directory tree (2 levels, exclude common noise)
+TREE=$(find . -maxdepth 2 -mindepth 1 \
+  -not -path '*/.git/*' \
+  -not -path '*/node_modules/*' \
+  -not -path '*/dist/*' \
+  -not -path '*/build/*' \
+  -not -path '*/.next/*' \
+  -not -path '*/.turbo/*' \
+  -not -path '*/coverage/*' \
+  -print 2>/dev/null | sed 's#^\./##' | sort | head -200)
+
+# Detect package manager
+PKG_MANAGER="unknown"
+[ -f pnpm-lock.yaml ] && PKG_MANAGER="pnpm"
+[ -f yarn.lock ] && PKG_MANAGER="yarn"
+[ -f package-lock.json ] && PKG_MANAGER="npm"
+[ -f Pipfile.lock ] && PKG_MANAGER="pipenv"
+[ -f poetry.lock ] && PKG_MANAGER="poetry"
+[ -f Cargo.lock ] && PKG_MANAGER="cargo"
+[ -f go.mod ] && PKG_MANAGER="go"
+
+# Extract scripts from package.json if Node project (supports node, jq, or grep fallback)
+SCRIPTS=""
+if [ -f package.json ]; then
+  if command -v node >/dev/null 2>&1; then
+    SCRIPTS=$(node -pe "try{Object.keys(require('./package.json').scripts||{}).join(', ')}catch(e){''}" 2>/dev/null || echo "")
+  elif command -v jq >/dev/null 2>&1; then
+    SCRIPTS=$(jq -r '.scripts // {} | keys | join(", ")' package.json 2>/dev/null || echo "")
+  else
+    # Fallback: extract script names with grep (crude but works for most cases)
+    SCRIPTS=$(grep -E '^\s+"[a-zA-Z0-9:_-]+"\s*:' package.json 2>/dev/null | \
+      sed -n '/"scripts"/,/^[[:space:]]*}/p' | \
+      grep -E '^\s+"[a-zA-Z0-9:_-]+"\s*:' | \
+      sed 's/.*"\([^"]*\)".*/\1/' | \
+      tr '\n' ', ' | sed 's/, $//')
+  fi
+fi
+
+# Find entry points (cheap heuristics)
+ENTRYPOINTS=$(find . -maxdepth 4 -type f \
+  \( -name 'index.*' -o -name 'main.*' -o -name 'app.*' -o -name 'server.*' -o -name 'cli.*' \) \
+  -not -path '*/node_modules/*' \
+  -not -path '*/.git/*' \
+  -not -path '*/dist/*' \
+  -not -path '*/build/*' \
+  -print 2>/dev/null | sed 's#^\./##' | sort | head -50)
+
+# Detect key config files (portable - check each individually)
+CONFIGS=""
+for cfg in package.json pnpm-lock.yaml yarn.lock package-lock.json \
+           tsconfig.json biome.json eslint.config.js eslint.config.mjs .eslintrc.js .eslintrc.json \
+           vitest.config.ts vitest.config.js jest.config.ts jest.config.js pytest.ini pyproject.toml \
+           go.mod Cargo.toml Makefile; do
+  [ -f "$cfg" ] && CONFIGS="$CONFIGS $cfg"
+done
+CONFIGS=$(echo "$CONFIGS" | xargs)  # trim whitespace
+
+# Extract test command from scripts (supports node, jq, or grep fallback)
+TEST_CMD=""
+if [ -f package.json ]; then
+  if command -v node >/dev/null 2>&1; then
+    TEST_CMD=$(node -pe "try{require('./package.json').scripts?.test||''}catch(e){''}" 2>/dev/null || echo "")
+  elif command -v jq >/dev/null 2>&1; then
+    TEST_CMD=$(jq -r '.scripts.test // ""' package.json 2>/dev/null || echo "")
+  else
+    # Fallback: look for test script with grep
+    TEST_CMD=$(grep -A1 '"test"' package.json 2>/dev/null | grep -v '"test"' | head -1 | sed 's/.*"test"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' | tr -d ',')
+  fi
+fi
+if [ -z "$TEST_CMD" ] && [ -f Makefile ]; then
+  grep -q "^test:" Makefile 2>/dev/null && TEST_CMD="make test"
+fi
+
+# Format testing section
+if [ -n "$TEST_CMD" ]; then
+  TESTING_SECTION="**Test Command:** \`${TEST_CMD}\`"
+else
+  TESTING_SECTION="*Test command will be documented after analysis.*"
+fi
+
+# Format entry points as list
+ENTRYPOINTS_LIST=""
+if [ -n "$ENTRYPOINTS" ]; then
+  ENTRYPOINTS_LIST=$(echo "$ENTRYPOINTS" | while read -r ep; do echo "- \`$ep\`"; done)
+else
+  ENTRYPOINTS_LIST="- None detected"
+fi
+
+# Format tree as markdown code block content
+TREE_FORMATTED=$(echo "$TREE" | sed 's/^/  /')
+
+# Format configs as list
+CONFIGS_LIST=""
+if [ -n "$CONFIGS" ]; then
+  for cfg in $CONFIGS; do
+    CONFIGS_LIST="$CONFIGS_LIST
+- \`$cfg\`"
+  done
+else
+  CONFIGS_LIST="
+- None detected"
+fi
+
+# Ensure output directory exists
+mkdir -p .oat/repo/knowledge
+
+# Write the thin index
+cat > .oat/repo/knowledge/project-index.md <<EOF
+---
+oat_generated: true
+oat_generated_at: ${DATE}
+oat_source_head_sha: ${HEAD_SHA}
+oat_source_main_merge_base_sha: ${MERGE_BASE_SHA}
+oat_index_type: thin
+oat_warning: "GENERATED FILE - Thin index, will be enriched after mapper completion"
+---
+
+# ${REPO_NAME}
+
+## Overview
+
+*Overview will be enriched after codebase analysis completes.*
+
+## Quick Orientation
+
+**Package Manager:** ${PKG_MANAGER}
+
+**Key Scripts:** ${SCRIPTS:-None detected}
+
+**Entry Points:**
+${ENTRYPOINTS_LIST}
+
+## Project Structure (Top-Level)
+
+\`\`\`
+${TREE_FORMATTED}
+\`\`\`
+
+## Configuration Files
+${CONFIGS_LIST}
+
+## Testing
+
+${TESTING_SECTION}
+
+## Next Steps
+
+This is a thin index generated for quick orientation. Full details will be available after codebase analysis completes in:
+
+- [stack.md](stack.md) - Technologies and dependencies (pending)
+- [architecture.md](architecture.md) - System design and patterns (pending)
+- [structure.md](structure.md) - Directory layout (pending)
+- [integrations.md](integrations.md) - External services (pending)
+- [testing.md](testing.md) - Test structure and practices (pending)
+- [conventions.md](conventions.md) - Code style and patterns (pending)
+- [concerns.md](concerns.md) - Technical debt and issues (pending)
+EOF
+
+# Count non-empty lines for accurate entrypoint count
+ENTRYPOINT_COUNT=$(printf "%s\n" "$ENTRYPOINTS" | sed '/^$/d' | wc -l | tr -d ' ')
+
+echo "Generated .oat/repo/knowledge/project-index.md (thin index)"
+echo "  Repo: ${REPO_NAME}"
+echo "  Package Manager: ${PKG_MANAGER}"
+echo "  Entry Points: ${ENTRYPOINT_COUNT} detected"

package/assets/skills/oat-agent-instructions-analyze/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-agent-instructions-analyze
-version: 1.11.2
+version: 1.12.0
 description: Run when you need to evaluate agent instruction file coverage, quality, and drift. Produces a severity-rated analysis artifact. Run before oat-agent-instructions-apply to identify what needs improvement.
 disable-model-invocation: true
 user-invocable: true
@@ -78,8 +78,10 @@ or fill in missing evidence gaps on its own.
 **Resolve providers:**
 
 ```bash
-SCRIPT_DIR=".agents/skills/oat-agent-instructions-analyze/scripts"
-TRACKING_SCRIPT=".oat/scripts/resolve-tracking.sh"
+# Set SKILL_DIR to the absolute directory containing this loaded SKILL.md.
+SCRIPT_DIR="$SKILL_DIR/scripts"
+SCOPE_ROOT="$(cd "$SKILL_DIR/../../.." && pwd)"
+TRACKING_SCRIPT="$SCOPE_ROOT/.oat/scripts/resolve-tracking.sh"
 PROVIDERS=$(bash "$SCRIPT_DIR/resolve-providers.sh" --non-interactive)
 # Or with explicit override:
 # PROVIDERS=$(bash "$SCRIPT_DIR/resolve-providers.sh" --providers claude,cursor)
@@ -468,7 +470,9 @@ If the loop is disabled, note `Auto artifact review: skipped (workflow.autoArtif
 **Update tracking:**
 
 ```bash
-TRACKING_SCRIPT=".oat/scripts/resolve-tracking.sh"
+# Set SKILL_DIR to the absolute directory containing this loaded SKILL.md.
+SCOPE_ROOT="$(cd "$SKILL_DIR/../../.." && pwd)"
+TRACKING_SCRIPT="$SCOPE_ROOT/.oat/scripts/resolve-tracking.sh"
 ROOT_TARGET=$(bash "$TRACKING_SCRIPT" root)
 ROOT_HASH=$(echo "$ROOT_TARGET" | jq -r '.commitHash')
 ROOT_BRANCH=$(echo "$ROOT_TARGET" | jq -r '.baseBranch')
@@ -526,6 +530,7 @@ Next step: Run oat-agent-instructions-apply to act on these findings.
 - Bundle summary template: `references/bundle-summary-template.md`
 - Bundle manifest template: `references/recommendations-manifest-template.yaml`
 - Recommendation pack template: `references/recommendation-pack-template.md`
-- Tracking script: `.oat/scripts/resolve-tracking.sh`
+- Tracking script: `$SCOPE_ROOT/.oat/scripts/resolve-tracking.sh`, where
+  `SCOPE_ROOT` is derived from this loaded skill's directory.
 - Provider resolution: `scripts/resolve-providers.sh`
 - File discovery: `scripts/resolve-instruction-files.sh`