@ngocsangairvds/vsaf 4.0.6 → 4.0.7

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

@@ -0,0 +1,133 @@
+# VDS-Evolution Ecosystem Alignment Report
+
+## Status: FULLY ALIGNED ✓
+
+---
+
+## System Components
+
+| Component | Location | Status |
+|-----------|----------|--------|
+| Scripts Repo | vds-scripts/ | HEAD: f7158c9 |
+| Mono .venv | vds/.venv/ | 52 lines, fix applied |
+| Tracked Shell | vds-evolution-mono.sh | Synced with mono |
+| env.py | vds_cli_common/src/ | Permanently patched |
+| router.py | vds_cli/src/ | Root-layout fix applied |
+
+---
+
+## Root Cause: Openspace __path_hook__
+
+The openspace package installs a custom PathEntryFinder in `sys.path_hooks`:
+
+1. **PATH_PLACEHOLDER** is added to `sys.path`:
+   ```
+   '__editable__.openspace-0.1.0.finder.__path_hook__'
+   ```
+
+2. **sys.path_hooks** is modified to include `_EditableNamespaceFinder`
+
+3. **When Python imports vds_evolution**:
+   - Iterates through `sys.path`
+   - Encounters PATH_PLACEHOLDER
+   - Calls path_hooks to get PathEntryFinder
+   - Openspace hook interferes with the import resolution
+
+4. **Result**: `find_spec()` returns `None` even though:
+   - `sys.path` contains the absolute path to vds_evolution
+   - The directory exists with `__init__.py`
+
+5. **Why CWD matters**:
+   - From scripts_repo: CWD + sys.path already primed
+   - From /tmp: PATH_PLACEHOLDER breaks the path iteration
+
+---
+
+## Fix Applied: spec_from_file_location
+
+All three scripts use this workaround:
+
+```python
+import importlib.util
+
+# Bypass sys.path_hooks, directly load from file
+spec = importlib.util.spec_from_file_location(
+    "vds_evolution",
+    "/path/to/vds_evolution/__init__.py"
+)
+module = importlib.util.module_from_spec(spec)
+sys.modules["vds_evolution"] = module
+spec.loader.exec_module(module)
+```
+
+This bypasses the entire `sys.path_hooks` machinery and loads directly from known file paths.
+
+---
+
+## UV Usage Assessment
+
+**Current approach: CORRECT**
+
+- `uv pip install -e` for editable development installs ✓
+- Manual script fix for the openspace hook edge case ✓
+- Editable install preserves source editing capability
+
+**Alternative approaches considered**:
+- Non-editable install: Would fix the hook issue, but loses source editing
+- uv tool install: Global install, may still hit hook issue
+
+**Recommendation**: Keep current approach, document the openspace hook issue.
+
+---
+
+## Repo-Boundary Component Status (per `who-ecosystem-alignment` Phase 4)
+
+Phase 4 of `who-ecosystem-alignment` codifies the canonical separation between
+`vds-scripts` (runtime Python only) and `vds-skills` (Claude-Code-facing
+artifacts). Components in this repo that intersect the boundary rules:
+
+| Component | Phase 4 status | Resolution path |
+|---|---|---|
+| `vds-scripts/vds_hooks/` (Python package) | **Retiring per FR-12** (Hook home: plugin format under `vds-skills/plugins/vds-hooks-*/` is the sole canonical hook surface) | `vds-hooks-claude-plugin-packaging` Phase 6 deletes the package (90 tracked files, 1.1 MB tracked content) |
+| `vds-scripts/.claude/skills/gitnexus/` (vendored skill mirror) | **Violates FR-11** (Vendoring policy: `vds-scripts` MUST NOT contain `.claude/skills/<name>/`) | `vds-skills-catalog-alignment-cleanup` Phase 5 deletes the 6 vendored sub-skills + adds `.gitignore` rule preventing regeneration |
+| `vds-scripts/*_orchestrator/` (31 orchestrators) | **Classified per FR-17** (Orchestrator coverage classification): 9 Tier A (have a corresponding skill), 0 Tier B (candidate for promotion), 22 Tier C (covered by `vds-scripts-skill` umbrella or too minimal) | No skill-creation work required; classification table in `who-ecosystem-alignment` Phase 4 design.md |
+| `vds-cli`, `mcp_server`, `platform_core`, `vds_agent_core`, `vds_evolution`, etc. | **In scope per FR-8** (Repo purpose: runtime Python only) | No change; these are exactly what vds-scripts SHOULD hold |
+
+---
+
+## Git State
+
+```
+HEAD: f7158c9 docs: add first-audit-run tutorial (FR-1.5 gap fill)
+Status: Clean (pushed to origin)
+Worktrees: 1 (scripts repo only)
+```
+
+---
+
+## Functional Tests
+
+| Test | Result |
+|------|--------|
+| scripts .venv status | ✓ OK |
+| mono .venv status | ✓ OK |
+| mono from /tmp | ✓ OK |
+| mono from scripts_repo | ✓ OK |
+| tracked shell | ✓ OK |
+
+---
+
+## Key Findings
+
+1. **Scripts consistency**: All 3 scripts use spec_from_file_location fix
+2. **Mono matches tracked**: vds-evolution-mono.sh == mono/.venv/bin/vds-evolution
+3. **Openspace hook**: Present in mono .venv, bypassed by fix
+4. **Root cause**: sys.path_hooks modification by openspace
+5. **Fix verified**: Works from any CWD
+6. **Git clean**: All changes pushed
+
+---
+
+## Conclusion
+
+The ecosystem is fully aligned and functioning correctly. The openspace __path_hook__ is a known issue with mixed venv environments (OpenSpace + vds-evolution). The spec_from_file_location workaround is the correct solution for this scenario.

