@ngocsangairvds/vsaf 4.0.6 → 4.0.7

package/skills/vds-skill/vds-scripts/docker/infrastructure/pgbouncer/userlist.txt

@@ -0,0 +1,50 @@
+; =============================================================================
+; 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/skills/vds-skill/vds-scripts/docker/infrastructure/pgbouncer/userlist.txt.template

@@ -0,0 +1,36 @@
+; =============================================================================
+; 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/skills/vds-skill/vds-scripts/docs/.confluence-evidence/PREFLIGHT.md

@@ -0,0 +1,132 @@
+# 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/skills/vds-skill/vds-scripts/docs/.confluence-evidence/README.md

@@ -0,0 +1,84 @@
+# 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/skills/vds-skill/vds-scripts/docs/.confluence.yaml

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

package/skills/vds-skill/vds-scripts/docs/.freshness.yaml

@@ -0,0 +1,54 @@
+pairs:
+  - doc: "docs/phases/CHANGELOG.md"
+    source: "AGENTS.md"
+    max_lag_days: 14
+  - doc: "docs/agents/reference/cli-commands.md"
+    source: "vds_cli/src/vds_cli/cli.py"
+    max_lag_days: 7
+  - doc: "llms.txt"
+    source: "AGENTS.md"
+    max_lag_days: 7
+  - doc: "docs/vi/agents/how-to/install-and-bootstrap-who-scripts-and-skills.md"
+    source: "docs/agents/how-to/install-and-bootstrap-who-scripts-and-skills.md"
+    max_lag_days: 30
+  - doc: "docs/vi/agents/tutorials/zero-to-productive-developer.md"
+    source: "docs/agents/tutorials/zero-to-productive-developer.md"
+    max_lag_days: 30
+  - doc: "docs/vi/agents/reference/agent-operational-contract.md"
+    source: "docs/agents/reference/agent-operational-contract.md"
+  - doc: "ECOSYSTEM-DOCS.md"
+    source: "AGENTS.md"
+    max_lag_days: 14
+  - doc: "ECOSYSTEM-CHANGELOG.md"
+    source: "AGENTS.md"
+    max_lag_days: 14
+  - doc: "docs/agents/reference/system-requirements.md"
+    source: "docs/agents/reference/configuration-reference.md"
+    max_lag_days: 14
+  - doc: "docs/agents/reference/common-errors.md"
+    source: "docs/agents/how-to/troubleshooting-guide.md"
+    max_lag_days: 7
+  - doc: "docs/agents/how-to/contribute-new-orchestrator.md"
+    source: "AGENTS.md"
+    max_lag_days: 30
+  - doc: "docs/agents/tutorials/feature-progression-guide.md"
+    source: "vds_cli/src/vds_cli/cli.py"
+    max_lag_days: 14
+  - doc: "docs/agents/reference/orchestrator-comparison-matrix.md"
+    source: "vds_cli/src/vds_cli/cli.py"
+    max_lag_days: 14
+  - doc: "docs/agents/explanation/whats-new.md"
+    source: "ECOSYSTEM-CHANGELOG.md"
+    max_lag_days: 7
+  - doc: "docs/agents/explanation/development-roadmap.md"
+    source: "docs/phases/CHANGELOG.md"
+    max_lag_days: 14
+  - doc: "docs/agents/reference/orchestrator-architecture.md"
+    source: "vds_cli/src/vds_cli/cli.py"
+    max_lag_days: 14
+  - doc: "docs/agents/explanation/data-flow.md"
+    source: "docs/agents/explanation/system-architecture.md"
+    max_lag_days: 14
+  - doc: "docs/agents/tutorials/quick-start.md"
+    source: "docs/agents/explanation/who-ecosystem-introduction.md"
+    max_lag_days: 14