@ngocsangairvds/vsaf 4.0.6 → 4.0.7

package/skills/vds-skill/vds-scripts/docs/README.md

@@ -0,0 +1,235 @@
+# VDS Scripts Documentation
+
+Centralized reference for the Python orchestration stack (git/jira/confluence/bitbucket/vds_cli/mcp_server, markdown tools, docker). Use this single README for all operational guidance.
+
+---
+
+## 1. Quick Start
+
+For the canonical human + AI-agent install/bootstrap workflow, start with `docs/agents/how-to/install-and-bootstrap-who-scripts-and-skills.md`.
+Use the steps below as the scripts-workspace quick start after that canonical bootstrap path is understood.
+
+1. **Install uv**
+   ```bash
+   curl -LsSf https://astral.sh/uv/install.sh | sh
+   ```
+2. **Bootstrap all projects**
+   ```bash
+   cd vds-scripts
+   ./scripts/bootstrap_uv.sh --frozen
+   ```
+3. **Verify credentials + health**
+   ```bash
+   ./scripts/worktree_uv.sh run --project vds_cli vds-cli env status
+   ./scripts/worktree_uv.sh run --project vds_cli vds-cli status
+   ./scripts/worktree_uv.sh run --project vds_cli vds-cli doctor
+   ```
+   If `vds-cli` fails with `ModuleNotFoundError: vds_cli`, run:
+   ```bash
+   uv --project vds_cli sync --no-editable
+   ```
+4. **Sample operations**
+   ```bash
+   ./scripts/worktree_uv.sh run --project vds_cli vds-cli git status --project insurance
+   ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira search "project = NTTC" --limit 5
+   ./scripts/worktree_uv.sh run --project vds_cli vds-cli confluence content search "space = TDOV" --limit 5
+   ./scripts/worktree_uv.sh run --project vds_cli vds-cli bitbucket projects
+   ```
+
+**Environment:** Store shared credentials in `VDS_ENV_FILE` or `<config-root>/.env`.
+`<config-root>` resolves from `VDS_CONFIG_DIR` when set,
+otherwise from the friendly user-home VDS default (`~/.vds` on Unix-like systems).
+All `vds-scripts` CLIs auto-load the shared env file via `vds_cli_common`.
+If a variable is already set in the shell, it takes precedence over values loaded from `.env`.
+Use `./scripts/worktree_uv.sh run --project vds_cli vds-cli env status` to confirm.
+See `docs/agents/reference/portable-paths-and-config.md` for the full precedence and path model.
+If you update shared packages (e.g., `vds_cli_common`), re-sync the affected project:
+`uv sync --project <orchestrator> --reinstall`.
+
+---
+
+## 2. Documentation Map (Diátaxis)
+
+- **Tutorials (learning by doing)**:
+  - Use **section 1 Quick Start** on this page to bootstrap uv, sync projects, and run first commands.
+  - Follow the environment setup workflow in `AGENTS.md` §2.1–2.3 for an end‑to‑end walkthrough.
+- **How‑To guides (task recipes)**:
+  - **CLI Reference** (section 3 below) – copy/pasteable commands for common tasks (git, Jira, Confluence, Bitbucket, PDF).
+  - Git orchestrator examples in `vds-scripts/git_orchestrator/README.md`.
+  - Diagram generation flows in `vds-scripts/diagram_generator/README.md`.
+- **Reference (API/command surface)**:
+  - Atlassian Features Matrix (section 4) – what each orchestrator supports and the exact subcommands.
+  - Individual orchestrator READMEs (`jira_orchestrator/README.md`, `confluence_orchestrator/README.md`, `bitbucket_orchestrator/README.md`).
+- **Explanation (architecture & rationale)**:
+  - Migration & Architecture Snapshot (section 2) – why `vds-scripts/` exists and how components fit together.
+  - Bitbucket orchestrator architecture / practices docs under `bitbucket_orchestrator/`.
+
+For **AI agents**, use this file as the primary operational reference and `AGENTS.md` as the higher‑level policy and workflow guide.
+
+---
+
+## 3. Migration & Architecture Snapshot
+
+- **Cutover Date:** 2025‑11‑26 – `docs-nttc/scripts/*` replaced by this repo.
+- **Included Components:** `git_orchestrator`, `jira_orchestrator`, `confluence_orchestrator`, `bitbucket_orchestrator`, `vds_cli`, `mcp_server`, `markdown_orchestrator`, `diagram_generator`, `docker`.
+- **Rollback (reference only):** restore `split/vds-scripts` branch inside monorepo if needed.
+- **Shared Assets:** `repo-manifest.yaml` now lives in repo root; default path updated in git orchestrator.
+- **Standards:** All packages use `pyproject.toml`, `uv.lock`, Ruff, pytest, `atlassian-python-api v4.0.7`.
+
+---
+
+## 4. CLI Reference
+
+| Task | Command |
+| --- | --- |
+| Check env / status | `./scripts/worktree_uv.sh run --project vds_cli vds-cli env status` • `./scripts/worktree_uv.sh run --project vds_cli vds-cli status` |
+| Regenerate manifest | `./scripts/worktree_uv.sh run --project vds_cli vds-cli regenerate-manifest` (add `--dry-run` to preview) |
+| Git pull/status (manifest-aware) | `./scripts/worktree_uv.sh run --project vds_cli vds-cli git pull --project lep` • `... git status --match "*notification*"` |
+| Branch lifecycle | `./scripts/worktree_uv.sh run --project vds_cli vds-cli git branch list --project insurance` |
+| Jira operations | `./scripts/worktree_uv.sh run --project vds_cli vds-cli jira search "<JQL>" --limit 20` • `... jira session create` |
+| Confluence | `./scripts/worktree_uv.sh run --project vds_cli vds-cli confluence content page <ID> --server external --expand body.storage` |
+| Bitbucket | `./scripts/worktree_uv.sh run --project vds_cli vds-cli bitbucket repositories INSURANCE` |
+| Elastic | `./scripts/worktree_uv.sh run --project vds_cli vds-cli elastic ping` |
+| Grafana | `./scripts/worktree_uv.sh run --project vds_cli vds-cli grafana health` |
+| Hooks / Markdown lint | `./scripts/worktree_uv.sh run --project markdown_orchestrator python -m vds_markdown_orchestrator.cli lint` |
+
+> **Tip:** `./scripts/worktree_uv.sh run --project vds_cli vds-cli --help` and `... <service> --help` expose all flags. Use `--json-only` for machine-readable output or `--no-reports` to skip report files.
+
+Git commands automatically attempt to regenerate `vds-scripts/repo-manifest.yaml` from Bitbucket (LEP/INSURANCE/SAVING/EKYC)
+before running the underlying git orchestrator. To disable this behavior (for example, when offline), set
+`VDS_GIT_AUTO_REGENERATE_MANIFEST=0` (or `false`/`off`) in your shell environment before invoking `vds-cli git ...`.
+
+## 4.1 Smoke Matrix (2026-02-06)
+
+Run from `WHO-project/vds-scripts`:
+
+```bash
+# Unified CLI + live credentialed checks
+./scripts/worktree_uv.sh run --project vds_cli vds-cli env status
+./scripts/worktree_uv.sh run --project vds_cli vds-cli jira search "assignee = currentUser() ORDER BY updated DESC" --limit 1
+./scripts/worktree_uv.sh run --project jira_orchestrator vds-cli jira search "assignee = currentUser() ORDER BY updated DESC" --limit 1 --json-only
+./scripts/worktree_uv.sh run --project vds_cli vds-cli confluence search --cql "type=page" --limit 1
+./scripts/worktree_uv.sh run --project vds_cli vds-cli bitbucket projects
+
+# Service-specific live checks
+./scripts/worktree_uv.sh run --project vds_cli vds-cli elastic ping
+./scripts/worktree_uv.sh run --project vds_cli vds-cli grafana health
+./scripts/worktree_uv.sh run --project vds_cli vds-cli sonarqube ping
+./scripts/worktree_uv.sh run --project vds_cli vds-cli pdf -- version
+```
+
+Notes:
+- `vds-cli` routes all orchestrators after loading shared environment variables.
+- Router integrity is validated against each orchestrator's `[project.scripts]` declaration and target source module to prevent stale entrypoint drift.
+
+---
+
+## 5. Atlassian Features Matrix
+
+| Service | Feature | Command / Notes |
+| --- | --- | --- |
+| Jira | Search / filters | `vds-cli jira search "<JQL>" --limit N` (enhanced JQL on cloud) |
+| Jira | Issue details & transitions | `vds-cli jira issue <KEY>` • `jira transition <KEY> --status Done` |
+| Jira | Sessions | `jira session create/status/destroy` (reduces auth overhead) |
+| Confluence | CQL search & page read | `confluence content search "<CQL>"` • `confluence content page <ID>` |
+| Confluence | Attachments | `confluence content attachments sync --page-id ...` (built-in retry) |
+| Bitbucket | Projects/repos | `bitbucket projects` • `bitbucket repositories <PROJECT>` |
+| Bitbucket | Pull requests | `bitbucket pull-requests <PROJECT> <REPO>` (approve/comment/block) |
+| Git orchestration | Multi-repo ops | `git clone/pull/fetch/status/list/branch/checkout/add/commit/push/log/diff/stash/tag/remote` with `--project/--match/--tag` filters |
+
+All commands honor the shared manifest and emit JSON reports under `reports/<service>/YYYY/MM/DD/`.
+
+---
+
+## 6. Docker & Deployment
+
+```bash
+cd vds-scripts/docker
+cp env.example .env   # if provided
+docker compose up -d
+docker compose logs -f
+docker compose down
+```
+
+- Services: MCP server (FastMCP) + Redis.
+- Rebuild image: `docker compose build --no-cache mcp-server`.
+- Phase 2 Ubuntu portability verification: `./scripts/verification/phase2_portable_paths_ubuntu_docker.sh` (supported entrypoint; uses `docker/compose.phase2-verification.yml` underneath)
+- Run smoke tests inside container:
+  ```bash
+  docker compose exec mcp-server ./scripts/worktree_uv.sh run --project vds_cli vds-cli status
+  docker compose exec mcp-server uv run --project mcp_server pytest tests/unit -q
+  ```
+
+### 6.1 Offline Deployment (Air-Gapped)
+
+- Procedure: `docs/deployment/offline-docker-image-load.md`
+- Loader script: `scripts/deployment/load_docker_images_offline.sh`
+- Example:
+  ```bash
+  ./scripts/deployment/load_docker_images_offline.sh --images-dir /opt/vds/images
+  ```
+
+---
+
+## 7. Monitoring (T7) Log
+
+| Date | Env | CLI | Jira | Confluence | Bitbucket | Git | Docker | Notes |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| 2025‑11‑26 | | | | | | | | |
+| 2025‑11‑27 | | | | | | | | |
+| 2025‑11‑28 | | | | | | | | |
+| 2025‑11‑29 | | | | | | | | |
+| 2025‑11‑30 | | | | | | | | |
+| 2025‑12‑01 | | | | | | | | |
+| 2025‑12‑02 | | | | | | | | |
+| 2025‑12‑03 | | | | | | | | |
+| 2025‑12‑04 | | | | | | | | |
+| 2025‑12‑05 | | | | | | | | |
+| 2025‑12‑06 | | | | | | | | |
+| 2025‑12‑07 | | | | | | | | |
+| 2025‑12‑08 | | | | | | | | |
+| 2025‑12‑09 | | | | | | | | |
+| 2025‑12‑10 | | | | | | | | |
+
+- Daily steps: env status → CLI status → Jira/Confluence/Bitbucket/Git smoke → docker uptime.
+- Log incidents in the table above or issue tracker with captured `reports/verification/*` artifacts.
+- Exit criteria: 14 consecutive successful days + no unresolved incidents >72h + final summary circulated.
+
+---
+
+## 8. Deployment Task Tracker
+
+| ID | Description | Owner | Status | Notes |
+| --- | --- | --- | --- | --- |
+| T1 | Dependency matrix | Platform Core | ✅ | Logged in `vds-scripts.md` |
+| T2 | Filter repo & push | DevOps | ✅ | Tag `v1.0.0-pre` |
+| T3 | Document uv/bootstrap | Python Guild | ✅ | `scripts/bootstrap_uv.sh` |
+| T4 | Update documentation links | Docs Team | ✅ | AGENTS + README updated |
+| T5 | Verification (lint/tests/smoke) | QA Automation | ✅ | Evidence under `reports/verification/` |
+| T6 | Cutover & announcement | Release Eng | ✅ | Completed 2025‑11‑26 |
+| T7 | Post-cutover monitoring | Ops + AI Agents | 🔄 | Use section 6 table |
+| T8 | Cleanup legacy dirs | Platform Core | ✅ | All `docs-nttc/scripts/*` removed |
+
+Contacts: `platform-core@digital.vn`, `automation@digital.vn`, `ops@digital.vn`.
+
+---
+
+## 9. Support & References
+
+- **repo-manifest:** `vds-scripts/repo-manifest.yaml`
+- **Reports:** `vds-scripts/reports/<service>/YYYY/MM/DD/`
+- **SLA/MTTR policy:** `docs/operations/sla-mttr-policy.md`
+- **Bitbucket practices / architecture:** under respective orchestrator directories.
+- **AGENTS.md:** root guide referencing this README.
+
+_Last updated: 2026‑02‑06_
+
+
+
+
+
+
+
+
+
+

