@ngocsangairvds/vsaf 3.1.27 → 3.2.2

package/tools/skills/vds-scripts-skill/references/platform-bootstrap.md

@@ -0,0 +1,31 @@
+# Platform Bootstrap
+
+Use this guide when you need to enter the WHO scripts ecosystem and choose the first command to run.
+
+## Canonical entrypoints
+
+- Interactive monorepo-root usage:
+  - `./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package vds-cli vds-cli --help`
+  - `./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package vds-cli vds-cli env status`
+  - `./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package vds-cli vds-cli status`
+  - `./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package vds-cli vds-cli doctor`
+- Dedicated `vds-scripts` worktree usage:
+  - `./scripts/worktree_uv.sh run --package vds_cli vds-cli --help`
+  - `./scripts/worktree_uv.sh run --package vds_cli vds-cli env status`
+  - `./scripts/worktree_uv.sh run --package vds_cli vds-cli status`
+  - `./scripts/worktree_uv.sh run --package vds_cli vds-cli doctor`
+- Maintained shell scripts should not copy those raw forms. They should source `scripts/vds_sh_helpers.sh` and use the helper contract (`vds_uv_run_package`, `vds_uv_sync_package`, `vds_uv_sync_all`).
+- Preferred integrated baseline for the `WHO-project/vds-scripts` workspace is Python 3.14+.
+
+## Common first steps
+
+1. Check environment readiness with `vds-cli env status`
+2. Check routed-service availability with `vds-cli status` and `vds-cli doctor`
+3. Decide whether the task belongs to:
+   - a platform command family
+   - a specialist CLI such as `vds-audit` or `vds-spec`
+   - a specialist skill such as `audit-orchestrator-skill`
+
+## When to stop using the platform skill
+
+If the task becomes specialist or phase-sensitive, route to the specialist skill rather than extending the platform path.

package/tools/skills/vds-scripts-skill/references/specialist-routing.md

@@ -0,0 +1,14 @@
+# Specialist Routing
+
+Use this routing map when the platform skill identifies a specialist domain.
+
+| Intent | Preferred Skill | Why |
+|-------|------------------|-----|
+| Run audit workflows, readiness checks, reruns, uploads | `audit-orchestrator-skill` | Phase-aware audit guidance lives there |
+| Evaluate README/API docs/security docs with LLM support | `llm-analysis-skill` | Specialist content-evaluation guidance lives there |
+| Create or consolidate specs | `spec-creation-skill` | Owns spec workflow and alignment practices |
+| Develop or update CLI/orchestrator packages | `cli-development-skill` | Owns Typer/JSON/CLI package standards |
+| Configure or use LSPs | `lsp-skill` | Owns LSP tooling guidance |
+| Analyze cross-repo dependency cycles | `circular-dependency-skill` | Owns cycle-analysis workflow |
+| Research with local + web sources | `research-skill` | Owns research-first workflow |
+| Build structural graph context | `code-review-graph-skill` | Companion graph-analysis workflow |

package/tools/skills/vds-scripts-skill/references/validation-commands.md

@@ -0,0 +1,15 @@
+# Validation Commands
+
+Representative WHO validation and docs command families:
+
+- `vds-cli openapi ...`
+- `vds-cli links ...`
+- `vds-cli structure ...`
+- `vds-cli schema ...`
+- `vds-cli pdf ...`
+- `vds-cli diagrams ...`
+- `vds-cli excel ...`
+- `vds-cli google-sheets ...`
+- `vds-markdown ...`
+
+Use specialist docs or package READMEs for deeper command coverage.

package/tools/skills/vsaf-build/SKILL.md

@@ -5,6 +5,16 @@ description: Implement code following existing PRD + SRS + testcases. Use after
 
 # VSAF Build
 