package/skills/vds-skill/vds-scripts/Makefile

@@ -0,0 +1,119 @@
+# VDS Ecosystem Infrastructure Makefile
+# Phase: ecosystem-infrastructure-evolution v2.10.0
+#
+# Quick targets for the unified docker/ three-tier compose topology.
+# Run from vds-scripts repo root.
+#
+# Tiers (per ADR-INF-10):
+#   - Tier 1 docker-compose.infra.yml     : postgres, redis, qdrant
+#   - Tier 2 docker-compose.services.yml  : memory-api/worker, scheduler, multi-agent (long-running)
+#   - Tier 3 docker-compose.cli.yml       : audit, pdf, progress, db-query, vds-cli, mcp-server (CLI)
+#
+# Long-running services use `up -d` (`make up-memory`, etc.).
+# CLI containers use `run --rm` (`make run-audit ARGS="workflow run --project X"`).
+
+.PHONY: help \
+        env-link \
+        up-infra up-memory up-scheduler up-multi-agent up-services \
+        run-audit run-audit-migrate run-pdf run-progress run-progress-migrate run-db-query run-vds-cli \
+        down restart status verify build-cli clean-volumes
+
+# Hybrid project-identity anchor: -p flag + `name: vds-platform` in compose YAML
+# both pin the project as "vds-platform" regardless of CWD (ADR-INF-7).
+COMPOSE_PROJECT := vds-platform
+INFRA           := -f docker/docker-compose.infra.yml
+SERVICES        := -f docker/docker-compose.infra.yml -f docker/docker-compose.services.yml
+CLI             := -f docker/docker-compose.infra.yml -f docker/docker-compose.cli.yml
+ALL             := -f docker/docker-compose.infra.yml -f docker/docker-compose.services.yml -f docker/docker-compose.cli.yml
+
+DC := docker compose -p $(COMPOSE_PROJECT)
+
+help: ## Show this help message
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
+
+# === One-time bootstrap: env symlink (v2.0.17 N.52 consolidation) ===========
+# Compose's `${VAR}` substitution reads from compose's own .env (or shell),
+# NOT from the per-service env_file: block. To make ~/.vds/.env feed BOTH
+# in-container env_file AND YAML interpolation, link docker/.env -> ~/.vds/.env.
+env-link: ## Create docker/.env -> ~/.vds/.env symlink (idempotent; gitignored)
+	@if [ ! -L docker/.env ]; then \
+		ln -sf $$HOME/.vds/.env docker/.env && \
+		echo "Linked docker/.env -> ~/.vds/.env"; \
+	else \
+		echo "docker/.env already linked"; \
+	fi
+
+# === Long-running services (Tier 2; `up -d` keeps them running) ============
+# Per spec v2.12.2 P4 deploy postmortem: `--build` is included by default so
+# pulling latest master always rebuilds the service image. Operators who want
+# to skip the build (image is fresh) can set NO_BUILD=1.
+BUILD_FLAG := $(if $(NO_BUILD),,--build)
+
+up-infra: env-link ## Start shared infrastructure only (postgres, redis, qdrant)
+	$(DC) $(INFRA) --profile infra up -d
+
+up-memory: env-link ## Start infra + memory-api + memory-worker (rebuilds image; set NO_BUILD=1 to skip)
+	$(DC) $(SERVICES) --profile memory up -d $(BUILD_FLAG)
+
+up-scheduler: env-link ## Start infra + scheduler-orchestrator (rebuilds image; needs VDS_SCHEDULER_ENABLED=true; set NO_BUILD=1 to skip)
+	# Phase 217 HTTP refactor: scheduler depends_on memory-api; activate both --profile scheduler and --profile memory.
+	$(DC) $(SERVICES) --profile scheduler --profile memory up -d $(BUILD_FLAG)
+
+up-multi-agent: env-link ## Start infra + multi-agent-orchestrator (rebuilds image; set NO_BUILD=1 to skip)
+	$(DC) $(SERVICES) --profile multi-agent up -d $(BUILD_FLAG)
+
+up-services: env-link ## Start infra + all 4 long-running services (rebuilds images; set NO_BUILD=1 to skip)
+	# Tier 3B retired in v2.15.10 (ADR-INF-10): long-running services only need services.yml.
+	$(DC) $(SERVICES) --profile full up -d $(BUILD_FLAG)
+
+# === CLI containers (Tier 3; `run --rm` invocation pattern) ================
+# Override ARGS to pass subcommands. ARGS defaults to --help.
+ARGS ?= --help
+
+run-audit: env-link ## Run audit CLI (set ARGS="workflow run --project X")
+	$(DC) $(CLI) --profile audit run --rm audit-orchestrator $(ARGS)
+
+# v2.15.10 (ADR-INF-10): Tier 3B migrate containers retired.
+# Migrations run via --entrypoint override against the orchestrator service container.
+run-audit-migrate: env-link ## Run audit Alembic migrations to head (one-shot)
+	$(DC) $(CLI) --profile audit run --rm --no-deps --entrypoint /opt/venv/bin/alembic audit-orchestrator -c /app/audit_orchestrator/alembic.ini upgrade head
+
+run-pdf: env-link ## Run pdf CLI (set ARGS="merge a.pdf b.pdf -o c.pdf")
+	$(DC) $(CLI) --profile pdf run --rm pdf-orchestrator $(ARGS)
+
+run-progress: env-link ## Run progress CLI (set ARGS="generate --project X")
+	$(DC) $(CLI) --profile progress run --rm progress-report-orchestrator $(ARGS)
+
+# v2.15.10 (ADR-INF-10): Tier 3B migrate containers retired.
+# Migrations run via --entrypoint override against the orchestrator service container.
+run-progress-migrate: env-link ## Run progress Alembic migrations to head (one-shot)
+	$(DC) $(CLI) --profile progress run --rm --no-deps --entrypoint /opt/venv/bin/alembic progress-report-orchestrator -c /app/progress_report_orchestrator/alembic.ini upgrade head
+
+run-db-query: env-link ## Run db-query CLI (set ARGS="query --connection prod -q 'SELECT 1'")
+	$(DC) $(CLI) --profile db-query run --rm db-query-orchestrator $(ARGS)
+
+run-vds-cli: env-link ## Run unified vds-cli router (set ARGS="<service> <command>")
+	$(DC) $(CLI) --profile vds-cli run --rm vds-cli $(ARGS)
+
+# === Build / build CLI images ahead of time ================================
+
+build-cli: ## Pre-build all 6 CLI images (audit, pdf, progress, db-query, vds-cli, mcp-server)
+	$(DC) $(CLI) --profile cli build
+
+# === Lifecycle =============================================================
+
+down: ## Stop and remove ALL containers (volumes preserved)
+	$(DC) $(ALL) --profile full --profile cli down
+
+restart: down up-services ## Stop everything and start the long-running services
+
+status: ## Show running containers and ports
+	@docker ps --filter "name=vds-" --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
+
+verify: ## Run topology verification (stdlib python3, no uv)
+	python3 scripts/verify-infra-topology.py --profile infra
+
+clean-volumes: ## Remove all VDS-managed volumes (DESTRUCTIVE — prompts first)
+	@echo "About to remove: vds_postgres_data vds_redis_data vds_qdrant_data vds-audit-cache vds-memory-logs vds-pdf-cache vds-progress-cache"
+	@read -p "Type YES to confirm: " confirm && [ "$$confirm" = "YES" ] || (echo "Aborted." && exit 1)
+	docker volume rm -f vds_postgres_data vds_redis_data vds_qdrant_data vds-audit-cache vds-memory-logs vds-pdf-cache vds-progress-cache 2>/dev/null || true

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

