@ngocsangairvds/vsaf 4.1.8 → 4.1.9

package/skills/vds-skill/vds-scripts/docs/agents/how-to/orchestrator-workflows/code-quality-gate-workflow.md

@@ -1,138 +0,0 @@
-<!-- diátaxis: how-to -->
-
-# Code Quality Gate Workflow
-
-> Run a comprehensive code quality pipeline combining SonarQube, hexagonal compliance, structure validation, and circular dependency detection.
-
-## Prerequisites
-
-- `vds-scripts` cloned and bootstrapped
-- SonarQube server configured in `~/.vds/.env`
-- Target repo has `pyproject.toml` or `package.json`
-
-## Workflow Overview
-
-```
-SonarQube (static analysis)
-    ↓
-Hexagonal (architecture compliance)
-    ↓
-Structure (code organization)
-    ↓
-Circular Dependency (import cycles)
-    ↓
-Consolidated Quality Report
-```
-
-## Step 1: SonarQube Static Analysis
-
-Run SonarQube analysis on the target repo:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli sonarqube analyze --repo vds-scripts --branch main
-```
-
-Expected output:
-
-```
-[sonarqube] Project: vds-scripts
-[sonarqube] Issues: 12 (3 critical, 5 major, 4 minor)
-[sonarqube] Coverage: 78%
-[sonarqube] Duplications: 2.1%
-```
-
-Export the report:
-
-```bash
-vds-cli sonarqube report --repo vds-scripts --format json --output sonar-report.json
-```
-
-## Step 2: Hexagonal Compliance Check
-
-Validate hexagonal architecture compliance:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli hexagonal check --path . --strict
-```
-
-Expected output:
-
-```
-[hexagonal] Checking dependency direction...
-[hexagonal] Port/adapter boundaries: 24
-[hexagonal] Violations: 2
-[hexagonal] Report: hexagonal-report.json
-```
-
-## Step 3: Structure Validation
-
-Validate code structure and organization:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli structure validate --path . --mode target-state
-```
-
-Expected output:
-
-```
-[structure] Validating folder structure...
-[structure] Modules: 18
-[structure] Violations: 1 (missing __init__.py)
-[structure] Report: structure-report.json
-```
-
-## Step 4: Circular Dependency Detection
-
-Detect import cycles:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli circular-dependency analyze --path . --language python
-```
-
-Expected output:
-
-```
-[circular_dependency] Analyzing imports...
-[circular_dependency] Cycles found: 0
-[circular_dependency] Status: PASS
-```
-
-## Step 5: Consolidated Quality Report
-
-Generate a unified quality report:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli docs quality-report \
-  --sonar sonar-report.json \
-  --hexagonal hexagonal-report.json \
-  --structure structure-report.json \
-  --circular circular-report.json \
-  --output quality-report.md
-```
-
-## CI Integration
-
-Add to `.github/workflows/quality.yml`:
-
-```yaml
-- name: Code Quality Gate
-  run: |
-    vds-cli sonarqube analyze --repo ${{ github.repository }}
-    vds-cli hexagonal check --path . --strict
-    vds-cli structure validate --path . --mode target-state
-    vds-cli circular-dependency analyze --path . --language python
-```
-
-## Troubleshooting
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| SonarQube auth fails | Token expired | Refresh `SONAR_TOKEN` in `~/.vds/.env` |
-| Hexagonal check too strict | `--strict` flag | Use `--strict=false` for gradual compliance |
-| Circular dependency false positive | Test imports | Add `--exclude tests/` |
-| Structure check fails on new module | Missing config | Update `target-state.yaml` |

package/skills/vds-skill/vds-scripts/docs/agents/how-to/orchestrator-workflows/confluence-bitbucket-sync-workflow.md

@@ -1,130 +0,0 @@
-<!-- diátaxis: how-to -->
-
-# Confluence → Bitbucket Sync Workflow
-
-> Validate documentation health, push to Confluence, and verify Bitbucket links in a single pipeline.
-
-## Prerequisites
-
-- `vds-scripts` cloned and bootstrapped (`./scripts/worktree_uv.sh sync`)
-- `vds-cli doctor` passes
-- `~/.vds/.env` contains `VDS_USERNAME`, `VDS_PASSWORD`, `CONFLUENCE_HOST`
-- Bitbucket project slug and target repo known
-
-## Workflow Overview
-
-```
-docs validate (check health)
-    ↓
-confluence sync (push pages)
-    ↓
-bitbucket verify (check links)
-```
-
-## Step 1: Validate Documentation Health
-
-Run the docs validator to check diátaxis headers, link integrity, and structure.
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli docs validate --check-diataxis --check-links
-```
-
-Expected output:
-
-```
-[docs] Scanning: docs/agents/
-[docs] Files checked: 42
-[docs] Diátaxis headers: 42/42 PASS
-[docs] Broken links: 0
-[docs] Warnings: 2 (orphaned images)
-[docs] Result: PASS
-```
-
-Run a stricter check before CI:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli docs validate --check-diataxis --check-links --fail-on-warning
-```
-
-## Step 2: Sync to Confluence
-
-Push validated documentation to the Confluence space.
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli confluence sync --source docs/agents/how-to/ --space WHO --parent-page 88722450
-```
-
-Expected output:
-
-```
-[confluence] Connected: https://confluence.digital.vn
-[confluence] Pages to sync: 12
-[confluence] Created: 3
-[confluence] Updated: 9
-[confluence] Unchanged: 0
-[confluence] Errors: 0
-[confluence] Sync complete
-```
-
-Sync a single guide with explicit title:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli confluence sync --source docs/agents/how-to/first-audit-run.md \
-  --space WHO --parent-page 88722450 --title "First Audit Run"
-```
-
-## Step 3: Verify Bitbucket Links
-
-After Confluence pages are live, verify that Bitbucket repo links resolve correctly.
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli bitbucket verify-links --project vds-scripts --check-confluence-refs
-```
-
-Expected output:
-
-```
-[bitbucket] Repos scanned: 1
-[bitbucket] README links: 14
-[bitbucket] Confluence refs: 6
-[bitbucket] Broken: 0
-[bitbucket] Result: PASS
-```
-
-## CI Integration
-
-Add the following job to `.github/workflows/docs-sync.yml`:
-
-```yaml
-  docs-sync:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - name: Validate docs
-        run: |
-          ./scripts/worktree_uv.sh run --project vds_cli \
-            vds-cli docs validate --check-diataxis --check-links --fail-on-warning
-      - name: Sync to Confluence
-        run: |
-          ./scripts/worktree_uv.sh run --project vds_cli \
-            vds-cli confluence sync --source docs/agents/ --space WHO --parent-page ${{ vars.CONFLUENCE_PARENT_PAGE }}
-      - name: Verify Bitbucket links
-        run: |
-          ./scripts/worktree_uv.sh run --project vds_cli \
-            vds-cli bitbucket verify-links --project vds-scripts --check-confluence-refs
-```
-
-## Troubleshooting
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| `docs validate` fails on diátaxis | Missing `<!-- diátaxis: how-to -->` header | Add header to offending file and re-run |
-| `confluence sync` auth error | Missing or expired credentials | Check `~/.vds/.env` for `VDS_USERNAME` and `VDS_PASSWORD` |
-| `confluence sync` page conflict | Duplicate page title in space | Use `--title` override or delete duplicate manually |
-| `bitbucket verify-links` finds broken refs | Confluence page ID changed | Update hardcoded page IDs in README or docs |
-| Sync is slow | Large image attachments | Add `--skip-attachments` for text-only sync |

