@ngocsangairvds/vsaf 4.1.7 → 4.1.9

package/skills/vds-skill/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/skills/vds-skill/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/skills/vds-skill/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/skills/vds-skill/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/skills/vds-skill/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.

package/skills/vds-skill/vds-scripts/docs/agents/how-to/03-memory-cross-agent.md

@@ -1,241 +0,0 @@
-<!-- diátaxis: how-to -->
-
-# Using VDS AI Memory from External Agent CLIs
-
-This guide covers how external agent runtimes — Codex, OpenCode, and Qwen — can
-read from and write to VDS AI Memory using the `vds-cli memory` subcommand.
-
-## Prerequisites
-
-The VDS AI Memory API must be running and reachable. Start the active runtime stack if needed:
-
-```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.
-
-## Runtime Environment Resolution
-
-| Variable | Purpose | Default |
-|---|---|---|
-| `VDS_MEMORY_API_URL` | Explicit base URL of the memory API | If unset: `http://localhost:${API_PORT:-8000}` |
-
-`vds-cli memory` loads `~/.vds/.env` automatically. Set an explicit URL only
-when the runtime is on a non-default host/port:
-
-```bash
-export VDS_MEMORY_API_URL="http://localhost:8010"
-```
-
-> **Note:** The memory API does not require an API key in its default
-> local-dev configuration. For current runtime/deployment guidance, prefer
-> `WHO-project/vds-scripts/memory_orchestrator/README.md` and the canonical spec
-> triplet under `.gpt-5.4/specs/vds-ai-memory/`.
-
-## Storing a Decision
-
-```bash
-# Store a decision scoped to a project using tags
-vds-cli memory store "decided to use Kafka for async event dispatch" \
-  --category business-logic --importance high \
-  --tags PAR,architecture,kafka
-
-# Minimal store
-vds-cli memory store "merchant-billing uses Spring Boot 3.2"
-```
-
-## Searching Memories
-
-```bash
-# Semantic search across all memories
-vds-cli memory search "kafka event dispatch" --limit 5
-
-# Filter by category
-vds-cli memory search "auth patterns" --category business-logic --limit 10
-```
-
-## Usage from Each Agent CLI
-
-All agent CLIs that can run shell commands can call `vds-cli` directly.
-Inherit `~/.vds/.env` via the shell session that launches the agent. Set
-`VDS_MEMORY_API_URL` only if you need an explicit override.
-
-### Codex
-
-```bash
-codex exec --skip-git-repo-check -m gpt-5.4 "your prompt here"
-```
-
-Within the Codex session, the agent runs shell commands:
-
-```bash
-vds-cli memory store "Codex discovered that merchant-report uses JPA auditing"
-vds-cli memory search "merchant-report auditing"
-```
-
-### OpenCode (Z.AI / GLM)
-
-```bash
-opencode run -m "zai-coding-plan/glm-5.1" "your prompt here"
-```
-
-The OpenCode agent shell-executes:
-
-```bash
-vds-cli memory store "OpenCode: PAR project checklist page is 88722450" \
-  --category business-logic --importance high
-vds-cli memory search "PAR checklist"
-```
-
-### Qwen
-
-```bash
-qwen -m qwen3-coder "your prompt here"
-```
-
-Qwen agents call:
-
-```bash
-vds-cli memory store "Qwen: insurance hexagonal boundary violations found in 3 repos"
-vds-cli memory search "hexagonal boundary violations"
-```
-
-## Project Scoping via Tags
-
-To keep memories scoped to a project, include the project key as a tag:
-
-```bash
-# Store scoped to project PAR
-vds-cli memory store "billing service auth pattern confirmed" \
-  --tags PAR,billing,auth
-
-# Search within PAR context (post-filter by tags)
-vds-cli memory search "billing auth" --limit 10
-```
-
-## Health Check
-
-Before a long agent run, verify the memory service is reachable:
-
-```bash
-vds-cli memory health
-```
-
-Expected output: `{"status": "healthy", ...}`
-
-## Practical Rules
-
-- Store decisions immediately after they are made — do not batch at end of session.
-- Include project key, service name, and date context in the content string.
-- Keep content under 500 characters per memory for searchability.
-- Do not store secrets, credentials, or personal data.
-- Use `--importance high` for irreversible architectural decisions.
-
----
-
-## Python SDK: `vds_memory_client` (VAMI-003)
-
-Since VAMI-003, a standalone Python package `vds_memory_client` provides
-programmatic access to VDS AI Memory for any Python agent or script — no
-`vds-cli` installation required.
-
-### Installing
-
-```bash
-# From the VDS monorepo (worktree or vds-scripts)
-uv run --project WHO-project/vds-scripts/vds_memory_client python3 -c "import vds_memory_client"
-
-# Or add as a dependency in your pyproject.toml
-[tool.uv.sources]
-vds_memory_client = { path = "../../vds_memory_client" }
-```
-
-### Basic Usage
-
-```python
-import asyncio
-from vds_memory_client import VDSMemoryClient
-
-async def main():
-    import os
-
-    base_url = os.getenv("VDS_MEMORY_API_URL") or f"http://localhost:{os.getenv('API_PORT', '8000')}"
-    client = VDSMemoryClient(base_url=base_url, timeout=10.0)
-
-    # Health check
-    status = await client.health()
-    print(status)  # {"status": "healthy", ...}
-
-    # Store a decision
-    result = await client.store(
-        content="Decided to use Kafka for async event dispatch",
-        category="business-logic",
-        importance="high",
-        tags=["PAR", "architecture"],
-    )
-    print(result["memory_id"])
-
-    # Search
-    results = await client.search(query="kafka event dispatch", limit=5)
-    for m in results["results"]:
-        print(f"[{m['category']}] {m['content'][:80]}")
-
-asyncio.run(main())
-```
-
-### Session State Caching
-
-`VDSMemoryClient` caches the health-check result in `~/.vds/.memory-session.json`
-using an atomic write (`tempfile.mkstemp` + `os.replace`). This file is:
-- **Not** in iCloud (lives in `~/.vds/`, not `~/Library/Mobile Documents/`)
-- Safe for concurrent writes from multiple agent processes
-- Valid for 60 minutes by default before the client re-checks health
-
-### iCloud Path Compatibility
-
-`vds_memory_client` runs correctly from iCloud-backed project paths
-(e.g. `~/Library/Mobile Documents/com~apple~CloudDocs/...`). The key properties
-that make this safe:
-
-| Concern | How it is handled |
-|---------|-------------------|
-| Spaces in path arguments | Wrap variables in double-quotes: `"$CLAUDE_PROJECT_DIR/..."` |
-| Atomic session writes | Written to `~/.vds/` (outside iCloud), using `os.replace()` |
-| `uv run --project <path>` | Path passed as a quoted argument; uv handles spaces correctly |
-
-### Hook Integration (now via Claude Code plugins)
-
-**Status (2026-04-24)**: The `vds_hooks` Python package was retired by
-`vds-hooks-claude-plugin-packaging` Phase 6. Hook integration with VDS AI Memory
-now lives entirely in the **Claude Code plugin format**:
-
-- `WHO-project/vds-skills/plugins/vds-hooks-core/` — generic hooks
-- `WHO-project/vds-skills/plugins/vds-hooks-extras/` — VDS-specific hooks (memory, audit, agent context)
-
-Plugins are installed via `/plugin marketplace add` + `/plugin install` and fire
-automatically on Claude Code events (`SessionStart`, `Stop`, `SessionEnd`,
-`UserPromptSubmit`, etc.) — no manual `vds-cli` invocation required.
-
-For the HTTP proxy endpoints, see
-`WHO-project/vds-scripts/memory_orchestrator/` — those endpoints are
-independent of the Python-package retirement and continue to serve
-`POST /api/v1/hooks/session-context` and `POST /api/v1/hooks/session-persist`.
-
-For SDK-level memory access from your own scripts, use `vds_memory_client`
-(see "Python SDK" section above). For the canonical hook semantics + dual-path
-safety-net design, see the spec at
-`.gpt-5.4/specs/vds-hooks-claude-plugin-packaging/` (Phase 6 archive +
-predecessor `hooks.RETIRED-2026-05-02/`).
-
-### Environment Variables
-
-| Variable | Effect | Default |
-|----------|--------|---------|
-| `VDS_MEMORY_API_URL` | API base URL | If unset: `http://localhost:${API_PORT:-8000}` |
-| `VDS_HOOK_SESSION_MEMORY` | Set to `"0"` to disable session context hook | `"1"` |
-| `VDS_HOOK_MEMORY_PERSIST` | Set to `"0"` to disable persist-stop hook | `"1"` |
-| `VDS_HOOK_MEMORY_DECISIONS` | Set to `"0"` to skip decision extraction | `"1"` |