@ngocsangairvds/vsaf 4.1.7 → 4.1.9

package/skills/vds-skill/vds-scripts/docs/agents/how-to/run-ecosystem-daily-report.md

@@ -1,213 +0,0 @@
-<!-- diátaxis: how-to -->
-
-# Run the Ecosystem Daily Report
-
-> Step-by-step operator guide for verifying, triggering, and troubleshooting the ecosystem daily report.
-
-**Time budget:** ≤ 5 minutes per troubleshooting section.
-
-## Table of Contents
-
-1. [Verify the schedule is running](#verify-the-schedule-is-running)
-2. [Trigger manually](#trigger-manually)
-3. [Check collector output](#check-collector-output)
-4. [Read the golden-signals report](#read-the-golden-signals-report)
-5. [Handle failures](#handle-failures)
-
-## Verify the schedule is running
-
-**Command:**
-```bash
-vds-cli scheduler schedules show ecosystem-daily-report
-```
-
-**Expected output:**
-```
-Name:       ecosystem-daily-report
-Cron:       0 6 * * *
-Queue:      ops-default
-Status:     active
-Next run:   2026-04-28 06:00:00+00:00
-```
-
-**If output is unexpected:**
-
-| Output | Meaning | Next step |
-|--------|---------|-----------|
-| `Status: paused` | Schedule is paused | Run `vds-cli scheduler schedules resume ecosystem-daily-report` |
-| `Status: missing` | Schedule not registered | Check `VDS_SCHEDULER_ENABLED=true` in shell/env, then re-register the schedule |
-| Empty / not found | Scheduler service may be down | Check Docker: `docker ps | grep scheduler` |
-
-## Trigger manually
-
-**Command:**
-```bash
-vds-cli scheduler schedules trigger-now ecosystem-daily-report
-```
-
-**Expected output:**
-```
-Triggered ecosystem-daily-report
-Workflow ID: wf-<uuid>
-Status:      PENDING
-```
-
-**If output is unexpected:**
-
-| Output | Meaning | Next step |
-|--------|---------|-----------|
-| `Scheduler not found` | Scheduler service not reachable | Verify scheduler container: `docker ps | grep scheduler` |
-| `Authentication error` | DBOS or scheduler credentials missing | Check `VDS_SCHEDULER_ENABLED` and state DSN env vars |
-| No response | Network or queue congestion | Retry once; if still failing, check `ops-default` queue depth |
-
-## Check collector output
-
-**Command (diagnose a single collector):**
-```bash
-./scripts/worktree_uv.sh run --project scheduler_orchestrator \
-  python scheduler_orchestrator/scripts/collector-diagnostics.py "Prometheus"
-```
-
-**Expected output:**
-```json
-{
-  "collector": "Prometheus",
-  "status": "ok",
-  "metrics": { ... },
-  "golden_signals": { ... }
-}
-```
-
-**Command (all collectors, JSON):**
-```bash
-./scripts/worktree_uv.sh run --project scheduler_orchestrator \
-  python scheduler_orchestrator/scripts/collector-diagnostics.py --all --json
-```
-
-**If output is unexpected:**
-
-| Output | Meaning | Next step |
-|--------|---------|-----------|
-| `Collector unavailable — timed out after 10s` | Collector exceeded timeout | Bump `VDS_ECOSYSTEM_DAILY__COLLECTOR_TIMEOUT_S=30`; restart; if persistent, check downstream dependency (e.g., Prometheus endpoint down) |
-| `connection refused` | Target port/service not reachable | Verify target is up: `curl http://localhost:8005/metrics` or `docker ps | grep <service>` |
-| `subprocess error` | Git or Docker command failed | Check `git worktree list` or `docker ps` directly |
-
-## Read the golden-signals report
-
-**Command (read the latest report):**
-```bash
-cat reports/ecosystem/$(ls -t reports/ecosystem/ | head -n 1)
-```
-
-**Expected output (exec mode, healthy):**
-```
-📊 Ecosystem Report — 2026-04-28 | 🟢 Health: 94/100
-ERRORS:    2 workflow failures (↓3 vs yesterday)
-LATENCY:   p95 workflow start: 0.8s | p95 event dispatch: 120ms
-SATURATION: PG pool: 23/500 (5%) | Redis: 42MB/256MB (16%) | Queue: 3 pending
-TRAFFIC:   142 workflows completed | 47 events dispatched | 72+70 commits
-```
-
-**If the file is missing:**
-1. Check DB: `SELECT report_date, health_score FROM sched.ecosystem_report_runs ORDER BY report_date DESC LIMIT 3;`
-2. If no row for today → report never ran: see [Report not generated by 06:30 UTC](#report-not-generated-by-0630-utc).
-3. If row exists with `report_path` → check path or filesystem permissions.
-
-## Handle failures
-
-### Report not generated by 06:30 UTC
-
-**Step 1 (30 s) — Check workflow errors:**
-```bash
-vds-cli scheduler workflows list --status ERROR
-```
-
-**Step 2 (30 s) — Check if schedule is paused:**
-```bash
-vds-cli scheduler schedules show ecosystem-daily-report
-```
-
-**Step 3 (30 s) — Verify scheduler enabled:**
-```bash
-echo $VDS_SCHEDULER_ENABLED
-# Expected: true
-```
-
-**Step 4 (1 min) — Trigger manually and watch:**
-```bash
-vds-cli scheduler schedules trigger-now ecosystem-daily-report
-# Then tail events:
-vds-cli scheduler events tail --topic ecosystem.daily.failed
-```
-
-**Step 5 (2 min) — Programmatic check:**
-```bash
-./scripts/worktree_uv.sh run --project scheduler_orchestrator \
-  python -c "from scheduler_orchestrator.tasks.ecosystem_report import check_missed_run; check_missed_run()"
-```
-
-### Health score is 🔴 (<60)
-
-**Step 1 (1 min) — Read the full report for triage hints:**
-```bash
-./scripts/worktree_uv.sh run --project scheduler_orchestrator \
-  python scheduler_orchestrator/scripts/generate-report.py --mode full --output /tmp/triage.md
-cat /tmp/triage.md
-```
-
-**Step 2 (1 min) — Identify which collectors are failing:**
-Look for `[unavailable]` placeholders in the report output.
-
-**Step 3 (2 min) — Diagnose the failing collector:**
-```bash
-./scripts/worktree_uv.sh run --project scheduler_orchestrator \
-  python scheduler_orchestrator/scripts/collector-diagnostics.py <CollectorName>
-```
-
-**Step 4 (1 min) — Adjust thresholds if anomaly is a false positive:**
-```bash
-export VDS_ECOSYSTEM_DAILY__ERROR_THRESHOLD=20
-export VDS_ECOSYSTEM_DAILY__PENDING_THRESHOLD=100
-export VDS_ECOSYSTEM_DAILY__COMMIT_THRESHOLD=75
-```
-
-### Specific collector timeout
-
-**Symptom:** Section shows `⚠️ Collector unavailable — <Name> timed out after 10s`
-
-**Quick command:**
-```bash
-# Confirm the collector works with longer timeout
-VDS_ECOSYSTEM_DAILY__COLLECTOR_TIMEOUT_S=30 \
-./scripts/worktree_uv.sh run --project scheduler_orchestrator \
-  python scheduler_orchestrator/scripts/collector-diagnostics.py "<Name>"
-```
-
-**Expected:** Returns metrics instead of timeout.
-
-**Next steps:**
-1. Make timeout change permanent in `~/.vds/.env` or the scheduler's env.
-2. If still timing out, check downstream dependency (endpoint/process/container).
-
-### DBOS migration drift
-
-**Symptom:** `sched.ecosystem_report_runs` row exists but `health_score` is NULL; or `golden_signals` column is missing.
-
-**Step 1 (1 min) — Check migration status:**
-```bash
-./scripts/worktree_uv.sh run --project scheduler_orchestrator \
-  alembic -c scheduler_orchestrator/alembic.ini current
-```
-
-**Expected:** Current revision is `20260428_a1b2c3d4e5f8_add_phase2_report_columns` (or newer).
-
-**Step 2 (3 min) — Apply migration:**
-```bash
-./scripts/worktree_uv.sh run --project scheduler_orchestrator \
-  alembic -c scheduler_orchestrator/alembic.ini upgrade head
-```
-
-**Step 3 (1 min) — Re-run report:**
-```bash
-vds-cli scheduler schedules trigger-now ecosystem-daily-report
-```

package/skills/vds-skill/vds-scripts/docs/agents/how-to/tips-and-tricks.md

@@ -1,138 +0,0 @@
-<!-- diátaxis: how-to -->
-
-# Tips & Tricks
-
-## Performance
-
-### Run Audits in Parallel
-
-```bash
-# Audit multiple repos concurrently
-vds-cli audit --repo repo-a,repo-b,repo-c --parallel
-
-# Use worktrees to avoid branch switching overhead
-vds-cli git worktree-create --branch feature/x
-```
-
-### Cache Warming
-
-```bash
-# Pre-load orchestrator metadata (saves 2–3s per command)
-vds-cli docs ecosystem-report --warm-cache
-```
-
-### Fast Database Queries
-
-```bash
-# Use prepared queries instead of ad-hoc
-vds-cli db-query --query-file saved-query.sql --connection production
-```
-
-## Productivity
-
-### Shell Aliases
-
-```bash
-# Add to .bashrc or .zshrc
-alias vd='vds-cli'
-alias vda='vds-cli audit'
-alias vdc='vds-cli confluence'
-alias vdg='vds-cli git'
-alias vdm='vds-cli memory'
-```
-
-### Fuzzy Finder Integration
-
-```bash
-# Find and open any orchestrator command
-vds-cli --help | fzf
-
-# Search skills
-cat skills-index.md | fzf
-```
-
-### Git Worktree Shortcuts
-
-```bash
-# Quick create + enter worktree
-worktree() {
-    vds-cli git worktree-create --branch "$1"
-    cd "$(vds-cli git worktree-list --format path --branch "$1")"
-}
-```
-
-### Effective Agent Prompting
-
-- Start with the goal: "Run an audit on the INSURANCE department"
-- Provide context: "Use checklist DEP-001, target repo insurance-service"
-- Specify output: "Generate a markdown report with severity levels"
-- Reference skills: "Use the audit-orchestrator-skill"
-
-## Debugging
-
-### Log Inspection
-
-```bash
-# View recent orchestrator logs
-vds-cli logs --orchestrator audit --last 100
-
-# Follow live logs
-vds-cli logs --orchestrator scheduler --follow
-```
-
-### Database Queries
-
-```bash
-# Check audit results
-vds-cli db-query --connection postgres --query "SELECT * FROM audit_results WHERE repo='my-service' ORDER BY created_at DESC LIMIT 10"
-```
-
-### Test Isolation
-
-```bash
-# Run a single test file
-pytest tests/test_audit.py -v
-
-# Run with verbose output
-pytest tests/ -v --tb=short
-
-# Run only failed tests
-pytest --lf
-```
-
-## Quality of Life
-
-### IDE Setup
-
-Recommended VS Code extensions:
-- Python (Microsoft)
-- Even Better TOML
-- Markdown All in One
-- Mermaid Markdown Syntax Highlighting
-
-### Pre-Commit Hook
-
-```bash
-# Install the hook (run once)
-vds-cli lint install-hook
-
-# Or run manually before commit
-vds-cli lint --all
-```
-
-### Auto-Complete
-
-Enable shell completion for `vds-cli`:
-
-```bash
-# Bash
-vds-cli --install-completion bash
-
-# Zsh
-vds-cli --install-completion zsh
-```
-
-## See Also
-
-- [Troubleshooting Guide](../how-to/troubleshooting-guide.md)
-- [Feature Progression Guide](../tutorials/feature-progression-guide.md)

package/skills/vds-skill/vds-scripts/docs/agents/how-to/troubleshooting-guide.md

@@ -1,221 +0,0 @@
-<!-- diátaxis: how-to -->
-
-# Troubleshooting Guide
-
-## Quick Diagnostic
-
-```bash
-# Run the doctor command
-vds-cli doctor
-```
-
-## CLI Failures
-
-### `vds-cli: command not found`
-
-**Cause:** Not in PATH or not installed.
-
-**Fix:**
-```bash
-# Verify uv sync completed
-uv sync
-
-# Check PATH includes .venv/bin
-which vds-cli || echo "Not in PATH"
-```
-
-### `uv sync` fails with resolution error
-
-**Cause:** Dependency conflict or outdated lock file.
-
-**Fix:**
-```bash
-# Update lock file
-uv lock
-
-# If still failing, clear cache
-uv cache clean
-uv sync
-```
-
-### Orchestrator command returns nothing
-
-**Cause:** Orchestrator not registered or entry point missing.
-
-**Fix:**
-```bash
-# Check orchestrator registration
-vds-cli --help | grep <orchestrator>
-
-# Verify entry point
-which vds-<orchestrator>
-```
-
-## Test Failures
-
-### `pytest` fails with DB connection error
-
-**Cause:** Postgres or Redis not running.
-
-**Fix:**
-```bash
-# Start services
-docker compose up -d postgres redis
-
-# Verify
-docker compose ps
-```
-
-### Mock assertion fails
-
-**Cause:** Mock not configured for the right module path.
-
-**Fix:**
-```python
-# Correct: patch where the function is USED
-@patch("my_module.external_api_call")
-def test_something(mock_api):
-    ...
-```
-
-## Sync Failures
-
-### Confluence sync fails with 401
-
-**Cause:** Token expired or incorrect.
-
-**Fix:**
-```bash
-# Verify token
-echo $INTERNAL_CONFLUENCE_TOKEN | head -c 20
-
-# Regenerate in Confluence → Account Settings → Personal Access Tokens
-# Update ~/.vds/.env
-```
-
-### Bitbucket operations timeout
-
-**Cause:** Network issue or incorrect base URL.
-
-**Fix:**
-```bash
-# Verify connectivity
-curl -I $VDS_BITBUCKET_HTTP_BASE
-
-# Check base URL in ~/.vds/.env
-grep BITBUCKET ~/.vds/.env
-```
-
-## Phase 225 Embedding (Post 2026-04-26)
-
-### Container won't start: Ollama unreachable
-
-**Cause:** Memory orchestrator cannot reach local Ollama service (default at `host.docker.internal:11434`).
-
-**Fix:**
-```bash
-# Check if Ollama is running on host
-curl -I http://host.docker.internal:11434/api/tags
-
-# If 404/timeout, start Ollama or switch to cloud provider
-# Switch to OpenAI (example)
-cat ~/.vds/.env | grep -E "VDS_AGENT_CORE_EMBED__"
-
-# Update for OpenAI
-cat >> ~/.vds/.env <<'EOF'
-VDS_AGENT_CORE_EMBED__PROVIDER=openai
-VDS_AGENT_CORE_EMBED__BASE_URL=https://api.openai.com/v1
-VDS_AGENT_CORE_EMBED__API_KEY=sk-...
-VDS_AGENT_CORE_EMBED__MODEL_STANDARD=text-embedding-3-large
-VDS_AGENT_CORE_EMBED__DIMENSION=1024
-EOF
-
-# Restart memory orchestrator
-docker compose -p vds-platform restart memory-api memory-worker
-```
-
-### Dimension mismatch on cloud switch
-
-**Cause:** Switching embedding providers without dimension validation enabled.
-
-**Fix:**
-```bash
-# Verify current Qdrant collection dimension
-vds-cli memory admin list-collections
-
-# If switching models and dimension changes are required:
-# 1. Stop memory orchestrator
-docker compose -p vds-platform stop memory-api memory-worker
-
-# 2. Drop existing collection (destructive!)
-vds-cli memory admin drop-collection --collection vds_memories --confirm
-
-# 3. Update ~/.vds/.env with new dimension
-# (see Phase 225 Embedding section above)
-
-# 4. Verify dimension configuration
-vds-cli doctor  # should show no warnings about dimension verification
-```
-
-**Prevention:** Always check provider dimension defaults before switching.
-- Ollama/bge-m3: 1024 (default VDS baseline)
-- OpenAI/text-embedding-3-small: 1536 (no truncation)
-- OpenAI/text-embedding-3-large: 3072 (truncate to 1024 with matryoshka)
-
-### Image size larger than expected (clear stale layers)
-
-**Cause:** Docker build cache contains stale embedding/ML layers from previous provider (sentence-transformers, etc.).
-
-**Fix:**
-```bash
-# Clean Docker build cache (affects all projects)
-docker builder prune -a
-
-# Or rebuild memory-api image from scratch
-docker compose -p vds-platform build --no-cache memory-api memory-worker
-
-# Verify Phase 225 image is lean (should be ~10 GB, not 27+ GB)
-docker images vds-memory-api --format 'table {{.Repository}}\t{{.Size}}'
-```
-
-## Environment Issues
-
-### `~/.vds/.env` not loading
-
-**Cause:** File permissions or wrong location.
-
-**Fix:**
-```bash
-# Verify file exists and is readable
-ls -la ~/.vds/.env
-
-# Check env loading
-vds-cli env status
-```
-
-### Docker services not starting
-
-**Cause:** Port conflicts or missing images.
-
-**Fix:**
-```bash
-# Check port usage
-lsof -i :5432  # Postgres
-lsof -i :6379  # Redis
-
-# Pull images
-docker compose pull
-```
-
-## Escalation Path
-
-| Severity | Channel | Information to Provide |
-|----------|---------|----------------------|
-| Minor | Fix yourself using this guide | — |
-| Moderate | Ask in team Slack | Command, error output, `vds-cli doctor` |
-| Critical | File incident | All of the above + timeline, impact |
-
-## See Also
-
-- [Common Errors](../reference/common-errors.md)
-- [Configuration Reference](../reference/configuration-reference.md)