@ngocsangairvds/vsaf 3.2.16 → 4.0.1

package/tools/vds-scripts/docs/agents/how-to/03-memory-cross-agent.md

@@ -1,241 +0,0 @@
-<!-- diátaxis: how-to -->
-
-# Using VDS AI Memory from External Agent CLIs
-
-This guide covers how external agent runtimes — Codex, OpenCode, and Qwen — can
-read from and write to VDS AI Memory using the `vds-cli memory` subcommand.
-
-## Prerequisites
-
-The VDS AI Memory API must be running and reachable. Start the active runtime stack if needed:
-
-```bash
-cd WHO-project/vds-scripts/memory_orchestrator
-docker compose --profile dev --profile mem0 up -d
-```
-
-This starts the active memory runtime stack from `memory_orchestrator/`.
-
-> `WHO-project/vds-ai-memory/` is historical/archive-only and should not be used for current startup or runtime guidance.
-
-## Runtime Environment Resolution
-
-| Variable | Purpose | Default |
-|---|---|---|
-| `VDS_MEMORY_API_URL` | Explicit base URL of the memory API | If unset: `http://localhost:${API_PORT:-8000}` |
-
-`vds-cli memory` loads `~/.vds/.env` automatically. Set an explicit URL only
-when the runtime is on a non-default host/port:
-
-```bash
-export VDS_MEMORY_API_URL="http://localhost:8010"
-```
-
-> **Note:** The memory API does not require an API key in its default
-> local-dev configuration. For current runtime/deployment guidance, prefer
-> `WHO-project/vds-scripts/memory_orchestrator/README.md` and the canonical spec
-> triplet under `.gpt-5.4/specs/vds-ai-memory/`.
-
-## Storing a Decision
-
-```bash
-# Store a decision scoped to a project using tags
-vds-cli memory store "decided to use Kafka for async event dispatch" \
-  --category business-logic --importance high \
-  --tags PAR,architecture,kafka
-
-# Minimal store
-vds-cli memory store "merchant-billing uses Spring Boot 3.2"
-```
-
-## Searching Memories
-
-```bash
-# Semantic search across all memories
-vds-cli memory search "kafka event dispatch" --limit 5
-
-# Filter by category
-vds-cli memory search "auth patterns" --category business-logic --limit 10
-```
-
-## Usage from Each Agent CLI
-
-All agent CLIs that can run shell commands can call `vds-cli` directly.
-Inherit `~/.vds/.env` via the shell session that launches the agent. Set
-`VDS_MEMORY_API_URL` only if you need an explicit override.
-
-### Codex
-
-```bash
-codex exec --skip-git-repo-check -m gpt-5.4 "your prompt here"
-```
-
-Within the Codex session, the agent runs shell commands:
-
-```bash
-vds-cli memory store "Codex discovered that merchant-report uses JPA auditing"
-vds-cli memory search "merchant-report auditing"
-```
-
-### OpenCode (Z.AI / GLM)
-
-```bash
-opencode run -m "zai-coding-plan/glm-5.1" "your prompt here"
-```
-
-The OpenCode agent shell-executes:
-
-```bash
-vds-cli memory store "OpenCode: PAR project checklist page is 88722450" \
-  --category business-logic --importance high
-vds-cli memory search "PAR checklist"
-```
-
-### Qwen
-
-```bash
-qwen -m qwen3-coder "your prompt here"
-```
-
-Qwen agents call:
-
-```bash
-vds-cli memory store "Qwen: insurance hexagonal boundary violations found in 3 repos"
-vds-cli memory search "hexagonal boundary violations"
-```
-
-## Project Scoping via Tags
-
-To keep memories scoped to a project, include the project key as a tag:
-
-```bash
-# Store scoped to project PAR
-vds-cli memory store "billing service auth pattern confirmed" \
-  --tags PAR,billing,auth
-
-# Search within PAR context (post-filter by tags)
-vds-cli memory search "billing auth" --limit 10
-```
-
-## Health Check
-
-Before a long agent run, verify the memory service is reachable:
-
-```bash
-vds-cli memory health
-```
-
-Expected output: `{"status": "healthy", ...}`
-
-## Practical Rules
-
-- Store decisions immediately after they are made — do not batch at end of session.
-- Include project key, service name, and date context in the content string.
-- Keep content under 500 characters per memory for searchability.
-- Do not store secrets, credentials, or personal data.
-- Use `--importance high` for irreversible architectural decisions.
-
----
-
-## Python SDK: `vds_memory_client` (VAMI-003)
-
-Since VAMI-003, a standalone Python package `vds_memory_client` provides
-programmatic access to VDS AI Memory for any Python agent or script — no
-`vds-cli` installation required.
-
-### Installing
-
-```bash
-# From the VDS monorepo (worktree or vds-scripts)
-uv run --project WHO-project/vds-scripts/vds_memory_client python3 -c "import vds_memory_client"
-
-# Or add as a dependency in your pyproject.toml
-[tool.uv.sources]
-vds_memory_client = { path = "../../vds_memory_client" }
-```
-
-### Basic Usage
-
-```python
-import asyncio
-from vds_memory_client import VDSMemoryClient
-
-async def main():
-    import os
-
-    base_url = os.getenv("VDS_MEMORY_API_URL") or f"http://localhost:{os.getenv('API_PORT', '8000')}"
-    client = VDSMemoryClient(base_url=base_url, timeout=10.0)
-
-    # Health check
-    status = await client.health()
-    print(status)  # {"status": "healthy", ...}
-
-    # Store a decision
-    result = await client.store(
-        content="Decided to use Kafka for async event dispatch",
-        category="business-logic",
-        importance="high",
-        tags=["PAR", "architecture"],
-    )
-    print(result["memory_id"])
-
-    # Search
-    results = await client.search(query="kafka event dispatch", limit=5)
-    for m in results["results"]:
-        print(f"[{m['category']}] {m['content'][:80]}")
-
-asyncio.run(main())
-```
-
-### Session State Caching
-
-`VDSMemoryClient` caches the health-check result in `~/.vds/.memory-session.json`
-using an atomic write (`tempfile.mkstemp` + `os.replace`). This file is:
-- **Not** in iCloud (lives in `~/.vds/`, not `~/Library/Mobile Documents/`)
-- Safe for concurrent writes from multiple agent processes
-- Valid for 60 minutes by default before the client re-checks health
-
-### iCloud Path Compatibility
-
-`vds_memory_client` runs correctly from iCloud-backed project paths
-(e.g. `~/Library/Mobile Documents/com~apple~CloudDocs/...`). The key properties
-that make this safe:
-
-| Concern | How it is handled |
-|---------|-------------------|
-| Spaces in path arguments | Wrap variables in double-quotes: `"$CLAUDE_PROJECT_DIR/..."` |
-| Atomic session writes | Written to `~/.vds/` (outside iCloud), using `os.replace()` |
-| `uv run --project <path>` | Path passed as a quoted argument; uv handles spaces correctly |
-
-### Hook Integration (now via Claude Code plugins)
-
-**Status (2026-04-24)**: The `vds_hooks` Python package was retired by
-`vds-hooks-claude-plugin-packaging` Phase 6. Hook integration with VDS AI Memory
-now lives entirely in the **Claude Code plugin format**:
-
-- `WHO-project/vds-skills/plugins/vds-hooks-core/` — generic hooks
-- `WHO-project/vds-skills/plugins/vds-hooks-extras/` — VDS-specific hooks (memory, audit, agent context)
-
-Plugins are installed via `/plugin marketplace add` + `/plugin install` and fire
-automatically on Claude Code events (`SessionStart`, `Stop`, `SessionEnd`,
-`UserPromptSubmit`, etc.) — no manual `vds-cli` invocation required.
-
-For the HTTP proxy endpoints, see
-`WHO-project/vds-scripts/memory_orchestrator/` — those endpoints are
-independent of the Python-package retirement and continue to serve
-`POST /api/v1/hooks/session-context` and `POST /api/v1/hooks/session-persist`.
-
-For SDK-level memory access from your own scripts, use `vds_memory_client`
-(see "Python SDK" section above). For the canonical hook semantics + dual-path
-safety-net design, see the spec at
-`.gpt-5.4/specs/vds-hooks-claude-plugin-packaging/` (Phase 6 archive +
-predecessor `hooks.RETIRED-2026-05-02/`).
-
-### Environment Variables
-
-| Variable | Effect | Default |
-|----------|--------|---------|
-| `VDS_MEMORY_API_URL` | API base URL | If unset: `http://localhost:${API_PORT:-8000}` |
-| `VDS_HOOK_SESSION_MEMORY` | Set to `"0"` to disable session context hook | `"1"` |
-| `VDS_HOOK_MEMORY_PERSIST` | Set to `"0"` to disable persist-stop hook | `"1"` |
-| `VDS_HOOK_MEMORY_DECISIONS` | Set to `"0"` to skip decision extraction | `"1"` |

