@ngocsangairvds/vsaf 3.2.16 → 4.0.1

package/tools/vds-scripts/docs/agents/how-to/choose-the-right-command-or-skill.md

@@ -1,34 +0,0 @@
-<!-- diátaxis: how-to -->
-
-# Choose The Right WHO Command Or Skill
-
-Use this guide when you know the task you want to perform but are not sure whether to start with a CLI command family or a specialist skill.
-
-## Step 1: Is this a platform-routing question?
-
-Use `vds-scripts-skill` when you need to:
-- find the right WHO command family
-- bootstrap the scripts workspace
-- understand which workspace capability owns a task
-- route to the correct specialist skill
-
-## Step 2: Route by task intent
-
-| Intent | Start Here |
-|-------|------------|
-| Run audit workflow, readiness, rerun, upload | `audit-orchestrator-skill` + `vds-cli audit` |
-| Evaluate README/API docs/security docs with LLM support | `llm-analysis-skill` |
-| Create or update specs | `spec-creation-skill` + `vds-cli spec` |
-| Develop a CLI/orchestrator | `cli-development-skill` |
-| Use Jira/Confluence/Bitbucket/Git | `vds-scripts-skill` + `vds-cli` integration family |
-| Validate docs, links, schemas, OpenAPI, diagrams, sheets | `vds-scripts-skill` + validation family |
-| Configure LSP | `lsp-skill` |
-| Analyze dependency cycles | `circular-dependency-skill` |
-| Research across local + external sources | `research-skill` |
-
-## Step 3: Follow canonical sources
-
-- Scripts: `WHO-project/vds-scripts/`
-- Skills: `WHO-project/vds-skills/skills/`
-- Do not edit `.agent/skills/` directly
-- For shared env/config/cache path behavior, use `../reference/portable-paths-and-config.md`

package/tools/vds-scripts/docs/agents/how-to/contribute-new-orchestrator.md

@@ -1,149 +0,0 @@
-<!-- diátaxis: how-to -->
-
-# Contribute a New Orchestrator
-
-## Prerequisites
-
-- Python 3.14+
-- uv installed
-- Docker (for testing with Postgres/Redis)
-- Familiarity with Typer and structlog
-
-## Workflow
-
-### 1. Create Branch
-
-```bash
-# From vds-scripts root
-git checkout -b feature/my-new-orchestrator
-```
-
-### 2. Scaffold the Orchestrator
-
-```bash
-# Create directory
-cd vds-scripts
-mkdir my_orchestrator
-cd my_orchestrator
-
-# Initialize uv project
-uv init --lib
-
-# Add dependencies
-uv add typer structlog pydantic-settings
-```
-
-### 3. Implement the CLI
-
-Create `my_orchestrator/src/my_orchestrator/cli.py`:
-
-```python
-import typer
-import structlog
-
-app = typer.Typer(help="My new orchestrator")
-logger = structlog.get_logger(__name__)
-
-@app.command()
-def run(input: str):
-    """Run my orchestrator."""
-    logger.info("starting", input=input)
-    # Implementation here
-    logger.info("completed", input=input)
-
-if __name__ == "__main__":
-    app()
-```
-
-### 4. Add Entry Point
-
-Update `pyproject.toml`:
-
-```toml
-[project.scripts]
-vds-my-orchestrator = "my_orchestrator.cli:app"
-```
-
-### 5. Register in Router
-
-Add to `vds_cli/src/vds_cli/router.py`:
-
-```python
-ORCHESTRATORS = {
-    # ... existing entries
-    "my_orchestrator": {
-        "module": "my_orchestrator.cli",
-        "path": "my_orchestrator",
-        "entry": "vds-my-orchestrator",
-    },
-}
-```
-
-### 6. Write Tests
-
-Create `tests/test_my_orchestrator.py`:
-
-```python
-import pytest
-from my_orchestrator.cli import app
-from typer.testing import CliRunner
-
-runner = CliRunner()
-
-def test_run():
-    result = runner.invoke(app, ["run", "test-input"])
-    assert result.exit_code == 0
-    assert "completed" in result.output
-```
-
-### 7. Add Documentation
-
-Create `docs/agents/reference/my-orchestrator.md` following the Diátaxis pattern.
-
-### 8. Update Ecosystem Files
-
-- Add to `AGENTS.md` router section
-- Append to `llms.txt`
-- Update `ECOSYSTEM-DOCS.md`
-
-### 9. Run Validation
-
-```bash
-vds-cli docs validate
-pytest
-```
-
-### 10. Commit and PR
-
-```bash
-git add .
-git commit -m "feat: add my-orchestrator orchestrator
-
-- Implements X functionality
-- Adds Y tests
-- Updates docs and AGENTS.md"
-```
-
-## PR Checklist
-
-- [ ] Tests pass (`pytest`)
-- [ ] Docs validated (`vds-cli docs validate`)
-- [ ] AGENTS.md line count ≤250
-- [ ] New doc has YAML frontmatter
-- [ ] Entry point registered in router
-- [ ] No hardcoded secrets
-- [ ] Error handling with context
-
-## Code Review Criteria
-
-Reviews check for:
-- Correct Typer/structlog patterns
-- Proper error handling
-- Test coverage ≥80%
-- Documentation completeness
-- No external API calls in tests (use mocks)
-
-## See Also
-
-- [Orchestrator Architecture](../reference/orchestrator-architecture.md)
-- [Add a Skill](../how-to/add-a-skill.md)

package/tools/vds-scripts/docs/agents/how-to/decision-tree.md

@@ -1,63 +0,0 @@
-<!-- diátaxis: how-to -->
-# What Kind of Doc Am I Writing?
-
-Quick decision tree for choosing the correct Diátaxis quadrant.
-
----
-
-## The One-Question Method
-
-Start at the top and answer each question. The first "YES" tells you the quadrant.
-
-```
-Q1: Is this for someone who has NEVER done this before?
-     → YES → TUTORIAL
-     → NO → Q2
-
-Q2: Is this a step-by-step recipe for a SPECIFIC task?
-     → YES → HOW-TO GUIDE
-     → NO → Q3
-
-Q3: Is this listing exact flags, contracts, or API surfaces?
-     → YES → REFERENCE
-     → NO → Q4
-
-Q4: Is this explaining WHY something works or background concepts?
-     → YES → EXPLANATION
-     → NO → Re-examine your scope. You may be mixing quadrants.
-```
-
----
-
-## Examples by Quadrant
-
-| Doc Title | Quadrant | Why |
-|-----------|----------|-----|
-| "Day 0: Install the WHO toolchain" | Tutorial | First-time learner |
-| "How to add a new skill to the catalog" | How-to | Specific task |
-| `vds-cli --help` auto-generated docs | Reference | Exact flags |
-| "Why we use Diátaxis for doc architecture" | Explanation | Background concept |
-
----
-
-## Common Anti-Patterns
-
-| Anti-Pattern | Fix |
-|--------------|-----|
-| Tutorial sneaks in unrelated tasks | Split to a separate How-to |
-| Reference doc tells a story | Delete narrative; keep only facts |
-| How-to explains the "why" | Move "why" to a linked Explanation doc |
-| Explanation gives step-by-step commands | Move commands to a How-to |
-
----
-
-## Header Convention
-
-Every `.md` in `docs/agents/` should include its quadrant as the very first line:
-
-```markdown
-<!-- diátaxis: tutorial -->
-# Title
-```
-
-Valid values: `tutorial`, `how-to`, `reference`, `explanation`

package/tools/vds-scripts/docs/agents/how-to/first-audit-run.md

