@ngocsangairvds/vsaf 4.0.5 → 4.0.7

package/skills/vds-skill/vds-scripts/docs/phases/phase125_skill_runtime_closure_20260321.md

@@ -0,0 +1,91 @@
+# Phase 125 Skill Runtime Closure — 2026-03-21
+
+## Summary
+
+This closure finalizes Phase 125 runtime skill integration in the main worktree.
+
+Completed items:
+- fixed runtime profile skill configuration for `omniroute-gpt-openai` and `omniroute-glm-openai`
+- fixed skills catalog alignment by adding missing `QUALITY.md` for `hexagonal-compliance-skill`
+- added deterministic dependency-cycle skill recommendation support for `circular-dependency-skill`
+- fixed upstream requirement interpretation so CL-004-like dependency rows emit `skills_needed=true` and `skill_objectives=["analyze_dependency_cycles"]`
+- reran focused verification and live runs to confirm exported telemetry
+
+## Runtime profile outcome
+
+Both target profiles now resolve skill policy successfully with:
+- configured skills directories
+- default trust tier set to `internal`
+- policy-eligible and runtime-loaded skills available
+
+## Verification outcome
+
+Phase 125 verification script:
+- `8/8` checks passed
+
+Focused tests passed:
+- `test_skill_manager_focus.py`
+- `test_requirement_analysis.py`
+
+## Live verification evidence
+
+### CL-002 targeted live run
+Thread:
+- `phase125-live-cl002-20260321-152735`
+
+Outcome:
+- live artifact produced successfully
+- row outcome remained an audit `FAIL`
+- this confirmed skill-runtime telemetry was landing in artifacts
+- current Phase 131 follow-up migrates this row to the dedicated `public-interface-boundary-skill` lane instead of the broader architecture-compliance lane
+- when multiple repos in the same project need CL-002 review, prefer one shared `vds-cli public-interface scan-project` artifact as companion context and keep final row verdicts repo-grounded
+
+### CL-004 dependency-cycle live runs
+Threads:
+- `phase125-live-cl004b-20260321-160748`
+- `phase125-live-cl004c-20260321-161407`
+
+Confirmed in exported artifacts:
+- `skill_policy_retry.recommended_skills` now converges to:
+  - `circular-dependency-skill`
+- prompt tool telemetry recorded actual use of:
+  - `load_skill`
+  - `read_skill_resource`
+- effective usage recorded for `circular-dependency-skill`
+- final interpretation fix confirmed in live artifact:
+  - `skills_needed: true`
+  - `skills_needed_reason: requirement_keyword:circular dependency`
+  - `skill_objectives: ["analyze_dependency_cycles"]`
+- closure-grade `CL-004` pass export must preserve project-scope artifact refs:
+  - `project-dependency-graph.json`
+  - `project-cycle-report.json`
+  - `project-topology.json`
+  and must not collapse to repo-local fallback refs such as `mvnw.cmd`
+
+### Hexagonal skill status
+
+The runtime recommendation path for hexagonal rows now resolves correctly to:
+- `hexagonal-compliance-skill`
+- `research-skill`
+- `code-review-graph-skill`
+
+The PAR checklist slice used in this closure did not provide a dedicated hexagonal row equivalent to CL-004 for live execution proof, but the recommendation path and availability were verified in the main worktree runtime.
+
+## Files included in this closure
+
+### vds-scripts
+- `audit_orchestrator/scripts/verify_phase125_skill_integration.py`
+- `audit_orchestrator/src/vds_audit_orchestrator/agents/skill_manager.py`
+- `audit_orchestrator/src/vds_audit_orchestrator/engine/row_evaluator_types.py`
+- `audit_orchestrator/src/vds_audit_orchestrator/engine/skill_recommendation.py`
+- `audit_orchestrator/tests/test_agents/test_skill_manager_focus.py`
+- `audit_orchestrator/tests/unit/engine/test_requirement_analysis.py`
+- `docs/phases/phase125_skill_runtime_closure_20260321.md`
+
+### vds-skills
+- `skills/hexagonal-compliance-skill/QUALITY.md`
+
+## Commit intent
+
+This closure commit is intentionally scoped to Phase 125 skill runtime alignment only.
+Unrelated dirty files already present in the main worktree are excluded.

