@ngocsangairvds/vsaf 4.0.6 → 4.0.7

package/skills/vds-skill/vds-scripts/docs/agents/reference/orchestrator-comparison-matrix.md

@@ -0,0 +1,79 @@
+<!-- diátaxis: reference -->
+
+# Orchestrator Comparison Matrix
+
+Quick reference for selecting the right orchestrator for your task.
+
+## By Use Case
+
+### I want to audit code quality
+
+| Orchestrator | Scope | Prerequisites | Output |
+|-------------|-------|--------------|--------|
+| `audit` | Multi-repo, department-level | Confluence access, checklist config | Scorecard, evidence |
+| `sonarqube` | Single repo | SonarQube server | Issues, metrics, coverage |
+| `hexagonal` | Single repo | Python source | Boundary violations |
+| `public_interface` | Single repo | Python source | Import violations |
+
+### I want to generate or update documentation
+
+| Orchestrator | Scope | Prerequisites | Output |
+|-------------|-------|--------------|--------|
+| `confluence` | Pages, spaces | Confluence credentials | Uploaded pages |
+| `markdown` | Files | — | Formatted markdown |
+| `brd` | Business requirements | PRD input | BRD document |
+| `spec` | VDS specs | Skill manifest | Validated spec |
+| `diagrams` | Architecture | Code or config | Mermaid, PNG, PDF |
+
+### I want to work with data
+
+| Orchestrator | Scope | Prerequisites | Output |
+|-------------|-------|--------------|--------|
+| `db_query` | Ad-hoc SQL | DB connection | Query results |
+| `elastic` | Logs, metrics | ES cluster | Search results |
+| `schema` | Data formats | Source schema | Converted schema |
+| `excel` | Spreadsheets | — | Processed Excel |
+| `google_sheets` | Sheets | Google API | Synced data |
+| `metabase` | Dashboards | Metabase instance | Embedded charts |
+
+### I want to manage infrastructure
+
+| Orchestrator | Scope | Prerequisites | Output |
+|-------------|-------|--------------|--------|
+| `git` | Repositories | Git access | Worktrees, operations |
+| `scheduler` | Cron jobs | Redis | Scheduled tasks |
+| `evolution` | Ecosystem health | Postgres | Evolution report |
+| `links` | Internal links | — | Link health report |
+| `structure` | Repo structure | — | Structure analysis |
+
+### I want AI-assisted development
+
+| Orchestrator | Scope | Prerequisites | Output |
+|-------------|-------|--------------|--------|
+| `memory` | Cross-session | Memory service | Persistent knowledge |
+| `research` | Evidence | MCP router | Research report |
+| `multi_agent` | Parallel agents | Workflow def | Aggregated results |
+| `telegram` | Notifications | Bot token | Messages, alerts |
+| `claude` | Claude API | Anthropic key | Generated content |
+| `mcp` | MCP servers | Server config | Integrated tools |
+| `lsp` | Code intelligence | LSP server | Diagnostics, refs |
+
+## By Complexity
+
+| Complexity | Orchestrators | Start With |
+|-----------|---------------|-----------|
+| Basic | audit, confluence, db_query, diagrams, progress, scheduler | `vds-cli <name> --help` |
+| Intermediate | circular_dependency, elastic, git, hexagonal, links, memory, public_interface, schema, sonarqube, spec, structure | Read the how-to guide first |
+| Advanced | brd, claude, evolution, excel, google_sheets, intellij, jira, lsp, markdown, mcp, metabase, multi_agent, openapi, pdf, research, telegram | Check prerequisites carefully |
+
+## Quick Recommendations
+
+| Task | Recommended | Why |
+|------|------------|-----|
+| First audit ever | `audit` | Built-in defaults, no extra config |
+| Upload evidence | `confluence` | Automatic formatting |
+| Check architecture | `hexagonal` + `public_interface` | Two views of same problem |
+| Generate diagrams | `diagrams` | Mermaid output, version-controlled |
+| Parallel work | `git worktree-create` | Isolated branches |
+| Research topic | `research` | Combines local + web sources |
+| Schedule reports | `scheduler` | Cron-like, Redis-backed |

package/skills/vds-skill/vds-scripts/docs/agents/reference/orchestrator-index.md

