@ngocsangairvds/vsaf 3.2.16 → 4.0.0

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

@@ -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.

package/tools/vds-scripts/docs/agents/explanation/system-architecture.md

@@ -1,139 +0,0 @@
-<!-- diátaxis: explanation -->
-
-# System Architecture
-
-## Component Diagram
-
-```mermaid
-graph TB
-    subgraph User Layer
-        CLI[vds-cli]
-        AGENTS[AGENTS.md]
-        SKILLS[Skills]
-    end
-    
-    subgraph Orchestration Layer
-        ROUTER[Router]
-        ORCH1[Audit]
-        ORCH2[Confluence]
-        ORCH3[Git]
-        ORCH4[Memory]
-        ORCH5[...33 more]
-    end
-    
-    subgraph Data Layer
-        PG[(Postgres)]
-        RD[(Redis)]
-        QD[(Qdrant)]
-        FS[Filesystem]
-    end
-    
-    subgraph External Layer
-        CONF[Confluence]
-        BB[Bitbucket]
-        ES[ElasticSearch]
-        SONAR[SonarQube]
-    end
-    
-    CLI --> ROUTER
-    AGENTS --> CLI
-    SKILLS --> CLI
-    ROUTER --> ORCH1
-    ROUTER --> ORCH2
-    ROUTER --> ORCH3
-    ROUTER --> ORCH4
-    ORCH1 --> PG
-    ORCH2 --> CONF
-    ORCH4 --> QD
-    ORCH3 --> BB
-    ORCH1 --> SONAR
-    PG --> RD
-```
-
-## Interaction Patterns
-
-### Request/Response (Synchronous)
-
-Most orchestrator commands are synchronous:
-
-```
-User → vds-cli → Router → uv run → Orchestrator CLI → External API → Response
-```
-
-Example: `vds-cli audit --repo my-service`
-
-### Async/Pub-Sub
-
-The scheduler uses Redis pub/sub for job distribution:
-
-```
-Scheduler → Redis Channel → Worker → Orchestrator → Result → Postgres
-```
-
-### Streaming
-
-Multi-agent workflows stream results via SSE (Server-Sent Events):
-
-```
-Multi-agent → Event Stream → Console/Telegram
-```
-
-## Data Stores
-
-| Store | Purpose | Persistence | Access Pattern |
-|-------|---------|-------------|----------------|
-| Postgres | Audit results, progress reports, orchestrator state | Persistent | SQL queries |
-| Redis | Job queues, session state, cache | Ephemeral | Key-value, pub/sub |
-| Qdrant | AI memory vectors, semantic search | Persistent | Vector similarity |
-| Filesystem | Specs, docs, evidence files | Persistent | File I/O |
-
-## Deployment View
-
-### Local Development
-
-```bash
-# Start services
-docker compose up -d
-
-# Sync environment
-uv sync
-
-# Run CLI
-vds-cli --help
-```
-
-### CI/CD
-
-```yaml
-# .github/workflows/docs-quality.yml
-- name: Validate docs
-  run: vds-cli docs validate
-- name: Run tests
-  run: pytest
-```
-
-### Docker (Production)
-
-All orchestrators run as independent containers orchestrated by Docker Compose. The CLI container mounts the orchestrator source directories and dispatches via `uv run`.
-
-## Security Boundaries
-
-| Boundary | Mechanism |
-|----------|-----------|
-| External API credentials | `~/.vds/.env` (user-local, not in repo) |
-| Database connections | Connection strings via env vars |
-| Git operations | SSH keys or HTTPS tokens |
-| AI memory | API key in env, data in Qdrant |
-
-## Scaling Considerations
-
-- **Horizontal**: Add worker containers for scheduler jobs
-- **Vertical**: Scale Postgres and Redis for higher throughput
-- **Caching**: Redis for frequently accessed orchestrator metadata
-- **Queue depth**: Monitor Redis list lengths for backlog detection
-
-## See Also
-
-- [Orchestrator Architecture](../reference/orchestrator-architecture.md)
-- [Data Flow](../explanation/data-flow.md)
-- [Configuration Reference](../reference/configuration-reference.md)

package/tools/vds-scripts/docs/agents/explanation/whats-new.md

@@ -1,75 +0,0 @@
-<!-- diátaxis: explanation -->
-
-# What's New
-
-Track recent changes and verify your environment is current.
-
-## 2026-04-30 — Comprehensive Documentation (Phase 180)
-
-New documentation covering 8 target sections:
-- Introduction, Quick Start, System Requirements, Configuration Reference
-- Features Overview, Feature Progression Guide, Orchestrator Comparison
-- Architecture docs (expanded), System Architecture, Data Flow
-- Current Development, Roadmap, Contribution Guide
-- Tips & Tricks, Troubleshooting Guide, Common Errors Reference
-
-Verify you have the new docs:
-```bash
-vds-cli docs validate && vds-cli docs quality-score
-```
-
-## 2026-04-29 — Telegram Bridge & Lint Hygiene
-
-- **Telegram Bridge**: Bot-based notifications with multi-runner support (Claude, ACP, Codex)
-  - 102 test files, 9 skill references
-  - Daemon + 2 runner surfaces
-- **Lint Hygiene**: Track-α fixes for Phase 220
-  - AGENTS.md capped at 250 lines
-  - `vds-cli lint` command family
-
-Check bridge status:
-```bash
-vds-cli telegram status --daemon 2>/dev/null || echo "Telegram bridge not configured"
-```
-
-## 2026-04-22 — Phase 179 Merge
-
-- Diátaxis documentation structure (explanation, tutorial, how-to, reference)
-- Validation gates in AGENTS.md
-- Observability: `vds-cli docs consumption-funnel`, `freshness-report`, `ecosystem-report`
-- Confluence sync reference doc
-- Infrastructure v2.15 documentation
-
-## 2026-04-21 — Phase 177 Merge
-
-- Dual-audience persona separation (human vs agent)
-- Vietnamese translations (58 canonical + 19 drafts)
-- Ecosystem docs index (`ECOSYSTEM-DOCS.md`)
-- Changelog (`ECOSYSTEM-CHANGELOG.md`)
-- Pre-commit hooks and CI quality gate
-
-## Upcoming
-
-- Phase 220 Track-α: Lint hardening continued
-- Phase 181+: Additional orchestrator deep dives
-- Video tutorials
-
-## Quick Health Check
-
-Run this weekly:
-```bash
-# Verify all gates pass
-vds-cli docs validate
-vds-cli --help > /dev/null && echo "CLI OK"
-
-# Check test baseline
-pytest --co -q | tail -1
-
-# Check for stale docs
-vds-cli docs freshness-report --days 30
-```
-
-## See Also
-
-- [Development Roadmap](development-roadmap.md)
-- [ECOSYSTEM-CHANGELOG.md](../../../ECOSYSTEM-CHANGELOG.md)

package/tools/vds-scripts/docs/agents/explanation/who-ecosystem-introduction.md

