docs: add session preflight and expand lint scope batch5

2026-02-16 03:53:56 -08:00
parent 9c9f4fa182
commit de7533f97e
7 changed files with 120 additions and 25 deletions
--- a/docs/NODE2_DIAGNOSTIC_REPORT.md
+++ b/docs/NODE2_DIAGNOSTIC_REPORT.md
@@ -7,7 +7,7 @@

 ## ✅ 1. Моделі — ВСІ ЗБЕРЕЖЕНІ (Ollama)

-### 📦 8 моделей в Ollama (загалом ~118 GB):
+### 📦 8 моделей в Ollama (загалом ~118 GB)

 | Модель | Розмір | Параметри | Тип | Статус |
 |--------|--------|-----------|------|--------|
@@ -24,7 +24,7 @@

 ---

-### ❌ Видалено з `models/` (не Ollama):
+### ❌ Видалено з `models/` (не Ollama)

 - **qwen3-vl-32b-instruct** (~130 GB) — vision-модель для мультимодальності
  - 65.5 GB `.gguf` файл
@@ -33,7 +33,7 @@

 **Проблема:** Немає vision-моделей для мультимодальних запитів!

-**Рішення:** 
+**Рішення:**
 1. Завантажити `llava:13b` через Ollama (~13 GB)
 2. АБО відновити Qwen3-VL з HuggingFace (якщо потрібен кастомний inference)

@@ -77,7 +77,7 @@ curl http://localhost:9102/health

 ## ✅ 4. DAGI Stack — Частково ПРАЦЮЄ

-### Запущені сервіси:
+### Запущені сервіси

 | Сервіс | Статус | Порт | Призначення |
 |--------|--------|------|-------------|
@@ -91,7 +91,7 @@ curl http://localhost:9102/health

 ---

-### 🤖 12 CrewAI Агентів (4 Workflows):
+### 🤖 12 CrewAI Агентів (4 Workflows)

 #### 1. **Onboarding Workflow** (3 агенти)
 - `welcomer` — вітання нових користувачів
@@ -123,7 +123,7 @@ curl http://localhost:9010/workflow/list

 ## ⚠️ 5. Мультимодальні сервіси — ЧАСТКОВО

-### ✅ Працюють:
+### ✅ Працюють

 | Сервіс | Порт | Статус | Призначення |
 |--------|------|--------|-------------|
@@ -132,7 +132,7 @@ curl http://localhost:9010/workflow/list
 | **Agent Cabinet** | 8898 | ✅ Healthy | Управління агентами |
 | **MeiliSearch** | 7700 | ✅ Running | Текстовий пошук |

-### ❌ НЕ працюють:
+### ❌ НЕ працюють

 | Сервіс | Порт | Статус | Причина |
 |--------|------|--------|---------|
@@ -145,19 +145,19 @@ curl http://localhost:9010/workflow/list

 ## 📊 6. Інфраструктура NODE2

-### Ресурси:
+### Ресурси
 - **CPU:** Apple M4 Max (40-core GPU)
 - **RAM:** 64 GB
 - **VRAM:** 48 GB (GPU)
 - **Диск:** ~500 GB вільно (після cleanup)

-### Docker мережа:
+### Docker мережа
 - `dagi-network` — всі DAGI сервіси
 - Bridge для комунікації між контейнерами

-### Ollama:
+### Ollama
 - **Версія:** Latest