package/tools/vds-scripts/docs/agents/how-to/04-using-progress-reports.md

@@ -1,240 +0,0 @@
-<!-- diátaxis: how-to -->
-
-# How To: Generate Progress Reports
-
-## Prerequisites
-
-1. **Repos synced**: `vds-cli audit sync repos --bitbucket-project INSURANCE-AI`
-2. **BMAD knowledge graph**: Must exist at `~/.vds/cache/repos/INSURANCE-AI-project/bmad_ntbh/`
-3. **Database** (optional): Set `VDS_PROGRESS_STATE_DSN` in `~/.vds/.env` for persistence
-
-## Quick Start
-
-```bash
-# Structural-only report (fast, ~2s)
-vds-cli progress report -p INSURANCE-AI --dimensions structural --skip-sync
-
-# Check your score
-vds-cli progress db status
-```
-
-## Common Workflows
-
-### Daily Score Check
-
-```bash
-# Generate report and check trend
-vds-cli progress report -p INSURANCE-AI --dimensions structural --skip-sync -q
-vds-cli progress db status
-```
-
-### Deep-Dive a Specific FR
-
-```bash
-# FR8 analysis in JSON
-vds-cli progress report -p INSURANCE-AI --fr FR8 --dimensions structural --format json --skip-sync -q
-```
-
-### Scripted/CI Usage
-
-Use `--quiet` (`-q`) and `--format json` for clean machine-readable output:
-
-```bash
-SCORE=$(vds-cli progress report -p INSURANCE-AI --dimensions structural --format json --skip-sync -q \
-  | python3 -c "import sys,json; print(json.load(sys.stdin)['overall_score'])")
-echo "Current score: $SCORE"
-```
-
-### Resume an Interrupted Run
-
-If a run fails mid-pipeline, the checkpoint is saved in the DB:
-
-```bash
-# The run_id is printed in the log output
-vds-cli progress report -p INSURANCE-AI --resume-run-id <uuid-from-failed-run>
-```
-
-### Topology Exploration
-
-```bash
-# List all FRs in the knowledge graph
-vds-cli progress topology -p INSURANCE-AI -q | jq '.fr_modules[].fr_id'
-
-# Count services
-vds-cli progress topology -p INSURANCE-AI -q | jq '.service_catalog | length'
-```
-
-## LLM Provider Selection (Phase 3)
-
-Use `--llm-provider` to control which LLM backend scores dimensions 7-8:
-
-```bash
-# Auto-detect from environment (default)
-vds-cli progress report -p INSURANCE-AI --llm-provider auto
-
-# Explicit provider
-vds-cli progress report -p INSURANCE-AI --llm-provider openai    # requires OPENAI_API_KEY
-vds-cli progress report -p INSURANCE-AI --llm-provider anthropic # requires ANTHROPIC_AUTH_TOKEN
-vds-cli progress report -p INSURANCE-AI --llm-provider ollama    # requires Ollama on localhost:11434
-
-# Disable LLM entirely (equivalent to --dimensions structural)
-vds-cli progress report -p INSURANCE-AI --llm-provider none --skip-sync
-```
-
-Auto-detect order: explicit `--profile` → `VDS_AUDIT_LLM_ENABLED=0` hard-disable → `OPENAI_API_KEY` / `ANTHROPIC_AUTH_TOKEN` env → structural-only.
-
-**Ollama is NOT auto-detected** — it must be requested via `--llm-provider ollama` explicitly. This is because Ollama's installed models may be cloud-routed, embedding-only, or reasoning models that need different token budgets, so aggressive auto-detection caused score regressions. When auto mode finds no provider, it leaves dims 7-8 as `None` and scores renormalize across structural dimensions only — **auto-detect is guaranteed to produce the same score as `--llm-provider none`**.
-
-## JSON Report Schema (Phase 3)
-
-Phase 3 reports include three new top-level keys in `--format json` output:
-
-```bash
-vds-cli progress report -p INSURANCE-AI --dimensions structural --format json --skip-sync -q \
-  | jq '{heatmap: .heatmap, repo_health: .repo_health, coverage: .dimension_coverage}'
-```
-
-- **`heatmap`**: List of FR × dimension objects — boolean pass/fail and numeric scores per FR
-- **`repo_health`**: Per-repo test ratio and `green`/`yellow`/`red` health indicator
-- **`dimension_coverage`**: Pass-rates and averages across all FRs (e.g. `service_exists: 0.9`)
-
-## Scripted Score + Coverage
-
-```bash
-vds-cli progress report -p INSURANCE-AI --dimensions structural --format json --skip-sync -q | \
-  python3 -c "
-import sys, json
-d = json.load(sys.stdin)
-print(f'Score: {d[\"overall_score\"]}')
-print(f'Doc chain: {d[\"dimension_coverage\"].get(\"doc_chain_complete\", \"N/A\")}')
-print(f'Recommendations: {sum(len(s[\"recommendations\"]) for s in d[\"sections\"])}')
-"
-```
-
-## Progressive Disclosure Modes (Phase 4)
-
-`--mode` picks a rendering tier. All four modes use the same underlying computation — only the rendered output differs:
-
-```bash
-# Exec: ≤20 lines. Slack pastes, email digests, GitHub status checks.
-vds-cli progress report -p INSURANCE-AI --mode exec --skip-sync -q
-
-# Summary: ≤100 lines. Standup review, code-review context, daily digest.
-vds-cli progress report -p INSURANCE-AI --mode summary --skip-sync -q
-
-# Standard: ~564 lines. Default. Byte-identical to pre-Phase-4 output (heatmap,
-# per-FR detail, trend, risk register). Use when daily development review.
-vds-cli progress report -p INSURANCE-AI --skip-sync -q   # --mode standard is implicit
-
-# Full: ~581 lines. Standard + stratified cluster sub-reports + appendices.
-# Use for quarterly audits, retrospectives, compliance packets.
-vds-cli progress report -p INSURANCE-AI --mode full --skip-sync -q
-```
-
-**Tip**: Start with `--mode exec` when piping into chat notifications and bump up to `summary` or `full` only when someone asks "why did the score move?"
-
-## CI/CD Quality Gates (Phase 4)
-
-Make progress report failures break your pipeline. `vds-cli progress report` exits with:
-
-- `0` — report generated, no gates tripped
-- `1` — runtime error (missing DSN, sync failed, crash)
-- `2` — **quality gate failed** (report file still written)
-
-```bash
-# Fail the build if overall score drops below 60
-vds-cli progress report -p INSURANCE-AI --skip-sync --fail-under 60 -q
-
-# Fail if any FR regressed by more than 15 points vs the previous run
-vds-cli progress report -p INSURANCE-AI --skip-sync --fail-on-regression -q
-
-# Compare against a specific historical run instead of "previous"
-vds-cli progress report -p INSURANCE-AI --skip-sync \
-  --fail-on-regression --baseline <run-id> -q
-
-# Combine gates — any trip exits 2
-vds-cli progress report -p INSURANCE-AI --skip-sync \
-  --fail-under 60 --fail-on-regression -q
-echo $?   # 2 if either gate fails
-```
-
-**Important**: Unlike SonarQube's `sonar-scanner` (which silently exits 0 even on gate failure unless you pass `-Dsonar.qualitygate.wait=true`), `vds-cli progress` honors gate flags immediately when set. The report file is always written before the non-zero exit, so your CI can still upload it as an artifact.
-
-**GitHub Actions example**:
-
-```yaml
-- name: Progress check
-  run: |
-    vds-cli progress report -p INSURANCE-AI --skip-sync \
-      --fail-under 60 --mode exec -q > progress.txt
-  continue-on-error: false   # exit 2 fails the step
-
-- name: Upload report
-  if: always()   # still upload when the step failed
-  uses: actions/upload-artifact@v4
-  with:
-    path: ~/.vds/cache/progress-reports/
-```
-
-## Bimodal Distribution / Stratified Clusters (Phase 4)
-
-When your FR scores split cleanly into "passing FRs" and "failing FRs" with no middle tier, the report emits a `bimodal_warning` block. This is the **valence-gap heuristic** — a UX signal, not statistical bimodality (ADR-Q7).
-
-Detection rules (all must hold):
-
-1. `total_frs ≥ 10`
-2. `medium == 0`
-3. `high_count > 0 AND low_count > 0`
-4. `min(high, low) / total ≥ 0.25` (dominance guard — kills skewed-unimodal false positives like 14/0/1)
-
-When detected, `summary` and `full` modes render **stratified sub-reports**: a high-cluster mini-report (passing FRs, avg score, weakest remaining dim, top remaining action) and a low-cluster mini-report (blocked FRs, dominant blocker, highest-priority fix).
-
-Extract cluster data from JSON:
-
-```bash
-vds-cli progress report -p INSURANCE-AI --format json --skip-sync -q \
-  | jq '.bimodal_warning'
-# {
-#   "detected": true,
-#   "stratification_variable": "service_exists",
-#   "high_cluster": {
-#     "label": "passing",
-#     "fr_ids": ["FR6", "FR7", "FR8", ...],
-#     "avg_score": 83.6,
-#     "dominant_blocker": "test_coverage",
-#     "top_recommendation_fr": "FR8"
-#   },
-#   "low_cluster": { ... }
-# }
-```
-
-**Interpretation**: A bimodal warning usually means *"the services that exist are healthy; the ones that are failing aren't built yet"* — your work is recipe-style scaffolding, not debugging the passing services. Use `dominant_blocker` to pick the next sprint focus and `top_recommendation_fr` as the starting FR.
-
-## Trend Regression Bucketing (Phase 4)
-
-When a previous run exists, the report bucketizes FR deltas vs baseline:
-
-| Δ score | Bucket | Render |
-|---------|--------|--------|
-| `Δ ≤ -15` | **Critical regression** | Loud callout + risk register entry |
-| `-15 < Δ ≤ -5` | Minor regression | Subtle callout |
-| `-5 < Δ < 5` | Noise floor | Ignored |
-| `5 ≤ Δ < 15` | Improvement | Noted |
-| `Δ ≥ 15` | Major improvement | Highlighted |
-
-Thresholds are intentionally simple for Phase 4. Phase 4.1 will upgrade to **Western Electric Rules** (3σ single-point, 2-of-3 at 2σ, 4-of-5 at 1σ) using rolling mean/stddev from `daily_scores`.
-
-## Troubleshooting
-
-| Problem | Solution |
-|---------|----------|
-| "no DSN provided" | Set `VDS_PROGRESS_STATE_DSN` in `~/.vds/.env` |
-| "bmad_ntbh not found" | Run `vds-cli audit sync repos --bitbucket-project INSURANCE-AI` |
-| Structlog lines in output | Use `-q` flag or redirect stderr (`2>/dev/null`) |
-| Score unchanged after code changes | Re-sync repos (remove `--skip-sync`) |
-| LLM not detected | Check `OPENAI_API_KEY` / `ANTHROPIC_AUTH_TOKEN` in `~/.vds/.env`, or use `--llm-provider none` |
-| CI shows exit 0 when score is low | Confirm `--fail-under <score>` flag is set — gates are opt-in |
-| `--fail-on-regression` not tripping | No baseline exists yet (first run) or baseline is outside the noise floor — pass `--baseline <run-id>` explicitly |
-| `bimodal_warning.detected: false` when I expected true | Check `total_frs ≥ 10`, `medium == 0`, dominance `≥ 0.25` — skewed distributions like 14/0/1 are rejected by design |
-| `--mode exec` output missing trend | Exec mode is deliberately ≤20 lines; use `--mode summary` for trend sparklines |
-| Standard mode output looks different | Should be byte-identical to Phase 3. File a bug if it's not — the G-Q11c structural invariants test guards this. |