@@ -0,0 +1,73 @@
+<!-- diátaxis: reference -->
+
+# Orchestrator Index
+
+> Quick-reference for all 28 VDS orchestrators.
+
+## Core Platform
+
+| Orchestrator | Purpose | CLI Entry | Doc |
+|-------------|---------|-----------|-----|
+| audit | Audit execution and reporting | `vds-cli audit` | [audit-triage-playbook](audit-triage-playbook.md) |
+| bitbucket | Bitbucket operations | `vds-cli bitbucket-cli` | [cli-commands](cli-commands.md) |
+| brd | Business requirements documents | `vds-cli brd` | [brd-orchestrator](brd-orchestrator.md) |
+| circular-dependency | Circular dependency detection | `vds-cli circular-dependency` | [circular-dependency-orchestrator](circular-dependency-orchestrator.md) |
+| confluence | Confluence operations | `vds-cli confluence-cli` | [cli-commands](cli-commands.md) |
+| db-query | Database query operations | `vds-cli db-query` | [db-query-orchestrator](db-query-orchestrator.md) |
+| diagrams | Diagram generation | `vds-cli diagrams` | [diagrams-orchestrator](diagrams-orchestrator.md) |
+| elastic | Elasticsearch operations | `vds-cli elastic` | [elastic-orchestrator](elastic-orchestrator.md) |
+| evolution | Ecosystem evolution loop | `vds-cli evolution` | [evolution-orchestrator](evolution-orchestrator.md) |
+| excel | Excel processing | `vds-cli excel` | [excel-orchestrator](excel-orchestrator.md) |
+| git | Git repository operations | `vds-cli git-orchestrator` | [cli-commands](cli-commands.md) |
+| google-sheets | Google Sheets integration | `vds-cli google-sheets` | [google-sheets-orchestrator](google-sheets-orchestrator.md) |
+| grafana | Grafana logs and metrics | `vds-cli grafana` | [grafana-orchestrator](grafana-orchestrator.md) |
+| hexagonal | Hexagonal compliance | `vds-cli hexagonal` | [hexagonal-orchestrator](hexagonal-orchestrator.md) |
+| intellij | IntelliJ plugin operations | `vds-cli intellij` | [intellij-orchestrator](intellij-orchestrator.md) |
+| jira | JIRA operations | `vds-cli jira-cli` | [cli-commands](cli-commands.md) |
+| links | Link validation | `vds-cli links` | [links-orchestrator](links-orchestrator.md) |
+| lsp | Language server protocol | `vds-cli lsp` | [lsp-orchestrator](lsp-orchestrator.md) |
+| markdown | Markdown processing | `vds-cli markdown` | [markdown-orchestrator](markdown-orchestrator.md) |
+| mcp | MCP router and tools | `vds-cli mcp-server` | [mcp-orchestrator](mcp-orchestrator.md) |
+| memory | Memory search and storage | `vds-cli memory` | [memory-orchestrator](memory-orchestrator.md) |
+| metabase | Metabase analytics | `vds-cli metabase` | [metabase-orchestrator](metabase-orchestrator.md) |
+| multi-agent | Multi-agent coordination | `vds-cli multi-agent` | [multi-agent-orchestrator](multi-agent-orchestrator.md) |
+| openapi | OpenAPI schema operations | `vds-cli openapi` | [openapi-orchestrator](openapi-orchestrator.md) |
+| pdf | PDF generation | `vds-cli pdf` | [pdf-orchestrator](pdf-orchestrator.md) |
+| progress | Progress reporting | `vds-cli progress` | [progress-orchestrator](progress-orchestrator.md) |
+| public-interface | Public API analysis | `vds-cli public-interface` | [public-interface-orchestrator](public-interface-orchestrator.md) |
+| research | Research and evidence | `vds-cli research` | [research-orchestrator](research-orchestrator.md) |
+| schema | Schema conversion | `vds-cli schema-convert` | [schema-orchestrator](schema-orchestrator.md) |
+| sonarqube | SonarQube integration | `vds-cli sonarqube` | [sonarqube-orchestrator](sonarqube-orchestrator.md) |
+| spec | Spec creation | `vds-cli spec` | [spec-orchestrator](spec-orchestrator.md) |
+| structure | Code structure analysis | `vds-cli structure` | [structure-orchestrator](structure-orchestrator.md) |
+| tasks | Task management | `vds-cli tasks` | [tasks-orchestrator](tasks-orchestrator.md) |
+
+## By Category
+
+### Audit & Reporting
+- [audit](audit-triage-playbook.md), [progress](progress-orchestrator.md), [spec](spec-orchestrator.md)
+
+### Data & Analytics
+- [db-query](db-query-orchestrator.md), [elastic](elastic-orchestrator.md), [grafana](grafana-orchestrator.md), [metabase](metabase-orchestrator.md), [google-sheets](google-sheets-orchestrator.md), [excel](excel-orchestrator.md)
+
+### Code Quality
+- [circular-dependency](circular-dependency-orchestrator.md), [hexagonal](hexagonal-orchestrator.md), [sonarqube](sonarqube-orchestrator.md), [structure](structure-orchestrator.md), [public-interface](public-interface-orchestrator.md), [intellij](intellij-orchestrator.md), [lsp](lsp-orchestrator.md)
+
+### Documentation
+- [confluence](cli-commands.md), [markdown](markdown-orchestrator.md), [pdf](pdf-orchestrator.md), [diagrams](diagrams-orchestrator.md), [brd](brd-orchestrator.md)
+
+### Research & Intelligence
+- [research](research-orchestrator.md), [memory](memory-orchestrator.md), [mcp](mcp-orchestrator.md)
+
+### DevOps
+- [git](cli-commands.md), [bitbucket](cli-commands.md), [jira](cli-commands.md), [links](links-orchestrator.md), [openapi](openapi-orchestrator.md), [schema](schema-orchestrator.md)
+
+### Coordination
+- [tasks](tasks-orchestrator.md), [multi-agent](multi-agent-orchestrator.md), [evolution](evolution-orchestrator.md)
+
+## Related
+
+- [Orchestrator Architecture](orchestrator-architecture.md)
+- [CLI Commands Reference](cli-commands.md)
+- [CLI Help Matrix](cli-help-matrix.md)
+- [Skills Reference](skills-reference.md)

