@ngocsangairvds/vsaf 4.0.5 → 4.0.7

package/skills/vds-skill/vds-scripts/docs/agents/reference/backup-restore.md

@@ -0,0 +1,132 @@
+<!-- diátaxis: reference -->
+# Backup & Restore
+
+## What Gets Backed Up
+
+| Store | Criticality | Backup Method | Recovery Point |
+|-------|-------------|---------------|----------------|
+| **PostgreSQL** | **CRITICAL** | `pg_dump --schema=<s>` per schema, custom format | Per-backup |
+| **Redis** | Medium | `BGSAVE` → RDB file | Point-in-time at backup |
+| **Qdrant** | Medium | Snapshot API (`POST /snapshots`) | Point-in-time at backup |
+| **Logs** | Low | Rotated (10MB × 3 per container) | Ephemeral |
+| **Celery** | Low | Re-enqueued from scheduler | Ephemeral |
+
+## Backup
+
+```bash
+# Full backup (PostgreSQL + Redis + Qdrant)
+bash scripts/backup.sh
+
+# Single schema only
+bash scripts/backup.sh --schema memory
+
+# Skip Redis/Qdrant (DB-only)
+bash scripts/backup.sh --no-redis --no-qdrant
+```
+
+Backups land in `docker/backups/<YYYY-MM-DDTHHMMSS>/` with:
+- `audit_state.dump`, `memory.dump`, `sched.dump`, `progress.dump`, `dbos.dump`
+- `schema_ddl.sql` (DDL-only, no data — for DR schema reconstruction)
+- `redis-dump.rdb`
+- `manifest.txt`
+
+Retention: keep last 7 daily; script warns at > 14.
+
+## Restore
+
+### PostgreSQL — Full Schema Restore
+
+```bash
+# 1. Stop dependent services
+docker compose -p vds-platform --profile full stop
+
+# 2. Restore a single schema (example: memory)
+BACKUP_DIR=docker/backups/<timestamp>
+docker exec -i vds-postgres pg_restore -U postgres -d vds_platform \
+  --schema=memory --clean --if-exists --no-owner --no-acl \
+  < "$BACKUP_DIR/memory.dump"
+
+# 3. Restore all schemas
+for f in "$BACKUP_DIR"/*.dump; do
+  schema=$(basename "$f" .dump)
+  docker exec -i vds-postgres pg_restore -U postgres -d vds_platform \
+    --schema="$schema" --clean --if-exists --no-owner --no-acl < "$f"
+done
+
+# 4. Run alembic to ensure version stamps match
+# (entrypoint auto-migrates on restart, or run explicitly)
+docker compose -p vds-platform \
+  -f docker/docker-compose.infra.yml \
+  -f docker/docker-compose.services.yml \
+  -f docker/docker-compose.cli.yml \
+  --profile memory run --rm --no-deps memory-api \
+  /opt/venv/bin/alembic -c /app/memory_orchestrator/alembic.ini upgrade head
+
+# 5. Restart services
+docker compose -p vds-platform --profile memory --profile scheduler up -d
+```
+
+### PostgreSQL — Point-in-Time Recovery (PITR)
+
+Advanced: `scheduler_orchestrator/scripts/dr/pitr-drill.sh` for WAL-based recovery.
+See that script for detailed instructions.
+
+### Redis
+
+```bash
+# 1. Stop memory-worker (Celery)
+docker compose -p vds-platform stop memory-worker
+
+# 2. Copy RDB into Redis data volume
+docker cp docker/backups/<timestamp>/redis-dump.rdb vds-redis:/data/dump.rdb
+docker exec vds-redis redis-cli SHUTDOWN NOSAVE
+
+# 3. Restart Redis (reads dump.rdb on start)
+docker compose -p vds-platform up -d redis
+docker compose -p vds-platform up -d memory-worker
+```
+
+### Qdrant
+
+Qdrant snapshots are stored inside the Qdrant storage directory. Recovery:
+
+```bash
+# 1. List snapshots
+curl http://localhost:6335/snapshots
+
+# 2. Restore from snapshot (via Qdrant UI or API)
+# See: https://qdrant.tech/documentation/concepts/snapshots/
+```
+
+## Machine Migration
+
+To move the entire VDS stack to new hardware:
+
+```bash
+# On OLD machine:
+bash scripts/backup.sh
+tar czf vds-backup-$(date '+%Y%m%d').tar.gz docker/backups/<latest>/
+
+# Copy the tarball to NEW machine:
+scp vds-backup-*.tar.gz user@new-host:/tmp/
+
+# On NEW machine:
+cd /path/to/vds-scripts
+tar xzf /tmp/vds-backup-*.tar.gz
+cp docker/infrastructure/.env.template ~/.vds/.env
+# Edit ~/.vds/.env with correct credentials
+bash scripts/deploy-bootstrap.sh
+
+# Restore data:
+# Stop services first, then follow the PostgreSQL restore steps above
+# for each .dump file in the extracted backup directory.
+```
+
+## Scheduling
+
+For automated daily backups, add a cron job or use the `/schedule` command:
+
+```bash
+# Daily at 2:17 AM (off-minute to avoid fleet-wide stampede)
+17 2 * * * cd /path/to/vds-scripts && bash scripts/backup.sh >> docker/backups/backup.log 2>&1
+```

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