package/skills/vds-skill/vds-scripts/docs/agents/README.md

@@ -0,0 +1,33 @@
+<!-- diátaxis: explanation -->
+
+
+## Doc Structure
+
+This directory follows the Diátaxis framework:
+
+| Quadrant | Purpose | Examples |
+|----------|---------|----------|
+| [Tutorials](tutorials/) | Step-by-step learning | zero-to-productive-developer |
+| [How-To](how-to/) | Task-focused guides | install, decision-tree, workflow |
+| [Reference](reference/) | Command/API reference | 28 orchestrator docs |
+| [Explanation](explanation/) | Conceptual depth | ecosystem model, verification |
+
+## CLI Entry
+
+```bash
+# Validate all docs
+vds-cli docs validate --repo-root . --check-diataxis --check-orchestrators --check-vi
+
+# Score quality
+vds-cli docs quality-score --repo-root .
+
+# Show freshness
+vds-cli docs freshness --repo-root .
+```
+
+## Related
+
+- [VDS Scripts AGENTS.md](../../../AGENTS.md)
+- [Orchestrator Index](reference/orchestrator-index.md)
+- [WHO Ecosystem Model](explanation/who-ecosystem-model.md)
+- [Confluence Hub](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation)

package/skills/vds-skill/vds-scripts/docs/agents/explanation/data-flow.md

