@ngocsangairvds/vsaf 3.2.14 → 3.2.15

package/tools/vds-scripts/ECOSYSTEM_ALIGNMENT.md

@@ -1,133 +0,0 @@
-# VDS-Evolution Ecosystem Alignment Report
-
-## Status: FULLY ALIGNED ✓
-
----
-
-## System Components
-
-| Component | Location | Status |
-|-----------|----------|--------|
-| Scripts Repo | vds-scripts/ | HEAD: f7158c9 |
-| Mono .venv | vds/.venv/ | 52 lines, fix applied |
-| Tracked Shell | vds-evolution-mono.sh | Synced with mono |
-| env.py | vds_cli_common/src/ | Permanently patched |
-| router.py | vds_cli/src/ | Root-layout fix applied |
-
----
-
-## Root Cause: Openspace __path_hook__
-
-The openspace package installs a custom PathEntryFinder in `sys.path_hooks`:
-
-1. **PATH_PLACEHOLDER** is added to `sys.path`:
-   ```
-   '__editable__.openspace-0.1.0.finder.__path_hook__'
-   ```
-
-2. **sys.path_hooks** is modified to include `_EditableNamespaceFinder`
-
-3. **When Python imports vds_evolution**:
-   - Iterates through `sys.path`
-   - Encounters PATH_PLACEHOLDER
-   - Calls path_hooks to get PathEntryFinder
-   - Openspace hook interferes with the import resolution
-
-4. **Result**: `find_spec()` returns `None` even though:
-   - `sys.path` contains the absolute path to vds_evolution
-   - The directory exists with `__init__.py`
-
-5. **Why CWD matters**:
-   - From scripts_repo: CWD + sys.path already primed
-   - From /tmp: PATH_PLACEHOLDER breaks the path iteration
-
----
-
-## Fix Applied: spec_from_file_location
-
-All three scripts use this workaround:
-
-```python
-import importlib.util
-
-# Bypass sys.path_hooks, directly load from file
-spec = importlib.util.spec_from_file_location(
-    "vds_evolution",
-    "/path/to/vds_evolution/__init__.py"
-)
-module = importlib.util.module_from_spec(spec)
-sys.modules["vds_evolution"] = module
-spec.loader.exec_module(module)
-```
-
-This bypasses the entire `sys.path_hooks` machinery and loads directly from known file paths.
-
----
-
-## UV Usage Assessment
-
-**Current approach: CORRECT**
-
-- `uv pip install -e` for editable development installs ✓
-- Manual script fix for the openspace hook edge case ✓
-- Editable install preserves source editing capability
-
-**Alternative approaches considered**:
-- Non-editable install: Would fix the hook issue, but loses source editing
-- uv tool install: Global install, may still hit hook issue
-
-**Recommendation**: Keep current approach, document the openspace hook issue.
-
----
-
-## Repo-Boundary Component Status (per `who-ecosystem-alignment` Phase 4)
-
-Phase 4 of `who-ecosystem-alignment` codifies the canonical separation between
-`vds-scripts` (runtime Python only) and `vds-skills` (Claude-Code-facing
-artifacts). Components in this repo that intersect the boundary rules:
-
-| Component | Phase 4 status | Resolution path |
-|---|---|---|
-| `vds-scripts/vds_hooks/` (Python package) | **Retiring per FR-12** (Hook home: plugin format under `vds-skills/plugins/vds-hooks-*/` is the sole canonical hook surface) | `vds-hooks-claude-plugin-packaging` Phase 6 deletes the package (90 tracked files, 1.1 MB tracked content) |
-| `vds-scripts/.claude/skills/gitnexus/` (vendored skill mirror) | **Violates FR-11** (Vendoring policy: `vds-scripts` MUST NOT contain `.claude/skills/<name>/`) | `vds-skills-catalog-alignment-cleanup` Phase 5 deletes the 6 vendored sub-skills + adds `.gitignore` rule preventing regeneration |
-| `vds-scripts/*_orchestrator/` (31 orchestrators) | **Classified per FR-17** (Orchestrator coverage classification): 9 Tier A (have a corresponding skill), 0 Tier B (candidate for promotion), 22 Tier C (covered by `vds-scripts-skill` umbrella or too minimal) | No skill-creation work required; classification table in `who-ecosystem-alignment` Phase 4 design.md |
-| `vds-cli`, `mcp_server`, `platform_core`, `vds_agent_core`, `vds_evolution`, etc. | **In scope per FR-8** (Repo purpose: runtime Python only) | No change; these are exactly what vds-scripts SHOULD hold |
-
----
-
-## Git State
-
-```
-HEAD: f7158c9 docs: add first-audit-run tutorial (FR-1.5 gap fill)
-Status: Clean (pushed to origin)
-Worktrees: 1 (scripts repo only)
-```
-
----
-
-## Functional Tests
-
-| Test | Result |
-|------|--------|
-| scripts .venv status | ✓ OK |
-| mono .venv status | ✓ OK |
-| mono from /tmp | ✓ OK |
-| mono from scripts_repo | ✓ OK |
-| tracked shell | ✓ OK |
-
----
-
-## Key Findings
-
-1. **Scripts consistency**: All 3 scripts use spec_from_file_location fix
-2. **Mono matches tracked**: vds-evolution-mono.sh == mono/.venv/bin/vds-evolution
-3. **Openspace hook**: Present in mono .venv, bypassed by fix
-4. **Root cause**: sys.path_hooks modification by openspace
-5. **Fix verified**: Works from any CWD
-6. **Git clean**: All changes pushed
-
----
-
-## Conclusion
-
-The ecosystem is fully aligned and functioning correctly. The openspace __path_hook__ is a known issue with mixed venv environments (OpenSpace + vds-evolution). The spec_from_file_location workaround is the correct solution for this scenario.

