vmware-debug 1.11.2__tar.gz → 1.11.4__tar.gz

{vmware_debug-1.11.2 → vmware_debug-1.11.4}/.claude-plugin/plugin.json

@@ -2,8 +2,8 @@
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "vmware-debug",
   "displayName": "VMware Debug",
-  "version": "1.11.2",
-  "description": "Read-only VMware incident correlation: timeline, spikes, root-cause routing. 2 MCP tools.",
+  "version": "1.11.4",
+  "description": "VMware incident timeline, root-cause routing, local case ledger; no vSphere access. 14 MCP tools.",
   "author": {
     "name": "Wei Zhou",
     "email": "zhouwei008@gmail.com",

{vmware_debug-1.11.2 → vmware_debug-1.11.4}/.mcp.json

@@ -5,7 +5,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "vmware-debug==1.11.2",
+        "vmware-debug==1.11.4",
         "vmware-debug-mcp"
       ]
     }

{vmware_debug-1.11.2 → vmware_debug-1.11.4}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: vmware-debug
-Version: 1.11.2
-Summary: VMware diagnostic brain — read-only incident triage, log/event correlation, and root-cause routing across the VMware skill family
+Version: 1.11.4
+Summary: VMware diagnostic brain — offline incident triage, log/event correlation, and root-cause routing across the VMware skill family
 Project-URL: Homepage, https://github.com/vmware-skills/VMware-Debug
 Project-URL: Repository, https://github.com/vmware-skills/VMware-Debug
 Project-URL: Issues, https://github.com/vmware-skills/VMware-Debug/issues
@@ -18,17 +18,13 @@ Requires-Dist: mcp[cli]<2.0,>=1.10
 Requires-Dist: pyyaml<7.0,>=6.0
 Requires-Dist: rich<15.0,>=13.0
 Requires-Dist: typer<1.0,>=0.12
-Requires-Dist: vmware-policy<2.0,>=1.11.0
+Requires-Dist: vmware-policy<2.0,>=1.13.1
 Description-Content-Type: text/markdown
 
 <!-- mcp-name: io.github.vmware-skills/vmware-debug -->
 
 # VMware Debug
 
-> ⚠️ **Work in progress** — the core (event correlation engine, MCP tools, CLI)
-> is built and tested; README, `server.json`, full reference docs, and packaging
-> polish are still landing. Not yet published to PyPI.
-
 > **Disclaimer**: Community-maintained open-source project, **not affiliated with,
 > endorsed by, or sponsored by VMware, Inc. or Broadcom Inc.** "VMware" and
 > "vSphere" are trademarks of Broadcom. Source is publicly auditable under the MIT
@@ -37,21 +33,43 @@ Description-Content-Type: text/markdown
 The diagnostic brain of the VMware skill family. You bring the symptom (an error,
 a log dump, a slow VM); this skill runs a systematic investigation, correlates
 events from the other skills into one timeline, ranks root-cause hypotheses, and
-tells you what to check next. It is **read-only** — it never changes anything and
-never executes fixes. Remediation is routed to `vmware-aiops` (single op) or
+tells you what to check next. It **never touches vSphere** — it connects to
+nothing and never executes fixes; its only writes are to a local case ledger
+under `$OPS_HOME`. Remediation is routed to `vmware-aiops` (single op) or
 `vmware-pilot` (multi-step, gated), mirroring the `vmware-harden → vmware-pilot`
 advisor/executor split.
 
 See [`skills/vmware-debug/SKILL.md`](skills/vmware-debug/SKILL.md) for the full
 methodology, the event-envelope contract, and symptom routing.
 
-## MCP tools
+## MCP tools (14 — 7 read, 7 write)
+
+The seven writes go to the local case ledger only; none reaches a VMware system.
+
+**Correlation** — stateless, for a single look:
 
 | Tool | What |
 |---|---|
 | `incident_timeline` | [READ] Correlate pre-fetched events → timeline + spikes + ranked hypotheses + next-check ideas |
 | `list_symptom_categories` | [READ] List recognised symptom categories + what to check for each |
 