@@ -0,0 +1,132 @@
+<!-- diátaxis: explanation -->
+
+# Data Flow
+
+## Request Lifecycle
+
+### Audit Command
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant CLI as vds-cli
+    participant R as Router
+    participant O as Audit Orchestrator
+    participant PG as Postgres
+    participant CONF as Confluence
+    participant EXT as External API
+    
+    U->>CLI: vds-cli audit --repo my-service
+    CLI->>CLI: Parse arguments (Typer)
+    CLI->>R: Dispatch "audit"
+    R->>R: Validate orchestrator exists
+    R->>O: uv run vds-audit
+    O->>PG: Load checklist config
+    O->>EXT: Fetch repo metadata (Bitbucket)
+    O->>EXT: Run SonarQube analysis
+    O->>PG: Store results
+    O->>CONF: Upload evidence (optional)
+    O->>R: JSON output
+    R->>CLI: Forward output
+    CLI->>U: Console output
+```
+
+### Confluence Sync Command
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant CLI as vds-cli
+    participant R as Router
+    participant O as Confluence Orchestrator
+    participant FS as Filesystem
+    participant CONF as Confluence
+    
+    U->>CLI: vds-cli docs confluence-sync --repo my-service
+    CLI->>R: Dispatch "confluence"
+    R->>O: uv run vds-confluence-cli
+    O->>FS: Read docs/agents/
+    O->>FS: Read AGENTS.md, llms.txt
+    O->>CONF: Authenticate (token)
+    O->>CONF: Upload pages
+    O->>O: Generate evidence snapshot
+    O->>R: Completion status
+    R->>CLI: Forward status
+    CLI->>U: Sync report
+```
+
+## Error Handling Flow
+
+```mermaid
+graph TD
+    A[Command Start] --> B{Validation}
+    B -->|Valid| C[Orchestrator Run]
+    B -->|Invalid| D[Validation Error]
+    C -->|Success| E[Result Output]
+    C -->|Failure| F{Error Type}
+    F -->|Auth| G[Auth Error: Check ~/.vds/.env]
+    F -->|Network| H[Network Error: Retry or check connectivity]
+    F -->|Not Found| I[Not Found: Verify resource exists]
+    F -->|Other| J[Generic Error: See logs]
+    D --> K[Exit code 1]
+    G --> K
+    H --> K
+    I --> K
+    J --> K
+    E --> L[Exit code 0]
+```
+
+## Data Transformation Points
+
+### Input Normalization
+
+- Repo names are normalized to lowercase
+- Paths are resolved to absolute paths
+- Env vars are loaded from `~/.vds/.env` before orchestrator invocation
+
+### Output Formatting
+
+- JSON output: For programmatic consumption
+- Table output: For human readability (Rich tables)
+- Markdown output: For documentation generation
+- Evidence format: Structured JSON for Confluence upload
+
+### Caching
+
+| Cache Key | Store | TTL | Invalidation |
+|-----------|-------|-----|-------------|
+| Orchestrator metadata | Redis | 1 hour | On version change |
+| Confluence page list | Postgres | 4 hours | On sync completion |
+| Audit results | Postgres | Permanent | On re-audit |
+| AI memory vectors | Qdrant | Permanent | On explicit update |
+
+## Logging Flow
+
+```
+Orchestrator → structlog → JSON → Console/File → Optional: Postgres evidence
+```
+
+All log entries include:
+- Timestamp (ISO 8601)
+- Orchestrator name
+- Operation
+- Status (started/completed/failed)
+- Context (repo, checklist, user)
+
+## Data Flow Workflow
+
+Trace the path of a single audit request end-to-end:
+
+```bash
+vds-cli audit --repo my-service --checklist security
+# CLI parses args, dispatches to Audit Orchestrator via Router
+# Orchestrator loads checklist from Postgres
+# External APIs (Bitbucket, SonarQube) are invoked
+# Results are stored back in Postgres and returned as JSON
+```
+
+## See Also
+
+- [Orchestrator Architecture](../reference/orchestrator-architecture.md)
+- [System Architecture](../explanation/system-architecture.md)
+- [Troubleshooting Guide](../how-to/troubleshooting-guide.md)

