@ngocsangairvds/vsaf 4.1.9 → 4.1.10

package/skills/vds-skill/runtime/docs/agents/explanation/system-architecture.md

@@ -0,0 +1,139 @@
+<!-- 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/runtime/docs/agents/explanation/whats-new.md

@@ -0,0 +1,75 @@
+<!-- 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/runtime/docs/agents/explanation/who-ecosystem-introduction.md

@@ -0,0 +1,65 @@
+<!-- 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/runtime/docs/agents/explanation/who-ecosystem-model.md

@@ -0,0 +1,41 @@
+<!-- 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/runtime/docs/agents/how-to/02-using-vds-ai-memory.md

@@ -0,0 +1,98 @@
+<!-- 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/runtime/docs/agents/how-to/03-memory-cross-agent.md

@@ -0,0 +1,241 @@
+<!-- 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"` |