+**Investigation ledger** — for an incident you will reason about over time:
+
+| Tool | What |
+|---|---|
+| `case_open` | [WRITE] Define the event; returns a case id and the grade this environment can reach |
+| `case_readiness` | [READ] What grade this environment can reach, per symptom category, **before** you start |
+| `case_knowledge` | [READ] Which knowledge formats are accepted, what is mounted, and which entries apply to a case |
+| `case_plan` | [READ] What to fetch next — skill, tool and purpose per step; recomputed from the case's current state |
+| `case_list` | [READ] Cases, newest first |
+| `case_get` | [READ] One case: scope, ledger sizes, grade history |
+| `case_hypotheses` | [WRITE] Register a candidate explanation, or read the ledger of what supports and refutes each |
+| `case_submit_evidence` | [WRITE] Record one retrieved fact, with its source, query and time basis |
+| `case_record_gap` | [WRITE] Record what could **not** be retrieved, and how to close it |
+| `case_timeline` | [WRITE] Correlate everything the case has collected into one timeline |
+| `case_grade` | [WRITE] Recompute the conclusion grade from the ledger and record it |
+| `case_close` | [WRITE] Record the final grade, archive, and name what was left open |
+
 ## Offline / Air-Gapped Install (from source)
 
 This project uses the modern PEP 517 build system (hatchling), so there is **no

vmware_debug-1.11.4/README-CN.md

@@ -0,0 +1,72 @@
+<!-- mcp-name: io.github.vmware-skills/vmware-debug -->
+
+# VMware Debug（中文）
+
+> **声明**：本项目为社区维护的开源项目，**与 VMware, Inc. 或 Broadcom Inc. 无任何隶属、
+> 背书或赞助关系。** "VMware"、"vSphere" 为 Broadcom 商标。源码以 MIT 许可证公开可审计。
+
+VMware skill 家族的**诊断大脑**。你给出症状（报错、日志、变慢的 VM），它来跑系统化排查：
+把其它 skill 取到的事件关联成一条时间线、检测突刺、给根因假设排序，并告诉你下一步该查什么。
+它**从不触碰 vSphere**——不连接任何东西，也从不执行修复；唯一的写入是 `$OPS_HOME` 下的本地案卷。修复一律路由给 vmware-aiops（单步）或
+vmware-pilot（多步、带审批门控），完全复刻 vmware-harden → vmware-pilot 的「顾问/执行」分工。
+
+## 配套 Skill
+
+| 需求 | Skill |
+|---|---|
+| 故障关联 / 根因 | **vmware-debug**（本项目） |
+| 集中日志检索 | vmware-log-insight（把 `log_search` 结果喂给它） |
+| vCenter 事件与告警 | vmware-monitor |
+| 指标 / 异常 | vmware-aria |
+| 执行修复 | vmware-aiops（单步）/ vmware-pilot（多步门控） |
+
+## 安装
+
+```bash
+uv tool install vmware-debug
+vmware-debug categories          # 看它能诊断哪些症状类别
+```
+
+## MCP 工具（14 个：7 读、7 写）
+
+7 个写工具只写本地案卷，没有一个触及任何 VMware 系统。
+
+**关联**——无状态，看一眼用：
+
+- `incident_timeline`：[READ] 把已取到的事件关联成 时间线 + 突刺 + 排序后的根因假设 + 下一步检查建议
+- `list_symptom_categories`：[READ] 症状类别及对应的排查路由（不知道查什么时用它）
+
+**调查案卷**——需要持续推理的事件：
+
+- `case_open`：[WRITE] 定义事件；返回案卷 id 和本环境能达到的结论等级
+- `case_readiness`：[READ] 开始**之前**，按症状类别说明本环境能达到的等级
+- `case_knowledge`：[READ] 接受哪些知识格式、挂载了什么、哪些条目适用于某个案卷
+- `case_plan`：[READ] 下一步该取什么——每步给出 skill、工具和目的；按案卷当前状态重算
+- `case_list`：[READ] 案卷列表，最新的在前
+- `case_get`：[READ] 单个案卷：范围、账本大小、等级历史
+- `case_hypotheses`：[WRITE] 登记一个候选解释，或读取各假设的支持/反驳账本
+- `case_submit_evidence`：[WRITE] 记录一条取到的事实，连同来源、查询和时间基准
+- `case_record_gap`：[WRITE] 记录**没能**取到的东西，以及如何补上
+- `case_timeline`：[WRITE] 把案卷收集到的一切关联成一条时间线
+- `case_grade`：[WRITE] 从账本重算结论等级并记录
+- `case_close`：[WRITE] 记录最终等级、归档，并写明留下了哪些未决项
+
+**事件信封**：`{ts, source, severity, entity, text, fields}`。agent 把各源事件归一成此形状再交给
+debug；debug 因此与其它包零运行时依赖。**请把每条事件的 `event_type` 保留在 `fields` 里**——
+分类器除了正文之外也匹配它，而现代 vSphere 多数事件是 `EventEx`：正文是一句通用套话，
+真正说明「这是什么事件」的只有 `eventTypeId`。
+
+## 安全
+
+结构上离线、无凭据：不连任何 vCenter/NSX/Aria，对 VMware 没有可破坏面，也没有秘密可泄露。
+唯一的写入是本地案卷：证据、缺口、假设和等级历史只增不改；`timeline.md` 由证据重新生成，
+`case.json` 保存当前等级和状态。多个写入者同样成立：每次写案卷都要先拿该案卷的锁文件（`.ledger.lock`，
+独占创建），所以两个进程在共享的 `$OPS_HOME` 里写同一个案卷会被串行化，而不是互相丢条目；每个文件都先写到
+临时文件名再移到位，读者不会读到写了一半的文件（在不支持硬链接的文件系统上，新的证据文件改为原地创建：
+仍然绝不覆盖，但可能被读到写了一半）。崩溃进程留下的锁会连同持有者一起报告，从不自动删除；
+确认没有进程在写该案卷后再手动删除。已发布的 1.11.3 及更早版本不拿这个锁，共享案卷目录的每台机器都要升级。
+详见 [SECURITY.md](SECURITY.md)。
+
+## 许可证
+
+MIT。