package/skills/vds-skill/vds-scripts/docs/agents/reference/pdf-orchestrator.md

@@ -0,0 +1,57 @@
+<!-- diátaxis: reference -->
+
+# PDF Orchestrator
+
+> PDF generation from markdown and other formats — convert, apply templates, batch generate.
+
+## Scope
+
+- **Does:** Convert markdown to PDF, apply templates, batch generate documents, and handle Vietnamese text rendering.
+- **Does NOT:** Edit existing PDFs, perform OCR, or replace dedicated PDF editors.
+- **Primary users:** AI agents (document delivery), operators (report generation), compliance teams.
+
+## CLI Entry
+
+```bash
+# Via unified router
+vds-cli pdf --help
+
+# Direct entry
+vds-cli pdf --help
+```
+
+## Key Commands
+
+| Command | Purpose | Common Flags |
+|---------|---------|-------------|
+| `vds-cli pdf md2pdf` | Markdown to PDF | `--input`, `--output`, `--template` |
+| `template` | Apply PDF template | `--template`, `--data` |
+| `batch` | Batch generate PDFs | `--input-dir`, `--output-dir` |
+| `validate` | Validate PDF output | `--input` |
+
+## Common Workflows
+
+### Workflow: Generate Report from Markdown
+
+1. Write report in markdown with frontmatter
+2. Run `vds-cli pdf md2pdf --input report.md --output report.pdf --template corporate`
+3. Validate output: `vds-cli pdf validate --input report.pdf`
+
+### Workflow: Batch Generate Invoices
+
+1. Prepare invoice data as JSON files
+2. Run `vds-cli pdf batch --input-dir invoices/ --output-dir pdfs/ --template invoice`
+3. Review generated PDFs
+
+## Related
+
+- **Orchestrators:** [markdown](markdown-orchestrator.md), [diagrams](diagrams-orchestrator.md), [confluence](cli-commands.md)
+- **Confluence:** [WHO PDF](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation)
+
+## Troubleshooting
+
+| Issue | Cause | Resolution |
+|-------|-------|------------|
+| Command not found | Orchestrator not installed | Run `uv sync --all-packages` |
+| Config missing | `~/.vds/.env` unset | Add required credentials per [AGENTS.md](../../../AGENTS.md) |
+| Permission denied | Insufficient privileges | Check Bitbucket/Confluence token scope |

