npm - @ngocsangairvds/vsaf - Versions diffs - 4.1.7 → 4.1.9 - Mend

@ngocsangairvds/vsaf 4.1.7 → 4.1.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1063) hide show

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

@@ -1,235 +0,0 @@
-# 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 DELETED Viewed

@@ -1,33 +0,0 @@
-<!-- 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 DELETED Viewed

@@ -1,132 +0,0 @@
-<!-- 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 DELETED Viewed

@@ -1,49 +0,0 @@
-<!-- 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 DELETED Viewed

@@ -1,62 +0,0 @@
-<!-- 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 DELETED Viewed

@@ -1,36 +0,0 @@
-<!-- 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 DELETED Viewed

@@ -1,127 +0,0 @@
-<!-- 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.