@ngocsangairvds/vsaf 4.0.6 → 4.0.7

package/skills/vds-skill/vds-scripts/.importlinter

@@ -0,0 +1,86 @@
+[importlinter]
+# Root packages that participate in contracts. Kept to workspace members so
+# `lint-imports` resolves them in the workspace venv without extra sync steps.
+# TSK-7.12b will expand this set to include `vds_platform_core` once that
+# package is added to `tool.uv.workspace.members` (part of TSK-7.12a scope).
+root_packages =
+    vds_agent_core
+    vds_cli_common
+    vds_platform_core
+include_external_packages = True
+
+# --- No-op seed contract ---
+#
+# TSK-7.0 (Phase 7, v24.2.0) installs import-linter and seeds this file with a
+# contract that always passes, so CI can wire up `lint-imports` before
+# TSK-7.12b adds the real layering invariant.
+#
+# TSK-7.12b will append a "forbidden" contract of the form:
+#
+#   [importlinter:contract:platform-core-no-vds-cli-common]
+#   name = platform_core must not depend on vds_cli_common
+#   type = forbidden
+#   source_modules = vds_platform_core
+#   forbidden_modules = vds_cli_common
+#
+# That contract makes the Layer 1 -> Layer 2 inversion (DEFAULT_ENV_PATHS lazy
+# import at config.py:20-23) a build-break rather than a runtime-only warning.
+
+[importlinter:contract:platform-core-no-vds-cli-common]
+name = platform_core must not depend on vds_cli_common
+type = forbidden
+source_modules =
+    vds_platform_core
+forbidden_modules =
+    vds_cli_common
+
+# --- Phase 9 FR-9 boundary contract (added 2026-04-30) ---
+#
+# Encodes the spec mandate from `vds-agent-core-alignment` requirements.md
+# that `vds_agent_core` depends ONLY on `vds_cli_common` + `vds_platform_core`.
+# Wave 33 dependency-chain audit verified the runtime state is clean; this
+# contract makes future regressions a CI build-break instead of a manual-grep
+# discovery. Replaces the `phase7-seed-noop` seed (deleted 2026-04-30).
+#
+# Forbidden modules: every workspace orchestrator. If a new orchestrator
+# joins the workspace, add it here.
+
+[importlinter:contract:agent-core-isolation]
+name = vds_agent_core must not depend on any orchestrator
+type = forbidden
+source_modules =
+    vds_agent_core
+forbidden_modules =
+    vds_audit_orchestrator
+    vds_memory_orchestrator
+    vds_scheduler_orchestrator
+    vds_multi_agent_orchestrator
+    vds_progress_report_orchestrator
+    vds_research_orchestrator
+    vds_spec_orchestrator
+    vds_task_orchestrator
+    vds_evolution
+    vds_confluence_orchestrator
+    vds_bitbucket_orchestrator
+    vds_jira_orchestrator
+    vds_grafana_orchestrator
+    vds_sonarqube_orchestrator
+    vds_elastic_orchestrator
+    vds_brd_orchestrator
+    vds_circular_dependency_orchestrator
+    vds_db_query_orchestrator
+    vds_excel_orchestrator
+    vds_git_orchestrator
+    vds_google_sheets_orchestrator
+    vds_hexagonal_orchestrator
+    vds_intellij_orchestrator
+    vds_links_orchestrator
+    vds_lsp_orchestrator
+    vds_markdown_orchestrator
+    vds_metabase_orchestrator
+    vds_openapi_orchestrator
+    vds_pdf_orchestrator
+    vds_public_interface_boundary_orchestrator
+    vds_structure_orchestrator
+    vds_sync_orchestrator
+    vds_cli

package/skills/vds-skill/vds-scripts/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "code-review-graph": {
+      "command": "uvx",
+      "args": [
+        "code-review-graph",
+        "serve"
+      ]
+    }
+  }
+}

package/skills/vds-skill/vds-scripts/.pre-commit-config.yaml

@@ -0,0 +1,62 @@
+# Pre-commit configuration for WHO-project/vds-scripts.
+#
+# The local hook below was introduced after commit 4e2cd398 to prevent
+# re-committing the antipatterns that crashed Bitbucket Server's /browse UI
+# with "500 UNKNOWN": macOS .nosync symlinks, absolute-path symlinks,
+# Finder rename-conflict artifacts, and committed worktree directories.
+#
+# Install once per checkout:
+#   uv tool install pre-commit   # or: pipx install pre-commit
+#   pre-commit install
+repos:
+  - repo: local
+    hooks:
+      - id: check-invalid-symlinks
+        name: Block invalid symlinks, committed worktrees, and macOS rename-conflict files
+        entry: python3 scripts/check-invalid-symlinks.py
+        language: system
+        pass_filenames: false
+        always_run: true
+        stages: [pre-commit]
+
+      - id: agent-core-isolation
+        name: vds_agent_core must not import orchestrators (FR-10.12)
+        entry: .venv/bin/lint-imports --contract agent-core-isolation
+        language: system
+        pass_filenames: false
+        stages: [pre-commit]
+
+      - id: vds-agent-core-no-legacy-typing
+        name: vds_agent_core must use modern typing (no UP006/UP007/UP035) (FR-10.13)
+        entry: .venv/bin/ruff check vds_agent_core/src/ --select UP006,UP007,UP035 --quiet
+        language: system
+        pass_filenames: false
+        stages: [pre-commit]
+
+      - id: vds-agent-core-use-pathlib
+        name: vds_agent_core must use pathlib not os.path (FR-10.13)
+        entry: .venv/bin/ruff check vds_agent_core/src/ --select PTH --quiet
+        language: system
+        pass_filenames: false
+        stages: [pre-commit]
+
+      - id: vds-agent-core-no-debug-markers
+        name: vds_agent_core src must not contain TODO/FIXME/XXX/HACK (FR-10.13)
+        entry: python3 scripts/check-no-debug-markers.py
+        language: system
+        pass_filenames: false
+        stages: [pre-commit]
+
+      - id: vds-agent-core-future-annotations
+        name: vds_agent_core src (non-init) must have from __future__ import annotations (FR-10.13)
+        entry: python3 scripts/check-future-annotations.py
+        language: system
+        pass_filenames: false
+        stages: [pre-commit]
+
+      - id: vds-agent-core-no-unittest
+        name: vds_agent_core tests must not use unittest.TestCase or self.assert* (FR-10.13)
+        entry: python3 scripts/check-no-unittest.py
+        language: system
+        pass_filenames: false
+        stages: [pre-commit]

package/skills/vds-skill/vds-scripts/.ruffignore

@@ -0,0 +1,3 @@
+# Ruff ignore patterns (gitignore-style)
+# Intentional non-compliant fixtures that cause E902 syntax errors
+**/python-noncompliant/**

package/skills/vds-skill/vds-scripts/.secrets.baseline

@@ -0,0 +1,133 @@
+{
+  "version": "1.5.0",
+  "plugins_used": [
+    {
+      "name": "ArtifactoryDetector"
+    },
+    {
+      "name": "AWSKeyDetector"
+    },
+    {
+      "name": "AzureStorageKeyDetector"
+    },
+    {
+      "name": "Base64HighEntropyString",
+      "limit": 4.5
+    },
+    {
+      "name": "BasicAuthDetector"
+    },
+    {
+      "name": "CloudantDetector"
+    },
+    {
+      "name": "DiscordBotTokenDetector"
+    },
+    {
+      "name": "GitHubTokenDetector"
+    },
+    {
+      "name": "GitLabTokenDetector"
+    },
+    {
+      "name": "HexHighEntropyString",
+      "limit": 3.0
+    },
+    {
+      "name": "IbmCloudIamDetector"
+    },
+    {
+      "name": "IbmCosHmacDetector"
+    },
+    {
+      "name": "IPPublicDetector"
+    },
+    {
+      "name": "JwtTokenDetector"
+    },
+    {
+      "name": "KeywordDetector",
+      "keyword_exclude": ""
+    },
+    {
+      "name": "MailchimpDetector"
+    },
+    {
+      "name": "NpmDetector"
+    },
+    {
+      "name": "OpenAIDetector"
+    },
+    {
+      "name": "PrivateKeyDetector"
+    },
+    {
+      "name": "PypiTokenDetector"
+    },
+    {
+      "name": "SendGridDetector"
+    },
+    {
+      "name": "SlackDetector"
+    },
+    {
+      "name": "SoftlayerDetector"
+    },
+    {
+      "name": "SquareOAuthDetector"
+    },
+    {
+      "name": "StripeDetector"
+    },
+    {
+      "name": "TelegramBotTokenDetector"
+    },
+    {
+      "name": "TwilioKeyDetector"
+    }
+  ],
+  "filters_used": [
+    {
+      "path": "detect_secrets.filters.allowlist.is_line_allowlisted"
+    },
+    {
+      "path": "detect_secrets.filters.common.is_ignored_due_to_verification_policies",
+      "min_level": 2
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_indirect_reference"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_likely_id_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_lock_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_not_alphanumeric_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_potential_uuid"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_prefixed_with_dollar_sign"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_sequential_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_swagger_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_templated_secret"
+    },
+    {
+      "path": "detect_secrets.filters.regex.should_exclude_file",
+      "pattern": [
+        ".*"
+      ]
+    }
+  ],
+  "results": {},
+  "generated_at": "2026-01-29T05:10:47Z"
+}

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

@@ -0,0 +1,250 @@
+# AGENTS.md — VDS Scripts Workspace
+
+> Python automation workspace for VDS orchestrators and routed CLI commands.
+
+## Scope
+
+- Repository: `WHO-project/vds-scripts`
+- Primary responsibilities:
+  - `vds-cli` routed command surface
+  - audit/spec/task/progress/research/evolution orchestrators
+  - shared runtime and environment contracts
+- This file is Tier-0 operator contract (keep concise). Deep command catalogs and phase details live in docs references.
+
+## Repo Boundary
+
+This repo holds **runtime Python only** — CLI entry points, orchestrators, MCP
+servers, platform abstractions, agent-core libraries, evolution loops.
+Claude-Code-facing artifacts (skills, hook plugins, sync machinery, governance
+docs) live in `WHO-project/vds-skills/`.
+
+Canonical rules: `who-ecosystem-alignment` Phase 4 FR-8 (Repo purpose) and FR-9
+(Direction of dependency: skills may reference vds-scripts entry points;
+vds-scripts must build, test, and run with **zero** vds-skills artifacts
+present). FR-11 forbids `.claude/skills/<name>/` directories here. FR-12
+forbids new hook packages here (canonical hook surface is
+`vds-skills/plugins/vds-hooks-*/`).
+
+## Quick Start
+
+```bash
+cd WHO-project/vds-scripts
+
+# CLI router — unified entry point for all operations
+./scripts/worktree_uv.sh run --project vds_cli vds-cli --help
+./scripts/worktree_uv.sh run --project vds_cli vds-cli env status
+./scripts/worktree_uv.sh run --project vds_cli vds-cli status
+./scripts/worktree_uv.sh run --project vds_cli vds-cli doctor
+
+# Specialist services (all route through vds-cli)
+./scripts/worktree_uv.sh run --project vds_cli vds-cli audit --help
+./scripts/worktree_uv.sh run --project vds_cli vds-cli spec --help
+./scripts/worktree_uv.sh run --project vds_cli vds-cli evolution --help
+```
+
+## Unified Routing Contract
+
+**`vds-cli` is the single canonical entry point** for all user-facing orchestrator operations.
+
+- All commands route through `./scripts/worktree_uv.sh run --project vds_cli vds-cli <service> <command> [args]`.
+- `pyproject.toml [project.scripts]` are router implementation detail — not user-facing contracts.
+- Internal scripts (e.g., `vds-evolution`) are backend mechanisms invoked by the router, not directly by users.
+
+## Rules
+
+- Use `./scripts/worktree_uv.sh run --project vds_cli vds-cli ...` for worktree-safe Python execution.
+- Runtime is Postgres-first. Do not add filesystem fallback for audit state or evidence.
+- Use VDS SDK surfaces for Confluence/Bitbucket operations.
+- Keep phase history and long command narratives out of AGENTS.md.
+
+### Testing Rules
+
+- Tests must mock all external services (Confluence, Bitbucket, LLM providers, HTTP endpoints).
+- Control env vars with `monkeypatch.setenv` / `delenv`; do not read real local credentials.
+- Prefer focused tests for changed modules during development; run broad suites at merge gates.
+
+### Phase Numbering & Branch Naming
+
+Phase numbers are **per-spec local** structural labels, not monorepo-global tags. The same number can mean different things in different specs (e.g., `## Phase 219` in `vds-ai-memory` ≠ `## Phase 219` in `ecosystem-scheduling`). To prevent silent branch-namespace collisions when sessions run in parallel, new phase branches MUST use the prefix `<spec-prefix>-phase<N>`:
+
+- `vai-phase219` — vds-ai-memory (`vai`)
+- `eco-phase5` — ecosystem-infrastructure-evolution (`eco`)
+- `audit-phase6` — audit-orchestrator (`audit`)
+- `core-phase172` — vds-agent-core-alignment (`core`)
+
+Commit messages retain the narrative `phase<N>` form for readability. Existing un-prefixed branches (e.g., `phase218`, `phase219/...`) are grandfathered; the prefix rule applies prospectively. When starting a new phase, check the spec's `requirements.md` for the next free phase number within that spec, then `git branch -a | grep <spec-prefix>-phase<N>` before creating the branch — collision is now diagnosable by name.
+
+### Active Spec Sync
+
+vds-ai-memory: **1547 tests**, spec v20.22.0 (Phase 228/229/230/231 Finalized, Phase 232 Blocked — dedup never ran, max_groups=10, embed degraded)
+
+### Containerization Policy
+
+| Command Category                | Runtime                         | Examples                                                                       |
+| ------------------------------- | ------------------------------- | ------------------------------------------------------------------------------ |
+| **Host-only** (never in Docker) | Host filesystem                 | `vds-cli skills sync`, `git commit/rebase`, `vds-cli spec create`              |
+| **Host-only**                   | Host credentials/env            | `vds-cli memory store/search`, `./scripts/worktree_uv.sh`                      |
+| **Container-eligible**          | Docker                          | `vds-cli audit workflow`, `vds-cli research search`, `vds-cli confluence sync` |
+| **Hybrid**                      | Container (read) + Host (write) | `vds-cli progress report` (read DB, write reports), `vds-cli pdf convert`      |
+
+`vds-skills` remains container-free. Skill sync must run on host.
+
+### Scheduler Architecture (Single-Scheduler Operator Note, post-2026-04-24)
+
+The VDS ecosystem now has **one** periodic-task scheduler: **`scheduler_orchestrator`** (DBOS-backed, in `scheduler_orchestrator/`). Celery Beat was retired by ADR-14 on 2026-04-24 (commit `a0ba4179`); audit trail at `scheduler_orchestrator/CLOSURE-v2.0.18.md` (Phase 0 of `.gpt-5.4/specs/vds-scheduler/`).
+
+| Concern                                  | Owner                                                                | Notes                                                                                                                                                                                                                                                                    |
+| ---------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| All periodic schedules (cron + interval) | `scheduler_orchestrator` (DBOS)                                      | Includes the 6 ex-Celery-Beat memory-evolution tasks (`memory.evolution.{dispatch,sweep,replay-dlq}`, `mem0.{resolve-pending-ids,repush-stalled,repush-local-only}`) plus audit drift scans, chain triggers, event-bus dispatch, and scheduled agent-step workflows      |
+| Ad-hoc Celery task dispatch              | Celery worker in `memory_orchestrator/` (worker only — beat retired) | The worker plumbing (`memory_evolution/celery_app.py` + `celery_entrypoint.py`) is intentionally retained per `scheduler_orchestrator/CLOSURE-v2.0.18.md` §Scope Clarification, for explicit `.delay()` / `.send_task()` dispatch from production code. Not a scheduler. |
+| Kill switch                              | `VDS_SCHEDULER_ENABLED=false` (default)                              | Disables `scheduler_orchestrator` completely. Celery worker dispatch is unaffected.                                                                                                                                                                                      |
+
+**Kill-switch rule**: `VDS_SCHEDULER_ENABLED=false` (the default in `~/.vds/.env`) keeps `scheduler_orchestrator` dormant. Set `VDS_SCHEDULER_ENABLED=true` only when the scheduler service is intentionally started; this activates 7+ DBOS schedules (6 ex-Celery memory-evolution + `evolution.auto-promote` + the autoscaler tick).
+
+- **Ecosystem Daily Report** (`ecosystem.daily.report`): Runs at 06:00 UTC daily on `ops-default` queue. Collects git activity, scheduler health, event bus metrics, queue depths. Writes Markdown to `reports/ecosystem/`, persists to `sched.ecosystem_report_runs`, publishes `ecosystem.daily.completed`/`.failed` events. Config: `VDS_ECOSYSTEM_DAILY__*` env vars. Spec: `.gpt-5.4/specs/ecosystem-daily-report/`.
+
+**What is NOT a scheduler anymore**: Celery Beat (container removed from the legacy mem0-deploy stack; the unified `docker/docker-compose.services.yml` is beat-free by design; `beat_schedule` is empty `{}`). Tests asserting Celery Beat schedule registrations were updated in v2.0.10 to assert post-retirement empty state. The legacy compose files were retired to `docker/legacy/` in P3 + P4 WP-4.0; that directory was removed in spec v2.15.12 per the no-legacy directive — recover via git history if rollback is ever needed.
+
+## Entry Points
+
+All services route through a single entry:
+
+```bash
+vds-cli <service> <command> [args]
+```
+
+**Core service families** (non-exhaustive):
+
+- `vds-cli audit ...` — Audit operations (repo, project, multi-project)
+- `vds-cli spec ...` — Spec lifecycle (create, validate, consolidate)
+- `vds-cli tasks ...` — Task orchestrator
+- `vds-cli progress ...` — Progress reports
+- `vds-cli research ...` — Research orchestrator
+- `vds-cli memory ...` — Memory operations
+- `vds-cli evolution ...` — Evolution loop
+- `vds-cli confluence ...` — Confluence operations
+- `vds-cli bitbucket ...` — Bitbucket operations
+- `vds-cli git ...` — Git orchestrator
+- `vds-cli jira ...` — JIRA operations
+- `vds-cli db-query ...` — Database queries
+- `vds-cli grafana ...` — Grafana operations
+- `vds-cli sonarqube ...` — SonarQube operations
+- `vds-cli lsp ...` — LSP operations
+- `vds-cli elastic ...` — Elasticsearch operations
+- `vds-cli pdf ...` — PDF generation
+- `vds-cli diagrams ...` — Diagram generation
+- `vds-cli schema ...` — Schema conversion
+- `vds-cli excel ...` — Excel operations
+- `vds-cli google-sheets ...` — Google Sheets operations
+- `vds-cli circular-dependency ...` — Circular dependency analysis
+- `vds-cli openapi ...` — OpenAPI operations
+- `vds-cli links ...` — Link validation
+- `vds-cli structure ...` — Structure validation
+- `vds-cli brd ...` — BRD coverage
+- `vds-cli intellij ...` — IntelliJ operations
+- `vds-cli metabase ...` — Metabase operations
+- `vds-cli hexagonal ...` — Hexagonal compliance
+- `vds-cli markdown ...` — Markdown operations
+- `vds-cli mcp ...` — MCP server operations
+- `vds-cli multi-agent ...` — Multi-agent operations
+- `vds-cli public-interface ...` — Public interface boundary
+- `vds-cli scheduler ...` — Ecosystem scheduler (schedule/event/chain ops); requires `VDS_SCHEDULER_ENABLED=true`
+- `vds-cli telegram ...` — Telegram bridge ops (DISABLED 2026-04-30 — aiogram pydantic conflict; restore when aiogram >=3.28.0). Bridge code present at `telegram_bridge/`, 102 tests pass offline.
+
+## Search & Navigation
+
+- Start with `rg` for exact symbols and strings.
+- Use `sg` / structural search for pattern-level code exploration.
+- For large-scope understanding, prefer graphify/gitnexus before broad file scans.
+- Phase truth and runtime baselines are maintained in docs references (below), not inline here.
+
+## Code
+
+### Critical Path Symbols
+
+Before changing a symbol, run impact analysis:
+
+- `gitnexus_impact({target: "SymbolName", direction: "upstream"})`
+
+Before committing, run scope detection:
+
+- `gitnexus_detect_changes({scope: "staged"})`
+
+For unknown flows, start with:
+
+- `gitnexus_query({query: "concept"})`
+- `gitnexus_context({name: "symbol"})`
+
+### GitNexus Guardrails
+
+- Treat HIGH/CRITICAL impact results as explicit risk gates and surface them before continuing edits.
+- Never perform symbol renames via plain find/replace; use graph-aware rename workflows.
+- Re-index intentionally after significant code changes:
+  - `npx gitnexus analyze`
+  - `npx gitnexus analyze --embeddings` (when embeddings are in use)
+
+## Validation Gates (last verified: 2026-05-04 (Phase 14 post-merge))
+
+| Package                                      | Passed     | Failed | Skipped | Gate                                                                                                                                               |
+| -------------------------------------------- | ---------- | ------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| spec_orchestrator                            | 14         | 0      | 0       | GREEN                                                                                                                                              |
+| scheduler_orchestrator                       | 1,454      | 0      | 3       | GREEN (+2 from FR-14.2 cache fix)                                                                                                                  |
+| vds_agent_core                               | 932        | 0      | 0       | GREEN (+6 from FR-14.1 + FR-14.5 forward-ref fixes)                                                                                                |
+| memory_orchestrator (Phase 225 surface)      | 8          | 0      | 0       | GREEN                                                                                                                                              |
+| multi_agent_orchestrator (Phase 225 surface) | 49         | 0      | 0       | GREEN                                                                                                                                              |
+| audit_orchestrator (profile-focused subset)  | 121        | 15     | 24      | DEGRADED — pre-existing Python 3.14 forward-ref + config_hooks bugs (FR-14.1/14.5 reduced GAP cascade, full audit suite 8,290 PASS still DEGRADED) |
+| progress_report_orchestrator                 | 452        | 1      | 0       | DEGRADED — pre-existing alembic env_py schema-name assertion                                                                                       |
+| telegram_bridge                              | 102+       | 0      | 0       | GREEN                                                                                                                                              |
+| vds_cli (ecosystem)                          | 286        | 0      | 5       | GREEN                                                                                                                                              |
+| **Phase 14 surface total**                   | **1,477+** | **0**  | **8**   | GREEN (+8 from Phase 14 fixes)                                                                                                                     |
+
+- Scheduler Alembic: `a1b2c3d4e5f8` (Phase 2 golden-signals columns live)
+- Memory/Progress/Audit Alembic: AT_HEAD
+- Docker: 10/10 containers healthy; worker + API same image digest
+- Live CLI smoke: 6/6 pass (spec validate, scheduler help, trigger-now, db-query, onboarding-funnel, freshness)
+- Phase 231 deploy: vds-memory:1.0.0 image **10.4 GB** (62% reduction from 27.6 GB pre-Phase-225); all 7 health layers healthy; doctor embedding fallback OLLAMA_BASE_URL → BASE_URL deployed; VDS_MEMORY_TIMEOUT_SECONDS=300 set; entrypoint.sh alembic upgrade head verified
+
+## Docs
+
+- CLI command reference: `docs/agents/reference/cli-commands.md`
+- Ecosystem report: `docs/agents/reference/ecosystem-daily-report.md`
+- Skills commands: `docs/agents/reference/skills-commands.md`
+- Infrastructure v2.15: `docs/agents/reference/infrastructure-v2.15.md`
+- CI workflows: `docs/agents/reference/ci-workflows.md`
+- Ecosystem index: `ECOSYSTEM-DOCS.md`
+- Ecosystem changelog: `ECOSYSTEM-CHANGELOG.md`
+- Environment git-helper: `docs/agents/reference/env-git-helper.md`
+- Phase archive: `docs/phases/CHANGELOG.md`
+- Script authoring contract: `scripts/README.md`
+- Worktree wrapper contract (Phase 220.V): `scripts/README.md` §Worktree Wrapper Scripts (`worktree-add.sh` / `worktree-remove.sh` are canonical for vds-scripts; bare `git worktree` is fallback only)
+- Telegram Bridge reference: `telegram_bridge/skill_content/references/README.md`
+- Root router: `../AGENTS.md`
+- Ecosystem alignment: `ECOSYSTEM_ALIGNMENT.md` (openspace hook analysis)
+- Canonical spec: `.gpt-5.4/specs/ARCHIVE/who-project-documentation-enhancement/` (ARCHIVED — Phases 177→179 + post-merge updates merged)
+
+### Comprehensive Docs (Phase 180)
+
+- Introduction: `docs/agents/explanation/who-ecosystem-introduction.md`
+- Quick Start: `docs/agents/tutorials/quick-start.md`
+- Configuration: `docs/agents/reference/configuration-reference.md`
+- Troubleshooting: `docs/agents/how-to/troubleshooting-guide.md`
+- Architecture: `docs/agents/explanation/system-architecture.md`
+- Tips & Tricks: `docs/agents/how-to/tips-and-tricks.md`
+- See all: `ECOSYSTEM-DOCS.md`
+
+### Symlink Handling
+
+- `CLAUDE.md` in this repo is a symlink → `AGENTS.md`.
+- On filesystems where `core.symlinks=false`, the validator reports:
+  `CLAUDE.md is not a symlink to AGENTS.md (ERROR)`.
+- Fix: enable Git symlinks (`git config --global core.symlinks true`) or re-clone.
+
+## Ngôn ngữ / Language
+
+- [English](./AGENTS.md)
+- [Tiếng Việt](./AGENTS.vi.md)
+
+## Confluence Documentation
+
+- [WHO-Project Ecosystem Documentation](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation)
+  ecosystem: **41 tests**, spec v2.16.0 (Phase 0/8 Finalized; v2.16.0 deploy-portability extension applied)