+## Applied Rules
+
+> These rules apply to all code implemented through this flow. Read the full rule before proceeding.
+
+| Rule | File | Applies to |
+|------|------|------------|
+| Run Verification After Coding | `.vsaf/rules/dev/java/run_verification_after_coding.md` | Every task implementation |
+| SonarQube Coding Standard | `.vsaf/rules/dev/java/sonarqube_coding_standard.md` | Java projects only |
+| Java Project Development Rules | `.vsaf/rules/dev/java/java_Project_Development_Rules.md` | Java projects only |
+
 ## Objective
 Implement code strictly following PRD, SRS, and testcases, one task at a time, with TDD — ensuring each commit has tests passing AND is verified against spec.
 
@@ -57,6 +67,21 @@ Implement code strictly following PRD, SRS, and testcases, one task at a time, w
   - Have a clear verification step
   - Be small enough for 1 commit
 
+### Step 2.5 — Code Quality Gate (mandatory for Java projects)
+
+Before writing any code, confirm the quality baseline:
+
+- Read `.vsaf/rules/dev/java/sonarqube_coding_standard.md` — internalize all rules (zero Critical/Blocker, ≥80% new-code coverage, no `System.out`, no hardcoded credentials, etc.)
+- Read `.vsaf/rules/dev/java/java_Project_Development_Rules.md` — enforce: methods ≤40 lines, nesting ≤3 levels, `@Transactional` at service layer only, coverage ≥70%
+- During every task implementation, actively prevent violations:
+  - Use SLF4J logger — never `System.out.println` / `e.printStackTrace()`
+  - Use try-with-resources for all closeable resources
+  - Null-check before dereferencing, use `Optional.orElseThrow()` not `.get()`
+  - Extract constants for string literals repeated ≥3 times
+  - Keep cognitive complexity ≤15 and cyclomatic complexity ≤10 per method
+- After each task commit: mentally verify no SonarQube Blocker/Critical rules were introduced
+- If the project is **not Java**: skip this step
+
 ### Step 2b — Subagent dispatch (large plans, optional)
 - If plan has ≥ 20 tasks AND HAS_SUPERPOWERS: use `superpowers:subagent-driven-development`
   - Dispatch tasks to sub-agents with a two-phase review pipeline
@@ -73,9 +98,14 @@ Implement code strictly following PRD, SRS, and testcases, one task at a time, w
 
 - After each task, run sequentially:
   1. `mcp__gitnexus__detect_changes` — verify only the expected files changed
-  2. **Verification against spec** (mandatory):
-     - **If HAS_SUPERPOWERS**: use `superpowers:verification-before-completion` — confirm outcome matches SRS intent, not just "tests pass"
+  2. **Verification against spec** (mandatory) — follow `.vsaf/rules/dev/java/run_verification_after_coding.md`:
+     - Compile with zero errors (`mvn clean compile` for Maven, equivalent for other build tools)
+     - Run all tests — all must pass (`mvn test`)
+     - Start the application — confirm it boots with no errors
+     - Trigger the changed endpoint/logic with a real request and confirm the response
+     - **If HAS_SUPERPOWERS**: additionally use `superpowers:verification-before-completion` — confirm outcome matches SRS intent
      - **If not**: self-verify: re-read the corresponding FR/NFR in SRS, confirm behavior is correct, record verification result
+     - If full environment is unavailable: use Docker Compose / Testcontainers / mock boundary — do NOT skip verification
   3. Commit: `git commit -m "<type>: <task description>"`
 
 ### Step 3.5 — Checkpoint review (every 3-5 tasks)

package/tools/skills/vsaf-ship/SKILL.md

@@ -5,6 +5,16 @@ description: Multi-layer review + ship code. Used after /vsaf-build and /vsaf-te
 
 # VSAF Ship
 
