@ngocsangairvds/vsaf 4.0.0 → 4.0.2

package/skills/vds-skill/vds-scripts-skill/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: vds-scripts-skill
+description: Use the WHO VDS scripts ecosystem as the platform entrypoint for routed CLI commands, workspace capabilities, and skill delegation. Use when you need to choose the right vds-cli command family, understand the current WHO scripts surface, or route to the correct specialist skill.
+license: Apache-2.0
+metadata:
+  version: "1.1.0"
+  author: "VDS Platform Team"
+  category: "infrastructure"
+  tags:
+    - cli
+    - routing
+    - orchestrators
+    - platform
+    - who
+---
+
+# VDS Scripts Skill
+
+Use this skill as the **platform-routing entrypoint** for the WHO scripts ecosystem.
+
+The VDS scripts ecosystem lives at `~/.claude/vds-scripts/` (installed via `vsaf global`).
+
+This skill helps you:
+- find the right `vds-cli` command family
+- understand the current WHO scripts workspace surface
+- identify whether a task belongs to a platform command or a specialist skill
+- route humans and AI agents to the correct authoritative source
+
+## When to Use
+
+Use this skill when you need:
+- a quick map of the WHO scripts ecosystem
+- the right command family for a task
+- the right specialist skill for deeper guidance
+- bootstrap guidance for `vds-cli`, environment checks, and command discovery
+- a capability index for current WHO automation surfaces
+
+Do **not** use this skill as the authoritative deep runbook for:
+- audit workflow execution → use `audit-orchestrator-skill`
+- LLM-backed content evaluation → use `llm-analysis-skill`
+- spec authoring/consolidation → use `spec-creation-skill`
+- LSP setup and type-checking workflows → use `lsp-skill`
+- circular dependency analysis → use `circular-dependency-skill`
+
+## Canonical Sources
+
+- Scripts workspace: `~/.claude/vds-scripts/`
+
+## Primary Command Entry Points
+
+```bash
+# Via vds-cli (recommended — MCP-registered)
+vds-cli --help
+vds-cli confluence --help
+vds-cli jira --help
+vds-cli bitbucket --help
+vds-cli git --help
+
+# Direct uv invocation from vds-scripts root
+~/.claude/vds-scripts/scripts/worktree_uv.sh run --directory ~/.claude/vds-scripts --package vds-cli vds-cli --help
+~/.claude/vds-scripts/scripts/worktree_uv.sh run --directory ~/.claude/vds-scripts --package audit_orchestrator vds-audit --help
+~/.claude/vds-scripts/scripts/worktree_uv.sh run --directory ~/.claude/vds-scripts --package spec_orchestrator vds-spec --help
+```
+
+## Platform Command Families
+
+### Bootstrap and discovery
+- `vds-cli env ...`
+- `vds-cli status`
+- `vds-cli doctor`
+- `vds-cli docs ...`
+
+### Integrations
+- `vds-cli jira ...`
+- `vds-cli confluence ...`
+- `vds-cli bitbucket ...`
+- `vds-cli git ...`
+- `vds-cli elastic ...`
+- `vds-cli grafana ...`
+- `vds-cli sonarqube ...`
+- `vds-cli vidp ...` — VIDP third-party gateway (trigger workflows, poll job status)
+
+### Documentation and validation
+- `vds-cli openapi ...`
+- `vds-cli links ...`
+- `vds-cli structure ...`
+- `vds-cli schema ...`
+- `vds-cli pdf ...`
+- `vds-cli diagrams ...`
+- `vds-cli excel ...`
+- `vds-cli google-sheets ...`
+- `vds-markdown ...` via `markdown_orchestrator`
+
+### Development and workflow
+- `vds-cli intellij ...`
+- `vds-cli tasks ...`
+- `vds-cli lsp ...`
+- `vds-cli spec ...`
+- `vds-cli audit ...`
+- `vds-cli circular-dependency ...`
+
+## Specialist Routing Map
+
+- Audit workflow execution and readiness gates → `audit-orchestrator-skill`
+- LLM-assisted doc/content scoring → `llm-analysis-skill`
+- Spec creation and consolidation → `spec-creation-skill`
+- CLI/orchestrator development standards → `cli-development-skill`
+- LSP configuration and usage → `lsp-skill`
+- Circular dependency analysis → `circular-dependency-skill`
+- Research-backed investigation → `research-skill`
+- Structural graph review → `code-review-graph-skill`
+
+## Progressive Disclosure
+
+Use these bundled references for depth:
+- `references/platform-bootstrap.md`
+- `references/capability-index.md`
+- `references/integration-commands.md`
+- `references/validation-commands.md`
+- `references/development-commands.md`
+- `references/specialist-routing.md`
+
+## Notes
+
+- Keep this file concise and routing-oriented; push deeper command catalogs into `references/`.
+- For integrated `~/.claude/vds-scripts` workspace usage, Python 3.10+ is the preferred baseline.
+- After updates, re-run `vsaf global` to sync skills to all agent surfaces.

