@ngocsangairvds/vsaf 3.2.16 → 4.0.0

package/tools/vds-scripts/docker/infrastructure/init-schemas.sql

@@ -1,143 +0,0 @@
--- =============================================================================
--- VDS Shared Infrastructure — Schema Initialization
--- =============================================================================
--- Phase: ecosystem-infrastructure-evolution P0
--- Created: 2026-04-25
---
--- This script creates schemas and roles for all VDS orchestrators.
--- It is idempotent — safe to run multiple times.
---
--- Schemas:
---   - memory: memory_orchestrator (mem0, evolution, analytics)
---   - sched: scheduler_orchestrator (DBOS schedules, events, chains)
---   - dbos: scheduler_orchestrator (DBOS system tables)
--- =============================================================================
-
--- =============================================================================
--- OWNERSHIP BOUNDARY (per ADR-INF-11, P4 v2.11.1)
--- =============================================================================
--- This file owns: schemas + roles + DBOS CREATE grant ONLY.
--- This file does NOT own: tables, indexes, functions, views, ENUMs, etc.
---
--- Per-service tables are owned by per-service Alembic environments:
---   - memory.* tables       -> memory_orchestrator/alembic/versions/
---   - sched.* tables        -> scheduler_orchestrator/alembic/versions/
---   - dbos.* tables         -> DBOS framework (system tables; CREATE granted to vds_sched_runtime)
---
--- This script runs ONCE at postgres container init (Docker entrypoint
--- /docker-entrypoint-initdb.d/01-schemas.sql); it does NOT re-run on
--- subsequent container restarts. Schema/role changes require a fresh
--- volume init (rare; coordinate with operator).
---
--- Adding tables here would create a divergent source-of-truth from the
--- per-service Alembic envs. DO NOT add CREATE TABLE statements to this file.
--- =============================================================================
-
--- v2.0.17 N.55: pre-install uuid-ossp extension so DBOS bootstrap (which issues
--- `CREATE EXTENSION IF NOT EXISTS "uuid-ossp"` at first launch) does NOT require
--- SUPERUSER privileges on every fresh container start. Pre-installing here lets
--- the future v2.0.18 least-privilege DSN switch (vds_sched_runtime) work; today
--- DBOS bootstrap runs as `postgres` superuser so `CREATE EXTENSION` succeeds
--- regardless, but pre-installing makes the privilege contract explicit and
--- forward-compatible.
-CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
-
--- Create schemas
-CREATE SCHEMA IF NOT EXISTS memory;
-CREATE SCHEMA IF NOT EXISTS sched;
-CREATE SCHEMA IF NOT EXISTS dbos;
-
--- Create roles (passwords are set via environment variables at runtime)
--- Note: In production, passwords should be managed via Docker secrets or vault
-
--- Role: memory_orchestrator application user
-DO $$
-BEGIN
-    CREATE ROLE vds_memory_app WITH LOGIN;
-EXCEPTION
-    WHEN duplicate_object THEN NULL;
-END
-$$;
-
--- Role: scheduler_orchestrator application user
-DO $$
-BEGIN
-    CREATE ROLE vds_scheduler_app WITH LOGIN;
-EXCEPTION
-    WHEN duplicate_object THEN NULL;
-END
-$$;
-
--- Role: DBOS scheduler runtime user
-DO $$
-BEGIN
-    CREATE ROLE vds_sched_runtime WITH LOGIN;
-EXCEPTION
-    WHEN duplicate_object THEN NULL;
-END
-$$;
-
--- v2.0.17 N.52: Role passwords for least-privilege DSN switch.
--- Without these ALTER ROLE statements, the roles exist with LOGIN but no
--- password — peer/trust auth via `docker exec psql -U <role>` works, but
--- TCP connections from other containers (the canonical deployment path)
--- fail with "password authentication failed". The passwords below are
--- DEFAULT DEV PASSWORDS for the local shared-infra bring-up. Operators MUST
--- rotate them via a separate post-init step in production:
---
---   docker exec vds-postgres psql -U postgres -c \
---     "ALTER ROLE vds_scheduler_app WITH PASSWORD '<production-secret>';"
---
--- and update the compose DATABASE_URL accordingly. The ecosystem-scheduling
--- spec (TSK-N.52 carryover) tracks the cross-orchestrator coordination
--- needed to migrate the canonical DSN from `postgres` superuser to
--- least-privilege role for all 4 schema owners.
-ALTER ROLE vds_memory_app    WITH PASSWORD 'dev_memory_pw';
-ALTER ROLE vds_scheduler_app WITH PASSWORD 'dev_scheduler_app_pw';
-ALTER ROLE vds_sched_runtime WITH PASSWORD 'dev_sched_runtime_pw';
-
--- v2.0.17 N.52: vds_sched_runtime needs database-level CREATE for DBOS
--- bootstrap (DBOS issues `CREATE SCHEMA "dbos"` without IF NOT EXISTS, which
--- requires db-level CREATE even when the schema already exists).
-GRANT CREATE ON DATABASE vds_platform TO vds_sched_runtime;
-
--- Grant schema usage
-GRANT USAGE ON SCHEMA memory TO vds_memory_app;
-GRANT USAGE ON SCHEMA sched TO vds_scheduler_app, vds_sched_runtime;
-GRANT USAGE ON SCHEMA dbos TO vds_sched_runtime;
-
--- Grant CREATE privilege on dbos schema for DBOS system tables
-GRANT USAGE, CREATE ON SCHEMA dbos TO vds_sched_runtime;
-
--- Grant ALL privileges on each schema to its owner role
-GRANT ALL PRIVILEGES ON SCHEMA memory TO vds_memory_app;
-GRANT ALL PRIVILEGES ON SCHEMA sched TO vds_scheduler_app, vds_sched_runtime;
-GRANT ALL PRIVILEGES ON SCHEMA dbos TO vds_sched_runtime;
-
--- Default privileges so future tables are auto-granted
-ALTER DEFAULT PRIVILEGES IN SCHEMA memory GRANT ALL ON TABLES TO vds_memory_app;
-ALTER DEFAULT PRIVILEGES IN SCHEMA memory GRANT ALL ON SEQUENCES TO vds_memory_app;
-ALTER DEFAULT PRIVILEGES IN SCHEMA sched GRANT ALL ON TABLES TO vds_scheduler_app, vds_sched_runtime;
-ALTER DEFAULT PRIVILEGES IN SCHEMA sched GRANT ALL ON SEQUENCES TO vds_scheduler_app, vds_sched_runtime;
-
--- Note: dbos schema uses USAGE, CREATE (not ALL) since DBOS manages its own objects
-
--- =============================================================================
--- v2.15.9 (P8 follow-up F20 close): no database-level search_path override
--- =============================================================================
--- Pre-P8, this database had `search_path = 'memory, public'` set at the database
--- level (a P0-leftover from when vds_platform was the memory-only DB). Post-P8,
--- search_path pinning happens in two places:
---   1. PgBouncer per-stanza `connect_query='SET search_path TO <schema>, public'`
---      (fires on backend SPAWN — see docker/infrastructure/pgbouncer/pgbouncer.ini)
---   2. Per-application connect-time SQL (SQLAlchemy `connect` event listener,
---      psycopg helper wrapper) for unqualified-DML resilience across PgBouncer
---      backend reuse — see references/connection-pooling.md F21/D1 caveats
---
--- A database-level default would silently override the per-stanza connect_query
--- value after `server_reset_query=DISCARD ALL` resets session state between
--- client checkouts in session mode (originally caught as F20 in v2.15.6 audit).
--- This RESET ensures fresh deploys never regress to the legacy default. The
--- statement is a no-op when search_path is already unset, so it's safe to
--- run on every fresh init.
-ALTER DATABASE vds_platform RESET search_path;