+## Applied Rules
+
+> These rules are enforced as gates before shipping. Code that violates them cannot be merged.
+
+| Rule | File | Gate |
+|------|------|------|
+| Run Verification After Coding | `.vsaf/rules/dev/java/run_verification_after_coding.md` | Step 1 (pre-review) |
+| SonarQube Coding Standard | `.vsaf/rules/dev/java/sonarqube_coding_standard.md` | Step 2 (code review) |
+| Java Project Development Rules | `.vsaf/rules/dev/java/java_Project_Development_Rules.md` | Step 2 (code review) |
+
 ## Objective
 Multi-layer review, verify scope, validate architecture, push PR. Ensure code has passed all gates before shipping.
 
@@ -21,25 +31,44 @@ Multi-layer review, verify scope, validate architecture, push PR. Ensure code ha
 - Confirm only the expected files/symbols have changed
 - If unexpected changes are detected: **STOP** — review before proceeding
 
-### Step 1 — Structured review handoff (Superpowers)
+### Step 1 — Verification gate (mandatory — before any review)
+- Read `.vsaf/rules/dev/java/run_verification_after_coding.md` and confirm all 5 acceptance criteria are met:
+  - [ ] Code compiles with zero errors
+  - [ ] All existing tests pass
+  - [ ] Application starts without errors
+  - [ ] The changed feature/endpoint was manually triggered and returned the expected result
+  - [ ] No new `ERROR` log lines appear on the happy path
+- If any criterion is NOT met: **STOP** — fix before proceeding to review
+
+### Step 2 — Structured review handoff (Superpowers)
 - Use `superpowers:requesting-code-review` to create a structured handoff:
   - What changed and why
   - What to watch for (risk areas)
   - Context for the reviewer
 - This handoff is the input for the subsequent review layers
 
-### Step 2 — Review Layer 1: Code Review
+### Step 3 — Review Layer 1: Code Review + SonarQube Gate
 - **If Superpowers is available**: use `superpowers:code-review`
 - **If not**: use skill `bmad-code-review`
 - Check: code structure, naming, patterns, SOLID principles
+- **SonarQube gate** (mandatory for Java projects — read `.vsaf/rules/dev/java/sonarqube_coding_standard.md`):
+  - Zero Blocker or Critical issues — must fix before merge, no exceptions
+  - Zero bugs (`squid:S2259` null deref, `squid:S2095` unclosed resources, `squid:S3655` Optional.get without check)
+  - Zero vulnerabilities (no hardcoded credentials, no SQL injection, no sensitive data in logs)
+  - No `System.out.println` / `e.printStackTrace()` — use SLF4J
+  - Coverage ≥80% on new code; Technical Debt Ratio ≤5%
+  - Duplications <3% on new code
+  - Run locally: `mvn clean verify sonar:sonar -Dsonar.projectKey=<key> -Dsonar.host.url=http://localhost:9000 -Dsonar.login=<token>`
+- **Java rules gate** (mandatory for Java projects — read `.vsaf/rules/dev/java/java_Project_Development_Rules.md`):
+  - Methods ≤40 lines, nesting ≤3 levels, `@Transactional` only at service layer
 - Fix issues if any, re-commit
 
-#### Step 2b — Handle reviewer feedback (if any)
+#### Step 3b — Handle reviewer feedback (if any)
 - If the review has feedback that needs to be addressed:
   - Use `superpowers:receiving-code-review` — systematic response, no ad-hoc fixes
   - Fix → re-commit → re-review if needed
 
-### Step 3 — Review Layer 1.5: Adversarial Review
+### Step 4 — Review Layer 1.5: Adversarial Review
 - Use skill `bmad-review-adversarial-general` — cynical attack on new code
   - Look for: logic flaws, security holes, performance traps, silent failures
 - Use skill `bmad-review-edge-case-hunter` — exhaustive boundary analysis
@@ -49,21 +78,21 @@ Multi-layer review, verify scope, validate architecture, push PR. Ensure code ha
   - **SHOULD FIX**: create a follow-up task
   - **NOTED**: acknowledged, no action needed
 
-### Step 4 — Architectural constraint check (GitNexus)
+### Step 5 — Architectural constraint check (GitNexus)
 - Run `gitnexus_shape_check` — validate no architectural constraints are violated
 - If there are violations: **STOP** — fix before proceeding
 
