@ngocsangairvds/vsaf 3.2.16 → 4.0.0

package/tools/vds-scripts/docs/agents/reference/diagrams-orchestrator.md

@@ -1,52 +0,0 @@
-<!-- diátaxis: reference -->
-
-# Diagrams Orchestrator
-
-> Generate C4, sequence, component, use case, and mermaid diagrams from code or DSL.
-
-## Scope
-
-- **Does:** Generate C4 context/container/component/code diagrams, sequence diagrams, use case diagrams, and render mermaid from markdown or DSL.
-- **Does NOT:** Create artistic diagrams, replace dedicated diagramming tools like draw.io.
-- **Primary users:** AI agents (architecture documentation), developers (design docs).
-
-## CLI Entry
-
-```bash
-# Via unified router
-vds-cli diagrams --help
-
-# Direct entry
-vds-cli diagrams --help
-```
-
-## Key Commands
-
-| Command | Purpose | Common Flags |
-|---------|---------|-------------|
-| `c4` | Generate C4 diagram | `--level`, `--output` |
-| `sequence` | Generate sequence diagram | `--participants`, `--output` |
-| `component` | Generate component diagram | `--scope`, `--output` |
-| `usecase` | Generate use case diagram | `--actors`, `--output` |
-| `mermaid` | Render mermaid from file | `--input`, `--output` |
-
-## Common Workflows
-
-### Workflow: Generate C4 Architecture Diagram
-
-1. Define components in a DSL or markdown file
-2. Run `vds-cli diagrams c4 --level container --input architecture.md --output c4-container.png`
-3. Review generated diagram
-4. Include in Confluence or documentation
-
-### Workflow: Render Mermaid from Markdown
-
-1. Write mermaid syntax in a markdown file: ````mermaid graph TD; A-->B;````
-2. Run `vds-cli diagrams mermaid --input doc.md --output diagram.svg`
-3. Embed SVG in documentation
-
-## Related
-
-- **Orchestrators:** [schema](schema-orchestrator.md), [structure](structure-orchestrator.md), [pdf](pdf-orchestrator.md)
-- **Skills:** [cli-development-skill](../../../../vds-skills/skills/cli-development-skill/SKILL.md)
-- **Confluence:** [WHO Diagrams](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation)

package/tools/vds-scripts/docs/agents/reference/ecosystem-daily-report.md

@@ -1,229 +0,0 @@
-<!-- diátaxis: reference -->
-
-# Ecosystem Daily Report
-
-> Automated daily health collation for the VDS ecosystem (DBOS cron + adaptive reporting).
-
-**Summary**
-Runs at 06:00 UTC via DBOS cron, executes 10 parallel collectors, aggregates Golden Signals into a 0-100 health score, and emits Markdown + DB + events.
-
-## Table of Contents
-
-1. [Quick Reference](#quick-reference)
-2. [Architecture](#architecture)
-3. [Collector Inventory](#collector-inventory)
-4. [Configuration](#configuration)
-5. [Report Output](#report-output)
-6. [Health Score](#health-score)
-7. [Phase 3 Status](#phase-3-status)
-
-## Quick Reference
-
-| Item | Value |
-|------|-------|
-| Alias | `ecosystem.daily.report` |
-| Schedule | `ecosystem-daily-report` |
-| Cron | `0 6 * * *` (06:00 UTC) |
-| Queue | `ops-default` |
-| Output path | `reports/ecosystem/YYYY-MM-DD-ecosystem-report.md` |
-| DB table | `sched.ecosystem_report_runs` |
-| Events | `ecosystem.daily.completed`, `ecosystem.daily.failed` |
-| Config prefix | `VDS_ECOSYSTEM_DAILY__` |
-| Report modes | `auto` (default), `exec`, `summary`, `full` |
-| Collector timeout | 10 s (default) |
-
-## Architecture
-
-```mermaid
-flowchart TB
-  Cron["DBOS Cron 06:00 UTC"] --> Queue["ops-default Queue"]
-  Queue --> Workflow["Ecosystem Report Workflow"]
-  Workflow --> Registry["Collector Registry\n(10 active + 1 deferred)"]
-  Registry --> C1["GitActivityCollector"]
-  Registry --> C2["SchedulerStatusCollector"]
-  Registry --> C3["EventBusCollector"]
-  Registry --> C4["QueueMetricsCollector"]
-  Registry --> C5["PrometheusCollector"]
-  Registry --> C6["InfraHealthCollector"]
-  Registry --> C7["TestSuiteCollector"]
-  Registry --> C8["WorktreeHygieneCollector"]
-  Registry --> C9["SpecPhaseCollector"]
-  Registry --> C10["MemoryHealthCollector"]
-  C1 & C2 & C3 & C4 & C5 & C6 & C7 & C8 & C9 & C10 --> Aggregator["Golden Signals Aggregator"]
-  Aggregator --> Formatter["Report Formatter\n(auto / exec / summary / full)"]
-  Formatter --> Markdown["reports/ecosystem/\nYYYY-MM-DD-ecosystem-report.md"]
-  Formatter --> DB[("sched.ecosystem_report_runs")]
-  Formatter --> Events["ecosystem.daily.completed\necosystem.daily.failed"]
-```
-
-**ASCII overview:**
-```
-  Cron (06:00 UTC) --> ops-default Queue --> Ecosystem Report Workflow
-      |
-      +--> Collector Registry (parallel execution)
-      |     +-- GitActivityCollector       (Tier 1)
-      |     +-- SchedulerStatusCollector  (Tier 1)
-      |     +-- EventBusCollector         (Tier 1)
-      |     +-- QueueMetricsCollector     (Tier 1)
-      |     +-- PrometheusCollector       (Tier 1)
-      |     +-- InfraHealthCollector      (Tier 1)
-      |     +-- TestSuiteCollector        (Tier 2)
-      |     +-- WorktreeHygieneCollector  (Tier 2)
-      |     +-- SpecPhaseCollector        (Tier 2)
-      |     +-- MemoryHealthCollector     (Tier 3)
-      |
-      +--> Golden Signals Aggregator
-              |
-              +--> Report Formatter
-                      +--> Markdown report file
-                      +--> DB table  (sched.ecosystem_report_runs)
-                      +--> Events      (completed / failed)
-```
-
-**Key design points:**
-
-- **Pluggable collector protocol** — each collector implements `EcosystemCollector` with an async `collect()` returning `CollectorResult`.
-- **Parallel execution** — total runtime is bounded by the slowest collector, not the sum of timeouts.
-- **Graceful degradation** — a single collector failure (timeout, exception, connection refused) produces an `[unavailable]` placeholder; the report never crashes due to one collector.
-- **Adaptive reporting** — `auto` mode dispatches the report verbosity based on the computed health score.
-
-## Collector Inventory
-
-All collectors implement the `EcosystemCollector` protocol. Ten are active; one is deferred to Phase 3.
-
-| # | Collector | Tier | Purpose | Source | Weight in health score |
-|---|-----------|------|---------|--------|------------------------|
-| 1 | `GitActivityCollector` | 1 | Git activity across repos | Local `.git/` repos | delivery |
-| 2 | `SchedulerStatusCollector` | 1 | Schedule + workflow health | `sched.schedules`, `sched.workflow_registry`, `sched.chain_definitions` | runtime |
-| 3 | `EventBusCollector` | 1 | Event outbox + subscription depth | `sched.events_outbox`, `sched.subscriptions` | events |
-| 4 | `QueueMetricsCollector` | 1 | Queue depth + DBOS status | `dbos.workflow_status` | runtime |
-| 5 | `PrometheusCollector` | 1 | SLO / SLI from metrics endpoint | `http://localhost:8005/metrics` | observability |
-| 6 | `InfraHealthCollector` | 1 | Docker + Postgres + Redis health | Docker, `pg_stat_*`, `redis-cli INFO` | infrastructure |
-| 7 | `TestSuiteCollector` | 2 | Latest test outcomes | `.pytest_cache/` | knowledge |
-| 8 | `WorktreeHygieneCollector` | 2 | Stale worktree + disk usage | `git worktree list`, `du` | delivery |
-| 9 | `SpecPhaseCollector` | 2 | Spec coverage + phase alignment | `.gpt-5.4/specs/` YAML frontmatter | knowledge |
-| 10 | `MemoryHealthCollector` | 3 | Memory service liveness | `http://localhost:8010/health` | knowledge |
-| 11 | `LLMUsageCollector` | 3 | LLM token / cost usage | Serialized JSONL logs from `logs/ecosystem/` | knowledge |
-| 12 | `TrendForecastCollector` | 3 | Health trend forecasting | Computes trend direction + trend classification | knowledge |
-
-**Scoring weights:** runtime 25%, infrastructure 20%, observability 15%, events 15%, delivery 15%, knowledge 10%.
-
-## Configuration
-
-Environment variables use the prefix `VDS_ECOSYSTEM_DAILY__`.
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `VDS_ECOSYSTEM_DAILY__COLLECTOR_TIMEOUT_S` | `10` | Per-collector timeout (seconds) |
-| `VDS_ECOSYSTEM_DAILY__DISABLED_COLLECTORS` | `[]` | JSON list of section names to skip, e.g. `["Prometheus/SLO", "Memory"]` |
-| `VDS_ECOSYSTEM_DAILY__REPORT_MODE` | `auto` | Force a mode: `auto`, `exec`, `summary`, `full` |
-| `VDS_ECOSYSTEM_DAILY__ERROR_THRESHOLD` | `10` | Anomaly threshold for 24h workflow errors |
-| `VDS_ECOSYSTEM_DAILY__PENDING_THRESHOLD` | `100` | Anomaly threshold for pending queue depth |
-| `VDS_ECOSYSTEM_DAILY__COMMIT_THRESHOLD` | `50` | Anomaly threshold for daily commit count |
-| `VDS_ECOSYSTEM_DAILY__ZERO_OUTBOX_ALERT` | `true` | Emit anomaly when outbox is empty |
-| `VDS_ECOSYSTEM_DAILY__DOCKER_SOCKET` | `/var/run/docker.sock` | Docker socket path for InfraHealth collector |
-| `VDS_ECOSYSTEM_DAILY__REDIS_HOST` | `localhost` | Redis host for InfraHealth collector |
-| `VDS_ECOSYSTEM_DAILY__REDIS_PORT` | `6379` | Redis port for InfraHealth collector |
-
-## Report Output
-
-**Markdown file**
-Path: `reports/ecosystem/YYYY-MM-DD-ecosystem-report.md`
-
-**Database row**
-Table: `sched.ecosystem_report_runs`
-Key columns:
-- `id` (text PK, UUID)
-- `report_date` (date, unique)
-- `generated_at` (timestamptz)
-- `health_score` (integer, 0-100)
-- `golden_signals` (JSONB)
-- `generation_duration_ms` (integer)
-- `exec_text`, `summary_text` (text, nullable)
-
-**Events**
-- `ecosystem.daily.completed` — emitted on success
-- `ecosystem.daily.failed` — emitted on failure
-
-## Health Score
-
-- **Range:** 0-100
-- **Scoring:** six weighted components start at 100, each receives collector-provided deductions; floor at 0, ceiling at 100.
-- **Trend:** `up`, `down`, or `flat` vs previous day's persisted score.
-
-| Range | Emoji | Meaning |
-|-------|-------|---------|
-| 85-100 | 🟢 | Healthy — all systems nominal |
-| 60-84 | 🟡 | Degraded — attention needed |
-| 0-59 | 🔴 | Critical — immediate triage required |
-
-**Health-based auto mode dispatch:**
-
-| Condition | Auto mode selected | Approximate length |
-|-----------|-------------------|--------------------|
-| Health ≥ 85, 0 anomalies | `exec` | 6-8 lines |
-| Health ≥ 85, 1+ anomalies | `exec+anomalies` | 10-14 lines |
-| Health 60-84 | `summary` | 14-18 lines |
-| Health < 60 | `full+triage` | 18-20+ lines |
-
-## Phase 3 Status
-
-**Phase 3 is in-progress (edr-phase3/intelligent-watchdog branch, 6 commits landed).**
-
-Phase 3 delivers five capability waves atop Phase 2 infrastructure:
-
-### Wave 0 — Foundation (Wave 0.1, 0.2, 0.3)
-- **Wave 0.1**: vds-cli ecosystem dashboard CLI entry point + Wave 3 Slack delivery
-- **Wave 0.2**: JSONL exporter for LLM usage spans (structured logs to `logs/ecosystem/llm_usage_<date>.jsonl`)
-- **Wave 0.3**: llm_pricing.yaml configuration for cost calculation
-
-### Wave 1 — Slack Notification Delivery (TSK-P3-1.1..1.5)
-- Slack webhook integration for ecosystem report publication
-- Configurable notification timings and formatting
-- Event-driven delivery on `ecosystem.daily.completed`
-
-### Wave 2 — Trend Forecasting (TSK-P3-2.1..2.5)
-- TrendForecastCollector implementation
-- Trend direction computation (up/down/flat vs previous day)
-- Sparkline ASCII rendering for historical display
-- Critical bucket detection at 15% decline threshold
-
-### Wave 3 — CLI Dashboard (Wave 0.1 + Wave 3, TSK-P3-3)
-- `vds-cli ecosystem dashboard` command for on-demand report generation
-- Integration with vds-cli routing contract
-- Support for all report modes (auto, exec, summary, full)
-
-### Wave 4 — LLM Usage Tracking (TSK-P3-4.2..4.5)
-- LLMUsageCollector implementation
-- Ingests JSONL logs from `logs/ecosystem/llm_usage_*.jsonl`
-- Computes token counts, cost estimates (via llm_pricing.yaml)
-- Populates `llm_summary` column in `sched.ecosystem_report_runs`
-
-**Test coverage:** 99 new unit + integration tests (scheduler_orchestrator + vds_cli ecosystem suite). Full unit suite: 1,283 passing, 0 failing, 108+ ecosystem tests.
-
-**Wave 5 (Security + DORA) and Wave 6 (Alembic + Integration)** pending in follow-up lanes.
-
-## Example Invocations
-
-**Manual trigger (operator CLI):**
-```bash
-vds-cli scheduler schedules trigger-now ecosystem-daily-report
-```
-
-**Generate a local report on-demand:**
-```bash
-./scripts/worktree_uv.sh run --project scheduler_orchestrator \
-  python scheduler_orchestrator/scripts/generate-report.py --mode full
-```
-
-**Diagnose a specific collector:**
-```bash
-./scripts/worktree_uv.sh run --project scheduler_orchestrator \
-  python scheduler_orchestrator/scripts/collector-diagnostics.py "Prometheus"
-```
-
-**CI verification (all Phase 2 tests + collectors):**
-```bash
-./scripts/worktree_uv.sh run --project scheduler_orchestrator \
-  bash scheduler_orchestrator/scripts/verify-phase2.sh
-```

package/tools/vds-scripts/docs/agents/reference/elastic-orchestrator.md

@@ -1,57 +0,0 @@
-<!-- diátaxis: reference -->
-
-# Elasticsearch Orchestrator
-
-> Elasticsearch operations via Kibana proxy — query indices, inspect mappings, run aggregations.
-
-## Scope
-
-- **Does:** Query ES indices, inspect mappings, run aggregations, export results, and manage index aliases.
-- **Does NOT:** Manage cluster topology, replace Kibana UI, or handle index lifecycle policies.
-- **Primary users:** AI agents (log analysis), operators (metric queries), SRE (incident response).
-
-## CLI Entry
-
-```bash
-# Via unified router
-vds-cli elastic --help
-
-# Direct entry
-vds-cli elastic --help
-```
-
-## Key Commands
-
-| Command | Purpose | Common Flags |
-|---------|---------|-------------|
-| `query` | Run ES query | `--index`, `--query`, `--format` |
-| `mapping` | Inspect index mapping | `--index` |
-| `aggregate` | Run aggregation | `--index`, `--agg` |
-| `alias` | Manage index aliases | `--action`, `--alias` |
-
-## Common Workflows
-
-### Workflow: Query Application Logs
-
-1. Run `vds-cli elastic query --index app-logs-* --query '{"match": {"level": "ERROR"}}'`
-2. Filter by time range: add `--from 2026-04-01 --to 2026-04-22`
-3. Export results: `--format json --output errors.json`
-
-### Workflow: Inspect Index Mapping
-
-1. Run `vds-cli elastic mapping --index my-index`
-2. Review field types and analyzers
-3. Compare with expected schema
-
-## Related
-
-- **Orchestrators:** [grafana](grafana-orchestrator.md), [db-query](db-query-orchestrator.md), [metabase](metabase-orchestrator.md)
-- **Confluence:** [WHO Elastic](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation)
-
-## Troubleshooting
-
-| Issue | Cause | Resolution |
-|-------|-------|------------|
-| Command not found | Orchestrator not installed | Run `uv sync --all-packages` |
-| Config missing | `~/.vds/.env` unset | Add required credentials per [AGENTS.md](../../../AGENTS.md) |
-| Permission denied | Insufficient privileges | Check Bitbucket/Confluence token scope |

package/tools/vds-scripts/docs/agents/reference/env-git-helper.md

@@ -1,216 +0,0 @@
-<!-- diátaxis: reference -->
-
-# Env Git Helper Reference
-
-> Canonical git credential helper (`git-credential-vds`) — install, verify, lifecycle.
-
-## Summary
-
-| Property | Value |
-|----------|-------|
-| Binary name | `git-credential-vds` |
-| Install path | `~/.vds/bin/git-credential-vds` |
-| State file | `~/.vds/.git-credential-helper-cooldown.json` |
-| Legacy state | `~/.vds/.git_helper_state.json` |
-| Source module | `vds_cli.env_git_helper` |
-| Asset source | `vds_cli/assets/git-credential-helper.py` |
-
-## Table of Contents
-
-- [Quick Reference](#quick-reference)
-- [Installation](#installation)
-- [Verification](#verification)
-- [Removal](#removal)
-- [Status](#status)
-- [State Management](#state-management)
-- [Environment](#environment)
-- [Security](#security)
-- [Troubleshooting](#troubleshooting)
-- [Spec References](#spec-references)
-
-## Quick Reference
-
-| Command | Purpose | Example |
-|---------|---------|---------|
-| `vds-cli env install-git-helper` | Install canonical helper and clean legacy artifacts | `vds-cli env install-git-helper` |
-| `vds-cli env install-git-helper --force` | Force install, bypass signature check | `vds-cli env install-git-helper --force` |
-| `vds-cli env verify-git-helper` | Verify installed state and git config | `vds-cli env verify-git-helper` |
-| `vds-cli env verify-git-helper --reset-cooldown` | Verify and clear cooldown state | `vds-cli env verify-git-helper --reset-cooldown` |
-| `vds-cli env remove-git-helper` | Uninstall helper and unset git config | `vds-cli env remove-git-helper` |
-| `vds-cli env remove-git-helper --purge` | Uninstall and delete cooldown state file | `vds-cli env remove-git-helper --purge` |
-| `vds-cli env status` | Show env and helper status | `vds-cli env status` |
-| `vds-cli env load` | Load shared VDS environment from `~/.vds/.env` | `vds-cli env load` |
-| `vds-cli doctor` | Full diagnostic including helper status | `vds-cli doctor` |
-
-## Installation
-
-```bash
-vds-cli env install-git-helper
-```
-
-Installs the canonical git credential helper from the bundled asset
-`vds_cli/assets/git-credential-helper.py`.
-
-**Actions performed:**
-
-1. Creates `~/.vds/bin/` with mode `0o700` (AC-23.7).
-2. Writes the helper to `~/.vds/bin/git-credential-vds` with mode `0o700` (AC-23.7).
-3. Runs `git config --global credential.helper <absolute-path>` with `shell=False` (AC-23.8).
-4. Removes legacy pre-FR-24 artifacts after signature verification (AC-24.4 / AC-24.6).
-5. Migrates legacy state file if present and the new path is free (AC-24.5).
-6. Runs a self-probe: simulates an allowlist-miss `get` request and expects exit `0` with no output (AC-23.2(d)).
-
-**Flags:**
-
-- `--force`: Override the AC-24.6 signature check and remove legacy artifacts unconditionally.
-
-**Result fields:**
-
-| Field | Meaning |
-|-------|---------|
-| `target` | Path to installed binary |
-| `removed` | Legacy artifacts deleted |
-| `preserved` | Legacy artifacts kept (signature mismatch) |
-| `migrated_state` | New state file path if migration occurred |
-| `probe_ok` | Self-probe passed |
-
-## Verification
-
-```bash
-vds-cli env verify-git-helper
-```
-
-Returns exit code `0` if all checks pass, `1` otherwise.
-
-**Checks performed:**
-
-| Check | Detail |
-|-------|--------|
-| Helper file | `~/.vds/bin/git-credential-vds` exists |
-| Executable | Mode has `+x` bits (verified via `st_mode & 0o111`) |
-| Git config | `credential.helper` is set to the installed absolute path or ends with `git-credential-vds` |
-| Cooldown reset | Only when `--reset-cooldown` is passed |
-
-**Flags:**
-
-- `--reset-cooldown`: Truncate the cooldown state file to `{"failures": [], "cooldown_until": 0}` and set mode `0o600`.
-
-## Removal
-
-```bash
-vds-cli env remove-git-helper
-```
-
-Idempotent — safe when nothing is installed (AC-23.4).
-
-**Actions performed:**
-
-1. Deletes `~/.vds/bin/git-credential-vds` if it exists.
-2. Unsets `git config --global credential.helper` (best-effort, no failure on missing config).
-3. With `--purge`, also deletes the cooldown state file.
-
-**Flags:**
-
-- `--purge`: Also delete `~/.vds/.git-credential-helper-cooldown.json`.
-
-**Result fields:**
-
-| Field | Meaning |
-|-------|---------|
-| `deleted_binary` | Binary was present and removed |
-| `deleted_state` | State file was present and removed (only with `--purge`) |
-
-## Status
-
-There is no dedicated CLI subcommand for helper status. The helper state is surfaced through:
-
-- `vds-cli env status` — shows "Git credential helper: ✅ Installed" or missing/broken.
-- `vds-cli doctor` — includes helper status in the diagnostic table.
-
-**States:**
-
-| State | Meaning | Remediation |
-|-------|---------|-------------|
-| `installed` | Binary exists and is executable | None |
-| `missing` | Binary not found | Run `vds-cli env install-git-helper` |
-| `broken` | Binary exists but lacks executable bits | Re-run `vds-cli env install-git-helper` to repair mode |
-
-## State Management
-
-**Current state file:** `~/.vds/.git-credential-helper-cooldown.json`
-
-The helper itself (not the installer) reads and writes this file to implement cooldown/lockout prevention (FR-21). The file is human-inspectable JSON with keys `failures` and `cooldown_until`. Mode is `0o600`.
-
-**Legacy migration (AC-24.5):**
-
-- Legacy path: `~/.vds/.git_helper_state.json`
-- Migration occurs during `install()` only if the new path does not already exist.
-- If the new path already exists, the legacy file is deleted (best-effort) and migration is skipped.
-
-**Legacy artifact cleanup (AC-24.4 / AC-24.6):**
-
-During install, the following pre-FR-24 artifacts are inspected and removed if their content matches the signature (`VDS_USERNAME` and `def cmd_get`):
-
-- `~/.vds/git_credential_helper.py`
-- `~/.vds/git_credential_helper.py.bak`
-- `/tmp/git_credential_helper_v2.py`
-
-Files that do not match the signature are preserved with a warning unless `--force` is used.
-
-## Environment
-
-| Variable / Constant | Default | Purpose |
-|---------------------|---------|---------|
-| `VDS_DIR` | `.vds` | Directory name under `$HOME` for VDS state |
-| `INSTALLED_BINARY_NAME` | `git-credential-vds` | Name of the installed binary |
-| `SIGNATURE_MARKERS` | `("VDS_USERNAME", "def cmd_get")` | Markers for legacy content verification |
-
-The installer uses these module-level mode constants:
-
-- `INSTALLED_MODE = 0o700`
-- `DIR_MODE = 0o700`
-- `STATE_MODE = 0o600`
-
-## Security
-
-| AC | Requirement | Implementation |
-|----|-------------|----------------|
-| AC-23.2(a) | Bundle canonical helper from asset | `resources.files("vds_cli").joinpath("assets/git-credential-helper.py")` |
-| AC-23.2(d) | Self-probe on install | Allowlist-miss `get` → expects exit `0` and empty stdout |
-| AC-23.7 | File modes | Binary `0o700`, parent dir `0o700`, state file `0o600` |
-| AC-23.8 | Subprocess safety | All `subprocess.run` calls use `shell=False` with list args |
-| AC-24.4 | Legacy artifact cleanup | Installer removes known pre-FR-24 filenames after signature check |
-| AC-24.5 | State migration | Legacy `~/.vds/.git_helper_state.json` → new cooldown JSON path |
-| AC-24.6 | Signature check | Legacy files are preserved if they do not contain both `VDS_USERNAME` and `def cmd_get` |
-
-Additional runtime security properties of the helper asset itself:
-
-- AC-20.5: Emits ONLY `username=` and `password=` lines to stdout; no stderr except the AC-21.6 cooldown countdown carve-out.
-- AC-21.7: State file is written with mode `0o600`.
-- AC-25.1: The helper uses stdlib-only imports so it can run when git invokes it outside the vds-scripts venv.
-
-## Troubleshooting
-
-**Install fails with permission error**
-→ Check that `$HOME` is writable and that `~/.vds` is not owned by root.
-
-**Verify fails on "Executable"**
-→ The binary may have lost its mode bits. Re-run `vds-cli env install-git-helper`.
-
-**Verify fails on "Git config"**
-→ The `credential.helper` global config may point to a different path. Run install again or manually run `git config --global credential.helper ~/.vds/bin/git-credential-vds`.
-
-**Self-probe fails during install**
-→ The probe simulates an allowlist-miss (host not in `bitbucket.digital.vn` allowlist) and expects exit `0` with no output. If it fails, check that the binary was written correctly and is executable.
-
-**Legacy state not migrated**
-→ Migration only runs if the new state file `~/.vds/.git-credential-helper-cooldown.json` does not already exist. If it exists, the legacy file is deleted instead.
-
-**Binary not invoked by git**
-→ Ensure `git config --global credential.helper` points to the absolute path of `~/.vds/bin/git-credential-vds`. The installer sets this automatically.
-
-## Spec References
-
-- who-ecosystem-alignment Phase 5 v0.7.0 — FR-23 (env lifecycle), FR-24 (single canonical artifact), FR-25 (logic non-overlap policy)
-- FR-20 / FR-21: Host-filtered emission and lockout-prevention cooldown state file (implemented in the helper asset)
-- TSK-5.27: Lifecycle test coverage in `vds_cli/tests/test_env_git_helper_lifecycle.py`

package/tools/vds-scripts/docs/agents/reference/evolution-orchestrator.md

@@ -1,113 +0,0 @@
-<!-- diátaxis: reference -->
-
-# Evolution Orchestrator
-
-> WHO ecosystem evolution loop — manage skill evolution through three-gate pipeline, verdict tracking, and automatic promotion.
-
-## Scope
-
-- **Does:** Route skills through gates, track verdicts, auto-promote approved changes, sign/verify HMAC integrity.
-- **Does NOT:** Make autonomous decisions without kill-switch approval, replace code review.
-- **Primary users:** AI agents (skill maintenance), human leads (approval), release managers.
-
-## CLI Entry
-
-```bash
-# Evolution Loop CLI
-vds-cli evolution --help
-```
-
-## Key Commands
-
-| Command | Purpose |
-|---------|---------|
-| `status` | Show kill-switch state, queue depth, recent verdicts |
-| `list` | List all verdicts (pending, promoted, rejected) |
-| `show VERDICT_ID` | Show detailed verdict |
-| `route SKILL.md` | Route skill through Gate 1→2→3 pipeline |
-| `promote VERDICT_ID` | Promote eligible verdict to master |
-| `reject VERDICT_ID` | Reject verdict |
-| `escalate VERDICT_ID` | Escalate for human review |
-| `sign-verdict PATH` | HMAC sign verdict |
-| `verify-verdict PATH` | Verify HMAC signature |
-| `ensemble-judge SKILL` | Three-judge evaluation |
-| `openspace-doctor` | Readiness checks |
-| `openspace-sync-shadow` | Sync canonical→shadow skills |
-
-## Kill Switch
-
-Controls autonomous mode:
-
-| Mode | Env Var | Behavior |
-|------|---------|----------|
-| MANUAL | `OPENSPACE_AUTONOMOUS_ENABLED=false` | Human controls all |
-| AUTO | `OPENSPACE_AUTONOMOUS_ENABLED=true` | Daemon auto-promotes |
-
-## Three-Gate Pipeline
-
-```
-ExecutionAnalysis
-       │
-       ▼
-┌──────────────┐
-│ Gate 1       │ → Structural (queue, budget)
-└──────────────┘
-       │
-       ▼
-┌──────────────┐
-│ Gate 2       │ → Behavioral (regression)
-└──────────────┘
-       │
-       ▼
-┌──────────────┐
-│ Gate 3       │ → Semantic (Claude quality)
-└──────────────┘
-       │
-       ▼
-   Verdict
-```
-
-## Common Workflows
-
-### Workflow: Route a Skill (Manual)
-
-```bash
-# Route skill through pipeline
-vds-cli evolution route path/to/skill.md
-
-# Check verdict
-vds-cli evolution list
-vds-cli evolution show VERDICT_ID
-
-# Promote if eligible
-vds-cli evolution promote VERDICT_ID
-```
-
-### Workflow: Enable Auto-Promote
-
-```bash
-# Set kill switch to AUTO
-export OPENSPACE_AUTONOMOUS_ENABLED=true
-
-# Run daemon
-./scripts/install-evolution-auto.sh
-```
-
-### Workflow: Verify System Health
-
-```bash
-# Check status
-vds-cli evolution status
-
-# Run diagnostics
-vds-cli evolution openspace-doctor
-
-# Sync skills
-vds-cli evolution openspace-sync-shadow
-```
-
-## Related
-
-- **Spec:** [.gpt-5.4/specs/who-ecosystem-evolution-loop/SPEC.md](../../.gpt-5.4/specs/who-ecosystem-evolution-loop/SPEC.md)
-- **Deep Integration:** [docs/evolution-loop-deep-integration.md](../../docs/evolution-loop-deep-integration.md)
-- **Rollout Guide:** [docs/evolution-auto-run-rollout.md](../../docs/evolution-auto-run-rollout.md)