package/skills/vds-skill/vds-scripts/docs/agents/explanation/development-roadmap.md

@@ -0,0 +1,49 @@
+<!-- diátaxis: explanation -->
+
+# Development Roadmap
+
+## Completed Phases
+
+| Phase | Theme | Merge Date | Key Deliverable |
+|-------|-------|-----------|----------------|
+| 177 | Docs Foundation | 2026-04-21 | Diátaxis structure, dual-audience, vi-VN |
+| 178 | Validation Design | — | Design-only, rolled into 179 |
+| 179 | Observability & Quality | 2026-04-29 | Validation gates, metrics, Confluence sync |
+| 180 | Comprehensive Docs | 2026-04-30 | 8 sections, 20 new docs |
+
+## Active Work
+
+| Phase | Theme | Status |
+|-------|-------|--------|
+| 220 Track-α | Lint hardening | In progress |
+
+## Planned Phases
+
+| Phase | Theme | ETA | Scope |
+|-------|-------|-----|-------|
+| 181 | Orchestrator Deep Dives | 2026-05 | Per-orchestrator tutorials |
+| 182 | Video Tutorials | 2026-05 | Screen recordings for setup |
+| 183 | Community Contributions | 2026-06 | External contributor guide |
+| 184 | Advanced AI Patterns | 2026-06 | Multi-agent workflows, memory optimization |
+
+## Decision Criteria
+
+Phase prioritization follows:
+
+1. **Operational impact** — Does this reduce incidents or toil?
+2. **Onboarding friction** — Does this help new developers?
+3. **Strategic alignment** — Does this support broader organizational goals?
+4. **Effort vs value** — Is the scope proportional to the impact?
+
+## See Also
+
+```bash
+# List completed phases
+vds-cli roadmap --status completed
+# Show active work items
+vds-cli roadmap --status active --format markdown
+```
+
+- [What's New](whats-new.md)
+- [Contribute New Orchestrator](../how-to/contribute-new-orchestrator.md)
+- Spec directories under `.gpt-5.4/specs/`

package/skills/vds-skill/vds-scripts/docs/agents/explanation/features-overview.md

@@ -0,0 +1,62 @@
+<!-- diátaxis: explanation -->
+
+# Features Overview
+
+The WHO ecosystem provides 37 orchestrators organized by complexity and use case.
+
+## By Complexity
+
+### Basic — Day 1–3
+
+| Feature | Orchestrator | One-Line Description |
+|---------|-----------|---------------------|
+| Audit code quality | `audit` | Run automated audits on any repository |
+| Sync to Confluence | `confluence` | Upload evidence and reports to Confluence |
+| Query databases | `db_query` | Run ad-hoc SQL across PostgreSQL, SQL Server, MariaDB |
+| Generate diagrams | `diagrams` | Create architecture diagrams from code |
+| Run progress reports | `progress` | Generate INSURANCE-AI progress reports |
+| Schedule workflows | `scheduler` | Create cron/interval schedules |
+
+### Intermediate — Day 4–7
+
+| Feature | Orchestrator | One-Line Description |
+|---------|-----------|---------------------|
+| Multi-project audit | `audit` | Audit multiple repos in one command |
+| Git worktree management | `git` | Create, lock, repair, retire worktrees |
+| Circular dependency analysis | `circular_dependency` | Detect cycle risk across repos |
+| ElasticSearch operations | `elastic` | Index and search logs and metrics |
+| Hexagonal compliance check | `hexagonal` | Verify clean architecture boundaries |
+| SonarQube integration | `sonarqube` | Run quality analysis and view issues |
+
+### Advanced — Day 8+
+
+| Feature | Orchestrator | One-Line Description |
+|---------|-----------|---------------------|
+| AI-powered research | `research` | Combine local code search with web research |
+| Custom skill authoring | `spec` | Create and validate VDS agent skills |
+| Multi-agent workflows | `multi_agent` | Coordinate parallel agent teams |
+| Telegram integration | `telegram` | Bot-based notification and interaction |
+| AI memory management | `memory` | Cross-session knowledge persistence |
+| OpenAPI handling | `openapi` | Parse, validate, and generate OpenAPI specs |
+| BRD generation | `brd` | Business requirements documents |
+| Schema conversion | `schema` | Convert between data schemas |
+| MCP server integration | `mcp` | Model Context Protocol server management |
+| Claude API workflows | `claude` | Anthropic Claude API orchestration |
+
+## By Functional Area
+
+| Area | Orchestrators |
+|------|--------------|
+| **Audit & Quality** | audit, sonarqube, hexagonal, public_interface |
+| **Documentation** | confluence, markdown, brd, spec, diagrams |
+| **Data & Storage** | db_query, elastic, schema, excel, google_sheets, metabase |
+| **DevOps & Infra** | git, scheduler, evolution, links, structure |
+| **AI & Agents** | memory, research, multi_agent, telegram, claude, mcp, lsp |
+| **Integration** | bitbucket, jira, openapi, pdf, intellij |
+| **Reporting** | progress, grafana |
+
+## See Also
+
+- [Feature Progression Guide](../tutorials/feature-progression-guide.md) — Day 8–14 learning path
+- [Orchestrator Comparison Matrix](../reference/orchestrator-comparison-matrix.md) — Detailed comparison
+- [Quick Start](../tutorials/quick-start.md) — Get running in 5 minutes

package/skills/vds-skill/vds-scripts/docs/agents/explanation/index.md

@@ -0,0 +1,36 @@
+<!-- diátaxis: explanation -->
+
+# WHO Ecosystem Explanation Index
+
+> Overview and navigation for WHO documentation explanation pages.
+
+## Available Explanations
+
+| Document | Purpose | Audience |
+|----------|---------|----------|
+| [Runtime Verification and Gap Reporting](runtime-verification-and-gap-reporting.md) | How VDS verifies results and reports gaps | All developers |
+| [WHO Ecosystem Model](who-ecosystem-model.md) | Architecture and component relationships | New team members |
+
+## Common Questions
+
+### How does the WHO ecosystem work?
+
+The WHO ecosystem is a multi-repo monorepo centered around `WHO-project/`:
+- `vds-scripts`: Core platform and orchestrator router
+- `vds-skills`: 27+ skills catalog
+- `vds-skills`: Unified skills catalog, hooks, and plugin marketplace
+- `vds-ai-memory`: Cross-session memory
+
+### How do I find the right doc?
+
+Use [Orchestrator Index](../reference/orchestrator-index.md) or search with:
+```bash
+rg "topic" docs/agents/
+```
+
+## Related
+
+- [WHO Ecosystem Model](who-ecosystem-model.md)
+- [Runtime Verification](runtime-verification-and-gap-reporting.md)
+- [Orchestrator Index](../reference/orchestrator-index.md)
+- [Skills Reference](../reference/skills-reference.md)

package/skills/vds-skill/vds-scripts/docs/agents/explanation/runtime-verification-and-gap-reporting.md

@@ -0,0 +1,127 @@
+<!-- diátaxis: explanation -->
+
+# Runtime Verification and Gap Reporting (Phase 3)
+
+Phase 3 of the WHO ecosystem alignment introduces a strict separation between
+file/catalog alignment and live runtime verification. A skills/doc surface can
+be internally aligned yet still fail in practice because the required runtime,
+credentials, network path, or active skill-discovery surface is incomplete.
+
+This guide defines the operator-facing contract for verifying runtime state
+without claiming unsupported CLI surfaces.
+
+## Runtime-Discovery Contract
+
+Runtime verification should confirm the state of the environment actually used
+by operators or agents in practice. The contract is evidence-based and should
+prefer existing supported commands over hypothetical convenience flags.
+
+### Discovery mechanisms
+
+- **Environment inspection**: confirm required environment variables, config
+  roots, and credentials locations are present and point to the expected VDS
+  paths.
+- **Credential verification**: confirm auth material is usable with existing
+  doctor commands such as `vds-cli audit --json-only doctor credentials`.
+- **Provider/profile verification**: confirm the configured profile set is
+  resolvable and available with existing commands such as
+  `vds-cli audit --json-only doctor profile-availability ...`.
+- **Readiness verification**: confirm project or repo state is materially ready
+  with existing commands such as `vds-cli audit --json-only state readiness ...`.
+- **Checklist/source verification**: confirm checklist retrieval and related
+  source surfaces with `vds-cli audit query-checklist ...` when the issue involves
+  source-checklist reachability rather than repo/project readiness.
+
+### Verification levels
+
+- **L1: Connectivity** — can the operator environment reach the required
+  service or source surface?
+- **L2: Authentication** — do the configured credentials authenticate
+  successfully for the intended surface?
+- **L3: Functional** — can an existing supported command perform a real,
+  minimal operation such as resolving readiness, listing checklist rows, or
+  validating profile availability?
+- **L4: Operational suitability** — is the surface usable enough for the
+  intended workflow within the expected timeout and environment constraints?
+
+## Known Runtime Gaps
+
+When runtime availability does not match the documented or cataloged
+expectation, the gap should be recorded explicitly rather than hidden behind a
+generic failure summary.
+
+### Gap classes
+
+- **Connectivity gap** — network path, host resolution, firewall, or transport
+  failure prevents access.
+- **Authentication gap** — credentials are missing, invalid, expired, or lack
+  sufficient permissions.
+- **Functional gap** — the service is reachable but the required operation or
+  workflow surface still fails.
+- **Environment gap** — local profile/config/runtime setup does not match the
+  documented expectation.
+
+### Reporting shape
+
+Each verified gap should record:
+
+- **Runtime status**: `READY`, `DEGRADED`, or `UNAVAILABLE`
+- **Gap ID**: stable identifier such as `GAP-RT-001`
+- **Surface**: which runtime surface failed (credentials, profile availability,
+  readiness, checklist retrieval, active skill-discovery, etc.)
+- **Description**: what did not match the documented expectation
+- **Impact**: what workflows are blocked or degraded
+- **Evidence**: exact command output or observed runtime signal
+- **Remediation**: next action to resolve or narrow the gap
+- **Status**: `OPEN`, `IN_PROGRESS`, or `RESOLVED`
+
+## Supported Operator Verification Pattern
+
+Use only commands already documented and supported in the current repo surface.
+
+### Credentials
+
+```bash
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit --json-only doctor credentials --require-state-dsn
+```
+
+### Profile / provider availability
+
+```bash
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit --json-only doctor profile-availability --mode active
+```
+
+### Project or repo readiness
+
+```bash
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit --json-only state readiness --project <PROJECT_PAGE_ID>
+```
+
+### Checklist/source surface verification
+
+```bash
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit query-checklist --checklist-page 88722450 --summary-only
+```
+
+## What This Guide Does Not Assume
+
+This guide does **not** assume the existence of convenience commands such as
+`vds-cli doctor --runtime-only` or `vds-cli status --show-gaps` unless those
+surfaces are implemented and documented elsewhere in the maintained repo.
+
+If such convenience surfaces are introduced later, they should be documented as
+an additive follow-up rather than retroactively treated as if they already
+exist.
+
+## Relation To Phase 3 Tasks
+
+- **TSK-3.14 / TSK-3.15**: define the runtime-discovery contract and compare
+  documented expectations against the active runtime surface used in practice.
+- **TSK-3.16 / TSK-3.17 / TSK-3.18**: document fallback behavior, runtime-status,
+  and known runtime gaps separately from file/catalog alignment.
+- **TSK-3.20 / TSK-3.21 / TSK-3.22**: support deterministic validation and clear
+  classification of runtime/tooling failures.