package/tools/vds-scripts/docker/infrastructure/pgbouncer/pgbouncer.ini

@@ -1,71 +0,0 @@
-; =============================================================================
-; VDS PgBouncer config — SESSION-mode pooling, per-database stanzas
-; ADR-INF-13 / FR-15 / ecosystem-infrastructure-evolution P8 (v2.15.3)
-; Pinned: edoburu/pgbouncer >= v1.24 (image v1.25.1-p0)
-;
-; Session mode (1:1 client:backend) preserves correctness for:
-;   - DBOS LISTEN/NOTIFY (scheduler_orchestrator event bus, dispatcher loop,
-;     chains, WS streams)
-;   - asyncpg full statement_cache_size=512 (memory_orchestrator)
-;   - WITH HOLD cursors, temp tables, application_name, query cancel
-;   - alembic pg_try_advisory_xact_lock (tx-scoped is a strict subset of
-;     what session mode permits)
-;
-; Future R12 escalation: per-stanza `pool_mode=transaction` override on
-; memory stanza if 90-day SHOW POOLS shows sustained cl_waiting>0.
-; Sched stays session-mode permanently.
-; =============================================================================
-
-[databases]
-; One stanza per VDS schema. `connect_query` runs ONCE per backend connection
-; at startup, pinning search_path before the pool hands the backend to a client.
-; (`options=` is NOT a valid per-stanza key in PgBouncer 1.24+; use `connect_query`.)
-vds_memory   = host=vds-postgres port=5432 dbname=vds_platform connect_query='SET search_path TO memory, public' pool_size=40
-vds_sched    = host=vds-postgres port=5432 dbname=vds_platform connect_query='SET search_path TO sched, public' pool_size=40
-
-[pgbouncer]
-listen_addr        = 0.0.0.0
-listen_port        = 6432
-auth_type          = scram-sha-256
-auth_file          = /etc/pgbouncer/userlist.txt
-; auth_query runs as auth_user (NOT the connecting client). Without auth_user,
-; PgBouncer attempts pg_shadow lookups using the client's own credentials —
-; works only when client is superuser. Since we may add non-superuser DSNs
-; later, pin auth_user to the dedicated pgbouncer_auth role (created at deploy
-; time per ROLLBACK.md §P8 First-Time Deploy Prerequisites).
-auth_user          = pgbouncer_auth
-auth_query         = SELECT usename, passwd FROM pg_shadow WHERE usename=$1
-; FR-224.7 hardening: pin auth_query to a real DB. Without this, pgbouncer
-; 1.18+ uses the *connecting* db as auth_dbname; when a client connects to
-; the special `pgbouncer` admin DB (e.g. the healthcheck's `psql -d pgbouncer`),
-; the lookup fails with "cannot use the reserved 'pgbouncer' database as an
-; auth_dbname". `vds_memory` is one of the 4 stanzas defined above and routes
-; to the underlying vds_platform DB where pg_shadow lives.
-auth_dbname        = vds_memory
-admin_users        = pgbouncer_admin
-stats_users        = pgbouncer_stats
-pool_mode          = session
-max_client_conn    = 500
-default_pool_size  = 40
-min_pool_size      = 5
-max_prepared_statements = 200
-server_reset_query = DISCARD ALL
-server_reset_query_always = 0
-server_idle_timeout = 600
-server_lifetime    = 3600
-; v2.15.12: trimmed to `extra_float_digits` only (Postgres standard parameter
-; many drivers send by default — not legacy compat).
-;   - `options` was added pre-P8 for clients sending DSN-URL `?options=-c
-;     search_path=...` query fragments. v2.15.x retired URL-options in favor
-;     of per-stanza `connect_query` pinning + per-app post-handshake SET.
-;     No active code sends `options` as a startup parameter post-v2.15.10.
-;   - `search_path` was added in v2.15.8 first-attempt fix when memory-api
-;     used asyncpg `server_settings={"search_path": ...}` (StartupMessage
-;     route). v2.15.8 robust fix replaced that with SQLAlchemy `connect`
-;     event listener (post-handshake SET). The allowlist entry was retained
-;     "in case other libraries use it" — removed v2.15.12 per no-legacy
-;     directive. Verified zero `unsupported startup parameter` rejections
-;     in PgBouncer logs pre-removal.
-ignore_startup_parameters = extra_float_digits
-log_pooler_errors  = 1
-stats_period       = 60

package/tools/vds-scripts/docker/infrastructure/pgbouncer/userlist.txt

@@ -1,50 +0,0 @@
-; =============================================================================
-; VDS PgBouncer userlist — DEPLOY-TIME GENERATION REQUIRED
-; =============================================================================
-; This file is committed as a STUB so the docker compose volume mount succeeds
-; on first `up -d` (Docker bind-mount auto-creates missing source paths as
-; DIRECTORIES, which would crash pgbouncer with "auth_file: not a regular file").
-;
-; BEFORE FIRST DEPLOY, replace this file's contents with real password hashes
-; for the 3 PgBouncer-level users (admin, stats, auth). Run from project root:
-;
-;   # 1. Create the 3 PgBouncer users (one-time, idempotent):
-;   docker exec vds-postgres psql -U postgres -c "
-;     DO \$\$ BEGIN
-;       CREATE USER pgbouncer_admin WITH PASSWORD '$PGBOUNCER_ADMIN_PASSWORD';
-;     EXCEPTION WHEN duplicate_object THEN ALTER USER pgbouncer_admin
-;       WITH PASSWORD '$PGBOUNCER_ADMIN_PASSWORD'; END \$\$;
-;     -- Repeat for pgbouncer_stats and pgbouncer_auth (with their own passwords)
-;     GRANT pg_read_all_settings TO pgbouncer_stats;
-;   "
-;
-;   # 2. Generate userlist.txt from pg_shadow:
-;   docker exec vds-postgres psql -U postgres -t -A -c "
-;     SELECT '\"' || usename || '\" \"' || passwd || '\"'
-;     FROM pg_shadow
-;     WHERE usename IN ('postgres','pgbouncer_admin','pgbouncer_stats','pgbouncer_auth')
-;       AND passwd IS NOT NULL
-;   " > docker/infrastructure/pgbouncer/userlist.txt
-;
-;   # 3. Verify file is non-empty + has 4 lines:
-;   wc -l docker/infrastructure/pgbouncer/userlist.txt
-;
-;   # 4. Then bring up pgbouncer:
-;   docker compose -f docker/docker-compose.infra.yml --profile infra up -d vds-pgbouncer
-;
-; The `auth_query` in pgbouncer.ini handles per-service password lookup at
-; runtime; only the 3 bootstrap users + postgres need entries here.
-;
-; SECURITY NOTE: this stub will be tracked in git so the volume mount works.
-; Once you run the generation, the real password hashes will appear as a
-; modified-file diff. Use `git update-index --skip-worktree
-; docker/infrastructure/pgbouncer/userlist.txt` to keep them out of git
-; without removing the stub from tracking.
-; =============================================================================
-
-; Placeholder line so this file is a valid non-empty file for Docker mount.
-; PgBouncer will read this on startup and find no real users until you replace
-; this content. The healthcheck will FAIL until step 2 above runs and the file
-; gets real password hashes.
-
-"placeholder_user" "REPLACE_BEFORE_DEPLOY_runs_pg_shadow_query_per_userlist_template"

package/tools/vds-scripts/docker/infrastructure/pgbouncer/userlist.txt.template

@@ -1,36 +0,0 @@
-; =============================================================================
-; VDS PgBouncer userlist.txt TEMPLATE
-; =============================================================================
-; This file is a TEMPLATE. The real `userlist.txt` (no `.template` suffix)
-; must be generated by an init script at deploy time and is NEVER committed.
-;
-; Format: "username" "password-hash"
-;   - username : matches Postgres role (or pgbouncer_admin/pgbouncer_stats)
-;   - password-hash : SCRAM-SHA-256 hash from pg_shadow.passwd
-;
-; Generation pattern (run once at deploy time):
-;   docker exec vds-postgres psql -U postgres -t -A -c \
-;     "SELECT '\"' || usename || '\" \"' || passwd || '\"' \
-;      FROM pg_shadow \
-;      WHERE usename IN ('postgres','pgbouncer_admin','pgbouncer_stats','pgbouncer_auth') \
-;        AND passwd IS NOT NULL" \
-;     > docker/infrastructure/pgbouncer/userlist.txt
-;
-; The `pgbouncer_admin`, `pgbouncer_stats`, `pgbouncer_auth` users must be
-; created in Postgres before generating userlist.txt:
-;
-;   CREATE USER pgbouncer_admin WITH PASSWORD '<strong-password>';
-;   CREATE USER pgbouncer_stats WITH PASSWORD '<strong-password>';
-;   CREATE USER pgbouncer_auth WITH PASSWORD '<strong-password>';
-;   GRANT pg_read_all_settings TO pgbouncer_stats;
-;
-; The `auth_query` in pgbouncer.ini handles per-service password lookup
-; transparently — only the bootstrap admin/stats/auth users need entries here.
-;
-; The actual `userlist.txt` file is gitignored and stays out of version control.
-; =============================================================================
-
-; Example format (DO NOT use these placeholder hashes; generate real ones):
-; "pgbouncer_admin" "SCRAM-SHA-256$4096:placeholder-salt$placeholder-stored:placeholder-server-key"
-; "pgbouncer_stats" "SCRAM-SHA-256$4096:placeholder-salt$placeholder-stored:placeholder-server-key"
-; "pgbouncer_auth"  "SCRAM-SHA-256$4096:placeholder-salt$placeholder-stored:placeholder-server-key"

package/tools/vds-scripts/docs/.confluence-evidence/PREFLIGHT.md

@@ -1,132 +0,0 @@
-# Docs Confluence Evidence — Pre-flight Checklist
-
-A maintainer walks through this checklist before flipping `ALLOW_EVIDENCE_PUSH=true`
-in [`../../.github/workflows/docs-confluence-evidence.yml`](../../.github/workflows/docs-confluence-evidence.yml).
-For the runtime description of what the workflow writes, see the sibling
-[`README.md`](./README.md).
-
----
-
-## 1. Why the flag exists
-
-`ALLOW_EVIDENCE_PUSH` is the one-line kill switch between "workflow runs daily
-and records evidence as a workflow artifact" (safe, read-only) and "workflow
-also commits and pushes the snapshot to the default branch" (mutates history).
-It exists because scheduled workflows pushing to a protected default branch is
-organization-policy-dependent and the wrong default for a freshly-landed
-workflow — we want observable runs before we trust auto-commits.
-
----
-
-## 2. Organization policy checks
-
-Verify each item before enabling push. Each bullet names the concern plus a
-one-liner for how to verify it.
-
-- **Scheduled-workflow push permissions** — org may block `GITHUB_TOKEN` from
-  pushing on `schedule` triggers.
-  *Verify:* Org Settings → Actions → General → "Workflow permissions" shows
-  "Read and write" for the repo, or repo-level override is enabled.
-- **Protected-branch rules on default branch** — a branch-protection rule may
-  reject direct pushes from the bot identity.
-  *Verify:* Repo Settings → Branches → rule for default branch; confirm either
-  bypass for `github-actions[bot]` or that "Restrict who can push" excludes it.
-- **Required status checks** — required checks on the default branch will
-  block the bot's push if the evidence commit is expected to satisfy them.
-  *Verify:* Same Branch rule panel; confirm required checks list does not
-  include checks that can only run on PRs.
-- **Code-owner approvals** — CODEOWNERS-enforced review on `docs/**` would
-  require a human approval on every bot commit.
-  *Verify:* `grep -R 'docs/\.confluence-evidence' CODEOWNERS .github/CODEOWNERS`
-  returns no required-review owners, OR the bot identity is exempted.
-- **Signed-commit requirement** — if the branch demands signed commits, native
-  `git commit` from the runner will be rejected (the previous third-party
-  action did not sign either — see limitations below).
-  *Verify:* Branch rule panel → "Require signed commits" is OFF, or wire up a
-  commit-signing step before enabling push.
-
----
-
-## 3. Workflow self-test (push still disabled)
-
-Walk through this with `ALLOW_EVIDENCE_PUSH=false` before flipping it to true.
-
-1. Actions tab → "Docs Confluence Evidence Log" → "Run workflow" → `main`.
-2. Wait for the run to finish green. The commit step must be **skipped** (grey),
-   not executed.
-3. On the run page, confirm the `docs-confluence-evidence-<date>` artifact is
-   attached. Download and inspect it — it should contain a single
-   `<date>.json` with a `validate` and `quality_score` object.
-4. Confirm the workflow **Summary** tab shows validator status, issue count,
-   and quality-score average.
-5. Only after two or three healthy manual runs: flip `ALLOW_EVIDENCE_PUSH` to
-   `'true'` in the workflow `env:` block (or define repo variable
-   `ALLOW_EVIDENCE_PUSH=true`).
-6. Re-run `workflow_dispatch`. The commit step should now run and produce a
-   commit on the default branch. Inspect the commit — it must only touch
-   `docs/.confluence-evidence/<date>.json`.
-
----
-
-## 4. Retention & pruning — TODO
-
-`docs/.confluence-evidence/` grows one JSON per day unbounded once push is
-enabled. At ~5-30 KB/file that is manageable for a year, but the directory
-will eventually bloat the repo and slow `git clone`.
-
-**TODO (before enabling push for >90 days):** add a pruning workflow.
-Suggested filename and shape:
-
-- `.github/workflows/confluence-evidence-prune.yml`
-- Schedule: quarterly (`0 4 1 */3 *`) or monthly with a 90-day retention
-  window.
-- Logic: `find docs/.confluence-evidence -name '*.json' -mtime +90 -delete`
-  then commit + push using the same native-git pattern as this workflow.
-- Alternative: keep the newest N daily snapshots plus month-end snapshots.
-
-Do not enable push without a pruning plan filed as a follow-up issue.
-
----
-
-## 5. Rollback
-
-If an enabled push causes issues (bad commits, branch-protection violations,
-noisy history):
-
-1. **Disable immediately.** Flip the flag back:
-   `env: ALLOW_EVIDENCE_PUSH: 'false'` in
-   [`../../.github/workflows/docs-confluence-evidence.yml`](../../.github/workflows/docs-confluence-evidence.yml),
-   merge as a hotfix. (Repository-variable override takes effect on the next
-   run without a code change.)
-2. **Delete offending snapshots.** Single targeted commit:
-   `git rm docs/.confluence-evidence/<dates>.json && git commit -m "revert(docs): drop bad evidence snapshots"`.
-   Do not rewrite history unless the branch allows it.
-3. **Confirm quiet.** Re-run the workflow via `workflow_dispatch` with the
-   flag off. The run should upload the artifact and skip the commit step — a
-   quiet no-op against the repo.
-4. Only re-enable after addressing the root cause and re-walking sections 2–3.
-
----
-
-## 6. Observability
-
-Where evidence from a healthy run shows up:
-
-- **GitHub Actions run logs** — Actions tab → "Docs Confluence Evidence Log"
-  → pick a run. Each step emits `validator status:` / `quality average:`
-  lines.
-- **Workflow step summary** — "Summary" tab on the run page renders a
-  markdown table with validator status, issue count, and quality-score
-  average for that date.
-- **Workflow artifact** — `docs-confluence-evidence-<date>` artifact is
-  retained for 90 days and contains the raw JSON snapshot.
-- **Repo files (once push is enabled)** — `docs/.confluence-evidence/<date>.json`
-  is a dated snapshot. A healthy snapshot has:
-  - `validate.status == "pass"` and `validate.issue_count == 0` (or a small,
-    steady-state non-blocking count).
-  - `quality_score.average` is a number in the expected band (compare
-    against the prior day's file).
-  - `generated_at` is within an hour of the 03:00 UTC scheduled trigger.
-
-Cross-reference: sibling [`README.md`](./README.md) describes the snapshot
-shape and downstream reviewers' expectations.

package/tools/vds-scripts/docs/.confluence-evidence/README.md

@@ -1,84 +0,0 @@
-# Confluence Evidence Log
-
-Runtime proof that the VDS docs health gates (validator + quality score) are
-running outside of PR-time checks. Populated daily by the
-[`docs-confluence-evidence.yml`](../../.github/workflows/docs-confluence-evidence.yml)
-GitHub Actions workflow.
-
-This is **validation-only evidence** — the workflow does not invoke actual
-Confluence sync (sync requires secrets and could mutate pages). The purpose is
-to answer the question *"is our docs pipeline healthy today?"* without needing
-a human to open a PR.
-
-## Filename convention
-
-```
-docs/.confluence-evidence/YYYY-MM-DD.json
-```
-
-One snapshot per UTC calendar day. The workflow runs at `03:00 UTC`.
-
-## Snapshot schema
-
-Each file is a JSON object with the following shape:
-
-```json
-{
-  "generated_at": "2026-04-23T03:00:12+00:00",
-  "date": "2026-04-23",
-  "workflow": "docs-confluence-evidence",
-  "validate": {
-    "status": "pass",
-    "issue_count": 0,
-    "issues": []
-  },
-  "quality_score": {
-    "average": 0.78,
-    "docs": {
-      "docs/README.md": { "total": 0.82, "...": "..." }
-    }
-  }
-}
-```
-
-### How to interpret a snapshot
-
-- `validate.status` — `pass` means the day's run of `vds-cli docs validate`
-  with `--check-vi --check-diataxis --check-orchestrators --check-skills`
-  returned zero issues. `fail` means issues were detected; the first 50 are
-  captured in `validate.issues`.
-- `validate.issue_count` — total issues (not capped at 50).
-- `quality_score.average` — corpus-wide average doc quality score; the PR gate
-  in `docs-quality.yml` enforces `>= 0.6`.
-- `quality_score.docs` — per-document scores. Useful for spotting slow drift
-  even when the average is still above the threshold.
-
-A `status: error` in `validate` (or `average: null`) means the evidence step
-itself failed to run — inspect the workflow logs for that day.
-
-## Retention
-
-**TODO**: add a pruning workflow that deletes snapshots older than 90 days.
-For now, snapshots accumulate. Each file is small (< 50 KB) so the immediate
-cost is low, but we should not let the directory grow unbounded.
-
-GitHub Actions artifact uploads (see the `Upload evidence artifact` step in
-the workflow) already use a 90-day retention; the in-repo copy is the
-long-lived audit trail.
-
-## Why the directory is git-tracked but starts empty
-
-The `.gitkeep` file ensures the directory exists before any real evidence has
-landed. The commit-back step of the workflow is **disabled by default**
-(`ALLOW_EVIDENCE_PUSH=false`) because pushing from scheduled workflows is
-org-policy-dependent. Enable it by setting the repository variable
-`ALLOW_EVIDENCE_PUSH=true` once the policy is confirmed.
-
-Until commit-back is enabled, daily evidence is still produced — just as a
-workflow artifact instead of a committed file.
-
-## See also
-
-- Workflow: [`.github/workflows/docs-confluence-evidence.yml`](../../.github/workflows/docs-confluence-evidence.yml)
-- PR-time gate: [`.github/workflows/docs-quality.yml`](../../.github/workflows/docs-quality.yml)
-- Spec gap: `.gpt-5.4/specs/ARCHIVE/who-project-documentation-enhancement/tasks.md` (Gap 3 — Confluence auto-sync runtime proof)

package/tools/vds-scripts/docs/.confluence.yaml

@@ -1,157 +0,0 @@
-bitbucket:
-  base_url: http://bitbucket.digital.vn
-  project: WHO
-  server: internal
-pages:
-- description: Top-level navigation hub linking to all repos and child pages
-  lang: en
-  page_id: '98997962'
-  source_files:
-  - AGENTS.md
-  - llms.txt
-  template: navigation_hub
-  title: WHO-Project Ecosystem Documentation
-  type: navigation_hub
-- bitbucket_links:
-  - label: vds-scripts README
-    path: README.md
-  - label: Bootstrap Guide
-    path: docs/agents/how-to/install-and-bootstrap-who-scripts-and-skills.md
-  description: Step-by-step setup for new developers
-  lang: en
-  page_id: '98997963'
-  source_files:
-  - AGENTS.md
-  - README.md
-  template: installation_guide
-  title: Ecosystem Installation Guide
-  type: hybrid_guide
-- bitbucket_links:
-  - label: Full CLI Reference
-    path: docs/agents/reference/cli-commands.md
-  - label: Orchestrator Architecture
-    path: docs/agents/reference/orchestrator-architecture.md
-  description: CLI surface, orchestrators, testing rules
-  lang: en
-  page_id: '98997964'
-  source_files:
-  - AGENTS.md
-  - docs/agents/reference/cli-commands.md
-  template: quick_reference
-  title: vds-scripts Quick Reference
-  type: quick_reference
-- bitbucket_links:
-  - label: Full Registry
-    path: registry.yaml
-  - label: Add a Skill Guide
-    path: docs/agents/how-to/add-a-skill.md
-  description: Skill registry, authoring workflow, alignment
-  lang: en
-  page_id: '98997965'
-  repo: vds-skills
-  source_files:
-  - AGENTS.md
-  - registry.yaml
-  template: quick_reference
-  title: vds-skills Quick Reference
-  type: quick_reference
-- bitbucket_links:
-  - label: Packaging Guide
-    path: README.md
-  - label: Deploy Script
-    path: scripts/deploy.sh
-  description: Hooks, plugins, deploy workflow
-  lang: en
-  page_id: '98997966'
-  source_files:
-  - AGENTS.md
-  - README.md
-  template: quick_reference
-  title: vds-claude-plugins Quick Reference
-  type: quick_reference
-- description: Auto-generated validation and freshness status
-  generated: true
-  lang: en
-  page_id: '98997968'
-  source_files:
-  - docs/agents/reference/health-dashboard.md
-  - docs/.freshness.yaml
-  template: health_dashboard
-  title: Documentation Health Dashboard
-  type: health_dashboard
-- bitbucket_links:
-  - label: Tài liệu vds-scripts
-    path: docs/vi/agents/README.md
-  - label: Hướng dẫn cài đặt
-    path: docs/vi/agents/how-to/install-and-bootstrap-who-scripts-and-skills.md
-  description: Cài đặt hệ sinh thái WHO-project
-  lang: vi
-  page_id: '99846963'
-  source_files:
-  - AGENTS.vi.md
-  - docs/vi/agents/how-to/install-and-bootstrap-who-scripts-and-skills.md
-  template: installation_guide
-  title: Hướng dẫn cài đặt hệ sinh thái
-  type: hybrid_guide
-- bitbucket_links:
-  - label: Tài liệu vds-scripts
-    path: docs/vi/agents/README.md
-  - label: Hướng dẫn sử dụng vds-ai-memory
-    path: docs/vi/agents/how-to/02-using-vds-ai-memory.md
-  description: Tài liệu tham khảo CLI
-  lang: vi
-  page_id: '99846964'
-  source_files:
-  - AGENTS.vi.md
-  template: quick_reference
-  title: Tài liệu tham khảo vds-scripts
-  type: quick_reference
-- bitbucket_links:
-  - label: Registry Đầy đủ
-    path: registry.yaml
-  - label: Hướng dẫn Thêm Skill
-    path: docs/vi/agents/how-to/add-a-skill.md
-  description: Registry và workflow
-  lang: vi
-  page_id: '99846965'
-  repo: vds-skills
-  source_files:
-  - AGENTS.vi.md
-  - registry.yaml
-  template: quick_reference
-  title: Tài liệu tham khảo vds-skills
-  type: quick_reference
-- bitbucket_links:
-  - label: Packaging Guide
-    path: README.md
-  - label: Deploy Script
-    path: scripts/deploy.sh
-  description: Hook, plugin và quy trình deploy
-  lang: vi
-  page_id: '99846966'
-  source_files:
-  - AGENTS.vi.md
-  - README.md
-  template: quick_reference
-  title: Tài liệu tham khảo vds-claude-plugins
-  type: quick_reference
-parent_page_id: '57250660'
-repos:
-- active: true
-  description: Core WHO scripts — CLI, orchestrators, validation
-  name: vds-scripts
-  slug: vds-scripts
-- active: true
-  description: Skill registry and authoring framework
-  name: vds-skills
-  slug: vds-skills
-- active: false
-  description: vds-claude-plugins merged into vds-skills (2026-04-22). Content maintained in vds-skills repo.
-  name: vds-claude-plugins
-  slug: vds-claude-plugins
-- active: false
-  description: AI memory system (active, tracked separately at .gpt-5.4/specs/vds-ai-memory/)
-  name: vds-ai-memory
-  slug: vds-ai-memory
-space_key: TTCN24
-confluence_url: http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation