@ngocsangairvds/vsaf 4.0.5 → 4.0.7

package/skills/vds-skill/vds-scripts/scripts/setup_intellij_workspace.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""
+VDS CLI command to set up IntelliJ IDEA workspace for the VDS monorepo.
+"""
+
+import os
+import subprocess
+import sys
+
+
+def setup_intellij_workspace():
+    """
+    Set up IntelliJ IDEA workspace by generating module files and updating modules.xml.
+    """
+    # Get the VDS root directory
+    vds_root = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
+    scripts_dir = os.path.join(vds_root, "vds-scripts", "scripts")
+
+    print("Setting up IntelliJ IDEA workspace for VDS monorepo...")
+    print(f"VDS Root: {vds_root}")
+
+    # Run the module generation script
+    print("\n1. Generating IntelliJ IDEA module files...")
+    try:
+        result = subprocess.run(
+            [sys.executable, os.path.join(scripts_dir, "generate_intellij_modules.py")],
+            cwd=scripts_dir,
+            capture_output=True,
+            text=True,
+        )
+
+        if result.returncode != 0:
+            print(f"Error generating module files: {result.stderr}")
+            return False
+
+        print(result.stdout)
+    except Exception as e:
+        print(f"Error running module generation script: {e}")
+        return False
+
+    # Run the modules.xml update script
+    print("\n2. Updating modules.xml file...")
+    try:
+        result = subprocess.run(
+            [sys.executable, os.path.join(scripts_dir, "update_modules_xml.py")],
+            cwd=scripts_dir,
+            capture_output=True,
+            text=True,
+        )
+
+        if result.returncode != 0:
+            print(f"Error updating modules.xml: {result.stderr}")
+            return False
+
+        print(result.stdout)
+    except Exception as e:
+        print(f"Error running modules.xml update script: {e}")
+        return False
+
+    print("\n3. IntelliJ IDEA workspace setup complete!")
+    print("\nNext steps:")
+    print("1. Refresh your project in IntelliJ IDEA (Ctrl+Alt+Y / Cmd+Alt+Y)")
+    print("2. The project should now be organized with all modules grouped by project type")
+    print("3. If modules don't appear, go to File → Project Structure → Modules to import them")
+
+    return True
+
+
+if __name__ == "__main__":
+    success = setup_intellij_workspace()
+    sys.exit(0 if success else 1)

package/skills/vds-skill/vds-scripts/scripts/smoke-test-deploy.sh

@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+# pytest-skip-default: requires Docker
+#
+# smoke-test-deploy.sh — v2.12.3 §Post-Merge Live Deploy runbook (P6 WP-6.3)
+#
+# Automates the 8-step runbook and writes a JSON evidence artifact to
+# docs/p4-closure-evidence/smoke-<timestamp>-<git-sha>.json
+#
+# Usage:
+#   bash scripts/smoke-test-deploy.sh [--target {live|ephemeral}]
+#
+# Environment:
+#   VDS_SMOKE_ARTIFACT_DIR   Override artifact directory
+#                            (default: <repo-root>/docs/p4-closure-evidence)
+#   SKIP_DOWNGRADE_TESTS     Set to 1 to skip step 8 (alembic downgrade
+#                            regression suite); useful if Docker is unavailable.
+#
+# Exit codes:
+#   0  All 8 runbook steps passed + verify succeeded
+#   1  One or more steps failed (partial artifact still written)
+#   2  Pre-flight check failed (Python / make not found)
+#
+# Steps:
+#   1. make build-cli
+#   2. make run-audit-migrate
+#   3. make run-progress-migrate
+#   4. make up-memory
+#   5. make up-multi-agent
+#   6. make up-scheduler
+#   7. make verify
+#   8. pytest -m docker (alembic downgrade regression — ADR-INF-11)
+#      Skip with: SKIP_DOWNGRADE_TESTS=1 bash scripts/smoke-test-deploy.sh
+#
+# DO NOT run this script directly in CI unless Docker compose is available.
+# The unit-test contract (scripts/tests/test_smoke_deploy.py) covers the
+# Python logic; this Bash wrapper is the operator-facing entrypoint.
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Parse arguments
+# ---------------------------------------------------------------------------
+TARGET="live"
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --target)
+      TARGET="$2"
+      shift 2
+      ;;
+    --target=*)
+      TARGET="${1#*=}"
+      shift
+      ;;
+    -h|--help)
+      grep '^#' "$0" | sed 's/^# \?//'
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      exit 2
+      ;;
+  esac
+done
+
+if [[ "$TARGET" != "live" && "$TARGET" != "ephemeral" ]]; then
+  echo "ERROR: --target must be 'live' or 'ephemeral', got: $TARGET" >&2
+  exit 2
+fi
+
+# ---------------------------------------------------------------------------
+# Resolve paths
+# ---------------------------------------------------------------------------
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+ARTIFACT_DIR="${VDS_SMOKE_ARTIFACT_DIR:-"$REPO_ROOT/docs/p4-closure-evidence"}"
+
+# ---------------------------------------------------------------------------
+# Pre-flight: require Python 3 and make
+# ---------------------------------------------------------------------------
+if ! command -v python3 &>/dev/null; then
+  echo "ERROR: python3 not found in PATH" >&2
+  exit 2
+fi
+if ! command -v make &>/dev/null; then
+  echo "ERROR: make not found in PATH" >&2
+  exit 2
+fi
+
+# ---------------------------------------------------------------------------
+# Locate smoke_deploy_lib.py (sibling of this script)
+# ---------------------------------------------------------------------------
+SMOKE_LIB="$SCRIPT_DIR/smoke_deploy_lib.py"
+if [[ ! -f "$SMOKE_LIB" ]]; then
+  echo "ERROR: $SMOKE_LIB not found — cannot proceed" >&2
+  exit 2
+fi
+
+# ---------------------------------------------------------------------------
+# Resolve git SHA for artifact filename
+# ---------------------------------------------------------------------------
+GIT_SHA="unknown"
+if command -v git &>/dev/null; then
+  GIT_SHA="$(git -C "$REPO_ROOT" rev-parse --short HEAD 2>/dev/null || echo "unknown")"
+fi
+
+# ---------------------------------------------------------------------------
+# Delegate to Python helper (handles step execution + artifact writing + trap)
+# ---------------------------------------------------------------------------
+echo "=== VDS P6 WP-6.3 Smoke Deploy (8 steps) ==="
+echo "  target:              $TARGET"
+echo "  repo root:           $REPO_ROOT"
+echo "  artifact dir:        $ARTIFACT_DIR"
+echo "  git SHA:             $GIT_SHA"
+echo "  skip downgrade tests: ${SKIP_DOWNGRADE_TESTS:-0}"
+echo ""
+
+ARTIFACT_PATH="$(SKIP_DOWNGRADE_TESTS="${SKIP_DOWNGRADE_TESTS:-0}" python3 "$SMOKE_LIB" \
+  --artifact-dir "$ARTIFACT_DIR" \
+  --repo-root    "$REPO_ROOT" \
+  --git-sha      "$GIT_SHA" \
+  --target       "$TARGET")"
+
+EXIT_CODE=$?
+
+if [[ -n "$ARTIFACT_PATH" ]]; then
+  echo ""
+  echo "Artifact: $ARTIFACT_PATH"
+fi
+
+if [[ $EXIT_CODE -eq 0 ]]; then
+  echo "Result:   PASS"
+else
+  echo "Result:   FAIL (exit $EXIT_CODE)" >&2
+fi
+
+exit $EXIT_CODE

package/skills/vds-skill/vds-scripts/scripts/smoke_deploy_lib.py

@@ -0,0 +1,205 @@
+"""smoke_deploy_lib — Python helper for scripts/smoke-test-deploy.sh.
+
+Implements the runbook step-runner, artifact writing, and short-circuit
+logic used by the smoke test. The Bash wrapper delegates JSON artifact
+writing and result aggregation to this module.
+
+Stdlib-only per ADR-INF-8.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import time
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# Runbook definition — v2.12.2 §Post-Merge Live Deploy order
+# ---------------------------------------------------------------------------
+
+RUNBOOK: list[str] = [
+    "make build-cli",
+    "make run-audit-migrate",
+    "make run-progress-migrate",
+    "make up-memory",
+    "make up-multi-agent",
+    "make up-scheduler",
+    "make verify",
+    # Step 8 (P6 WP-6.3): alembic downgrade regression suite.
+    # Exercises the surgical-no-op 0001.downgrade() pattern (ADR-INF-11
+    # §Schema-Drop-Safe Downgrade Pattern). Requires Docker daemon.
+    # Skip cleanly with: SKIP_DOWNGRADE_TESTS=1 bash scripts/smoke-test-deploy.sh
+    "uv run --project scheduler_orchestrator pytest scheduler_orchestrator/tests/test_alembic_downgrade.py -m docker -v --timeout=120",
+]
+
+
+def _run_step(cmd: str, cwd: Path | None = None, timeout: float = 600.0) -> dict[str, Any]:
+    """Run a single make target; return step record with timing + exit code.
+
+    timeout (seconds, default 600 = 10 min): caps any single step. A hung
+    Docker daemon or stuck health-check would otherwise block the smoke
+    script forever; the cap turns that into a recorded failure with
+    exit_code=124 (matching GNU timeout convention) so CI can move on.
+    """
+    t0 = time.monotonic()
+    parts = cmd.split()
+    try:
+        proc = subprocess.run(
+            parts,
+            capture_output=True,
+            text=True,
+            cwd=str(cwd) if cwd else None,
+            timeout=timeout,
+        )
+        exit_code = proc.returncode
+        stdout = proc.stdout
+        stderr = proc.stderr
+    except subprocess.TimeoutExpired as exc:
+        exit_code = 124  # GNU timeout convention
+        stdout = (
+            (exc.stdout or b"").decode("utf-8", errors="replace")
+            if isinstance(exc.stdout, bytes)
+            else (exc.stdout or "")
+        )
+        stderr = f"TIMEOUT after {timeout}s — {exc}"
+    except FileNotFoundError as exc:
+        exit_code = 127
+        stdout = ""
+        stderr = str(exc)
+    duration = round(time.monotonic() - t0, 3)
+    return {
+        "command": cmd,
+        "exit_code": exit_code,
+        "duration_s": duration,
+        "stdout": stdout[-2000:] if stdout else "",
+        "stderr": stderr[-2000:] if stderr else "",
+    }
+
+
+def run_smoke(
+    *,
+    artifact_dir: Path,
+    repo_root: Path,
+    git_sha: str,
+    target: str = "live",
+) -> dict[str, Any]:
+    """Execute the v2.12.2 runbook and write a JSON artifact.
+
+    Parameters
+    ----------
+    artifact_dir:
+        Directory where the smoke-<timestamp>-<sha>.json artifact is written.
+        Created automatically if absent.
+    repo_root:
+        Repository root — make targets are invoked from here.
+    git_sha:
+        Short git SHA embedded in artifact filename for traceability.
+    target:
+        ``'live'`` (default) or ``'ephemeral'`` — recorded in artifact.
+
+    Returns
+    -------
+    dict
+        The artifact payload (same data written to disk).
+    """
+    artifact_dir = Path(artifact_dir)
+    artifact_dir.mkdir(parents=True, exist_ok=True)
+
+    timestamp = datetime.now(tz=UTC).strftime("%Y%m%dT%H%M%SZ")
+    artifact_name = f"smoke-{timestamp}-{git_sha}.json"
+    artifact_path = artifact_dir / artifact_name
+
+    steps: list[dict[str, Any]] = []
+    overall_passed = True
+
+    skip_downgrade = os.environ.get("SKIP_DOWNGRADE_TESTS", "0").strip() == "1"
+
+    for cmd in RUNBOOK:
+        # Step 8 opt-out: alembic downgrade regression tests require Docker.
+        # Operator sets SKIP_DOWNGRADE_TESTS=1 when Docker is unavailable.
+        if skip_downgrade and "test_alembic_downgrade" in cmd:
+            steps.append(
+                {
+                    "command": cmd,
+                    "exit_code": 0,
+                    "duration_s": 0.0,
+                    "stdout": "SKIPPED (SKIP_DOWNGRADE_TESTS=1)",
+                    "stderr": "",
+                }
+            )
+            continue
+
+        step = _run_step(cmd, cwd=repo_root)
+        steps.append(step)
+        if step["exit_code"] != 0:
+            overall_passed = False
+            # Short-circuit: write partial artifact and stop
+            break
+
+    payload: dict[str, Any] = {
+        "passed": overall_passed,
+        "git_sha": git_sha,
+        "timestamp": timestamp,
+        "target": target,
+        "steps": steps,
+    }
+
+    artifact_path.write_text(json.dumps(payload, indent=2))
+
+    return payload
+
+
+# ---------------------------------------------------------------------------
+# CLI entry point (used by smoke-test-deploy.sh)
+# ---------------------------------------------------------------------------
+
+
+def _cli() -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Run v2.12.2 Post-Merge Live Deploy runbook and emit JSON artifact")
+    parser.add_argument(
+        "--artifact-dir",
+        required=True,
+        help="Directory to write smoke-<timestamp>-<sha>.json",
+    )
+    parser.add_argument(
+        "--repo-root",
+        default=".",
+        help="Repository root for make invocations (default: .)",
+    )
+    parser.add_argument(
+        "--git-sha",
+        required=True,
+        help="Short git SHA for artifact filename",
+    )
+    parser.add_argument(
+        "--target",
+        choices=["live", "ephemeral"],
+        default="live",
+        help="Deployment target (default: live)",
+    )
+    args = parser.parse_args()
+
+    result = run_smoke(
+        artifact_dir=Path(args.artifact_dir),
+        repo_root=Path(args.repo_root),
+        git_sha=args.git_sha,
+        target=args.target,
+    )
+    # Print artifact path to stdout for the Bash caller to capture
+    artifact_dir = Path(args.artifact_dir)
+    artifacts = sorted(artifact_dir.glob(f"smoke-*-{args.git_sha}.json"))
+    if artifacts:
+        print(str(artifacts[-1]))
+
+    return 0 if result["passed"] else 1
+
+
+if __name__ == "__main__":
+    sys.exit(_cli())

package/skills/vds-skill/vds-scripts/scripts/target-state-automation/README.md

@@ -0,0 +1,89 @@
+# Target-State Documentation Automation Scripts
+
+## Overview
+
+Automation scripts for generating, validating, and managing target-state documentation across all VDS Insurance Platform services.
+
+## Scripts
+
+### 1. generate_diagrams.sh
+Generate component, sequence, and use case diagrams for services using VDS Diagram Generator.
+
+### 2. validate_diagrams.sh
+Validate existing PlantUML and Mermaid diagrams for syntax errors.
+
+### 3. validate_markdown.sh
+Validate markdown files against VDS documentation standards.
+
+### 4. sync_confluence.sh
+Upload documentation and diagrams to Confluence.
+
+### 5. validate_brd_coverage.sh
+Validate BRD coverage for completed services.
+
+### 6. multi_agent_coordinator.py
+Python script for coordinating multi-agent execution with task queue and file locking.
+
+## UV Contract
+
+All scripts in this directory route Python tool invocations through the
+worktree-safe wrapper stack. See [`../README.md`](../README.md#uv-contract--canonical-usage)
+for the full contract. Key points specific to this directory:
+
+### Sourcing the helper
+
+Every script sources `scripts/vds_sh_helpers.sh` (one level up):
+
+```/dev/null/target-state-automation-source.sh#L1-2
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/../vds_sh_helpers.sh"
+```
+
+### Standard invocation pattern
+
+```/dev/null/target-state-automation-run.sh#L1-5
+# Run a vds_cli command
+vds_uv_run_package vds_cli vds-cli <subcommand> [args...]
+
+# Run a markdown_orchestrator command (note the -- separator)
+vds_uv_run_package markdown_orchestrator -- vds-cli markdown <subcommand> [args...]
+```
+
+Do **not** use `uv run --project <path>` or a monorepo-relative `cd` before
+`uv run`. Both patterns break in worktrees and alternate checkouts.
+
+### Intentional exception — validate_markdown.sh
+
+`validate_markdown.sh` uses an editable install (`uv pip install -e .`) for
+local-dev iteration on `markdown_orchestrator` source. This is documented in
+the script header. Do not migrate it to the standard wrapper pattern without
+evaluating whether editable-install semantics are still required.
+
+### Backward-compatible helper — docs_root.sh
+
+`docs_root.sh` is now a shim that delegates to `vds_sh_helpers.sh`. Existing
+scripts that source it continue to work. New scripts should source
+`../vds_sh_helpers.sh` directly.
+
+## Configuration
+
+All scripts use environment variables from the shared VDS env/config layer.
+
+- `VDS_INSURANCE_DOCS_ROOT` overrides the documentation root.
+- Without the override, scripts prefer `WHO-project/insurance-document` and then fall back to the first `*-project/insurance-document` match.
+- `AGENT_ID` sets the coordination lock identity (default: `markdown-agent-01`).
+
+## Dependencies
+
+- PlantUML CLI (latest version)
+- markdownlint-cli2 (npm package)
+- Bash 4.0+
+- Python 3.14+ preferred for integrated `vds-scripts` workspace usage
+- VDS-AI-Memory service running
+
+## Version
+
+**Automation Scripts Version**: 1.0
+**Created**: 2025-01-06
+**Author**: OpenCode Agent
+**Status**: Draft - Ready for Implementation

package/skills/vds-skill/vds-scripts/scripts/target-state-automation/confluence_sync_coordinator.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=scripts/vds_sh_helpers.sh
+source "$SCRIPT_DIR/../vds_sh_helpers.sh"
+
+ROOT="$(vds_resolve_scripts_root)"
+DOCS_ROOT="$(resolve_insurance_docs_root "$ROOT")"
+TARGET_STATE_ROOT="$DOCS_ROOT/projects/INSURANCE/analysis/target-state"
+COORD="$ROOT/scripts/target-state-automation/coordination.sh"
+AGENT_ID="${AGENT_ID:-confluence-agent-01}"
+PAGE_ID="${PAGE_ID:?Set PAGE_ID for Confluence sync}"
+SERVER="${SERVER:-external}"
+
+lock_file="$TARGET_STATE_ROOT/README.md"
+"$COORD" lock "$AGENT_ID" "$lock_file" "confluence-sync" >/dev/null || true
+
+vds_uv_run_package vds_cli vds-cli confluence sync pngs "$PAGE_ID" \
+  --dir "$TARGET_STATE_ROOT/architecture" \
+  --server "$SERVER"
+
+vds_uv_run_package vds_cli vds-cli confluence sync pdfs "$PAGE_ID" \
+  --dir "$TARGET_STATE_ROOT" \
+  --server "$SERVER"
+
+"$COORD" unlock "$AGENT_ID" "$lock_file" >/dev/null || true

package/skills/vds-skill/vds-scripts/scripts/target-state-automation/coordination.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# UV-PATTERN: NO-UV — This script uses only curl and inline python3 to call
+# the multi-agent coordination HTTP API.  It has no uv dependency and does not
+# need to be migrated to the worktree wrapper pattern.
+set -euo pipefail
+
+BASE_URL="${BASE_URL:-http://localhost:8000}"
+SESSION_ID="${SESSION_ID:-multi_agent_session_$(date +%Y%m%d)}"
+USER_ID="${USER_ID:-multi_agent_coordinator}"
+
+if [[ $# -lt 1 ]]; then
+  echo "Usage: $0 <command> [args]"
+  echo "Commands:"
+  echo "  init-tasks <tasks.json>"
+  echo "  register <agent_id> <capabilities_csv>"
+  echo "  heartbeat <agent_id>"
+  echo "  acquire <agent_id>"
+  echo "  progress <agent_id> <task_id> <progress>"
+  echo "  complete <agent_id> <task_id> <result_json>"
+  echo "  list-tasks"
+  echo "  list-agents"
+  echo "  lock <agent_id> <file_path> <operation>"
+  echo "  unlock <agent_id> <file_path>"
+  exit 1
+fi
+
+cmd="$1"
+shift
+
+case "$cmd" in
+  init-tasks)
+    tasks_file="$1"
+    curl -sS -X POST "$BASE_URL/api/v1/coordination/tasks/initialize" \
+      -H "Content-Type: application/json" \
+      -d @"$tasks_file"
+    ;;
+  register)
+    agent_id="$1"
+    capabilities_csv="$2"
+    IFS=',' read -r -a caps <<< "$capabilities_csv"
+    payload=$(python3 - <<'PY'
+import json, os
+agent_id = os.environ["AGENT_ID"]
+caps = os.environ["CAPS"].split(",") if os.environ["CAPS"] else []
+payload = {
+  "session_id": os.environ["SESSION_ID"],
+  "user_id": os.environ["USER_ID"],
+  "agent_id": agent_id,
+  "capabilities": [c.strip() for c in caps if c.strip()],
+  "max_concurrent_tasks": 1,
+  "metadata": {"org_id": "vds-internal"},
+}
+print(json.dumps(payload))
+PY
+)
+    AGENT_ID="$agent_id" CAPS="$capabilities_csv" SESSION_ID="$SESSION_ID" USER_ID="$USER_ID" \
+      curl -sS -X POST "$BASE_URL/api/v1/coordination/agents/register" \
+        -H "Content-Type: application/json" \
+        -d "$payload"
+    ;;
+  heartbeat)
+    agent_id="$1"
+    curl -sS -X POST "$BASE_URL/api/v1/coordination/agents/heartbeat" \
+      -H "Content-Type: application/json" \
+      -d "{\"session_id\":\"$SESSION_ID\",\"agent_id\":\"$agent_id\"}"
+    ;;
+  acquire)
+    agent_id="$1"
+    curl -sS -X POST "$BASE_URL/api/v1/coordination/tasks/acquire" \
+      -H "Content-Type: application/json" \
+      -d "{\"session_id\":\"$SESSION_ID\",\"user_id\":\"$USER_ID\",\"agent_id\":\"$agent_id\"}"
+    ;;
+  progress)
+    agent_id="$1"
+    task_id="$2"
+    progress="$3"
+    curl -sS -X POST "$BASE_URL/api/v1/coordination/tasks/progress" \
+      -H "Content-Type: application/json" \
+      -d "{\"session_id\":\"$SESSION_ID\",\"user_id\":\"$USER_ID\",\"task_id\":\"$task_id\",\"agent_id\":\"$agent_id\",\"progress\":$progress}"
+    ;;
+  complete)
+    agent_id="$1"
+    task_id="$2"
+    result_json="$3"
+    curl -sS -X POST "$BASE_URL/api/v1/coordination/tasks/complete" \
+      -H "Content-Type: application/json" \
+      -d "{\"session_id\":\"$SESSION_ID\",\"user_id\":\"$USER_ID\",\"task_id\":\"$task_id\",\"agent_id\":\"$agent_id\",\"result\":$result_json}"
+    ;;
+  list-tasks)
+    curl -sS "$BASE_URL/api/v1/coordination/tasks?session_id=$SESSION_ID"
+    ;;
+  list-agents)
+    curl -sS "$BASE_URL/api/v1/coordination/agents?session_id=$SESSION_ID"
+    ;;
+  lock)
+    agent_id="$1"
+    file_path="$2"
+    operation="$3"
+    curl -sS -X POST "$BASE_URL/api/v1/coordination/locks/acquire" \
+      -H "Content-Type: application/json" \
+      -d "{\"session_id\":\"$SESSION_ID\",\"user_id\":\"$USER_ID\",\"file_path\":\"$file_path\",\"agent_id\":\"$agent_id\",\"operation\":\"$operation\"}"
+    ;;
+  unlock)
+    agent_id="$1"
+    file_path="$2"
+    curl -sS -X POST "$BASE_URL/api/v1/coordination/locks/release" \
+      -H "Content-Type: application/json" \
+      -d "{\"session_id\":\"$SESSION_ID\",\"user_id\":\"$USER_ID\",\"file_path\":\"$file_path\",\"agent_id\":\"$agent_id\"}"
+    ;;
+  *)
+    echo "Unknown command: $cmd"
+    exit 1
+    ;;
+esac