package/skills/vds-skill/vds-scripts/docs/agents/how-to/orchestrator-workflows/document-delivery-workflow.md

@@ -1,142 +0,0 @@
-<!-- diátaxis: how-to -->
-
-# Document Delivery Workflow
-
-> Generate and deliver documentation from markdown through diagrams, PDF, and Confluence.
-
-## Prerequisites
-
-- `vds-scripts` cloned and bootstrapped
-- Confluence credentials in `~/.vds/.env`
-- Markdown source files in `docs/` directory
-
-## Workflow Overview
-
-```
-Markdown (source content)
-    ↓
-Diagrams (generate visuals)
-    ↓
-PDF (format for delivery)
-    ↓
-Confluence (publish and share)
-```
-
-## Step 1: Prepare Markdown Content
-
-Write documentation in markdown with embedded mermaid diagrams:
-
-```markdown
-# Architecture Overview
-
-## System Diagram
-
-```mermaid
-graph TD
-    A[Client] --> B[API Gateway]
-    B --> C[Service A]
-    B --> D[Service B]
-```
-
-## Details
-
-See [API Reference](../reference/api.md).
-```
-
-## Step 2: Generate Diagrams
-
-Render mermaid diagrams to images:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli diagrams mermaid --input architecture.md --output diagrams/
-```
-
-Expected output:
-
-```
-[diagrams] Found 2 mermaid blocks
-[diagrams] Rendered: diagrams/diagram-1.svg
-[diagrams] Rendered: diagrams/diagram-2.svg
-```
-
-Generate C4 diagrams if needed:
-
-```bash
-vds-cli diagrams c4 --level container --input c4-model.md --output c4-container.png
-```
-
-## Step 3: Convert to PDF
-
-Generate PDF from markdown:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli pdf md2pdf --input architecture.md --output architecture.pdf --template corporate
-```
-
-Expected output:
-
-```
-[pdf] Converting architecture.md...
-[pdf] Applied template: corporate
-[pdf] Output: architecture.pdf (12 pages)
-```
-
-Batch generate for all docs:
-
-```bash
-vds-cli pdf batch --input-dir docs/ --output-dir pdfs/ --template corporate
-```
-
-## Step 4: Publish to Confluence
-
-Sync documentation to Confluence:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli confluence sync --input architecture.md --page-id 12345 --space WHO
-```
-
-Expected output:
-
-```
-[confluence] Uploading to space WHO...
-[confluence] Page updated: Architecture Overview
-[confluence] Attachments: 3 images, 1 PDF
-```
-
-## Step 5: Verify and Share
-
-Validate published content:
-
-```bash
-vds-cli confluence validate --page-id 12345 --check-links --check-images
-```
-
-Share with team:
-
-```bash
-vds-cli confluence notify --page-id 12345 --channel slack --message "Architecture docs updated"
-```
-
-## CI Integration
-
-Add to `.github/workflows/docs.yml`:
-
-```yaml
-- name: Document Delivery
-  run: |
-    vds-cli diagrams mermaid --input docs/ --output diagrams/
-    vds-cli pdf batch --input-dir docs/ --output-dir pdfs/
-    vds-cli confluence sync --input docs/ --space WHO
-```
-
-## Troubleshooting
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| Mermaid render fails | Invalid syntax | Validate with `vds-cli diagrams validate` |
-| PDF missing fonts | System fonts unavailable | Install `libgobject-2.0-0` or use Docker |
-| Confluence upload fails | Auth expired | Refresh `CONFLUENCE_TOKEN` in `~/.vds/.env` |
-| Images not attached | Path mismatch | Use relative paths from markdown file |

package/skills/vds-skill/vds-scripts/docs/agents/how-to/orchestrator-workflows/memory-progress-workflow.md

@@ -1,140 +0,0 @@
-<!-- diátaxis: how-to -->
-
-# Memory → Progress Tracking Workflow
-
-> Store observations in VDS AI Memory, recall prior context, and generate progress reports to track phase completion.
-
-## Prerequisites
-
-- `vds-scripts` cloned and bootstrapped (`./scripts/worktree_uv.sh sync`)
-- `vds-cli doctor` passes
-- `~/.vds/.env` contains memory backend credentials (Postgres DSN or local file path)
-
-## Workflow Overview
-
-```
-memory store (save observations)
-    ↓
-memory recall (retrieve context)
-    ↓
-progress report (track completion)
-```
-
-## Step 1: Store Observations in Memory
-
-Save key observations after each work session so they are available to future agents.
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli memory store --tag "phase174,spec,fr-3" \
-  --content "FR-3 requires multi-step workflow guides combining 2+ orchestrators"
-```
-
-Expected output:
-
-```
-[memory] Stored observation: obs-20260422-001
-[memory] Tags: phase174, spec, fr-3
-[memory] Content length: 72 characters
-[memory] Timestamp: 2026-04-22T08:00:00Z
-```
-
-Store multiple observations from a batch session:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli memory store --tag "phase174,audit" \
-  --content "Audit run completed with 3 violations in hexagonal-compliance rules"
-```
-
-## Step 2: Recall Prior Context
-
-Before starting a new session, search memory for relevant prior work.
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli memory search "phase174 workflow guides"
-```
-
-Expected output:
-
-```
-[memory] Query: phase174 workflow guides
-[memory] Results: 2
-[memory] obs-20260422-001 — phase174, spec, fr-3
-[memory] obs-20260422-002 — phase174, audit
-[memory] Retrieved in 0.12s
-```
-
-Recall with tag filter for narrower scope:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli memory search "fr-3" --tag spec
-```
-
-## Step 3: Generate Progress Reports
-
-Create a progress report from stored observations and current audit state.
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli progress report --phase 174 --format markdown
-```
-
-Expected output:
-
-```
-[progress] Phase: 174
-[progress] Spec items: 8/12 complete
-[progress] Audit violations: 3 open
-[progress] Report: /tmp/vds-progress-phase174.md
-```
-
-Generate a consolidated report across multiple phases:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli progress report --phase 174,175,176 --format json
-```
-
-Track phase completion with checklist integration:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli progress checklist --phase 174 --update-status
-```
-
-Expected output:
-
-```
-[checklist] Phase: 174
-[checklist] Items: 12
-[checklist] Completed: 8
-[checklist] Blocked: 1
-[checklist] Not started: 3
-[checklist] State saved to: checklist-progress.state
-```
-
-## Automation Tips
-
-Add to your shell profile or agent hook to auto-store after each command:
-
-```bash
-vds_memory_store() {
-  local tag="$1"
-  local content="$2"
-  ./scripts/worktree_uv.sh run --project vds_cli \
-    vds-cli memory store --tag "$tag" --content "$content"
-}
-```
-
-## Troubleshooting
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| `memory store` fails with auth error | Missing DSN or credentials | Check `~/.vds/.env` for `VDS_MEMORY_DSN` or local path |
-| `memory search` returns empty | No matching tags or content | Broaden query or check stored tags with `memory list` |
-| `progress report` shows stale data | State file not updated | Run `vds-cli progress checklist --update-status` first |
-| `progress checklist` blocked item | Missing dependency or material | Check `blocked_by_materials` flag in checklist state |
-| Memory operations are slow | Large observation corpus | Add `--limit 50` to search or prune old observations |

package/skills/vds-skill/vds-scripts/docs/agents/how-to/orchestrator-workflows/research-spec-audit-workflow.md

@@ -1,135 +0,0 @@
-<!-- diátaxis: how-to -->
-
-# Research → Spec → Audit Workflow
-
-> Combine the research, spec, and audit orchestrators to gather evidence, formalize requirements, and validate implementation.
-
-## Prerequisites
-
-- `vds-scripts` cloned and bootstrapped (`./scripts/worktree_uv.sh sync`)
-- `vds-cli doctor` passes
-- Target repo(s) accessible via Bitbucket
-- `~/.vds/.env` contains `VDS_USERNAME`, `VDS_PASSWORD`, and `OPENAI_API_KEY`
-
-## Workflow Overview
-
-```
-research (gather evidence)
-    ↓
-spec (create/validate spec)
-    ↓
-audit (execute validation)
-```
-
-## Step 1: Gather Evidence with Research
-
-Run a targeted research query to collect evidence for the feature or gap you need to address.
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli research search "hexagonal architecture compliance patterns"
-```
-
-Expected output:
-
-```
-[research] Query: hexagonal architecture compliance patterns
-[research] Sources found: 12
-[research] Top result: https://example.com/hexagonal-guide
-[research] Evidence saved to: /tmp/vds-research-evidence-<timestamp>.json
-```
-
-Score the evidence quality before proceeding:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli research score --evidence /tmp/vds-research-evidence-<timestamp>.json
-```
-
-Expected output:
-
-```
-[score] Total evidence items: 12
-[score] High quality: 8
-[score] Medium quality: 3
-[score] Low quality: 1
-[score] Average score: 0.78
-```
-
-## Step 2: Create or Validate a Spec
-
-Use the spec orchestrator to create a new spec from the research evidence.
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli spec create hexagonal-compliance --evidence /tmp/vds-research-evidence-<timestamp>.json
-```
-
-Expected output:
-
-```
-[spec] Created: .gpt-5.4/specs/hexagonal-compliance/requirements.md
-[spec] Created: .gpt-5.4/specs/hexagonal-compliance/design.md
-[spec] Created: .gpt-5.4/specs/hexagonal-compliance/tasks.md
-[spec] Next: run validation
-```
-
-Validate the spec triplet:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli spec validate --spec-dir .gpt-5.4/specs/hexagonal-compliance
-```
-
-Expected output:
-
-```
-[validate] requirements.md: PASS
-[validate] design.md: PASS
-[validate] tasks.md: PASS
-[validate] 3/3 files valid
-```
-
-Run alignment checks:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli spec check-alignment --spec-dir .gpt-5.4/specs/hexagonal-compliance
-```
-
-## Step 3: Execute Audit Validation
-
-Run the audit orchestrator against the target repo using the validated spec.
-
-```bash
-./scripts/worktree_uv.sh run --project audit_orchestrator \
-  vds-cli audit run --repo vds-scripts --scope full --spec hexagonal-compliance
-```
-
-Expected output:
-
-```
-[audit] Profile: default
-[audit] Scope: full
-[audit] Spec: hexagonal-compliance
-[audit] Rules: 47
-[audit] Violations: 3
-[audit] Report: /tmp/vds-audit-report-<timestamp>.json
-```
-
-Generate a consolidated report:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli research report --evidence /tmp/vds-research-evidence-<timestamp>.json \
-  --audit /tmp/vds-audit-report-<timestamp>.json
-```
-
-## Troubleshooting
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| `research search` returns zero results | MCP router unavailable or Tavily quota exhausted | Run `vds-cli research health` to diagnose |
-| `spec validate` fails with missing FR | requirements.md has gaps | Add missing functional requirements and re-run |
-| `audit run` fails with `--spec not found` | Spec name mismatch | Use exact spec directory name, or omit `--spec` for default |
-| `check-alignment` reports drift | Design and tasks are out of sync | Run `vds-cli spec consolidate` then re-check |