compass-kb-validation 3.0.0__tar.gz → 3.2.0__tar.gz

{compass_kb_validation-3.0.0 → compass_kb_validation-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: compass-kb-validation
-Version: 3.0.0
+Version: 3.2.0
 Summary: Knowledge-base readiness validation for RAG & AI agents — config-driven, deterministic pipeline integrity checks.
 Author: COMPASS
 License: MIT

{compass_kb_validation-3.0.0 → compass_kb_validation-3.2.0}/compass/__init__.py

@@ -5,4 +5,4 @@ end-to-end: API upload -> object storage -> knowledge graph -> vector store ->
 retrieval quality, plus cross-store consistency.
 """
 
-__version__ = "3.0.0"
+__version__ = "3.2.0"

{compass_kb_validation-3.0.0 → compass_kb_validation-3.2.0}/compass/cli.py

@@ -36,6 +36,13 @@ pipeline:
   critical_steps: []
   readiness_threshold: 1.0       # READY when document pass-rate >= this (e.g. 0.99)
 
+# Advisory checks you have ACCEPTED as expected for this corpus (e.g. an insurance KB where
+# near-duplicate boilerplate is normal). They drop out of the hygiene / Platform Health scores
+# but are still counted and shown ("N suppressed"). Only advisory checks - a hard gating failure
+# is never suppressed. Ad-hoc equivalent: `compass discover --suppress "Near-duplicate embeddings"`.
+# suppressions:
+#   - "Near-duplicate embeddings"
+
 environments:
   dev:
     redis:

{compass_kb_validation-3.0.0 → compass_kb_validation-3.2.0}/compass/config/__init__.py

@@ -750,6 +750,12 @@ class Settings:
     display_name: str = ""
     environment: str = "dev"
     skip_steps: list[str] = field(default_factory=list)
+    # Advisory check labels the project has ACCEPTED as expected for this corpus (e.g. an
+    # insurance KB where near-duplicate boilerplate is normal). Suppressed advisories are
+    # excluded from the hygiene / Platform Health scores but still counted and shown ("N
+    # suppressed"). Only advisory (warn) checks can be suppressed - a hard gating failure
+    # always counts, so a known-issue can never mask a real failure.
+    suppressions: list[str] = field(default_factory=list)
     # Advisories raised while loading (e.g. an unrecognized top-level block that was
     # ignored). Surfaced by validate_config so a silently-dropped key is never invisible.
     config_warnings: list[str] = field(default_factory=list)
@@ -760,7 +766,7 @@ class Settings:
 # --------------------------------------------------------------------------- #
 # Non-service top-level keys that are legitimately not a service block.
 _META_KEYS = frozenset({"default_env", "display_name", "environments", "skip_steps",
-                        "pipeline_dependencies"})
+                        "pipeline_dependencies", "suppressions"})
 # The service-config blocks that may appear at the top level or under an environment.
 # Single source of truth: the flatten loop AND the unknown-key check both read this, so a
 # new block can never be added to one and forgotten in the other (which is exactly how
@@ -903,6 +909,7 @@ def load_settings(
         display_name=merged.get("display_name", ""),
         environment=resolved_env,
         skip_steps=list(merged.get("skip_steps", [])),
+        suppressions=list(merged.get("suppressions", [])),
     )
     # The embedding block's declared dimension IS the index's expected dimension. Cross-fill
     # it into the vector-store check when that check has no explicit value, so a project

{compass_kb_validation-3.0.0 → compass_kb_validation-3.2.0}/compass/report/__init__.py

@@ -80,8 +80,11 @@ _STEP_CATEGORY = {
     "API Upload": "Ingestion API",
 }
 _CAT_PATTERNS = [
-    ("Metadata & Consistency", re.compile(r"e_tag|required field|metadata consist|positional|section|page metadata|directory|predicate|date format|email|field rule", re.I)),
-    ("Chunk Structure", re.compile(r"boundaries|chunk count|size within|ordering|overlap", re.I)),
+    ("Metadata & Consistency", re.compile(r"e_tag|required field|metadata consist|page metadata|directory|predicate|date format|email|field rule", re.I)),
+    # 'positional correctness', 'chunk structure coherence' and 'all chunks validated' are
+    # STRUCTURAL (chunk ordering / integrity), not metadata - keep them out of the metadata
+    # bucket and out of an opaque "Other".
+    ("Chunk Structure", re.compile(r"boundaries|chunk count|chunk structure|all chunks|coheren|positional|section split|size within|ordering|overlap", re.I)),
     ("Embedding Quality", re.compile(r"embedding|normaliz|near-duplicate|dimension|distance metric", re.I)),
     ("Content Preservation", re.compile(r"fidelity|coverage|contaminat|duplicate|header|footer|table/figure", re.I)),
     ("Index & Schema", re.compile(r"index|schema", re.I)),
@@ -115,6 +118,35 @@ li .check-hint{margin:4px 0 0 0;display:block;}
 .rec-list{padding:14px 16px 16px;display:flex;flex-direction:column;gap:10px;}
 .rec-fix{font-size:12.5px;line-height:1.55;color:var(--ink);}
 .rec-more{font-size:12px;color:var(--muted);padding:4px 2px;}
+/* Action Plan confidence tiers: Observed (fact) / Likely (primary) / Possible (alternates). */
+.rca-line{display:flex;gap:8px;align-items:baseline;font-size:12.5px;line-height:1.55;color:var(--ink);margin-top:3px;}
+.rca-line:first-child{margin-top:0;}
+.conf-tag{flex:none;font-size:9.5px;font-weight:800;text-transform:uppercase;letter-spacing:.05em;padding:1px 7px;border-radius:999px;line-height:1.5;}
+.conf-tag.observed{background:rgba(37,99,235,.13);color:var(--accent);}
+.conf-tag.likely{background:rgba(217,119,6,.14);color:var(--warn);}
+.conf-tag.possible{background:var(--chip-bg);color:var(--muted);}
+/* Platform Health: a compact per-subsystem pass-rate rollup (dimensions are dynamic). */
+.phz{margin-top:12px;padding-top:11px;border-top:1px solid var(--line);}
+.phz-head{display:flex;align-items:baseline;gap:6px;margin-bottom:8px;}
+.phz-cap{font-size:10px;text-transform:uppercase;letter-spacing:.06em;color:var(--muted);font-weight:700;}
+.phz-overall{font-size:17px;font-weight:800;margin-left:auto;font-variant-numeric:tabular-nums;}
+.phz-overall.ok{color:var(--ok);}.phz-overall.warn{color:var(--warn);}.phz-overall.bad{color:var(--bad);}
+.phz-max{font-size:11px;color:var(--muted);font-weight:600;}
+.phz-grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(170px,1fr));gap:8px 16px;}
+.phz-top{display:flex;justify-content:space-between;align-items:baseline;font-size:11px;margin-bottom:2px;gap:8px;}
+.phz-name{color:var(--muted);white-space:nowrap;overflow:hidden;text-overflow:ellipsis;}
+.phz-score{flex:none;}
+.phz-score{font-weight:800;font-variant-numeric:tabular-nums;}
+.phz-score.ok{color:var(--ok);}.phz-score.warn{color:var(--warn);}.phz-score.bad{color:var(--bad);}
+.phz-bar{height:4px;border-radius:999px;background:var(--chip-bg);overflow:hidden;}
+.phz-bar i{display:block;height:100%;border-radius:999px;}
+.phz-bar i.ok{background:var(--ok);}.phz-bar i.warn{background:var(--warn);}.phz-bar i.bad{background:var(--bad);}
+/* Engineering Wins: the healthy counterpart to the Action Plan. */
+.wins-block{margin-top:16px;padding:12px 14px;background:rgba(22,163,74,.06);border:1px solid rgba(22,163,74,.2);border-radius:10px;}
+.wins-cap{font-size:10px;text-transform:uppercase;letter-spacing:.06em;color:var(--ok);font-weight:800;margin-bottom:8px;}
+.wins-grid{display:flex;flex-wrap:wrap;gap:7px 16px;}
+.win-item{display:flex;align-items:center;gap:6px;font-size:12.5px;color:var(--ink);}
+.win-tick{color:var(--ok);font-weight:800;}
 @media(max-width:600px){.subsys-row{grid-template-columns:1fr;gap:3px;}}
 .exec-bullets{margin:0 0 4px;padding-left:18px;font-size:13.5px;line-height:1.75;color:var(--ink);}
 .exec-bullets li{margin:0;}
@@ -285,7 +317,8 @@ def _result_payload(name: str, r: PipelineResult) -> dict:
     }
 
 
-def _aggregate(cases: list[dict], hide_skipped: bool = True) -> dict:
+def _aggregate(cases: list[dict], hide_skipped: bool = True,
+               suppress: set[str] | None = None) -> dict:
     total = len(cases)
     passed = sum(1 for c in cases if c["overall"] == "PASSED")
     failed = sum(1 for c in cases if c["overall"] == "FAILED")
@@ -298,6 +331,12 @@ def _aggregate(cases: list[dict], hide_skipped: bool = True) -> dict:
     # check is either a HARD failure (fails the step) or an ADVISORY warning (does not).
     # Neutral checks (the backend/config can't evaluate them) are counted separately.
     checks_hard = checks_advisory = checks_neutral = 0
+    # Advisory checks a project has explicitly accepted (config `suppressions`). They are
+    # excluded from scoring - like neutral checks - but tallied and shown, never hidden. HARD
+    # (gating) checks can NEVER be suppressed, so an accepted known-issue can't mask a failure.
+    checks_suppressed = 0
+    suppressed: Counter = Counter()
+    suppress = suppress or set()
     cat = {name: {"total": 0, "passed": 0, "adv_total": 0, "adv_passed": 0} for name, _ in _CAT_ORDER}
     # Which checks fail across the MOST documents. One systemic cause usually shows up as
     # one label repeated over many documents, so ranking by document count points at the
@@ -337,10 +376,19 @@ def _aggregate(cases: list[dict], hide_skipped: bool = True) -> dict:
                 if ch.get("supported", True) is False:
                     checks_neutral += 1  # neutral — backend can't evaluate this check
                     continue
-                k = _categorise(ch.get("label", ""), step_name)
+                _label = ch.get("label", "")
+                _sev = "warn" if str(ch.get("severity", "hard")).lower() == "warn" else "hard"
+                # Suppressed = an ADVISORY check the project accepted as expected (e.g. known
+                # boilerplate near-duplicates). Excluded from scoring but counted + shown.
+                # Only advisory can be suppressed - a hard/gating check ignores the list.
+                if _sev == "warn" and _label in suppress:
+                    checks_suppressed += 1
+                    suppressed[_label] += 1
+                    continue
+                k = _categorise(_label, step_name)
                 cat[k]["total"] += 1
                 ch_passed = bool(ch.get("passed"))
-                sev = "warn" if str(ch.get("severity", "hard")).lower() == "warn" else "hard"
+                sev = _sev
                 # Hygiene tracks ADVISORY (WARN) checks only - the quality BEYOND the
                 # integrity gate. HARD checks passing is what READY already reports, so
                 # counting them would just pull hygiene toward 100 and hide the signal.
@@ -355,9 +403,17 @@ def _aggregate(cases: list[dict], hide_skipped: bool = True) -> dict:
                     checks_advisory += 1
                 else:
                     checks_hard += 1
-                label = ch.get("label", "")
-                rec = offenders.setdefault(label, {"label": label, "docs": 0, "severity": sev, "step": step_name})
+                label = _label
+                rec = offenders.setdefault(
+                    label, {"label": label, "docs": 0, "severity": sev, "step": step_name, "detail": ""})
                 rec["docs"] += 1
+                # Keep one concrete, measured example (the check's own detail, e.g.
+                # "4200 (~3000 expected)") so the Action Plan can show a specific number
+                # instead of a generic cause. First non-empty wins - deterministic.
+                if not rec["detail"]:
+                    _dv = str(ch.get("detail") or "").strip()
+                    if _dv:
+                        rec["detail"] = _dv
                 # a label is HARD overall if it ever gates
                 if sev == "hard":
                     rec["severity"] = "hard"
@@ -401,6 +457,11 @@ def _aggregate(cases: list[dict], hide_skipped: bool = True) -> dict:
         # rests on less than the full pipeline.
         "docs_incomplete": docs_incomplete,
         "hygiene": hygiene,
+        # Accepted advisory issues (config `suppressions`): count + per-label tally, shown
+        # so a suppressed warning is disclosed, never silently dropped.
+        "checks_suppressed": checks_suppressed,
+        "suppressed": [{"label": lbl, "docs": n} for lbl, n in
+                       sorted(suppressed.items(), key=lambda kv: (-kv[1], kv[0]))],
     }
 
 
@@ -412,15 +473,16 @@ _HYGIENE_TIERS = (
 )
 
 
-def hygiene_from_results(results: list[dict]) -> dict | None:
+def hygiene_from_results(results: list[dict], suppress: list[str] | None = None) -> dict | None:
     """Public: compute the KB Hygiene score from a list of ``{name, result}`` items.
 
     Same deterministic scoring the report uses, exposed so the CLI can gate on it
-    (``--quality-threshold``) without rendering HTML. Returns None if there are no
-    advisory checks to score.
+    (``--quality-threshold``) without rendering HTML. ``suppress`` accepts the same accepted
+    advisory labels as the report, so the gate and the report agree. Returns None if there
+    are no advisory checks to score.
     """
     cases = [_result_payload(item.get("name", item["result"].file_name), item["result"]) for item in results]
-    return _aggregate(cases).get("hygiene")
+    return _aggregate(cases, suppress=set(suppress or [])).get("hygiene")
 
 
 def _hygiene_score(cat: dict) -> dict | None:
@@ -661,6 +723,12 @@ def _exec_summary(agg: dict, corpus: dict | None = None, cases: list[dict] | Non
                      f'these documents - see Coverage">{agg["docs_incomplete"]} not fully validated</span>')
     if agg.get("checks_advisory"):
         chips.append(f'<span class="hero-chip">{agg["checks_advisory"]} advisory</span>')
+    if agg.get("checks_suppressed"):
+        # Accepted known-issues: disclosed, never hidden. Tooltip names what was suppressed.
+        acc = ", ".join(f'{s["label"]} (x{s["docs"]})' for s in agg.get("suppressed", [])[:8])
+        chips.append(f'<span class="hero-chip" data-tip="Accepted advisory issues (config '
+                     f'suppressions) - excluded from hygiene &amp; health, never from the gate: '
+                     f'{_esc(acc)}">{agg["checks_suppressed"]} suppressed</span>')
     chips_html = f'<div class="hero-chips">{"".join(chips)}</div>' if chips else ""
     t = max(agg["total"], 1)
     seg = ""
@@ -692,8 +760,10 @@ def _exec_summary(agg: dict, corpus: dict | None = None, cases: list[dict] | Non
             <span><i class="warn"></i> {agg['partial']} partial</span>
             <span><i class="bad"></i> {agg['failed']} failed</span>
           </div>
+          {_health_strip(_platform_health(agg.get('cat_rows', [])))}
         </div>
       </div>
+      {_wins_block(agg)}
       <div class="exec-stats summary-stats-foot">
         <div class="exec-stat"><div class="v">{agg['total']}</div><div class="l">Documents</div></div>
         <div class="exec-stat"><div class="v">{agg['steps_passed']}/{agg['steps_total']}</div><div class="l">Steps Passed</div></div>
@@ -848,6 +918,135 @@ _EFFORT = {
 _EFFORT_RANK = {"LOW": 0, "MEDIUM": 1, "HIGH": 2}
 _ACTION_CAP = 6   # max cards in the always-open Action Plan; the rest are in the collapsible list
 
+# A category-specific, ACTIONABLE fix (an instruction), distinct from _ROOT_CAUSE (a cause).
+# Keeping one per subsystem stops two different cards printing the same remediation verbatim.
+_FIX_GUIDANCE = {
+    "Chunk Structure": "Re-chunk with a size/overlap that fits these documents and keep splits on sentence or paragraph boundaries.",
+    "Embedding Quality": "Re-embed after de-duplicating and stripping boilerplate; confirm the model and dimension match the index.",
+    "Content Preservation": "Strip headers/footers before chunking and verify ingestion drops or duplicates no source text.",
+    "Metadata & Consistency": "Backfill the missing metadata field and reconcile its value across the stores that disagree.",
+    "Index & Schema": "Align the index field types and vector config with what the pipeline actually writes.",
+    "Retrieval & Query": "Verify the query-embedding path and metadata filters, then re-tune the similarity threshold.",
+    "Knowledge Graph": "Re-ingest the graph so every document has its expected nodes, links, and typing.",
+    "Object Storage": "Restore the missing or altered source objects and re-run the storage stage.",
+    "Cross-Stage Consistency": "Re-run ingestion so every store agrees on id, hash, and content for each document.",
+    "Ingestion API": "Inspect the upload response and retry ingestion for documents without a success id.",
+    "Other": "Review the grouped checks below and address the shared cause.",
+}
+# Secondary hypotheses. Rendered under "Possible" so the report separates what it MEASURED
+# (Observed) from its primary guess (Likely) and the alternates it cannot rule out (Possible).
+_POSSIBLE_CAUSES = {
+    "Chunk Structure": ["Source documents vary widely in length", "Overlap set too low for cross-boundary context"],
+    "Embedding Quality": ["Repetitive/boilerplate text inflating near-duplicates", "A model or dimension mismatch at write time"],
+    "Content Preservation": ["Tables or figures dropped by the extractor", "Headers/footers folded into chunk bodies"],
+    "Metadata & Consistency": ["A field renamed between stores", "Ingestion wrote before metadata was attached"],
+    "Index & Schema": ["Schema drifted after an upgrade", "A field indexed with the wrong type"],
+    "Retrieval & Query": ["A metadata filter excluding valid chunks", "Similarity threshold set too high", "Chunk overlap starving boundary recall"],
+    "Knowledge Graph": ["A namespace or prefix mismatch", "Links written under an unexpected predicate"],
+    "Object Storage": ["An object expired or was moved", "Wrong content-type set on upload"],
+    "Cross-Stage Consistency": ["A store lagged during ingestion", "A partial re-ingest left stores out of sync"],
+    "Ingestion API": ["A transient upload error went unretried", "The ingestion response schema changed"],
+    "Other": [],
+}
+
+
+def _platform_health(cat_rows: list[dict]) -> dict | None:
+    """A compact KB-health rollup: one dimension PER CATEGORY actually present in this run.
+
+    Dynamic by design - the dimensions are whatever the pipeline's steps produced (via
+    ``cat_rows``), not a hardcoded list. A project with no graph step simply has no graph
+    dimension. Each dimension scores the pass rate of its evaluable checks (hard + advisory),
+    so it reads as overall subsystem health, and the composite is check-weighted across them.
+    Worst-first, so the weakest subsystem is the signal that leads. None when nothing ran.
+    """
+    dims, tp, tt = [], 0, 0
+    for r in cat_rows:
+        if not r.get("total"):
+            continue
+        dims.append({"name": r["name"], "score": round(100 * r["passed"] / r["total"]),
+                     "passed": r["passed"], "total": r["total"]})
+        tp += r["passed"]
+        tt += r["total"]
+    if not dims:
+        return None
+    dims.sort(key=lambda d: (d["score"], d["name"]))
+    return {"score": round(100 * tp / tt), "dimensions": dims}
+
+
+def _health_band(score: int) -> str:
+    return "ok" if score >= 90 else "warn" if score >= 70 else "bad"
+
+
+def _health_strip(h: dict | None) -> str:
+    """A subtle five-second read of subsystem health: a composite plus a mini-bar per
+    dimension. Deliberately compact - a signal, not another table."""
+    if not h:
+        return ""
+    bars = ""
+    for d in h["dimensions"]:
+        cls = _health_band(d["score"])
+        bars += (
+            f'<div class="phz-dim" data-tip="{d["passed"]}/{d["total"]} checks passed">'
+            f'<div class="phz-top"><span class="phz-name">{_esc(d["name"])}</span>'
+            f'<span class="phz-score {cls}">{d["score"]}</span></div>'
+            f'<div class="phz-bar"><i class="{cls}" style="width:{d["score"]}%"></i></div></div>'
+        )
+    ocls = _health_band(h["score"])
+    return (
+        '<div class="phz" data-tip="Check pass-rate grouped by KB subsystem present in this run. '
+        'Deterministic; overall integrity/quality still live in the verdict and hygiene above.">'
+        '<div class="phz-head"><span class="phz-cap">Platform Health</span>'
+        f'<span class="phz-overall {ocls}">{h["score"]}</span><span class="phz-max">/100</span></div>'
+        f'<div class="phz-grid">{bars}</div></div>'
+    )
+
+
+# A per-category "win" phrased as an outcome, shown only when that category is 100% clean.
+_WIN_LABEL = {
+    "Object Storage": "No storage failures",
+    "Knowledge Graph": "No graph inconsistencies",
+    "Cross-Stage Consistency": "Stores agree on every document",
+    "Ingestion API": "Every document ingested cleanly",
+    "Embedding Quality": "Embeddings clean across the corpus",
+    "Chunk Structure": "Chunk structure clean across the corpus",
+    "Content Preservation": "Source content fully preserved",
+    "Metadata & Consistency": "Metadata complete and consistent",
+    "Index & Schema": "Index schema matches expectations",
+    "Retrieval & Query": "Retrieval clean across the corpus",
+}
+
+
+def _engineering_wins(agg: dict) -> list[str]:
+    """What is demonstrably HEALTHY - so a good KB is not represented only by its problems.
+
+    Deterministic and honest: every item is a check-backed fact (a category that passed
+    100%, zero errors, a full-pass gate), never a platitude. Empty list -> no section.
+    """
+    wins: list[str] = []
+    total = agg.get("total", 0)
+    if total and agg.get("failed", 0) == 0 and agg.get("errors", 0) == 0:
+        wins.append(f"All {total} document(s) validated - no integrity failures")
+    elif agg.get("errors", 0) == 0 and agg.get("checks_total", 0):
+        wins.append("No runtime errors")
+    for row in agg.get("cat_rows", []):
+        if row.get("total") and row["passed"] == row["total"]:
+            lbl = _WIN_LABEL.get(row["name"])
+            if lbl and lbl not in wins:
+                wins.append(lbl)
+    return wins[:6]
+
+
+def _wins_block(agg: dict) -> str:
+    wins = _engineering_wins(agg)
+    if not wins:
+        return ""
+    items = "".join(f'<span class="win-item"><span class="win-tick">&#10003;</span>{_esc(w)}</span>'
+                    for w in wins)
+    return ('<div class="wins-block" data-tip="Check-backed strengths in this run - '
+            'the healthy counterpart to the Action Plan.">'
+            '<div class="wins-cap">Engineering Wins</div>'
+            f'<div class="wins-grid">{items}</div></div>')
+
 
 def _impact_cls(pct: int) -> str:
     return "bad" if pct >= 50 else "warn" if pct >= 20 else "ok"
@@ -901,9 +1100,22 @@ def _action_plan_section(agg: dict) -> str:
     # cards below; a pointer here makes the remainder explicit rather than silently dropped.
     cards = ""
     for i, g in enumerate(ranked[:_ACTION_CAP], 1):
+        ranked_checks = sorted(g["checks"], key=lambda o: -o["docs"])
         evidence = ", ".join(f'{_esc(o["label"])} {round(100 * o["docs"] / g["total"])}%'
-                             for o in sorted(g["checks"], key=lambda o: -o["docs"])[:3])
-        fix = g["fix"] or _ROOT_CAUSE.get(g["cat"], "")
+                             for o in ranked_checks[:3])
+        # A concrete measured example from the worst check (e.g. "4200 (~3000 expected)"),
+        # so Observed carries a specific number - the "why" - not just which check failed.
+        example = next((o.get("detail") for o in ranked_checks if o.get("detail")), "")
+        if example:
+            evidence += f' <span class="check-detail">e.g. {_esc(example)}</span>'
+        # A concise, category-specific INSTRUCTION here - the diagnosis now lives in the
+        # Observed/Likely/Possible tiers, so the fix line is just "what to do" and never
+        # repeats a cause. The verbose per-check hint stays in the detailed cards below.
+        fix = _FIX_GUIDANCE.get(g["cat"]) or g["fix"] or _ROOT_CAUSE.get(g["cat"], "")
+        possible = _POSSIBLE_CAUSES.get(g["cat"], [])
+        possible_html = (
+            '<div class="rca-line"><span class="conf-tag possible">Possible</span>'
+            f'<span>{_esc("; ".join(possible))}</span></div>' if possible else "")
         cards += (
             # Border color driven by PRIORITY (inline overrides the shared :has(.tag.*) rule,
             # which would otherwise pick a colour from the impact/effort chips too).
@@ -914,8 +1126,13 @@ def _action_plan_section(agg: dict) -> str:
             f'<span class="tag {_impact_cls(g["impact"])}" title="documents affected">impact {g["impact"]}%</span>'
             f'<span class="tag {g["effort_cls"]}" title="estimated engineering effort">est. effort {g["effort"]}</span>'
             '</div>'
-            f'<div class="rca-cause"><b>Likely cause:</b> {_esc(_ROOT_CAUSE.get(g["cat"], ""))} '
-            f'<span class="check-detail">Evidence: {evidence}</span></div>'
+            # Separate what we MEASURED (Observed) from the primary guess (Likely) and the
+            # alternates we can't rule out (Possible), so a hypothesis never reads as a fact.
+            '<div class="rca-cause">'
+            f'<div class="rca-line"><span class="conf-tag observed">Observed</span><span>{evidence}</span></div>'
+            f'<div class="rca-line"><span class="conf-tag likely">Likely</span><span>{_esc(_ROOT_CAUSE.get(g["cat"], ""))}</span></div>'
+            f'{possible_html}'
+            '</div>'
             + (f'<div class="rec-fix">Fix: {_esc(fix)}</div>' if fix else "")
             + '</div>'
         )
@@ -953,7 +1170,8 @@ def _issues_by_subsystem(agg: dict) -> str:
             f'{o["docs"]}/{g["total"]} docs ({round(100 * o["docs"] / g["total"])}%)</span></li>'
             for o in sorted(g["checks"], key=lambda o: -o["docs"])
         )
-        fix_html = f'<div class="rec-fix">Fix: {_esc(g["fix"])}</div>' if g["fix"] else ""
+        fix_txt = g["fix"] or _FIX_GUIDANCE.get(g["cat"])
+        fix_html = f'<div class="rec-fix">Fix: {_esc(fix_txt)}</div>' if fix_txt else ""
         cards += (
             f'<details class="cov-row"{" open" if g["severity"] == "hard" else ""}>'
             '<summary class="cov-sum">'
@@ -1422,35 +1640,113 @@ def _trends_section(trends: list[dict]) -> str:
 </div>"""
 
 
-def _glossary_section(present_steps: list[str] | None = None) -> str:
-    # Each entry carries the step name(s) it documents so the glossary can show only the
-    # steps that actually appear in THIS run (not the whole catalogue). present_steps=None
-    # (e.g. legacy/trends-only) falls back to listing all of them.
-    steps = [
+def _glossary_section(agg: dict | None = None, corpus: dict | None = None, mode: str = "") -> str:
+    """A run-driven glossary: it explains only the vocabulary THIS run actually used.
+
+    Sections are included conditionally - a step that did not run, a category with no checks,
+    a Platform Health rollup that could not be computed, the Action Plan tiers when there is
+    no Action Plan, a Readiness Verdict without a corpus, or the mode that was not used, are
+    all omitted. So the glossary tracks the report above it instead of listing the full
+    catalogue. ``agg=None`` (e.g. a trends-only render) falls back to the complete set.
+    """
+    present_steps = agg.get("present_steps") if agg else None
+    present_cats = {row["name"] for row in agg.get("cat_rows", [])} if agg else None
+
+    sections: list[str] = []
+
+    def section(title: str, body: str) -> None:
+        sections.append(f'<div class="glossary-section"><h4>{_esc(title)}</h4>{body}</div>')
+
+    def dl(pairs) -> str:
+        return "<dl>" + "".join(f"<dt>{_esc(n)}</dt><dd>{_esc(d)}</dd>" for n, d in pairs) + "</dl>"
+
+    # Counting levels are the base vocabulary for every run - always shown.
+    section("Counting Levels", dl([
+        ("Document", "One knowledge-base item (a file / object). Reports may also call it a 'case'. A run validates one or more documents."),
+        ("Pipeline step", "One stage of the pipeline applied to a document (e.g. S3 Storage, Redis Chunks). Each document runs several steps."),
+        ("Check", "One individual assertion inside a step (e.g. 'embedding dimension matches'). A step bundles many checks."),
+    ]))
+
+    # Pipeline steps: only those that appear in THIS run.
+    step_defs = [
         ("API Upload", "Uploads the document through the ingestion API (GraphQL multipart) and confirms a document id is returned.", ("API Upload",)),
         ("S3 Storage", "Confirms the object landed in storage with the expected content type, size, recency and ETag/MD5 integrity.", ("S3 Storage",)),
         ("GraphDB / Neptune Metadata", "Validates document metadata in the knowledge graph: required predicates, identity uniqueness, cross-store agreement with object storage (eTag + storage key), RDF typing, namespace consistency, dangling links, orphan nodes, formats and declarative structure checks.", ("GraphDB Metadata", "Neptune Metadata")),
-        ("Redis Chunks", "28 toggleable checks over the vector store: chunk existence, ids, embeddings, dimensions, ordering, duplicates and metadata.", ("Redis Chunks",)),
+        ("Redis Chunks", "Toggleable checks over the vector store: chunk existence, ids, embeddings, dimensions, ordering, duplicates and metadata.", ("Redis Chunks",)),
         ("Retrieval Quality", "Informational diagnostics: recall@K, MRR, exact-term and paraphrase robustness. Never blocks the pipeline.", ("Retrieval Quality",)),
         ("Cross-Stage Consistency", "Do object storage, the graph and the vector index agree about each document: presence, eTag, shared metadata, chunk-count sanity, ACL propagation.", ("Cross-Stage Consistency",)),
     ]
     if present_steps is not None:
-        present = set(present_steps)
-        steps = [t for t in steps if any(name in present for name in t[2])]
-    defs = "".join(f"<dt>{_esc(n)}</dt><dd>{_esc(d)}</dd>" for n, d, _ in steps)
-    cats = "".join(f"<dt>{_esc(n)}</dt><dd>{_esc(d)}</dd>" for n, d in _CAT_ORDER)
-    # The three counting levels - the source of most "what does this number mean?" confusion.
-    levels = [
-        ("Document", "One knowledge-base item (a file / object). Reports may also call it a 'case'. A run validates one or more documents."),
-        ("Pipeline step", "One stage of the pipeline applied to a document (e.g. S3 Storage, Redis Chunks). Each document runs several steps."),
-        ("Check", "One individual assertion inside a step (e.g. 'embedding dimension matches'). A step bundles many checks."),
-    ]
-    levels_html = "".join(f"<dt>{_esc(n)}</dt><dd>{_esc(d)}</dd>" for n, d in levels)
-    modes = [
-        ("Live Ingestion", "Push documents through the ingestion API and validate each stage as it lands (run_validation)."),
-        ("Discovery", "Validate a knowledge base that is already populated, without re-ingesting (discover_and_validate)."),
-    ]
-    modes_html = "".join(f"<dt>{_esc(n)}</dt><dd>{_esc(d)}</dd>" for n, d in modes)
+        pset = set(present_steps)
+        step_defs = [t for t in step_defs if any(n in pset for n in t[2])]
+    if step_defs:
+        section("Pipeline Steps", dl([(n, d) for n, d, _ in step_defs]))
+
+    # Check categories: only those actually exercised this run.
+    cat_pairs = [(n, d) for n, d in _CAT_ORDER if present_cats is None or n in present_cats]
+    if cat_pairs:
+        section("Check Categories", dl(cat_pairs))
+
+    # Platform Health: only when there were evaluable checks to roll up.
+    if agg is not None and _platform_health(agg.get("cat_rows", [])) is not None:
+        section("Platform Health",
+                '<div class="score-scale"><span class="s-ok">90-100 healthy</span>'
+                '<span class="s-warn">70-89 attention</span><span class="s-bad">below 70 weak</span></div>'
+                + dl([
+                    ("Platform Health (0-100)", "The share of evaluable checks (hard + advisory) that passed, grouped by the subsystems present in this run and check-weighted into one composite. It is data-plane health, deterministic - not answer quality, which needs an LLM judge and lives in the eval layer."),
+                    ("Dimension score", "The same pass rate for a single subsystem - e.g. 'Retrieval & Query 52' means 52% of its checks passed. Dimensions are dynamic (only subsystems that actually ran appear) and are shown worst-first so the weakest leads."),
+                ]).replace("<dl>", '<dl style="margin-top:10px">')
+                + '<dd style="margin-top:8px">A high overall can still hide one weak dimension - read the per-subsystem bars, not only the composite.</dd>')
+
+    # Signal Confidence: only when the run produced an Action Plan (i.e. there are findings).
+    if agg is not None and _subsystem_groups(agg):
+        section("Signal Confidence (Action Plan)",
+                dl([
+                    ("Observed", "What the run measured directly: the failing checks and how many documents they affect. Fact, not inference."),
+                    ("Likely", "The single best hypothesis for that observed pattern. A strong guess, not a proven cause."),
+                    ("Possible", "Other explanations the evidence cannot rule out - worth checking if the Likely cause does not hold."),
+                ])
+                + '<dd style="margin-top:8px">Each Action Plan card separates these three tiers, so a hypothesis is never presented as a measured fact.</dd>')
+
+    # Run mode: only the one that ran (both if unknown, e.g. a legacy render).
+    mode_defs = {
+        "Live Ingestion": "Push documents through the ingestion API and validate each stage as it lands (run_validation).",
+        "Discovery": "Validate a knowledge base that is already populated, without re-ingesting (discover_and_validate).",
+    }
+    active_modes = [(mode, mode_defs[mode])] if mode in mode_defs else list(mode_defs.items())
+    section("Run Mode" if mode in mode_defs else "Run Modes", dl(active_modes))
+
+    # Status scale is fundamental to reading any status pill - always shown.
+    section("Status Scale",
+            '<div class="score-scale"><span class="s-ok">PASSED</span><span class="s-warn">PARTIAL</span>'
+            '<span class="s-bad">FAILED / ERROR</span><span class="s-na">SKIPPED</span></div>'
+            '<dl style="margin-top:10px">'
+            '<dt>PASSED</dt><dd>Every evaluable check passed.</dd>'
+            '<dt>PARTIAL</dt><dd>Some steps passed and some failed within a document.</dd>'
+            '<dt>FAILED / ERROR</dt><dd>A check failed (FAILED) or the step raised unexpectedly (ERROR).</dd>'
+            '<dt>SKIPPED</dt><dd>Step not part of this project\'s pipeline / configured out, or BLOCKED because an upstream step it depends on did not produce the artifact it needs (e.g. the object never reached storage, so it cannot be chunked). Blocked steps are still listed with the upstream culprit - they are neutral, never counted as a failure. Independent branches (e.g. graph vs vector) are unaffected by each other.</dd>'
+            '<dt>UNSUPPORTED</dt><dd>A check the backend cannot answer (e.g. a vector store that does not expose raw vectors). Counted as neutral - excluded from pass/fail totals, never a failure.</dd>'
+            '</dl>'
+            '<dd style="margin-top:8px">A document is PASSED only when every non-skipped step passes. Critical-step failures halt remaining steps.</dd>')
+
+    # Suppressed: only when this run actually accepted advisory issues.
+    if agg is not None and agg.get("checks_suppressed"):
+        section("Suppressed (accepted)", dl([
+            ("Suppressed", "An advisory check the project accepted as expected for this corpus "
+             "(config `suppressions` / `--suppress`) - e.g. near-duplicate boilerplate in policy "
+             "documents. Excluded from the hygiene and Platform Health scores but still counted "
+             "and shown as 'N suppressed'. Only advisory checks can be suppressed; a hard gating "
+             "failure is never suppressed, so an accepted known-issue can never mask a real one."),
+        ]))
+
+    # Readiness Verdict: only when a corpus supplied one.
+    if corpus is not None:
+        section("Readiness Verdict",
+                '<div class="score-scale"><span class="s-ok">READY</span><span class="s-warn">AT RISK</span>'
+                '<span class="s-bad">NOT READY</span></div>'
+                '<dd style="margin-top:10px">Corpus-level verdict over the whole document set: completeness '
+                '(expected vs actual), duplicates, and coverage - distinct from any single document\'s pass/fail.</dd>')
+
     return f"""
 <div id="section-definitions">
 <section class="section">
@@ -1460,29 +1756,7 @@ def _glossary_section(present_steps: list[str] | None = None) -> str:
       <svg class="glossary-chevron" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polyline points="6 9 12 15 18 9"/></svg>
     </div>
     <div class="glossary-body" id="glossaryBody">
-      <div class="glossary-grid">
-        <div class="glossary-section"><h4>Counting Levels</h4><dl>{levels_html}</dl></div>
-        <div class="glossary-section"><h4>Pipeline Steps</h4><dl>{defs}</dl></div>
-        <div class="glossary-section"><h4>Check Categories</h4><dl>{cats}</dl></div>
-        <div class="glossary-section"><h4>Run Modes</h4><dl>{modes_html}</dl></div>
-        <div class="glossary-section">
-          <h4>Status Scale</h4>
-          <div class="score-scale"><span class="s-ok">PASSED</span><span class="s-warn">PARTIAL</span><span class="s-bad">FAILED / ERROR</span><span class="s-na">SKIPPED</span></div>
-          <dl style="margin-top:10px">
-            <dt>PASSED</dt><dd>Every evaluable check passed.</dd>
-            <dt>PARTIAL</dt><dd>Some steps passed and some failed within a document.</dd>
-            <dt>FAILED / ERROR</dt><dd>A check failed (FAILED) or the step raised unexpectedly (ERROR).</dd>
-            <dt>SKIPPED</dt><dd>Step not part of this project's pipeline / configured out, or BLOCKED because an upstream step it depends on did not produce the artifact it needs (e.g. the object never reached storage, so it cannot be chunked). Blocked steps are still listed with the upstream culprit - they are neutral, never counted as a failure. Independent branches (e.g. graph vs vector) are unaffected by each other.</dd>
-            <dt>UNSUPPORTED</dt><dd>A check the backend cannot answer (e.g. a vector store that does not expose raw vectors). Counted as neutral - excluded from pass/fail totals, never a failure.</dd>
-          </dl>
-          <dd style="margin-top:8px">A document is PASSED only when every non-skipped step passes. Critical-step failures halt remaining steps.</dd>
-        </div>
-        <div class="glossary-section">
-          <h4>Readiness Verdict</h4>
-          <div class="score-scale"><span class="s-ok">READY</span><span class="s-warn">AT RISK</span><span class="s-bad">NOT READY</span></div>
-          <dd style="margin-top:10px">Corpus-level verdict over the whole document set: completeness (expected vs actual), duplicates, and coverage - distinct from any single document's pass/fail.</dd>
-        </div>
-      </div>
+      <div class="glossary-grid">{"".join(sections)}</div>
     </div>
   </div>
 </section>
@@ -1561,8 +1835,8 @@ function _insights(d){
 var _STEP_CATEGORY={"Neptune Metadata":"Knowledge Graph","GraphDB Metadata":"Knowledge Graph","S3 Storage":"Object Storage","Cross-Stage Consistency":"Cross-Stage Consistency","API Upload":"Ingestion API"};
 function _categorise(label, step){
   var l=(label||'').toLowerCase();
-  if(/e_tag|required field|metadata consist|positional|section|page metadata|directory|predicate|date format|email|field rule/.test(l)) return 'Metadata & Consistency';
-  if(/boundaries|chunk count|size within|ordering|overlap/.test(l)) return 'Chunk Structure';
+  if(/e_tag|required field|metadata consist|page metadata|directory|predicate|date format|email|field rule/.test(l)) return 'Metadata & Consistency';
+  if(/boundaries|chunk count|chunk structure|all chunks|coheren|positional|section split|size within|ordering|overlap/.test(l)) return 'Chunk Structure';
   if(/embedding|normaliz|near-duplicate|dimension|distance metric/.test(l)) return 'Embedding Quality';
   if(/fidelity|coverage|contaminat|duplicate|header|footer|table\/figure/.test(l)) return 'Content Preservation';
   if(/index|schema/.test(l)) return 'Index & Schema';
@@ -1835,6 +2109,7 @@ def generate_batch_dashboard(
     wall_seconds: float | None = None,
     concurrency: int | None = None,
     evidence: dict | None = None,
+    suppress: list[str] | None = None,
 ) -> str:
     """Generate a self-contained, interactive HTML dashboard. Returns abs path.
 
@@ -1854,7 +2129,8 @@ def generate_batch_dashboard(
     _ICON = {s.name: s.icon for s in registered_steps()}
 
     cases = [_result_payload(item.get("name", item["result"].file_name), item["result"]) for item in results]
-    agg = _aggregate(cases, hide_skipped=hide_skipped)  # computed on FULL data, before any trim
+    # computed on FULL data, before any trim; suppressions accepted from config
+    agg = _aggregate(cases, hide_skipped=hide_skipped, suppress=set(suppress or []))
     # Wall clock vs compute time: agg["duration"] is the SUM of per-document durations, so
     # under --parallel it far exceeds the elapsed time (a 502-doc run summed 1319s but
     # finished in 329s). Carry the real wall clock and concurrency so the summary can show
@@ -1984,7 +2260,7 @@ def generate_batch_dashboard(
   {_document_section(cases)}
   {_details_section(cases, agg['present_steps'])}
   {trends_html}
-  {_glossary_section(agg.get('present_steps'))}
+  {_glossary_section(agg, corpus, mode)}
 </main>
 {_MODAL}
 <div id="compass-tip"></div>