@@ -1,65 +0,0 @@
-<!-- diátaxis: explanation -->
-
-# WHO Ecosystem Introduction
-
-The WHO (Workflow Orchestration Harness) ecosystem is a unified platform for automating software engineering workflows across the VDS organization. It combines AI agents, orchestrated CLI tools, and persistent memory to accelerate development, audit, and infrastructure tasks.
-
-## What You Get
-
-- **36 orchestrators** covering audit, reporting, infrastructure, and integration workflows
-- **27 agent skills** for specialized tasks (research, spec creation, code review)
-- **Cross-session memory** so AI agents remember context between conversations
-- **Validated documentation** with quality gates and freshness tracking
-
-## Ecosystem Components
-
-```mermaid
-graph TD
-    subgraph CLI
-        A[vds-cli]
-    end
-    subgraph Orchestrators
-        B[audit]<-->C[confluence]
-        D[bitbucket]<-->E[git]
-        F[db-query]<-->G[progress]
-        H[scheduler]<-->I[telegram-bridge]
-    end
-    subgraph Platform
-        J[Postgres]<-->K[Redis]
-        L[Qdrant]<-->M[AI Memory]
-    end
-    A --> B
-    A --> D
-    A --> F
-    A --> H
-    B --> J
-    C --> J
-    G --> K
-    M --> L
-```
-
-## Target Audiences
-
-| Audience | Entry Point | Primary Tools |
-|----------|-------------|---------------|
-| **Platform Engineers** | [Quick Start](quick-start.md) | Docker, uv, CI/CD |
-| **Service Developers** | [Feature Progression](feature-progression-guide.md) | Orchestrators, skills |
-| **Auditors** | [Audit Triage Playbook](../../reference/audit-triage-playbook.md) | `vds-cli audit` |
-| **AI Agents** | [Agent Operational Contract](../../reference/agent-operational-contract.md) | AGENTS.md, skills |
-
-## Repositories
-
-- [`vds-scripts`](https://bitbucket.org/viettel-digital-services/vds-scripts) — CLI, orchestrators, and core workflows
-- [`vds-skills`](https://bitbucket.org/viettel-digital-services/vds-skills) — Agent skills and reference guides
-- [`vds-ai-memory`](https://bitbucket.org/viettel-digital-services/vds-ai-memory) — Cross-session memory and knowledge base
-
-## Quick Links
-
-- [Setup](quick-start.md) — Get running in 5 minutes
-- [Features](features-overview.md) — What you can do
-- [Architecture](system-architecture.md) — How it works
-- [Configuration](configuration-reference.md) — All settings
-- [Tips](tips-and-tricks.md) — Work faster
-- [Troubleshooting](troubleshooting-guide.md) — Fix problems
-- [What's New](whats-new.md) — Recent changes
-- [Contribute](contribute-new-orchestrator.md) — Add capabilities

package/tools/vds-scripts/docs/agents/explanation/who-ecosystem-model.md

@@ -1,41 +0,0 @@
-<!-- diátaxis: explanation -->
-
-# WHO Ecosystem Model
-
-`WHO-project` is the canonical VDS ecosystem for both reusable skills and routed scripts.
-
-## Canonical ownership
-
-- Skills live under `WHO-project/vds-skills/skills/`
-- Scripts and orchestrators live under `WHO-project/vds-scripts/`
-- `.agent/skills/` is a compatibility mirror or symlink path, not an authoring source
-- generated `AGENTS.md` surfaces are downstream outputs, not canonical content roots
-
-## Platform versus specialist guidance
-
-Use `vds-scripts-skill` as the **platform-routing skill** when you need to:
-- find the correct command family
-- understand the current WHO scripts workspace surface
-- route a task to the correct specialist skill
-
-Use specialist skills when you need deep workflow guidance, for example:
-- `audit-orchestrator-skill` for audit workflow execution and readiness/gating flows
-- `llm-analysis-skill` for LLM-backed content evaluation
-- `spec-creation-skill` for spec creation and consolidation
-- `lsp-skill` for LSP setup and usage
-- `circular-dependency-skill` for dependency-cycle analysis
-
-## Current scripts capability layers
-
-- routed command surfaces via `vds-cli`
-- standalone workspace capabilities such as markdown, hexagonal, MCP, and multi-agent support
-- shared support layers such as `vds_cli_common`
-
-This model keeps the platform skill concise while still covering the full current WHO ecosystem through references and routing aids.
-
-## Related Documents
-
-- [VDS CLI Reference](vds-cli-reference.md)
-- [Orchestrator Index](orchestrator-index.md)
-- [Skills Reference](skills-reference.md)
-- [Confluence Hub](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation)

package/tools/vds-scripts/docs/agents/how-to/02-using-vds-ai-memory.md

@@ -1,98 +0,0 @@
-<!-- diátaxis: how-to -->
-
-# How To Use VDS AI Memory
-
-Use the skill entrypoint first:
-
-- Skill: `WHO-project/vds-skills/skills/vds-ai-memory-skill/SKILL.md`
-
-Operational context:
-
-- [WHO project baseline](../../../AGENTS.md)
-- Skills catalog: `WHO-project/vds-skills/README.md`
-
-## Prerequisites
-
-Start the active VDS AI Memory runtime before using the CLI:
-
-```bash
-cd WHO-project/vds-scripts/memory_orchestrator
-docker compose --profile dev --profile mem0 up -d
-```
-
-This starts the active memory runtime stack from `memory_orchestrator/`.
-
-> `WHO-project/vds-ai-memory/` is historical/archive-only and should not be used for current startup or runtime guidance.
-
-## Base URL Resolution
-
-`vds-cli memory` (and direct `vds-memory`) load `~/.vds/.env` and resolve the
-API base URL in this order:
-
-1. `VDS_MEMORY_API_URL`
-2. `http://localhost:${API_PORT}` (when `API_PORT` is set)
-3. `http://localhost:8000`
-
-In most sessions, you should not need to pass `--api-url` manually.
-
-## CLI Commands (Recommended)
-
-The `vds-cli memory` subcommand is the primary interface for agents and interactive use.
-
-```bash
-# Search memories by semantic query
-vds-cli memory search "auth patterns" --limit 5
-
-# Store a new memory
-vds-cli memory store "PAR billing uses Spring Boot 3.2" \
-  --category code --importance high --tags spring-boot,PAR
-
-# Retrieve a specific memory by ID
-vds-cli memory get <memory_id>
-
-# List active sessions
-vds-cli memory sessions
-
-# Health check
-vds-cli memory health
-
-# Statistics (machine-readable)
-vds-cli memory --json-only stats
-```
-
-## Command Discovery
-
-- Use `vds-cli memory ...` for normal routed execution.
-- Put global options before the subcommand, for example: `vds-cli memory --json-only stats`
-- Use the direct package entrypoint for full command help:
-
-```bash
-./scripts/worktree_uv.sh run --project memory_orchestrator vds-memory --help
-```
-
-## Practical Rules
-
-- Capture durable decisions with dates, paths, commands, and evidence.
-- Prefer short decision records over long narrative summaries.
-- Use tags to improve searchability across agents.
-- Do not store secrets, tokens, or personal data.
-
-## Hook Integration (automatic, since Phase 6 HX.2)
-
-VDS AI Memory is wired into Claude Code via two parallel hook paths, both registered in `.claude/settings.local.json`:
-
-1. **Command path** (fallback, works even when Docker is down) — uses the `vds-cli memory-*` console scripts installed in `WHO-project/vds-scripts/.venv/bin/`:
-   - `vds-cli memory-session-context` on `SessionStart` (5s timeout) — pre-loads prior decisions
-   - `vds-cli memory-persist-stop` on `Stop` (30s) — auto-persists session summary
-   - `vds-cli memory-persist-stop --session-end` on `SessionEnd` (30s) — final summary
-   - `vds-cli memory-prompt-search` on `UserPromptSubmit` (3s) — per-prompt memory search
-
-2. **HTTP path** (low-latency, ~20× faster when Docker is up) — calls dedicated endpoints on the running memory service:
-   - `POST <BASE_URL>/api/v1/hooks/session-context` on `SessionStart`
-   - `POST <BASE_URL>/api/v1/hooks/session-persist` on `Stop`
-
-`<BASE_URL>` follows the same resolution order in **Base URL Resolution** above.
-
-Both paths run in parallel on the same events as a **dual-path safety net**. HTTP non-2xx responses are non-blocking in Claude Code, so if the memory service is unreachable (rebuilding, stopped, laptop offline), the command path still succeeds. You generally shouldn't need to do anything manually — just use `vds-cli memory store` for explicit saves and the hooks handle the rest.
-
-Env-var toggles: `VDS_HOOK_SESSION_MEMORY=0` disables SessionStart pre-load, `VDS_HOOK_MEMORY_PERSIST=0` disables Stop auto-persist, `VDS_HOOK_MEMORY_DECISIONS=0` disables decision auto-capture. Default all on.