-### Step 5 — Review Layer 2: Knowledge graph sync
+### Step 6 — Review Layer 2: Knowledge graph sync
 - Run `vsaf index` (= `gitnexus analyze`)
 - Update the call graph to reflect the new code
 - This is the final layer — ensure the index accurately reflects the current code state
 
-### Step 6 — Final verification gate (Superpowers)
+### Step 7 — Final verification gate (Superpowers)
 - Use `superpowers:verification-before-completion`
 - Confirm all deliverables match the spec — not just "tests pass"
 - This is the final gate before PR
 
-### Step 7 — Pre-PR checklist (Superpowers)
+### Step 8 — Pre-PR checklist (Superpowers)
 - **If Superpowers is available**: use `superpowers:finishing-a-development-branch` — automated pre-PR checklist
 - **If not**: check manually:
   - [ ] Tests pass
@@ -72,7 +101,7 @@ Multi-layer review, verify scope, validate architecture, push PR. Ensure code ha
   - [ ] Test results file exists
   - [ ] All MUST FIX resolved
 
-### Step 8 — Push PR
+### Step 9 — Push PR
 ```bash
 git push origin feature/<name>
 ```
@@ -82,13 +111,15 @@ PR description must include:
 - Adversarial triage: MUST FIX: 0, SHOULD FIX: N, NOTED: N
 - Shape check result
 
