@ngocsangairvds/vsaf 4.1.8 → 4.1.9

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

@@ -1,79 +0,0 @@
-<!-- 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

@@ -1,73 +0,0 @@
-<!-- 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

@@ -1,57 +0,0 @@
-<!-- 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

@@ -1,129 +0,0 @@
-<!-- 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

@@ -1,51 +0,0 @@
-<!-- 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

@@ -1,215 +0,0 @@
-<!-- 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

@@ -1,73 +0,0 @@
-<!-- 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)