package/skills/vds-skill/vds-scripts/docs/agents/reference/portable-paths-validation-matrix.md

@@ -0,0 +1,129 @@
+<!-- diátaxis: reference -->
+
+# Portable path/config validation matrix
+
+This reference turns the Phase 2 portability spec into an executable validation posture.
+It records what should be validated natively on the host, what can be validated in
+Docker-based Ubuntu/Linux, and what must remain Windows-oriented simulation unless a
+real Windows environment is available.
+
+## Verification lanes
+
+| Lane | Purpose | Environment | Evidence type |
+| --- | --- | --- | --- |
+| macOS native | Confirm the host development environment uses the shared helper and respects overrides | Current macOS host | Focused tests + manual CLI smoke |
+| Ubuntu/Linux via Docker | Confirm the helper and focused tests behave in real Linux userspace | Docker container on current host | Scripted test run |
+| Windows-oriented simulation | Confirm Windows path/env semantics are modeled correctly in code/docs/tests | Non-Windows host | Contract tests + documented examples |
+| Windows native (future) | Confirm behavior on real Windows filesystem/shell/env | Real Windows host or CI runner | Deferred unless available |
+
+## Current Phase 2 evidence contract
+
+When reporting portability status, classify each result as one of:
+
+- `native-macos`
+- `docker-ubuntu`
+- `windows-simulated`
+- `windows-native`
+- `deferred`
+
+Do not collapse these into one generic “cross-platform verified” claim.
+
+## Recommended checks by lane
+
+### 1. macOS native
+
+Run on the active development host.
+
+Recommended checks:
+- `uv run --project vds_cli_common pytest vds_cli_common/tests/test_paths.py vds_cli_common/tests/test_env.py`
+- `PYTHONPATH=audit_orchestrator/src:vds_cli_common/src:bitbucket_orchestrator/src:confluence_orchestrator/src:sonarqube_orchestrator/src:google_sheets_orchestrator/src:excel_orchestrator/src:git_orchestrator/src:vds_cli/src:spec_orchestrator/src ./scripts/worktree_uv.sh run --project audit_orchestrator pytest audit_orchestrator/tests/test_paths_config_phase2.py audit_orchestrator/tests/test_cli_paths_phase2.py audit_orchestrator/tests/unit/scripts/test_verify_phase124_handoff.py`
+- optional smoke: `./scripts/worktree_uv.sh run --project vds_cli vds-cli env status`
+
+Expected evidence:
+- shared helper tests pass
+- audit orchestrator focused path/log/report tests pass
+- no host-specific absolute paths are required for the focused path/config workflow
+
+### 2. Ubuntu/Linux via Docker
+
+Use a Linux container because it exercises real Linux path behavior while reusing the mounted worktree.
+
+Recommended command:
+- `./scripts/verification/phase2_portable_paths_ubuntu_docker.sh`
+- underlying compose asset: `docker/compose.phase2-verification.yml`
+
+Expected evidence:
+- Linux container test run passes through the supported script entrypoint
+- explicit `VDS_CONFIG_DIR`, `VDS_CACHE_DIR`, `VDS_LOG_DIR`, and `VDS_ENV_FILE` overrides work
+- the container uses its own verification environment path rather than depending on the mounted host `.venv`
+- the Docker lane uses an explicit container-local uv cache and verbose/frozen setup for reproducible troubleshooting
+- no hidden dependency on macOS-only paths remains in the focused verification set
+
+Limits:
+- this is Linux verification, not Windows verification
+- Docker Desktop mount behavior is still host-mediated and should not be confused with a fully independent machine
+
+### 3. Windows-oriented simulation / contract validation
+
+Use this lane on macOS/Linux hosts when no real Windows runner is available.
+
+Recommended evidence:
+- focused unit tests around helper precedence and path handling
+- documented Windows override examples in `portable-paths-and-config.md`
+- command/reference surfaces that avoid hardcoded POSIX-only assumptions
+- placeholder-based repo-cache/report-root examples instead of claiming native Windows execution
+
+Expected evidence:
+- Windows-specific separators and override semantics are accounted for in docs and helper contract
+- path/env model does not assume POSIX shell expansion as the only setup path
+
+Limits:
+- this is not proof of native PowerShell/CMD behavior
+- this is not proof of native Windows filesystem edge cases
+
+### 4. Windows native (future lane)
+
+Use only when a real Windows host or CI runner is available.
+
+Recommended future checks:
+- run the focused Phase 2 pytest suite on Windows
+- verify `VDS_CONFIG_DIR`, `VDS_CACHE_DIR`, `VDS_LOG_DIR`, `VDS_ENV_FILE` from PowerShell
+- verify path rendering and shell examples against real Windows defaults
+
+Status for current host-driven Phase 2 work:
+- `deferred`
+
+## Validation matrix
+
+| Check | macOS native | Docker Ubuntu | Windows simulated | Windows native |
+| --- | --- | --- | --- | --- |
+| Shared helper precedence tests | Yes | Yes | Yes | Deferred |
+| Audit report/log default tests | Yes | Yes | Yes | Deferred |
+| CLI/bootstrap smoke | Yes | Optional | Docs/examples only | Deferred |
+| Native filesystem semantics | Yes | Yes | No | Deferred |
+| Native shell semantics | Yes | Yes (bash) | No | Deferred |
+| PowerShell/CMD semantics | No | No | Partial docs/contracts | Deferred |
+
+## Reporting template
+
+Use this structure when recording Phase 2 evidence:
+
+- `native-macos`: what commands/tests ran, pass/fail, notes
+- `docker-ubuntu`: image used, commands/tests ran, pass/fail, notes
+- `windows-simulated`: tests/docs/contracts exercised, pass/fail, notes
+- `windows-native`: `deferred` unless a real environment was used
+
+Current implementation evidence:
+- `docs/phases/phase2-portable-paths/verification-evidence-2026-03-23.md`
+
+## Decision rule for Phase 2 closure
+
+Phase 2 can claim:
+- native macOS validation
+- Docker-based Ubuntu/Linux validation
+- Windows-oriented simulation/contract validation
+
+Phase 2 should **not** claim:
+- native Windows verification
+
+unless an actual Windows host/CI lane produced evidence.