@@ -0,0 +1,103 @@
+# VDS Scripts & Orchestrator Ecosystem
+
+**Centralized Automation Platform for Viettel Digital Services**
+
+This repository contains the `vds-cli` and a collection of specialized orchestrators designed to automate the software development lifecycle, from documentation management to infrastructure verification.
+
+`WHO-project` is the canonical VDS ecosystem for both reusable skills and routed scripts. Within that model, this repository is the authoritative scripts workspace, while the companion `WHO-project/vds-skills/` repository is the authoritative skills catalog.
+
+## 🚀 Quick Start
+
+Ensure you have the VDS CLI installed and configured.
+For the canonical human + AI-agent install/bootstrap flow, start with `docs/agents/how-to/install-and-bootstrap-who-scripts-and-skills.md`.
+
+```bash
+# Install dependencies in the current worktree
+./scripts/worktree_uv.sh sync
+
+# Verify installation
+./scripts/worktree_uv.sh run --project vds_cli vds-cli --version
+
+# Check environment status
+./scripts/worktree_uv.sh run --project vds_cli vds-cli env status
+```
+
+---
+
+## 📦 Available Orchestrators
+
+The platform is modularized into specialized orchestrators, each handling a specific domain.
+
+### Core Utilities
+
+| Orchestrator | Command | Description |
+|--------------|---------|-------------|
+| **[Task Orchestrator](./task_orchestrator/README.md)** | `vds-cli tasks --` | Manage, refine, and audit service task breakdowns and project plans. |
+| **[Excel Orchestrator](./excel_orchestrator/README.md)** | `vds-cli excel --` | Read, write, and format Excel reports (used by Task Orchestrator). |
+| **[Git Orchestrator](./git_orchestrator/README.md)** | `vds-cli git --` | Repository management, cloning, and syncing across projects. |
+| **[OpenAPI Orchestrator](./openapi_orchestrator/README.md)** | `vds-cli openapi --` | Validate, merge, and manage OpenAPI 3.x specifications. |
+
+### Documentation & Knowledge
+
+| Orchestrator | Command | Description |
+|--------------|---------|-------------|
+| **[Markdown Orchestrator](./markdown_orchestrator/README.md)** | `uv run --project markdown_orchestrator vds-markdown ...` | Format, lint, and validate Markdown documentation (direct CLI). |
+| **[PDF Orchestrator](./pdf_orchestrator/README.md)** | `vds-cli pdf --` | Generate high-fidelity PDFs from markdown sources. |
+| **[Diagram Generator](./diagram_generator/README.md)** | `vds-cli diagrams --` | Generate C4, Sequence, and ER diagrams from code/text. |
+| **[BRD Orchestrator](./brd_orchestrator/README.md)** | `vds-cli brd --` | Validate requirement coverage against Business Requirements Documents. |
+| **[Schema Converter](./schema_converter/README.md)** | `vds-cli schema --` | Convert between SQL, Prisma, JSON Schema, and Markdown. |
+
+### Integration & Infrastructure
+
+| Orchestrator | Command | Description |
+|--------------|---------|-------------|
+| **[Jira Orchestrator](./jira_orchestrator/README.md)** | `vds-cli jira` | Interact with Jira API for ticket management. |
+| **[Confluence Orchestrator](./confluence_orchestrator/README.md)** | `vds-cli confluence` | Publish documentation to Confluence pages. |
+| **[Bitbucket Orchestrator](./bitbucket_orchestrator/README.md)** | `vds-cli bitbucket` | Manage PRs, repositories, and branch permissions. |
+| **[Elastic Orchestrator](./elastic_orchestrator/README.md)** | `vds-cli elastic --` | Query and manage Elasticsearch indices. |
+| **[DB Query Orchestrator](./db_query_orchestrator/README.md)** | `vds-cli db_query --` | Manage named DB connections and run safe read-only SQL against PostgreSQL, SQL Server, and MariaDB. |
+| **[Grafana Orchestrator](./grafana_orchestrator/README.md)** | `vds-cli grafana --` | Query logs and metrics via Grafana Datasource. |
+| **[SonarQube Orchestrator](./sonarqube_orchestrator/README.md)** | `vds-cli sonarqube --` | Trigger scans and check quality gates. |
+
+### Ecosystem Scheduling
+
+| Orchestrator | Command | Description |
+|--------------|---------|-------------|
+| **[Scheduler Orchestrator](./scheduler_orchestrator/README.md)** | `vds-cli scheduler --` | Durable cron/interval/one-shot schedule management, event-bus dispatch, chain triggers, and DBOS workflow orchestration. Requires `VDS_SCHEDULER_ENABLED=true`. |
+
+### Developer Experience
+
+| Orchestrator | Command | Description |
+|--------------|---------|-------------|
+| **[IntelliJ Orchestrator](./intellij_orchestrator/README.md)** | `vds-cli intellij --` | Automate workspace setup and run configurations. |
+| **[Links Orchestrator](./links_orchestrator/README.md)** | `vds-cli links --` | Validate relative and absolute links across documentation. |
+| **[Structure Orchestrator](./structure_orchestrator/README.md)** | `vds-cli structure --` | Enforce repository folder structure and naming conventions. |
+
+---
+
+## 🛠️ Development Standards
+
+All orchestrators should follow the `vds-cli` routed command model and shared environment-loading pattern used in `vds_cli_common`.
+
+### Key Requirements
+1.  **Structure**: Must follow `src/vds_[name]_orchestrator/cli.py` pattern.
+2.  **Configuration**: Keep secrets in `VDS_ENV_FILE` or `<config-root>/.env`; `<config-root>` resolves from `VDS_CONFIG_DIR` when set, otherwise from the friendly user-home VDS default (`~/.vds` on Unix-like systems). Keep non-sensitive extraction tuning in `<config-root>/config/extract-docs.toml`.
+3.  **Testing**: Minimum 80% unit test coverage.
+4.  **CLI**: Expose commands via `typer` for integration into `vds-cli`.
+5.  **Audit Runtime Contract (current merged baseline)**: `vds-audit` workflow/analyze/ad-hoc consume evidence from Postgres chunks only (no runtime disk evidence ingestion path). Use `vds-audit prepare --project <PROJECT_STORAGE_KEY>` to run the deterministic prep sequence (`parse-registry -> sync repos -> extract-docs`), then confirm `state readiness` reports `ready=true`, `docs_chunk_ready=true`, and `code_chunk_ready=true`.
+
+### Creating a New Orchestrator
+
+1.  Copy the structure from an existing module (e.g., `task_orchestrator`).
+2.  Implement the logic in `src/`.
+3.  Register the module in `vds_cli/src/vds_cli/router.py`.
+4.  Add the command group in `vds_cli/src/vds_cli/cli.py`.
+5.  Add entry to this README.
+
+---
+
+## 🤝 Contributing
+
+1.  Create a feature branch `feature/enhance-[orchestrator]`.
+2.  Ensure tests pass: `uv run pytest`.
+3.  Submit a PR via `vds bitbucket pr create`.