package/tools/vds-scripts/ENV-HYGIENE-OPS-NOTE.md

@@ -1,65 +0,0 @@
-# VAMI-012 Follow-Up — Local `.env` Hygiene (Findings 1 & 2)
-
-**Date**: 2026-04-18
-**Scope**: operational (non-committable — `.env` is gitignored and lives only in the master checkout).
-
-## Why this file exists
-
-The file `memory_orchestrator/.env` is **gitignored** (see repo `.gitignore` lines matching `.env`). It does not exist in source control and cannot be modified via a branch-commit workflow. This note records the two operational edits performed to the live master checkout so future operators / auditors can reproduce them.
-
-## Target file
-
-```
-/Users/vds-ai/Library/Mobile Documents/com~apple~CloudDocs/project/vds/WHO-project/vds-scripts/memory_orchestrator/.env
-```
-
-Timestamped backup created before editing:
-```
-memory_orchestrator/.env.bak-20260418-110716
-```
-
-## Finding 1 — `MEM0_API_KEY` duplicated locally
-
-**Rubric**: sensitivity=high, coupling=low, portability=high → GLOBAL (`~/.vds/.env`).
-
-Removed from local `.env`. Source of truth remains `~/.vds/.env`.
-
-### Verification
-
-```bash
-# Compose loads both files via env_file:
-#   - .env                  (project-local)
-#   - ${HOME}/.vds/.env     (platform global)
-docker compose -p vds-platform -f docker/docker-compose.infra.yml -f docker/docker-compose.services.yml restart memory-api  # post-v2.15.12: legacy memory_orchestrator/compose.yaml is gone (was retired to docker/legacy/ in P4 WP-4.0; that directory removed v2.15.12 per no-legacy directive — recover via git if needed)
-docker exec vds-ai-memory-api-1 bash -c 'echo "len=${#MEM0_API_KEY}"'
-# Expected: len=43  (confirms key still present, loaded from ~/.vds/.env)
-```
-
-Verified 2026-04-18 11:07 local. Key length 43 (matches the `m0-*` value in `~/.vds/.env`; redacted here).
-
-## Finding 2 — `MEM0_QDRANT_PORT=6335` dead-code
-
-Docker Compose precedence: `environment:` overrides `env_file:`. `compose.yaml` lines 94/146/204 hardcode `MEM0_QDRANT_PORT: 6333` in the `environment:` block on api / worker / beat. The `.env` value `MEM0_QDRANT_PORT=6335` never reached any in-container process.
-
-Removed from local `.env`.
-
-### Verification
-
-```bash
-docker exec vds-ai-memory-api-1 bash -c 'echo "$MEM0_QDRANT_PORT"'
-# Expected: 6333  (from compose environment: block, unchanged)
-```
-
-Verified 2026-04-18 11:07 local. Port still 6333 as expected.
-
-## Revert procedure
-
-```bash
-cd "/Users/vds-ai/.../WHO-project/vds-scripts/memory_orchestrator"
-cp .env.bak-20260418-110716 .env
-docker compose restart api
-```
-
-## Why no git commit for these findings
-
-The two fixes target a gitignored runtime configuration file. Committing anything in the worktree for Findings 1 & 2 would not propagate the change — operators apply these edits against their own local `.env` or `~/.vds/.env`. This note (plus the investigation write-up) is the durable artifact.