package/skills/vds-skill/vds-scripts/docs/agents/reference/progress-orchestrator.md

@@ -0,0 +1,51 @@
+<!-- diátaxis: reference -->
+
+# Progress Orchestrator
+
+> Report and visualize progress across VDS phases and audit lanes.
+
+## Scope
+
+- **Does:** Generate progress reports, track completion metrics, visualize phase status.
+- **Does NOT:** Execute audits, modify task state directly.
+- **Primary users:** Human leads (status review), AI agents (self-reporting).
+
+## CLI Entry
+
+```bash
+# Via unified router
+vds-cli progress --help
+
+# Direct entry
+vds-cli progress --help
+```
+
+## Key Commands
+
+| Command | Purpose | Common Flags |
+|---------|---------|-------------|
+| `report` | Generate progress report | `--phase`, `--lane` |
+| `summary` | One-line status summary | `--format` |
+| `visualize` | ASCII or HTML timeline | `--output` |
+
+## Common Workflows
+
+### Workflow: Phase Progress Check
+
+1. Run `vds-cli progress report --phase 174`
+2. Review completion percentages per wave
+3. Identify blocked tasks
+4. Export for standup: `vds-cli progress summary --format markdown`
+
+## Related
+
+- **Orchestrators:** [tasks](tasks-orchestrator.md), [audit](audit-triage-playbook.md), [spec](spec-orchestrator.md)
+- **Confluence:** [WHO Progress](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation)
+
+## Troubleshooting
+
+| Issue | Cause | Resolution |
+|-------|-------|------------|
+| Command not found | Orchestrator not installed | Run `uv sync --all-packages` |
+| Config missing | `~/.vds/.env` unset | Add required credentials per [AGENTS.md](../../../AGENTS.md) |
+| Permission denied | Insufficient privileges | Check Bitbucket/Confluence token scope |

package/skills/vds-skill/vds-scripts/docs/agents/reference/progress-report-cli.md