package/tools/vds-scripts/docs/agents/how-to/08-semantic-search.md

@@ -1,46 +0,0 @@
-<!-- diátaxis: how-to -->
-
-# Semantic Search
-
-> Use semantic search to find code and documentation by meaning, not exact string.
-
-## Scope
-
-- **Does:** Search by concept, intent, and semantic meaning across code and docs.
-- **Does NOT:** Replace exact-string search (`rg`) when you know the symbol name.
-
-## CLI Entry
-
-```bash
-# Via unified router
-vds-cli research --help
-
-# Direct entry
-vds-cli research --help
-```
-
-## Key Commands
-
-| Command | Purpose |
-|---------|---------|
-| `search` | Semantic search |
-| `score` | Score evidence quality |
-
-## Workflow
-
-### Search by Meaning
-
-1. Run: `vds-cli research search "credential resolution pattern"`
-2. Review ranked results by relevance
-3. Filter by source: `--tool tavily`, `--tool grepai`
-
-```bash
-# Example: find how VDS handles retry
-grepai search "retry pattern with exponential backoff"
-```
-
-## Related
-
-- [Search Tools Reference](../reference/search-tools.md)
-- [Research Orchestrator](../reference/research-orchestrator.md)
-- [Memory Orchestrator](../reference/memory-orchestrator.md)

