npm - @ngocsangairvds/vsaf - Versions diffs - 3.2.14 → 3.2.16 - Mend

@ngocsangairvds/vsaf 3.2.14 → 3.2.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1442) hide show

package/tools/vds-scripts/audit_orchestrator/docs/DEPLOYMENT.md DELETED Viewed

@@ -1,778 +0,0 @@
-# Audit Orchestrator - Deployment Guide
-This guide covers installation, configuration, and deployment of the VDS Audit Orchestrator.
-## Table of Contents
-- [Overview](#overview)
-- [Prerequisites](#prerequisites)
-- [Installation](#installation)
-- [Configuration](#configuration)
-- [Ollama Embeddings Setup](#ollama-embeddings-setup)
-- [Running Audits](#running-audits)
-- [Template Creation](#template-creation-guide)
-- [Troubleshooting](#troubleshooting)
-- [CI/CD Integration](#cicd-integration)
----
-## Overview
-The Audit Orchestrator is a CLI tool that automates repository auditing against configurable templates. It integrates with VDS orchestrators (Bitbucket, Confluence, SonarQube, Git) to gather comprehensive data and generate detailed reports.
-**Key Features:**
-- Plugin-based check architecture for extensibility
-- Excel and Google Sheets template support
-- Async processing for 200+ repositories
-- Multiple output formats (Excel, JSON, Markdown, SARIF)
-- Adaptive weighting based on project profiles
-- Section-level scoring policies
----
-## Prerequisites
-### System Requirements
-| Requirement | Minimum | Recommended |
-|------------|---------|-------------|
-| Python | 3.14+ | 3.14+ |
-| RAM | 4 GB | 8 GB+ |
-| Disk | 500 MB | 1 GB+ |
-### Required Software
-1. **Python 3.14+**
-   ```bash
-   python3 --version
-   # Should output Python 3.14.x or higher
-   ```
-2. **uv Package Manager**
-   ```bash
-   curl -LsSf https://astral.sh/uv/install.sh | sh
-   # or via pip
-   pip install uv
-   ```
-3. **VDS Credentials** (for external integrations)
-   - Bitbucket API token (for branch permissions, merge conditions)
-   - Confluence API token (for documentation checks)
-   - SonarQube token (for quality gate checks)
-   - Google Sheets credentials (optional, for Google Sheets templates)
-### Orchestrator Dependencies
-The Audit Orchestrator requires these VDS orchestrators to be installed:
-```bash
-# These are referenced in pyproject.toml and automatically resolved
-vds-cli-common        # Shared utilities
-vds-excel-orchestrator  # Excel template loading
-vds-bitbucket-orchestrator  # Bitbucket integration
-vds-confluence-orchestrator  # Confluence integration
-vds-sonarqube-orchestrator  # SonarQube integration
-vds-google-sheets-orchestrator  # Google Sheets support (optional)
-```
----
-## Installation
-### 1. Clone or Navigate to Project
-```bash
-cd /path/to/vds/WHO-project/vds-scripts/audit_orchestrator
-```
-### 2. Create Virtual Environment and Install Dependencies
-```bash
-# Create virtual environment
-uv venv --python 3.14
-# Install dependencies
-uv sync --dev
-```
-### 3. Verify Installation
-```bash
-# Run the CLI
-uv run vds-audit --version
-# Expected output: vds-audit-orchestrator 0.1.0
-# List available checks
-uv run vds-audit list-checks
-```
-### 4. Optional: Install as Package
-```bash
-# Install in development mode
-uv pip install -e .
-# Now you can run directly
-vds-audit --version
-```
-### 5. Docker Build (repo root context)
-The Dockerfile relies on local path dependencies, so build from the repo root:
-```bash
-cd /path/to/vds
-docker build -f WHO-project/vds-scripts/audit_orchestrator/Dockerfile \
-  -t vds-audit-orchestrator:local .
-```
-### 6. Docker Compose Reset-First Runbook (Phase 47 Track P)
-Run infrastructure setup in this order to avoid stale volume/state drift.
-```bash
-cd /path/to/vds/WHO-project/vds-scripts/audit_orchestrator
-# 1) Reset persisted infra state
-docker compose down -v
-# 2) Start deterministic Postgres+pgvector runtime
-docker compose up -d audit-postgres
-# 3) Export hard-cut DSNs (no alias/fallback contract)
-export VDS_AUDIT_STATE_DSN="postgresql://postgres:${VDS_POSTGRES_PASSWORD:-vds_postgres_secret}@localhost:5432/vds_platform?options=-c%20search_path%3Daudit_state"
-export VDS_AUDIT_LANGGRAPH__POSTGRES_DSN="$VDS_AUDIT_STATE_DSN"
-# Note: post ecosystem-infrastructure-evolution v2.10.0, audit uses the shared
-# vds-postgres on port 5432 with the `audit_state` schema. The legacy port
-# 5434 / `vds_audit_checkpoints` DB remain referenced in docker/ROLLBACK.md.
-# 4) Initialize state schema
-uv run vds-audit state init --state-dsn "$VDS_AUDIT_STATE_DSN"
-# 5) Readiness checks
-docker compose exec audit-postgres pg_isready -U vds_audit -d vds_audit_checkpoints
-uv run vds-audit --json-only doctor credentials --require-state-dsn
-uv run vds-audit --json-only doctor correlation --since 30m --service "<SERVICE_NAME>" --audit-id "<THREAD_OR_REQUEST_ID>"
-uv run vds-audit state validate --state-dsn "$VDS_AUDIT_STATE_DSN"
-uv run vds-audit state index-health --state-dsn "$VDS_AUDIT_STATE_DSN" --index-type hnsw
-uv run vds-audit --json-only state doctor --state-dsn "$VDS_AUDIT_STATE_DSN"
-# 6) E2E flow (state-first reuse default)
-# Note: materials inspection is top-level `vds-audit list-materials`, not `vds-audit state list-materials`.
-uv run vds-audit --json-only state readiness --project "<PROJECT_STORAGE_KEY>" --repo "<REPO_STORAGE_KEY_OR_SLUG>" --state-dsn "$VDS_AUDIT_STATE_DSN" | jq '{ready, docs_chunk_ready, code_chunk_ready}'
-uv run vds-audit --json-only list-materials --state-dsn "$VDS_AUDIT_STATE_DSN" | jq '.projects[] | select(.project_storage_key=="<PROJECT_STORAGE_KEY>") | {project_storage_key, materialized_content_root, corpus_path, tables_path, mentions_path, link_graph_path, linked_page_resolution, retrieval_snapshot}'
-# 6.1) Refresh only when readiness is false, state paths are missing, or source inputs changed
-# Primary prepare flow (recommended)
-uv run vds-audit prepare --project "<PROJECT_STORAGE_KEY>" --registry-page "<REGISTRY_PAGE_URL_OR_ID>" --state-dsn "$VDS_AUDIT_STATE_DSN"
-# Optional explicit producer breakdown (equivalent refresh path)
-uv run vds-audit parse-registry --registry-page "<REGISTRY_PAGE_URL_OR_ID>" --state-dsn "$VDS_AUDIT_STATE_DSN"
-uv run vds-audit sync repos --bitbucket-project "<BITBUCKET_PROJECT_KEY>" --project-storage-key "<PROJECT_STORAGE_KEY>" --state-dsn "$VDS_AUDIT_STATE_DSN"
-uv run vds-audit extract-docs --registry-page "<REGISTRY_PAGE_URL_OR_ID>" --project-storage-key "<PROJECT_STORAGE_KEY>" --output-dir "<OUTPUT_DIR>" --state-dsn "$VDS_AUDIT_STATE_DSN"
-uv run vds-audit --json-only state readiness --project "<PROJECT_STORAGE_KEY>" --repo "<REPO_STORAGE_KEY_OR_SLUG>" --state-dsn "$VDS_AUDIT_STATE_DSN" | jq '{ready, docs_chunk_ready, code_chunk_ready}'
-uv run vds-audit workflow "<LOCAL_REPO_PATH>" --thread-id "phase47-$(date +%Y%m%d-%H%M%S)" --canonical-checklist --state-dsn "$VDS_AUDIT_STATE_DSN"
-```
-`--output-dir` controls extraction artifacts for local inspection/export only. Runtime `workflow` and `analyze` always load evidence from Postgres retrieval chunks.
-### Phase 93 Runtime Behavior
-- **Postgres-only runtime evidence**: Evidence loader queries Postgres directly; no disk fallback path. `corpus.jsonl` is a diagnostic export artifact only.
-- **Advisory lock auto-break**: Preparation advisory locks that are stale for >10 minutes are automatically detected and broken. Use `vds-audit doctor locks [--json]` to inspect active locks.
-- **`--registry-mode` removed**: Dead code; `checklist-first` is hardcoded.
-- **extract-docs flag reduction**: 46→15 visible flags (advanced flags available via `--help-all`).
-- **Bitbucket auto-disable**: When Bitbucket credentials are missing, warns and auto-disables instead of failing.
-- **`--skip-readiness-check`**: Debug-only workflow flag to skip project state readiness validation.
-- **Env overrides**: `VDS_AUDIT_SYNC_WORKSPACE` (sync repos workspace), `VDS_AUDIT_EXTRACT_OUTPUT_DIR` (extract-docs output dir).
-- **`corpus_documents` table**: Now includes `page_title` and `space_key` columns for direct metadata queries.
----
-## Configuration
-### Environment Variables
-The Audit Orchestrator uses environment variables for external service credentials:
-```bash
-# Bitbucket
-export BITBUCKET_TOKEN="your_bitbucket_app_token"
-export BITBUCKET_BASE_URL="https://bitbucket.example.com"
-# Confluence
-export CONFLUENCE_TOKEN="your_confluence_token"
-export CONFLUENCE_BASE_URL="https://confluence.example.com"
-# SonarQube
-export SONARQUBE_TOKEN="your_sonarqube_token"
-export SONARQUBE_BASE_URL="https://sonarqube.example.com"
-# Google Sheets (optional)
-export GOOGLE_SHEETS_CREDENTIALS_PATH="/path/to/service-account.json"
-# or
-export GOOGLE_SHEETS_OAUTH_CREDENTIALS_PATH="/path/to/oauth-credentials.json"
-export GOOGLE_SHEETS_API_KEY="your_api_key"
-```
-Recommended VDS layout:
-- Put sensitive values in `~/.vds/.env` (API keys, tokens, credentials) or the path referenced by `VDS_ENV_FILE`.
-- Keep non-sensitive extraction tuning in `~/.vds/config/extract-docs.toml` or the equivalent path under `VDS_CONFIG_DIR`.
-- Keep runtime profile/config values in `~/.vds/audit.yaml` and `~/.vds/audit.profiles.yaml` under the active VDS home layout.
-- `vds-cli` shared env loading resolves `VDS_ENV_FILE` when set, otherwise `<config-root>/.env` with `~/.vds/.env` as the active Unix-like default; maintained automation does not rely on repo-local `.env` fallback.
-- Examples of sensitive values to keep in `~/.vds/.env`: `ALIBABA_API_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `SONARQUBE_TOKEN`, `VDS_AUDIT_STATE_DSN`, `VDS_AUDIT_LANGGRAPH__POSTGRES_DSN`.
-- Alibaba DashScope runtime profiles use the same env-only secret pattern: `alibaba-openai` and `alibaba-anthropic` should reference `${ALIBABA_API_KEY}` from `~/.vds/audit.profiles.yaml`.
-#### Runtime Backend Policy Profiles (TSK-610.13)
-Runtime provider profiles in `~/.vds/audit.profiles.yaml` can now declare a minimal row-evaluation backend policy contract.
-```yaml
-default_profile: safe-default
-profiles:
-  safe-default:
-    env:
-      VDS_AUDIT_LLM_PROVIDER: openai
-    backend_policy:
-      backend: prompt_evaluator   # allowed: prompt_evaluator | dspy
-      locked: true             # deny runtime override requests
-      allow_override: false    # when true, accepts override request env
-```
-Override procedure:
-- Request override by setting `VDS_AUDIT_LLM__ROW_EVALUATION_BACKEND_OVERRIDE` before running CLI.
-- Override is applied only when profile policy has `allow_override: true` and `locked: false`.
-- If policy is locked, CLI fails fast with a validation error.
-Current scope:
-- Runtime backend choices are hard-cut to `prompt_evaluator` and `dspy`.
-- Unknown/removed backends fail fast at profile validation.
-### Configuration Files
-#### Project Profile (Optional)
-Create an `audit_profile.yaml` in your repository root for profile-specific settings:
-```yaml
-# audit_profile.yaml
-name: "My Service Profile"
-domain: "finance"
-business_criticality: "high"
-data_classification: "confidential"
-exposure: "external"
-# Optional: Custom weight multipliers
-weight_multipliers:
-  security: 1.3
-  compliance: 1.2
-# Optional: Section rules
-section_rules:
-  exclude:
-    - "mobile_security"
-  include:
-    - "pci_compliance"
-```
-#### Template Mapping (For Google Sheets)
-Create a JSON mapping file when using rubric-style Google Sheets:
-```json
-{
-  "sheets": {
-    "Checklist": {
-      "columns": {
-        "rule": "Rule",
-        "group": "Main criteria",
-        "check": "Sub-criteria",
-        "weight": "Weight",
-        "notes": "Technical notes"
-      }
-    }
-  }
-}
-```
-### Global CLI Options
-| Option | Default | Description |
-|--------|---------|-------------|
-| `--report-dir` | `vds-scripts/reports/audit_runs/` | Report output directory |
-| `--reports/--no-reports` | `--reports` | Enable/disable report file generation |
-| `--markdown/--no-markdown` | `--markdown` | Enable/disable Markdown summaries |
-| `--sarif/--no-sarif` | `--no-sarif` | Enable/disable SARIF output |
-| `--json-only` | `false` | Emit JSON to stdout only |
-| `--structured-logs` | `false` | JSON logs to stderr |
----
-## Ollama Embeddings Setup
-For Phase 43 retrieval (`lexical|vector|hybrid`), configure local Ollama embeddings using:
-- [OLLAMA_EMBEDDINGS_SETUP.md](OLLAMA_EMBEDDINGS_SETUP.md)
-This setup includes:
-1. Service/model bootstrap (`ollama serve`, `ollama pull bge-m3`, fallback `ollama pull nomic-embed-text`)
-2. Embedding endpoint smoke tests (`/api/embed`, `/v1/embeddings`)
-3. `~/.vds/.env` + `~/.vds/config/extract-docs.toml` wiring rules
-| `--verbose, -v` | `false` | Enable verbose output |
----
-## Running Audits
-### Basic Audit Command
-```bash
-uv run vds-audit audit /path/to/repos \
-  --template template.xlsx \
-  --output audit_report.xlsx
-```
-### Using Google Sheets Template
-```bash
-uv run vds-audit audit /path/to/repos \
-  --template-url "https://docs.google.com/spreadsheets/d/..." \
-  --template-sheet "Checklist" \
-  --output audit_report.xlsx
-```
-### Command Options
-| Option | Description |
-|--------|-------------|
-| `--template, -t` | Path to Excel template file |
-| `--template-url, -g` | Google Sheets URL |
-| `--template-sheet` | Sheet name (for Google Sheets) |
-| `--template-gid` | Sheet GID (for Google Sheets) |
-| `--template-table-index` | Table index for Google Docs templates (0-based) |
-| `--template-map` | JSON mapping file for rubric templates |
-| `--profile` | Explicit project profile file |
-| `--profile-map` | Profile map rules file |
-| `--adaptive-weights/--no-adaptive-weights` | Enable/disable adaptive weighting |
-| `--section-packs/--no-section-packs` | Enable/disable section packs |
-| `--section-pack` | Section pack names to apply (repeatable) |
-| `--baseline` | Baseline JSON report for trend indicators |
-| `--resume` | Resume from checkpoint file or directory |
-| `--checkpoint` | Enable checkpointing to specified file/dir |
-| `--gap-analysis/--no-gap-analysis` | Include evidence gap analysis in reports |
-| `--gap-llm/--no-gap-llm` | Enable/disable LLM usage for gap analysis |
-| `--gap-llm-model` | Override LLM model name for gap analysis |
-| `--gs-auth-method` | Google Sheets auth method |
-| `--gs-credentials-path` | Google Sheets service account credentials path |
-| `--gs-oauth-credentials-path` | Google Sheets OAuth credentials path |
-| `--gs-api-key` | Google Sheets API key |
-| `--concurrency, -c` | Concurrent checks per repo (default: 5) |
-| `--output, -o` | Output report path |
-| `--dry-run` | Preview without executing checks |
-### Example Audits
-#### Single Repository
-```bash
-uv run vds-audit audit /path/to/my-service \
-  --template base_audit.xlsx \
-  --output my_service_audit.xlsx
-```
-#### Multiple Repositories
-```bash
-uv run vds-audit audit /path/to/all-services \
-  --template base_audit.xlsx \
-  --concurrency 10 \
-  --output all_services_audit.xlsx
-```
-#### With Profile and Adaptive Weights
-```bash
-uv run vds-audit audit /path/to/repos \
-  --template base_audit.xlsx \
-  --profile production_profile.yaml \
-  --adaptive-weights
-```
-#### With Gap Analysis
-```bash
-uv run vds-audit audit /path/to/repos \
-  --template base_audit.xlsx \
-  --gap-analysis \
-  --gap-llm-model "claude-sonnet-4-20250514"
-```
-#### Google Sheets with Mapping
-```bash
-uv run vds-audit audit /path/to/repos \
-  --template-url "https://docs.google.com/spreadsheets/d/..." \
-  --template-sheet "Checklist" \
-  --template-map rubric_mapping.json \
-  --gs-auth-method "service_account" \
-  --gs-credentials-path "/path/to/credentials.json"
-```
----
-## Template & Gap Utilities
-### Analyze Template (LLM)
-```bash
-uv run vds-audit analyze-template \
-  --template-url "https://docs.google.com/spreadsheets/d/..." \
-  --template-sheet "Checklist" \
-  --output template_analysis.json
-```
-### Analyze Gaps (Standalone)
-```bash
-uv run vds-audit analyze-gaps /path/to/repo \
-  --template-analysis template_analysis.json \
-  --output gap_analysis.json
-```
-### Export Google Template to Excel
-```bash
-uv run vds-audit export-template \
-  --template-url "https://docs.google.com/spreadsheets/d/..." \
-  --output audit_template.xlsx
-```
----
-## Template Creation Guide
-### Excel Template Structure
-Standard templates require three sheets:
-#### 1. Metadata Sheet (Optional)
-| Key | Value |
-|-----|-------|
-| template_version | 1.0.0 |
-| owner | Your Team |
-| last_updated | 2025-01-31 |
-| target_project_types | microservice,library |
-#### 2. Sections Sheet
-| Column | Required | Description |
-|--------|----------|-------------|
-| id | Yes | Unique section identifier |
-| name | Yes | Human-readable name |
-| description | No | Section description |
-| weight | Yes | Weight (0-100, sum must equal 100) |
-| scoring_policy | No | weighted_mean, maturity, compliance_gate |
-| target_score | No | Maturity target (0-100) |
-| score_cap | No | Max score when critical checks fail |
-| confidence_mode | No | coverage, confidence, or both |
-| tags | No | Section tags (comma-separated) |
-**Example:**
-| id | name | weight | scoring_policy | tags |
-|----|------|--------|----------------|------|
-| security | Security Controls | 30 | weighted_mean | security |
-| documentation | Documentation | 20 | weighted_mean | governance |
-| quality | Code Quality | 25 | weighted_mean | quality |
-| testing | Test Coverage | 25 | weighted_mean | quality |
-#### 3. Checks Sheet
-| Column | Required | Description |
-|--------|----------|-------------|
-| id | Yes | Unique check identifier |
-| section_id | Yes | Parent section ID |
-| name | No | Check name (defaults to description) |
-| description | Yes | What the check validates |
-| max_points | Yes | Maximum points (default: 100) |
-| weight | No | Weight within section (uses severity fallback if omitted) |
-| check_type | Yes | Check plugin name |
-| check_config | No | JSON config for the check |
-| score_mode | No | binary, threshold, ratio, range, maturity |
-| severity | No | Critical, High, Medium, Low (default: Medium) |
-| priority | No | P1, P2, P3, P4 (default: P3) |
-| migration_effort | No | Low, Medium, High, Very High (default: Medium) |
-| required | No | Whether check is required (default: false) |
-| tags | No | Framework tags (comma-separated) |
-**Example:**
-| id | section_id | description | max_points | weight | check_type | check_config | severity |
-|----|------------|-------------|------------|--------|------------|--------------|----------|
-| SEC-001 | security | Branch protection enabled | 100 | 20 | bitbucket_branch_permission | {"branch": "main"} | High |
-| DOC-001 | documentation | README exists | 100 | | git_file_exists | {"file_path": "README.md"} | Medium |
-### Check Types Reference
-| Check Type | Category | Description | Config |
-|------------|----------|-------------|--------|
-| `git_file_exists` | git | Verifies file exists | `file_path` |
-| `git_file_content` | git | Validates file content | `file_path`, `pattern`, `expected_content` |
-| `bitbucket_branch_permission` | bitbucket | Validates branch protection | `branch`, `required_approvers` |
-| `bitbucket_merge_condition` | bitbucket | Validates PR merge conditions | `min_approvals`, `require_build_success` |
-| `confluence_page_exists` | confluence | Verifies documentation page | `page_title`, `space_key` |
-| `sonarqube_quality_gate` | sonarqube | Checks quality gate status | `gate_name`, `check_new_code` |
-### Template Validation
-Always validate templates before use:
-```bash
-uv run vds-audit validate-template --template template.xlsx
-```
----
-## Troubleshooting
-### Common Issues
-#### Issue: "Section weights must sum to 100.0"
-**Solution:** Ensure section weights in your template sum to exactly 100.0.
-```excel
-| Security | 30 |
-| Quality  | 25 |
-| Docs     | 20 |
-| Testing  | 25 |
-| TOTAL    | 100 |
-```
-#### Issue: "Check plugin 'xxx' not found"
-**Solution:** Verify the check type is registered:
-```bash
-uv run vds-audit list-checks --detailed
-```
-#### Issue: Google Sheets Authentication Failure
-**Solution:** Verify credentials and auth method:
-```bash
-# For service account
-export GOOGLE_SHEETS_CREDENTIALS_PATH="/path/to/service-account.json"
-uv run vds-audit audit ... --gs-auth-method "service_account"
-# For API key
-export GOOGLE_SHEETS_API_KEY="your_api_key"
-uv run vds-audit audit ... --gs-auth-method "api_key"
-# For OAuth
-export GOOGLE_SHEETS_OAUTH_CREDENTIALS_PATH="/path/to/oauth.json"
-uv run vds-audit audit ... --gs-auth-method "oauth"
-```
-#### Issue: "No git repositories found"
-**Solution:** Ensure the path contains git repositories:
-```bash
-# Single repo
-uv run vds-audit audit /path/to/my-service/..
-# Directory of repos (each with .git subdirectory)
-uv run vds-audit audit /path/to/all-services
-```
-#### Issue: Permission Denied Errors
-**Solution:** Check file/directory permissions and access tokens:
-```bash
-# Test repository access
-ls -la /path/to/repo
-# Verify API tokens
-echo $BITBUCKET_TOKEN
-echo $CONFLUENCE_TOKEN
-```
-### Debug Mode
-Enable verbose output for detailed debugging:
-```bash
-uv run vds-audit audit /path/to/repos \
-  --template template.xlsx \
-  --verbose \
-  --structured-logs
-```
-### Log Files
-Structured logs are written to stderr. For file logging, redirect stderr:
-```bash
-uv run vds-audit audit ... 2> audit.log
-```
----
-## CI/CD Integration
-### GitHub Actions Example
-```yaml
-name: Repository Audit
-on:
-  push:
-    branches: [main]
-  schedule:
-    - cron: '0 0 * * 0'  # Weekly
-jobs:
-  audit:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.14'
-      - name: Install uv
-        run: curl -LsSf https://astral.sh/uv/install.sh | sh
-      - name: Install Audit Orchestrator
-        run: |
-          cd audit_orchestrator
-          uv sync
-      - name: Run Audit
-        env:
-          BITBUCKET_TOKEN: ${{ secrets.BITBUCKET_TOKEN }}
-          CONFLUENCE_TOKEN: ${{ secrets.CONFLUENCE_TOKEN }}
-        run: |
-          cd audit_orchestrator
-          uv run vds-audit audit ../ \
-            --template templates/base_audit.xlsx \
-            --output reports/audit_$(date +%Y%m%d).xlsx \
-            --json-only
-      - name: Upload Report
-        uses: actions/upload-artifact@v4
-        with:
-          name: audit-report
-          path: audit_orchestrator/reports/*.xlsx
-```
-### Jenkins Pipeline Example
-```groovy
-pipeline {
-    agent any
-    environment {
-        BITBUCKET_TOKEN = credentials('bitbucket-token')
-        CONFLUENCE_TOKEN = credentials('confluence-token')
-    }
-    stages {
-        stage('Setup') {
-            steps {
-                sh 'curl -LsSf https://astral.sh/uv/install.sh | sh'
-                dir('audit_orchestrator') {
-                    sh 'uv sync'
-                }
-            }
-        }
-        stage('Audit') {
-            steps {
-                dir('audit_orchestrator') {
-                    sh '''
-                        uv run vds-audit audit ../ \
-                            --template templates/base_audit.xlsx \
-                            --output reports/audit_${BUILD_ID}.xlsx
-                    '''
-                }
-            }
-        }
-        stage('Archive') {
-            steps {
-                archiveArtifacts artifacts: 'audit_orchestrator/reports/*.xlsx'
-            }
-        }
-    }
-}
-```
-### GitLab CI Example
-```yaml
-audit:
-  image: python:3.14
-  script:
-    - pip install uv
-    - cd audit_orchestrator
-    - uv sync
-    - uv run vds-audit audit ../ \
-        --template templates/base_audit.xlsx \
-        --output reports/audit_${CI_PIPELINE_ID}.xlsx
-  artifacts:
-    paths:
-      - audit_orchestrator/reports/*.xlsx
-  only:
-    - main
-```
-### Exit Codes
-| Code | Meaning |
-|------|---------|
-| 0 | Success |
-| 1 | Error (check logs for details) |
-### JSON Output for CI/CD
-Use `--json-only` for machine-readable output:
-```bash
-uv run vds-audit audit /path/to/repos \
-  --template template.xlsx \
-  --json-only > audit_results.json
-# Check exit code
-if [ $? -eq 0 ]; then
-  echo "Audit passed"
-else
-  echo "Audit failed - check audit_results.json"
-fi
-```
----
-## Additional Resources
-- [API Documentation](API.md) - Developer API reference
-- [README.md](../README.md) - Project overview
-- [Requirements](../../.kiro/specs/audit-orchestrator/requirements.md) - Functional requirements
-- [Design](../../.kiro/specs/audit-orchestrator/design.md) - Architecture and design
----
-## Support
-For issues or questions:
-1. Check this guide's troubleshooting section
-2. Run with `--verbose` flag for detailed output
-3. Consult the requirements and design specifications