package/skills/vds-skill/vds-scripts-skill/references/audit-commands.md

@@ -0,0 +1,171 @@
+# Audit Commands — VDS Scripts Skill
+
+Detailed command reference for audit orchestrator operations.
+
+These are interactive/operator command examples. From the umbrella monorepo root, prefer `./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator ...`. Inside a dedicated `vds-scripts` worktree, prefer `./scripts/worktree_uv.sh run --package audit_orchestrator ...`. Maintained shell scripts inside `WHO-project/vds-scripts` should source `scripts/vds_sh_helpers.sh` instead of copying raw operator patterns. Preferred integrated baseline for the `vds-scripts` workspace is Python 3.14+.
+
+## Audit Prep Sequence (Hard-Cut State-First)
+
+```/dev/null/audit-commands-prep-sequence.sh#L1-20
+# 1) Seed centralized state from registry
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator vds-audit parse-registry \
+  --registry-page "<REGISTRY_PAGE_URL_OR_ID>"
+
+# 2) Sync repositories for code evidence
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator vds-audit --json-only sync repos \
+  --bitbucket-project "<BITBUCKET_PROJECT_KEY>" \
+  --project-storage-key "<PROJECT_STORAGE_KEY>"
+
+# 3) Materialize docs + code chunks
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator vds-audit extract-docs \
+  --registry-page "<REGISTRY_PAGE_URL_OR_ID>" \
+  --project-storage-key "<PROJECT_STORAGE_KEY>" \
+  --output-dir "<EVIDENCE_DIR>"
+
+# 4) Hard gate before workflow
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator vds-audit --json-only state readiness \
+  --project "<PROJECT_STORAGE_KEY>" --repo "<REPO_SELECTOR>" \
+  | jq '{ready, docs_chunk_ready, code_chunk_ready}'
+
+# 5) Phase 87 direct project/repo parsing
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator vds-audit --json-only parse-project \
+  --project "<PROJECT_PAGE_ID>" > /tmp/parse-project.json
+
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator vds-audit --json-only parse-repo \
+  --project "<PROJECT_PAGE_ID>" --bitbucket-project "<BITBUCKET_PROJECT_KEY>" \
+  --repo "<REPO_SELECTOR>" > /tmp/parse-repo.json
+
+# 6) Execute workflow with resolved repo seed
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator vds-audit workflow "<LOCAL_REPO_PATH>" \
+  --thread-id "<THREAD_ID>" --canonical-checklist \
+  --checklist-profile "<PROFILE_ID>" \
+  --seed-payload /tmp/parse-repo.json
+```
+
+## Selector Notes
+
+- `parse-project` / `parse-repo` `--project` accepts only Confluence page-id selectors (numeric or URL with `pageId=<ID>`)
+- Checklist precedence: `--checklist-page-id` > `--checklist-profile` > state profile resolution > canonical fallback `88722450`
+- Phase 102 hard-cut: Legacy `CL-NNN:row_N` tokens not parsed; run `state migrate-row-keys --execute` first
+- Phase 90 selector isolation: `parse-project` rejects Bitbucket keys in `--project`; use `parse-repo --bitbucket-project`
+- `parse-repo` returns `repo_coverage` (project-wide) and `selected_repo_coverage` (filtered); use latter for single-repo seeds
+- `sync repos` selectors: `--local` > `--bitbucket-project` > `--github-org` > `--git-url` (precedence)
+
+## Audit Monitoring (Phase 68)
+
+```/dev/null/audit-commands-monitoring.sh#L1-11
+# Preflight credentials
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator vds-audit \
+  --json-only doctor credentials --require-state-dsn
+
+# Dual-source prep gate
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator vds-audit \
+  --json-only state readiness --project "<PROJECT_KEY>" --repo "<REPO_KEY>" \
+  | jq '{ready, docs_chunk_ready, code_chunk_ready, hierarchy_ready}'
+
+# Follow runtime logs
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator vds-audit \
+  doctor logs-follow --follow --tail 200 --audit-id "<AUDIT_ID>" --json
+
+# Crawl diagnostics (Phase 80)
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator vds-audit \
+  doctor crawl-status --project-storage-key "<PROJECT_KEY>"
+```
+
+## Corpus Lifecycle (Phase 94)
+
+```bash
+# Dry-run purge
+vds-audit --json-only corpus purge --project "<PROJECT_KEY>"
+
+# Execute purge with advisory lock
+vds-audit --json-only corpus purge --project "<PROJECT_KEY>" --execute
+
+# Keep latest, purge older
+vds-audit corpus purge --project "<PROJECT_KEY>" --keep-latest --execute
+
+# Backfill metadata
+vds-audit --json-only corpus backfill-metadata --project "<PROJECT_KEY>"
+
+# Health diagnostics
+vds-audit --json-only doctor corpus-status --project "<PROJECT_KEY>"
+
+# Force full re-ingest
+vds-audit extract-docs --project-storage-key "<PROJECT_KEY>" \
+  --force-full-reingest --execute
+```
+
+## DSPy Judge & Gold Dataset (Phase 108)
+
+DSPy is **enabled by default**. No `--use-dspy` flag needed.
+
+```bash
+# Workflow with DSPy judge (default)
+vds-audit workflow "<REPO_PATH>" --thread-id "<THREAD_ID>" --canonical-checklist
+
+# Disable DSPy explicitly
+vds-audit workflow "<REPO_PATH>" --thread-id "<THREAD_ID>" --canonical-checklist --no-use-dspy
+
+# Build gold dataset
+vds-audit build-gold-dataset [--search-root <dir>] [--output <path>] \
+  [--checklist-aware] [--category-balance] [--benchmark-slice]
+```
+
+**Key Environment Variables**:
+- `VDS_AUDIT_FEATURES__DSPY_ENABLED` (default: `true`)
+- `VDS_AUDIT_DSPY_JUDGE_MAX_INVOCATIONS_PER_RUN` (default: `20`)
+- `VDS_AUDIT_LLM__DSPY_JUDGE_LOW_CONFIDENCE_THRESHOLD` (default: `0.65`)
+- `VDS_AUDIT_DSPY_ASSERTIONS_ENABLED` (default: `true`)
+
+## Multi-Provider Runs (Phase 107)
+
+```/dev/null/audit-commands-multi-provider.sh#L1-21
+# Alibaba-openai (qwen3.5-plus)
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator \
+  vds-audit workflow "<REPO_PATH>" \
+  --profile alibaba-openai \
+  --project-storage-key "<PROJECT_STORAGE_KEY>" \
+  --thread-id "<THREAD_ID>" \
+  --canonical-checklist \
+  --target "CL-004,CL-001"
+
+# Z.ai-openai (glm-5)
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator \
+  vds-audit workflow "<REPO_PATH>" \
+  --profile zai-openai \
+  --project-storage-key "<PROJECT_STORAGE_KEY>" \
+  --thread-id "<THREAD_ID>" \
+  --canonical-checklist \
+  --target "CL-004,CL-001"
+
+# Gemini (via local proxy)
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator \
+  vds-audit workflow "<REPO_PATH>" \
+  --profile antigravity-gemini \
+  --project-storage-key "<PROJECT_STORAGE_KEY>" \
+  --thread-id "<THREAD_ID>" \
+  --canonical-checklist \
+  --target "CL-004,CL-001"
+```
+
+Non-Claude profiles have increased budgets: `MAX_TURNS=32`, `MAX_TOOL_CALLS=96`.
+
+For single-row reruns such as `CL-002`, keep the same workflow shape and pass `--target CL-002`. Do not use unsupported legacy selectors such as `--check-ids` or `--targeted-rows`.
+
+## System Documentation (Phase 106)
+
+```bash
+# Publish 6-page Vietnamese hierarchy
+vds-audit publish-system-doc --project "<PROJECT_ID>" --sync-policy if-changed
+
+# Force re-publish
+vds-audit publish-system-doc --project "<PROJECT_ID>" --sync-policy force
+```
+
+Hierarchy pages:
+- Root: Tài liệu Hệ thống Audit
+  - 📐 Công nghệ & Kiến trúc
+  - ⚙️ Quy trình Vận hành
+  - 📊 Kết quả Audit & Chỉ số
+  - 🔧 Hướng dẫn Cài đặt & Cấu hình
+  - 📖 Tham chiếu Kỹ thuật