@@ -0,0 +1,56 @@
+<!-- diátaxis: reference -->
+
+# Bitbucket Orchestrator
+
+> Interact with Bitbucket: clone repos, list branches, read file contents, check PRs, and trigger pipelines.
+
+## Scope
+
+**What this orchestrator does:**
+- Clone or mirror Git repositories from Bitbucket Cloud.
+- List branches and tags programmatically.
+- Read file contents at a specific commit or branch.
+- Check open pull requests and their statuses.
+- Trigger pipeline runs (build/test) via REST.
+
+**What it does NOT do:**
+- Does not merge pull requests or modify branch protection rules.
+- Does not provide full Bitbucket administration.
+
+**Primary users:** AI agents provisioning workspace clones; CI/CD pipelines for build triggers.
+
+## CLI Entry
+
+```bash
+vds-cli bitbucket --help
+vds-cli bitbucket-cli --help
+```
+
+## Key Commands
+
+| Command | Purpose | Common Flags |
+|---------|---------|-------------|
+| `clone` | Clone a repo locally | `--repo`, `--branch` |
+| `list-branches` | List refs in a repository | `--repo` |
+| `read-file` | Get file content at a path | `--repo`, `--path`, `--branch` |
+| `list-prs` | Show open pull requests | `--repo`, `--state` |
+| `trigger-pipeline` | Run a pipeline step | `--repo`, `--branch`, `--step` |
+| `archive` | Download repo archive | `--repo`, `--format` |
+
+## Common Workflows
+
+### Workflow 1: Workspace Bootstrap
+1. List available repos: `vds-cli bitbucket list-repos --workspace=WHO-project`.
+2. Clone target repo: `vds-cli bitbucket clone --repo=vds-scripts --branch=master`.
+3. Verify with `vds-cli bitbucket read-file --repo=vds-scripts --path=AGENTS.md`.
+
+### Workflow 2: Audit Evidence Download
+1. Query PRs for a checkpoint: `vds-cli bitbucket list-prs --repo=vds-scripts --state=MERGED`.
+2. Download specific source files at commit: `vds-cli bitbucket read-file --repo=vds-scripts --path=src/vds_cli/router.py --branch=master`.
+3. Attach downloaded files to Confluence audit pages.
+
+## Related
+
+- **Orchestrators:** [git](git-orchestrator.md), [confluence](confluence-orchestrator.md), [audit](audit-triage-playbook.md)
+- **Skills:** [gitnexus-exploring](../../../../vds-skills/skills/gitnexus-exploring/SKILL.md)
+- **Bitbucket:** https://bitbucket.digital.vn/WHO-project/vds-scripts

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

