@ngocsangairvds/vsaf 3.1.27 → 3.2.1

package/tools/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/tools/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

package/tools/vds-scripts/scripts/target-state-automation/docs_root.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# docs_root.sh — Backward-compatibility shim.
+#
+# Delegates to scripts/vds_sh_helpers.sh which provides the authoritative
+# implementations.  Existing callers that source this file and call
+# resolve_repo_root() or resolve_insurance_docs_root() continue to work
+# without modification.
+
+set -euo pipefail
+
+_DOCS_ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../vds_sh_helpers.sh
+source "$_DOCS_ROOT_DIR/../vds_sh_helpers.sh"
+
+# resolve_repo_root — kept for backward compatibility.
+# Returns the vds-scripts workspace root (same as vds_resolve_scripts_root).
+resolve_repo_root() {
+  vds_resolve_scripts_root
+}
+
+# resolve_insurance_docs_root is already provided by vds_sh_helpers.sh.
+# No re-declaration needed.

package/tools/vds-scripts/scripts/target-state-automation/generate_diagrams.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Generate component + sequence + use-case diagrams for all INSURANCE services.
+# Requires: uv, vds_cli project synced.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=scripts/vds_sh_helpers.sh
+source "$SCRIPT_DIR/../vds_sh_helpers.sh"
+
+services=$(vds_uv_run_package vds_cli vds-cli diagrams -- --project INSURANCE --list | grep "insurance-")
+
+for svc in $services; do
+  echo "Generating diagrams for: $svc"
+  vds_uv_run_package vds_cli vds-cli diagrams -- --project INSURANCE --service "$svc" --component --sequence --use-case
+done
+
+echo "Validating diagrams..."
+vds_uv_run_package vds_cli vds-cli diagrams -- --project INSURANCE --validate-existing
+
+echo "Done."
+

package/tools/vds-scripts/scripts/target-state-automation/markdown_coordinator.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=WHO-project/vds-scripts/scripts/vds_sh_helpers.sh
+source "$SCRIPT_DIR/../vds_sh_helpers.sh"
+
+SCRIPTS_ROOT="$(vds_resolve_scripts_root)"
+MONO_ROOT="$(dirname "$(dirname "$SCRIPTS_ROOT")")"
+DOCS_ROOT="$(resolve_insurance_docs_root "$MONO_ROOT")"
+DOC_ROOT="$DOCS_ROOT/projects/INSURANCE/analysis/target-state"
+COORD="$SCRIPTS_ROOT/scripts/target-state-automation/coordination.sh"
+AGENT_ID="${AGENT_ID:-markdown-agent-01}"
+
+lock_file="$DOC_ROOT/README.md"
+"$COORD" lock "$AGENT_ID" "$lock_file" "markdown-check" >/dev/null || true
+
+cd "$DOC_ROOT"
+vds_uv_run_package markdown_orchestrator -- vds-markdown check \
+  architecture/*.md \
+  architecture/**/*.md \
+  service-specifications/**/*.md \
+  *.md
+
+"$COORD" unlock "$AGENT_ID" "$lock_file" >/dev/null || true

package/tools/vds-scripts/scripts/target-state-automation/progress_dashboard.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# UV-PATTERN: NO-UV — Delegates entirely to coordination.sh (curl/HTTP calls).
+# No uv invocation needed.
+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)"
+COORD="$ROOT/scripts/target-state-automation/coordination.sh"
+
+echo "== Agents =="
+"$COORD" list-agents
+
+echo "== Tasks =="
+"$COORD" list-tasks

package/tools/vds-scripts/scripts/target-state-automation/schema_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:-schema-agent-01}"
+
+if [[ -z "${SERVICES:-}" ]]; then
+  SERVICES=$(ls -d "$TARGET_STATE_ARCH_ROOT"/insurance-* 2>/dev/null | xargs -n1 basename)
+fi
+
+for svc in $SERVICES; do
+  echo "== $svc =="
+  schema_file="$TARGET_STATE_ARCH_ROOT/$svc/${svc}-database-target-schema.md"
+  "$COORD" lock "$AGENT_ID" "$schema_file" "validate-schema" >/dev/null || true
+  vds_uv_run_package vds_cli vds-cli schema convert --service "$svc" --format plantuml --validate
+  "$COORD" unlock "$AGENT_ID" "$schema_file" >/dev/null || true
+  echo "-- done $svc --"
+done