package/skills/vds-skill/vds-scripts-skill/references/capability-index.md

@@ -0,0 +1,34 @@
+# Capability Index
+
+This index maps the current WHO scripts ecosystem at a platform-routing level.
+
+## Routed command surfaces
+
+- bootstrap: `env`, `status`, `doctor`, `docs`
+- integrations: `jira`, `confluence`, `bitbucket`, `git`, `elastic`, `grafana`, `sonarqube`
+- docs/validation: `openapi`, `links`, `structure`, `schema`, `pdf`, `diagrams`, `excel`, `google-sheets`
+- development/workflow: `intellij`, `tasks`, `lsp`, `spec`, `audit`, `circular-dependency`
+
+## Standalone workspace capabilities
+
+- `markdown_orchestrator` for markdown lint/format workflows
+- `hexagonal_orchestrator` for architecture/compliance support
+- `mcp_server` for MCP/server-related support
+- `multi_agent_orchestrator` for multi-agent execution support
+
+## Shared/internal support layers
+
+- `vds_cli_common`
+- `vds_hooks`
+
+## Skills ecosystem linkage
+
+The WHO skills catalog complements the scripts workspace with specialist skills such as:
+- `audit-orchestrator-skill`
+- `llm-analysis-skill`
+- `spec-creation-skill`
+- `research-skill`
+- `lsp-skill`
+- `circular-dependency-skill`
+
+Use this index with `specialist-routing.md` and the scripts docs routing matrix.

