/doctor

description: "Health check for great_cto. Shows pipeline state, missing artefacts, hook status, last run per agent, and permission-denied tail."
argument-hint: "[--fix] — optional, emits remediation commands"
user-invocable: true
allowed-tools: Read, Bash, Glob, Grep
model: haiku

You are the Doctor. Produce a concise, actionable health report for the great_cto pipeline in this project. Do NOT fix — only diagnose and point. Reports go to stdout; no files written.

Setup

source .great_cto/env.sh 2>/dev/null || export PATH="/opt/homebrew/bin:$HOME/.local/bin:/usr/local/bin:$PATH"
FIX_MODE=false
SKILLS_DETAIL=false
SKILLS_REFRESH=false
for arg in "$@"; do
  case "$arg" in
    --fix) FIX_MODE=true ;;
    --skills) SKILLS_DETAIL=true ;;
    --skills-refresh) SKILLS_REFRESH=true; SKILLS_DETAIL=true ;;
  esac
done
TODAY=$(date +%Y-%m-%d)
NOW_EPOCH=$(date +%s)

Check 1 — Required files

REQ_FILES=(.great_cto/PROJECT.md)
MISS=0
for f in "${REQ_FILES[@]}"; do
  if [ ! -f "$f" ]; then
    echo "MISSING: $f — run /start (new) or /audit (existing repo)"
    MISS=$((MISS+1))
  fi
done

Exit early with summary if PROJECT.md missing — no point checking the rest.

Check 2 — PROJECT.md format (v1.0.76+ contract)

# Use bash -c to avoid zsh nomatch + grep-c "0 || echo 0" doubling quirks.
if [ -f .great_cto/PROJECT.md ]; then
  HAS_STACK=$(grep -c "^Stack:" .great_cto/PROJECT.md 2>/dev/null); HAS_STACK=${HAS_STACK:-0}
  HAS_TYPE=$(grep -c "^Type:" .great_cto/PROJECT.md 2>/dev/null); HAS_TYPE=${HAS_TYPE:-0}
  HAS_ARCHETYPE=$(grep -c "archetype:" .great_cto/PROJECT.md 2>/dev/null); HAS_ARCHETYPE=${HAS_ARCHETYPE:-0}
  echo "PROJECT.md format:"
  [ "${HAS_STACK}" -gt 0 ] && echo "  ✓ Stack: line present" || echo "  ⚠ Stack: line missing — old format, run /audit to migrate"
  [ "${HAS_TYPE}" -gt 0 ] && echo "  ✓ Type: line present" || echo "  ⚠ Type: line missing — old format, run /audit to migrate"
  [ "${HAS_ARCHETYPE}" -gt 0 ] && echo "  ✓ archetype: present" || echo "  ⚠ archetype: missing"
fi

Check 2c — Archetype confidence

if [ -f .great_cto/PROJECT.md ]; then
  CONFIDENCE=$(grep "^archetype_confidence:" .great_cto/PROJECT.md 2>/dev/null | awk '{print $2}')
  ALTERNATIVES=$(grep "^archetype_alternatives:" .great_cto/PROJECT.md 2>/dev/null | sed 's/.*\[//;s/\]//')
  echo "Archetype confidence:"
  case "${CONFIDENCE:-}" in
    high)
      echo "  ✓ archetype_confidence: high — detector is certain"
      ;;
    medium|low)
      echo "  ⚠ archetype_confidence: ${CONFIDENCE} — consider reviewing alternatives: ${ALTERNATIVES:-none}"
      echo "    Run /audit to re-detect, or set archetype: manually in .great_cto/PROJECT.md"
      ;;
    user-specified)
      echo "  ✓ archetype_confidence: user-specified — manually confirmed"
      ;;
    "")
      echo "  ⚠ archetype_confidence: missing — upgrade to v1.0.146+ and re-run bootstrap"
      echo "    Quick fix: run \`npx great-cto\` in the project directory"
      ;;
    *)
      echo "  ⚠ archetype_confidence: unknown value '${CONFIDENCE}' — expected high | medium | low | user-specified"
      ;;
  esac
fi

Check 3 — Output artefacts per phase

echo ""
echo "Pipeline artefacts:"
# Use find instead of globs so zsh without nullglob doesn't error on no-match.
find_latest() { find "$1" -maxdepth 1 -name "$2" 2>/dev/null | sort -V | tail -1; }
LAST_AUDIT=$(find_latest docs/audit          'AUDIT-*.md')
LAST_ARCH=$(find_latest  docs/architecture   'ARCH-*.md')
LAST_QA=$(find_latest    docs/qa-reports     'QA-*.md')
LAST_CSO=$(find_latest   docs/security       'CSO-*.md')
LAST_ADR=$(find_latest   docs/decisions      'ADR-*.md')
LAST_DIGEST=$( [ -f .great_cto/digest-latest.md ] && echo .great_cto/digest-latest.md )

age_days() {
  local f="$1"
  [ -z "$f" ] || [ ! -f "$f" ] && { echo "-"; return; }
  local mtime
  mtime=$(stat -f %m "$f" 2>/dev/null || stat -c %Y "$f" 2>/dev/null || echo 0)
  echo $(( (NOW_EPOCH - mtime) / 86400 ))
}

report_artefact() {
  local label="$1"; local path="$2"; local max_age="$3"
  if [ -z "$path" ]; then
    echo "  ✗ $label: NEVER — run the relevant command"
    return
  fi
  local age; age=$(age_days "$path")
  if [ "$age" -gt "$max_age" ]; then
    echo "  ⚠ $label: $age days old (max $max_age) — $(basename "$path")"
  else
    echo "  ✓ $label: $age days old — $(basename "$path")"
  fi
}

report_artefact "audit"        "$LAST_AUDIT"  30
report_artefact "architecture" "$LAST_ARCH"   90
report_artefact "qa report"    "$LAST_QA"     14
report_artefact "security"     "$LAST_CSO"    30
report_artefact "ADR (latest)" "$LAST_ADR"    90
report_artefact "digest"       "$LAST_DIGEST"  7

Check 3b — ADR health (lifecycle + supersession)

echo ""
echo "ADR health:"
ADR_DIR="docs/decisions"
if [ -d "$ADR_DIR" ] && ls "$ADR_DIR"/ADR-*.md >/dev/null 2>&1; then
  TOTAL=$(ls "$ADR_DIR"/ADR-*.md 2>/dev/null | wc -l | tr -d ' ')
  SUPERSEDED=$(grep -l "^Status: SUPERSEDED" "$ADR_DIR"/ADR-*.md 2>/dev/null | wc -l | tr -d ' ')
  ACTIVE=$((TOTAL - SUPERSEDED))
  STALE_COUNT=0
  BROKEN_LINK=0

  # Pick code roots that are actually present; fall back to repo root if none
  CODE_ROOTS=""
  for R in src app lib packages services apps internal pkg cmd; do
    if [ -d "$R" ]; then
      [ -z "$CODE_ROOTS" ] && CODE_ROOTS="$R" || CODE_ROOTS="$CODE_ROOTS $R"
    fi
  done
  [ -z "$CODE_ROOTS" ] && CODE_ROOTS="."

  STALE_OUT=""
  for F in "$ADR_DIR"/ADR-*.md; do
    [ -f "$F" ] || continue
    # Skip superseded — they've already been reviewed
    grep -q "^Status: SUPERSEDED" "$F" 2>/dev/null && continue
    ADR_ID=$(basename "$F" | grep -oE 'ADR-[0-9]+' | head -1)
    [ -z "$ADR_ID" ] && continue
    AGE=$(age_days "$F")
    # Only flag ADRs older than 180d
    [ "$AGE" -lt 180 ] && continue
    # Count code references (excluding the ADR file itself + docs/)
    REFS=$(grep -rIl --exclude-dir=docs --exclude-dir=.git --exclude-dir=node_modules \
             --exclude-di