package/tools/vds-scripts/scripts/target-state-automation/sync_confluence.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Sync docs and diagrams to Confluence.
+# Requires: uv, vds_cli project synced, proper tokens in the shared VDS env file
+
+PAGE_ID=${1:-166465076}  # override with first arg
+
+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")"
+DOC_DIR="$DOCS_ROOT/projects/INSURANCE/analysis/target-state"
+ARCH_DIR="$DOC_DIR/architecture"
+
+echo "Syncing PDFs (docs) to Confluence page $PAGE_ID..."
+vds_uv_run_package vds_cli vds-cli confluence sync pdfs \
+  "$PAGE_ID" \
+  --dir "$DOC_DIR" \
+  --server external
+
+echo "Syncing PNG/SVG (diagrams) to Confluence page $PAGE_ID..."
+vds_uv_run_package vds_cli vds-cli confluence sync pngs \
+  "$PAGE_ID" \
+  --dir "$ARCH_DIR" \
+  --server external
+
+echo "Done."

package/tools/vds-scripts/scripts/target-state-automation/update_dependencies.sh

@@ -0,0 +1,19 @@
+#!/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"
+FLAGS="${UV_SYNC_FLAGS:-}"
+
+# Sync a narrow subset of workspace packages for diagram/markdown workflows.
+# This is a targeted helper, not the canonical full-workspace bootstrap path.
+if [[ -n "$FLAGS" ]]; then
+  # shellcheck disable=SC2206
+  EXTRA_ARGS=( $FLAGS )
+else
+  EXTRA_ARGS=()
+fi
+
+vds_uv_sync_package vds_cli "${EXTRA_ARGS[@]+"${EXTRA_ARGS[@]}"}"
+vds_uv_sync_package markdown_orchestrator "${EXTRA_ARGS[@]+"${EXTRA_ARGS[@]}"}"

package/tools/vds-scripts/scripts/target-state-automation/validate_links.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# UV-PATTERN: NO-UV — Uses inline python3 for link validation; no uv invocation.
+# Root resolution goes through docs_root.sh shim (safe marker-based).
+# No migration needed.
+set -euo pipefail
+
+# Validate relative markdown links within target-state docs.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=WHO-project/vds-scripts/scripts/target-state-automation/docs_root.sh
+source "$SCRIPT_DIR/docs_root.sh"
+
+ROOT="$(resolve_repo_root)"
+TARGET_STATE_ROOT="$(resolve_insurance_docs_root "$ROOT")/projects/INSURANCE/analysis/target-state"
+
+TARGET_STATE_ROOT="$TARGET_STATE_ROOT" python3 - <<'PY'
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from urllib.parse import unquote
+
+root = Path(os.environ["TARGET_STATE_ROOT"]).resolve()
+md_files = sorted([p for p in root.rglob('*.md') if p.is_file()])
+
+link_re = re.compile(r"!?\[[^\]]*\]\(([^)]+)\)")
+
+errors: list[str] = []
+
+for f in md_files:
+    text = f.read_text(encoding='utf-8', errors='ignore')
+    for raw in link_re.findall(text):
+        link = raw.strip()
+        if not link:
+            continue
+        # strip title part: (path "title")
+        if ' ' in link and not link.startswith('http'):
+            link = link.split(' ')[0]
+        link = unquote(link)
+
+        # Skip anchors/external links/schemes
+        if link.startswith(('#', 'http://', 'https://', 'mailto:')):
+            continue
+        if '://' in link:  # includes file://
+            continue
+        if link.startswith(('ac:', 'ri:')):
+            continue
+        if '{' in link or '}' in link:  # template placeholders
+            continue
+
+        # strip fragment
+        link = link.split('#', 1)[0]
+        if not link or link.startswith('data:'):
+            continue
+        if link.endswith('/'):
+            continue  # directory navigation links are allowed
+
+        # Only validate links that look like local files
+        allowed_ext = {'.md', '.pdf', '.puml', '.plantuml', '.png', '.svg', '.mmd'}
+        if Path(link).suffix and Path(link).suffix.lower() not in allowed_ext:
+            continue
+        if not Path(link).suffix:
+            continue
+
+        target = (f.parent / link).resolve()
+        # Skip links that point outside target-state root
+        try:
+            target.relative_to(root.resolve())
+        except ValueError:
+            continue
+
+        if not target.exists():
+            errors.append(f"{f.relative_to(root)} -> {raw}")
+
+if errors:
+    print('❌ Link validation failed (missing targets)')
+    for e in errors[:200]:
+        print('-', e)
+    if len(errors) > 200:
+        print(f"... and {len(errors)-200} more")
+    raise SystemExit(1)
+
+print('✅ Link validation passed')
+print('Files scanned:', len(md_files))
+PY

package/tools/vds-scripts/scripts/target-state-automation/validate_markdown.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Validate markdown in target-state docs.
+# Requires: uv, markdown_orchestrator project synced.
+#
+# UV-PATTERN EXCEPTION: This script intentionally uses `uv pip install -e .`
+# rather than the standard helper-driven workspace pattern (for example
+# `vds_uv_run_package markdown_orchestrator ...`). Reason: the script is a
+# local-dev helper that installs the package
+# in editable mode so authors can iterate on the markdown_orchestrator source
+# without re-syncing the full workspace.  This is a deliberate trade-off for
+# development convenience, not an oversight.  Do NOT migrate to the worktree
+# wrapper pattern without first evaluating whether the editable-install
+# semantics are still needed.
+#
+# See scripts/vds_sh_helpers.sh for the canonical UV invocation helpers.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=WHO-project/vds-scripts/scripts/target-state-automation/docs_root.sh
+source "$SCRIPT_DIR/docs_root.sh"
+
+ROOT="$(resolve_repo_root)"
+VDS_SCRIPTS="$ROOT/WHO-project/vds-scripts"
+DOCS_ROOT="$(resolve_insurance_docs_root "$ROOT")"
+TARGET_STATE="$DOCS_ROOT/projects/INSURANCE/analysis/target-state"
+
+echo "Validating markdown in target-state..."
+echo "========================================"
+
+# Run markdown validation — editable install intentional (see header comment).
+cd "$VDS_SCRIPTS/markdown_orchestrator"
+uv pip install -e . --quiet
+uv run -- vds-markdown check \
+  "$TARGET_STATE"/architecture/*.md \
+  "$TARGET_STATE"/architecture/**/*.md \
+  "$TARGET_STATE"/service-specifications/**/*.md \
+  "$TARGET_STATE"/*.md
+
+VALIDATION_EXIT_CODE=$?
+
+echo ""
+echo "========================================"
+echo "Markdown validation completed with exit code: $VALIDATION_EXIT_CODE"
+
+if [ $VALIDATION_EXIT_CODE -eq 0 ]; then
+  echo "Markdown validation PASSED"
+else
+  echo "Markdown validation FAILED with exit code: $VALIDATION_EXIT_CODE"
+fi
+
+echo ""

package/tools/vds-scripts/scripts/target-state-automation/validate_schemas.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Validate/generate PlantUML ERD diagrams for all INSURANCE services.
+# Requires: uv, vds_cli project synced.
+#
+# FOLLOW-UP DRIFT NOTE:
+# This script now routes through the canonical helper contract correctly, but
+# the underlying schema command surface appears to have drifted: the current
+# `vds-cli schema` / `vds-schema-convert` compatibility layer no longer accepts
+# the historical `convert --all --format plantuml --validate-all` shape.
+# Keep this script classified as follow-up schema-command alignment work rather
+# than treating any remaining failure here as a helper-layer regression.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=WHO-project/vds-scripts/scripts/vds_sh_helpers.sh
+source "$SCRIPT_DIR/../vds_sh_helpers.sh"
+
+echo "Validating PlantUML ERDs for all services..."
+echo "ERROR: schema validation automation is currently unavailable in this worktree." >&2
+echo "The shell helper migration is complete, but the underlying schema command surface is still a follow-up item." >&2
+echo "Use help-first discovery to inspect the current schema compatibility layer:" >&2
+echo "  ./scripts/worktree_uv.sh run --project vds_cli vds-cli schema --help" >&2
+echo "  ./scripts/worktree_uv.sh run --project schema_converter vds-schema-convert convert --help" >&2
+exit 2
+

package/tools/vds-scripts/scripts/target-state-automation/validate_structure.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# UV-PATTERN: NO-UV — Uses inline python3 for structure validation; no uv invocation.
+# Root resolution goes through docs_root.sh shim (safe marker-based).
+# No migration needed.
+set -euo pipefail
+
+# Validate folder/file structure for target-state docs.
+# Checks:
+# - architecture/insurance-*/ required docs exist
+# - service-specifications/**/ required docs exist
+# - each architecture service has a matching service-spec folder
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=WHO-project/vds-scripts/scripts/target-state-automation/docs_root.sh
+source "$SCRIPT_DIR/docs_root.sh"
+
+ROOT="$(resolve_repo_root)"
+TARGET_STATE_ROOT="$(resolve_insurance_docs_root "$ROOT")/projects/INSURANCE/analysis/target-state"
+
+TARGET_STATE_ROOT="$TARGET_STATE_ROOT" python3 - <<'PY'
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+root = Path(os.environ["TARGET_STATE_ROOT"]).resolve()
+arch = root / 'architecture'
+spec = root / 'service-specifications'
+
+arch_required = [
+    'architecture.md',
+    'api-contracts.md',
+    'integration-patterns.md',
+    'database-target-schema.md',
+]
+
+# service-spec required (by suffix)
+spec_required_suffixes = [
+    '_SERVICE_SPEC.md',
+    '_API_SPEC.md',
+    '_DATA_MODEL.md',
+    '_BUSINESS_LOGIC.md',
+]
+
+errors: list[str] = []
+
+excluded_arch_svcs = {
+    # Known non-service apps/libs (no target-state schema/spec required)
+    'insurance-common',
+    'insurance-insuremo-common',
+    'insurance-customer-webview',
+}
+
+arch_svcs = sorted(
+    [
+        p
+        for p in arch.iterdir()
+        if p.is_dir() and p.name.startswith('insurance-') and p.name not in excluded_arch_svcs
+    ]
+)
+
+# Validate architecture per service
+for svc_dir in arch_svcs:
+    svc = svc_dir.name
+    for suf in arch_required:
+        fname = f"{svc}-{suf}"
+        if not (svc_dir / fname).exists():
+            errors.append(f"ARCH missing: {svc}/{fname}")
+
+# Identify service-spec dirs based on *_SERVICE_SPEC.md
+spec_service_dirs = sorted({p.parent for p in spec.rglob('*_SERVICE_SPEC.md')}, key=lambda p: str(p))
+
+# Validate service-spec required docs
+for d in spec_service_dirs:
+    if not (d / 'README.md').exists():
+        errors.append(f"SPEC missing: {d.relative_to(spec)}/README.md")
+    for suf in spec_required_suffixes:
+        if not any(p.name.endswith(suf) for p in d.glob('*.md')):
+            errors.append(f"SPEC missing: {d.relative_to(spec)}/*{suf}")
+
+# Ensure each architecture service has matching spec dir (by last path segment match)
+spec_paths = [str(p.relative_to(spec)) for p in spec_service_dirs]
+for svc_dir in arch_svcs:
+    key = svc_dir.name.replace('insurance-', '')
+    found = any(s.endswith('/' + key) or s == key for s in spec_paths)
+    if not found:
+        errors.append(f"SPEC missing for architecture service: {svc_dir.name} (expected folder ending with '{key}')")
+
+if errors:
+    print('❌ Structure validation failed')
+    for e in errors:
+        print('-', e)
+    raise SystemExit(1)
+
+print('✅ Structure validation passed')
+print(f"Architecture services: {len(arch_svcs)}")
+print(f"Service-spec folders: {len(spec_service_dirs)}")
+PY