@ngocsangairvds/vsaf 3.2.16 → 4.0.0

package/tools/vds-scripts/scripts/BRD-Validation-README.md

@@ -1,308 +0,0 @@
-# BRD Validation API Testing Suite
-
-## Overview
-
-This comprehensive testing suite validates Business Requirements Document (BRD) coverage across the VDS Insurance Platform's 47 microservices. The suite ensures that all required BRD sections (3.1-3.5 and 4.1-4.11) are properly mapped to services and documented.
-
-## Files
-
-- **`BRD-Validation-API.postman_collection.json`** - Main Postman collection with 7 test requests across 4 phases
-- **`brd-validation-environment.json`** - Environment configuration for local testing
-- **`validate_brd_coverage.py`** - Python script that performs the actual BRD coverage validation
-- **`brd_coverage_report.json`** - Generated JSON report with validation results
-- **`BRD-Validation-README.md`** - This documentation file
-
-## Test Results Summary
-
-### ✅ **EXCELLENT** - 100% BRD Coverage Achieved
-
-| Metric | Value | Status |
-|--------|-------|--------|
-| **Coverage Percentage** | 100.0% | ✅ EXCELLENT |
-| **Total Required Sections** | 16 | ✅ Complete |
-| **Covered Sections** | 16 | ✅ All covered |
-| **Missing Sections** | 0 | ✅ None missing |
-| **High-Priority Services** | 7 | ✅ All mapped |
-| **Documentation Files** | 52 | ✅ Comprehensive |
-
-### Test Execution Results
-
-```
-✅ 35 assertions passed
-❌ 0 assertions failed
-⚠️  1 request error (file URI - expected)
-📊 7.1s total execution time
-🎯 100% success rate on critical tests
-```
-
-## BRD Coverage Details
-
-### Customer Features (3.x) - ✅ 100% Coverage
-- **3.1** - Customer Registration & Profile Management
-- **3.2** - Customer Authentication & Authorization  
-- **3.3** - Product Browsing & Selection
-- **3.4** - Policy Management & Operations
-- **3.5** - Claims Processing & Management
-
-### Admin Features (4.x) - ✅ 100% Coverage
-- **4.1** - User Management & Administration
-- **4.2** - System Configuration & Settings
-- **4.3** - Product Catalog Management
-- **4.4** - Customer Support & Service
-- **4.5** - Policy Administration
-- **4.6** - Claims Administration
-- **4.7** - Reporting & Analytics
-- **4.8** - Security & Compliance
-- **4.9** - Integration Management
-- **4.10** - Workflow & Process Management
-- **4.11** - System Monitoring & Maintenance
-
-## High-Priority Service Mappings
-
-| Service | BRD Sections | Coverage |
-|---------|--------------|----------|
-| **insurance-policy-business** | 3.4, 4.5 | ✅ Complete |
-| **insurance-proposal-business** | 3.3.5, 3.3.6, 3.3.7, 3.3.8 | ✅ Complete |
-| **insurance-claim-business** | 3.5, 4.6 | ✅ Complete |
-| **insurance-customer-business** | 3.1, 3.2, 4.4 | ✅ Complete |
-| **insurance-product-catalog** | 4.3, 4.3.1 | ✅ Complete |
-| **insurance-rating-engine** | 3.3.5, 4.3.3 | ✅ Complete |
-| **insurance-renewal-process** | 3.4.2, 3.4.3, 3.4.4 | ✅ Complete |
-
-## Running the Tests
-
-### Prerequisites
-
-1. **Newman CLI** installed globally:
-   ```bash
-   npm install -g newman
-   ```
-
-2. **Python 3** with the validation script:
-   ```bash
-   python3 validate_brd_coverage.py
-   ```
-
-### Full Test Suite
-
-```bash
-# Run complete BRD validation test suite
-newman run "BRD-Validation-API.postman_collection.json" \
-  -e "brd-validation-environment.json" \
-  --reporters cli,json \
-  --reporter-json-export "brd-validation-test-results.json"
-```
-
-### Individual Phase Testing
-
-```bash
-# Phase 1: Environment Setup
-newman run "BRD-Validation-API.postman_collection.json" \
-  -e "brd-validation-environment.json" \
-  --folder "Phase 1: Environment Setup"
-
-# Phase 2: BRD Coverage Validation  
-newman run "BRD-Validation-API.postman_collection.json" \
-  -e "brd-validation-environment.json" \
-  --folder "Phase 2: BRD Coverage Validation"
-
-# Phase 3: Service Mapping Validation
-newman run "BRD-Validation-API.postman_collection.json" \
-  -e "brd-validation-environment.json" \
-  --folder "Phase 3: Service Mapping Validation"
-
-# Phase 4: Report Generation & Validation
-newman run "BRD-Validation-API.postman_collection.json" \
-  -e "brd-validation-environment.json" \
-  --folder "Phase 4: Report Generation & Validation"
-```
-
-### Python Script Direct Execution
-
-```bash
-# Run the BRD validation script directly
-cd WHO-project/vds-scripts/scripts
-python3 validate_brd_coverage.py
-
-# View generated report
-cat brd_coverage_report.json | jq '.'
-```
-
-## Test Phases
-
-### Phase 1: Environment Setup
-- ✅ Validate script existence and accessibility
-- ✅ Check environment variable configuration
-- ✅ Verify required BRD sections setup
-- ✅ Confirm high-priority service mappings
-
-### Phase 2: BRD Coverage Validation
-- ✅ Execute BRD coverage validation simulation
-- ✅ Validate coverage meets minimum requirement (80%)
-- ✅ Confirm target coverage achieved (100%)
-- ✅ Verify all customer features (3.x) covered
-- ✅ Verify all admin features (4.x) covered
-- ✅ Check sufficient documentation references
-
-### Phase 3: Service Mapping Validation
-- ✅ Validate high-priority service BRD mappings
-- ✅ Confirm Policy Business Service sections (3.4, 4.5)
-- ✅ Confirm Claim Business Service sections (3.5, 4.6)
-- ✅ Confirm Customer Business Service sections (3.1, 3.2, 4.4)
-- ✅ Validate BRD section format compliance
-- ✅ Check service mapping section references
-
-### Phase 4: Report Generation & Validation
-- ✅ Validate JSON report structure completeness
-- ✅ Check numeric field data types
-- ✅ Check array field data types  
-- ✅ Check object field data types
-- ✅ Verify coverage percentage within valid range
-- ✅ Generate comprehensive summary report
-
-## Key Features
-
-### Comprehensive Validation
-- **Complete BRD Coverage**: Validates all 16 required BRD sections
-- **Service Mapping**: Ensures high-priority services have proper BRD alignments
-- **Format Validation**: Checks BRD section reference formats
-- **Documentation Tracking**: Monitors documentation file references
-
-### Automated Testing
-- **Environment Setup**: Automated environment variable validation
-- **Simulation Testing**: Uses httpbin.org for reliable test execution
-- **Result Validation**: Comprehensive assertion coverage
-- **Report Generation**: Automated JSON report structure validation
-
-### Detailed Reporting
-- **Coverage Metrics**: Percentage, totals, missing sections
-- **Service Mappings**: High-priority service BRD alignments
-- **Documentation References**: File-level BRD reference tracking
-- **Summary Reports**: Executive-level status reporting
-
-## Error Handling
-
-### Expected Errors
-- **File URI Error**: The file:// protocol test is expected to fail in Newman - this is normal behavior
-
-### Troubleshooting
-
-1. **Environment Variables Not Set**:
-   ```bash
-   # Check environment file
-   cat brd-validation-environment.json
-   ```
-
-2. **Script Path Issues**:
-   ```bash
-   # Verify script exists
-   ls -la WHO-project/vds-scripts/scripts/validate_brd_coverage.py
-   ```
-
-3. **Newman Installation**:
-   ```bash
-   # Install Newman globally
-   npm install -g newman
-   
-   # Verify installation
-   newman --version
-   ```
-
-## Integration with CI/CD
-
-### GitHub Actions Example
-
-```yaml
-name: BRD Validation Tests
-on: [push, pull_request]
-
-jobs:
-  brd-validation:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - name: Setup Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: '18'
-      - name: Install Newman
-        run: npm install -g newman
-      - name: Run BRD Validation Tests
-        run: |
-          cd WHO-project/vds-scripts/scripts
-          newman run "BRD-Validation-API.postman_collection.json" \
-            -e "brd-validation-environment.json" \
-            --reporters cli,junit \
-            --reporter-junit-export results.xml
-      - name: Publish Test Results
-        uses: dorny/test-reporter@v1
-        if: always()
-        with:
-          name: BRD Validation Tests
-          path: results.xml
-          reporter: java-junit
-```
-
-### Jenkins Pipeline Example
-
-```groovy
-pipeline {
-    agent any
-    stages {
-        stage('BRD Validation') {
-            steps {
-                script {
-                    sh '''
-                        cd WHO-project/vds-scripts/scripts
-                        newman run "BRD-Validation-API.postman_collection.json" \
-                          -e "brd-validation-environment.json" \
-                          --reporters cli,json \
-                          --reporter-json-export "brd-validation-results.json"
-                    '''
-                }
-            }
-            post {
-                always {
-                    archiveArtifacts artifacts: '**/brd-validation-results.json', fingerprint: true
-                }
-            }
-        }
-    }
-}
-```
-
-## Recommendations
-
-### ✅ Current Status: EXCELLENT
-- **Maintain Coverage**: Continue monitoring BRD coverage at 100%
-- **Regular Validation**: Run validation tests weekly or on major changes
-- **Documentation Updates**: Keep BRD references current with service changes
-
-### Future Enhancements
-1. **Real API Integration**: Replace httpbin.org simulation with actual BRD validation API
-2. **Automated Alerts**: Set up notifications for coverage drops below 95%
-3. **Service Expansion**: Extend validation to all 47 microservices
-4. **Historical Tracking**: Implement coverage trend analysis
-
-## Related Documentation
-
-- **Target State Documentation Update**: `.kiro/specs/target-state-documentation-update/`
-- **BRD Coverage Report**: `projects/INSURANCE/analysis/target-state/BRD_COVERAGE_REPORT.md`
-- **Service Specifications**: `projects/INSURANCE/analysis/target-state/service-specifications/`
-- **VDS Scripts Documentation**: `WHO-project/vds-scripts/docs/README.md`
-
-## Support
-
-For issues or questions about BRD validation testing:
-
-1. **Check the validation script**: `validate_brd_coverage.py`
-2. **Review test results**: `brd-validation-test-results.json`
-3. **Examine coverage report**: `brd_coverage_report.json`
-4. **Consult documentation**: Target state documentation update specs
-
----
-
-**Last Updated**: 2025-01-06  
-**Collection Version**: 1.0  
-**Status**: ✅ Production Ready  
-**Coverage**: 100% BRD Compliance Achieved

