@ngocsangairvds/vsaf 3.2.14 → 3.2.16

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

@@ -1,1573 +0,0 @@
-# VDS Audit Orchestrator
-
-Automated repository auditing tool for the VDS monorepo with configurable templates, plugin-based checks, and comprehensive reporting.
-
-> **Architecture Note**: This is a **CLI-only tool** (Typer-based). It does NOT expose REST API endpoints. Testing is done via pytest (unit, integration, property-based tests), NOT Postman collections.
-
-## Quick Start
-
-```bash
-# Install dependencies
-cd audit_orchestrator
-uv sync --dev
-
-# Run an audit
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit audit /path/to/repos --template template.xlsx --output audit_report.xlsx
-
-# Validate a template
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit validate-template --template template.xlsx
-
-# Analyze a template (LLM-assisted)
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit analyze-template --template template.xlsx --output template_analysis.json
-
-# Analyze gaps for a repository
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit analyze-gaps /path/to/repo --template-analysis template_analysis.json \
-  --output gap_analysis.json
-
-# Export a Google template to Excel
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit export-template --template-url "https://docs.google.com/spreadsheets/d/..." \
-  --template-sheet "Checklist" --output audit_template.xlsx
-
-# List available checks
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit list-checks --detailed
-```
-
-## Features
-
-- **Plugin-Based Architecture** - Extensible check system with built-in integrations
-- **Excel & Google Sheets Templates** - Define audits in familiar spreadsheet formats
-- **Multiple Output Formats** - Excel reports, JSON, Markdown, and SARIF
-- **Async Processing** - Efficient handling of 200+ repositories
-- **Adaptive Weighting** - Intelligent scoring based on project profiles
-- **Section Scoring Policies** - Configurable aggregation (weighted mean, maturity, compliance gate)
-- **Comprehensive Reporting** - Detailed findings with evidence and recommendations
-- **Phase 20: Doc↔Code Traceability** - Dual evidence anchors for documentation and code
-- **Diagram Extraction** - Pure Python extractors for .drawio and .bmpr files
-- **Code Evidence Pack** - Bounded, LLM-ready code context from repositories
-- **Evidence Quality Gate** - Metrics and fail-fast for evidence readiness
-- **Phase 41: Agentic Investigation** - Tool-enabled code analysis with filesystem + LSP toolsets (`--agentic-mode off|auto|on`, default `auto`); tool-first step policy is one tool call per turn, bounded by `agentic.max_turns` and `agentic.max_tool_calls`
-- **Phase 115-120 Carry-Forward Slices** - Advisory search strategy, AST-grep tool support, cross-repo evidence context, project knowledge retrieval, expanded bilingual exemplar corpus, and direct backend checklist refresh/runtime guidance injection
-- **Phase 121: Workflow-Project Short-Circuit** - Re-run detection, force-rerun bypass, artifact regeneration, and resume interaction
-- **Phase 122: Instruction-Aware Evaluation** - Pre-evaluation requirement scope classification, manual check gating, cross-repo config awareness with `repo_role`, shared-resource indexing, instruction-aware evaluation with scoring rubric injection, and legacy cleanup
-
-## Current Baseline Snapshot
-
-- **Spec baseline**: `v21.0.0`
-- **Phase status**: Phase 171 merged — canonical latest-only baseline covering dispatch schema contract hardening (Phase 170), gradual dispatch ramp-up (Phase 171), and dispatch observability (Phase 169), all merged into mainline runtime.
-- **Test baseline**: `9402`
-- **Integration note**: Postgres-backed integration support remains available through the optional `test-integration` dependency extra, while bounded focused verification should prefer the Phase 170-171 schema-contract/gating/ramp-up and Phase 169 observability slices before broader live reruns.
-- **Alignment pack**: `./scripts/worktree_uv.sh run --project spec_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli spec validate-sync audit-orchestrator --agents-file AGENTS.md --agents-label "Audit orchestrator" --json-only` and `./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit --json-only validate-spec-sync --specs-dir .gpt-5.4/specs/audit-orchestrator --agents-file AGENTS.md`
-- **Phase 171 operator focus**: verify gradual ramp-up behavior (`--ramp-up-slots`, `--ramp-up-interval`, `submission_stagger_ms` 200ms default), Phase 170 schema compatibility (`doctor schema`, `dispatch_schema_gate()`, additive `claimed_at` repair), and Phase 169 dispatch observability (`heartbeat_at`, utilization persistence, progress summaries, dead-run detection).
-- **Phase boundary**: Phase 171 is additive on top of the merged Phase 170 baseline, which is additive on top of Phase 169 dispatch observability and Phase 168 atomic finalization.
-- **Targeted rerun note**: single-row `workflow` reruns use `--target <CHECK_ID_OR_ROW_SELECTOR>`; do not use unsupported legacy selectors such as `--check-ids` or `--targeted-rows`
-- **CL-005 quality note**: app-config-first datasource/schema/DB-instance rows must keep separation wording and must not treat config filenames such as `application.properties` as the hydrated repo identity.
-- **CL-006 quality note**: decisive production app-config proof must finalize as `PASS` with retained datasource plus pool-limit excerpts (`minimum-idle`, `maximum-pool-size`, `max-lifetime` or equivalent).
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Phase 42 Verification Gate](#phase-42-verification-gate)
-- [Usage](#usage)
-- [Templates](#templates)
-- [Output Formats](#output-formats)
-- [Contributing](#contributing)
-- [Documentation](#documentation)
-
----
-
-## Installation
-
-### Prerequisites
-
-- Python 3.14+
-- [uv](https://github.com/astral-sh/uv) package manager
-- VDS credentials (Bitbucket, Confluence, SonarQube as needed)
-- Embedding stack for Phase 43:
-  - Python package `pgvector>=0.4.2` (application dependency in this project)
-  - Postgres extension `vector` (pgvector) `>=0.8.1` in the target database
-
-### Setup
-
-```bash
-# Navigate to the audit orchestrator
-cd WHO-project/vds-scripts/audit_orchestrator
-
-# Create virtual environment and install dependencies
-uv sync --dev
-
-# Verify installation
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit --version
-
-# Optional: install real-Postgres integration test support for Phase 117/118
-./scripts/worktree_uv.sh sync --project audit_orchestrator --extra test-integration
-```
-
-### Targeted Workflow Rerun
-
-```bash
-./scripts/worktree_uv.sh run --project audit_orchestrator \
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit workflow <repo-cache-root>/PAR-project/merchant-report \
-  --profile zai-openai \
-  --project-storage-key 88727304 \
-  --thread-id phase124-cl002-par-mr-zai \
-  --canonical-checklist \
-  --target CL-002
-```
-
-Use the effective repo-cache root for your environment as resolved by the shared Phase 2 path/config model. Use `workflow-project` only for project-scope lanes.
-
-### Required Credentials (`VDS_ENV_FILE` or `<config-root>/.env`)
-
-Real CLI producer flows fail fast when required credentials are missing.
-
-```bash
-# 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).
-VDS_USERNAME=your_username
-VDS_PASSWORD=your_password
-
-# Confluence (primary: username/password above; tokens below are fallback only)
-INTERNAL_CONFLUENCE_TOKEN=...
-EXTERNAL_CONFLUENCE_TOKEN=...
-
-# Bitbucket (either username/password above, or token below)
-BITBUCKET_TOKEN=...
-
-# Centralized state DSN (preferred explicit key)
-VDS_AUDIT_STATE_DSN=postgresql://user:pass@host:5432/vds_audit
-
-# LangGraph checkpointer DSN
-VDS_AUDIT_LANGGRAPH__POSTGRES_DSN=postgresql://user:pass@host:5432/vds_audit
-
-# Optional for Phase 68c correlation doctor (Grafana/Elastic)
-VDS_GRAFANA_URL=http://10.207.58.64:8485/
-VDS_GRAFANA_TOKEN=...
-VDS_ELASTIC_KIBANA_URL=log.digital.vn
-VDS_ELASTIC_KIBANA_IP=10.207.56.26
-VDS_ELASTIC_USER=dev
-VDS_ELASTIC_PASSWORD=...
-```
-
-Credential preflight is enforced for:
-- `./scripts/worktree_uv.sh run --project vds_cli vds-cli audit parse-registry` (unless `--prefetch-dir` is used)
-- `./scripts/worktree_uv.sh run --project vds_cli vds-cli audit extract-docs` (when network-backed Confluence/Bitbucket access is required)
-- `./scripts/worktree_uv.sh run --project vds_cli vds-cli audit sync repos --bitbucket-project ...`
-
-Readiness check:
-
-```bash
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit --json-only doctor credentials --require-state-dsn
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit --json-only doctor correlation --log-file <log-root>/vds-audit-runtime-$(date +%Y%m%d).jsonl
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit --json-only doctor locks          # Inspect advisory locks (stale locks >10min auto-broken)
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit --json-only embedding-check --state-dsn "$VDS_AUDIT_STATE_DSN"
-```
-
-After this is configured, state-backed commands run without passing `--state-dsn` on every invocation.
-
-Optional Phase 117/118 storage verification commands:
-- `uv run python scripts/verify_phase117_cross_repo_evidence.py`
-- `uv run python scripts/verify_phase118_knowledge_agent.py`
-- `uv run pytest tests/integration/test_phase117_118_storage.py -q`
-
-The shared integration harness uses `testcontainers[postgres]` when available, skips cleanly when Docker or the optional dependency is unavailable, and can reuse an externally supplied `VDS_AUDIT_STATE_DSN`.
-
-Current implementation caveats I verified:
-- `workflow-project` multi-profile dispatch passes `--cross-repo-evidence` / `--knowledge-agent` flags through to child `workflow` runs and now also propagates a shared evidence context id via `--evidence-context-id`.
-- Canonical-checklist row execution now publishes qualifying discoveries into `audit_state.project_evidence_discoveries`; remaining verification work is end-to-end quality validation rather than missing runtime publish-path wiring.
-- Phase 118 TTL configuration accepts both the flat env aliases (`VDS_AUDIT_KNOWLEDGE_TTL_DAYS`, `VDS_AUDIT_KNOWLEDGE_CONFIDENCE_THRESHOLD`) and nested config/profile values.
-- Unified mode (`--row-unified-mode on`) keeps current Phase 115-120 runtime features enabled by default in canonical-checklist execution unless operators disable them explicitly.
-
-Deterministic runtime defaults:
-- `sync repos` workspace default: effective VDS cache root + `/repos` (override: `VDS_AUDIT_SYNC_WORKSPACE`)
-- `extract-docs` output dir default uses `--output-dir` (override: `VDS_AUDIT_EXTRACT_OUTPUT_DIR`)
-- shared Confluence material cache root: effective VDS cache root + `/confluence`
-- no runtime use of deprecated cache-material paths
-- config boundary for extraction: secrets in `VDS_ENV_FILE` or `<config-root>/.env`, non-sensitive tuning in `<config-root>/config/extract-docs.toml`
-- `extract-docs` exposes ≤15 visible flags; advanced flags are available via `--help-all`
-- `--skip-readiness-check` (debug-only): skip project state readiness validation before workflow execution
-- Runtime evidence resolution is Postgres-only (no disk fallback); `workflow` and `analyze` query Postgres chunks directly
-- Advisory locks on preparation steps auto-break after 10 minutes of staleness
-
-### Docker Build (repo root context)
-
-```bash
-cd /path/to/vds
-docker build -f WHO-project/vds-scripts/audit_orchestrator/Dockerfile \
-  -t vds-audit-orchestrator:local .
-```
-
-### Docker Compose Reset-First Runbook (P0: Shared Infrastructure)
-
-Use this exact order for a clean infra baseline with shared infrastructure.
-
-> **P0 Change**: Audit orchestrator now uses shared `vds-postgres` on port 5432 with `audit_state` schema.
-> The standalone `audit-postgres` container is retired.
-
-```bash
-cd /path/to/vds
-
-# 1) Start shared infrastructure first
-docker compose -f docker/docker-compose.infra.yml --profile infra up -d
-
-# 2) Wait for postgres to be healthy
-docker ps | grep vds-postgres
-
-# 3) Export DSNs for shared postgres with audit_state schema
-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"
-
-# 4) Verify schema exists (created by init-schemas.sql)
-docker exec vds-postgres psql -U postgres -d vds_platform -c "\dn"
-
-# 5) Initialize state schema if needed
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit state init --state-dsn "$VDS_AUDIT_STATE_DSN"
-
-# 6) Readiness checks
-docker compose -f docker/docker-compose.infra.yml exec postgres pg_isready -U postgres -d vds_platform
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit --json-only doctor credentials --require-state-dsn
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit --json-only state doctor --state-dsn "$VDS_AUDIT_STATE_DSN"
-
-# 7) E2E flow (prepare once -> analyze many)
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit prepare --project "<PROJECT_STORAGE_KEY>" --registry-page "<REGISTRY_PAGE_URL_OR_ID>" --state-dsn "$VDS_AUDIT_STATE_DSN"
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli 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}'
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit workflow "<LOCAL_REPO_PATH>" --thread-id "phase47-$(date +%Y%m%d-%H%M%S)" --canonical-checklist --state-dsn "$VDS_AUDIT_STATE_DSN"
-```
-
----
-
-## Phase 42 Verification Gate
-
-Phase 42 changes must pass the parse-seed centralized-state verification gate before merge/handoff.
-
-```bash
-cd WHO-project/vds-scripts/audit_orchestrator
-
-# Required gate (ruff + lsp + pyright + parse-seed tests + CLI help matrix)
-uv run python scripts/verify_phase_42.py --strict-help
-
-# Optional live matrix (prepare-once + parse seed + workflow)
-PHASE42_RUN_LIVE=1 \
-VDS_AUDIT_STATE_DSN="postgresql://..." \
-PHASE42_REGISTRY_PAGE="<REGISTRY_PAGE_URL_OR_ID>" \
-PHASE42_PROJECT="<PROJECT_STORAGE_KEY_OR_PAGE_ID_OR_NAME>" \
-PHASE42_REPO="<REPO_SELECTOR_KEY_OR_SLUG_OR_STORAGE_KEY_OR_URL>" \
-PHASE42_EVIDENCE_DIR="/tmp/phase42-evidence" \
-PHASE42_REPO_PATH="/path/to/repo" \
-PHASE42_THREAD_ID="phase42-live" \
-PHASE42_REPORT_DIR="/tmp/phase42-report" \
-# Optional: skip extract-docs refresh when reusing prepared centralized state snapshots
-# Only enable when BOTH checks pass:
-#   1) state readiness with --project + --repo returns ready=true, docs_chunk_ready=true, code_chunk_ready=true
-#   2) list-materials shows non-empty corpus_path/materialized_content_root for target project
-# PHASE42_SKIP_EXTRACT_DOCS_LIVE=1 \
-# Optional: speed up canonical workflow checks (defaults: mode=off, target=1)
-# PHASE42_CHECKLIST_ROW_LLM_MODE=off \
-# PHASE42_WORKFLOW_TARGET="1" \
-# Optional: bypass readiness gate in workflow steps (debug-only; default off)
-# PHASE42_SKIP_EVIDENCE_CHECK_LIVE=1 \
-# Optional: keep workflow-project check enabled (default); set to 1 to skip
-# PHASE42_SKIP_WORKFLOW_PROJECT_LIVE=1 \
-# Optional: custom workflow-project thread id
-# PHASE42_WORKFLOW_PROJECT_THREAD_ID="phase42-live-project" \
-# Optional: run workflow-resume correlation checks
-# PHASE42_RESUME_THREAD_ID="<EXISTING_WORKFLOW_THREAD_ID>" \
-# PHASE42_RESUME_APPROVE=1 \
-# PHASE42_RESUME_FEEDBACK="Phase42 verifier resume check" \
-# Optional: validate explain plan fields for state list queries when supported
-# PHASE42_CHECK_STATE_EXPLAIN_PLAN=1 \
-uv run python scripts/verify_phase_42.py --strict-help --live-matrix
-```
-
-The live matrix is expected to run in an environment with reachable Postgres,
-Confluence, and Bitbucket services.
-
----
-
-## Usage
-
-### Commands
-
-| Command | Description |
-|---------|-------------|
-| `audit` | Run audit against repositories |
-| `validate-template` | Validate template syntax and weights |
-| `analyze-template` | Extract evidence requirements from template criteria |
-| `analyze-gaps` | Collect evidence and evaluate gaps for a repository |
-| `export-template` | Export Google Sheet/Doc template to Excel |
-| `list-checks` | List available check types |
-| `status` | Check orchestrator status |
-| `extract-bitbucket-metadata` | Extract Bitbucket branch permissions and repository metadata |
-| `evidence-quality` | Check evidence readiness before audit |
-| `parse-registry` | Parse Confluence registry structure without downloading materials |
-| `extract-docs` | Pull project documentation/materials from Confluence and refresh Postgres retrieval snapshots |
-| `list-materials` | List extracted materials (optionally render a tree) |
-| `upload-results` | Publish audit results to Confluence (updates existing run page) |
-| `workflow` | Run LangGraph LLM workflow for a repository audit |
-| `workflow-resume` | Resume a paused LangGraph workflow |
-| `workflow-pending` | List workflows pending human review |
-| `workflow-export` | Export workflow visualization (mmd/png/svg) |
-| `doctor correlation` | Generate deterministic runtime/Grafana/Elastic correlation commands |
-| `embedding-check` | Validate Ollama model + embedding dimensions + pgvector readiness |
-| `state resolve-run-input` | Resolve canonical run input payload from centralized state |
-| `state readiness` | Check centralized state readiness for workflow/analyze inputs |
-| `state list-links` | List centralized-state lineage links between runs/artifacts |
-
-### Phase 68c Correlation Doctor
-
-Use `doctor correlation` to generate deterministic correlation commands for one audit run.
-It validates shared env-file keys loaded from `VDS_ENV_FILE` or `<config-root>/.env` for Grafana/Elastic and can optionally execute health checks.
-
-```bash
-# Generate correlation command templates only (runtime log + Grafana + Elastic)
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit --json-only doctor correlation \
-  --since 30m \
-  --service "<SERVICE_NAME>" \
-  --audit-id "<THREAD_OR_REQUEST_ID>" \
-  --log-file <log-root>/vds-audit-runtime-$(date +%Y%m%d).jsonl
-
-# Execute external readiness probes (no fallback logic)
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit --json-only doctor correlation \
-  --since 30m \
-  --service "<SERVICE_NAME>" \
-  --audit-id "<THREAD_OR_REQUEST_ID>" \
-  --run-health
-```
-
-The command returns:
-- runtime log capture command (`doctor logs-follow --no-follow`)
-- Grafana correlation query command (`./scripts/worktree_uv.sh run --project vds_cli vds-cli grafana --json-only search`)
-- Elastic/Kibana correlation query command (`./scripts/worktree_uv.sh run --project vds_cli vds-cli elastic --json-only search`)
-- optional health check payloads from `./scripts/worktree_uv.sh run --project vds_cli vds-cli grafana health` and `./scripts/worktree_uv.sh run --project vds_cli vds-cli elastic ping`
-
-### Audit Command
-
-```bash
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit audit [OPTIONS] REPO_PATH
-
-# Options:
-#   --template, -t PATH              Excel template file
-#   --template-url, -g URL           Google Sheets/Docs URL
-#   --template-sheet NAME            Sheet name for Google Sheets
-#   --template-gid GID               Sheet GID for Google Sheets
-#   --template-table-index INT       Google Docs table index (0-based)
-#   --template-map PATH              JSON mapping file for rubric templates
-#   --gs-auth-method TEXT            Google Sheets auth method
-#   --gs-credentials-path PATH       Google Sheets service account credentials path
-#   --gs-oauth-credentials-path PATH Google Sheets OAuth credentials path
-#   --gs-api-key TEXT                Google Sheets API key
-#   --project-profile PATH           Project profile file
-#   --profile-map PATH               Profile map rules file
-#   --output, -o PATH                Output report path
-#   --concurrency, -c INT            Check concurrency (default: 5)
-#   --dry-run                        Preview without executing
-#   --verbose, -v                    Verbose output
-#   --trace                          Enable full log output (disable truncation)
-#   --show-reasoning                 Show LLM reasoning chains in output
-```
-
-### Examples
-
-#### Basic Audit
-
-```bash
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit audit /path/to/my-service \
-  --template base_audit.xlsx \
-  --output my_audit.xlsx
-```
-
-#### Google Sheets Template
-
-```bash
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit audit /path/to/repos \
-  --template-url "https://docs.google.com/spreadsheets/d/..." \
-  --template-sheet "Checklist"
-```
-
-#### Google Docs Template (first table)
-
-```bash
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit audit /path/to/repos \
-  --template-url "https://docs.google.com/document/d/..."
-```
-
-#### Google Docs Template (specific table)
-
-```bash
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit audit /path/to/repos \
-  --template-url "https://docs.google.com/document/d/..." \
-  --template-table-index 1
-```
-
-#### Dry Run Preview
-
-```bash
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit audit /path/to/repos \
-  --template base_audit.xlsx \
-  --dry-run
-```
-
-#### JSON Output
-
-```bash
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit audit /path/to/repos \
-  --template base_audit.xlsx \
-  --json-only > results.json
-```
-
-### LangGraph Workflow (LLM)
-
-Use the LangGraph workflow when you need LLM-based analysis with evidence gating,
-batch control, and groundedness validation.
-
-```bash
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit workflow /path/to/repo \
-  --thread-id audit-001 \
-  --checklist-page-id 88722450 \
-  --checklist-row-llm-mode selective
-```
-
-#### Workflow Performance & Accuracy Options
-
-LLM analysis can be slow on large inputs. Use the options below to control latency
-and ensure evidence-backed outputs:
-
-```bash
-# Batch + timeout controls
---batch-size 5
---row-timeout-ms 45000
---batch-timeout-ms 120000
---row-timeout-progress-extension
---row-timeout-progress-retry-attempts 1
---row-timeout-progress-extension-ms 30000
---row-timeout-progress-max-ms 120000
---resume
---checkpoint-dir /path/to/checkpoints
-
-# Evidence readiness gate (recommended)
---skip-evidence-check            # debug-only bypass (default: false)
---min-docs 5
---min-code-files 3
---evidence-project "INSURANCE"
---max-evidence-chars 8000
-
-# Grounding validation (accuracy)
---strict-grounding
-
-# Debug artifacts
---debug-evidence-context
---debug-batch-timing
-```
-
-#### DSPy Optional Backend (Phase 40)
-
-Use DSPy backend as an opt-in runtime path. If DSPy or optimizer stack is not installed/configured,
-the evaluator falls back to the baseline tool-first path with structured fallback logs.
-
-```bash
-# Runtime toggle (safe fallback enabled by default behavior)
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit workflow /path/to/repo \
-  --thread-id audit-001 \
-  --canonical-checklist \
-  --target 1 \
-  --use-dspy
-
-# Build deterministic gold dataset from historical audit-checklist outputs
-uv run python scripts/build_gold_dataset.py \
-  --search-root reports \
-  --output reports/dspy_gold_dataset.json \
-  --quality-output reports/dspy_gold_dataset.quality.json
-
-# Compile optimizer artifact + metadata (real DSPy MIPROv2 when available)
-uv run python scripts/optimize_audit.py \
-  --dataset reports/dspy_gold_dataset.json \
-  --output-dir reports/dspy_compiled
-
-# Enforce real DSPy optimization (fail if fallback would be used)
-uv run python scripts/optimize_audit.py \
-  --dataset reports/dspy_gold_dataset.json \
-  --output-dir reports/dspy_compiled \
-  --require-dspy
-
-# Benchmark manual vs DSPy path on held-out set (runtime RowEvaluator A/B)
-uv run python scripts/benchmark_dspy.py \
-  --dataset reports/dspy_gold_dataset.json \
-  --compiled-artifact reports/dspy_compiled/audit_judge_optimized.json \
-  --output-dir reports/dspy_benchmark \
-  --benchmark-mode row_evaluator_ab \
-  --llm-mode per-row \
-  --max-rows 25 \
-  --stability-runs 2
-
-# Benchmark retrieval quality/latency/stability (lexical vs hybrid) from local run inputs
-uv run python scripts/benchmark_retrieval_modes.py \
-  --lexical-input reports/retrieval_benchmark/lexical_metrics.json \
-  --hybrid-input reports/retrieval_benchmark/hybrid_metrics.json \
-  --output-dir reports/retrieval_benchmark
-
-# Publish cross-gate matrix (baseline/dspy x lexical/hybrid) from local run inputs
-uv run python scripts/generate_cross_gate_matrix.py \
-  --legacy-lexical reports/cross_gate_inputs/legacy_lexical.json \
-  --legacy-hybrid reports/cross_gate_inputs/legacy_hybrid.json \
-  --dspy-lexical reports/cross_gate_inputs/dspy_lexical.json \
-  --dspy-hybrid reports/cross_gate_inputs/dspy_hybrid.json \
-  --output-dir reports/cross_gate_matrix
-```
-
-Outputs:
-- `reports/dspy_compiled/audit_judge_optimized.json`
-- `reports/dspy_compiled/audit_judge_optimized.meta.json`
-- `reports/dspy_benchmark/manual_vs_dspy_metrics.json`
-- `reports/dspy_benchmark/confusion_matrix.json`
-- `reports/dspy_benchmark/sampled_vn_quality_review.json`
-- `reports/retrieval_benchmark/retrieval_mode_benchmark.json`
-- `reports/cross_gate_matrix/cross_gate_backend_retrieval_matrix.json`
-- `reports/cross_gate_matrix/cross_gate_backend_retrieval_matrix.md`
-
-Troubleshooting:
-- Missing DSPy stack: install optional extra `uv sync --extra dspy-optimizer`.
-- Runtime still succeeds without optional extra; check logs for `row_evaluation_backend_fallback`.
-- Runtime benchmark fallback observability is exported in `manual_vs_dspy_metrics.json`:
-  - `benchmark_mode`
-  - `quality_metrics` (`guidance_adherence`, `anchor_grounding_quality`, `stability`)
-  - `fallback_reason_counts`
-- Guidance-heavy row verification uses `sampled_vn_quality_review.json` (`manual_reason`/`dspy_reason` grouped by `row_id`).
-- For real end-to-end verification path, use:
-  `uv run python scripts/verify_phase_40_dspy.py <repo_path> --evidence-dir <dir>`.
-  `uv run python scripts/verify_phase_43.py --guidance-review reports/dspy_benchmark/sampled_vn_quality_review.json --min-guidance-rows 3`.
-
-### Evidence Materials & Results Publishing
-
-#### Extract Confluence Materials
-
-Phase 36 hard cutover uses bulk crawl-tree extraction only.
-Phase 47/48/49 runtime contract is state-first, Postgres-only for retrieval, and in-process SDK-only for data-source clients:
-- `extract-docs --execute` refreshes retrieval snapshots after corpus extraction by default.
-- `extract-docs --json-only` now includes `performance` timing metrics (`total_duration_ms`, `project_processing_duration_ms`, `retrieval_refresh_duration_ms`) for deterministic NFR-Y7 verification.
-- `workflow --retrieval-mode lexical|vector|hybrid` reads retrieval evidence from Postgres state only (no filesystem fallback path).
-- runtime evidence resolution uses centralized state artifact paths only (`corpus_path`, `materialized_content_root`, `tables_path`, `mentions_path`, `link_graph_path`).
-- `vector`/`hybrid` fail fast when retrieval snapshot readiness is missing; run `extract-docs` for the target project scope to refresh.
-- Canonical checklist workflows (`--canonical-checklist`) validate centralized state readiness even when using `--seed-payload`; the CLI fails fast instead of attempting filesystem evidence ingestion.
-- `prepare` is the primary operator command and orchestrates `parse-registry -> sync repos -> extract-docs` with deterministic defaults.
-
-```bash
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit extract-docs \
-  --registry-page "<CONFLUENCE_REGISTRY_PAGE_URL_OR_ID>" \
-  --recursive-depth 2 \
-  --parse-concurrency 2 \
-  --include-attachments
-```
-
-- `--output-dir` is for producer artifact inspection only; runtime `workflow`/`analyze` load evidence from Postgres state, not local files.
-- Use `--project-page` to extract a single project page instead of a registry.
-- `--min-chars` controls the minimum converted characters before marking a doc as partial.
-- `--parse-concurrency` controls concurrent project-page parsing during registry traversal (lower this to `1-2` when Confluence is slow/throttled).
-- Bulk mode (Phase 18 hardening): a single `vds-cli confluence crawl-tree` call per project, plus optional LLM-ready outputs.
-
-```bash
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit extract-docs \
-  --project-page "http://10.254.136.35:8090/display/TDOV/13.02.10.+BRD" \
-  --confluence-server external \
-  --project-storage-key insurance-core \
-  --recursive-depth 1 \
-  --parse-concurrency 2 \
-  --include-attachments \
-  --no-include-bitbucket \
-  --body-format view \
-  --chunk-max-chars 4000 \
-  --emit-link-graph \
-  --emit-tables \
-  --emit-mentions \
-  --markitdown-external
-```
-
-- `--emit-*` outputs are supported with extract-docs bulk crawl execution (the only supported crawl mode).
-- `--body-format` controls which Confluence representation is stored/analyzed (`view|export_view|storage`). `--chunk-max-chars` bounds corpus chunks for LLM context windows.
-- Cache policy is fixed to read-write in the clean-break runtime.
-- `--content-root` overrides the materialized Confluence content destination (default remains under the selected `--output-dir`).
-- `--project-storage-key` filters extraction to discovered projects whose canonical storage key matches the provided key.
-- `--markitdown-external` enables an isolated Python 3.13 runner for MarkItDown to convert Office/PDF attachments while the main project remains on Python 3.14.
-- Bulk mode writes `crawl_manifest.json` under each project directory and records `corpus_path` / `link_graph_path` / `tables_path` / `mentions_path` in the per-project `manifest.json` under `crawl.*`.
-- For Confluence-only LLM evidence collection, use `--no-include-bitbucket` to skip README metadata fetches and avoid Bitbucket latency.
-- When Bitbucket metadata is required, tune reliability/latency with `--bitbucket-timeout`, `--bitbucket-retries`, and optionally `--no-bitbucket-include-last-commit`.
-- Defaults are now optimized for non-blocking runs: `--bitbucket-timeout 10`, `--bitbucket-retries 2`.
-- For cached repos, commit/default-branch probe failures now reuse cache tokens instead of forcing README redownload.
-- Bitbucket link processing is deduplicated per project run by canonical `project:repo` identity (duplicate and alias URLs are ignored), and shared-cache materialization runs once per project key to avoid repeated local copy/download checks.
-- Repo code-chunk refresh deduplicates targets by resolved local repo path, and discovered repo `head_commit_sha` values are persisted before long snapshot refresh so subsequent runs can reuse incremental diff baselines.
-
-#### Recommended Confluence Prep Modes For LLM (Postgres-First Runtime)
-
-Use this order for stable, machine-readable materials preparation:
-
-1. **Primary (recommended)**: `extract-docs --body-format view --emit-link-graph --emit-tables --emit-mentions`
-2. **Fallback A (rendering variant)**: rerun with `--body-format export_view` if `view` output is unexpectedly sparse for macro-heavy pages.
-3. **Fallback B (human-readable only)**: `vds-cli confluence export page --page-id <id>` (PDF) for manual review or emergency capture.
-
-Why this order:
-- `crawl-tree` artifacts preserve structure and metadata (`page_id`, `parent_id`, `depth`, `links`, table rows) required for deterministic LLM grounding.
-- PDF export is useful for readability but flattens structure and can reduce parsing reliability for automated link/table extraction.
-
-Quick validation checklist after extraction (state-first):
-
-```bash
-uv run --json-only ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit state readiness \
-  --project "<PROJECT_STORAGE_KEY_OR_PAGE_ID_OR_NAME>" \
-  --repo "<REPO_STORAGE_KEY_OR_SLUG>" \
-  --state-dsn "$VDS_AUDIT_STATE_DSN" | jq '{ready, docs_chunk_ready, code_chunk_ready}'
-
-uv run --json-only ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit 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}'
-```
-
-Phase 92 performance gate (NFR-Y7) can be verified from three extract-docs JSON runs:
-
-```bash
-uv run python scripts/verify_phase_92_performance.py \
-  --full-run-json "<full-run.json>" \
-  --no-change-json "<no-change.json>" \
-  --changed-only-json "<changed-only.json>"
-```
-
-- Gate metrics: no-change threshold uses `performance.total_duration_ms`; changed/full ratio uses `performance.retrieval_refresh_duration_ms` (falls back to total duration when refresh timing is absent).
-
-- If `state readiness` shows `docs_chunk_ready=false` or `list-materials` shows empty `corpus_path`, rerun `extract-docs` with `--body-format view` (or `export_view`) before LLM analysis.
-
-Quick benchmark + output verification (real artifacts):
-
-```bash
-# Parse diagnostics (live vs prefetch)
-jq '.diagnostics | {parse_duration_ms,network_fetches,prefetch_hits,prefetch_misses,fallback_fetches,step_timings_ms}' /tmp/vds_phase32_parse_live.json
-jq '.diagnostics | {parse_duration_ms,network_fetches,prefetch_hits,prefetch_misses,fallback_fetches,step_timings_ms}' /tmp/vds_phase32_parse_prefetch.json
-
-# Extraction quality signals (per-project manifest)
-jq '.crawl | {image_extraction,image_extraction_strategy,image_extraction_warnings}' /tmp/vds_phase32_extract_det_i/projects/*/manifest.json
-jq '.crawl | {image_extraction,image_extraction_strategy,image_extraction_warnings}' /tmp/vds_phase32_extract_hybrid_i/projects/*/manifest.json
-jq '.crawl | {image_extraction,image_extraction_strategy,image_extraction_warnings}' /tmp/vds_phase32_extract_llm_i/projects/*/manifest.json
-
-# Consolidated benchmark summary written by phase verification run
-cat /tmp/vds_phase32_benchmark_summary.json
-```
-
-#### Parse Registry Only (No Download)
-
-Use this to validate registry parsing behavior before full extraction:
-
-```bash
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit parse-registry \
-  --registry-page "http://confluence.digital.vn/pages/viewpage.action?pageId=88716667" \
-  --recursive-depth 1 \
-  --parse-concurrency 2 \
-  --timeout 120 \
-  --retries 1 \
-  --exclude-empty-projects
-```
-
-- `--exclude-empty-projects` removes nodes that have no discovered document/confluence/bitbucket links.
-- `--timeout` and `--retries` tune resilience for slow Confluence endpoints.
-- For large registries, keep depth at `1` unless nested project containers are required.
-
-#### Phase 24: Deterministic Registry Parsing (Recommended)
-
-`parse-registry` uses deterministic checklist-first parsing by default and extracts the checklist seed page plus project link inventory in one run:
-
-```bash
-# Checklist-first mode with budget controls
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit parse-registry \
-  --registry-page "http://confluence.digital.vn/pages/viewpage.action?pageId=88716667" \
-  --adaptive-depth \
-  --adaptive-max-depth 2 \
-  --max-projects 20 \
-  --step-timeout 30 \
-  --parse-concurrency 1 \
-  --timeout 120
-```
-
-**Phase 24 Registry Options:**
-| Option | Description |
-|--------|-------------|
-| `--checklist-page` | Explicit checklist page ID or URL override (bypasses auto-detection) |
-| `--max-projects` | Budget limit for number of projects to parse |
-| `--step-timeout` | Per-step timeout (seconds) for individual page parsing |
-| `--prefetch-dir` | Directory containing crawl-tree artifacts to use instead of network calls |
-| `--adaptive-depth/--no-adaptive-depth` | Enable adaptive deepening in checklist-first mode (default: enabled) |
-| `--adaptive-max-depth` | Maximum depth adaptive deepening can reach (default: `2`) |
-
-**Phase 26 Diagnostics (in `registry.diagnostics` JSON):**
-- `prefetch_hits`, `prefetch_misses`, `prefetch_pages_indexed`: prefetch artifact coverage.
-- `network_fetches`, `fallback_fetches`: network call and fallback pressure.
-- `step_timings_ms`: per-step parser latency breakdown.
-- `retry_count`, `rate_limit_events`, `retry_after_seconds`: retry and 429/Retry-After visibility.
-- `adaptive_depth_applied`, `adaptive_depth_from`, `adaptive_depth_to`, `adaptive_trigger_reason`: adaptive pass behavior.
-- `adaptive_candidate_count`, `adaptive_no_links_count`: trigger evidence counters from pass-1.
-
-#### Using Prefetch for Faster Parsing
-
-For large registries, use a two-step prefetch strategy to minimize network calls:
-
-```bash
-# Step 1: Prefetch registry tree with crawl-tree (single network call)
-REGISTRY_PAGE="<REGISTRY_PAGE_URL_OR_ID>"
-uv run --project ../vds_cli vds-cli confluence -- --json-only crawl-tree "${REGISTRY_PAGE}" \
-  --out /tmp/vds_registry_prefetch \
-  --depth 2 \
-  --no-include-attachments \
-  --body-format storage
-
-# Step 2: Parse from local artifacts (no network calls)
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit parse-registry \
-  --registry-page "${REGISTRY_PAGE}" \
-  --adaptive-depth \
-  --adaptive-max-depth 2 \
-  --prefetch-dir /tmp/vds_registry_prefetch
-```
-
-Observed benchmark against a production registry (2026-02-06):
-- Live parse (checklist-first): ~124s in a slow Confluence window.
-- Prefetch parse (same options + `--prefetch-dir`): ~1.6s, with `network_fetches=0`.
-
-Troubleshooting slow child-page retrieval:
-- High latency on `vds-cli confluence content child-pages` is typically upstream/API variance, not payload size.
-- Prefer prefetch mode for deterministic parsing (`crawl-tree` once, then local parse).
-- Keep `--parse-concurrency 1` for throttled environments and inspect diagnostics counters instead of increasing retries blindly.
-- For root -> department-container -> department -> project hierarchies, keep adaptive mode enabled with `--adaptive-max-depth 2` as baseline.
-
-#### Checklist Bootstrap for Workflow
-
-The workflow command can bootstrap the checklist page ID from centralized state metadata written by `parse-registry` (Phase 24 TSK-245):
-
-```bash
-# Parse and persist checklist seed to centralized state
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit parse-registry \
-  --registry-page "<REGISTRY_PAGE_URL_OR_ID>" \
-  --state-dsn "$VDS_AUDIT_STATE_DSN"
-
-# Workflow resolves checklist from centralized state automatically
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit workflow ./repo \
-  --thread-id audit-001 \
-  --canonical-checklist \
-  --state-dsn "$VDS_AUDIT_STATE_DSN"
-```
-
-**Checklist Page ID Precedence:**
-1. Explicit `--checklist-page-id` (highest priority)
-2. Centralized-state checklist seed from `parse-registry`
-
-#### Prepare Data Once -> Analyze Many (Phase 42)
-
-Use this flow to avoid repeated parse/extract work while running many analyses.
-`extract-docs` already includes retrieval snapshot refresh, so no separate `state refresh-retrieval-snapshot` step is required for normal prepare flow.
-Runtime evaluation is Postgres-only for evidence retrieval; disk artifacts are optional diagnostics/export outputs.
-
-```bash
-# 1) Reuse centralized state first (default path; do not re-prepare blindly)
-uv run --json-only ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit state readiness \
-  --project "<PROJECT_STORAGE_KEY_OR_PAGE_ID_OR_NAME>" \
-  --repo "<REPO_STORAGE_KEY_OR_SLUG>" \
-  --state-dsn "$VDS_AUDIT_STATE_DSN" | jq '{ready, docs_chunk_ready, code_chunk_ready}'
-
-# NOTE: project-only readiness can report docs status without repo code chunks.
-# Include --repo for dual-source gate decisions.
-
-uv run --json-only ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit 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}'
-
-# 1.1) Refresh producers only when readiness is false, source inputs changed, or state paths are missing
-# Primary prepare path:
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit prepare \
-  --project "<PROJECT_STORAGE_KEY>" \
-  --registry-page "<REGISTRY_PAGE_URL_OR_ID>" \
-  --state-dsn "$VDS_AUDIT_STATE_DSN"
-
-# Optional explicit producer steps (equivalent refresh path):
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit parse-registry --registry-page "<REGISTRY_PAGE_URL_OR_ID>" --state-dsn "$VDS_AUDIT_STATE_DSN"
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit sync repos --bitbucket-project "<BITBUCKET_PROJECT_KEY>" --project-storage-key "<PROJECT_STORAGE_KEY>" --state-dsn "$VDS_AUDIT_STATE_DSN"
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli 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"
-
-# 2) Build reusable parse seeds
-REPO_REF="<REPO_SELECTOR: REPO_KEY_OR_SLUG_OR_STORAGE_KEY_OR_URL>"
-
-uv run --json-only ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit parse-project \
-  --project "<PROJECT_STORAGE_KEY_OR_PAGE_ID_OR_NAME>" \
-  --state-dsn "$VDS_AUDIT_STATE_DSN" > /tmp/parse-project.json
-
-uv run --json-only ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit parse-repo \
-  --project "<PROJECT_STORAGE_KEY_OR_PAGE_ID_OR_NAME>" \
-  --repo "$REPO_REF" \
-  --state-dsn "$VDS_AUDIT_STATE_DSN" > /tmp/parse-repo.json
-
-# 3) Verify state readiness + skill policy, then reuse parse-repo seed
-REPO_STORAGE_KEY="$(jq -r '.repos[0].repo_storage_key // empty' /tmp/parse-repo.json)"
-uv run --json-only ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit state readiness \
-  --project "<PROJECT_STORAGE_KEY_OR_PAGE_ID_OR_NAME>" \
-  --repo "${REPO_STORAGE_KEY:-$REPO_REF}" \
-  --state-dsn "$VDS_AUDIT_STATE_DSN" | jq '{ready, docs_chunk_ready, code_chunk_ready}'
-uv run --json-only ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit doctor skills-policy
-
-DSPY_FLAG="--no-use-dspy"   # switch to --use-dspy only after compare-backends gate passes
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit workflow "<LOCAL_REPO_PATH>" \
-  --thread-id "audit-$(date +%Y%m%d-%H%M%S)" \
-  --canonical-checklist \
-  --agentic-mode auto \
-  --row-consistency-retry-mode auto \
-  $DSPY_FLAG \
-  --seed-payload /tmp/parse-repo.json \
-  --state-dsn "$VDS_AUDIT_STATE_DSN"
-```
-
-#### Extract Bitbucket Metadata
-
-Extract branch permissions, merge checks, and repository settings from Bitbucket for compliance auditing.
-
-```bash
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit extract-bitbucket-metadata \
-  --project-key INS \
-  --repo-slug insurance-core
-```
-
-This command collects:
-- Default branch name
-- Branch protection rules (branch permissions)
-- Merge check conditions (required approvers, etc.)
-- Default reviewers (when API becomes available)
-
-The command gracefully handles permission errors (403) and missing resources (404), logging warnings without failing. Output is saved as `metadata.json` with all collected information.
-When `--output-dir` is omitted, metadata is persisted to `<VDS_AUDIT_EVIDENCE_DIR>/bitbucket` (by default under the effective VDS cache root for your environment).
-
-Use `--json-only` for machine-readable output:
-
-```bash
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit --json-only extract-bitbucket-metadata \
-  --project-key INS \
-  --repo-slug insurance-core > metadata.json
-```
-
-#### Evidence Quality Check (Phase 20)
-
-Check evidence readiness before running an audit to ensure sufficient documentation and code context.
-
-```bash
-# Check evidence quality with threshold
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit evidence-quality \
-  --evidence-dir evidence/ \
-  --fail-threshold 80
-
-# Quality check using the configured persistent evidence root
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit evidence-quality \
-  --json
-
-# JSON output for CI/CD pipelines
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit --json-only evidence-quality \
-  > evidence_metrics.json
-```
-
-This command evaluates:
-- **Documentation Coverage**: Confluence pages, diagrams, attachments
-- **Code Evidence**: Repository structure, key files, traceability markers
-- **Quality Metrics**: Completeness, freshness, and usability scores
-
-Metric notes:
-- Attachment metrics are computed from real attachment artifacts (`attachments[]` / legacy attachment entries), not registry `project.documents` link inventory.
-- Max corpus chunk size is derived from Postgres `corpus_documents` chunk payloads using `text` (primary) with `content` backward compatibility. (`corpus.jsonl` is a diagnostic export artifact; runtime evidence is loaded from Postgres only.)
-
-Use `--fail-threshold` to set a minimum quality score (0-100). The command exits with code 1 if the threshold is not met, enabling fail-fast CI/CD workflows.
-
-#### List Extracted Materials (with Tree)
-
-```bash
-# State-only material listing
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit list-materials
-
-# Scoped filesystem view (optional)
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit list-materials \
-  --evidence-dir evidence \
-  --tree \
-  --tree-depth 4 \
-  --timestamps
-```
-
-`list-materials` reads manifests from centralized state. `--evidence-dir` is optional and only used to scope filesystem rendering/path filtering.
-
-#### Upload Results (Update-in-Place)
-
-```bash
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit upload-results \
-  --report-dir reports/verification \
-  --parent-page "<CONFLUENCE_PARENT_PAGE_URL_OR_ID>" \
-  --page-title "Audit Results - 2026-02-03"
-```
-
-- If a child page with the same title already exists under the audit history page, it is updated in-place.
-- Attachments (`.xlsx`, `.json`, `.sarif`) are replaced when a file with the same name exists.
-
-Phase 34 adds incremental upload control:
-
-```bash
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit upload-results \
-  --report-dir reports/workflow_smoke_row1_phase34_reverify_fix \
-  --parent-page "<CONFLUENCE_PARENT_PAGE_URL_OR_ID>" \
-  --page-title "Audit Results - Incremental" \
-  --update-mode incremental
-```
-
-- `--update-mode full` (default): full page refresh + attachment handling.
-- `--update-mode incremental`: apply delta-scoped updates when `audit-checklist.meta.json` and `audit-checklist.delta.json` are present.
-- Incremental mode automatically falls back to `full` with explicit logs if preconditions are missing or incompatible.
-
-#### Phase 46: `publish-system-doc` (Operator Notes, Complete)
-
-`publish-system-doc` is a Phase 46 command for publishing/syncing the managed **Audit System Documentation** Confluence page under the registry root/project parent.
-
-```bash
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit publish-system-doc --project "<PROJECT_REF>"
-```
-
-Current operator contract:
-- Required arg: `--project` (project storage key, page ID, or project name used to resolve centralized-state metadata).
-- Required runtime context: Confluence credentials in the shared VDS env file and a valid state DSN (`--state-dsn` or `VDS_AUDIT_STATE_DSN`).
-- Parent resolution: if `--parent-page` is omitted, parent is resolved from centralized state (registry/project metadata). If state does not contain a usable parent, provide `--parent-page` explicitly.
-- Content scope: published page body is canonical managed content only (audit system documentation sections + sync metadata marker); legacy/manual unrelated blocks are removed on sync update.
-- Sync policy (`--sync-policy`): `if-changed` (skip when rendered hash matches), `force` (apply update regardless of token match), `dry-run` (plan only, no Confluence write).
-- Conflict policy (`--sync-conflict`): `auto` (patch managed sections), `abort` (skip update when managed remote hash conflicts), `replace` (rewrite managed body sections).
-
-Verification example (safe dry-run):
-
-```bash
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit --json-only publish-system-doc \
-  --project "<PROJECT_REF>" \
-  --sync-policy dry-run \
-  --sync-conflict auto | jq '{command, thread_id, sync: .sync}'
-```
-
-#### Canonical Artifact Lifecycle (Phase 34)
-
-Canonical checklist runs now produce:
-- `audit-checklist.xlsx`: stakeholder-facing checklist with locked base columns + deterministic extensions.
-- `audit-checklist.json`: canonical checklist payload.
-- `audit-checklist.meta.json`: artifact schema/profile metadata (`template_hash`, `evidence_hash`, row count, projection version).
-- `audit-checklist.delta.json`: changed-row delta (`before`/`after`) for targeted/incremental reruns.
-- Postgres checklist state (`audit_state.checklist_runs`, `audit_state.checklist_row_results`, `audit_state.checklist_artifacts`) as runtime source of truth for run/row/lineage queries.
-
-Runtime authority note:
-- File artifacts are publish/export outputs; runtime checklist state is read from Postgres.
-
----
-
-## Runtime Profiles (Phase 45)
-
-Runtime profiles allow deterministic switching between LLM providers (Anthropic, OpenAI, Ollama, Google Gemini, llama.cpp) without editing the shared env file referenced by `VDS_ENV_FILE` or `<config-root>/.env` between runs.
-
-### Profile File Location
-
-**Default**: effective runtime profiles file resolved through the shared VDS path/config layer.
-
-**Override**: Set `VDS_AUDIT_RUNTIME_PROFILES_FILE` to use a custom path.
-
-### Profile File Schema
-
-```yaml
-# effective runtime profiles file (for example <config-root>/audit.profiles.yaml)
-# Optional: profile to use when no --profile flag is provided
-default_profile: ollama-local-openai
-
-profiles:
-  # Local Ollama development profile
-  ollama-local-openai:
-    env:
-      VDS_AUDIT_LLM_PROVIDER: ollama
-      OLLAMA_BASE_URL: http://localhost:11434
-      VDS_AUDIT_LLM__OLLAMA_PROTOCOL: openai  # openai or anthropic
-      OLLAMA_MODEL: llama3.2
-    timeout_policy:
-      agent_timeout_seconds: 900
-      agent_timeout_max_seconds: 3600
-      agent_timeout_extension_seconds: 300
-      agent_timeout_extension_attempts: 4
-      agent_timeout_heartbeat_seconds: 20
-      row_timeout_ms: 60000
-      batch_timeout_ms: 420000
-      row_timeout_progress_extension_enabled: true
-      row_timeout_progress_retry_attempts: 2
-      row_timeout_progress_extension_ms: 45000
-      row_timeout_progress_max_ms: 180000
-
-  # Production Anthropic profile
-  anthropic-prod:
-    env:
-      VDS_AUDIT_LLM_PROVIDER: anthropic
-      ANTHROPIC_API_KEY: sk-ant-...
-
-  # Production OpenAI profile
-  openai-prod:
-    env:
-      VDS_AUDIT_LLM_PROVIDER: openai
-      OPENAI_API_KEY: sk-...
-
-  # Google Gemini profile (native protocol via local proxy)
-  gemini:
-    model:
-      llm:
-        simple: "gemini-3-pro-high"
-        standard: "gemini-3-pro-high"
-        complex: "gemini-3-pro-high"
-      dspy:
-        model: "gemini/gemini-3-pro-high"
-        max_tokens: 8192
-        temperature: 0.0
-        google_base_url: "http://127.0.0.1:8045"
-        google_system_role_compat: true
-    env:
-      VDS_AUDIT_LLM_ENABLED: "true"
-      VDS_AUDIT_LLM_PROVIDER: google
-      GOOGLE_API_KEY: "sk-local"
-      VDS_AUDIT_LLM__GOOGLE_BASE_URL: "http://127.0.0.1:8045"
-```
-
-Validated Alibaba DashScope examples (`qwen3.5-plus`):
-
-```yaml
-  alibaba-openai:
-    model:
-      llm:
-        type: openai
-        base_url: https://coding-intl.dashscope.aliyuncs.com/v1
-        api_key: ${ALIBABA_API_KEY}
-        simple: qwen3.5-plus
-        standard: qwen3.5-plus
-        complex: qwen3.5-plus
-      dspy:
-        type: openai
-        model: openai/qwen3.5-plus
-    env:
-      VDS_AUDIT_LLM_ENABLED: "true"
-      VDS_AUDIT_LLM__API_KEY: ${ALIBABA_API_KEY}
-      VDS_AUDIT_LLM__MAX_TOKENS_PER_REQUEST: "12000"
-      VDS_AUDIT_LLM__AGENT_RETRIES: "2"
-      VDS_AUDIT_LLM__OUTPUT_RETRIES: "4"
-
-  alibaba-anthropic:
-    model:
-      llm:
-        type: anthropic
-        base_url: https://coding-intl.dashscope.aliyuncs.com/apps/anthropic
-        api_key: ${ALIBABA_API_KEY}
-        simple: qwen3.5-plus
-        standard: qwen3.5-plus
-        complex: qwen3.5-plus
-      dspy:
-        type: anthropic
-        model: anthropic/qwen3.5-plus
-    env:
-      VDS_AUDIT_LLM_ENABLED: "true"
-      VDS_AUDIT_LLM__API_KEY: ${ALIBABA_API_KEY}
-      VDS_AUDIT_LLM__MAX_TOKENS_PER_REQUEST: "12000"
-      VDS_AUDIT_LLM__AGENT_RETRIES: "2"
-      VDS_AUDIT_LLM__OUTPUT_RETRIES: "4"
-```
-
-- Leave `model.llm.reasoning_effort` unset for both Alibaba profiles; `qwen3.5-plus` on DashScope uses provider-native thinking controls more reliably than the generic reasoning-effort abstraction.
-
-### Schema Fields
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `default_profile` | string | No | Profile name to use when `--profile` is not specified |
-| `profiles` | map | Yes | Named profile definitions |
-| `profiles.<name>.env` | map | Yes | Environment variables to inject for this profile |
-| `profiles.<name>.model` | map | No | Structured model policy for LLM tiers + DSPy settings |
-| `profiles.<name>.retry_policy` | map | No | Retry scalar overrides (validated bounds) |
-| `profiles.<name>.timeout_policy` | map | No | Agent + workflow timeout scalar overrides (validated bounds) |
-
-`model` keys:
-- `model.llm.simple`
-- `model.llm.standard`
-- `model.llm.complex`
-- `model.dspy.model`
-- `model.dspy.max_tokens`
-- `model.dspy.temperature`
-- `model.dspy.google_base_url`
-- `model.dspy.google_system_role_compat`
-
-Model policy notes:
-- `model.llm.*` and `model.dspy.*` are validated on profile activation (unknown keys, wrong types, and out-of-range values fail fast).
-- DSPy coherence is validated at profile activation (`provider` + `VDS_AUDIT_DSPY_MODEL` must match by prefix, or let runtime auto-derive from `model.llm.standard`).
-- Runtime startup also enforces runtime contract checks (single-mode `pydanticai`) and endpoint/model compatibility checks.
-
-`timeout_policy` keys:
-- `agent_timeout_seconds`
-- `agent_timeout_max_seconds`
-- `agent_timeout_extension_seconds`
-- `agent_timeout_extension_attempts`
-- `agent_timeout_heartbeat_seconds`
-- `agent_idle_timeout_seconds`
-- `row_timeout_ms`
-- `batch_timeout_ms`
-- `row_timeout_progress_extension_enabled` (`true`/`false`)
-- `row_timeout_progress_retry_attempts`
-- `row_timeout_progress_extension_ms`
-- `row_timeout_progress_max_ms`
-
-### Usage Examples
-
-```bash
-# Use default profile from file (default_profile field)
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit workflow ./repo --thread-id test
-
-# Override with specific profile
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit --profile anthropic-prod workflow ./repo --thread-id test
-
-# Use OpenAI profile for audit
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit --profile openai-prod audit ./repo --template checklist.xlsx
-
-# Override profile file location via environment
-VDS_AUDIT_RUNTIME_PROFILES_FILE=/custom/path/profiles.yaml \
-  ./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit workflow ./repo --thread-id test
-```
-
-### Precedence Rules
-
-Profile resolution follows this precedence (highest to lowest):
-
-1. **CLI `--profile <name>` or `VDS_AUDIT_PROFILE`**: Explicit profile selection (CLI wins when both are present).
-2. **Profile file selection**: requested profile from `profiles.<name>`, otherwise `default_profile`.
-3. **Profile activation (pre-config-load)**: profile `model` + `env` values are injected before config loading.
-4. **Config merge**: the effective audit config file and remaining environment merge through normal config loading.
-
-**Important**: Profile values are injected *before* config loading, ensuring model/provider settings are active for LLM client initialization and startup validation.
-
-### Environment Override Escape Hatch
-
-For one-off runs, keep using direct env overrides. The CLI preserves explicit runtime model/endpoint overrides even when `--profile` is supplied (escape hatch for emergency/provider testing).
-
-Common override env keys:
-- `VDS_AUDIT_LLM__MODEL_SIMPLE`, `VDS_AUDIT_LLM__MODEL_STANDARD`, `VDS_AUDIT_LLM__MODEL_COMPLEX`
-- `VDS_AUDIT_DSPY_MODEL`, `VDS_AUDIT_DSPY_MAX_TOKENS`, `VDS_AUDIT_DSPY_TEMPERATURE`
-- `VDS_AUDIT_DSPY_GOOGLE_BASE_URL`, `VDS_AUDIT_DSPY_GOOGLE_SYSTEM_ROLE_COMPAT`
-- `VDS_AUDIT_LLM__OPENAI_BASE_URL`, `VDS_AUDIT_LLM__ANTHROPIC_BASE_URL`, `VDS_AUDIT_LLM__GOOGLE_BASE_URL`, `OLLAMA_BASE_URL`, `VDS_AUDIT_LLM__OLLAMA_PROTOCOL`, `VDS_AUDIT_LLM__OLLAMA_NUM_CTX`
-
-```bash
-VDS_AUDIT_DSPY_MODEL="openai/gpt-5-mini" \
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit --profile gemini workflow ./repo --thread-id test
-```
-
-### Migration Example (env-only -> structured model block)
-
-Before (env-only model wiring):
-
-```yaml
-profiles:
-  gemini:
-    env:
-      VDS_AUDIT_LLM__MODEL_SIMPLE: "gemini-3-pro-high"
-      VDS_AUDIT_LLM__MODEL_STANDARD: "gemini-3-pro-high"
-      VDS_AUDIT_LLM__MODEL_COMPLEX: "gemini-3-pro-high"
-      VDS_AUDIT_DSPY_MODEL: "google/gemini-3-pro-high"
-```
-
-After (structured model policy):
-
-```yaml
-profiles:
-  gemini:
-    model:
-      llm:
-        simple: "gemini-3-pro-high"
-        standard: "gemini-3-pro-high"
-        complex: "gemini-3-pro-high"
-      dspy:
-        model: "gemini/gemini-3-pro-high"
-```
-
-Tool-first policy note:
-- Row evaluation remains tool-first (bounded by `agentic.max_turns` and `agentic.max_tool_calls`), then selected prompt backend (`prompt_evaluator` or `dspy`) executes with gathered evidence context.
-
-### Skill Usage Effectiveness (Phase 73/74)
-
-For agentic checklist rows, skill tools must be used with an execution-first policy:
-
-- Decide `skills_needed` from requirement intent/evidence targets before calling skill tools.
-- When `skills_needed=false`, skill usage is optional and should be skipped unless it materially improves evidence quality.
-- Avoid discovery-only churn (`list_skills`/`load_skill` loops without evidence progression).
-- Preferred sequence is `load_skill(...)` then execution-class usage:
-  - `read_skill_resource(...)` (preferred),
-  - `run_skill_script(...)` only when explicitly available and script execution policy allows it.
-- Treat `load_skill` alone as bootstrap, not sufficient effective skill usage.
-- In read-only script policy (`allow_script_execution=false`), discovery/read calls remain allowed while `run_skill_script` stays blocked.
-- Strict effective-skill enforcement applies only when a row is skill-required (`skills_needed=true`), not globally.
-
-Diagnostics:
-
-```bash
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit --json-only doctor skills-policy
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit doctor logs-follow --tail 100 --no-follow --json
-```
-
-### Switching Providers
-
-```bash
-# Development with local Ollama
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit --profile ollama-local-openai workflow ./repo --thread-id dev-test
-
-# Production run with Anthropic
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit --profile anthropic-prod workflow ./repo --thread-id prod-audit
-
-# Google Gemini (native protocol)
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit --profile gemini workflow ./repo --thread-id gemini-test
-
-# One-off OpenAI test
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit --profile openai-prod analyze \
-  --requirement "API must authenticate requests" \
-  --state-dsn "$VDS_AUDIT_STATE_DSN"
-```
-
-### Profile vs Project Profile
-
-`--profile` and `--project-profile` target different layers:
-
-1. **Global runtime profile**: `--profile` applies first in CLI callback and injects runtime provider/env settings for the entire command.
-2. **Command-level project profile**: `--project-profile` applies inside supported commands (`audit`, `analyze-template`, `analyze-gaps`) and overrides profile auto-detection for project classification.
-
-They are complementary, not mutually exclusive: when both are supplied, runtime uses `--profile` while project scoring/detection uses `--project-profile`.
-
-```bash
-# Runtime profile only (provider/env behavior)
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit --profile openai-prod workflow ./repo --thread-id run-001
-
-# Both together: global runtime profile + command-level project profile
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit --profile openai-prod audit ./repos \
-  --template ./checklist.xlsx \
-  --project-profile ./profiles/service.yaml
-```
-
-### Global Options
-
-| Option | Description |
-|--------|-------------|
-| `--version` | Show CLI version and exit |
-| `--profile <name>` | Runtime provider profile from the effective runtime profiles file |
-| `--json-only` | Emit JSON to stdout only |
-| `--structured-logs` | JSON logs to stderr |
-| `--report-dir PATH` | Report output directory |
-| `--reports/--no-reports` | Enable/disable report files |
-| `--markdown/--no-markdown` | Enable/disable Markdown summaries |
-| `--sarif/--no-sarif` | Enable/disable SARIF output |
-| `--verbose, -v` | Verbose output |
-| `--trace` | Enable full log output (disable truncation) |
-| `--show-reasoning` | Show LLM reasoning chains in output |
-
----
-
-## Templates
-
-### Excel Template Structure
-
-Templates are Excel files with three sheets:
-
-#### 1. Sections Sheet
-
-Defines audit categories and their weights:
-
-| 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 |
-
-**Important:** Section weights must sum to 100.0.
-
-#### 2. Checks Sheet
-
-Defines individual audit criteria:
-
-| id | section_id | description | max_points | check_type | check_config | severity |
-|----|------------|-------------|------------|------------|--------------|----------|
-| SEC-001 | security | Branch protection enabled | 100 | bitbucket_branch_permission | {"branch": "main"} | High |
-| DOC-001 | documentation | README exists | 100 | git_file_exists | {"file_path": "README.md"} | Medium |
-
-**Note:** If `weight` is omitted, severity-based fallback is used:
-- Critical: 10.0
-- High: 7.5
-- Medium: 5.0
-- Low: 2.5
-
-#### 3. Metadata Sheet (Optional)
-
-| Key | Value |
-|-----|-------|
-| template_version | 1.0.0 |
-| owner | Your Team |
-| last_updated | 2025-01-31 |
-| target_project_types | microservice,library |
-
-### Check Types
-
-| Type | Description | Config |
-|------|-------------|--------|
-| `git_file_exists` | Verifies file exists | `file_path` |
-| `git_file_content` | Validates file content | `file_path`, `pattern` |
-| `bitbucket_branch_permission` | Branch protection settings | `branch`, `required_approvers` |
-| `bitbucket_merge_condition` | PR merge conditions | `min_approvals` |
-| `confluence_page_exists` | Documentation page exists | `page_title`, `space_key` |
-| `sonarqube_quality_gate` | Quality gate status | `gate_name`, `check_new_code` |
-
-### Template Validation
-
-```bash
-./scripts/worktree_uv.sh run --project audit_orchestrator ./scripts/worktree_uv.sh run --project vds_cli vds-cli audit validate-template --template template.xlsx
-```
-
----
-
-## Output Formats
-
-### Excel Report
-
-Primary output format with multiple sheets:
-
-- **Summary** - Aggregate scores and top issues
-- **Per-Repository Sheets** - Detailed findings by section
-- **Conditional Formatting** - Color-coded by severity
-
-### JSON Report
-
-Machine-readable output with full results:
-
-```json
-{
-  "metadata": {
-    "template_name": "Base Audit",
-    "template_version": "1.0.0",
-    "started_at": "2025-01-31T00:00:00Z"
-  },
-  "repositories": [
-    {
-      "repo_name": "my-service",
-      "total_score": 85.5,
-      "grade": "B",
-      "sections": [...]
-    }
-  ]
-}
-```
-
-### Markdown Summary
-
-CI-friendly summary with top issues:
-
-```markdown
-# Audit Summary
-
-**Template:** Base Audit v1.0.0
-**Repositories:** 5
-**Date:** 2025-01-31
-
-## Scores by Repository
-| Repository | Score | Grade |
-|------------|-------|-------|
-| my-service | 85.5 | B |
-...
-```
-
-### SARIF Report
-
-Static Analysis Results Interchange Format for tool integration:
-
-```json
-{
-  "version": "2.1.0",
-  "runs": [{
-    "tool": {"driver": {"name": "audit-orchestrator"}},
-    "results": [...]
-  }]
-}
-```
-
-Enable with `--sarif` flag.
-
----
-
-## Contributing
-
-### Development Setup
-
-```bash
-# Install with dev dependencies
-uv sync --dev
-
-# Run tests
-uv run pytest
-
-# Run with coverage
-uv run pytest --cov=vds_audit_orchestrator
-
-# Format code
-uv run ruff format src tests
-
-# Lint code
-uv run ruff check src tests
-
-# Phase 42 verification gate set
-uv run scripts/verify_phase_42.py --strict-help
-```
-
-### Creating Custom Checks
-
-1. Inherit from `BaseCheck`:
-
-```python
-from vds_audit_orchestrator.checks.base import BaseCheck, CheckContext, CheckResult
-from vds_audit_orchestrator.checks.registry import CheckRegistry, CheckMetadata
-from vds_audit_orchestrator.models.enums import Severity
-
-@CheckRegistry.register(
-    "my_custom_check",
-    metadata=CheckMetadata(
-        check_type="my_custom_check",
-        name="My Custom Check",
-        description="Validates custom criteria",
-        category="custom",
-        default_severity=Severity.MEDIUM,
-    )
-)
-class MyCustomCheck(BaseCheck):
-    async def execute(self, context: CheckContext) -> CheckResult:
-        # Check implementation
-        return CheckResult(
-            status=CheckStatus.PASSED,
-            score=100.0,
-            message="Check passed",
-        )
-```
-
-2. Place in `src/vds_audit_orchestrator/checks/custom/`
-
-3. Import in `__init__.py` to register
-
-### Project Structure
-
-```
-audit_orchestrator/
-├── src/vds_audit_orchestrator/
-│   ├── checks/          # Check implementations
-│   ├── engine/          # Audit orchestration
-│   ├── models/          # Pydantic models
-│   ├── reports/         # Report generators
-│   └── cli.py           # CLI entry point
-├── tests/               # Test suite
-├── docs/                # Documentation
-├── pyproject.toml       # Project config
-└── README.md
-```
-
-### Standards
-
-- Python 3.14+
-- Pydantic v2.12+ for data models
-- PydanticAI v1.59+ for LLM agent runtime
-- LangGraph v1.0.8+ for workflow orchestration
-- Structlog v25+ for logging
-- Typer v0.23+ for CLI
-- Ruff v0.15+ for formatting/linting
-
----
-
-## Documentation
-
-- [DEPLOYMENT.md](docs/DEPLOYMENT.md) - Installation and configuration guide
-- [OLLAMA_EMBEDDINGS_SETUP.md](docs/OLLAMA_EMBEDDINGS_SETUP.md) - Local embeddings setup/runbook for Phase 43 retrieval
-- [PHASE32_REAL_BENCHMARK_2026-02-08.md](docs/PHASE32_REAL_BENCHMARK_2026-02-08.md) - Real CLI benchmark evidence for parsing and extraction strategies
-- [API.md](docs/API.md) - Developer API reference
-- [Requirements](.kiro/specs/audit-orchestrator/requirements.md) - Functional requirements
-- [Design](.kiro/specs/audit-orchestrator/design.md) - Architecture and design
-
-## License
-
-Proprietary - Viettel Digital Services
-
-## Version
-
-4.2.1
-Design](.kiro/specs/audit-orchestrator/design.md) - Architecture and design
-
-## License
-
-Proprietary - Viettel Digital Services
-
-## Version
-
-4.2.1
-rietary - Viettel Digital Services
-
-## Version
-
-4.2.1
-igital Services
-
-## Version
-
-4.2.1
-.1
-Version
-
-4.2.1
-.1
-4.2.1
-.1
-Version
-
-4.2.1
-.1
-
-.1
-Version
-
-4.2.1
-.1
-4.2.1
-.1
-Version
-
-4.2.1
-.1
- License
-
-Proprietary - Viettel Digital Services
-
-## Version
-
-4.2.1
-rietary - Viettel Digital Services
-
-## Version
-
-4.2.1
-igital Services
-
-## Version
-
-4.2.1
-.1
-Version
-
-4.2.1
-.1
-4.2.1
-.1
-Version
-
-4.2.1
-.1
-
-.1
-Version
-
-4.2.1
-.1
-4.2.1
-.1
-Version
-
-4.2.1
-.1