- **URL:** http://localhost:11434
+- **URL:** [http://localhost:11434](http://localhost:11434)
 - **Models dir:** `/Users/apple/.ollama/models`

 ---
@@ -258,14 +258,14 @@ POST http://localhost:9010/workflow/execute

 ## ✅ 9. ПІДСУМОК

-### Готово:
+### Готово
 - ✅ **8 LLM-моделей збережені** в Ollama (включно з DeepSeek 70B)
 - ✅ **Swapper Service запущено** на NODE2 (порт 8890)
 - ✅ **DAGI Router працює** (порт 9102)
 - ✅ **12 CrewAI агентів готові** до інтеграції
 - ✅ **Web Search + Vector DB працюють**

-### Потрібно:
+### Потрібно
 - ⚠️ **Відновити vision-модель** (LLaVA або Qwen3-VL)
 - ⚠️ **Запустити STT/OCR** (для voice/photo)
 - ⚠️ **Підключити Swapper до Router** (NODE2 → NODE1)
@@ -280,4 +280,3 @@ POST http://localhost:9010/workflow/execute
 ---

 *Документ створено автоматично під час діагностики NODE2 після git cleanup операції.*
-
--- a/docs/SESSION_STARTER.md
+++ b/docs/SESSION_STARTER.md
@@ -21,6 +21,11 @@ Important: keep docs and runtime aligned via explicit drift checks, not assumpti

 ## Session Bootstrap (Services + Docs)

+0. Preflight (must pass before any task):
+```bash
+bash scripts/session/preflight.sh --expected-root /Users/apple/github-projects/microdao-daarion
+```
+
 1. Run integrations bootstrap report:
 ```bash
 bash scripts/docs/session_bootstrap.sh
--- a/docs/hardcode_vs_config.md
+++ b/docs/hardcode_vs_config.md
@@ -4,13 +4,13 @@

 **Хардкод** = значення, які "зашиті" прямо в коді і не можуть змінюватись без редагування коду.

-### Приклад хардкоду:
+### Приклад хардкоду
 ```python
 # ❌ ХАРДКОД - значення прямо в коді
 local_model = "qwen3-8b"  # Якщо треба змінити модель, треба редагувати код!
 ```

-### Проблеми хардкоду:
+### Проблеми хардкоду
 1. **Треба редагувати код** для зміни значення
 2. **Не можна змінити без перезапуску** сервісу
 3. **Важко тестувати** різні конфігурації
@@ -22,7 +22,7 @@ local_model = "qwen3-8b"  # Якщо треба змінити модель, т

 **Конфігурація** = значення, які зберігаються окремо від коду (в файлах, змінних середовища, БД) і можуть змінюватись без редагування коду.

-### Приклад конфігурації:
+### Приклад конфігурації
 ```yaml
 # ✅ КОНФІГ - значення в окремому файлі router-config.yml
 llm_profiles:
@@ -38,7 +38,7 @@ llm_profile = router_config.get("llm_profiles", {}).get("qwen3_science_8b")
 model = llm_profile.get("model")  # Беремо з конфігу, не хардкодимо!
 ```

-### Переваги конфігурації:
+### Переваги конфігурації
 1. **Зміна без редагування коду** - просто змінити YAML файл
 2. **Різні конфіги для різних середовищ** (dev/prod/staging)
 3. **Легко тестувати** - можна створити test-config.yml
@@ -60,13 +60,13 @@ model = llm_profile.get("model")  # Беремо з конфігу, не хар

 ## 🔧 ЩО МИ ВИПРАВИЛИ?

-### БУЛО (хардкод):
+### БУЛО (хардкод)
 ```python
 # ❌ Хардкод - модель завжди "qwen3-8b"
 local_model = "qwen3-8b"
 ```

-### СТАЛО (з конфігу):
+### СТАЛО (з конфігу)
 ```python
 # ✅ Читаємо з конфігу
 if llm_profile.get("provider") == "ollama":
@@ -74,7 +74,7 @@ if llm_profile.get("provider") == "ollama":
    local_model = ollama_model.replace(":", "-")  # qwen3:8b → qwen3-8b
 ```

-### Результат:
+### Результат
 - ✅ Модель береться з `router-config.yml`
 - ✅ Якщо змінити конфіг → зміниться поведінка
 - ✅ Не треба редагувати код для зміни моделі
@@ -84,12 +84,12 @@ if llm_profile.get("provider") == "ollama":

 ## 💡 КОЛИ ВИКОРИСТОВУВАТИ?

-### Хардкод - тільки для:
+### Хардкод - тільки для
 - Константи (π = 3.14, версія API)
 - Значення, які ніколи не зміняться
 - Технічні деталі (timeout = 5.0 сек)

-### Конфігурація - для:
+### Конфігурація - для
 - Моделі LLM
 - API ключі
 - URL сервісів
@@ -100,7 +100,7 @@ if llm_profile.get("provider") == "ollama":

 ## 📝 ПРИКЛАД З НАШОГО ПРОЄКТУ

-### router-config.yml (конфігурація):
+### router-config.yml (конфігурація)
 ```yaml
 agents:
  helion:
@@ -112,7 +112,7 @@ llm_profiles:
    model: qwen3:8b  # ← Можна змінити модель тут
 ```

-### main.py (код):
+### main.py (код)
 ```python
 # Читаємо з конфігу
 default_llm = agent_config.get("default_llm", "qwen3-8b")
--- a/docs/runbooks/DOCS_SERVICES_AUTOMATION_RUNBOOK.md
+++ b/docs/runbooks/DOCS_SERVICES_AUTOMATION_RUNBOOK.md
@@ -7,6 +7,13 @@ Scope: GitHub, Gitea, Jupyter, Pieces documentation integration workflow.

 Keep docs state synchronized with service reality and publish curated docs updates safely.

+## 0) Session preflight
+
+```bash
+cd /Users/apple/github-projects/microdao-daarion
+bash scripts/session/preflight.sh --expected-root /Users/apple/github-projects/microdao-daarion
+```
+
 ## 1) Refresh service status

 ```bash
--- a/docs/standards/lint_scope.txt
+++ b/docs/standards/lint_scope.txt
@@ -33,6 +33,8 @@ docs/DEPLOYMENT_OVERVIEW.md
 docs/DEPLOY_MIGRATIONS.md
 docs/ACTION_PLAN.md
 docs/NODE2_GUARDIAN_SETUP.md
+docs/hardcode_vs_config.md
+docs/NODE2_DIAGNOSTIC_REPORT.md
 docs/consolidation/README.md
 docs/consolidation/SOURCES.md
 docs/runbooks/DOCS_SERVICES_AUTOMATION_RUNBOOK.md
--- a/scripts/docs/docs_sync.sh
+++ b/scripts/docs/docs_sync.sh
@@ -118,6 +118,7 @@ doc_paths=(
  scripts/docs/docs_lint.sh
  scripts/docs/run_docs_maintenance.sh
  scripts/docs/install_local_cron.sh
+  scripts/session/preflight.sh
  scripts/docs/jupyter_sync.sh
  scripts/docs/pieces_sync.sh
  scripts/docs/services_sync.sh
--- a/scripts/session/preflight.sh
+++ b/scripts/session/preflight.sh
@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+EXPECTED_ROOT="${EXPECTED_ROOT:-/Users/apple/github-projects/microdao-daarion}"
+REQUIRE_SESSION_STARTER=1
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  bash scripts/session/preflight.sh [--expected-root /path/to/repo] [--no-session-starter]
+
+Checks:
+  - current working directory
+  - git repository root
+  - current branch
+  - latest commit
+  - docs/SESSION_STARTER.md presence (default required)
+  - docs directory presence
+
+Exit codes:
+  0  all checks passed
+  10 wrong repo root
+  11 missing SESSION_STARTER.md
+  12 missing docs directory
+  13 git not initialized / not a repo
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --expected-root)
+      EXPECTED_ROOT="$2"
+      shift 2
+      ;;
+    --no-session-starter)
+      REQUIRE_SESSION_STARTER=0
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown arg: $1" >&2
+      usage
+      exit 2
+      ;;
+  esac
+done
+
+if ! git_root="$(git rev-parse --show-toplevel 2>/dev/null)"; then
+  echo "[FAIL] not a git repository" >&2
+  exit 13
+fi
+
+pwd_now="$(pwd)"
+branch="$(git branch --show-current || true)"
+head_line="$(git log --oneline -n 1 2>/dev/null || echo 'NO_COMMITS')"
+
+printf "[INFO] pwd: %s\n" "$pwd_now"
+printf "[INFO] git_root: %s\n" "$git_root"
+printf "[INFO] branch: %s\n" "${branch:-DETACHED_OR_NONE}"
+printf "[INFO] head: %s\n" "$head_line"
+printf "[INFO] expected_root: %s\n" "$EXPECTED_ROOT"
+
+if [[ "$git_root" != "$EXPECTED_ROOT" ]]; then
+  echo "[FAIL] unexpected repository root" >&2
+  exit 10
+fi
+
+if [[ ! -d "$git_root/docs" ]]; then
+  echo "[FAIL] missing docs directory: $git_root/docs" >&2
+  exit 12
+fi
+
+if [[ "$REQUIRE_SESSION_STARTER" -eq 1 && ! -f "$git_root/docs/SESSION_STARTER.md" ]]; then
+  echo "[FAIL] missing SESSION_STARTER: $git_root/docs/SESSION_STARTER.md" >&2
+  exit 11
+fi
+
+echo "[PASS] preflight OK"