@@ -0,0 +1,215 @@
+<!-- diátaxis: reference -->
+
+# Progress Report CLI Reference
+
+## Overview
+
+The `vds-cli progress` CLI generates multi-dimensional alignment progress reports for
+INSURANCE-AI projects. It parses a BMAD knowledge graph, runs structural analysis
+across repos, and optionally scores with LLMs.
+
+Entry point: `vds-cli progress` (direct) or `vds-cli progress` (router)
+
+## Commands
+
+### `vds-cli progress report`
+
+Generate a progress report.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `-p` / `--bitbucket-project` | TEXT | *required* | Bitbucket project key |
+| `--bmad-repo` | TEXT | `bmad_ntbh` | Knowledge graph repo |
+| `--output-dir` | PATH | `~/.vds/cache/progress-reports` | Report output directory |
+| `--max-concurrent` | INT | `4` | Max parallel structural + LLM analyses |
+| `--profile` | TEXT | None | LLM runtime profile |
+| `--llm-provider` | TEXT | `auto` | `auto`, `openai`, `anthropic`, `ollama`, `none` |
+| `--dimensions` | TEXT | `all` | `all` or `structural` |
+| `--fr` | TEXT | None | Single FR deep-dive (e.g. `FR8`) |
+| `--format` | TEXT | `markdown` | `markdown` or `json` |
+| `--skip-sync` | FLAG | False | Skip repo sync |
+| `--resume-run-id` | TEXT | None | Resume interrupted run |
+| `--mode` | TEXT | `standard` | Rendering tier: `exec` (≤20 lines), `summary` (≤100), `standard` (Phase 3 backward-compat), `full` (everything) |
+| `--fail-under` | FLOAT | None | Exit 2 if overall_score below threshold (CI gate) |
+| `--fail-on-regression` | FLAG | False | Exit 2 if any FR has critical regression (Δ ≤ -15) |
+| `--baseline` | TEXT | None | Explicit baseline run_id for regression comparison (overrides "previous run" default) |
+| `-v` / `--verbose` | FLAG | False | DEBUG-level logging |
+| `-q` / `--quiet` | FLAG | False | Suppress all log output |
+
+### `vds-cli progress topology`
+
+Dump the parsed knowledge graph as JSON.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `-p` / `--bitbucket-project` | TEXT | *required* | Bitbucket project key |
+| `--bmad-repo` | TEXT | `bmad_ntbh` | Knowledge graph repo |
+| `-q` / `--quiet` | FLAG | False | Suppress log output |
+
+### `vds-cli progress db init`
+
+Create all 5 tables (idempotent).
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--dsn` | TEXT | env | Postgres DSN |
+
+### `vds-cli progress db status`
+
+Show table presence, run count, and last score.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--dsn` | TEXT | env | Postgres DSN |
+
+## LLM Provider Semantics (`--llm-provider`)
+
+| Value | Behavior |
+|-------|----------|
+| `auto` (default) | Detect cloud LLM from env vars (`OPENAI_API_KEY`, `ANTHROPIC_AUTH_TOKEN`). If none found, degrade gracefully: dims 7-8 stay `None`, score renormalizes across structural dims. Produces the **same score as `none`** when no credentials are available. |
+| `openai` | Force OpenAI — requires `OPENAI_API_KEY` or `VDS_AUDIT_LLM__API_KEY`. |
+| `anthropic` | Force Anthropic — requires `ANTHROPIC_AUTH_TOKEN` or `VDS_AUDIT_LLM__API_KEY`. |
+| `ollama` | Force Ollama at `localhost:11434`. **Not** part of auto-detect — must be explicit. |
+| `none` | Hard-disable LLM scoring. Dims 7-8 stay `None`, structural-only renormalization applies. |
+
+**Why Ollama is opt-in only:** Local Ollama installations may have cloud-routed models (need auth), embedding-only models (no chat support), or reasoning models that need larger `max_tokens`. Aggressive auto-detection caused score regressions. Users who want Ollama scoring must pass `--llm-provider ollama` explicitly.
+
+## Rendering Modes (`--mode`, Phase 4)
+
+Four-tier progressive disclosure. Every mode uses the same underlying
+computation — modes are purely rendering flags.
+
+| Mode | Line budget | Content | Use case |
+|------|------------|---------|----------|
+| `exec` | ≤ 20 | Title, overall score, delta, one-line distribution, top-1 action | Slack/email notifications, GitHub status checks |
+| `summary` | ≤ 100 | Exec content + full summary table + top-3 + score distribution + bimodal callout + dimension coverage | Standup view, code review context |
+| `standard` (default) | ≈ 564 | Phase 3 backward-compat output (heatmap, repo health, per-FR detail, trend, risk register). **Byte-identical to Phase 3** — guarded by G-Q11c snapshot gate | Daily development review |
+| `full` | ≈ 581 | Standard + stratified cluster sub-reports + appendices | Audit / compliance / retrospective |
+
+**Backward compatibility guarantee**: `--mode standard` produces the same
+markdown output as pre-Phase-4 default mode. Phase 4 features (bimodal
+callout, stratified sub-reports, dual-metric coverage with sparklines,
+regression subsections) appear only in `summary` and `full` modes.
+
+## CI/CD Exit Codes (Phase 4)
+
+| Exit code | Meaning |
+|-----------|---------|
+| `0` | Report generated, no gates tripped |
+| `1` | Runtime error (DSN missing, sync failed, crash) |
+| `2` | **Quality gate failed** — report file still written |
+
+Gate flags:
+
+| Flag | Effect |
+|------|--------|
+| `--fail-under <score>` | Exit 2 if `overall_score < score` |
+| `--fail-on-regression` | Exit 2 if any FR has `Δ ≤ -15` vs baseline |
+| `--baseline <run-id>` | Explicit baseline comparison (overrides "previous run" default) |
+
+**⚠ SonarQube anti-pattern avoided**: The SonarQube `sonar-scanner` CLI
+returns exit code 0 by default even when quality gates fail, unless you
+explicitly pass `-Dsonar.qualitygate.wait=true`. This has silently broken
+countless CI pipelines. `vds-cli progress report` does NOT have this trap —
+`--fail-under` and `--fail-on-regression` are opt-in, but when set they
+ARE honored immediately. Report file is ALWAYS written before exit 2, so
+CI artifacts are always captured.
+
+**Example CI usage**:
+```bash
+vds-cli progress report -p INSURANCE-AI --skip-sync --fail-under 60 -q
+# exits 2 when score < 60; report still written to ~/.vds/cache/progress-reports/
+echo $?  # 2
+```
+
+## Bimodal Detection / Valence-Gap Heuristic (ADR-Q7, Phase 4)
+
+When the score distribution has a valence gap (no medium tier), the report
+emits a `bimodal_warning` block in both markdown and JSON, with stratified
+`high_cluster` / `low_cluster` sub-reports.
+
+Detection rules (all 4 must hold):
+1. `total_frs >= 10` (minimum N)
+2. `medium == 0`
+3. `high > 0 AND low > 0`
+4. `min(high, low) / total >= 0.25` (dominance guard)
+
+**Terminology**: the implementation uses `_detect_valence_gap` internally
+per ADR-Q7 — this is a UX heuristic, NOT statistical bimodality. True
+bimodal detection requires Hartigan's dip test with N ≥ 30. The JSON API
+field name `bimodal_warning` is retained for API stability.
+
+**`bimodal_warning` JSON schema** (when `detected: true`):
+
+```json
+{
+  "detected": true,
+  "high_count": 7,
+  "low_count": 8,
+  "interpretation": "Score splits into high-performers (7 FRs ≥ 60) and low-performers (8 FRs < 30) with no medium tier.",
+  "stratification_variable": "service_exists",
+  "high_cluster": {
+    "label": "passing",
+    "fr_ids": ["FR6", "FR7", "FR8"],
+    "avg_score": 83.6,
+    "dominant_blocker": "test_coverage",
+    "top_recommendation_fr": "FR8"
+  },
+  "low_cluster": {
+    "label": "blocked",
+    "fr_ids": ["FR1", "FR2"],
+    "avg_score": 12.4,
+    "dominant_blocker": "service_exists",
+    "top_recommendation_fr": "FR1"
+  }
+}
+```
+
+When `detected: false`, only `{"detected": false}` is returned.
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `VDS_PROGRESS_STATE_DSN` | PostgreSQL DSN for run persistence. Set in `~/.vds/.env`. |
+| `VDS_AUDIT_LLM_ENABLED` | Set to `0`/`false`/`no` to hard-disable LLM in auto mode. |
+| `OPENAI_API_KEY` | Auto-detected by auto mode → uses `openai` provider. |
+| `ANTHROPIC_AUTH_TOKEN` | Auto-detected by auto mode → uses `anthropic` provider. |
+| `VDS_AUDIT_LLM__BASE_URL` | Override LLM base URL (for explicit providers). |
+| `VDS_AUDIT_LLM__MODEL_STANDARD` | Override LLM model name. |
+
+## Database Schema
+
+5 tables managed by `db init`:
+
+| Table | Purpose |
+|-------|---------|
+| `progress_runs` | Run metadata, checkpoint phase, overall score |
+| `fr_assessments` | Per-FR dimension scores (structural + LLM) |
+| `document_hashes` | SHA-256 hashes for incremental analysis |
+| `service_analyses` | Per-repo structural metrics (LOC, tests, endpoints) |
+| `daily_scores` | One row per project per day for trend tracking |
+
+## Output Files
+
+Reports are written to `~/.vds/cache/progress-reports/<PROJECT>/`:
+
+- `<date>.json` — Machine-readable JSON with all FR scores
+- `<date>.md` — Markdown with executive summary, risk table, per-FR breakdown
+
+## Examples
+
+```bash
+# Quick structural check
+vds-cli progress report -p INSURANCE-AI --dimensions structural --skip-sync -q
+
+# Pipe JSON to jq
+vds-cli progress report -p INSURANCE-AI --dimensions structural --format json --skip-sync -q \
+  | jq '.overall_score'
+
+# Topology exploration
+vds-cli progress topology -p INSURANCE-AI -q | jq '.fr_modules[].fr_id'
+
+# Check last score
+vds-cli progress db status
+```