package/skills/vds-skill/vds-scripts/bitbucket_manifest_mapping.toml

@@ -0,0 +1,34 @@
+# Bitbucket project → manifest mapping rules for dynamic repo-manifest.yaml generation
+#
+# This file is intentionally minimal: it only defines how to convert a Bitbucket
+# project key into:
+# - project_id: short id used in repo-manifest.yaml (lep, insurance, saving, ekyc)
+# - path_prefix: local path prefix in the monorepo
+# - default_branch: default branch name when generating entries
+#
+# To add more projects later, extend this file and rerun the generator.
+
+[projects.LEP]
+project_id = "lep"
+path_prefix = "LEP-project"
+default_branch = "release"
+
+[projects.INSURANCE]
+project_id = "insurance"
+path_prefix = "INSURANCE-project"
+default_branch = "release"
+
+[projects.SAVING]
+project_id = "saving"
+path_prefix = "SAVING-project"
+default_branch = "release"
+
+[projects.EKYC]
+project_id = "ekyc"
+path_prefix = "EKYC-project"
+default_branch = "release"
+
+[projects.DOPS]
+project_id = "dops"
+path_prefix = "DOPS-project"
+default_branch = "master"

package/skills/vds-skill/vds-scripts/bitbucket_orchestrator/ARCHITECTURE_ANALYSIS.md