@@ -1,83 +0,0 @@
-<!-- diátaxis: how-to -->
-
-# First Audit Run
-
-> Step-by-step guide for running your first repository audit using the WHO-project toolchain.
-
-## Prerequisites
-
-- `vds-scripts` cloned and bootstrapped (`./scripts/worktree_uv.sh sync`)
-- `vds-cli doctor` passes
-- Target repo(s) accessible via Bitbucket
-
-## Quick Start
-
-### 1. Discover available audit skills
-
-```bash
-cat WHO-project/vds-skills/skills/ | grep audit
-```
-
-Expected output includes `audit-orchestrator-skill`.
-
-### 2. Load the audit skill
-
-```bash
-cat WHO-project/vds-skills/skills/audit-orchestrator-skill
-```
-
-This prints the skill's operational contract, CLI flags, and examples.
-
-### 3. Run a single-repo audit
-
-```bash
-vds-cli audit run --repo vds-scripts --scope quick
-```
-
-- `--repo`: target repository slug
-- `--scope quick`: fast pass (rules + structure, no deep analysis)
-- `--scope full`: comprehensive audit (slower, more thorough)
-
-### 4. Review results
-
-Output is written to `audits/<timestamp>-<repo>-<scope>.md`.
-
-```bash
-cat audits/$(ls -t audits/ | head -n 1)
-```
-
-### 5. Escalate findings
-
-If the audit surfaces issues:
-
-```bash
-# Auto-create tickets from findings
-vds-cli audit escalate --from audits/<file>.md --tracker jira
-
-# Or export as Confluence table
-vds-cli audit export --format confluence --from audits/<file>.md
-```
-
-## Common Flags
-
-| Flag | Description |
-|------|-------------|
-| `--dry-run` | Show what would be audited without running |
-| `--rules-only` | Skip code analysis, check rules compliance only |
-| `--output-dir` | Custom output directory (default: `audits/`) |
-| `--format json` | Machine-readable output instead of markdown |
-
-## Troubleshooting
-
-| Symptom | Fix |
-|---------|-----|
-| `audit-orchestrator-skill not found` | Run `vds-cli skills sync --agent claude` to refresh catalog |
-| `Permission denied` on Bitbucket | Check `INTERNAL_BITBUCKET_TOKEN` in `~/.vds/.env` |
-| Empty audit output | Verify `--repo` slug matches Bitbucket exactly |
-| Slow execution | Use `--scope quick` or `--rules-only` for faster feedback |
-
-## Next Steps
-
-- Read the full audit skill: `cat WHO-project/vds-skills/skills/audit-orchestrator-skill`
-- Review the audit triage playbook: `docs/agents/reference/audit-triage-playbook.md`
-- Run cross-repo audits: `vds-cli audit run --repo-list repos.txt --scope full`

package/tools/vds-scripts/docs/agents/how-to/index.md

@@ -1,49 +0,0 @@
-<!-- diátaxis: how-to -->
-# How-To Guides
-
-> Step-by-step workflow guides for common VDS operations.
-
-## Workflow Quick Reference
-
-Use the following command to list all how-to guides in a script or orchestrator context:
-
-```bash
-vds-cli docs index --agent-script-path docs/agents/how-to/ --check-diataxis
-```
-
-## Available Guides
-
-| Guide | Orchestrator | Skill |
-|-------|-------------|-------|
-| [Install and Bootstrap WHO Scripts and Skills](install-and-bootstrap-who-scripts-and-skills.md) | `vds-scripts` | bootstrap |
-| [Configure Agents](configure-agents.md) | `vds-scripts` | config |
-| [Run Ecosystem Daily Report](run-ecosystem-daily-report.md) | `scheduler_orchestrator` | reporting |
-| [Apply Phase 3 Migration](apply-phase3-migration.md) | `scheduler_orchestrator` | migration |
-
-## Writing a New How-To
-
-1. Copy `TEMPLATE.md` (if available) or an existing guide.
-2. Add the `<!-- diátaxis: how-to -->` header.
-3. Include the prerequisite section, step-by-step workflow, and error handling.
-4. Run the doc quality gate before committing:
-
-```bash
-vds-cli docs validate --check-diataxis --repo-root .
-```
-
-## Workflow
-
-```mermaid
-graph LR
-    A[Identify Task] --> B[Match How-To]
-    B --> C[Follow Steps]
-    C --> D[Run Quality Gate]
-    D --> E[Commit]
-```
-
-## See Also
-
-- [Tutorials](../tutorials/) — Learning-oriented walkthroughs for new team members
-- [Reference](../reference/) — API contracts, CLI commands, and orchestrator runbooks
-- [Explanation](../explanation/) — Architectural decisions and design rationale
-- [Skills overview](choosing-the-right-skill.md) — How to pick the correct skill for a task

