@ngocsangairvds/vsaf 4.1.8 → 4.1.9

package/skills/vds-skill/vds-scripts/docs/vi/agents/how-to/orchestrator-workflows/confluence-bitbucket-sync-workflow.md

@@ -1,139 +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 từ tài liệu gốc tiếng Anh tại [`../../../../agents/how-to/orchestrator-workflows/confluence-bitbucket-sync-workflow.md`](../../../../agents/how-to/orchestrator-workflows/confluence-bitbucket-sync-workflow.md).
-> Theo `.gpt-5.4/specs/who-project-documentation-enhancement/requirements.md`, tài liệu tiếng Việt phải được con người dịch trước khi được coi là tài liệu chính thức. Một biên dịch viên con người phải rà soát, chỉnh sửa thành ngữ và thuật ngữ kỹ thuật, đồng thời gỡ bỏ biểu ngữ này trước khi tệp trở nên có hiệu lực.
->
-> Theo dõi: [`docs/vi/TRANSLATION-BACKLOG.md`](../../../TRANSLATION-BACKLOG.md) (độ sâu đường dẫn có thể khác — điều chỉnh nếu cần)
-
-# Quy trình đồng bộ Confluence → Bitbucket
-
-> Kiểm định tình trạng tài liệu, đẩy lên Confluence và xác minh liên kết Bitbucket trong một luồng duy nhất.
-
-## Đ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` thành công
-- `~/.vds/.env` chứa `VDS_USERNAME`, `VDS_PASSWORD`, `CONFLUENCE_HOST`
-- Đã biết slug dự án Bitbucket và repo mục tiêu
-
-## Tổng quan quy trình
-
-```
-docs validate (kiểm tra tình trạng)
-    ↓
-confluence sync (đẩy các trang)
-    ↓
-bitbucket verify (kiểm tra liên kết)
-```
-
-## Bước 1: Kiểm định tình trạng tài liệu
-
-Chạy công cụ kiểm định tài liệu để kiểm tra header diátaxis, tính toàn vẹn liên kết và cấu trúc.
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli docs validate --check-diataxis --check-links
-```
-
-Kết quả mong đợi:
-
-```
-[docs] Scanning: docs/agents/
-[docs] Files checked: 42
-[docs] Diátaxis headers: 42/42 PASS
-[docs] Broken links: 0
-[docs] Warnings: 2 (orphaned images)
-[docs] Result: PASS
-```
-
-Chạy kiểm tra nghiêm ngặt hơn trước CI:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli docs validate --check-diataxis --check-links --fail-on-warning
-```
-
-## Bước 2: Đồng bộ lên Confluence
-
-Đẩy tài liệu đã được kiểm định lên không gian Confluence.
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli confluence sync --source docs/agents/how-to/ --space WHO --parent-page 88722450
-```
-
-Kết quả mong đợi:
-
-```
-[confluence] Connected: https://confluence.digital.vn
-[confluence] Pages to sync: 12
-[confluence] Created: 3
-[confluence] Updated: 9
-[confluence] Unchanged: 0
-[confluence] Errors: 0
-[confluence] Sync complete
-```
-
-Đồng bộ một hướng dẫn duy nhất với tiêu đề chỉ định rõ:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli confluence sync --source docs/agents/how-to/first-audit-run.md \
-  --space WHO --parent-page 88722450 --title "First Audit Run"
-```
-
-## Bước 3: Xác minh liên kết Bitbucket
-
-Sau khi các trang Confluence đã hoạt động, xác minh rằng các liên kết repo Bitbucket phân giải đúng.
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli bitbucket verify-links --project vds-scripts --check-confluence-refs
-```
-
-Kết quả mong đợi:
-
-```
-[bitbucket] Repos scanned: 1
-[bitbucket] README links: 14
-[bitbucket] Confluence refs: 6
-[bitbucket] Broken: 0
-[bitbucket] Result: PASS
-```
-
-## Tích hợp CI
-
-Thêm job sau vào `.github/workflows/docs-sync.yml`:
-
-```yaml
-  docs-sync:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - name: Validate docs
-        run: |
-          ./scripts/worktree_uv.sh run --project vds_cli \
-            vds-cli docs validate --check-diataxis --check-links --fail-on-warning
-      - name: Sync to Confluence
-        run: |
-          ./scripts/worktree_uv.sh run --project vds_cli \
-            vds-cli confluence sync --source docs/agents/ --space WHO --parent-page ${{ vars.CONFLUENCE_PARENT_PAGE }}
-      - name: Verify Bitbucket links
-        run: |
-          ./scripts/worktree_uv.sh run --project vds_cli \
-            vds-cli bitbucket verify-links --project vds-scripts --check-confluence-refs
-```
-
-## Xử lý sự cố
-
-| Triệu chứng | Nguyên nhân | Khắc phục |
-|---------|-------|-----|
-| `docs validate` thất bại với diátaxis | Thiếu header `<!-- diátaxis: how-to -->` | Thêm header vào tệp vi phạm và chạy lại |
-| `confluence sync` lỗi xác thực | Thiếu hoặc hết hạn thông tin đăng nhập | Kiểm tra `~/.vds/.env` đối với `VDS_USERNAME` và `VDS_PASSWORD` |
-| `confluence sync` xung đột trang | Trùng tiêu đề trang trong không gian | Dùng ghi đè `--title` hoặc xóa trang trùng thủ công |
-| `bitbucket verify-links` phát hiện tham chiếu hỏng | ID trang Confluence đã thay đổi | Cập nhật các ID trang đang hardcode trong README hoặc tài liệu |
-| Đồng bộ chậm | Các tệp đính kèm ảnh kích thước lớn | Thêm `--skip-attachments` cho đồng bộ chỉ văn bản |

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

@@ -1,151 +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/document-delivery-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 phân phối tài liệu
-
-> Tạo và phân phối tài liệu từ markdown qua các khâu diagram, PDF và Confluence.
-
-## Điều kiện tiên quyết
-
-- `vds-scripts` đã được clone và khởi tạo
-- Thông tin xác thực Confluence trong `~/.vds/.env`
-- File nguồn markdown nằm trong thư mục `docs/`
-
-## Tổng quan quy trình
-
-```
-Markdown (nội dung nguồn)
-    ↓
-Diagrams (sinh hình ảnh)
-    ↓
-PDF (định dạng phân phối)
-    ↓
-Confluence (xuất bản và chia sẻ)
-```
-
-## Bước 1: Chuẩn bị nội dung markdown
-
-Soạn tài liệu bằng markdown có nhúng sơ đồ mermaid:
-
-```markdown
-# Architecture Overview
-
-## System Diagram
-
-```mermaid
-graph TD
-    A[Client] --> B[API Gateway]
-    B --> C[Service A]
-    B --> D[Service B]
-```
-
-## Details
-
-See [API Reference](../reference/api.md).
-```
-
-## Bước 2: Sinh sơ đồ
-
-Render sơ đồ mermaid thành hình ảnh:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli diagrams mermaid --input architecture.md --output diagrams/
-```
-
-Kết quả mong đợi:
-
-```
-[diagrams] Found 2 mermaid blocks
-[diagrams] Rendered: diagrams/diagram-1.svg
-[diagrams] Rendered: diagrams/diagram-2.svg
-```
-
-Sinh sơ đồ C4 nếu cần:
-
-```bash
-vds-cli diagrams c4 --level container --input c4-model.md --output c4-container.png
-```
-
-## Bước 3: Chuyển đổi sang PDF
-
-Sinh PDF từ markdown:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli pdf md2pdf --input architecture.md --output architecture.pdf --template corporate
-```
-
-Kết quả mong đợi:
-
-```
-[pdf] Converting architecture.md...
-[pdf] Applied template: corporate
-[pdf] Output: architecture.pdf (12 pages)
-```
-
-Sinh hàng loạt cho mọi tài liệu:
-
-```bash
-vds-cli pdf batch --input-dir docs/ --output-dir pdfs/ --template corporate
-```
-
-## Bước 4: Xuất bản lên Confluence
-
-Đồng bộ tài liệu lên Confluence:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli confluence sync --input architecture.md --page-id 12345 --space WHO
-```
-
-Kết quả mong đợi:
-
-```
-[confluence] Uploading to space WHO...
-[confluence] Page updated: Architecture Overview
-[confluence] Attachments: 3 images, 1 PDF
-```
-
-## Bước 5: Xác minh và chia sẻ
-
-Kiểm tra nội dung đã xuất bản:
-
-```bash
-vds-cli confluence validate --page-id 12345 --check-links --check-images
-```
-
-Chia sẻ với đội:
-
-```bash
-vds-cli confluence notify --page-id 12345 --channel slack --message "Architecture docs updated"
-```
-
-## Tích hợp CI
-
-Thêm vào `.github/workflows/docs.yml`:
-
-```yaml
-- name: Document Delivery
-  run: |
-    vds-cli diagrams mermaid --input docs/ --output diagrams/
-    vds-cli pdf batch --input-dir docs/ --output-dir pdfs/
-    vds-cli confluence sync --input docs/ --space WHO
-```
-
-## Xử lý sự cố
-
-| Triệu chứng | Nguyên nhân | Cách khắc phục |
-|---------|-------|-----|
-| Render mermaid thất bại | Cú pháp không hợp lệ | Xác thực bằng `vds-cli diagrams validate` |
-| PDF thiếu font | Hệ thống thiếu font | Cài `libgobject-2.0-0` hoặc dùng Docker |
-| Upload Confluence thất bại | Xác thực hết hạn | Làm mới `CONFLUENCE_TOKEN` trong `~/.vds/.env` |
-| Hình ảnh không được đính kèm | Sai đường dẫn | Dùng đường dẫn tương đối từ file markdown |

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

@@ -1,149 +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/memory-progress-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 Memory → theo dõi tiến độ
-
-> Lưu quan sát vào VDS AI Memory, gọi lại ngữ cảnh trước đó, và sinh báo cáo tiến độ để theo dõi mức hoàn thành phase.
-
-## Đ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
-- `~/.vds/.env` chứa thông tin xác thực backend memory (DSN Postgres hoặc đường dẫn file cục bộ)
-
-## Tổng quan quy trình
-
-```
-memory store (lưu quan sát)
-    ↓
-memory recall (truy hồi ngữ cảnh)
-    ↓
-progress report (theo dõi mức hoàn thành)
-```
-
-## Bước 1: Lưu quan sát vào Memory
-
-Lưu các quan sát quan trọng sau mỗi phiên làm việc để các agent về sau có thể tiếp cận.
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli memory store --tag "phase174,spec,fr-3" \
-  --content "FR-3 requires multi-step workflow guides combining 2+ orchestrators"
-```
-
-Kết quả mong đợi:
-
-```
-[memory] Stored observation: obs-20260422-001
-[memory] Tags: phase174, spec, fr-3
-[memory] Content length: 72 characters
-[memory] Timestamp: 2026-04-22T08:00:00Z
-```
-
-Lưu nhiều quan sát từ một phiên làm việc gộp:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli memory store --tag "phase174,audit" \
-  --content "Audit run completed with 3 violations in hexagonal-compliance rules"
-```
-
-## Bước 2: Truy hồi ngữ cảnh trước đó
-
-Trước khi bắt đầu phiên mới, tìm trong memory các công việc liên quan đã thực hiện trước đây.
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli memory search "phase174 workflow guides"
-```
-
-Kết quả mong đợi:
-
-```
-[memory] Query: phase174 workflow guides
-[memory] Results: 2
-[memory] obs-20260422-001 — phase174, spec, fr-3
-[memory] obs-20260422-002 — phase174, audit
-[memory] Retrieved in 0.12s
-```
-
-Truy hồi với bộ lọc tag để thu hẹp phạm vi:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli memory search "fr-3" --tag spec
-```
-
-## Bước 3: Sinh báo cáo tiến độ
-
-Tạo báo cáo tiến độ từ các quan sát đã lưu và trạng thái audit hiện tại.
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli progress report --phase 174 --format markdown
-```
-
-Kết quả mong đợi:
-
-```
-[progress] Phase: 174
-[progress] Spec items: 8/12 complete
-[progress] Audit violations: 3 open
-[progress] Report: /tmp/vds-progress-phase174.md
-```
-
-Sinh báo cáo tổng hợp qua nhiều phase:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli progress report --phase 174,175,176 --format json
-```
-
-Theo dõi mức hoàn thành phase với tích hợp checklist:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli progress checklist --phase 174 --update-status
-```
-
-Kết quả mong đợi:
-
-```
-[checklist] Phase: 174
-[checklist] Items: 12
-[checklist] Completed: 8
-[checklist] Blocked: 1
-[checklist] Not started: 3
-[checklist] State saved to: checklist-progress.state
-```
-
-## Mẹo tự động hóa
-
-Thêm vào shell profile hoặc hook của agent để tự lưu sau mỗi lệnh:
-
-```bash
-vds_memory_store() {
-  local tag="$1"
-  local content="$2"
-  ./scripts/worktree_uv.sh run --project vds_cli \
-    vds-cli memory store --tag "$tag" --content "$content"
-}
-```
-
-## Xử lý sự cố
-
-| Triệu chứng | Nguyên nhân | Cách khắc phục |
-|---------|-------|-----|
-| `memory store` lỗi xác thực | Thiếu DSN hoặc thông tin xác thực | Kiểm tra `~/.vds/.env` cho `VDS_MEMORY_DSN` hoặc đường dẫn cục bộ |
-| `memory search` trả về rỗng | Không có tag hoặc nội dung khớp | Mở rộng truy vấn hoặc kiểm tra các tag đã lưu bằng `memory list` |
-| `progress report` hiển thị dữ liệu cũ | File trạng thái chưa được cập nhật | Chạy `vds-cli progress checklist --update-status` trước |
-| `progress checklist` báo mục bị chặn | Thiếu phụ thuộc hoặc nguyên liệu | Kiểm tra cờ `blocked_by_materials` trong trạng thái checklist |
-| Thao tác memory chậm | Kho quan sát lớn | Thêm `--limit 50` vào lệnh search hoặc xóa bớt quan sát cũ |

package/skills/vds-skill/vds-scripts/docs/vi/agents/how-to/orchestrator-workflows/research-spec-audit-workflow.md

@@ -1,144 +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 từ tài liệu gốc tiếng Anh tại [`../../../../agents/how-to/orchestrator-workflows/research-spec-audit-workflow.md`](../../../../agents/how-to/orchestrator-workflows/research-spec-audit-workflow.md).
-> Theo `.gpt-5.4/specs/who-project-documentation-enhancement/requirements.md`, tài liệu tiếng Việt phải được con người dịch trước khi được coi là tài liệu chính thức. Một biên dịch viên con người phải rà soát, chỉnh sửa thành ngữ và thuật ngữ kỹ thuật, đồng thời gỡ bỏ biểu ngữ này trước khi tệp trở nên có hiệu lực.
->
-> Theo dõi: [`docs/vi/TRANSLATION-BACKLOG.md`](../../../TRANSLATION-BACKLOG.md) (độ sâu đường dẫn có thể khác — điều chỉnh nếu cần)
-
-# Quy trình Research → Spec → Audit
-
-> Kết hợp các điều phối viên research, spec và audit để thu thập bằng chứng, chính thức hóa yêu cầu và kiểm định việc triển khai.
-
-## Đ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` thành công
-- (Các) repo mục tiêu truy cập được qua Bitbucket
-- `~/.vds/.env` chứa `VDS_USERNAME`, `VDS_PASSWORD`, và `OPENAI_API_KEY`
-
-## Tổng quan quy trình
-
-```
-research (thu thập bằng chứng)
-    ↓
-spec (tạo/kiểm định spec)
-    ↓
-audit (thực thi kiểm định)
-```
-
-## Bước 1: Thu thập bằng chứng với Research
-
-Chạy truy vấn research có mục tiêu để thu thập bằng chứng cho tính năng hoặc khoảng trống bạn cần xử lý.
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli research search "hexagonal architecture compliance patterns"
-```
-
-Kết quả mong đợi:
-
-```
-[research] Query: hexagonal architecture compliance patterns
-[research] Sources found: 12
-[research] Top result: https://example.com/hexagonal-guide
-[research] Evidence saved to: /tmp/vds-research-evidence-<timestamp>.json
-```
-
-Chấm điểm chất lượng bằng chứng trước khi tiếp tục:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli research score --evidence /tmp/vds-research-evidence-<timestamp>.json
-```
-
-Kết quả mong đợi:
-
-```
-[score] Total evidence items: 12
-[score] High quality: 8
-[score] Medium quality: 3
-[score] Low quality: 1
-[score] Average score: 0.78
-```
-
-## Bước 2: Tạo hoặc kiểm định Spec
-
-Dùng điều phối viên spec để tạo một spec mới từ bằng chứng research.
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli spec create hexagonal-compliance --evidence /tmp/vds-research-evidence-<timestamp>.json
-```
-
-Kết quả mong đợi:
-
-```
-[spec] Created: .gpt-5.4/specs/hexagonal-compliance/requirements.md
-[spec] Created: .gpt-5.4/specs/hexagonal-compliance/design.md
-[spec] Created: .gpt-5.4/specs/hexagonal-compliance/tasks.md
-[spec] Next: run validation
-```
-
-Kiểm định bộ ba tệp spec:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli spec validate --spec-dir .gpt-5.4/specs/hexagonal-compliance
-```
-
-Kết quả mong đợi:
-
-```
-[validate] requirements.md: PASS
-[validate] design.md: PASS
-[validate] tasks.md: PASS
-[validate] 3/3 files valid
-```
-
-Chạy kiểm tra căn chỉnh:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli spec check-alignment --spec-dir .gpt-5.4/specs/hexagonal-compliance
-```
-
-## Bước 3: Thực thi kiểm định Audit
-
-Chạy điều phối viên audit đối với repo mục tiêu sử dụng spec đã được kiểm định.
-
-```bash
-./scripts/worktree_uv.sh run --project audit_orchestrator \
-  vds-cli audit run --repo vds-scripts --scope full --spec hexagonal-compliance
-```
-
-Kết quả mong đợi:
-
-```
-[audit] Profile: default
-[audit] Scope: full
-[audit] Spec: hexagonal-compliance
-[audit] Rules: 47
-[audit] Violations: 3
-[audit] Report: /tmp/vds-audit-report-<timestamp>.json
-```
-
-Tạo báo cáo hợp nhất:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli research report --evidence /tmp/vds-research-evidence-<timestamp>.json \
-  --audit /tmp/vds-audit-report-<timestamp>.json
-```
-
-## Xử lý sự cố
-
-| Triệu chứng | Nguyên nhân | Khắc phục |
-|---------|-------|-----|
-| `research search` trả về không có kết quả | MCP router không khả dụng hoặc đã hết hạn ngạch Tavily | Chạy `vds-cli research health` để chẩn đoán |
-| `spec validate` báo thiếu FR | `requirements.md` có khoảng trống | Bổ sung các yêu cầu chức năng còn thiếu và chạy lại |
-| `audit run` báo lỗi `--spec not found` | Tên spec không khớp | Dùng đúng tên thư mục spec, hoặc bỏ `--spec` để dùng mặc định |
-| `check-alignment` báo lệch | Design và tasks không đồng bộ | Chạy `vds-cli spec consolidate` rồi kiểm tra lại |