@@ -0,0 +1,258 @@
+# Bitbucket Orchestrator Architecture Analysis
+
+## Overview
+
+This document verifies that there is **no duplicate logic** in the Bitbucket-related code across the VDS scripts
+ecosystem. All Bitbucket operations follow a clean, single-source-of-truth architecture.
+
+## Architecture Layers
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    User/Agent Interface                     │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+         ┌───────────┴───────────┐
+         │                       │
+    ┌────▼────┐            ┌─────▼─────┐
+    │ VDS CLI │            │ MCP Server │
+    └────┬────┘            └─────┬─────┘
+         │                       │
+         │  Routes to            │  Calls VDS CLI
+         │                       │
+    ┌────▼───────────────────────▼────┐
+    │   Bitbucket Orchestrator         │
+    │   (Single Source of Truth)      │
+    └────┬────────────────────────────┘
+         │
+    ┌────▼────┐
+    │  SDK    │
+    │ (atlassian-python-api) │
+    └─────────┘
+```
+
+## Single Source of Truth
+
+### 1. Bitbucket Client (`bitbucket_orchestrator/src/vds_bitbucket_orchestrator/client.py`)
+
+**Status**: ✅ **ONLY** place that directly uses `AtlassianBitbucket` SDK
+
+```python
+from atlassian import Bitbucket as AtlassianBitbucket
+
+class BitbucketClient:
+    """Bitbucket client wrapper using atlassian-python-api SDK."""
+    def __init__(self, settings: BitbucketSettings):
+        # Only place that creates AtlassianBitbucket instance
+        self._client = AtlassianBitbucket(...)
+```
+
+**Verification**:
+
+- ✅ Only file that imports `AtlassianBitbucket`
+- ✅ All Bitbucket API calls go through this client
+- ✅ All error handling centralized here
+- ✅ All retry logic centralized here
+
+### 2. Configuration Loading (`bitbucket_orchestrator/src/vds_bitbucket_orchestrator/config.py`)
+
+**Status**: ✅ **ONLY** place that loads Bitbucket settings
+
+```python
+def load_settings(...) -> BitbucketSettings:
+    """Load orchestrator settings from the environment."""
+    # Only place that creates BitbucketSettings
+```
+
+**Verification**:
+
+- ✅ Only file that defines `BitbucketSettings`
+- ✅ Only file that implements `load_settings()` for Bitbucket
+- ✅ Consistent with other orchestrators (JIRA, Confluence)
+
+### 3. Client Factory (`bitbucket_orchestrator/src/vds_bitbucket_orchestrator/cli.py`)
+
+**Status**: ✅ **ONLY** place that builds BitbucketClient instances
+
+```python
+def _build_client(settings: BitbucketSettings) -> BitbucketClient:
+    """Build and return a configured BitbucketClient."""
+    return BitbucketClient(settings)
+```
+
+**Verification**:
+
+- ✅ Single factory function for client creation
+- ✅ Used consistently across all CLI commands
+- ✅ No duplicate client initialization logic
+
+## Integration Points (No Duplication)
+
+### 1. VDS CLI Router (`vds_cli/src/vds_cli/router.py`)
+
+**Status**: ✅ **NO** Bitbucket logic, only routing
+
+```python
+ORCHESTRATORS = {
+    "bitbucket": {
+        "module": "vds_bitbucket_orchestrator.cli",
+        "path": "bitbucket_orchestrator",
+    },
+}
+
+def run_orchestrator(service: str, args: list[str], script_dir: Path) -> int:
+    """Run orchestrator via uv."""
+    # Simply routes to orchestrator, no Bitbucket-specific logic
+```
+
+**Verification**:
+
+- ✅ No Bitbucket API calls
+- ✅ No Bitbucket client creation
+- ✅ No Bitbucket configuration loading
+- ✅ Pure routing logic only
+
+### 2. VDS CLI Main (`vds_cli/src/vds_cli/cli.py`)
+
+**Status**: ✅ **NO** Bitbucket logic, only command registration
+
+```python
+@app.command(context_settings=PASS_THRU_CONTEXT)
+def bitbucket(ctx: typer.Context) -> None:
+    """Bitbucket operations."""
+    _run_service("bitbucket", list(ctx.args))  # Routes to orchestrator
+```
+
+**Verification**:
+
+- ✅ No Bitbucket API calls
+- ✅ No Bitbucket client creation
+- ✅ No Bitbucket configuration loading
+- ✅ Pure command registration only
+
+### 3. MCP Server Tools (`mcp_server/src/vds_mcp_server/tools/bitbucket_tools.py`)
+
+**Status**: ✅ **NO** direct Bitbucket API calls, uses VDS CLI
+
+```python
+def register_bitbucket_tools(mcp: FastMCP, execute_cli: Callable[..., Any]) -> None:
+    """Register Bitbucket tools with MCP server."""
+
+    @mcp.tool()
+    async def bitbucket_list_projects() -> str:
+        # Uses VDS CLI, not direct API calls
+        result = await execute_cli("bitbucket", "projects")
+```
+
+**Verification**:
+
+- ✅ No direct `AtlassianBitbucket` usage
+- ✅ No direct `BitbucketClient` usage
+- ✅ No direct `BitbucketSettings` usage
+- ✅ Uses VDS CLI as abstraction layer
+- ✅ Proper separation of concerns
+
+### 4. Git Orchestrator (`git_orchestrator/src/vds_git_orchestrator/orchestrator.py`)
+
+**Status**: ✅ **NO** Bitbucket-specific code
+
+**Verification**:
+
+- ✅ No Bitbucket imports
+- ✅ No Bitbucket API calls
+- ✅ Only Git operations (uses Bitbucket as Git remote, not API)
+- ✅ References `VDS_BITBUCKET_HTTP_BASE` for Git URL construction only
+
+## Method Mapping Verification
+
+All Bitbucket operations map to a single implementation:
+
+| Operation | Implementation Location | Duplicates? | |-----------|------------------------|-------------| |
+`create_repository()` | `bitbucket_orchestrator/client.py` | ❌ None | | `get_repository()` |
+`bitbucket_orchestrator/client.py` | ❌ None | | `update_repository()` | `bitbucket_orchestrator/client.py` | ❌ None | |
+`delete_repository()` | `bitbucket_orchestrator/client.py` | ❌ None | | `fork_repository()` |
+`bitbucket_orchestrator/client.py` | ❌ None | | `list_repositories()` | `bitbucket_orchestrator/client.py` | ❌ None | |
+`create_pull_request()` | `bitbucket_orchestrator/client.py` | ❌ None | | All other operations |
+`bitbucket_orchestrator/client.py` | ❌ None |
+
+## Configuration Verification
+
+All Bitbucket configuration loading maps to a single implementation:
+
+| Configuration | Implementation Location | Duplicates? | |---------------|------------------------|-------------| |
+`BitbucketSettings` | `bitbucket_orchestrator/config.py` | ❌ None | | `load_settings()` |
+`bitbucket_orchestrator/config.py` | ❌ None | | Environment variable parsing | `bitbucket_orchestrator/config.py` | ❌
+None |
+
+## Client Initialization Verification
+
+All Bitbucket client creation maps to a single implementation:
+
+| Initialization | Implementation Location | Duplicates? | |----------------|------------------------|-------------| |
+`BitbucketClient.__init__()` | `bitbucket_orchestrator/client.py` | ❌ None | | `_build_client()` |
+`bitbucket_orchestrator/cli.py` | ❌ None | | SDK client creation | `bitbucket_orchestrator/client.py` | ❌ None |
+
+## Test Coverage Verification
+
+All tests use the same client initialization pattern:
+
+```python
+# All tests use this pattern - no duplication
+@patch("vds_bitbucket_orchestrator.client.AtlassianBitbucket")
+def test_something(mock_bitbucket_class: Mock, mock_settings: BitbucketSettings):
+    client = BitbucketClient(mock_settings)
+    # Test implementation
+```
+
+**Verification**:
+
+- ✅ All tests mock `AtlassianBitbucket` at the same location
+- ✅ All tests use `BitbucketClient` from same module
+- ✅ All tests use `BitbucketSettings` from same module
+- ✅ No duplicate test setup logic
+
+## Summary
+
+### ✅ No Duplication Found
+
+1. **Single SDK Usage**: Only `bitbucket_orchestrator/client.py` uses `AtlassianBitbucket`
+1. **Single Configuration**: Only `bitbucket_orchestrator/config.py` handles settings
+1. **Single Client Factory**: Only `bitbucket_orchestrator/cli.py` has `_build_client()`
+1. **Clean Integration**: VDS CLI and MCP Server use orchestrator, don't duplicate logic
+1. **Consistent Patterns**: All components follow the same architecture
+
+### Architecture Benefits
+
+1. **Maintainability**: Changes to Bitbucket logic only need to be made in one place
+1. **Consistency**: All consumers get the same behavior
+1. **Testability**: Single point to mock for testing
+1. **Error Handling**: Centralized error handling and retry logic
+1. **Documentation**: Single source of truth for API practices
+
+### Verification Commands
+
+```bash
+# Verify only one place imports AtlassianBitbucket
+grep -r "from atlassian import Bitbucket\|AtlassianBitbucket" docs-nttc/scripts/
+# Result: Only bitbucket_orchestrator/client.py
+
+# Verify only one place defines BitbucketSettings
+grep -r "class BitbucketSettings" docs-nttc/scripts/
+# Result: Only bitbucket_orchestrator/config.py
+
+# Verify only one place has _build_client for Bitbucket
+grep -r "def _build_client.*Bitbucket" docs-nttc/scripts/
+# Result: Only bitbucket_orchestrator/cli.py
+```
+
+## Conclusion
+
+✅ **No duplicate logic found**. The Bitbucket orchestrator follows a clean, single-source-of-truth architecture with
+proper separation of concerns:
+
+- **Orchestrator**: Implements all Bitbucket logic
+- **VDS CLI**: Routes commands to orchestrator
+- **MCP Server**: Uses VDS CLI as abstraction layer
+- **Git Orchestrator**: Uses Bitbucket as Git remote only, no API calls
+
+All components work together without duplication, ensuring maintainability and consistency.