@ngocsangairvds/vsaf 4.1.8 → 4.1.9

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

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

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

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

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

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

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