package/tools/vds-scripts/docs/agents/how-to/install-and-bootstrap-who-scripts-and-skills.md

@@ -1,314 +0,0 @@
-<!-- diátaxis: how-to -->
-
-# Install And Bootstrap WHO Scripts And Skills
-
-Use this guide when you need a clean, explicit setup path for the WHO scripts workspace and the WHO skills catalog.
-It is written for both human contributors and AI agents.
-
-## 1. Choose the right working mode
-
-- **Dedicated `vds-scripts` worktree**: prefer `./scripts/worktree_uv.sh ...` for all `uv` commands.
-- **Main `vds-scripts` checkout**: `uv sync` and `uv run --project ...` are acceptable.
-- **External clone**: set explicit `VDS_SCRIPTS_PATH` / `VDS_SKILLS_PATH` values and do not assume monorepo-relative defaults.
-
-## 2. Install prerequisites
-
-### Required for scripts workspace
-
-- `git`
-- `uv`
-- a supported shell environment
-
-Install `uv`:
-
-- macOS/Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh`
-- or use the package-manager workflow approved in your environment
-
-### Optional but recommended for skill workflows
-
-- `python3` (or `python`) for running `vds-skills-sync`
-
-This is required when you want `vds-skills-sync` to generate `AGENTS.md` from
-`registry.yaml`. It is not required when you only need to read canonical skill
-files directly.
-
-## 3. Set canonical paths
-
-Add these to `VDS_ENV_FILE` or `<config-root>/.env` for persistence when appropriate.
-`<config-root>` resolves from `VDS_CONFIG_DIR` when set, otherwise from the user-home VDS default.
-
-```bash
-export VDS_SCRIPTS_PATH="${VDS_SCRIPTS_PATH:-./WHO-project/vds-scripts}"
-export VDS_SKILLS_PATH="${VDS_SKILLS_PATH:-./WHO-project/vds-skills/skills}"
-```
-
-## 4. Bootstrap the scripts workspace
-
-### Dedicated `vds-scripts` worktree
-
-```bash
-cd "$VDS_SCRIPTS_PATH"
-./scripts/worktree_uv.sh sync --all-packages
-```
-
-### Non-worktree checkout
-
-```bash
-cd "$VDS_SCRIPTS_PATH"
-uv sync --all-packages
-```
-
-## 5. Verify the scripts workspace
-
-Run the minimum verification set before deeper work:
-
-```bash
-cd "$VDS_SCRIPTS_PATH"
-./scripts/worktree_uv.sh run --project vds_cli vds-cli --help
-./scripts/worktree_uv.sh run --project vds_cli vds-cli env status
-./scripts/worktree_uv.sh run --project vds_cli vds-cli audit --help
-./scripts/worktree_uv.sh run --project vds_cli vds-cli spec --help
-```
-
-If you are not in a dedicated worktree, use `uv run --project ...` equivalents.
-
-If `vds-cli env status` reports missing credentials, configure `~/.vds/.env` per §11 below before continuing. The same section covers the canonical git credential helper (`vds-cli env install-git-helper`).
-
-## 6. Verify the skills catalog
-
-```bash
-ls -la "$VDS_SKILLS_PATH/"
-```
-
-Canonical maintained skills live under:
-
-- `WHO-project/vds-skills/skills/`
-
-Do not treat `.agent/skills/` as an independent authoring source.
-
-## 7. Human workflow: OpenSkills usage
-
-When `node`/`npx` is available and OpenSkills is configured for the workspace:
-
-```bash
-ls WHO-project/vds-skills/skills/
-cat WHO-project/vds-skills/skills/vds-scripts-skill
-cat WHO-project/vds-skills/skills/audit-orchestrator-skill
-```
-
-Use OpenSkills when you want the standard install/read/sync workflow.
-
-## 8. AI-agent workflow: direct fallback when OpenSkills is unavailable
-
-If `cat WHO-project/vds-skills/skills/<skill-name>` fails because the current shell context does not resolve the workspace skill configuration correctly, fall back to the canonical skill files directly.
-
-Read from:
-
-- `WHO-project/vds-skills/skills/<skill-name>/SKILL.md`
-
-Examples:
-
-- `WHO-project/vds-skills/skills/vds-scripts-skill/SKILL.md`
-- `WHO-project/vds-skills/skills/audit-orchestrator-skill/SKILL.md`
-- `WHO-project/vds-skills/skills/spec-creation-skill/SKILL.md`
-
-This fallback is valid because the canonical source of truth is the WHO skills repository, not the mirror/symlink surfaces.
-
-## 9. Minimum agent-readiness checklist
-
-Before an AI agent proceeds, confirm:
-
-- `VDS_SCRIPTS_PATH` points to the intended scripts workspace
-- `VDS_SKILLS_PATH` points to the canonical skills directory
-- routed help works: `vds-cli --help`
-- specialist help works: `vds-audit --help`, `vds-cli spec --help`
-- evolution loop works: `.venv/bin/vds-cli evolution status` (or `vds-cli evolution status`)
-- the agent knows whether it is using OpenSkills loading or direct canonical skill-file reads
-- `.agent/skills/` is treated as compatibility-only, not as the maintained source
-
-## 10. OpenSpace evolution loop runtime (when using `vds_evolution`)
-
-If you intend to use the WHO ecosystem evolution loop with a real OpenSpace runtime,
-prefer repo-local runtime paths under the scripts workspace and keep durable env
-configuration in the shared VDS env layer.
-
-Recommended durable env placement:
-- `VDS_ENV_FILE`
-- or the default shared env file: `~/.vds/.env`
-
-Recommended variables:
-
-```bash
-OPENSPACE_WORKSPACE="$VDS_SCRIPTS_PATH/.openspace"
-OPENSPACE_HOST_SKILL_DIRS="$VDS_SCRIPTS_PATH/.openspace/shadow/skills"
-OPENSPACE_TRANSPORT=stdio
-OPENSPACE_AUTONOMOUS_ENABLED=false
-```
-
-Notes:
-- Keep autonomy disabled until the OpenSpace runtime is verified healthy.
-- Prefer repo-local `.openspace/` over ad hoc host-only directories so the setup is part of the workspace.
-- Refresh the shadow skill mirror from the canonical skills catalog before enabling automated evolution.
-- Ensure `openspace-mcp` is installed and callable in the active shell before relying on stdio transport.
-- Treat the official HKUDS/OpenSpace repository as the reference for runtime startup and env semantics; prefer the officially documented `stdio` and `sse` transports for real setup.
-
-### vds-cli evolution script execution
-
-The `vds-cli evolution` script works from any CWD due to a spec_from_file_location workaround that bypasses the openspace `__path_hook__` issue in mixed venv environments.
-
-**Available entry points:**
-
-| Entry | Location | Usage |
-|-------|----------|-------|
-| Standalone | `.venv/bin/vds-cli evolution` | Direct execution from scripts repo |
-| Tracked shell | `vds-cli evolution-mono.sh` | For monorepo compatibility |
-| Via router | `vds-cli evolution ...` | Through the unified CLI |
-
-**Typical commands:**
-
-```bash
-# Standalone (works from any CWD)
-.venv/bin/vds-cli evolution status
-.venv/bin/vds-cli evolution list
-
-# Via router
-vds-cli evolution status
-vds-cli evolution list
-
-# OpenSpace bootstrap
-vds-cli evolution openspace-bootstrap
-vds-cli evolution openspace-doctor
-```
-
-**Root cause note:** When the monorepo `.venv` contains both `openspace` and `vds-cli evolution` packages installed via `uv pip install -e`, the openspace editable installer registers a custom `PathEntryFinder` in `sys.path_hooks`. This causes `importlib.util.find_spec()` to return `None` for `vds-cli evolution` from certain CWDs. The script workaround uses `spec_from_file_location` + `module_from_spec` to bypass the hook entirely and directly load from known file paths.
-
-## 11. Configure credentials in `~/.vds/.env`
-
-This section defines the canonical shape of `~/.vds/.env` per `who-ecosystem-alignment` Phase 5 FR-18..FR-25. The file is the single source of credentials for all VDS orchestrators. Values shown below are placeholders — replace them with your real credentials. NEVER commit real credential values anywhere (NFR-12).
-
-### 11.1 Required keys (Atlassian shared identity)
-
-The three Atlassian orchestrators (`bitbucket_orchestrator`, `confluence_orchestrator`, `jira_orchestrator`) share the corporate SSO identity per FR-18 (Atlassian shared-identity model). Both keys are mandatory:
-
-```dotenv
-VDS_USERNAME=<your-corporate-username>
-VDS_PASSWORD=<your-corporate-password>
-```
-
-Removing either key simultaneously breaks Bitbucket SDK, Confluence SDK, and JIRA SDK access — see the Credential Consumer Inventory in `.gpt-5.4/specs/who-ecosystem-alignment/design.md` Phase 5 §Credential Consumer Inventory.
-
-### 11.2 Optional per-product tokens (token-preference asymmetry)
-
-Per FR-19, each Atlassian product accepts an additional per-product token. The resolution order is **asymmetric by product**:
-
-| Orchestrator | Token env var | Resolution priority |
-|---|---|---|
-| `bitbucket_orchestrator` | `BITBUCKET_TOKEN` | **Token preferred** over basic auth when both present |
-| `jira_orchestrator` | `JIRA_TOKEN` | **Token preferred** over basic auth when both present |
-| `confluence_orchestrator` | `INTERNAL_CONFLUENCE_TOKEN`, `EXTERNAL_CONFLUENCE_TOKEN` | **Basic auth primary** per `.claude/rules/sdk-and-auth-rules.md`; tokens are fallback |
-
-Configure tokens only if you've been issued one:
-
-```dotenv
-BITBUCKET_TOKEN=<your-bbdc-pat>
-JIRA_TOKEN=<your-jira-pat>
-INTERNAL_CONFLUENCE_TOKEN=<your-internal-confluence-token>
-EXTERNAL_CONFLUENCE_TOKEN=<your-external-confluence-token>
-```
-
-A token set to an empty string or whitespace is treated as absent per AC-19.5 — the SDK and the git credential helper both fall back to basic auth.
-
-### 11.3 Isolated-prefix orchestrators (non-Atlassian)
-
-Per FR-18 AC-18.2, non-Atlassian orchestrators use isolated credential prefixes and MUST NOT bind `VDS_PASSWORD`:
-
-```dotenv
-# Grafana
-VDS_GRAFANA_USER=<your-grafana-user>
-VDS_GRAFANA_PASSWORD=<your-grafana-password>
-VDS_GRAFANA_TOKEN=<your-grafana-pat>          # optional; preferred when set
-
-# SonarQube
-VDS_SONAR_USER=<your-sonar-user>
-VDS_SONAR_PASSWORD=<your-sonar-password>
-VDS_SONAR_TOKEN=<your-sonar-pat>              # optional; preferred when set
-
-# Elasticsearch (basic only — no token alternative in current SDK)
-VDS_ELASTIC_USER=<your-elastic-user>
-VDS_ELASTIC_PASSWORD=<your-elastic-password>
-```
-
-These prefixes can be rotated independently of the Atlassian shared identity.
-
-### 11.4 Endpoint URLs
-
-Per-orchestrator endpoint URLs are environment-specific:
-
-```dotenv
-VDS_BITBUCKET_URL=<your-bitbucket-base-url>
-VDS_CONFLUENCE_URL=<your-confluence-base-url>
-VDS_GRAFANA_URL=<your-grafana-url>
-# ... add one per orchestrator you intend to use
-```
-
-### 11.5 Install the git credential helper (`vds-cli env install-git-helper`)
-
-Per FR-23 (helper lifecycle via vds-cli) + FR-24 (single canonical artifact), the operator git credential helper is installed and managed exclusively via `vds-cli env`. NEVER install or upgrade the helper by manual `cp` / `chmod` / `git config` (FR-23 AC-23.1).
-
-```bash
-# Install the canonical helper at $HOME/.vds/bin/git-credential-vds (mode 0o700)
-# and configure git credential.helper to use it. Removes any pre-FR-24 artifacts
-# (signature-checked per AC-24.6 — user-authored files are preserved with a warning).
-./scripts/worktree_uv.sh run --project vds_cli vds-cli env install-git-helper
-
-# Verify install state (exit 0 ⇔ all checks pass)
-./scripts/worktree_uv.sh run --project vds_cli vds-cli env verify-git-helper
-
-# If a Bitbucket account-lock cooldown is active, reset after fixing creds:
-./scripts/worktree_uv.sh run --project vds_cli vds-cli env verify-git-helper --reset-cooldown
-
-# Uninstall (idempotent — safe to call when nothing is installed)
-./scripts/worktree_uv.sh run --project vds_cli vds-cli env remove-git-helper
-
-# Uninstall + delete cooldown state file
-./scripts/worktree_uv.sh run --project vds_cli vds-cli env remove-git-helper --purge
-```
-
-The helper enforces three contracts:
-
-- **Host allowlist** (FR-20 AC-20.1): credentials emitted ONLY for `bitbucket.digital.vn`. Extensible via `VDS_BITBUCKET_HOSTS` in `~/.vds/.env` (comma-separated). Never readable from shell env per AC-20.6 — extension requires `~/.vds/.env` edit. Other git hosts get silent fall-through to the next configured helper (e.g., osxkeychain).
-- **Lockout prevention** (FR-21): 3 failed-auth events within 60 seconds trigger a 300-second silent cooldown. State file at `$HOME/.vds/.git-credential-helper-cooldown.json` (mode `0o600` per AC-21.7). Reset via `verify-git-helper --reset-cooldown`.
-- **Token preference** (mirrors FR-19 for Bitbucket per AC-20.3): emits `BITBUCKET_TOKEN` over `VDS_PASSWORD` when both are configured.
-
-### 11.6 Verification
-
-Confirm the full credential + helper stack:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli vds-cli env status
-./scripts/worktree_uv.sh run --project vds_cli vds-cli env verify-git-helper
-./scripts/worktree_uv.sh run --project vds_cli vds-cli doctor
-```
-
-`vds-cli doctor` includes a "Git credential helper" status row (`installed` / `missing` / `broken`) per FR-23 AC-23.5, with a remediation hint pointing to `vds-cli env install-git-helper`.
-
-### 11.7 Canonical credential model
-
-The full credential resolution invariants — which orchestrators share `VDS_PASSWORD`, why the per-product token preference is asymmetric (Bitbucket/JIRA prefer token; Confluence keeps basic primary), what the helper lifecycle contract is, what file modes are required — live in:
-
-**Canonical credential model: `who-ecosystem-alignment` Phase 5 FR-18..FR-25** at `.gpt-5.4/specs/who-ecosystem-alignment/`.
-
-Refer to that spec when:
-
-- Adding a new orchestrator → declare its credential model (Atlassian-shared vs isolated-prefix) per AC-18.3 and update `design.md` Phase 5 §Credential Consumer Inventory.
-- Proposing changes to `~/.vds/.env` shape → audit which orchestrators read each key.
-- Modifying the git credential helper → AC-25.4 requires paired updates if `BitbucketSettings.get_auth_kwargs` or `vds_cli_common.env._parse_env_file` change.
-
-## 12. Related references
-
-- `../reference/portable-paths-and-config.md`
-- `../reference/cli-help-matrix.md`
-- `../tutorials/who-skills-and-scripts-onboarding.md`
-- `choose-the-right-command-or-skill.md`
-- `.gpt-5.4/specs/who-ecosystem-evolution-loop/`
-- `.gpt-5.4/specs/who-ecosystem-alignment/` (canonical credential model — Phase 5 FR-18..FR-25)