package/skills/vds-skill/vds-scripts/docs/phases/phase2-portable-paths/closure-handoff-summary-2026-03-23.md

@@ -0,0 +1,290 @@
+# Phase 2 closure handoff summary
+
+Date: 2026-03-24
+Phase: WHO ecosystem alignment - Phase 2 portable path/config cleanup
+Status: closure-ready
+
+## Purpose
+
+This note is the closure-oriented handoff summary for the active Phase 2 portable-path worktree.
+It records what is already implemented, what was validated, what remains intentionally deferred,
+and what the next recommended actions are for clean phase closure.
+
+## Worktree
+
+Active implementation lane:
+
+- `WHO-project/worktrees/vds-scripts-phase2-portable-paths`
+
+Primary intent of this lane:
+
+- remove hardcoded machine-specific path assumptions from maintained runtime surfaces,
+- establish a shared portable path/config model,
+- align maintained docs/help/spec text with the actual implementation state,
+- and produce honest validation evidence across supported verification lanes.
+
+## Executive summary
+
+Phase 2 is no longer primarily a migration-design effort.
+The shared path/config architecture is already implemented in the active worktree, focused regression
+coverage exists, major CLI surfaces were exercised, and portability guidance/evidence docs were added.
+
+This lane is now best treated as a closure-ready implementation and evidence packet:
+
+- maintained validation docs are aligned to the active contract,
+- canonical defaults and compatibility behavior are distinguished in maintained guidance,
+- validation evidence has been consolidated into maintained closure documents,
+- and native Windows claims remain explicitly deferred until a real Windows execution lane exists.
+
+## Implemented core architecture
+
+The active worktree implements the intended shared path/config model through:
+
+- `vds_cli_common/src/vds_cli_common/paths.py`
+- `vds_cli_common/src/vds_cli_common/env.py`
+- `vds_cli/src/vds_cli/env.py`
+
+Key implemented decisions:
+
+- shared path/config helper lives in `vds_cli_common.paths`,
+- the active friendly default uses a user-home VDS root (`~/.vds` on Unix-like systems),
+- explicit overrides are supported via:
+  - `VDS_CONFIG_DIR`
+  - `VDS_CACHE_DIR`
+  - `VDS_DATA_DIR`
+  - `VDS_LOG_DIR`
+  - `VDS_ENV_FILE`
+- maintained runtime surfaces use override-first resolution and otherwise fall back to the canonical user-home VDS defaults,
+- the shared env file default remains `<config-root>/.env`
+
+## Maintained runtime and doc alignment completed in this lane
+
+The worktree includes broad maintained-surface cleanup so user-facing behavior and guidance now better
+match the shared helper contract.
+
+Representative maintained surfaces touched in this lane include:
+
+- `audit_orchestrator/src/vds_audit_orchestrator/config.py`
+- `audit_orchestrator/src/vds_audit_orchestrator/cli_impl.py`
+- `audit_orchestrator/src/vds_audit_orchestrator/collectors/material_cache.py`
+- `audit_orchestrator/src/vds_audit_orchestrator/engine/project_topology.py`
+- `audit_orchestrator/src/vds_audit_orchestrator/evidence/loader.py`
+- `audit_orchestrator/src/vds_audit_orchestrator/extract_cmds.py`
+- `git_orchestrator/src/vds_git_orchestrator/orchestrator.py`
+- `confluence_orchestrator/src/confluence_orchestrator/config.py`
+- `sonarqube_orchestrator/src/vds_sonarqube_orchestrator/config.py`
+- `vds_cli/README.md`
+- `docs/agents/reference/portable-paths-and-config.md`
+- `docs/agents/reference/portable-paths-validation-matrix.md`
+
+## Focused regression coverage now present
+
+Focused regression tests exist in the active worktree for the shared helper and the main Phase 2
+audit/bootstrap path behavior.
+
+Representative tests:
+
+- `vds_cli_common/tests/test_paths.py`
+- `vds_cli_common/tests/test_env.py`
+- `audit_orchestrator/tests/test_paths_config_phase2.py`
+- `audit_orchestrator/tests/test_cli_paths_phase2.py`
+- `audit_orchestrator/tests/unit/scripts/test_verify_phase124_handoff.py`
+
+These tests support the claim that the first-wave portability implementation is already in place.
+Remaining work is evidence consolidation, not initial test creation.
+
+## Validation evidence summary
+
+Authoritative evidence note:
+
+- `docs/phases/phase2-portable-paths/verification-evidence-2026-03-23.md`
+
+Maintained validation guidance:
+
+- `docs/agents/reference/portable-paths-validation-matrix.md`
+- `docs/agents/reference/portable-paths-and-config.md`
+
+### Verified lanes
+
+#### 1. `native-macos`
+
+Status: pass
+
+Phase 2 host-native verification covered:
+
+- shared helper precedence and user-home VDS default behavior,
+- shared env loading behavior,
+- audit config/report/log default behavior,
+- and focused CLI/bootstrap checks.
+
+#### 2. `docker-ubuntu`
+
+Status: pass
+
+The supported Linux verification lane now runs through the compose-based path:
+
+- `docker/compose.phase2-verification.yml`
+- supported verification script under `scripts/verification/`
+
+Important outcome:
+
+- the Docker Ubuntu lane found real portability issues,
+- those issues were fixed in this worktree,
+- and the focused Linux verification packs now pass through the supported compose path.
+
+#### 3. `windows-simulated`
+
+Status: pass
+
+Current Windows-oriented evidence is contract-based rather than native:
+
+- helper precedence/path logic,
+- docs and examples using override variables,
+- and explicit avoidance of hardcoded POSIX-only examples in maintained guidance.
+
+#### 4. `windows-native`
+
+Status: deferred
+
+No native Windows host or CI runner was used in this phase.
+Phase 2 must not claim native Windows verification until a real Windows lane produces evidence.
+
+## Maintained contract interpretation
+
+Maintained Phase 2 surfaces now use one friendly contract.
+That contract should be interpreted as:
+
+- explicit env overrides win,
+- otherwise config/cache/data/log roots resolve from the canonical user-home VDS defaults,
+- the shared env file resolves from `VDS_ENV_FILE` or `<config-root>/.env`,
+- maintained docs and examples should advertise only the active override-plus-user-home-VDS contract.
+
+## Notable defects discovered and fixed during live verification
+
+This lane surfaced real code issues, not only doc drift.
+
+Examples fixed during live verification included:
+
+- import-breaking stray token in `audit_orchestrator/src/vds_audit_orchestrator/extract_cmds.py`
+- syntax issue in `sonarqube_orchestrator/src/vds_sonarqube_orchestrator/cli.py`
+- corrupted trailing fragment in `git_orchestrator/src/vds_git_orchestrator/orchestrator.py`
+- missing `get_shared_env_path` import in `elastic_orchestrator/src/vds_elastic_orchestrator/cli.py`, which previously broke the structured config-error path during `vds-cli elastic --json-only ping`
+- Jira `projects` raw credential traceback replaced with clean settings-driven CLI error handling in `jira_orchestrator/src/vds_jira_orchestrator/cli.py`
+- Bitbucket `projects` silent credential failure replaced with an operator-facing error in `bitbucket_orchestrator/src/vds_bitbucket_orchestrator/cli.py`
+
+These fixes matter for closure because they demonstrate that Phase 2 validation exercised real runtime
+entrypoints rather than only static text cleanup.
+
+## Phase 2 spec alignment status
+
+Spec location:
+
+- `.gpt-5.4/specs/who-ecosystem-alignment/`
+
+Current alignment posture:
+
+- the spec reflects that the shared helper architecture is implemented,
+- the Phase 2 `TSK-2.2x` / `TSK-2.3x` task block now reads as implemented and closure-ready where that matches the active worktree,
+- the validation matrix and evidence template are maintained, executed surfaces rather than hypothetical planning artifacts,
+- and native Windows remains explicitly deferred rather than implicitly open-ended.
+
+Spec tasks most relevant to the closure claim set:
+
+- `TSK-2.27`
+- `TSK-2.32`
+- `TSK-2.33`
+- `TSK-2.34`
+- `TSK-2.35`
+
+Interpretation of these tasks now:
+
+- implemented in code/docs/evidence,
+- closure-ready under the current truthful claim set,
+- with future work limited mainly to Windows-native validation or ordinary maintenance.
+
+## CLI verification posture
+
+Exported CLI entrypoints were verified from their owning package environments with `--help` and responded successfully across the active worktree surface, including the routed CLIs, standalone orchestrators, and hook scripts.
+
+Live read-only probes also confirmed the expected distinction between code defects and environment readiness:
+
+- the active shared env path now resolves from `~/.vds/.env` on the current Unix-like host, confirming the friendly `~/.vds` default is live rather than only documented
+- `vds-cli env status`, `vds-cli doctor`, and `vds-cli status` all succeed under that active `~/.vds` contract and report healthy shared-auth/bootstrap and router availability state
+- `vds-cli jira-cli --json-only projects` succeeds with authenticated data, and `vds-cli jira-cli search "project = CBDC ORDER BY updated DESC" --limit 3 --json-only` succeeds as an authenticated JQL feature probe; in the latest bounded run it returned `0` issues rather than an auth or transport failure
+- `vds-cli bitbucket-cli --json-only projects` succeeds with authenticated data, and `vds-cli bitbucket-cli --json-only repositories WHO --limit 5` succeeds with authenticated repository listing output
+- `vds-cli confluence-cli search --server internal --cql "type=page" --limit 1` succeeds with authenticated data and returns a real page result
+- `vds-cli elastic --json-only ping` succeeds in the current runtime and returns a healthy structured response with Kibana connection details
+- `vds-cli sonarqube --json-only ping` succeeds and reports an `up` status with server version data
+- `vds-cli grafana --json-only health` succeeds and reports healthy Grafana and datasource status
+- `vds-cli git list --match "*vds*"` succeeds through the routed manifest path and lists the expected VDS repositories
+- `vds-cli spec validate who-ecosystem-alignment` succeeds, reinforcing that the maintained spec surface remains aligned
+- `vds-cli audit --json-only doctor profile-availability --profiles zai-openai --mode active` currently reports `profile_not_found` for the local runtime profiles file rather than exposing a portability defect
+
+Continued one-by-one CLI verification also surfaced two additional operator-facing defects that were fixed during this closure pass:
+
+- `vds-subagent-stop-hook --help` originally emitted a coroutine-not-awaited runtime warning because `vds_hooks/src/vds_hooks/scripts/subagent_stop.py` had a corrupted duplicated tail; that corruption was removed and the help surface now runs cleanly
+- `vds-cli mcp-server --help` originally lacked a usable help path; a minimal explicit help surface was added in `mcp_server/src/vds_mcp_server/server.py`, a follow-on missing `sys` import was fixed, and the command now emits clean usage text
+
+This means the remaining live-probe failures are primarily environment/profile readiness issues, not maintained Phase 2 path-contract drift.
+
+## Deferred or future-only items
+
+The Phase 2 portability scope is closure-ready. The remaining items are intentionally outside the current truthful claim set.
+A maintained remaining-risk register now lives at `docs/phases/phase2-portable-paths/remaining-risk-register-2026-03-25.md`.
+
+### 1. Native Windows remains deferred
+
+Still required for any stronger claim:
+
+- Windows host or CI execution,
+- PowerShell or CMD validation,
+- native filesystem/path semantics evidence.
+
+### 2. Optional future polish
+
+Non-blocking follow-up work may still be useful when convenient:
+
+- keep maintained guidance free of accidental machine-specific examples,
+- keep maintained surfaces on one explicit-override-plus-user-home-VDS contract,
+- and continue normalizing broad docs/help examples when they are touched for unrelated work.
+
+## What is intentionally not required for closure
+
+The following are not blockers for truthful Phase 2 closure:
+
+- removal of all historical references in archived or generated artifacts,
+- claiming native Windows verification without a real Windows lane,
+- broad new migration work beyond the already-implemented shared helper model.
+
+## Recommended next actions
+
+1. Treat the Phase 2 lane as a completed portability implementation with maintained closure evidence, not a fresh migration pass.
+2. Keep `portable-paths-validation-matrix.md` and the evidence note as the maintained closure sources.
+3. Re-run targeted validation only if maintained portability surfaces change again.
+4. Present closure using this claim set only:
+   - native macOS validation,
+   - Docker-based Ubuntu/Linux validation,
+   - Windows-oriented simulation/contract validation,
+   - native Windows deferred.
+
+## Closure-ready claim set
+
+The current lane can truthfully claim:
+
+- core shared path/config migration is implemented,
+- maintained runtime/help/docs cleanup is closure-ready,
+- focused regression coverage exists,
+- native macOS verification passed,
+- Docker-based Ubuntu verification passed through the supported compose lane,
+- Windows-oriented simulation/contract coverage exists,
+- native Windows verification remains deferred.
+
+## Handoff note
+
+Use this document together with:
+
+- `docs/phases/phase2-portable-paths/verification-evidence-2026-03-23.md`
+- `docs/agents/reference/portable-paths-validation-matrix.md`
+- `.gpt-5.4/specs/who-ecosystem-alignment/tasks.md`
+
+when preparing the final Phase 2 closure statement or handing the lane to the next reviewer.

