@ngocsangairvds/vsaf 4.1.9 → 4.1.11

package/skills/vds-skill/runtime/docs/agents/reference/diagrams-orchestrator.md

@@ -0,0 +1,52 @@
+<!-- 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/skills/vds-skill/runtime/docs/agents/reference/ecosystem-daily-report.md

@@ -0,0 +1,229 @@
+<!-- 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/skills/vds-skill/runtime/docs/agents/reference/elastic-orchestrator.md

@@ -0,0 +1,57 @@
+<!-- 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/skills/vds-skill/runtime/docs/agents/reference/env-git-helper.md

@@ -0,0 +1,216 @@
+<!-- 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/skills/vds-skill/runtime/docs/agents/reference/evolution-orchestrator.md

@@ -0,0 +1,113 @@
+<!-- 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)