{vmware_debug-1.11.2 → vmware_debug-1.11.4}/README.md

@@ -2,10 +2,6 @@
 
 # VMware Debug
 
-> ⚠️ **Work in progress** — the core (event correlation engine, MCP tools, CLI)
-> is built and tested; README, `server.json`, full reference docs, and packaging
-> polish are still landing. Not yet published to PyPI.
-
 > **Disclaimer**: Community-maintained open-source project, **not affiliated with,
 > endorsed by, or sponsored by VMware, Inc. or Broadcom Inc.** "VMware" and
 > "vSphere" are trademarks of Broadcom. Source is publicly auditable under the MIT
@@ -14,21 +10,43 @@
 The diagnostic brain of the VMware skill family. You bring the symptom (an error,
 a log dump, a slow VM); this skill runs a systematic investigation, correlates
 events from the other skills into one timeline, ranks root-cause hypotheses, and
-tells you what to check next. It is **read-only** — it never changes anything and
-never executes fixes. Remediation is routed to `vmware-aiops` (single op) or
+tells you what to check next. It **never touches vSphere** — it connects to
+nothing and never executes fixes; its only writes are to a local case ledger
+under `$OPS_HOME`. Remediation is routed to `vmware-aiops` (single op) or
 `vmware-pilot` (multi-step, gated), mirroring the `vmware-harden → vmware-pilot`
 advisor/executor split.
 
 See [`skills/vmware-debug/SKILL.md`](skills/vmware-debug/SKILL.md) for the full
 methodology, the event-envelope contract, and symptom routing.
 
-## MCP tools
+## MCP tools (14 — 7 read, 7 write)
+
+The seven writes go to the local case ledger only; none reaches a VMware system.
+
+**Correlation** — stateless, for a single look:
 
 | Tool | What |
 |---|---|
 | `incident_timeline` | [READ] Correlate pre-fetched events → timeline + spikes + ranked hypotheses + next-check ideas |
 | `list_symptom_categories` | [READ] List recognised symptom categories + what to check for each |
 
+**Investigation ledger** — for an incident you will reason about over time:
+
+| Tool | What |
+|---|---|
+| `case_open` | [WRITE] Define the event; returns a case id and the grade this environment can reach |
+| `case_readiness` | [READ] What grade this environment can reach, per symptom category, **before** you start |
+| `case_knowledge` | [READ] Which knowledge formats are accepted, what is mounted, and which entries apply to a case |
+| `case_plan` | [READ] What to fetch next — skill, tool and purpose per step; recomputed from the case's current state |
+| `case_list` | [READ] Cases, newest first |
+| `case_get` | [READ] One case: scope, ledger sizes, grade history |
+| `case_hypotheses` | [WRITE] Register a candidate explanation, or read the ledger of what supports and refutes each |
+| `case_submit_evidence` | [WRITE] Record one retrieved fact, with its source, query and time basis |
+| `case_record_gap` | [WRITE] Record what could **not** be retrieved, and how to close it |
+| `case_timeline` | [WRITE] Correlate everything the case has collected into one timeline |
+| `case_grade` | [WRITE] Recompute the conclusion grade from the ledger and record it |
+| `case_close` | [WRITE] Record the final grade, archive, and name what was left open |
+
 ## Offline / Air-Gapped Install (from source)
 
 This project uses the modern PEP 517 build system (hatchling), so there is **no

{vmware_debug-1.11.2 → vmware_debug-1.11.4}/RELEASE_NOTES.md

@@ -1,3 +1,64 @@
+## v1.11.4 — concurrent writers stop losing case entries
+
+Two agents on one case — a supported setup, since `OPS_HOME` can point at a shared folder — lost
+entries: six processes writing 150 gaps and hypotheses each kept 157 of 900 gaps and handed out
+duplicate hypothesis ids. Ledger writes are now serialised by a per-case lock (`.ledger.lock`
+in the case folder), and each write lands atomically. Versions up to and including 1.11.3 do not
+take the lock, so **every machine that shares an `OPS_HOME` needs this version** — one older
+writer on the share can still lose entries.
+
+The manifests advertised 2 tools (14 are registered), and the docs called the case-ledger writes
+read-only. Both are corrected, and the docs now say that case data is sensitive, owner-only, and
+kept until you delete the case folder.
+
+**OpenClaw hid this skill unless `vmware-debug` was on PATH.** `metadata.openclaw.requires` was
+only `bins: ["vmware-debug"]` — there was no `requires.config` or `requires.env`, unlike most of the
+family. OpenClaw hides a skill whose required binary is missing, and a plugin install runs the
+server through uvx, which never puts `vmware-debug` on PATH, so there the skill was "needs setup / not
+visible to the model" (requirement semantics verified on OpenClaw 2026.6.35). `requires` is now
+`anyBins: ["vmware-debug", "uvx"]`; `optional.env` is unchanged, and the placeholder
+`primaryEnv: "NONE"` is gone.
+
+**Install commands in the skill pin this release.** ClawHub reviews SKILL.md and references/,
+not the package they install, so an unpinned `uv tool install` vouched for code nobody reviewed.
+Every install command for this package in the skill now names this version.
+
+## v1.11.3 — 398 tests never ran
+
+
+**`tests/__init__.py` was missing, and the whole suite -- 398 tests -- failed at
+collection.** `tests/eval/` and `tests/eval/regression/` were already packages,
+so `from tests.eval.regression._vsphere_event_vocabulary import ...` resolved
+only where the namespace-package fallback happened to work. It did not on
+Windows. One file.
+
+**The suite now runs on a cp936 machine.** Round 3 of the VCF 9 field testing ran
+on Windows Server 2025 with locale cp936. Across the family four repos' suites --
+1687 tests -- never executed at all, dying at collection reading our own UTF-8
+sources, and 101 more failed the same way. Most of those were the tests that
+verify the destructive-operation guardrails: the guardrails were fine, the tests
+that check them could not open a file. On the UTF-8 CI every one of them was
+green. A security test that cannot run is not a security test.
+
+Every text read and write here names its encoding now, `tests/` included -- the
+previous round fixed only the package, which is why this came back. A gate in
+`family_smoke` scans both trees by AST, and the whole family's suites were re-run
+under an ASCII locale to confirm: 15 of 15 green, from 1 of 15.
+
+**`--help` no longer dies on a console that cannot encode it.** On any console
+whose encoding cannot carry the characters in our own help text, `--help` exited
+with a `UnicodeEncodeError` traceback -- unavailable exactly on the machines
+where it is most needed. Four repos were affected; the handler is now relaxed in
+all fifteen so a glyph degrades instead of killing the command.
+
+**Unknown tool arguments are refused instead of dropped.** The schema declared
+`additionalProperties: false` and the runtime accepted them anyway, so a filter
+argument whose name a model guessed wrong returned the *unfiltered* result with
+nothing to indicate anything had been discarded. Fixed in vmware-policy 1.12.0
+and in force here.
+
+Requires vmware-policy 1.12.0.
+
 ## v1.11.2 — the resolver hijack, the discarded event identifier, and a parameter that did nothing
 
 Three findings from the 2026-08-30 real-hardware re-test. 

{vmware_debug-1.11.2 → vmware_debug-1.11.4}/SECURITY.md

@@ -15,11 +15,24 @@ or by email to the maintainer. Please do not open public issues for security bug
 
 ## Security Design
 
-### Read-only and offline by construction
-vmware-debug has **no write tools, no network access, and no credentials**. It
-does not connect to vCenter, NSX, Aria, or any appliance. Its tools are pure
-functions over event data the orchestrating agent has already fetched with the
-other skills' read tools. There is no destructive surface and no secret to leak.
+### Offline by construction; writes only its own ledger
+vmware-debug has **no network access and no credentials**. It does not connect to
+vCenter, NSX, Aria, or any appliance. Its tools work over event data the
+orchestrating agent has already fetched with the other skills' read tools. Seven
+of its fourteen MCP tools write — only to the local investigation ledger under
+`$OPS_HOME` (default `~/.vmware/cases`). Evidence, gaps, hypotheses and grade
+history are only ever added to; `timeline.md` is regenerated from the evidence
+and `case.json` holds the current grade and state. That holds with several writers
+too: every write to a case takes that case's lock file (`.ledger.lock`, created
+exclusively), so two processes working one case in a shared `$OPS_HOME` are
+serialised rather than losing each other's entries, and every file is written to
+a temporary name and moved into place, so a reader never sees half of one (on a
+filesystem without hard links, a new evidence file is created in place instead:
+still never overwritten, but readable half-written). A lock left by a crashed
+process is reported with its holder and never removed automatically; delete it
+once nothing is writing the case. Released versions up to and including 1.11.3
+do not take the lock, so upgrade every machine that shares a cases folder. There
+is no destructive surface against any VMware system and no secret to leak.
 
 ### No remediation execution
 debug only *diagnoses* and *recommends*. Any fix is routed to vmware-aiops

{vmware_debug-1.11.2 → vmware_debug-1.11.4}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vmware-debug"
-version = "1.11.2"
-description = "VMware diagnostic brain — read-only incident triage, log/event correlation, and root-cause routing across the VMware skill family"
+version = "1.11.4"
+description = "VMware diagnostic brain — offline incident triage, log/event correlation, and root-cause routing across the VMware skill family"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10"
@@ -21,7 +21,7 @@ dependencies = [
     "typer>=0.12,<1.0",
     "rich>=13.0,<15.0",
     "mcp[cli]>=1.10,<2.0",
-    "vmware-policy>=1.11.0,<2.0",
+    "vmware-policy>=1.13.1,<2.0",
     # Imported directly by ops/cases/grading.py for the rules file. It has
     # always arrived transitively via vmware-policy; a package should
     # declare what it imports rather than rely on a dependency's dependency.

{vmware_debug-1.11.2 → vmware_debug-1.11.4}/server.json

@@ -2,17 +2,17 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.vmware-skills/vmware-debug",
   "title": "VMware Debug",
-  "description": "Read-only VMware incident correlation: timeline, spikes, root-cause routing. 2 MCP tools.",
+  "description": "VMware incident timeline, root-cause routing, local case ledger; no vSphere access. 14 MCP tools.",
   "repository": {
     "url": "https://github.com/vmware-skills/VMware-Debug",
     "source": "github"
   },
-  "version": "1.11.2",
+  "version": "1.11.4",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "vmware-debug",
-      "version": "1.11.2",
+      "version": "1.11.4",
       "runtimeHint": "uvx",
       "packageArguments": [
         {

{vmware_debug-1.11.2 → vmware_debug-1.11.4}/skills/vmware-debug/SKILL.md

@@ -10,7 +10,8 @@ description: >
   don't know where to start. Always use this skill for "diagnose this VMware
   issue", "why is my VM slow", "troubleshoot this vSphere error", "what does
   this log mean", "help me figure out what broke" when the context is explicitly
-  VMware/vSphere/ESXi/NSX. It is READ-ONLY: it never changes anything. Do NOT
+  VMware/vSphere/ESXi/NSX. It never touches vSphere: its only writes are to a
+  local case ledger. Do NOT
   use it to execute fixes — single fixes go to vmware-aiops, multi-step gated
   remediation goes to vmware-pilot. Do NOT use it for routine inventory or
   health checks with no problem to solve — use vmware-monitor.
@@ -19,7 +20,7 @@ installer:
   package: vmware-debug
 allowed-tools:
   - Bash
-metadata: {"openclaw":{"requires":{"bins":["vmware-debug"]},"optional":{"env":["VMWARE_AUDIT_APPROVED_BY","VMWARE_AUDIT_RATIONALE"],"bins":["vmware-policy"]},"primaryEnv":"NONE","homepage":"https://github.com/vmware-skills/VMware-Debug","os":["macos","linux"]}}
+metadata: {"openclaw":{"requires":{"anyBins":["vmware-debug","uvx"]},"optional":{"env":["VMWARE_AUDIT_APPROVED_BY","VMWARE_AUDIT_RATIONALE"],"bins":["vmware-policy"]},"homepage":"https://github.com/vmware-skills/VMware-Debug","os":["macos","linux"]}}
 ---
 
 # VMware Debug
@@ -30,7 +31,8 @@ metadata: {"openclaw":{"requires":{"bins":["vmware-debug"]},"optional":{"env":["
 
 The diagnostic brain of the VMware skill family. You bring the symptom; this skill
 runs the investigation and points at the root cause. It **reads and reasons** — it
-never writes. Companion skills do the data collection and the fixing.
+never writes to vSphere; its only writes go to its own local case ledger.
+Companion skills do the data collection and the fixing.
 
 ## What This Skill Does
 
@@ -40,14 +42,16 @@ never writes. Companion skills do the data collection and the fixing.
 | Root-cause ranking | Score symptom clusters, surface the most likely cause first | Read |
 | Next-check ideas | Suggest exactly what to look at next (which skill/tool) when you're stuck | Read |
 | Remediation routing | Hand the fix to vmware-aiops (single) or vmware-pilot (gated, multi-step) | Read (routes only) |
+| Investigation ledger | Open a case; record evidence, gaps and hypotheses; grade and close it | Write (local ledger only) |
 
-**Zero write tools. Zero network access of its own.** It correlates data the agent
-has already gathered with the other skills' read tools.
+**No network access of its own, and no write to any VMware system.** It correlates
+data the agent has already gathered with the other skills' read tools; its seven
+write tools touch only the local case ledger.
 
 ## Quick Install
 
 ```bash
-uv tool install vmware-debug
+uv tool install vmware-debug==1.11.4
 vmware-debug categories          # see what it can diagnose
 ```
 
@@ -126,7 +130,7 @@ a recommended plan.
 | `case_grade` | [WRITE] Recompute the conclusion grade from the ledger and record it |
 | `case_close` | [WRITE] Record the final grade, archive, and name what was left open |
 
-The four writes go to `$OPS_HOME` (default `~/.vmware/cases/`) and nowhere else.
+The seven writes go to `$OPS_HOME` (default `~/.vmware/cases/`) and nowhere else.
 
 **List envelope** (output of `list_symptom_categories`): `{items, returned, limit, total, truncated, hint}` — read the rows from `items`. `truncated` is always `false` here, which is the point: it states that the catalogue is complete instead of leaving you to infer it.
 
@@ -267,11 +271,20 @@ vmware-debug mcp                                # start stdio MCP server (proxy-
 
 ## Audit & Safety
 
-Read-only by construction: no write tools, no network, nothing executed. Remediation
-is always routed to aiops/pilot, where the double-confirm / approval / audit gates live
-(audit DB `~/.vmware/audit.db`). Policy rules scope by environment; debug has no config
-and no connection to declare one about, so it reports a constant `local` — nothing here
-touches a remote VMware estate. See `references/setup-guide.md`.
+No network, nothing executed. The seven [WRITE] tools write only to the local case
+ledger under `$OPS_HOME`; nothing here touches a remote VMware estate. Evidence, gaps,
+hypotheses and grade history are only ever added to — `timeline.md` is regenerated from
+the evidence and `case.json` holds the current grade and state. Remediation is always routed to
+aiops/pilot, where the double-confirm / approval / audit gates live (audit DB
+`~/.vmware/audit.db`). debug has no config and no connection, so it registers no
+environment resolver, and its tools do not pass through the policy engine — no policy
+rule applies to them. See `references/setup-guide.md`.
+
+**Case data is sensitive and is kept until you delete it.** Each case lives in
+`$OPS_HOME/cases/<case-id>/` (default `~/.vmware/cases/`), created owner-only (`0700`).
+It holds whatever evidence was submitted — host names, addresses, log and event text.
+Nothing is deleted automatically: `case_close` records the grade and marks the case
+closed but keeps its files. Remove a case by deleting its folder.
 
 ## License
 

{vmware_debug-1.11.2 → vmware_debug-1.11.4}/skills/vmware-debug/references/agent-guardrails.md

@@ -16,7 +16,7 @@ vmware-debug are specific to this skill.
 
 vmware-debug exposes 14 MCP tools: 7 reads and 7 writes. It connects to nothing
 and holds no credentials — the calling agent gathers events from the other
-skills, normalises them, and hands them over. The four writes go to the local
+skills, normalises them, and hands them over. The seven writes go to the local
 investigation ledger under `~/.vmware/cases/`, never to a VMware system. That
 makes it the safest skill in the family to point a small model at — and the one
 most exposed to the model's reasoning, because its output *is* an
@@ -41,12 +41,12 @@ These are structural, so it cannot.
 
 | Guardrail you would otherwise prompt for | Now enforced by |
 |---|---|
-| "Work read-only and never modify anything" | **The tool surface itself.** Both tools are reads — this skill has no write tool at all, so there is nothing to withhold and nothing to switch off. |
-| "Diagnose only — never apply the fix you propose" | **Structural.** This skill has no tool that changes anything, and it holds no connection to vCenter, NSX or anything else. Remediation is routed to vmware-aiops or vmware-pilot by the calling agent. |
+| "Work read-only and never modify anything" | **The tool surface itself.** No tool reaches a VMware system. The seven [WRITE] tools write only to this skill's own local case ledger, so there is nothing in vSphere to withhold and nothing to switch off. |
+| "Diagnose only — never apply the fix you propose" | **Structural.** This skill has no tool that changes anything outside its own ledger, and it holds no connection to vCenter, NSX or anything else. Remediation is routed to vmware-aiops or vmware-pilot by the calling agent. |
 | "Do not fabricate a timeline — build it from the events I gave you" | **`incident_timeline` correlates only its input.** It is source-agnostic and has no way to fetch anything, so the timeline cannot contain an event the agent did not supply. |
 | "Tell me when the symptom is outside what you can recognise" | **`list_symptom_categories`** states the catalogue, and unmatched symptoms come back as `uncategorized` rather than being forced into the nearest signature. |
 | "Use explicit limits for queries that may return large amounts of data" | **The list envelope.** `list_symptom_categories` returns `{items, returned, limit, total, truncated, hint}` with `truncated` always `false` — which is the point: it states that the catalogue is complete instead of leaving you to infer it. |
-| "Log everything you looked at" | **The `@vmware_tool` decorator.** Every call is recorded to `~/.vmware/audit.db`, reads included. |
+| "Log everything you looked at" | **The case ledger, for investigations.** Evidence submitted to a case is recorded with its source skill, tool, query and fetch time. Debug's own tool calls are not written to `~/.vmware/audit.db`: none of them acts on a VMware target. |
 
 ---
 

{vmware_debug-1.11.2 → vmware_debug-1.11.4}/skills/vmware-debug/references/capabilities.md

@@ -1,6 +1,9 @@
 # vmware-debug Capabilities
 
-Read-only, offline incident correlation. No network, no credentials, no writes.
+Offline incident correlation. No network, no credentials, no writes to any VMware
+system. This table covers the two stateless correlation tools; the twelve `case_*`
+investigation-ledger tools (seven of which write, to the local ledger only) are
+listed in `SKILL.md`, and their response sizes are not yet measured here.
 
 | Tool | What it returns | Typical response tokens |
 |---|---|---|

{vmware_debug-1.11.2 → vmware_debug-1.11.4}/skills/vmware-debug/references/cli-reference.md

@@ -1,6 +1,8 @@
 # vmware-debug CLI Reference
 
-All commands are read-only and offline (no network, no credentials).
+All commands are offline (no network, no credentials). All but `mcp` are
+read-only; `mcp` starts the MCP server, whose seven `case_*` write tools record
+into the local case ledger.
 
 ## triage — correlate a set of collected events
 

{vmware_debug-1.11.2 → vmware_debug-1.11.4}/skills/vmware-debug/references/setup-guide.md

@@ -6,7 +6,7 @@ is a pure, offline correlation engine. There is no `config.yaml` and no `.env`.
 ## Install
 
 ```bash
-uv tool install vmware-debug
+uv tool install vmware-debug==1.11.4
 vmware-debug categories      # verify it runs
 ```
 
@@ -15,7 +15,7 @@ vmware-debug categories      # verify it runs
 ```json
 {
   "command": "uvx",
-  "args": ["--from", "vmware-debug", "vmware-debug-mcp"]
+  "args": ["--from", "vmware-debug==1.11.4", "vmware-debug-mcp"]
 }
 ```
 
@@ -33,17 +33,28 @@ routes fixes to (vmware-aiops, vmware-pilot).
 
 1. **Source Code** — https://github.com/vmware-skills/VMware-Debug (MIT).
 2. **Credentials** — none. debug holds no secrets and connects to nothing.
-3. **Network** — none. All tools are local pure functions over event data the
-   agent supplies.
-4. **Writes** — none. debug only diagnoses and recommends; remediation is routed
+3. **Network** — none. The correlation tools are local pure functions over
+   event data the agent supplies; the case tools read and write local files.
+4. **Writes** — only to the local investigation ledger under `$OPS_HOME`
+   (the seven [WRITE] `case_*` tools). Evidence, gaps, hypotheses and grade
+   history are only ever added to; `timeline.md` is regenerated from the evidence and
+   `case.json` holds the current grade and state. Nothing is written to any
+   VMware system: debug only diagnoses and recommends; remediation is routed
    to vmware-aiops / vmware-pilot, where confirmation/approval/audit live.
+   Case data is sensitive: each case folder (`$OPS_HOME/cases/<case-id>/`, default
+   `~/.vmware/cases/`) is created owner-only (`0700`) and holds the submitted
+   evidence — host names, addresses, log and event text. There is no automatic
+   retention limit: `case_close` marks a case closed and keeps its files; delete
+   the folder to remove a case.
 5. **No cross-skill coupling** — events arrive as plain dicts (the event
    envelope); debug imports no other skill package at runtime.
 6. **Environment scoping** — policy rules can scope by environment, and skills
    that connect to a VMware estate may declare `environment:` (`production` /
    `staging` / `lab`) per target in their own `config.yaml` as an optional label
    an environment-scoped `deny` rule can match on. debug has no config and no
-   connection to declare one about, so it reports a constant `local`. Since it
-   ships no operation above read risk, nothing here is gated either way.
+   connection to declare one about, so it registers no environment resolver —
+   it has no basis to answer for any target. Its tools do not pass through the
+   policy engine either, so no policy rule, environment-scoped or not, applies
+   to them.
 7. **Static analysis** — `uvx bandit -r vmware_debug/` (release bar:
    0 Medium+).

vmware_debug-1.11.4/tests/__init__.py

@@ -0,0 +1,9 @@
+"""Test package.
+
+``tests/eval/`` and ``tests/eval/regression/`` were already packages while this
+file was missing, so ``from tests.eval.regression._vsphere_event_vocabulary
+import ...`` resolved only where the namespace-package fallback happened to
+work. It did not on Windows, and the whole suite -- 398 tests -- failed at
+collection. The other repos that use cross-module test imports all carry this
+file; this one is the half-built package.
+"""

vmware_debug-1.11.4/tests/conftest.py

@@ -0,0 +1,42 @@
+"""Session-wide sandbox: the suite must not touch the operator's real files.
+
+Installed at *import* time, not in a fixture: a fixture runs after collection
+has imported every test module and, with them, the package — too late to move
+a path something already resolved.
+
+``OPS_HOME`` moves ``vmware_policy``'s shared ``audit.db`` (and the policy,
+budget and undo state beside it) and the case ledger under ``OPS_HOME/cases``. ``HOME`` moves anything resolved
+from ``~``.
+
+This repo got the sandbox on 2026-09-11, when a sibling (VMware-VDI) was found
+writing test rows into the operator's real ``~/.vmware/audit.db`` because it
+had none. This suite was not leaking — every case test sets ``OPS_HOME`` itself with ``monkeypatch``, so one that forgets would write into the operator's real ``~/.vmware/cases`` — but that was a property of which
+tests exist today, not a protection. See
+``tests/eval/regression/test_audit_isolation.py``.
+"""
+
+from __future__ import annotations
+
+import atexit
+import os
+import shutil
+import tempfile
+from pathlib import Path
+
+from vmware_policy.audit import reset_engine
+
+# The operator's real home, captured before the redirect.
+REAL_HOME = Path(os.path.expanduser("~"))
+
+SANDBOX_HOME = Path(tempfile.mkdtemp(prefix="vmware-debug-tests-"))
+
+os.environ["HOME"] = str(SANDBOX_HOME)
+os.environ["OPS_HOME"] = str(SANDBOX_HOME / ".vmware")
+# expanduser() consults USERPROFILE on Windows; keep every spelling pointing here.
+os.environ["USERPROFILE"] = str(SANDBOX_HOME)
+
+# The audit engine is a lazily built singleton bound to the path it first
+# resolved; clear any stale binding so writes cannot go back to the real file.
+reset_engine()
+
+atexit.register(shutil.rmtree, SANDBOX_HOME, True)

{vmware_debug-1.11.2 → vmware_debug-1.11.4}/tests/eval/capability/_scoring.py

@@ -132,13 +132,13 @@ class ScoreBoard:
             ),
             "scores": merged,
         }
-        path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n")
+        path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
 
 
 def previous_scores(path: Path = SCORES_PATH) -> dict[str, Any]:
     """Load the last recorded run, or ``{}`` on a first run / unreadable file."""
     try:
-        return json.loads(path.read_text()).get("scores", {})
+        return json.loads(path.read_text(encoding="utf-8")).get("scores", {})
     except (OSError, ValueError):
         return {}