package/skills/vds-skill/vds-scripts/AGENTS.vi.md

@@ -0,0 +1,92 @@
+# AGENTS.md — Không gian làm việc VDS Scripts
+
+> Không gian làm việc Python tự động hóa cho các điều phối viên và lệnh CLI được định tuyến của VDS.
+
+## Phạm vi
+
+- Repository: `WHO-project/vds-scripts`
+- Trách nhiệm chính:
+  - Bề mặt lệnh được định tuyến `vds-cli`
+  - Các điều phối viên audit/spec/task/progress/research
+  - Hợp đồng runtime và môi trường chia sẻ
+- Tệp này là hợp đồng vận hành Tier-0 (giữ ngắn gọn). Chi tiết lệnh sâu và giai đoạn nằm trong tài liệu tham khảo.
+
+## Khởi động nhanh
+
+```bash
+cd WHO-project/vds-scripts
+./scripts/worktree_uv.sh run --project vds_cli vds-cli --help
+./scripts/worktree_uv.sh run --project vds_cli vds-cli env status
+./scripts/worktree_uv.sh run --project audit_orchestrator vds-audit --help
+./scripts/worktree_uv.sh run --project spec_orchestrator vds-spec --help
+```
+
+## Quy tắc
+
+- Sử dụng `./scripts/worktree_uv.sh` để thực thi Python an toàn cho worktree.
+- Runtime ưu tiên Postgres-first. Không thêm dự phòng filesystem cho trạng thái audit hoặc bằng chứng.
+- Sử dụng bề mặt SDK VDS cho các thao tác Confluence/Bitbucket.
+- Giữ lịch sử giai đoạn và câu chuyện lệnh dài ở ngoài AGENTS.md.
+
+### Quy tắc kiểm thử
+
+- Các bài kiểm thử phải giả lập tất cả dịch vụ bên ngoài (Confluence, Bitbucket, nhà cung cấp LLM, điểm cuối HTTP).
+- Kiểm soát biến môi trường bằng `monkeypatch.setenv` / `delenv`; không đọc thông tin xác thực cục bộ thực.
+- Ưu tiên các bài kiểm thử tập trung cho các mô-đun đã thay đổi trong quá trình phát triển; chạy bộ kiểm thử rộng ở cổng merge.
+
+## Điểm vào
+
+- Bộ định tuyến thống nhất:
+  - `./scripts/worktree_uv.sh run --project vds_cli vds-cli <service> ...`
+- Các nhóm dịch vụ cốt lõi:
+  - `vds-cli audit ...`
+  - `vds-cli spec ...`
+  - `vds-cli tasks ...`
+  - `vds-cli progress ...`
+  - `vds-cli research ...`
+  - `vds-cli memory ...`
+
+## Tìm kiếm & Điều hướng
+
+- Bắt đầu bằng `rg` cho các ký hiệu và chuỗi chính xác.
+- Sử dụng `sg` / tìm kiếm cấu trúc để khám phá mẫu mức độ mã.
+- Để hiểu phạm vi lớn, ưu tiên graphify/gitnexus trước khi quét tệp rộng.
+- Sự thật về giai đoạn và đường cơ sở runtime được duy trì trong tài liệu tham khảo (bên dưới), không nội tuyến ở đây.
+
+## Trí tuệ mã
+
+Repo này được GitNexus lập chỉ mục là **vds-scripts**.
+
+- Trước khi thay đổi ký hiệu, chạy phân tích tác động:
+  - `gitnexus_impact({target: "SymbolName", direction: "upstream"})`
+- Trước khi commit, chạy phát hiện phạm vi:
+  - `gitnexus_detect_changes({scope: "staged"})`
+- Đối với các luồng chưa biết, bắt đầu bằng:
+  - `gitnexus_query({query: "concept"})`
+  - `gitnexus_context({name: "symbol"})`
+
+### Rào cản GitNexus
+
+- Coi kết quả tác động CAO/QUAN TRỌNG là rào cản rủi ro rõ ràng và trình bày chúng trước khi tiếp tục chỉnh sửa.
+- Không bao giờ thực hiện đổi tên ký hiệu qua tìm/thay thế thông thường; sử dụng quy trình đổi tên có nhận thức đồ thị.
+- Lập chỉ mục lại có chủ đích sau các thay đổi mã quan trọng:
+  - `npx gitnexus analyze`
+  - `npx gitnexus analyze --embeddings` (khi embeddings đang được sử dụng)
+
+## Tài liệu
+
+- Tài liệu tham khảo lệnh CLI: `docs/agents/reference/cli-commands.md`
+- Lưu trữ giai đoạn: `docs/phases/CHANGELOG.md`
+- Hợp đồng viết script: `scripts/README.md`
+- Bộ định tuyến gốc: `../AGENTS.md`
+
+### Xử lý Symlink
+
+- `CLAUDE.md` trong repo này là symlink → `AGENTS.md`.
+- Trên các hệ thống tệp nơi `core.symlinks=false`, trình xác thực báo cáo:
+  `CLAUDE.md is not a symlink to AGENTS.md (ERROR)`.
+- Khắc phục: bật Git symlinks (`git config --global core.symlinks true`) hoặc clone lại.
+
+## Ngôn ngữ / Language
+- [English](./AGENTS.md)
+- [Tiếng Việt](./AGENTS.vi.md)