@ngocsangairvds/vsaf 4.1.8 → 4.1.9

package/skills/vds-skill/vds-scripts/docs/vi/agents/how-to/first-audit-run.md

@@ -1,85 +0,0 @@
-<!-- diátaxis: how-to -->
-
-<!-- TODO: translate — Vietnamese translation pending -->
-
-# First Audit Run
-
-> Step-by-step guide for running your first repository audit using the WHO-project toolchain.
-
-## Prerequisites
-
-- `vds-scripts` cloned and bootstrapped (`./scripts/worktree_uv.sh sync`)
-- `vds-cli doctor` passes
-- Target repo(s) accessible via Bitbucket
-
-## Quick Start
-
-### 1. Discover available audit skills
-
-```bash
-cat WHO-project/vds-skills/skills/ | grep audit
-```
-
-Expected output includes `audit-orchestrator-skill`.
-
-### 2. Load the audit skill
-
-```bash
-cat WHO-project/vds-skills/skills/audit-orchestrator-skill
-```
-
-This prints the skill's operational contract, CLI flags, and examples.
-
-### 3. Run a single-repo audit
-
-```bash
-vds-cli audit run --repo vds-scripts --scope quick
-```
-
-- `--repo`: target repository slug
-- `--scope quick`: fast pass (rules + structure, no deep analysis)
-- `--scope full`: comprehensive audit (slower, more thorough)
-
-### 4. Review results
-
-Output is written to `audits/<timestamp>-<repo>-<scope>.md`.
-
-```bash
-cat audits/$(ls -t audits/ | head -n 1)
-```
-
-### 5. Escalate findings
-
-If the audit surfaces issues:
-
-```bash
-# Auto-create tickets from findings
-vds-cli audit escalate --from audits/<file>.md --tracker jira
-
-# Or export as Confluence table
-vds-cli audit export --format confluence --from audits/<file>.md
-```
-
-## Common Flags
-
-| Flag | Description |
-|------|-------------|
-| `--dry-run` | Show what would be audited without running |
-| `--rules-only` | Skip code analysis, check rules compliance only |
-| `--output-dir` | Custom output directory (default: `audits/`) |
-| `--format json` | Machine-readable output instead of markdown |
-
-## Troubleshooting
-
-| Symptom | Fix |
-|---------|-----|
-| `audit-orchestrator-skill not found` | Run `vds-cli skills sync --agent claude` to refresh catalog |
-| `Permission denied` on Bitbucket | Check `INTERNAL_BITBUCKET_TOKEN` in `~/.vds/.env` |
-| Empty audit output | Verify `--repo` slug matches Bitbucket exactly |
-| Slow execution | Use `--scope quick` or `--rules-only` for faster feedback |
-
-## Next Steps
-
-- Read the full audit skill: `cat WHO-project/vds-skills/skills/audit-orchestrator-skill`
-- Review the audit triage playbook: `docs/agents/reference/audit-triage-playbook.md`
-- Run cross-repo audits: `vds-cli audit run --repo-list repos.txt --scope full`

package/skills/vds-skill/vds-scripts/docs/vi/agents/how-to/index.md

@@ -1,21 +0,0 @@
-<!-- diátaxis: how-to -->
-
-<!-- TODO: translate — Vietnamese translation pending -->
-
-# How-to Guides
-
-Task-oriented guides for common agent workflows.
-
-- [Use VDS AI memory](02-using-vds-ai-memory.md)
-- [Use VDS AI memory from external agent CLIs (Codex, OpenCode, Qwen)](03-memory-cross-agent.md)
-- [Generate progress reports](04-using-progress-reports.md)
-- [Run semantic search](08-semantic-search.md)
-- [Install and bootstrap WHO scripts and skills](install-and-bootstrap-who-scripts-and-skills.md)
-- [Choose the right command or skill](choose-the-right-command-or-skill.md)
-- [Phase 131 all-project preparation](phase131-all-project-preparation.md)
-- [Phase 131 bounded parallel analysis](phase131-bounded-parallel-analysis.md)
-- [Phase 131 Confluence upload and recovery](phase131-confluence-upload-recovery.md)
-- [Phase 132 department-wide preparation](phase132-department-preparation.md)
-- [Audit orchestrator runtime guide](../../../audit_orchestrator/README.md)
-- [Scripts workspace operations](../../README.md)
-- [Portable paths and config reference](../reference/portable-paths-and-config.md)

package/skills/vds-skill/vds-scripts/docs/vi/agents/how-to/install-and-bootstrap-who-scripts-and-skills.md

@@ -1,156 +0,0 @@
-<!-- diátaxis: how-to -->
-
-# Hướng dẫn cài đặt và khởi tạo WHO Scripts và Skills
-
-> Hướng dẫn từng bước để cài đặt hệ sinh thái WHO-project từ đầu.
-
----
-
-## Yêu cầu tiên quyết
-
-Trước khi bắt đầu, hãy đảm bảo bạn có:
-
-- **Python 3.12+** — Cài đặt từ [python.org](https://python.org)
-- **uv** — Trình quản lý gói Python. `curl -LsSf https://astral.sh/uv/install.sh | sh`
-- **Git** — Hỗ trợ worktree. `git --version` >= 2.40
-- **Truy cập** — Tài khoản Bitbucket và Confluence được cấp quyền
-- **~/.vds/.env** — Tệp môi trường với thông tin xác thực (xem bước 3)
-
-## Bước 1: Clone các repository
-
-```bash
-# Tạo thư mục dự án
-mkdir -p WHO-project
-cd WHO-project
-
-# Clone các repository chính
-git clone http://bitbucket.digital.vn/scm/WHO/vds-scripts.git
-git clone http://bitbucket.digital.vn/scm/WHO/vds-skills.git
-git clone http://bitbucket.digital.vn/scm/WHO/vds-skills.git
-```
-
-## Bước 2: Đồng bộ workspace Python
-
-```bash
-cd vds-scripts
-./scripts/worktree_uv.sh sync --all-packages
-```
-
-Nếu `uv sync` báo lỗi:
-- Xác minh `pyproject.toml` tồn tại
-- Kiểm tra quyền thư mục `.venv/`
-- Thử xóa `.venv/` và chạy lại
-
-## Bước 3: Cấu hình môi trường (`~/.vds/.env`)
-
-> **Tham khảo đầy đủ**: phiên bản tiếng Anh §11 ([install-and-bootstrap-who-scripts-and-skills.md](../../../agents/how-to/install-and-bootstrap-who-scripts-and-skills.md)) chứa định nghĩa chuẩn cho `~/.vds/.env` theo `who-ecosystem-alignment` Phase 5 FR-18..FR-25 (merged tại `bd162539`).
-
-Cấu trúc tối thiểu (giá trị bên dưới là placeholder — thay bằng credentials thật của bạn, KHÔNG commit):
-
-```bash
-mkdir -p ~/.vds
-cat > ~/.vds/.env << 'ENVAR_EOF'
-# Atlassian shared identity (Bitbucket + Confluence + JIRA dùng chung)
-VDS_USERNAME=<your-corporate-username>
-VDS_PASSWORD=<your-corporate-password>
-
-# Optional per-product tokens (Bitbucket + JIRA: token được ưu tiên hơn basic;
-# Confluence: basic vẫn là primary path, token là fallback)
-BITBUCKET_TOKEN=<your-bbdc-pat>
-JIRA_TOKEN=<your-jira-pat>
-INTERNAL_CONFLUENCE_TOKEN=<your-internal-confluence-token>
-EXTERNAL_CONFLUENCE_TOKEN=<your-external-confluence-token>
-
-# Isolated-prefix (Grafana / SonarQube / Elastic — KHÔNG dùng chung VDS_PASSWORD)
-VDS_GRAFANA_USER=<your-grafana-user>
-VDS_GRAFANA_PASSWORD=<your-grafana-password>
-VDS_SONAR_USER=<your-sonar-user>
-VDS_SONAR_PASSWORD=<your-sonar-password>
-VDS_ELASTIC_USER=<your-elastic-user>
-VDS_ELASTIC_PASSWORD=<your-elastic-password>
-
-# Memory service (local)
-VDS_MEMORY_API_URL=http://localhost:8010
-ENVAR_EOF
-
-chmod 600 ~/.vds/.env
-```
-
-> **Quan trọng**: Không bao giờ commit `.env` hoặc thông tin xác thực vào Git (NFR-12).
-
-### Cài đặt git credential helper (FR-23)
-
-Helper được quản lý duy nhất qua `vds-cli env *` subcommands. KHÔNG cài thủ công bằng `cp` / `chmod` / `git config`.
-
-```bash
-# Cài helper canonical tại $HOME/.vds/bin/git-credential-vds (mode 0o700)
-./scripts/worktree_uv.sh run --project vds_cli vds-cli env install-git-helper
-
-# Kiểm tra trạng thái cài đặt
-./scripts/worktree_uv.sh run --project vds_cli vds-cli env verify-git-helper
-
-# Khi cần reset cooldown (sau khi sửa creds bị lock)
-./scripts/worktree_uv.sh run --project vds_cli vds-cli env verify-git-helper --reset-cooldown
-
-# Gỡ cài đặt (idempotent)
-./scripts/worktree_uv.sh run --project vds_cli vds-cli env remove-git-helper [--purge]
-```
-
-Helper bảo vệ chống Bitbucket account-lock thông qua: (a) host allowlist (mặc định `bitbucket.digital.vn`), (b) lockout-prevention (3 failures trong 60s → 300s cooldown), (c) token preference (BITBUCKET_TOKEN ưu tiên hơn VDS_PASSWORD khi cả hai có).
-
-## Bước 4: Xác minh cài đặt
-
-```bash
-# Kiểm tra vds-cli
-./scripts/worktree_uv.sh run --project vds_cli vds-cli --help
-
-# Kiểm tra trạng thái môi trường
-./scripts/worktree_uv.sh run --project vds_cli vds-cli env status
-
-# Chạy kiểm thử tập trung
-./scripts/worktree_uv.sh run --project vds_cli vds-cli doctor
-```
-
-Bạn sẽ thấy bảng màu với các hàng:
-- ✅ Shared env file present
-- ✅ VDS credentials
-- ✅ Bitbucket auth
-- ✅ Confluence auth
-
-## Bước 5: Cài đặt skills
-
-```bash
-cd ../vds-skills
-cat WHO-project/vds-skills/skills/
-vds-cli skills sync --agent claude
-```
-
-## Bước 6: Cài đặt Claude hooks (tùy chọn)
-
-```bash
-cd ../vds-skills
-bash scripts/deploy.sh
-bash scripts/test-hooks-smoke.sh
-```
-
-## Bước 7: Xác thực toàn bộ
-
-```bash
-cd ../vds-scripts
-./.venv/bin/vds-cli docs validate --repo-root . --check-vi --check-diataxis
-```
-
-Kết quả mong đợi: ✅ docs validate passed (với cảnh báo về bản dịch tiếng Việt nếu chưa hoàn thành)
-
-## Khắc phục sự cố thường gặp
-
-| Triệu chứng | Nguyên nhân | Khắc phục |
-|-------------|-------------|-----------|
-| `Module not found` | Chưa đồng bộ workspace | Chạy `./scripts/worktree_uv.sh sync --all-packages` |
-| `Auth failures` | Thiếu biến môi trường | Kiểm tra `~/.vds/.env` |
-| `Worktree issues` | `core.symlinks=false` | `git config --global core.symlinks true` |
-| `vds-cli not found` | Chưa cài đặt entrypoint | `./scripts/worktree_uv.sh run --project vds_cli ...` |
-
----
-
-**Tiếp theo**: [Con đường từ Zero đến Productive Developer](../tutorials/zero-to-productive-developer.md)

package/skills/vds-skill/vds-scripts/docs/vi/agents/how-to/orchestrator-workflows/analytics-pipeline-workflow.md

@@ -1,174 +0,0 @@
-<!-- diátaxis: how-to -->
-<!-- lang: vi -->
-<!-- draft-translation: needs-human-review -->
-
-> ⚠️ **BẢN DỊCH NHÁP — CẦN CON NGƯỜI RÀ SOÁT**
->
-> Đây là bản dịch tiếng Việt do máy tạo ra từ nguồn tiếng Anh tại `../../../../agents/how-to/orchestrator-workflows/analytics-pipeline-workflow.md`.
-> Theo `.gpt-5.4/specs/who-project-documentation-enhancement/requirements.md`, tài liệu tiếng Việt phải do con người dịch trước khi được xem là chính thức. Người rà soát cần kiểm tra, chỉnh sửa thuật ngữ kỹ thuật, và xóa banner này trước khi file trở thành chính thức.
->
-> Theo dõi: [`docs/vi/TRANSLATION-BACKLOG.md`](../../../TRANSLATION-BACKLOG.md)
-
-# Pipeline phân tích Elasticsearch → Grafana → Metabase
-
-> Kết hợp các orchestrator Elastic, Grafana và Metabase để truy vấn log, dựng biểu đồ và phân phối dashboard phân tích.
-
-## Điều kiện tiên quyết
-
-- `vds-scripts` đã được clone và khởi tạo (`./scripts/worktree_uv.sh sync`)
-- `vds-cli doctor` đạt trạng thái xanh cho các profile Elastic, Grafana và Metabase
-- `~/.vds/.env` chứa `ELASTIC_HOST`, `GRAFANA_HOST`, `METABASE_HOST`, và các thông tin xác thực tương ứng
-- Các index pattern đã được tạo trong Elasticsearch (ví dụ: `vds-logs-*`)
-
-## Tổng quan quy trình
-
-```
-Elastic (truy vấn log / xuất dữ liệu)
-    ↓
-Grafana (trực quan hóa số liệu)
-    ↓
-Metabase (phân phối dashboard)
-```
-
-## Bước 1: Truy vấn log trong Elasticsearch
-
-Chạy tìm kiếm log có mục tiêu để trích xuất dữ liệu phân tích thô.
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli elastic search --index "vds-logs-*" \
-  --query '{"bool":{"filter":[{"range":{"@timestamp":{"gte":"now-7d"}}},{"term":{"level":"ERROR"}}]}}' \
-  --size 5000 --output /tmp/elastic-errors.json
-```
-
-Kết quả mong đợi:
-
-```
-[elastic] Index: vds-logs-*
-[elastic] Hits: 3,421
-[elastic] Output: /tmp/elastic-errors.json
-[elastic] Duration: 1.2s
-```
-
-Tổng hợp lỗi theo dịch vụ để phục vụ bước trực quan hóa tiếp theo:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli elastic aggregate --index "vds-logs-*" \
-  --field "service.name" --metric "count" \
-  --time-range "now-7d" --output /tmp/error-agg.json
-```
-
-Kết quả mong đợi:
-
-```
-[elastic] Buckets: 12
-[elastic] Top: audit-orchestrator (847)
-[elastic] Output: /tmp/error-agg.json
-```
-
-## Bước 2: Dựng biểu đồ trong Grafana
-
-Nạp dữ liệu đã tổng hợp vào một datasource Grafana và tạo panel.
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli grafana datasource test --name "vds-elastic"
-```
-
-Kết quả mong đợi:
-
-```
-[grafana] Datasource "vds-cli elastic" status: OK
-[grafana] Version: 10.4.1
-```
-
-Tạo một dashboard với panel time-series từ truy vấn Elastic:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli grafana dashboard create --title "VDS Error Analytics" \
-  --datasource "vds-cli elastic" --panel-type timeseries \
-  --query '{"index":"vds-logs-*","body":{"aggs":{"services":{"terms":{"field":"service.name"}}}}}' \
-  --folder "VDS Operations"
-```
-
-Kết quả mong đợi:
-
-```
-[grafana] Dashboard created: /d/vds-error-analytics
-[grafana] UID: vds-error-analytics
-[grafana] Folder: VDS Operations
-```
-
-Sinh link snapshot để chia sẻ:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli grafana snapshot create --dashboard "vds-error-analytics" \
-  --name "Error Analytics Snapshot $(date +%Y-%m-%d)"
-```
-
-Kết quả mong đợi:
-
-```
-[grafana] Snapshot created: https://grafana.example.com/dashboard/snapshot/vds-error-analytics-2026-04-22
-```
-
-## Bước 3: Xuất dữ liệu phân tích sang Metabase
-
-Đồng bộ tập dữ liệu đã tổng hợp sang Metabase để phục vụ khai thác tự phục vụ.
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli metabase card create --database "vds-analytics" \
-  --name "Weekly Error Distribution" --query-file /tmp/error-agg.json
-```
-
-Kết quả mong đợi:
-
-```
-[metabase] Card created: 2143
-[metabase] Database: vds-analytics
-[metabase] Visualization: table
-```
-
-Thêm card vào dashboard Metabase:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli metabase dashboard add-card --dashboard "VDS Operational Metrics" \
-  --card 2143 --col 0 --row 0
-```
-
-Kết quả mong đợi:
-
-```
-[metabase] Dashboard updated: VDS Operational Metrics
-[metabase] Cards: 8
-```
-
-Công khai dashboard để truy cập public hoặc để nhúng:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli metabase dashboard publish --dashboard "VDS Operational Metrics" \
-  --enable-public-link
-```
-
-Kết quả mong đợi:
-
-```
-[metabase] Public link enabled
-[metabase] URL: https://metabase.example.com/public/dashboard/vds-operational-metrics
-```
-
-## Xử lý sự cố
-
-| Triệu chứng | Nguyên nhân | Cách khắc phục |
-|---------|-------|-----|
-| `elastic search` trả về 0 kết quả | Index pattern không khớp hoặc sai tên trường timestamp | Xác minh index bằng `vds-cli elastic indices list` |
-| `grafana datasource test` thất bại | Thiếu thông tin xác thực hoặc bị chặn kết nối ra ngoài | Kiểm tra `GRAFANA_API_KEY` trong `~/.vds/.env` |
-| `grafana dashboard create` panel rỗng | JSON truy vấn sai định dạng | Xác thực truy vấn bằng `vds-cli elastic search --dry-run` trước |
-| `metabase card create` thất bại | Kết nối database hoặc schema không khớp | Chạy `vds-cli metabase database sync --db "vds-analytics"` |
-| Link dashboard trả về 404 | UID hoặc slug thay đổi sau khi đổi tên | Chạy lại `vds-cli grafana dashboard list --search "VDS"` |

package/skills/vds-skill/vds-scripts/docs/vi/agents/how-to/orchestrator-workflows/code-quality-gate-workflow.md

@@ -1,147 +0,0 @@
-<!-- diátaxis: how-to -->
-<!-- lang: vi -->
-<!-- draft-translation: needs-human-review -->
-
-> ⚠️ **BẢN DỊCH NHÁP — CẦN CON NGƯỜI RÀ SOÁT**
->
-> Đây là bản dịch tiếng Việt do máy tạo ra từ nguồn tiếng Anh tại `../../../../agents/how-to/orchestrator-workflows/code-quality-gate-workflow.md`.
-> Theo `.gpt-5.4/specs/who-project-documentation-enhancement/requirements.md`, tài liệu tiếng Việt phải do con người dịch trước khi được xem là chính thức. Người rà soát cần kiểm tra, chỉnh sửa thuật ngữ kỹ thuật, và xóa banner này trước khi file trở thành chính thức.
->
-> Theo dõi: [`docs/vi/TRANSLATION-BACKLOG.md`](../../../TRANSLATION-BACKLOG.md)
-
-# Quy trình cổng chất lượng mã
-
-> Chạy pipeline chất lượng mã toàn diện kết hợp SonarQube, tuân thủ hexagonal, kiểm tra cấu trúc, và phát hiện phụ thuộc vòng.
-
-## Điều kiện tiên quyết
-
-- `vds-scripts` đã được clone và khởi tạo
-- Server SonarQube đã được cấu hình trong `~/.vds/.env`
-- Repository đích có `pyproject.toml` hoặc `package.json`
-
-## Tổng quan quy trình
-
-```
-SonarQube (phân tích tĩnh)
-    ↓
-Hexagonal (tuân thủ kiến trúc)
-    ↓
-Structure (tổ chức mã nguồn)
-    ↓
-Circular Dependency (vòng lặp import)
-    ↓
-Báo cáo chất lượng tổng hợp
-```
-
-## Bước 1: Phân tích tĩnh SonarQube
-
-Chạy phân tích SonarQube trên repo đích:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli sonarqube analyze --repo vds-scripts --branch main
-```
-
-Kết quả mong đợi:
-
-```
-[sonarqube] Project: vds-scripts
-[sonarqube] Issues: 12 (3 critical, 5 major, 4 minor)
-[sonarqube] Coverage: 78%
-[sonarqube] Duplications: 2.1%
-```
-
-Xuất báo cáo:
-
-```bash
-vds-cli sonarqube report --repo vds-scripts --format json --output sonar-report.json
-```
-
-## Bước 2: Kiểm tra tuân thủ hexagonal
-
-Kiểm tra tính tuân thủ kiến trúc hexagonal:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli hexagonal check --path . --strict
-```
-
-Kết quả mong đợi:
-
-```
-[hexagonal] Checking dependency direction...
-[hexagonal] Port/adapter boundaries: 24
-[hexagonal] Violations: 2
-[hexagonal] Report: hexagonal-report.json
-```
-
-## Bước 3: Kiểm tra cấu trúc
-
-Kiểm tra cấu trúc và tổ chức mã nguồn:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli structure validate --path . --mode target-state
-```
-
-Kết quả mong đợi:
-
-```
-[structure] Validating folder structure...
-[structure] Modules: 18
-[structure] Violations: 1 (missing __init__.py)
-[structure] Report: structure-report.json
-```
-
-## Bước 4: Phát hiện phụ thuộc vòng
-
-Phát hiện vòng lặp import:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli circular-dependency analyze --path . --language python
-```
-
-Kết quả mong đợi:
-
-```
-[circular_dependency] Analyzing imports...
-[circular_dependency] Cycles found: 0
-[circular_dependency] Status: PASS
-```
-
-## Bước 5: Báo cáo chất lượng tổng hợp
-
-Sinh báo cáo chất lượng hợp nhất:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli docs quality-report \
-  --sonar sonar-report.json \
-  --hexagonal hexagonal-report.json \
-  --structure structure-report.json \
-  --circular circular-report.json \
-  --output quality-report.md
-```
-
-## Tích hợp CI
-
-Thêm vào `.github/workflows/quality.yml`:
-
-```yaml
-- name: Code Quality Gate
-  run: |
-    vds-cli sonarqube analyze --repo ${{ github.repository }}
-    vds-cli hexagonal check --path . --strict
-    vds-cli structure validate --path . --mode target-state
-    vds-cli circular-dependency analyze --path . --language python
-```
-
-## Xử lý sự cố
-
-| Triệu chứng | Nguyên nhân | Cách khắc phục |
-|---------|-------|-----|
-| Xác thực SonarQube thất bại | Token hết hạn | Làm mới `SONAR_TOKEN` trong `~/.vds/.env` |
-| Kiểm tra hexagonal quá nghiêm ngặt | Dùng cờ `--strict` | Dùng `--strict=false` để tuân thủ dần |
-| Phụ thuộc vòng báo dương tính giả | Import từ test | Thêm `--exclude tests/` |
-| Kiểm tra cấu trúc thất bại ở module mới | Thiếu cấu hình | Cập nhật `target-state.yaml` |