From 1bcad0fb0e2ff3e52fe5c9428046acc68e90cfa2 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 28 Mar 2026 07:31:10 +0000
Subject: [PATCH 1/2] Initial plan


From 86fc12e1e2cb4cf12ff3cf9f274770be51228cd5 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 28 Mar 2026 07:39:29 +0000
Subject: [PATCH 2/2] docs: qualify AGENTS.md claims with test-backed
 validation status

Agent-Logs-Url: https://github.com/SkBlaz/py3plex/sessions/5b6f5c25-e053-4828-9e3b-a2e988f02ec7

Co-authored-by: SkBlaz <10035780+SkBlaz@users.noreply.github.com>
---
 AGENTS.md                                 | 16 +++++++--
 tests/test_agents_documentation_claims.py | 42 +++++++++++++++++++++++
 2 files changed, 56 insertions(+), 2 deletions(-)
 create mode 100644 tests/test_agents_documentation_claims.py

diff --git a/AGENTS.md b/AGENTS.md
index 7f39f2de..a94c8bc0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,7 +12,7 @@
 
 ** New to py3plex?** 
 - **5 minutes**: See [dsl_patterns_quick_reference.py](examples/getting_started/dsl_patterns_quick_reference.py) for 7 copy-paste patterns
-- **15 minutes**: Jump to [Quick Start: Golden Paths](#quick-start-golden-paths) for 5 essential patterns that cover 80% of use cases
+- **15 minutes**: Jump to [Quick Start: Golden Paths](#quick-start-golden-paths) for 5 high-value patterns that cover common workflows
 - **Deep dive**: Continue reading this comprehensive guide
 
 ---
@@ -98,6 +98,10 @@ q = q.compute("degree").hint()  # Get new suggestions
 - Learning new DSL features
 - Debugging query construction issues
 
+**Validation status**:
+- Execution and chaining behavior are covered by `tests/test_agents_ergonomics_features.py`
+- Exact hint text and formatting may evolve between versions; rely on API behavior, not exact output text
+
 ### Enhanced QueryResult Introspection
 
 **What it does**: QueryResult objects now have rich `__repr__` showing full context.
@@ -247,6 +251,10 @@ with suppress_warnings("degree_ambiguity", "node_replica_confusion"):
 - **React to warnings**: Warnings are actionable — apply suggested alternatives when applicable
 - **Don't ignore**: Warnings indicate potential correctness or performance issues
 
+**Validation status**:
+- Warning suppression behavior (`suppress_warnings`) is tested in `tests/test_agents_ergonomics_features.py`
+- Warning triggering thresholds and exact warning text are implementation details and may vary across releases
+
 ### Multilayer Semantics Mental Model
 
 **Core concepts LLM agents must understand**:
@@ -336,12 +344,16 @@ result = (
 result.export_bundle("analysis.bundle.json.gz", compress=True)
 ```
 
-**LLM agent guidance**: When user asks "how do I...", search these recipes first. They represent tested, best-practice patterns.
+**LLM agent guidance**: When user asks "how do I...", search these recipes first and then validate in the current environment.
 
 ---
 
 ## Quick Start: Golden Paths
 
+**Validation status**:
+- Path 1 and Path 2 are exercised in `tests/test_agents_golden_paths.py`
+- Path 3, Path 4, and Path 5 are advanced workflows and may require optional modules or setup in the current environment
+
 ### Path 1: Network Analysis from CSV
 
 ```python
diff --git a/tests/test_agents_documentation_claims.py b/tests/test_agents_documentation_claims.py
new file mode 100644
index 00000000..66c2e3a3
--- /dev/null
+++ b/tests/test_agents_documentation_claims.py
@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Guardrails for AGENTS.md claim language.
+
+These tests ensure AGENTS.md keeps conservative wording around validation
+coverage and warning behavior so documentation does not over-claim support.
+"""
+
+from pathlib import Path
+
+
+def _read_agents_md() -> str:
+    repo_root = Path(__file__).parent.parent
+    return (repo_root / "AGENTS.md").read_text(encoding="utf-8")
+
+
+def test_quickstart_validation_status_is_explicit():
+    """Golden Paths section should clearly state tested vs advanced paths."""
+    text = _read_agents_md()
+
+    assert "**Validation status**:" in text
+    assert "Path 1 and Path 2 are exercised in `tests/test_agents_golden_paths.py`" in text
+    assert (
+        "Path 3, Path 4, and Path 5 are advanced workflows and may require optional modules or setup in the current environment"
+        in text
+    )
+
+
+def test_warning_behavior_claims_are_conservative():
+    """Ergonomics warning docs should avoid implying stable warning text contracts."""
+    text = _read_agents_md()
+
+    assert (
+        "Warning suppression behavior (`suppress_warnings`) is tested in `tests/test_agents_ergonomics_features.py`"
+        in text
+    )
+    assert (
+        "Warning triggering thresholds and exact warning text are implementation details and may vary across releases"
+        in text
+    )
+