package/tools/vds-scripts/docs/agents/how-to/apply-phase3-migration.md

@@ -1,148 +0,0 @@
-<!-- diátaxis: how-to -->
-
-# How to apply the Phase 3 alembic migration
-
-> Operator runbook to bring the live `sched.ecosystem_report_runs` schema into
-> alignment with the Phase 3 collector code merged at `412b067b`.
-
-**Time budget**: ≤ 10 minutes. **Risk**: low (additive migration; reversible).
-
-## Why
-
-Phase 3 of the ecosystem-daily-report (`edr-phase3/intelligent-watchdog`,
-merged at `412b067bcbb44c466cf62f5f62a11d0888090848` on 2026-04-30) added
-five new collectors and a Slack delivery step. Their results are persisted
-to **new columns** on `sched.ecosystem_report_runs`:
-
-- `llm_summary` (JSONB) — LLM provider/model token totals + USD cost
-- `dora_summary` (JSONB) — deploy frequency, lead time, CFR, time-to-restore
-- `trend_summary` (JSONB) — z-scores + sparklines + trend directions
-- `security_summary` (JSONB) — placeholder for SecurityAdvisoryCollector
-- `slack_delivered` (boolean), `slack_delivered_at` (timestamptz)
-
-Plus a new table `sched.ecosystem_report_archive` with a GIN-indexed
-`full_report` JSONB column for historical search.
-
-The migration file shipped at `412b067b` (revision `b2c3d4e5f8a9`,
-down-revision `a1b2c3d4e5f8`) but the live database still points at
-the Phase 2 head. **Until you run `alembic upgrade head`**, the cron
-that fires at 06:00 UTC will hand the SQLAlchemy model rows containing
-the Phase 3 columns to a database that does not have those columns,
-which leads to either persistence failure or silent loss of Phase 3 data
-depending on driver behavior.
-
-## When
-
-After the Phase 3 merge has landed on master (verify with
-`git log --oneline 412b067b -1`) and **before** you rely on persisted
-Phase 3 reports — i.e. before the next 06:00 UTC cron fire, or before
-the next manual `vds-cli scheduler schedules trigger-now ecosystem-daily-report`.
-
-## Prerequisites
-
-- `~/.vds/.env` populated (Postgres DSN, `VDS_SCHEDULER_ENABLED=true`).
-- Working tree at master `412b067b` or later.
-- Postgres 16 healthy (`docker ps | grep postgres` shows the
-  `vds-postgres` container with status `healthy`).
-
-## Steps
-
-### 1. Apply the migration
-
-```bash
-cd WHO-project/vds-scripts
-./scripts/worktree_uv.sh run --project scheduler_orchestrator alembic upgrade head
-```
-
-Expected output:
-
-```
-INFO  [alembic.runtime.migration] Running upgrade a1b2c3d4e5f8 -> b2c3d4e5f8a9, add_phase3_report_columns
-```
-
-### 2. Verify the scheduler service is running
-
-```bash
-docker ps | grep scheduler                      # vds-scheduler container healthy
-vds-cli scheduler schedules show ecosystem-daily-report
-```
-
-The schedule should be listed with status `active` (not `paused`) and a
-`next_run` timestamp set to the next 06:00 UTC. If `Status: paused`, run
-`vds-cli scheduler schedules resume ecosystem-daily-report`.
-
-### 3. Trigger one workflow run for verification
-
-Don't wait for 06:00 UTC; force one fire so you can confirm the new
-schema is being written through:
-
-```bash
-vds-cli scheduler schedules trigger-now ecosystem-daily-report
-```
-
-Then check the workflow result:
-
-```bash
-vds-cli scheduler workflows list --status SUCCESS --limit 1
-```
-
-A new `reports/ecosystem/<today>-ecosystem-report.md` file should also
-appear in the worktree.
-
-### 4. Confirm the new row populates Phase 3 columns
-
-```bash
-vds-cli ecosystem report history --days 1
-```
-
-The latest row should show non-NULL `dora_summary`, `trend_summary`,
-`llm_summary`, `slack_delivered`, `slack_delivered_at`. NULL or
-`[unavailable]` payloads are *also* acceptable — what matters is that
-the cron successfully wrote through the migrated schema rather than
-crashing on `column does not exist`.
-
-> Caveat: `llm_summary` will report `[unavailable]` until the Phase 4
-> producer-wiring task lands (see the spec's "Phase 4 Followup — JSONL
-> Producer Wiring" note). This is graceful degradation per AC-P3.9, not
-> a regression.
-
-## Verification
-
-You will know the migration worked when:
-
-- `alembic current` shows `b2c3d4e5f8a9 (head)`.
-- `psql ... -c "\d sched.ecosystem_report_runs"` lists the six new
-  columns above.
-- `psql ... -c "\d sched.ecosystem_report_archive"` shows the new
-  archive table with a GIN index on `full_report`.
-- A fresh row from `vds-cli ecosystem report history --days 1` is
-  written without error after step 3.
-
-## Rollback
-
-If you need to revert (for example, a downstream consumer is not yet
-ready for the new columns):
-
-```bash
-# 1. Pause the schedule so the next cron does not crash on the
-#    pre-Phase-3 schema.
-vds-cli scheduler schedules pause ecosystem-daily-report
-
-# 2. Downgrade.
-cd WHO-project/vds-scripts
-./scripts/worktree_uv.sh run --project scheduler_orchestrator alembic downgrade -1
-```
-
-`alembic downgrade -1` reverts to `a1b2c3d4e5f8` (Phase 2 head), drops
-the six Phase 3 columns and the `ecosystem_report_archive` table.
-**Do not resume the schedule** until either you re-apply the migration
-or you check out a pre-`412b067b` master tip whose model code matches
-the Phase 2 schema.
-
-## See also
-
-- Spec post-merge runbook: `.gpt-5.4/specs/ecosystem-daily-report/tasks.md`
-  → "Post-Merge Operator Runbook"
-- DORA bootstrap criterion: `.gpt-5.4/specs/ecosystem-daily-report/design.md`
-  → "Bootstrap criterion (verdict locked 2026-04-30, Lane Alpha)"
-- Existing daily-report runbook: `docs/agents/how-to/run-ecosystem-daily-report.md`