package/skills/vds-skill/vds-scripts/docs/phases/phase2-portable-paths/remaining-risk-register-2026-03-25.md

@@ -0,0 +1,143 @@
+# Phase 2 remaining risk register
+
+Date: 2026-03-25
+Status: maintained
+Scope: WHO ecosystem alignment Phase 2 portable path/config closure posture
+
+This note records the remaining risks after the Phase 2 portable path/config work reached a closure-ready state.
+It distinguishes maintained-surface risks from historical/generated artifacts and from explicitly deferred validation lanes.
+
+## Risk classification
+
+| Risk class | Status | Meaning |
+| --- | --- | --- |
+| Maintained portability defect | none currently confirmed | A current code/doc/help surface still violates the active Phase 2 contract |
+| Environment/profile readiness | present but non-blocking | A live probe depends on missing local service/profile config rather than a path defect |
+| Historical/generated artifact drift | present | Old reports, summaries, generated files, or archived artifacts still contain host-specific examples |
+| Native Windows verification gap | explicitly deferred | Contract/simulation coverage exists, but no native Windows host/CI evidence exists |
+| Non-core package/platform variance | present but bounded | Package-specific platform logic exists outside the core shared path/config contract |
+
+## Current maintained-surface assessment
+
+Current conclusion:
+- no confirmed maintained Phase 2 path/config defects remain in the core shared-helper lane after rebasing onto latest `master` and rerunning focused verification
+- maintained docs, guides, skills, and help surfaces now consistently advertise the explicit-override-plus-user-home-VDS contract
+- direct executable discovery for AI agents improved materially through the verified help matrix and direct-help fixes
+
+## Remaining risks by category
+
+### 1. Native Windows verification remains deferred
+
+Status: deferred by design
+
+What is true now:
+- Windows-oriented simulation/contract coverage exists
+- path semantics and naming guidance explicitly account for Windows-oriented environments
+- the spec and validation matrix explicitly distinguish `windows-simulated` from `windows-native`
+
+What is still missing:
+- real Windows host or CI execution
+- PowerShell/CMD validation evidence
+- native filesystem/path semantics proof on Windows itself
+
+Current impact:
+- Phase 2 must not claim native Windows verification
+- this is a truthful-claims boundary, not a known Unix-like runtime defect
+
+### 2. Environment/profile readiness remains a live-probe variable
+
+Status: present but non-blocking
+
+Observed example:
+- `vds-cli audit --json-only doctor profile-availability --profiles zai-openai --mode active` still reports `profile_not_found` in the local runtime
+
+Interpretation:
+- this is a local profile readiness/configuration issue
+- it is not evidence of a shared path/config regression
+
+Current impact:
+- bounded live verification should continue to distinguish environment readiness failures from portability failures
+
+### 3. Historical and generated artifacts still contain host-specific paths
+
+Status: present
+
+Observed examples include:
+- old phase summaries and implementation reports with `/Users/...` paths
+- generated JSON artifacts and validation outputs containing historical local file paths
+- archived or compatibility materials that still mention direct `~/.vds/...` examples without the newer `<config-root>` abstraction language
+
+Interpretation:
+- these artifacts are not the maintained Phase 2 source of truth
+- they should not be used to contradict the maintained closure claim set
+
+Current impact:
+- low risk to runtime correctness
+- moderate risk to human readers if historical artifacts are mistaken for current guidance
+
+Recommended handling:
+- treat cleanup as opportunistic follow-up rather than a Phase 2 closure blocker
+
+### 4. Non-core package/platform variance still exists
+
+Status: present but bounded
+
+Observed examples include:
+- package-specific platform logic in `vds_hooks`
+- WSL/Windows path conversion helpers in `lsp_orchestrator`
+- package-local installer/platform settings outside the core shared helper model
+
+Interpretation:
+- these are not currently confirmed violations of the Phase 2 core shared path/config contract
+- they represent adjacent platform behavior that may need separate modernization later
+
+Current impact:
+- low risk to the core Phase 2 closure packet
+- medium follow-up value for future platform hardening work
+
+### 5. Direct executable naming remains a documentation hazard without the help matrix
+
+Status: mitigated in maintained docs
+
+What changed:
+- `vds-task` compatibility alias was added
+- `vds-diagrams` and `vds-cli schema-convert` now expose structured Typer help surfaces
+- `docs/agents/reference/cli-help-matrix.md` now records routed families, direct executable names, and verified `--help` status
+
+Residual risk:
+- future packages can still drift if direct executable names change without docs updates
+
+Recommended handling:
+- treat `--help` verification and the CLI help matrix as maintained alignment surfaces
+
+## Live verification summary backing this register
+
+After rebasing onto latest `master`, the following remained live-verified:
+- `vds-cli env status`
+- `vds-cli status`
+- `vds-cli doctor`
+- `vds-cli jira-cli --json-only projects`
+- `vds-cli bitbucket-cli --json-only projects`
+- `vds-cli bitbucket-cli --json-only repositories WHO --limit 5`
+- `vds-cli confluence-cli search --server internal --cql "type=page" --limit 1`
+- `vds-cli elastic --json-only ping`
+- `vds-cli sonarqube --json-only ping`
+- `vds-cli grafana --json-only health`
+- `vds-cli git list --match "*vds*"`
+- direct help surfaces including `vds-task`, `vds-diagrams`, `vds-schema-convert`, `vds-cli mcp-server`, and `vds-subagent-stop-hook`
+
+## Risk posture for closure
+
+Phase 2 remains closure-ready under this truthful claim set:
+- native macOS validation passed
+- Docker-based Ubuntu/Linux validation passed through the supported compose lane
+- Windows-oriented simulation/contract validation exists
+- native Windows remains explicitly deferred
+- no confirmed maintained core shared-helper portability defect remains open
+
+## Recommended next actions
+
+1. Keep this register linked from the closure handoff packet.
+2. Treat native Windows as the primary explicit future validation gap.
+3. Treat historical/generated artifact cleanup as opportunistic, not blocking.
+4. Keep the CLI help matrix maintained whenever direct executable names or help surfaces change.