-### Step 9 — Output to user
+### Step 10 — Output to user
 ```
 ## Ship Complete: [feature]
 
 ### Reviews
 - Scope check (detect_changes):  PASS — [N files, N symbols changed]
+- Verification gate:             PASS [compile ✓, tests ✓, run ✓, endpoint ✓]
 - Layer 1 (Code Review):         PASS [superpowers / bmad-code-review]
+- SonarQube gate:                PASS [Blockers: 0, Criticals: 0, Coverage: X%]
 - Layer 1.5 (Adversarial):       PASS [MUST FIX: 0, SHOULD FIX: N, NOTED: N]
 - Shape check:                   PASS
 - Layer 2 (Graph sync):          PASS

package/tools/skills/vsaf-test/SKILL.md

@@ -5,6 +5,14 @@ description: "Two modes: (1) generate testcases from SRS — used after /vsaf-do
 
 # VSAF Test
 
+## Applied Rules
+
+> The run-verification rule applies to **Mode 2 (run)** only. Test generation (Mode 1) is a documentation activity.
+
+| Rule | File | Applies to |
+|------|------|------------|
+| Run Verification After Coding | `.vsaf/rules/dev/java/run_verification_after_coding.md` | Mode 2: Run — executing tests + recording results |
+
 ## Mode distinction
 
 | Command | Mode | Goal |

package/tools/vds-scripts/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "code-review-graph": {
+      "command": "uvx",
+      "args": [
+        "code-review-graph",
+        "serve"
+      ]
+    }
+  }
+}

package/tools/vds-scripts/.secrets.baseline

@@ -0,0 +1,133 @@
+{
+  "version": "1.5.0",
+  "plugins_used": [
+    {
+      "name": "ArtifactoryDetector"
+    },
+    {
+      "name": "AWSKeyDetector"
+    },
+    {
+      "name": "AzureStorageKeyDetector"
+    },
+    {
+      "name": "Base64HighEntropyString",
+      "limit": 4.5
+    },
+    {
+      "name": "BasicAuthDetector"
+    },
+    {
+      "name": "CloudantDetector"
+    },
+    {
+      "name": "DiscordBotTokenDetector"
+    },
+    {
+      "name": "GitHubTokenDetector"
+    },
+    {
+      "name": "GitLabTokenDetector"
+    },
+    {
+      "name": "HexHighEntropyString",
+      "limit": 3.0
+    },
+    {
+      "name": "IbmCloudIamDetector"
+    },
+    {
+      "name": "IbmCosHmacDetector"
+    },
+    {
+      "name": "IPPublicDetector"
+    },
+    {
+      "name": "JwtTokenDetector"
+    },
+    {
+      "name": "KeywordDetector",
+      "keyword_exclude": ""
+    },
+    {
+      "name": "MailchimpDetector"
+    },
+    {
+      "name": "NpmDetector"
+    },
+    {
+      "name": "OpenAIDetector"
+    },
+    {
+      "name": "PrivateKeyDetector"
+    },
+    {
+      "name": "PypiTokenDetector"
+    },
+    {
+      "name": "SendGridDetector"
+    },
+    {
+      "name": "SlackDetector"
+    },
+    {
+      "name": "SoftlayerDetector"
+    },
+    {
+      "name": "SquareOAuthDetector"
+    },
+    {
+      "name": "StripeDetector"
+    },
+    {
+      "name": "TelegramBotTokenDetector"
+    },
+    {
+      "name": "TwilioKeyDetector"
+    }
+  ],
+  "filters_used": [
+    {
+      "path": "detect_secrets.filters.allowlist.is_line_allowlisted"
+    },
+    {
+      "path": "detect_secrets.filters.common.is_ignored_due_to_verification_policies",
+      "min_level": 2
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_indirect_reference"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_likely_id_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_lock_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_not_alphanumeric_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_potential_uuid"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_prefixed_with_dollar_sign"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_sequential_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_swagger_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_templated_secret"
+    },
+    {
+      "path": "detect_secrets.filters.regex.should_exclude_file",
+      "pattern": [
+        ".*"
+      ]
+    }
+  ],
+  "results": {},
+  "generated_at": "2026-01-29T05:10:47Z"
+}

package/tools/vds-scripts/AGENTS.md

@@ -0,0 +1,152 @@
+# AGENTS.md — VDS Scripts Workspace
+
+Audit orchestrator: **8439 tests**, spec v4.93.0 (Phase 152 Planned)
+
+Operational rules for `WHO-project/vds-scripts`.
+
+## Scope
+
+- UV workspace for VDS automation CLIs.
+- Audit baseline is tracked in `.gpt-5.4/specs/audit-orchestrator/`.
+- Use this file for scripts-workspace rules; use `CLAUDE.md` here only for GitNexus/tool overlays.
+
+## Core Rules
+
+- Use `./scripts/worktree_uv.sh` for worktree-safe commands.
+- Runtime is Postgres-first. Do not add filesystem fallback for audit state/evidence.
+- Use the VDS Python SDK for Confluence and Bitbucket operations.
+- Keep spec guidance latest-only; do not reopen completed audit sidecars.
+
+## Current Runtime Truth
+
+- `workflow-project` is the authoritative single-project execution path.
+- `workflow-projects` is the parent orchestration surface and forwards upload behavior to child `workflow-project` runs.
+- Repo-page publication defaults to the canonical project page as the hierarchy anchor.
+- The publisher creates one shared `Project Audit - <project name> (<project page id>)` page directly under the project page and one repo report page per repo beneath it.
+- `--confluence-parent` is a manual override only.
+- `workflow` and `workflow-project` generate PDF reports by default; use `--no-generate-pdf` to disable.
+
+## Canonical Commands
+
+```bash
+./scripts/worktree_uv.sh sync --all-packages
+./scripts/worktree_uv.sh run --project audit_orchestrator vds-audit --help
+./scripts/worktree_uv.sh run --project spec_orchestrator vds-spec --help
+./scripts/worktree_uv.sh run --project vds_cli vds-cli --help
+```
+
+## Required Validation
+
+```bash
+./scripts/worktree_uv.sh run --project spec_orchestrator vds-spec validate audit-orchestrator
+./scripts/worktree_uv.sh run --project spec_orchestrator vds-spec check-alignment audit-orchestrator
+./scripts/worktree_uv.sh run --project spec_orchestrator vds-spec validate-sync audit-orchestrator --agents-file AGENTS.md --agents-label 'Audit orchestrator' --json-only
+```
+
+## References
+
+- Root policy: `../../AGENTS.md`
+- WHO router: `../AGENTS.md`
+- Docs: `docs/agents/`
+
+<!-- gitnexus:start -->
+# GitNexus — Code Intelligence
+
+This project is indexed by GitNexus as **phase150-eval-timeout-resilience** (38818 symbols, 99103 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+
+> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
+
+## Always Do
+
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
+
+## When Debugging
+
+1. `gitnexus_query({query: "<error or symptom>"})` — find execution flows related to the issue
+2. `gitnexus_context({name: "<suspect function>"})` — see all callers, callees, and process participation
+3. `READ gitnexus://repo/phase150-eval-timeout-resilience/process/{processName}` — trace the full execution flow step by step
+4. For regressions: `gitnexus_detect_changes({scope: "compare", base_ref: "main"})` — see what your branch changed
+
+## When Refactoring
+
+- **Renaming**: MUST use `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with `dry_run: false`.
+- **Extracting/Splitting**: MUST run `gitnexus_context({name: "target"})` to see all incoming/outgoing refs, then `gitnexus_impact({target: "target", direction: "upstream"})` to find all external callers before moving code.
+- After any refactor: run `gitnexus_detect_changes({scope: "all"})` to verify only expected files changed.
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
+- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
+
+## Tools Quick Reference
+
+| Tool | When to use | Command |
+|------|-------------|---------|
+| `query` | Find code by concept | `gitnexus_query({query: "auth validation"})` |
+| `context` | 360-degree view of one symbol | `gitnexus_context({name: "validateUser"})` |
+| `impact` | Blast radius before editing | `gitnexus_impact({target: "X", direction: "upstream"})` |
+| `detect_changes` | Pre-commit scope check | `gitnexus_detect_changes({scope: "staged"})` |
+| `rename` | Safe multi-file rename | `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` |
+| `cypher` | Custom graph queries | `gitnexus_cypher({query: "MATCH ..."})` |
+
+## Impact Risk Levels
+
+| Depth | Meaning | Action |
+|-------|---------|--------|
+| d=1 | WILL BREAK — direct callers/importers | MUST update these |
+| d=2 | LIKELY AFFECTED — indirect deps | Should test |
+| d=3 | MAY NEED TESTING — transitive | Test if critical path |
+
+## Resources
+
+| Resource | Use for |
+|----------|---------|
+| `gitnexus://repo/phase150-eval-timeout-resilience/context` | Codebase overview, check index freshness |
+| `gitnexus://repo/phase150-eval-timeout-resilience/clusters` | All functional areas |
+| `gitnexus://repo/phase150-eval-timeout-resilience/processes` | All execution flows |
+| `gitnexus://repo/phase150-eval-timeout-resilience/process/{name}` | Step-by-step execution trace |
+
+## Self-Check Before Finishing
+
+Before completing any code modification task, verify:
+1. `gitnexus_impact` was run for all modified symbols
+2. No HIGH/CRITICAL risk warnings were ignored
+3. `gitnexus_detect_changes()` confirms changes match expected scope
+4. All d=1 (WILL BREAK) dependents were updated
+
+## Keeping the Index Fresh
+
+After committing code changes, the GitNexus index becomes stale. Re-run analyze to update it:
+
+```bash
+npx gitnexus analyze
+```
+
+If the index previously included embeddings, preserve them by adding `--embeddings`:
+
+```bash
+npx gitnexus analyze --embeddings
+```
+
+To check whether embeddings exist, inspect `.gitnexus/meta.json` — the `stats.embeddings` field shows the count (0 means no embeddings). **Running analyze without `--embeddings` will delete any previously generated embeddings.**
+
+> Claude Code users: A PostToolUse hook handles this automatically after `git commit` and `git merge`.
+
+## CLI
+
+| Task | Read this skill file |
+|------|---------------------|
+| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
+| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
+| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
+| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
+| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
+| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
+
+<!-- gitnexus:end -->