package/skills/vds-skill/vds-scripts/scripts/target-state-automation/diagram_coordinator.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=scripts/vds_sh_helpers.sh
+source "$SCRIPT_DIR/../vds_sh_helpers.sh"
+
+ROOT="$(vds_resolve_scripts_root)"
+DOCS_ROOT="$(resolve_insurance_docs_root "$ROOT")"
+TARGET_STATE_ARCH_ROOT="$DOCS_ROOT/projects/INSURANCE/analysis/target-state/architecture"
+COORD="$ROOT/scripts/target-state-automation/coordination.sh"
+AGENT_ID="${AGENT_ID:-diagram-agent-01}"
+
+if [[ -z "${SERVICES:-}" ]]; then
+  SERVICES=$(vds_uv_run_package vds_cli vds-cli diagrams -- --project INSURANCE --list | sed -n 's/^  - //p')
+fi
+
+for svc in $SERVICES; do
+  echo "== $svc =="
+  lock_file="$TARGET_STATE_ARCH_ROOT/$svc/${svc}-component.puml"
+  "$COORD" lock "$AGENT_ID" "$lock_file" "generate-diagrams" >/dev/null || true
+  vds_uv_run_package vds_cli vds-cli diagrams -- --project INSURANCE --service "$svc" --use-case
+  "$COORD" unlock "$AGENT_ID" "$lock_file" >/dev/null || true
+  echo "-- done $svc --"
+done