@ngocsangairvds/vsaf 4.1.8 → 4.1.9

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

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

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

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

@@ -1,135 +0,0 @@
-# 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.