package/tools/vds-scripts/CLAUDE.md

@@ -0,0 +1,101 @@
+<!-- gitnexus:start -->
+# GitNexus — Code Intelligence
+
+This project is indexed by GitNexus as **phase150-eval-timeout-resilience** (38818 symbols, 99103 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+
+> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
+
+## Always Do
+
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
+
+## When Debugging
+
+1. `gitnexus_query({query: "<error or symptom>"})` — find execution flows related to the issue
+2. `gitnexus_context({name: "<suspect function>"})` — see all callers, callees, and process participation
+3. `READ gitnexus://repo/phase150-eval-timeout-resilience/process/{processName}` — trace the full execution flow step by step
+4. For regressions: `gitnexus_detect_changes({scope: "compare", base_ref: "main"})` — see what your branch changed
+
+## When Refactoring
+
+- **Renaming**: MUST use `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with `dry_run: false`.
+- **Extracting/Splitting**: MUST run `gitnexus_context({name: "target"})` to see all incoming/outgoing refs, then `gitnexus_impact({target: "target", direction: "upstream"})` to find all external callers before moving code.
+- After any refactor: run `gitnexus_detect_changes({scope: "all"})` to verify only expected files changed.
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
+- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
+
+## Tools Quick Reference
+
+| Tool | When to use | Command |
+|------|-------------|---------|
+| `query` | Find code by concept | `gitnexus_query({query: "auth validation"})` |
+| `context` | 360-degree view of one symbol | `gitnexus_context({name: "validateUser"})` |
+| `impact` | Blast radius before editing | `gitnexus_impact({target: "X", direction: "upstream"})` |
+| `detect_changes` | Pre-commit scope check | `gitnexus_detect_changes({scope: "staged"})` |
+| `rename` | Safe multi-file rename | `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` |
+| `cypher` | Custom graph queries | `gitnexus_cypher({query: "MATCH ..."})` |
+
+## Impact Risk Levels
+
+| Depth | Meaning | Action |
+|-------|---------|--------|
+| d=1 | WILL BREAK — direct callers/importers | MUST update these |
+| d=2 | LIKELY AFFECTED — indirect deps | Should test |
+| d=3 | MAY NEED TESTING — transitive | Test if critical path |
+
+## Resources
+
+| Resource | Use for |
+|----------|---------|
+| `gitnexus://repo/phase150-eval-timeout-resilience/context` | Codebase overview, check index freshness |
+| `gitnexus://repo/phase150-eval-timeout-resilience/clusters` | All functional areas |
+| `gitnexus://repo/phase150-eval-timeout-resilience/processes` | All execution flows |
+| `gitnexus://repo/phase150-eval-timeout-resilience/process/{name}` | Step-by-step execution trace |
+
+## Self-Check Before Finishing
+
+Before completing any code modification task, verify:
+1. `gitnexus_impact` was run for all modified symbols
+2. No HIGH/CRITICAL risk warnings were ignored
+3. `gitnexus_detect_changes()` confirms changes match expected scope
+4. All d=1 (WILL BREAK) dependents were updated
+
+## Keeping the Index Fresh
+
+After committing code changes, the GitNexus index becomes stale. Re-run analyze to update it:
+
+```bash
+npx gitnexus analyze
+```
+
+If the index previously included embeddings, preserve them by adding `--embeddings`:
+
+```bash
+npx gitnexus analyze --embeddings
+```
+
+To check whether embeddings exist, inspect `.gitnexus/meta.json` — the `stats.embeddings` field shows the count (0 means no embeddings). **Running analyze without `--embeddings` will delete any previously generated embeddings.**
+
+> Claude Code users: A PostToolUse hook handles this automatically after `git commit` and `git merge`.
+
+## CLI
+
+| Task | Read this skill file |
+|------|---------------------|
+| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
+| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
+| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
+| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
+| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
+| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
+
+<!-- gitnexus:end -->