package/skills/vds-skill/vds-scripts/docs/agents/reference/public-interface-orchestrator.md

@@ -0,0 +1,73 @@
+<!-- diátaxis: reference -->
+
+# Public Interface Orchestrator
+
+> Public interface boundary evidence extraction for audit compliance.
+
+## Scope
+
+- **Does:** Scan repositories for import statements that may indicate boundary violations (internal, impl, adapter, infrastructure imports), producing heuristic evidence for audit checklist items.
+- **Does NOT:** Prove violations conclusively — output requires manual confirmation and syntax-aware interpretation.
+- **Primary users:** AI agents (audit evidence collection), compliance reviewers.
+
+## CLI Entry
+
+```bash
+# Via unified router
+vds-cli public-interface --help
+
+# Direct entry
+vds-cli public-interface --help
+```
+
+## Key Commands
+
+| Command | Purpose | Common Flags |
+|---------|---------|-------------|
+| `scan-repo` | Scan a single repo for boundary candidate imports | `--json/--no-json`, `--output` |
+| `scan-project` | Scan a project directory containing multiple repos | `--json/--no-json`, `--output` |
+
+## Detection Heuristics
+
+Scans `.py`, `.java`, `.kt`, `.ts`, `.tsx`, `.js`, `.jsx` files (excluding tests) for:
+
+- `internal` imports
+- `impl` / `adapter` imports
+- `infrastructure` imports
+- `*Impl` / `*Implementation` symbol imports
+
+## Workflow Examples
+
+```bash
+# Scan a single repository
+vds-cli public-interface scan-repo /path/to/repo
+
+# Scan with JSON output persisted
+vds-cli public-interface scan-repo /path/to/repo --output boundary-evidence.json
+
+# Scan a project directory containing multiple repos
+vds-cli public-interface scan-project /path/to/project --output project-boundary.json
+
+# Non-JSON human-readable output
+vds-cli public-interface scan-repo /path/to/repo --no-json
+```
+
+## Output Format
+
+```json
+{
+  "command": "scan-repo",
+  "scope": "repo",
+  "shared_companion_only": true,
+  "files_scanned": 150,
+  "candidate_file_count": 3,
+  "result_type": "evidence_gap",
+  "reasoning": "...",
+  "candidates": [...]
+}
+```
+
+## Related
+
+- **Orchestrators:** [hexagonal](hexagonal-orchestrator.md), [structure](structure-orchestrator.md)
+- **Confluence:** [WHO Public Interface](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation)