vmware-debug 1.9.0__tar.gz → 1.10.0__tar.gz

{vmware_debug-1.9.0 → vmware_debug-1.10.0}/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "vmware-debug",
   "displayName": "VMware Debug",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "Read-only VMware incident correlation: timeline, spikes, root-cause routing. 2 MCP tools.",
   "author": {
     "name": "Wei Zhou",

{vmware_debug-1.9.0 → vmware_debug-1.10.0}/.mcp.json

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

{vmware_debug-1.9.0 → vmware_debug-1.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vmware-debug
-Version: 1.9.0
+Version: 1.10.0
 Summary: VMware diagnostic brain — read-only 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

{vmware_debug-1.9.0 → vmware_debug-1.10.0}/RELEASE_NOTES.md

@@ -1,3 +1,45 @@
+## v1.10.0 — the knowledge layer is implemented, not just described
+
+v1.9.0 shipped the investigation layer with `applies_to` documented as the thing
+that makes a knowledge entry decisive. Nothing parsed a knowledge file and
+nothing checked applicability. Any file at all under the knowledge root raised
+the reported ceiling, and anything labelled `knowledge-kb` counted as decisive.
+The route to a wrong Confirmed that the design was written to close was open the
+whole time, and the metric said zero only because no fixture walked it.
+
+`case_knowledge` (the 14th tool) answers the first question anyone mounting a
+library asks — which formats are taken — without them reading a design document:
+
+    .md .markdown   YAML front-matter between --- fences, body below (preferred)
+    .yaml .yml      the whole file is one entry
+    .json           one entry per file
+    .jsonl          one JSON object per line (what ticketing systems export)
+    .csv .tsv       one entry per row; dotted columns for nested constraints
+    .txt .log       a sibling <name>.yaml carries the metadata
+
+PDF, DOCX, PPTX and HTML are named as needing conversion rather than ignored,
+and a file that cannot be parsed is reported rather than skipped.
+
+**An entry is decisive only if its own `applies_to` was checked against the
+case's recorded versions and passed.** Three things follow, each found by
+reviewing the version before it:
+
+* Knowledge evidence must say WHICH entry it is. "Some applicable entry is
+  mounted somewhere" is a different claim from "this one applies", and the first
+  version accepted it — an agent citing the entry written for 9.x could confirm
+  a case about 8.0.3 as long as an unrelated entry happened to match.
+* A constraint the case scope cannot answer is not a match. Silence is not a
+  pass; reading it as one is how an entry for different hardware ends a case.
+* **A constraint the checker cannot evaluate is not a pass either.** The first
+  version understood product, build, driver and firmware and treated every other
+  key as satisfied, so `build` without a `product`, a `hardware_model` list, and
+  an outright typo all came back decisive. Unknown and satisfied must never be
+  the same answer.
+
+Given two entries that read identically — one for `>=8.0, <9.0`, one for
+`>=9.0` — a case scoped to vSphere 8.0.3 now reaches Confirmed citing the first
+and stays at Probable citing the second, naming the range that excluded it.
+
 ## v1.9.0 — the investigation layer: 2 tools become 13
 
 Correlating events answers "what happened together". A case answers "what do we

{vmware_debug-1.9.0 → vmware_debug-1.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vmware-debug"
-version = "1.9.0"
+version = "1.10.0"
 description = "VMware diagnostic brain — read-only incident triage, log/event correlation, and root-cause routing across the VMware skill family"
 readme = "README.md"
 license = "MIT"

{vmware_debug-1.9.0 → vmware_debug-1.10.0}/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/vmware-skills/VMware-Debug",
     "source": "github"
   },
-  "version": "1.9.0",
+  "version": "1.10.0",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "vmware-debug",
-      "version": "1.9.0",
+      "version": "1.10.0",
       "transport": {
         "type": "stdio"
       }

{vmware_debug-1.9.0 → vmware_debug-1.10.0}/skills/vmware-debug/SKILL.md

@@ -100,7 +100,7 @@ a recommended plan.
 - **MCP** (in an agent): the agent calls the other skills' read tools, then `incident_timeline` to correlate. This is the primary mode — that's where the cross-skill "联动" happens.
 - **CLI** (humans): `vmware-debug triage --events events.json` correlates a JSON array you collected yourself.
 
-## MCP Tools (13 — 6 read, 7 write)
+## MCP Tools (14 — 7 read, 7 write)
 
 **Correlation** — stateless, for a single look:
 
@@ -115,6 +115,7 @@ a recommended plan.
 |---|---|
 | `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 |
@@ -179,6 +180,52 @@ so the gap is visible now rather than when the conclusion refuses to firm up.
 "readiness 78%" cannot. Two classes served by the *same* skill count as one
 source, so it agrees with what `case_grade` will actually award.
 
+### Mounting a knowledge library
+
+`case_knowledge` answers "what can I add" without anyone reading this file.
+Entries go under `$OPS_HOME/knowledge/{kb,runbook,sr,cases}/`:
+
+| Format | How metadata travels |
+|---|---|
+| `.md` `.markdown` | YAML front-matter between `---` fences, body below — **preferred** |
+| `.yaml` `.yml` | the whole file is one entry |
+| `.json` | one entry per file |
+| `.jsonl` | one JSON object per line — what ticketing systems export |
+| `.csv` `.tsv` | one entry per row; use dotted columns (`driver.version`) for nested constraints |
+| `.txt` `.log` | a sibling `<name>.yaml` carries the metadata |
+
+PDF, DOCX, PPTX and HTML must be converted to Markdown first — `case_knowledge`
+names them rather than ignoring them.
+
+**Every entry needs an `applies_to` block to be decisive:**
+
+```yaml
+---
+id: KB-2026-0417
+applies_to:
+  product: vsphere
+  build: ">=8.0.3, <9.0"
+  driver: {name: nvme_pcie, version: ">=1.2.4"}
+  firmware: {vendor: dell, version: ">=52.26"}
+---
+```
+
+`product`, `build`, `driver` and `firmware` are the constraints the checker
+evaluates. **Any other key leaves the entry non-decisive** — including a typo —
+because an unverified constraint is not a satisfied one, and `case_knowledge`
+names the key it could not check.
+
+Knowledge evidence must say **which** entry it is
+(`case_submit_evidence(source_skill="knowledge-kb", knowledge_entry_id="KB-…")`)
+— "some applicable entry is mounted somewhere" is a different claim from "this
+one applies", and only the second can carry a conclusion.
+
+Matching is **by version applicability, never by similarity** — an entry written
+for the wrong build reads exactly like the right one, and similarity is the only
+thing that would let it through. An entry with no `applies_to` can support a
+hypothesis but can never make a case Confirmed. A constraint the case scope
+cannot answer is not a match either: silence is not a pass.
+
 > **On a stock install the ceiling is Probable.** Confirmed needs a decisive
 > source, and there is neither a hardware-diagnostic channel (no Redfish/BMC, no
 > SMART/NVMe) nor a knowledge library mounted — `~/.vmware/knowledge/` ships

{vmware_debug-1.9.0 → vmware_debug-1.10.0}/skills/vmware-debug/references/agent-guardrails.md

@@ -14,7 +14,7 @@ vmware-monitor and vmware-aria against a production vSphere estate with Llama
 cross-skill rules are identical across this family; the parts below marked
 vmware-debug are specific to this skill.
 
-vmware-debug exposes 13 MCP tools: 6 reads and 7 writes. It connects to nothing
+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
 investigation ledger under `~/.vmware/cases/`, never to a VMware system. That

{vmware_debug-1.9.0 → vmware_debug-1.10.0}/tests/eval/capability/_scores.json

@@ -9,13 +9,14 @@
           "list_symptom_categories",
           "case_open",
           "case_list",
-          "case_readiness"
+          "case_readiness",
+          "case_knowledge"
         ],
         "reachable_on_surface": 8,
         "reachable_only_via_description": 0,
         "required_entity_params": 8,
         "required_params_classified": "8/17",
-        "tool_count": 13
+        "tool_count": 14
       },
       "maximum": 8,
       "pct": 100.0,
@@ -43,12 +44,12 @@
     },
     "entry_point_availability": {
       "detail": {
-        "full_entry_points": 5
+        "full_entry_points": 6
       },
-      "maximum": 13,
-      "pct": 38.5,
+      "maximum": 14,
+      "pct": 42.9,
       "unit": "entry points",
-      "value": 5
+      "value": 6
     },
     "error_actionability": {
       "detail": {
@@ -77,7 +78,7 @@
               "names_artifact",
               "states_remedy"
             ],
-            "where": "evidence.py:281"
+            "where": "evidence.py:289"
           },
           {
             "message": "gaps.json in case {} is not valid JSON: {}. It was hand-edited. Restore it rather than deleting it \u2014",
@@ -85,7 +86,7 @@
               "names_artifact",
               "states_remedy"
             ],
-            "where": "evidence.py:283"
+            "where": "evidence.py:291"
           },
           {
             "message": "Cannot read grading_rules.yaml at {}: {}",
@@ -93,7 +94,7 @@
               "names_artifact",
               "states_remedy"
             ],
-            "where": "grading.py:55"
+            "where": "grading.py:56"
           },
           {
             "message": "grading_rules.yaml at {} is not valid YAML: {}. Fix it rather than deleting it \u2014 falling back to the",
@@ -101,7 +102,7 @@
               "names_artifact",
               "states_remedy"
             ],
-            "where": "grading.py:57"
+            "where": "grading.py:58"
           },
           {
             "message": "A hypothesis needs a statement \u2014 what you think happened, in one line. An unnamed hypothesis cannot ",
@@ -195,18 +196,18 @@
           "case_open": 354,
           "case_plan": 360,
           "case_record_gap": 337,
-          "case_submit_evidence": 549,
+          "case_submit_evidence": 621,
           "incident_timeline": 329
         },
-        "manifest_tokens": 3428,
-        "mean_tokens_per_tool": 263.7,
+        "manifest_tokens": 3777,
+        "mean_tokens_per_tool": 269.8,
         "reference_context": 16384,
-        "tool_count": 13
+        "tool_count": 14
       },
       "maximum": 16384,
-      "pct": 79.1,
+      "pct": 76.9,
       "unit": "tokens",
-      "value": 12956
+      "value": 12607
     },
     "parameter_documentation_coverage": {
       "detail": {
@@ -226,10 +227,10 @@
           ]
         }
       },
-      "maximum": 43,
-      "pct": 83.7,
+      "maximum": 45,
+      "pct": 84.4,
       "unit": "parameters",
-      "value": 36
+      "value": 38
     },
     "per_tool_token_discipline": {
       "detail": {
@@ -237,13 +238,13 @@
         "over_ceiling": {
           "case_open": 354,
           "case_plan": 360,
-          "case_submit_evidence": 549
+          "case_submit_evidence": 621
         }
       },
-      "maximum": 13,
-      "pct": 76.9,
+      "maximum": 14,
+      "pct": 78.6,
       "unit": "tools",
-      "value": 10
+      "value": 11
     },
     "read_only_manifest_saving": {
       "detail": {
@@ -263,10 +264,10 @@
       "detail": {
         "unmarked": []
       },
-      "maximum": 13,
+      "maximum": 14,
       "pct": 100.0,
       "unit": "points",
-      "value": 13
+      "value": 14
     },
     "remedy_survives_truncation": {
       "detail": {
@@ -277,10 +278,10 @@
           "envelope.py:138",
           "conclusion.py:135",
           "conclusion.py:144",
-          "evidence.py:172",
-          "evidence.py:204",
-          "evidence.py:240",
-          "grading.py:65",
+          "evidence.py:179",
+          "evidence.py:211",
+          "evidence.py:248",
+          "grading.py:66",
           "hypotheses.py:47",
           "hypotheses.py:70"
         ]
@@ -300,14 +301,14 @@
     "tool_description_quality": {
       "detail": {
         "per_dimension_pct": {
-          "args": 76.9,
-          "gotcha": 84.6,
+          "args": 78.6,
+          "gotcha": 85.7,
           "marker": 100.0,
-          "next_hop": 61.5,
+          "next_hop": 57.1,
           "what": 100.0,
-          "when": 92.3
+          "when": 92.9
         },
-        "tools_graded": 13,
+        "tools_graded": 14,
         "weakest_tools": {
           "case_close": [
             "next_hop"
@@ -319,6 +320,9 @@
             "args",
             "next_hop"
           ],
+          "case_knowledge": [
+            "next_hop"
+          ],
           "case_list": [
             "gotcha",
             "next_hop"
@@ -332,29 +336,26 @@
           ],
           "case_submit_evidence": [
             "args"
-          ],
-          "case_timeline": [
-            "args"
           ]
         }
       },
-      "maximum": 78,
-      "pct": 85.9,
+      "maximum": 84,
+      "pct": 85.7,
       "unit": "points",
-      "value": 67
+      "value": 72
     },
     "tool_failure_payload_quality": {
       "detail": {
         "bare_string_error_lines": [],
-        "carries_hint": 12,
-        "dict_shaped": 12,
-        "error_return_sites": 12,
-        "hint_names_artifact": 12
+        "carries_hint": 13,
+        "dict_shaped": 13,
+        "error_return_sites": 13,
+        "hint_names_artifact": 13
       },
-      "maximum": 36,
+      "maximum": 39,
       "pct": 100.0,
       "unit": "checks",
-      "value": 36
+      "value": 39
     }
   }
 }

{vmware_debug-1.9.0 → vmware_debug-1.10.0}/tests/eval/regression/test_investigation_metrics.py

@@ -114,12 +114,17 @@ def test_wrong_confirmed_rate_is_zero(label, sources, gaps, _unused):
     assert grade != "confirmed", f"{label!r} reached Confirmed — grade was {grade}"
 
 
-def test_the_only_route_to_confirmed_is_the_intended_one():
+def test_the_only_route_to_confirmed_is_the_intended_one(tmp_path):
     """The counterpart. A metric that can only fail is not measuring anything —
-    if nothing can reach Confirmed, 'wrong-Confirmed rate is zero' is vacuous."""
-    cid = _case()
+    if nothing can reach Confirmed, 'wrong-Confirmed rate is zero' is vacuous.
+
+    Reaching it now takes a mounted entry whose applies_to matches, which is
+    exactly the bar the design sets.
+    """
+    _kb(tmp_path, "KB-ok.md", "applies_to:\n  product: vsphere\n")
+    cid = _scoped_case({"vsphere": "8.0.3"})
     _ev(cid, "vmware-monitor")
-    _ev(cid, "knowledge-sr")
+    _ev(cid, "knowledge-sr", knowledge_entry_id="KB-ok.md")
     assert grade_case(cid).grade == "confirmed"
 
 
@@ -215,3 +220,97 @@ def test_every_unreachable_source_carries_a_remedy():
         cid = _case()
         for u in plan_next(cid, category=category)["unavailable"]:
             assert u["how_to_supply"], f"{category}: {u['evidence_class']} has no remedy"
+
+
+# ── Metric 1, continued: the route the design says must not exist ──────────
+#
+# Added after the knowledge layer was implemented. Until then `applies_to` was
+# prose: any file at all raised the ceiling and anything labelled `knowledge-kb`
+# counted as decisive. The wrong-Confirmed metric passed only because no fixture
+# exercised the one route a wrong Confirmed actually takes.
+
+
+def _kb(tmp_path, name, applies_block):
+    p = tmp_path / "vmware" / "knowledge" / "kb" / name
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(f"---\nid: {name}\n{applies_block}---\nbody\n")
+
+
+def _scoped_case(versions):
+    cid = create_case(
+        Scope(
+            summary=f"scoped {next(_SEQ)}",
+            determined_by="test",
+            product_versions=versions,
+        ),
+        at=AT,
+    ).case_id
+    add_hypothesis(cid, "failing device")
+    return cid
+
+
+def test_a_knowledge_entry_for_the_wrong_build_cannot_confirm(tmp_path):
+    """The canonical wrong Confirmed. The entry is real, well-formed, and about
+    the right product — and it is for 9.x while this estate runs 8.0.3."""
+    _kb(tmp_path, "KB-1.md", "applies_to:\n  product: vsphere\n  build: '>=9.0'\n")
+    cid = _scoped_case({"vsphere": "8.0.3"})
+    _ev(cid, "vmware-monitor")
+    _ev(cid, "knowledge-kb")
+    assert grade_case(cid).grade != "confirmed"
+
+
+def test_a_knowledge_entry_with_no_applies_to_cannot_confirm(tmp_path):
+    _kb(tmp_path, "KB-2.md", "")
+    cid = _scoped_case({"vsphere": "8.0.3"})
+    _ev(cid, "vmware-monitor")
+    _ev(cid, "knowledge-kb")
+    assert grade_case(cid).grade != "confirmed"
+
+
+def test_a_matching_entry_does_confirm(tmp_path):
+    """The counterpart, so the rule above is a filter and not a wall."""
+    _kb(tmp_path, "KB-3.md", "applies_to:\n  product: vsphere\n  build: '>=8.0, <9.0'\n")
+    cid = _scoped_case({"vsphere": "8.0.3"})
+    _ev(cid, "vmware-monitor")
+    _ev(cid, "knowledge-kb", knowledge_entry_id="KB-3.md")
+    assert grade_case(cid).grade == "confirmed"
+
+
+def test_citing_the_wrong_entry_does_not_borrow_a_matching_one(tmp_path):
+    """Caught reviewing the applicability filter.
+
+    The first version passed when ANY mounted entry applied, so an agent citing
+    the entry written for 9.x could confirm a case about 8.0.3 as long as some
+    unrelated entry happened to match. "An entry is decisive only if ITS
+    applies_to passed" was true of the docstring and not of the code.
+
+    Knowledge evidence now has to say which entry it is, and that entry is the
+    one checked.
+    """
+    _kb(tmp_path, "KB-right.md", "applies_to:\n  product: vsphere\n  build: '>=8.0, <9.0'\n")
+    _kb(tmp_path, "KB-wrong.md", "applies_to:\n  product: vsphere\n  build: '>=9.0'\n")
+    cid = _scoped_case({"vsphere": "8.0.3"})
+    _ev(cid, "vmware-monitor")
+    _ev(cid, "knowledge-kb", knowledge_entry_id="KB-wrong.md")
+    assert grade_case(cid).grade != "confirmed"
+
+
+def test_citing_the_right_entry_confirms(tmp_path):
+    _kb(tmp_path, "KB-right.md", "applies_to:\n  product: vsphere\n  build: '>=8.0, <9.0'\n")
+    _kb(tmp_path, "KB-wrong.md", "applies_to:\n  product: vsphere\n  build: '>=9.0'\n")
+    cid = _scoped_case({"vsphere": "8.0.3"})
+    _ev(cid, "vmware-monitor")
+    _ev(cid, "knowledge-kb", knowledge_entry_id="KB-right.md")
+    assert grade_case(cid).grade == "confirmed"
+
+
+def test_knowledge_evidence_that_names_no_entry_is_not_decisive(tmp_path):
+    """Without the id there is nothing to check, and 'something applicable
+    exists somewhere' is not the same claim."""
+    _kb(tmp_path, "KB-right.md", "applies_to:\n  product: vsphere\n---\n")
+    cid = _scoped_case({"vsphere": "8.0.3"})
+    _ev(cid, "vmware-monitor")
+    _ev(cid, "knowledge-kb")
+    r = grade_case(cid)
+    assert r.grade != "confirmed"
+    assert any("which entry" in x for x in r.reasons), r.reasons

{vmware_debug-1.9.0 → vmware_debug-1.10.0}/tests/test_case_grading.py

@@ -31,6 +31,21 @@ def isolated_home(tmp_path, monkeypatch):
     monkeypatch.setenv("OPS_HOME", str(tmp_path / "vmware"))
 
 
+@pytest.fixture
+def mounted_kb(tmp_path):
+    """A knowledge entry that genuinely applies to the case fixture's scope.
+
+    Submitting evidence labelled `knowledge-sr` used to be enough to confirm a
+    case; the label did all the work. Now the entry has to exist and its
+    applies_to has to match, so a test that wants Confirmed has to construct one
+    — which is the point.
+    """
+    p = tmp_path / "vmware" / "knowledge" / "kb" / "KB-fixture.md"
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text("---\nid: KB-fixture\napplies_to:\n  product: vsphere\n---\nbody\n")
+    return p
+
+
 @pytest.fixture
 def case():
     """A case with H1 already registered.
@@ -39,12 +54,22 @@ def case():
     unregistered hypothesis is now refused — a dangling id used to block and
     falsify nothing while silently costing a grade level.
     """
-    cid = create_case(Scope(summary="vsan latency", determined_by="alarm 42"), at=AT).case_id
+    cid = create_case(
+        Scope(
+            summary="vsan latency", determined_by="alarm 42",
+            product_versions={"vsphere": "8.0.3"},
+        ),
+        at=AT,
+    ).case_id
     add_hypothesis(cid, "failing device")
     return cid
 
 
 def evidence(skill="vmware-monitor", tool="list_events", **kw):
+    # Knowledge evidence must say which entry it is; without that its
+    # applicability cannot be checked and it is not decisive.
+    if skill in ("knowledge-kb", "knowledge-sr") and "knowledge_entry_id" not in kw:
+        kw["knowledge_entry_id"] = "KB-fixture"
     return Evidence(
         source_skill=skill,
         source_tool=tool,
@@ -131,7 +156,7 @@ class TestConfirmedNeedsADecisiveSource:
             record_evidence(case, evidence(skill=skill))
         assert grade_case(case).grade == "probable"
 
-    def test_a_decisive_source_reaches_confirmed(self, case):
+    def test_a_decisive_source_reaches_confirmed(self, case, mounted_kb):
         record_evidence(case, evidence(skill="vmware-monitor"))
         record_evidence(case, evidence(skill="knowledge-sr"))
         assert grade_case(case).grade == "confirmed"
@@ -178,7 +203,7 @@ class TestExclusionNeedsAFalsifyingObservation:
 
 
 class TestDemotion:
-    def test_a_new_gap_takes_confirmed_back_down_to_probable(self, case):
+    def test_a_new_gap_takes_confirmed_back_down_to_probable(self, case, mounted_kb):
         record_evidence(case, evidence(skill="vmware-monitor"))
         record_evidence(case, evidence(skill="knowledge-sr"))
         assert grade_case(case).grade == "confirmed"
@@ -265,7 +290,7 @@ class TestTheRulesFileHasNoDecorativeKnobs:
         p.parent.mkdir(parents=True, exist_ok=True)
         p.write_text(body)
 
-    def test_relaxing_the_prerequisite_actually_relaxes_it(self, case, tmp_path):
+    def test_relaxing_the_prerequisite_actually_relaxes_it(self, case, tmp_path, mounted_kb):
         """One decisive source, no corroboration: Confirmed under the relaxed
         rule, and not under the packaged one."""
         record_evidence(case, evidence(skill="knowledge-sr"))