package/skills/vds-skill/vds-scripts/docs/phases/phase2-portable-paths/verification-evidence-2026-03-23.md

@@ -0,0 +1,135 @@
+# Phase 2 portability verification evidence
+
+Date: 2026-03-24
+Status: validated and closure-ready
+Scope: WHO ecosystem alignment Phase 2 portable path/config work
+
+This note records the actual verification evidence produced during the current Phase 2 implementation pass.
+It follows the validation lanes defined in `docs/agents/reference/portable-paths-validation-matrix.md`.
+
+## Evidence summary
+
+| Lane | Status | Notes |
+| --- | --- | --- |
+| `native-macos` | pass | Focused Phase 2 helper/audit tests passed on the active macOS host |
+| `docker-ubuntu` | pass | Compose-based Ubuntu verification now passes end-to-end in real Linux userspace using the supported verification script and the focused Phase 2 test packs |
+| `windows-simulated` | pass | Covered by helper/docs/contracts and placeholder-based path examples |
+| `windows-native` | deferred | No real Windows host or CI runner used in this phase |
+
+## 1. Native macOS evidence
+
+Focused host-native commands run successfully during the implementation pass.
+
+Validated areas:
+- shared helper precedence and user-home VDS default behavior
+- `vds_cli` shared env loading behavior
+- `audit_orchestrator` config/report/log default behavior
+- Phase 124 handoff command-pack portability expectations
+
+Observed result:
+- focused Phase 2 host-native test pack passed
+
+## 2. Docker Ubuntu evidence
+
+Compose-based verification command:
+- `docker compose -f docker/compose.phase2-verification.yml run --rm phase2-ubuntu-verifier`
+
+Observed result:
+- the Ubuntu/Linux lane successfully exercised the mounted worktree in real Linux userspace and exposed real portability issues that were then fixed
+- after those fixes, later reruns no longer failed on the original path-layout bugs
+- the supported compose-based verification script now passes end-to-end with the focused Linux Phase 2 verification packs
+- latest successful Linux results from the supported lane:
+  - `vds_cli_common/tests/test_paths.py` + `vds_cli_common/tests/test_env.py`: `15 passed`
+  - `audit_orchestrator/tests/test_paths_config_phase2.py` + `audit_orchestrator/tests/unit/scripts/test_verify_phase124_handoff.py`: `4 passed`
+  - `audit_orchestrator/tests/test_cli_paths_phase2.py`: `2 passed`
+
+Important findings during verification:
+- the first Ubuntu compose runs exposed a real portability bug in `audit_orchestrator/scripts/verify_phase124_handoff.py`
+- the script assumed a host-specific workspace layout and monorepo-relative command path posture
+- the bug was fixed by resolving workspace roots and script-path prefixes dynamically so the helper works in:
+  - monorepo root layout
+  - direct `vds-scripts` worktree layout
+  - compose-mounted `/workspace` layout
+- an additional operational issue appeared when the container tried to reuse the mounted host `.venv`
+- the compose verification lane was updated to use `UV_PROJECT_ENVIRONMENT=/tmp/phase2-uv-env` so Linux verification uses a container-local environment instead of mutating or depending on the mounted host environment
+- the Docker lane was further updated to use `UV_CACHE_DIR=/tmp/phase2-uv-cache`, `UV_HTTP_TIMEOUT=120`, `UV_LINK_MODE=copy`, and a persistent compose volume for the uv cache so Linux verification is easier to debug and less dependent on repeated cold-start bootstrap
+- the supported compose command was narrowed to the focused Phase 2 Linux verification packs so the lane proves the path/config work directly instead of spending most runtime on unrelated full-project dependency setup
+
+Current interpretation:
+- this lane now provides a passing `docker-ubuntu` result for the focused Phase 2 portability scope
+- the remaining caveat is operational rather than functional: the original full-project audit environment bootstrap was much heavier than needed for the actual Phase 2 path/config assertions
+- the supported verification lane now uses the focused real-Linux checks that directly prove the Phase 2 portability behavior
+
+Those fixes are part of the Phase 2 evidence because they were discovered by the Linux verification lane, not by the original host-only test pass.
+
+## 3. Windows-simulated evidence
+
+Current Windows-oriented evidence comes from:
+- shared helper/tests that validate override precedence and path/config behavior without assuming POSIX shell-only setup
+- docs and references that explicitly document Windows-oriented env/path override usage
+- placeholder-based repo-cache/report-root command examples instead of hardcoded POSIX-only examples
+- explicit spec/docs language distinguishing simulation from native Windows verification
+
+This lane supports a claim of `windows-simulated`, not `windows-native`.
+
+## 4. Deferred Windows-native evidence
+
+Not executed in this phase.
+
+Required future environments for true Windows-native validation:
+- Windows CI runner
+- Windows VM
+- or an operator-run Windows host with PowerShell/CMD validation evidence
+
+## 5. Live CLI verification refresh (2026-03-24)
+
+A fresh bounded live-verification sweep was rerun from the active Phase 2 worktree using package-direct `uv run --project ...` entrypoints so each CLI was exercised from its owning package environment.
+
+Commands exercised in this refresh included:
+- `vds-cli env status`
+- `vds-cli audit --json-only doctor profile-availability --profiles zai-openai --mode active`
+- `vds-cli elastic --json-only ping`
+- `vds-cli jira-cli --json-only projects`
+- `vds-cli jira-cli search "project = CBDC ORDER BY updated DESC" --limit 3 --json-only`
+- `vds-cli bitbucket-cli --json-only projects`
+- `vds-cli bitbucket-cli --json-only repositories WHO --limit 5`
+- `vds-cli confluence-cli search --server internal --cql "type=page" --limit 1`
+- `vds-cli git list --match "*vds*"`
+
+Observed results:
+- `vds-cli env status` succeeded and resolved the shared env file from the active VDS config root
+- `vds-cli jira-cli --json-only projects` succeeded and returned authenticated project data
+- `vds-cli jira-cli search "project = CBDC ORDER BY updated DESC" --limit 3 --json-only` succeeded as a real authenticated JQL call; in this bounded run it returned `0` issues rather than a transport or auth failure
+- `vds-cli bitbucket-cli --json-only projects` succeeded and returned authenticated project data
+- `vds-cli bitbucket-cli --json-only repositories WHO --limit 5` succeeded and returned repository data including `vds-scripts` and `vds-skills`
+- `vds-cli confluence-cli search --server internal --cql "type=page" --limit 1` succeeded and returned a real page result
+- `vds-cli elastic --json-only ping` succeeded in the current runtime and returned a healthy structured response including Kibana connection details
+- `vds-cli git list --match "*vds*"` succeeded and listed the expected WHO/insurance VDS repositories from the active manifest routing path
+- `vds-cli audit --json-only doctor profile-availability --profiles zai-openai --mode active` still reports `profile_not_found` for the local runtime profiles file rather than exposing a path-contract defect
+
+Current interpretation of the refresh:
+- no new maintained Phase 2 path/config regressions were found in the bounded live probes
+- the active runtime now proves the friendly `~/.vds` default end to end because `vds-cli`, JIRA, Bitbucket, Confluence, Elastic, and routed Git all executed successfully against the active shared environment on the current Unix-like host
+- the remaining observed non-successful probe in this bounded pass is limited to local audit profile readiness rather than a portable-path implementation defect
+- this refresh strengthens the closure claim that the maintained path/config work is functioning end to end in real CLI usage, not only in focused test packs
+
+Additional CLI-surface verification after the refresh found and fixed two operator-facing anomalies in the active worktree:
+- `vds-subagent-stop-hook --help` originally emitted a `RuntimeWarning: coroutine 'main' was never awaited` because `vds_hooks/src/vds_hooks/scripts/subagent_stop.py` contained a corrupted duplicated tail; the trailing corruption was removed and the help surface now runs cleanly
+- `vds-cli mcp-server --help` originally did not emit a usable help surface because the entrypoint lacked explicit help handling; after adding a minimal help path, a missing `sys` import surfaced and was fixed; the command now prints a clean usage/help message
+
+Interpretation of these follow-up fixes:
+- they were real CLI-surface defects discovered by the continued live verification sweep rather than path-contract regressions
+- both defects are now fixed and reverified in the active Phase 2 worktree
+- the later JIRA `search --json-only` inconsistency was also narrowed to CLI option placement, patched so command-local `--json-only` is accepted, and reverified with a real authenticated JQL search call
+
+## Decision
+
+Current Phase 2 work can honestly claim:
+- native macOS validation
+- Docker-based Ubuntu/Linux validation through the supported compose verification lane
+- Windows-oriented simulation/contract validation
+
+Current Phase 2 work must not claim:
+- native Windows verification
+
+until a real Windows execution environment is used.