@@ -0,0 +1,52 @@
+<!-- diátaxis: reference -->
+
+# BRD Orchestrator
+
+> Business Requirements Document generation and validation.
+
+## Scope
+
+- **Does:** Generate BRDs from specs, validate requirements completeness, track sign-offs, and export to PDF/Confluence.
+- **Does NOT:** Write requirements from scratch, replace product management tools, or make business decisions.
+- **Primary users:** AI agents (doc generation), product owners, business analysts.
+
+## CLI Entry
+
+```bash
+# Via unified router
+vds-cli brd --help
+
+# Direct entry
+vds-cli brd --help
+```
+
+## Key Commands
+
+| Command | Purpose | Common Flags |
+|---------|---------|-------------|
+| `generate` | Generate BRD from spec | `--spec`, `--output` |
+| `validate` | Validate completeness | `--input` |
+| `track` | Track sign-offs | `--brd-id`, `--status` |
+| `export` | Export to PDF/Confluence | `--input`, `--format` |
+
+## Common Workflows
+
+### Workflow: Generate BRD from Spec
+
+1. Ensure spec is validated: `vds-cli spec validate .gpt-5.4/specs/my-spec`
+2. Run `vds-cli brd generate --spec .gpt-5.4/specs/my-spec --output brd.md`
+3. Review generated BRD
+4. Export: `vds-cli brd export --input brd.md --format pdf`
+
+## Related
+
+- **Orchestrators:** [spec](spec-orchestrator.md), [pdf](pdf-orchestrator.md), [confluence](cli-commands.md)
+- **Confluence:** [WHO BRD](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/capability-coverage-review.md

@@ -0,0 +1,51 @@
+<!-- diátaxis: reference -->
+
+# Capability Coverage Review
+
+This review compares the implemented WHO ecosystem alignment changes against the current capability inventory.
+
+## Coverage status
+
+### Covered by platform skill and routing docs
+
+- bootstrap and discovery command families
+- integration command families
+- documentation and validation command families
+- development and workflow command families
+- specialist skill routing guidance
+- canonical WHO ownership model for skills and scripts
+- human and AI onboarding/routing docs
+
+### Covered by capability inventory
+
+- routed command surfaces
+- standalone workspace capabilities such as markdown, hexagonal, MCP, and multi-agent support
+- shared/internal support layers such as `vds_cli_common`
+- skills-catalog linkage
+- derived/generated surfaces
+
+### Covered by skills-catalog alignment
+
+- updated `vds-scripts-skill` role and metadata
+- updated `llm-analysis-skill` catalog description
+- updated skills-catalog guidance for platform routing
+
+## Deferred to controlled root-level step
+
+These items are intentionally not finalized inside the isolated repo worktrees:
+
+- root generated `AGENTS.md` sync
+- monorepo-root execution of `verify-alignment.sh`
+- any root-surface updates that would escape the two isolated repo worktrees
+
+## Conclusion
+
+The worktree-local implementation covers the spec's repo-local skills/docs/routing requirements.
+The remaining completion items are the controlled generated-surface sync and monorepo-root alignment verification step.
+
+## Related Documents
+
+- [VDS CLI Reference](vds-cli-reference.md)
+- [Orchestrator Index](orchestrator-index.md)
+- [Skills Reference](skills-reference.md)
+- [Confluence Hub](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation)

package/skills/vds-skill/vds-scripts/docs/agents/reference/ci-workflows.md

@@ -0,0 +1,98 @@
+<!-- diátaxis: reference -->
+# VDS CI/CD Workflows — Operational Contract
+
+> Continuous Integration pipeline contract for WHO-project/vds-scripts.
+
+## Overview
+
+All CI runs on `ubuntu-latest` via GitHub Actions. Jobs are split by concern: lint/type/test gate, doc quality gate, Confluence evidence, scheduler health, and Confluence sync on push.
+
+## Workflow Catalog
+
+| File | Name | Trigger | Purpose |
+|------|------|---------|---------|
+| `lint-and-test.yml` | Lint, Type, Test & Standardize | Push | `uv sync`, `pytest`, `ruff check`, `mypy` |
+| `docs-quality.yml` | Docs Quality Gate | `docs/**` PR paths | `score_all_docs()` + `validate_docs()` |
+| `docs-confluence-evidence.yml` | Docs Confluence Evidence Log | Schedule | Daily snapshot of freshness + quality scores |
+| `chaos-smoke.yml` | Chaos Smoke — Scheduler Orchestrator | Manual | Chaos & resilience testing, scheduler restart validation |
+| `scheduler-load-smoke.yml` | Scheduler Load Smoke (1-min) | Push | 60-second `/health` smoke in stub mode |
+| `confluence-sync.yml` | Confluence Sync | Push | Sync docs to Confluence on `docs/**` changes |
+
+### Lint, Type, Test & Standardize
+
+- **Trigger**: Every push
+- **Steps**:
+  1. Checkout
+  2. `uv sync --all-packages`
+  3. `pytest` (unit + integration)
+  4. `ruff check --fix`
+  5. `mypy` strict mode
+- **Failure**: Blocks PR merge via branch protection
+
+### Docs Quality Gate
+
+- **Trigger**: PR touching `docs/**` or `vds_cli/src/vds_cli/docs_cmd.py`
+- **Checks**:
+  - `score_all_docs(Path('.'))` — average must be ≥ 0.6
+  - `validate_docs(..., check_vi=True, check_diataxis=True, cross_repo=True, check_orchestrators=True, check_skills=True)` — zero issues
+- **Failure**: Annotates PR with `::error::` markers
+
+### Docs Confluence Evidence Log
+
+- **Trigger**: Daily cron (UTC 06:00)
+- **Output**: JSONL in `docs/.confluence-evidence/` — one line per doc with score and timestamp
+- **Monitoring**: Viewed via `vds-cli docs quality-score --format json`
+
+### Chaos Smoke
+
+- **Trigger**: Manual (`workflow_dispatch`)
+- **Scope**: Restart scheduler containers, verify DBOS re-registration, check event-bus recovery
+- **Duration**: ~5 minutes per run
+- **On failure**: Open incident in `scheduler_orchestrator/docs/runbooks/`
+
+### Scheduler Load Smoke
+
+- **Trigger**: Push
+- **Scope**: FastAPI `/health` endpoint, no DB required
+- **Timeout**: 60 seconds
+- **On failure**: Blocks PR (treated as critical path)
+
+### Confluence Sync
+
+- **Trigger**: Push to `main`
+- **Scope**: Syncs `docs/agents/reference/` and selected how-tos to Confluence space
+- **Requires**: `CONFLUENCE_INTERNAL_TOKEN` in repository secrets
+- **Dry-run**: `vds-cli docs confluence-sync --dry-run`
+
+## Alert Matrix
+
+| Workflow | On Failure | Owner |
+|----------|-----------|-------|
+| lint-and-test | PR blocked, Slack #builds | Feature author |
+| docs-quality | PR annotated, merge blocked | Docs maintainer |
+| docs-confluence-evidence | Incident log in `docs/.confluence-evidence/` | Ops rotation |
+| chaos-smoke | Severity-1 if scheduler down > 2 min | Scheduler on-call |
+| scheduler-load-smoke | PR blocked | Feature author |
+| confluence-sync | Silent failure (log only) | Docs automation |
+
+## Key Files Watched
+
+```
+docs/**                          — docs-quality, confluence-sync
+vds_cli/src/vds_cli/docs*        — docs-quality
+.github/workflows/*.yml          — lint-and-test (self-protect)
+scheduler_orchestrator/**        — scheduler-load-smoke, chaos-smoke
+docker/**                        — lint-and-test (Dockerfile lint)
+```
+
+## Caveats
+
+- `confluence-sync.yml` runs on **every push to main**, not just doc changes; this is intentional for drift detection.
+- `chaos-smoke.yml` is **manual only**; automated chaos runs violate SLO during business hours.
+- `docs-quality.yml` skips on pushes (not PRs) to avoid noise on automated commit batches.
+
+## See Also
+
+- [infrastructure-v2.15](infrastructure-v2.15.md) — Container and healthcheck patterns
+- [ecosystem-daily-report](ecosystem-daily-report.md) — Daily metrics and health monitoring
+- `.github/workflows/` in repo root — Live workflow definitions

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

@@ -0,0 +1,55 @@
+<!-- diátaxis: reference -->
+
+# Circular Dependency Orchestrator
+
+> Detect and visualize circular dependencies in Python and JavaScript codebases.
+
+## Scope
+
+- **Does:** Analyze import graphs, detect cycles, generate visualizations, suggest break points, and export cycle reports.
+- **Does NOT:** Auto-fix cycles, analyze non-code dependencies, or replace architectural review.
+- **Primary users:** AI agents (code health), developers (refactoring planning), tech leads.
+
+## CLI Entry
+
+```bash
+# Via unified router
+vds-cli circular-dependency --help
+
+# Direct entry
+vds-circular-dependency --help
+```
+
+## Key Commands
+
+| Command | Purpose | Common Flags |
+|---------|---------|-------------|
+| `analyze` | Analyze repo for cycles | `--path`, `--language` |
+| `visualize` | Generate cycle graph | `--format`, `--output` |
+| `report` | Generate cycle report | `--output`, `--detail` |
+| `suggest` | Suggest break points | `--cycle-id` |
+
+## Common Workflows
+
+### Workflow: Detect and Fix Cycles
+
+1. Run `vds-cli circular-dependency analyze --path . --language python`
+2. Review detected cycles
+3. Visualize: `vds-cli circular-dependency visualize --format svg --output cycles.svg`
+4. Get suggestions: `vds-circular-dependency suggest --cycle-id 1`
+5. Refactor based on suggestions
+6. Re-run analysis to verify fix
+
+## Related
+
+- **Orchestrators:** [structure](structure-orchestrator.md), [hexagonal](hexagonal-orchestrator.md), [code-review](code-review-graph-skill.md)
+- **Skills:** [circular-dependency-skill](../../../../vds-skills/skills/circular-dependency-skill/SKILL.md)
+- **Confluence:** [WHO Circular Dependency](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 |