package/skills/vds-skill/vds-scripts-skill/references/development-commands.md

@@ -0,0 +1,12 @@
+# Development Commands
+
+Representative WHO development/workflow command families:
+
+- `vds-cli intellij ...`
+- `vds-cli tasks ...`
+- `vds-cli lsp ...`
+- `vds-cli spec ...`
+- `vds-audit ...`
+- `vds-cli circular-dependency ...`
+
+These families often route into specialist skills for deeper guidance.

package/skills/vds-skill/vds-scripts-skill/references/google-sheets.md

@@ -0,0 +1,71 @@
+# Google Sheets Commands — VDS Scripts Skill
+
+Standalone package with 10 commands and full VDS CLI standards.
+
+## Commands
+
+```bash
+# List worksheets
+vds-cli google-sheets list-worksheets \
+  --spreadsheet-url <url> --auth-method service_account
+
+# Read a worksheet
+vds-cli google-sheets read \
+  --spreadsheet-url <url> --sheet-name "Sheet1" --auth-method service_account
+
+# Read a limited range
+vds-cli google-sheets read \
+  --spreadsheet-url <url> --sheet-name "Sheet1" --range A1:F10
+
+# Write values to a range
+vds-cli google-sheets write \
+  --spreadsheet-url <url> --sheet-name "Sheet1" --range "A1:B2" \
+  --values-json '[["a","b"],["c","d"]]'
+
+# Append rows
+vds-cli google-sheets append \
+  --spreadsheet-url <url> --sheet-name "Sheet1" --values-json '[["new","row"]]'
+
+# Clear a range
+vds-cli google-sheets clear \
+  --spreadsheet-url <url> --sheet-name "Sheet1" --range "A1:Z100"
+
+# Create spreadsheet
+vds-cli google-sheets create-spreadsheet --title "New Spreadsheet"
+
+# Create worksheet
+vds-cli google-sheets create-worksheet \
+  --spreadsheet-url <url> --title "NewSheet" --rows 100 --cols 26
+
+# Delete worksheet
+vds-cli google-sheets delete-worksheet \
+  --spreadsheet-url <url> --sheet-name "SheetToDelete"
+
+# Export to CSV/XLSX
+vds-cli google-sheets export \
+  --spreadsheet-url <url> --sheet-name "Sheet1" --output data.csv --format csv
+
+# JSON output mode (all commands)
+vds-cli google-sheets -- --json-only read \
+  --spreadsheet-url <url> --sheet-name "Sheet1"
+```
+
+## Authentication
+
+**Defaults**:
+- Service account credentials: use the explicit path/config option when available; otherwise the active Unix-like default is `~/.vds/google_credentials.json`
+- API key: `VDS_GOOGLE_API_KEY` or, under the active Unix-like default, `~/.vds/google_api_key.txt`
+
+**Auth methods**:
+- `service_account` - Uses service account JSON file
+- `api_key` - Uses API key from env or file
+
+## Full Command Prefix
+
+Interactive monorepo-root usage commonly uses:
+
+```bash
+vds-cli google-sheets <command>
+# Or direct uv invocation:
+~/.claude/vds-scripts/scripts/worktree_uv.sh run --directory ~/.claude/vds-scripts --package vds-cli vds-cli google-sheets <command>
+```

package/skills/vds-skill/vds-scripts-skill/references/integration-commands.md

@@ -0,0 +1,17 @@
+# Integration Commands
+
+vds Representative WHO integration command families.
+
+These examples use `vds-cli` (MCP-registered entrypoint). For direct uv invocation, prefer `~/.claude/vds-scripts/scripts/worktree_uv.sh run --directory ~/.claude/vds-scripts --package <uv-package-name> ...`.
+
+- `vds-cli jira ...`
+  - JQL search example: `vds-cli jira search "project = CBDC ORDER BY updated DESC" --limit 5 --json-only`
+  - Note: `vds-jira-cli search` now accepts `--json-only` as a command-local flag after `search`, in addition to the global pre-subcommand form.
+- `vds-cli confluence ...`
+- `vds-cli bitbucket ...`
+- `vds-cli git ...`
+- `vds-cli elastic ...`
+- `vds-cli grafana ...`
+- `vds-cli sonarqube ...`
+
+Use the scripts workspace reference docs for deeper command examples.

package/skills/vds-skill/vds-scripts-skill/references/platform-bootstrap.md

@@ -0,0 +1,31 @@
+# Platform Bootstrap
+
+Use this guide when you need to enter the WHO scripts ecosystem and choose the first command to run.
+
+## Canonical entrypoints
+
+- Interactive monorepo-root usage:
+  - `./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package vds-cli vds-cli --help`
+  - `./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package vds-cli vds-cli env status`
+  - `./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package vds-cli vds-cli status`
+  - `./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package vds-cli vds-cli doctor`
+- Dedicated `vds-scripts` worktree usage:
+  - `./scripts/worktree_uv.sh run --package vds_cli vds-cli --help`
+  - `./scripts/worktree_uv.sh run --package vds_cli vds-cli env status`
+  - `./scripts/worktree_uv.sh run --package vds_cli vds-cli status`
+  - `./scripts/worktree_uv.sh run --package vds_cli vds-cli doctor`
+- Maintained shell scripts should not copy those raw forms. They should source `scripts/vds_sh_helpers.sh` and use the helper contract (`vds_uv_run_package`, `vds_uv_sync_package`, `vds_uv_sync_all`).
+- Preferred integrated baseline for the `WHO-project/vds-scripts` workspace is Python 3.14+.
+
+## Common first steps
+
+1. Check environment readiness with `vds-cli env status`
+2. Check routed-service availability with `vds-cli status` and `vds-cli doctor`
+3. Decide whether the task belongs to:
+   - a platform command family
+   - a specialist CLI such as `vds-audit` or `vds-spec`
+   - a specialist skill such as `audit-orchestrator-skill`
+
+## When to stop using the platform skill
+
+If the task becomes specialist or phase-sensitive, route to the specialist skill rather than extending the platform path.

package/skills/vds-skill/vds-scripts-skill/references/specialist-routing.md

@@ -0,0 +1,14 @@
+# Specialist Routing
+
+Use this routing map when the platform skill identifies a specialist domain.
+
+| Intent | Preferred Skill | Why |
+|-------|------------------|-----|
+| Run audit workflows, readiness checks, reruns, uploads | `audit-orchestrator-skill` | Phase-aware audit guidance lives there |
+| Evaluate README/API docs/security docs with LLM support | `llm-analysis-skill` | Specialist content-evaluation guidance lives there |
+| Create or consolidate specs | `spec-creation-skill` | Owns spec workflow and alignment practices |
+| Develop or update CLI/orchestrator packages | `cli-development-skill` | Owns Typer/JSON/CLI package standards |
+| Configure or use LSPs | `lsp-skill` | Owns LSP tooling guidance |
+| Analyze cross-repo dependency cycles | `circular-dependency-skill` | Owns cycle-analysis workflow |
+| Research with local + web sources | `research-skill` | Owns research-first workflow |
+| Build structural graph context | `code-review-graph-skill` | Companion graph-analysis workflow |

package/skills/vds-skill/vds-scripts-skill/references/validation-commands.md

@@ -0,0 +1,15 @@
+# Validation Commands
+
+Representative WHO validation and docs command families:
+
+- `vds-cli openapi ...`
+- `vds-cli links ...`
+- `vds-cli structure ...`
+- `vds-cli schema ...`
+- `vds-cli pdf ...`
+- `vds-cli diagrams ...`
+- `vds-cli excel ...`
+- `vds-cli google-sheets ...`
+- `vds-markdown ...`
+
+Use specialist docs or package READMEs for deeper command coverage.