package/tools/vds-scripts/INVESTIGATION-cloud-401.md

@@ -1,103 +0,0 @@
-# VAMI-012 Follow-Up: Cloud "401" Investigation
-
-**Date**: 2026-04-18
-**Branch**: `feat/vami012-followup`
-**Scope**: Root cause of reported `GET /v1/ping/ → 401 Unauthorized` and subsequent `mem0_add_exception:HTTPStatusError` entries.
-
-## TL;DR
-
-The 401 on `/v1/ping/` was **transient and historical** (1 occurrence in last 30m, all others older than 3 hours — at 03:31). The **current, ongoing** mem0 cloud failure is **HTTP 400 Bad Request** on `POST /v3/memories/add/`, caused by a schema mismatch in `_cloud_add()` inside `mem0_adapter.py`. The API key is correct and auth works end-to-end.
-
-## Hypotheses Tested
-
-| # | Hypothesis | Verdict |
-|---|---|---|
-| 1 | `/v1/ping/` deprecated | **REJECTED** — ping returns 200 with `Token` scheme. |
-| 2 | Wrong auth header (`Bearer` vs `Token`) | **Partially confirmed but not the issue** — mem0 SDK 2.0.0 already uses `Authorization: Token <key>` correctly. Only raw `Bearer` attempts fail (we reproduced that separately for completeness). |
-| 3 | Key prefix changed | **REJECTED** — `m0-Hx4lLCB...` authenticates cleanly; ping confirms `user_email=victory1908@gmail.com`, `org_id=org_g3nYV3jeJF1OsStnyr9DatbZQTHwWzsnOGT4y8of`. |
-| 4 | Account/org restriction | **REJECTED** — add / search / get_all all succeed when called directly. |
-| 5 | Region-specific endpoint | **REJECTED** — default `api.mem0.ai` works. |
-| 6 | Adapter `_build_cloud_client` kwargs mismatch | **REJECTED at build-client level** — ping via externally-supplied `httpx.Client` still returns 200 (auth headers are injected by SDK post-construct). |
-| 7 | Network/proxy container divergence | **REJECTED** — verified both host and container reach `api.mem0.ai` successfully. |
-
-## Root Cause (HTTP 400, current)
-
-`_cloud_add()` in `memory_orchestrator/src/vds_memory_orchestrator/service/services/mem0_adapter.py:475-484` constructs:
-
-```python
-options = AddMemoryOptions(
-    user_id=kwargs.get("user_id"),
-    agent_id=kwargs.get("agent_id"),
-    run_id=kwargs.get("run_id"),
-    metadata=kwargs.get("metadata"),
-)
-return await self._cloud_call("add", messages, options=options)
-```
-
-`AddMemoryOptions` in `mem0==2.0.0` **does not have `user_id`, `agent_id`, or `run_id` fields**. Its schema is:
-```
-['filters', 'metadata', 'infer', 'custom_categories',
- 'custom_instructions', 'timestamp', 'structured_data_schema']
-```
-
-Pydantic silently drops unknown constructor kwargs. Consequently `options.model_dump(exclude_unset=True)` returns only `{"metadata": {...}}`. The SDK's `MemoryClient.add()` merges `{**options.model_dump(exclude_unset=True), **kwargs}` — but the adapter passes no extra kwargs to `_cloud_call("add", messages, options=options)`. The final payload sent to `/v3/memories/add/` has no entity ID, and the API responds:
-
-```json
-{"error":"{'non_field_errors': [ErrorDetail(string='At least one entity ID is required (user_id, agent_id, app_id, or run_id).', code='invalid')]}"}
-```
-
-### Live reproducer (run inside `vds-ai-memory-api-1`)
-
-```python
-from mem0 import AsyncMemoryClient
-from mem0.client.types import AddMemoryOptions
-import os, asyncio
-
-async def main():
-    c = AsyncMemoryClient(api_key=os.environ["MEM0_API_KEY"])
-    options = AddMemoryOptions(user_id="claude-agent", agent_id=None,
-                               run_id="sess-1", metadata={"source":"vds"})
-    await c.add([{"role":"user","content":"test"}], options=options)
-# -> httpx.HTTPStatusError: 400 Bad Request
-#    "At least one entity ID is required"
-```
-
-And contrast — the SDK's recommended form works:
-
-```python
-await c.add([{"role":"user","content":"test"}],
-            user_id="claude-agent", run_id="sess-1",
-            metadata={"source":"vds"})  # -> 202 PENDING
-```
-
-## Historical 401 Explanation
-
-The earlier `/v1/ping/` 401 entries (03:31 window) predate the container restart that picked up the fully-aligned env. Since the `.env` / `~/.vds/.env` / container env are now consistent, no new 401 has occurred (30-minute live sample: **1 stale** 401 vs **16 fresh** 400s). The 401 is not the active failure mode.
-
-## Recommended Fix (out of scope for this worktree)
-
-Modify `_cloud_add` to pass entity IDs alongside (not inside) `AddMemoryOptions`. Conceptually:
-
-```python
-async def _cloud_add(self, messages, **kwargs):
-    from mem0.client.types import AddMemoryOptions
-    options = AddMemoryOptions(metadata=kwargs.get("metadata"),
-                               infer=kwargs.get("infer"))
-    entity_kwargs = {k: kwargs[k]
-                     for k in ("user_id", "agent_id", "app_id", "run_id")
-                     if kwargs.get(k) is not None}
-    return await self._cloud_call("add", messages, options=options, **entity_kwargs)
-```
-
-Apply the same pattern to `_cloud_search` (`SearchMemoryOptions` also excludes entity fields in 2.0.0) and verify `_cloud_get_all` / `_cloud_update`.
-
-This change is **not implemented here** — it is a code mutation to the landed VAMI-012 adapter and should land as a new targeted fix (candidate: `fix(vami-012): route entity IDs outside AddMemoryOptions for mem0 2.0.0`). A dedicated ticket/spec is recommended because:
-
-1. It requires test updates covering all four cloud helpers.
-2. The OSS (self-hosted) path is unaffected — local `Memory.add()` accepts `user_id` directly; dual-mode mixing should be re-tested.
-3. The fix is user-visible only when cloud-mode or dual-mode is active (the failure currently degrades gracefully — PG storage still succeeds, only cloud sync is blocked).
-
-## Status vs. Deliverable
-
-- In-scope investigation: **complete**. Fix is identified and reproducible.
-- Code-change fix: **NOT applied**. This investigation agent is constrained to analyze rather than modify the adapter.

package/tools/vds-scripts/MEM0_2.0_API_REFERENCE.md

@@ -1,238 +0,0 @@
-# mem0 2.0.0 — Client API Reference (VAMI-012 Cloud Adapter Fix)
-
-Live-verified against `mem0==2.0.0` installed in `vds-ai-memory-api-1` on 2026-04-18. All 4 calls exercised against `https://api.mem0.ai` with HTTP 2xx.
-
-## Key Invariants (read first)
-
-1. **`AddMemoryOptions` does NOT contain `user_id` / `agent_id` / `app_id` / `run_id`.** Passing them to the constructor *silently drops them* (Pydantic extra=ignore). This is the root cause of VAMI-012's cloud bug.
-2. **All 4 methods accept entity IDs via `**kwargs`**, but rules differ by method:
-   - `add()` — entity IDs are passed as top-level kwargs (`user_id=..., agent_id=...`).
-   - `search()` / `get_all()` — top-level entity kwargs are **rejected** (`ValueError`). They MUST live inside `filters={...}`.
-   - `update()` — no entity IDs (memory is addressed by `memory_id`).
-3. **`ENTITY_PARAMS = frozenset({'app_id','run_id','user_id','agent_id'})`** — the guard set used by `search`/`get_all`.
-4. **Kwargs merge order** (all 4 methods): `options.model_dump(exclude_unset=True)` first, then `**kwargs` override it. Caller kwargs win.
-5. Both `MemoryClient` (sync) and `AsyncMemoryClient` (async) expose identical signatures. The adapter can mirror the same shape for sync vs async paths.
-6. Return type is `Dict[str, Any]` — NOT an async generator, NOT a Pydantic model. Caller reads `.get("results")`, `.get("count")`, etc.
-
----
-
-## `add()`
-
-### Signature
-
-```python
-async def add(
-    self,
-    messages,                                            # str | dict | list[dict]
-    options: Optional[AddMemoryOptions] = None,
-    **kwargs,                                            # user_id, agent_id, app_id, run_id, etc.
-) -> Dict[str, Any]
-```
-
-### `AddMemoryOptions` fields (`model_fields`)
-
-```
-filters:                 Dict[str, Any] | None
-metadata:                Dict[str, Any] | None
-infer:                   bool           | None
-custom_categories:       List[Dict[str, Any]] | None
-custom_instructions:     str            | None
-timestamp:               int            | None
-structured_data_schema:  Dict[str, Any] | None
-```
-
-No entity-ID fields on this Options class. Do NOT put `user_id` inside `AddMemoryOptions(...)` — it is dropped.
-
-### Entity ID handling
-
-- `user_id`, `agent_id`, `app_id`, `run_id` → **top-level `**kwargs`** on `add()`.
-- They are merged into the POST body at `/v3/memories/add/` alongside `messages` via `_prepare_payload`.
-
-### Return shape (live)
-
-```json
-{"message": "...", "status": "PENDING", "event_id": "<uuid>"}
-```
-
-Async ingestion — no memory object returned synchronously. Caller must poll (e.g. `get_all` / `get`) or trust the event id.
-
-### Reproducer
-
-```python
-from mem0 import AsyncMemoryClient
-from mem0.client.types import AddMemoryOptions
-
-c = AsyncMemoryClient(api_key=os.environ["MEM0_API_KEY"])
-res = await c.add(
-    "Hi, I love Vietnamese coffee.",
-    options=AddMemoryOptions(metadata={"src": "adapter"}),
-    user_id="u1", agent_id="a1", run_id="r1",
-)
-# res -> {"message": "...", "status": "PENDING", "event_id": "..."}
-```
-
----
-
-## `search()`
-
-### Signature
-
-```python
-async def search(
-    self,
-    query: str,
-    options: Optional[SearchMemoryOptions] = None,
-    **kwargs,                   # filters=..., other SearchMemoryOptions-compatible fields
-) -> Dict[str, Any]
-```
-
-### `SearchMemoryOptions` fields
-
-```
-filters:    Dict[str, Any] | None
-metadata:   Dict[str, Any] | None
-top_k:      int            | None
-rerank:     bool           | None
-threshold:  float          | None
-fields:     List[str]      | None
-categories: List[str]      | None
-```
-
-### Entity ID handling — STRICT
-
-- Top-level `user_id=`, `agent_id=`, `app_id=`, `run_id=` kwargs **raise `ValueError`**:
-  > "Top-level entity parameters {…} are not supported in search(). Use filters={'user_id': '...'} instead."
-- Correct form: `filters={"user_id": "u1", "agent_id": "a1"}` either on the Options or as a top-level `filters=` kwarg.
-
-### Return shape
-
-`{"results": [ {...memory...}, ... ]}` (v1.1 format). Memory object fields: `id`, `memory`, `user_id`, `metadata`, `categories`, `created_at`, `updated_at`, `expiration_date`, `structured_attributes`.
-
-### Reproducer
-
-```python
-from mem0.client.types import SearchMemoryOptions
-s = await c.search(
-    "coffee",
-    options=SearchMemoryOptions(top_k=5),
-    filters={"user_id": "u1"},
-)
-# s -> {"results": [...]}
-```
-
----
-
-## `get_all()`
-
-### Signature
-
-```python
-async def get_all(
-    self,
-    options: Optional[GetAllMemoryOptions] = None,
-    **kwargs,
-) -> Dict[str, Any]
-```
-
-### `GetAllMemoryOptions` fields
-
-```
-filters:     Dict[str, Any] | None
-page:        int            | None
-page_size:   int            | None
-start_date:  str            | None
-end_date:    str            | None
-categories:  List[str]      | None
-```
-
-### Entity ID handling — STRICT (same as search)
-
-Top-level entity kwargs raise `ValueError`. Must use `filters={...}`. Cloud also returns **HTTP 400** if no entity filter is supplied at all (`/v3/memories/` without filters is rejected server-side).
-
-### Return shape
-
-```json
-{"count": <int>, "next": <url|null>, "previous": <url|null>, "results": [ {...}, ... ]}
-```
-
-Paginated. `page` and `page_size` are lifted out of the JSON body and sent as query params by the client (`POST /v3/memories/?page=1&page_size=10`).
-
-### Reproducer
-
-```python
-from mem0.client.types import GetAllMemoryOptions
-g = await c.get_all(
-    options=GetAllMemoryOptions(page=1, page_size=10),
-    filters={"user_id": "u1"},
-)
-# g -> {"count": 13, "next": "...", "previous": null, "results": [...]}
-```
-
----
-
-## `update()`
-
-### Signature
-
-```python
-async def update(
-    self,
-    memory_id: str,
-    options: Optional[UpdateMemoryOptions] = None,
-    **kwargs,                   # text=, metadata=, timestamp=
-) -> Dict[str, Any]
-```
-
-### `UpdateMemoryOptions` fields
-
-```
-text:       str                       | None
-metadata:   Dict[str, Any]            | None
-timestamp:  int | float | str         | None
-```
-
-No entity IDs. `memory_id` is the only addressing input. Raises `ValueError` if none of `text` / `metadata` / `timestamp` are provided.
-
-### Return shape
-
-Full memory object (same fields as `search`/`get_all` results): `id`, `memory`, `user_id`, `metadata`, `categories`, `created_at`, `updated_at`, `expiration_date`, `structured_attributes`. HTTP verb: `PUT /v1/memories/{memory_id}/`.
-
-### Reproducer
-
-```python
-from mem0.client.types import UpdateMemoryOptions
-u = await c.update("b79735a9-da7b-4bce-8988-47be66260f01", text="Updated text")
-# or: await c.update(mid, options=UpdateMemoryOptions(metadata={"k": "v"}))
-```
-
----
-
-## Migration checklist for `mem0_adapter.py` (4 helpers)
-
-For each helper, confirm it follows the rules below before leaving it "fixed":
-
-### `_cloud_add`
-- [ ] `AddMemoryOptions(...)` constructor contains ONLY fields from its schema (`filters`, `metadata`, `infer`, `custom_categories`, `custom_instructions`, `timestamp`, `structured_data_schema`).
-- [ ] `user_id`, `agent_id`, `app_id`, `run_id` are passed to `client.add(...)` as **top-level kwargs**, not inside `options=`.
-- [ ] Caller does not rely on a memory object in the return — expect `{"status": "PENDING", "event_id": ...}`.
-
-### `_cloud_search`
-- [ ] `SearchMemoryOptions(...)` contains only its schema fields (`filters`, `metadata`, `top_k`, `rerank`, `threshold`, `fields`, `categories`).
-- [ ] Entity IDs are placed **inside `filters=`** — either on the Options or as a top-level `filters={"user_id": ...}` kwarg. Never as bare `user_id=` kwargs (raises `ValueError`).
-- [ ] Caller reads `response["results"]`.
-
-### `_cloud_get_all`
-- [ ] `GetAllMemoryOptions(...)` contains only its schema fields (`filters`, `page`, `page_size`, `start_date`, `end_date`, `categories`).
-- [ ] Entity IDs go inside `filters=`. Never as top-level kwargs (raises `ValueError`).
-- [ ] At least one entity filter is supplied when a scoped read is intended — unfiltered cloud `get_all` returns HTTP 400.
-- [ ] Caller reads `response["results"]` and `response["count"]` for pagination.
-
-### `_cloud_update`
-- [ ] Address memory by `memory_id` (positional). Do NOT attempt to pass `user_id`.
-- [ ] Payload built from `UpdateMemoryOptions(text=..., metadata=..., timestamp=...)` or equivalent kwargs — at least one must be non-None.
-- [ ] Caller reads the returned memory object (same shape as `get_all` result entries).
-
-### Cross-cutting
-- [ ] Adapter never constructs any `*MemoryOptions` with fields outside the schemas above (Pydantic silently drops them — verify with `list(Cls.model_fields)`).
-- [ ] Both sync (`MemoryClient`) and async (`AsyncMemoryClient`) code paths follow identical rules — signatures match.
-- [ ] Error translation handles cloud 400s from missing entity filters on `search`/`get_all` distinctly from 401 auth errors.

package/tools/vds-scripts/PACKAGE_P125B_IMPLEMENTATION_SUMMARY.md

@@ -1,131 +0,0 @@
-# Package P125-B Implementation Summary
-
-**Completed:** TSK-125.3 and TSK-125.4
-
-## TSK-125.3: Repomix-skill Bounded Integration
-
-### Files Created
-
-1. **`audit_orchestrator/src/vds_audit_orchestrator/engine/companion_context_service.py`** (434 lines)
-   - New service for generating bounded companion context using repomix-skill
-   - Key components:
-     - `CompanionContextRequest`: Validates requests with explicit repo scope, narrow include patterns, and explicit output paths
-     - `CompanionContextArtifact`: Metadata-rich artifacts explicitly marked as non-authoritative evidence
-     - `CompanionContextService`: Main service that wraps repomix-skill with bounded filters
-     - Default ignore patterns to exclude low-signal files (node_modules, build outputs, lock files, etc.)
-   
-   - **Critical Requirements Met:**
-     - ✅ Requires explicit repo scope (no open-ended searches)
-     - ✅ Narrow include/ignore filters to avoid token bloat
-     - ✅ Explicit output paths for artifact tracking
-     - ✅ Artifact metadata (source repos, filters, token counts, row/check identifiers)
-     - ✅ Generated artifacts marked as companion context only (NOT authoritative evidence)
-
-2. **`audit_orchestrator/src/vds_audit_orchestrator/agents/skill_tools.py`** (204 lines)
-   - LangChain-compatible tools for companion context generation
-   - Tools:
-     - `generate_companion_context`: General-purpose companion context generation
-     - `create_check_companion_context`: Convenience wrapper for check-specific context
-   - Helper functions for tool registry and companion context tool identification
-
-3. **`audit_orchestrator/tests/test_companion_context_service.py`** (232 lines)
-   - Comprehensive test suite covering:
-     - Request validation (repo_path, include_patterns, output_path requirements)
-     - Artifact metadata serialization
-     - Service initialization and command building
-     - Default ignore patterns
-     - Integration test (skipped by default, requires RUN_INTEGRATION_TESTS=1)
-   
-   - **Test Results:** 10 passed, 1 skipped ✅
-
-## TSK-125.4: Telemetry Separation
-
-### Files Modified
-
-1. **`audit_orchestrator/src/vds_audit_orchestrator/observability/metrics.py`**
-   - Added new skill-tool telemetry metrics:
-     - `_skill_tool_invocations`: Counter for skill-tool invocations (separate from docs/code tools)
-     - `_skill_tool_duration`: Histogram for skill-tool execution duration
-     - `_companion_artifact_generated`: Counter for companion artifacts (skill-assisted, non-authoritative)
-     - `_skill_execution_provenance`: Counter for skill execution provenance tracking
-   
-   - Added recording functions:
-     - `record_skill_tool_invocation()`: Records skill-tool activity with skill name, action, status, duration
-     - `record_companion_artifact_generated()`: Records companion artifact generation with metadata
-     - `record_skill_execution_provenance()`: Records skill execution provenance (skill name, status, artifact presence)
-   
-   - **Telemetry Requirements Met:**
-     - ✅ Skill-tool activity reported separately from docs/code tool activity
-     - ✅ Companion artifacts identified as skill-assisted
-     - ✅ Provenance preserved (skill name, execution status, artifact presence)
-     - ✅ Ready for integration with docs-path vs project-knowledge fallback metrics
-
-## Integration Points
-
-The companion context service integrates with the existing audit orchestrator through:
-
-1. **Skill Execution Tracking**: Uses `SkillExecutor.record_tool_usage()` to record skill invocations for telemetry
-2. **Metrics Export**: New skill metrics are exported via Prometheus when metrics are enabled
-3. **Tool Registry**: Skill tools can be registered with agent toolsets via `get_companion_context_tools()`
-
-## Usage Example
-
-```python
-from vds_audit_orchestrator.engine.companion_context_service import (
-    CompanionContextRequest,
-    CompanionContextService,
-)
-
-# Create request with explicit scope
-request = CompanionContextRequest(
-    repo_path="/path/to/repo",  # Explicit scope (required)
-    include_patterns=["src/api/**/*.py"],  # Narrow filters
-    output_path="/output/companion-api-context.txt",
-    context_purpose="Support API compliance check CL-003",
-    check_id="CL-003",
-    row_id="row-123",
-)
-
-# Generate companion context
-service = CompanionContextService()
-artifact = service.generate_context(request)
-
-# Artifacts are ALWAYS marked as companion-only (non-authoritative)
-assert artifact.is_companion_only is True
-assert artifact.skill_name == "repomix-skill"
-```
-
-## Key Design Decisions
-
-1. **Explicit Scope Required**: No open-ended searches - repo_path and include_patterns must be specified
-2. **Narrow Filters**: Default ignore patterns exclude low-signal files to minimize token bloat
-3. **Non-Authoritative**: Companion artifacts are explicitly marked as non-authoritative evidence
-4. **Metadata-Rich**: Every artifact includes full provenance (source repo, filters, token counts, check/row IDs)
-5. **Telemetry-Ready**: Skill invocations are tracked separately from docs/code tool activity
-
-## Testing
-
-All tests pass:
-- Unit tests: 10 passed
-- Integration tests: 1 skipped (requires RUN_INTEGRATION_TESTS=1)
-
-Run tests with:
-```bash
-./scripts/worktree_uv.sh run --project audit_orchestrator pytest audit_orchestrator/tests/test_companion_context_service.py -v
-```
-
-## Next Steps
-
-Remaining work for complete Phase 125 integration:
-
-1. **Row Evaluator Integration**: Update `row_evaluator.py` to extract skill metrics from tool usage records
-2. **CLI Telemetry**: Update `cli_impl.py` to report skill-tool activity in workflow output
-3. **Integration Testing**: Add integration tests with actual repomix-skill execution
-
-## Constraints Followed
-
-- ✅ Work ONLY in Phase 125 worktree
-- ✅ No modifications to files other agents are working on
-- ✅ Used `./scripts/worktree_uv.sh run --project audit_orchestrator` for all commands
-- ✅ Tests run with `uv run pytest audit_orchestrator/tests/`
-- ✅ Clear commit messages: "feat(phase125): TSK-125.X - description"