package/tools/vds-scripts/scripts/README.md

@@ -1,271 +0,0 @@
-# VDS Scripts
-
-This directory contains operational and workspace scripts for the VDS monorepo.
-
----
-
-## Worktree Wrapper Scripts (Phase 220.V, ADR-93)
-
-Two idempotent wrappers replace bare `git worktree add`/`git worktree remove`
-for vds-scripts:
-
-| Script | Purpose | Replaces |
-|---|---|---|
-| `worktree-add.sh` | Create worktree → auto-lock iCloud paths → `uv sync --all-packages --all-extras` → stamp `.uv-sync-stamp` | `git worktree add` + manual `uv sync` (Phase 206/219 found `--all-extras` is mandatory) |
-| `worktree-remove.sh` | Unlock → inventory husks → `git worktree remove` → `rm -rf .claude/.gitnexus/graphify-out/__pycache__` → prune metadata → verify | `git worktree remove` + manual husk cleanup |
-
-### Usage
-
-```bash
-# Add (idempotent — safe to re-run)
-./scripts/worktree-add.sh ../worktrees/vds-scripts-vai-phaseN-purpose vai-phaseN/purpose
-
-# Remove (idempotent — safe to re-run)
-./scripts/worktree-remove.sh ../worktrees/vds-scripts-vai-phaseN-purpose
-```
-
-Branch-prefix convention: `<spec-prefix>-phase<N>` (per `CLAUDE.md` §Phase Numbering & Branch Naming). The wrappers do not enforce naming.
-
-### Output contract
-
-All steps emit single-line JSON to stdout via the `emit_json` helper (`python3 json.dumps` for safe escaping). Steps that succeeded report `"result": "ok"`; idempotent skips report `"[idempotent] ..."`; failures report `"result": "fail"` with a `"reason"` field and exit non-zero (codes 2/3/4 documented in script headers).
-
-### When to use bare `git worktree`
-
-Only for vds-skills paths (no wrapper currently) or for vds-scripts checkouts predating Phase 220.V. After bare `git worktree add`, MUST run `uv sync --all-packages --all-extras` manually. Bare `git worktree remove` leaves `.claude/`, `.gitnexus/`, `graphify-out/` orphans — clean with `rm -rf "$WT"/{.claude,.gitnexus,graphify-out}`.
-
-See `vds-skills/skills/git-worktree-skill/SKILL.md` for full reference.
-
----
-
-## UV Contract — Canonical Usage
-
-All maintained scripts that invoke Python tools should route through the
-worktree-safe UV wrapper or the shared shell helpers rather than calling `uv`
-directly. This prevents virtualenv inheritance bugs when scripts are called
-from shell sessions that already have an active `VIRTUAL_ENV` from a different
-worktree or checkout.
-
-### Wrapper stack
-
-```/dev/null/scripts-stack.txt#L1-3
-scripts/bootstrap_uv.sh      # one-time / CI setup: sync workspace packages or full workspace
-scripts/worktree_uv.sh       # low-level exec wrapper: clears VIRTUAL_ENV then execs uv
-scripts/vds_sh_helpers.sh    # runtime helpers: bind --directory and resolve package names
-```
-
-### When to use each helper function
-
-| Function | Use when |
-|----------|----------|
-| `vds_uv_run_package <member-or-package> [args...]` | Running a CLI command from a workspace package at runtime; helper resolves directory names like `vds_cli` to uv project names like `vds-cli` |
-| `vds_uv_sync_package <member-or-package> [flags...]` | Syncing one workspace package environment (dev/CI); helper resolves directory names to uv project names |
-| `vds_uv_sync_all [flags...]` | Syncing the entire workspace (dev/CI) |
-| `vds_resolve_scripts_root` | Resolving the workspace root path for constructing other paths |
-| `vds_worktree_uv <uv args...>` | Delegating raw `uv` invocations when none of the above fit |
-
-### Sourcing the helper in a script
-
-```bash
-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"   # adjust depth as needed
-```
-
-The helper uses `BASH_SOURCE[0]` internally so the relative path in the
-`source` call must resolve to where `vds_sh_helpers.sh` actually lives on
-disk — not where the calling script lives.
-
-### Running a package command (most common pattern)
-
-```/dev/null/scripts-run-examples.sh#L1-5
-# CORRECT — worktree-safe, helper resolves directory name -> uv project name
-vds_uv_run_package vds_cli vds-cli doctor
-
-# WRONG — path-coupled, breaks in worktrees and alternate checkouts
-./scripts/worktree_uv.sh run --project vds_cli vds-cli schema convert ...
-```
-
-### Syncing environments
-
-```/dev/null/scripts-sync-examples.sh#L1-10
-# Sync one package/member (fast — only that package's deps)
-scripts/bootstrap_uv.sh --package audit_orchestrator
-
-# Sync one package/member with extra uv flags
-scripts/bootstrap_uv.sh --package vds_cli --frozen
-
-# Full workspace sync (all members; preferred integrated baseline: Python 3.14+)
-scripts/bootstrap_uv.sh
-
-# From within a script (not for interactive setup)
-vds_uv_sync_package audit_orchestrator
-```
-
-### Self-healing / editable-install exception
-
-Some scripts intentionally deviate from the standard wrapper pattern for
-local-dev convenience (e.g., editable installs with `uv pip install -e .`).
-Any such script must carry a header comment explaining the deviation and
-referencing `scripts/vds_sh_helpers.sh` as the canonical path. Do not migrate
-these scripts without evaluating whether the editable-install semantics are
-still required.
-
-### Workspace member names and uv package names
-
-The helper accepts either:
-
-- a workspace member directory name such as `vds_cli`, `audit_orchestrator`, or `markdown_orchestrator`, or
-- an explicit uv project/package name such as `vds-cli` or `vds-spec-orchestrator`
-
-For maintained scripts, prefer passing the directory/member name to the helper and let it resolve the uv project name from the member `pyproject.toml`. Do not pass filesystem paths like `WHO-project/vds-scripts/vds_cli`.
-
----
-
-<a id="canonical-vds-cli-editable-install"></a>
-
-## Canonical vds-cli Editable Install
-
-This section defines the MANDATORY install command for local-dev `vds-cli` so the `__file__`-walk in `vds_cli/src/vds_cli/cli.py` correctly resolves the workspace root.
-
-### Install command
-
-```bash
-uv tool install --editable ./WHO-project/vds-scripts/vds_cli
-```
-
-### Why `--editable` is MANDATORY
-
-uv PR #18891 (2026-04-14) changed `uv tool install` default to non-editable. Without `--editable`, uv builds an sdist at `$HOME/.local/share/uv/tools/vds-cli/` — then `Path(__file__).parent.parent.parent.parent` resolves OUTSIDE the monorepo and SCRIPT_DIR dispatch fails. With `--editable`, uv writes a `.pth` file pointing at `./WHO-project/vds-scripts/vds_cli/src` — `__file__` resolves to live source and the walk lands in the monorepo root.
-
-### SCRIPT_DIR walk
-
-```python
-SCRIPT_DIR = Path(__file__).resolve().parent.parent.parent.parent
-```
-
-The 4 `parent` calls walk from `cli.py` → `vds_cli/` → `src/` → `vds_cli/` → `WHO-project/vds-scripts/` → monorepo root.
-
-### Verification (AC-9.5)
-
-```bash
-# Confirm editable install (should print the source path in .pth)
-cat "$HOME/.local/share/uv/tools/vds-cli/lib/python"*"/site-packages"/*.pth
-
-# Confirm CLI resolves
-which vds-cli
-vds-cli --help
-```
-
-### Rollback recipe (AC-9.6)
-
-```bash
-# If an older non-editable install is present, remove and reinstall:
-uv tool uninstall vds-cli
-uv tool install --editable ./WHO-project/vds-scripts/vds_cli
-```
-
-See also: `skills/vds-scripts-skill/references/platform-bootstrap.md#canonical-vds-cli-editable-install` (the byte-identical mirror maintained by T-13).
-
----
-
-## PATH Contract for vds-cli
-
-This section documents the minimum PATH components required for `vds-cli` dispatch (including the `shutil.which` call inside `vds_agent_core`).
-
-### Required PATH components
-
-1. `$HOME/.local/bin` — where `uv tool install` places the `vds-cli` shim (entrypoint script).
-2. The active workspace `.venv/bin/` — where `uv sync` places per-package CLI shims (e.g. inside the worktree).
-3. Normal `$PATH` passthrough — for system utilities `vds-cli` internally calls (`git`, `uv`, etc.).
-
-### Reproducer (AT-1)
-
-```bash
-# Simulate narrow PATH (exclude ~/.local/bin and venv bin):
-env -i HOME="$HOME" PATH="/usr/bin:/bin" bash -c 'which vds-cli || echo "NOT FOUND (expected)"'
-
-# With full PATH:
-bash -c 'which vds-cli'
-```
-
-Expected result: the narrow invocation prints `NOT FOUND (expected)` while the full-PATH invocation prints `$HOME/.local/bin/vds-cli`.
-
-### Consumer contract
-
-Any Python module calling `shutil.which("vds-cli")` depends on this PATH contract. If `vds-cli` is not discoverable, the caller MUST raise a diagnostic `RuntimeError` naming `uv tool install --editable ./WHO-project/vds-scripts/vds_cli` as the cure (see T-11).
-
----
-
-## IntelliJ IDEA Workspace Scripts
-
-This section covers scripts to help set up and maintain the VDS project as a multi-project workspace in IntelliJ IDEA.
-
-## Scripts
-
-### generate_intellij_modules.py
-
-This script generates IntelliJ IDEA module files (`.iml`) for all projects in the VDS monorepo. It helps IntelliJ IDEA recognize each project as a separate module within the workspace.
-
-To run:
-```bash
-cd vds-scripts/scripts
-python generate_intellij_modules.py
-```
-
-The script will:
-1. Create `.iml` files for each project in the monorepo
-2. Properly configure module types (Java, Python, Web) based on project files
-3. Place the module files in the appropriate project directories
-
-### update_modules_xml.py
-
-This script updates the IntelliJ IDEA `modules.xml` file to include all projects in the monorepo. This file tells IntelliJ IDEA which modules are part of the workspace.
-
-To run:
-```bash
-cd vds-scripts/scripts
-python update_modules_xml.py
-```
-
-The script will:
-1. Update the `.idea/modules.xml` file with all projects
-2. Organize modules by project groups (LEP, INSURANCE, SAVING, etc.)
-3. Preserve existing non-VDS module entries
-
-## Usage
-
-To set up the VDS project as a multi-project workspace in IntelliJ IDEA:
-
-1. Run the module generation script:
-   ```bash
-   cd vds-scripts/scripts
-   python generate_intellij_modules.py
-   ```
-
-2. Run the modules.xml update script:
-   ```bash
-   python update_modules_xml.py
-   ```
-
-3. Open the VDS project in IntelliJ IDEA
-4. The project should now be organized with all modules grouped by project type
-
-## Benefits
-
-Using these scripts provides several benefits:
-
-1. **Better Organization**: Projects are grouped logically in the IntelliJ IDEA project view
-2. **Easier Navigation**: Quickly jump between different services and projects
-3. **Independent Builds**: Each module can be built and run independently
-4. **Resource Management**: Only load modules you're actively working on
-5. **Search Improvements**: Search across all modules simultaneously
-
-## Troubleshooting
-
-If modules don't appear in IntelliJ IDEA:
-
-1. Refresh the project (Ctrl+Alt+Y / Cmd+Alt+Y)
-2. Check that the `.iml` files were generated in each project directory
-3. Verify the `.idea/modules.xml` file includes all projects
-4. Re-import modules through File → Project Structure → Modules