fix(docs): update docs

tom-sapletta-com · coru-agent · tom-sapletta-com · commit 71113745ede9 · 2026-07-20T00:14:05.000+02:00
Statistics: 12 files changed, 116 insertions, 67 deletions

Summary:
- Dirs: .=6, tests=3, src=2, docs=1
- Exts: .py=5, .md=3, .less=1, .yaml=1, .toml=1, .lock=1
- A/M/D: 0/12/0
- Symbols: class FakeRequest, test_testql_mcp_tools, _private_dependency_imports, test_testql_autorepair_uses_public_runner_release_floor, test_koru_src_has_no_private_env2llm_imports

Modified files:
- CHANGELOG.md (+4/-0)
- README.md (+4/-4)
- TODO.md (+11/-0)
- app.doql.less (+4/-4)
- docs/architecture/dependency-boundary-inventory.yaml (+3/-2)
- pyproject.toml (+4/-4)
- src/koru/deps_autorepair.py (+2/-2)
- src/koruapi/testql_bridge.py (+14/-40)
- tests/test_deps_autorepair.py (+7/-0)
- tests/test_package_deduplication.py (+15/-4)
- tests/test_testql_bridge.py (+41/-0)
- uv.lock (+7/-7)

Implementation notes (heuristics):
- Type inferred from file paths + diff keywords + add/delete ratio
- Scope prefers 'goal' when goal/* is touched; otherwise based on top-level dirs
- For &lt;=6 files: generate short per-file notes from added lines (defs/classes/click options/headings)
- A/M/D derived from git name-status; per-file +X/-X from git numstat

Co-authored-by: Koru Agent &lt;agent@coru.dev&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- The TestQL bridge now delegates scenario resolution and batch execution to
+  the public `testql.verification` contract from TestQL 1.2.62. Successful
+  responses include the versioned result schema plus canonical request/result
+  hashes, and Koru no longer imports private TestQL runner symbols.
 - The env2llm registry bridge now consumes the public, typed service factory
   from env2llm 0.1.14 and includes its canonical service descriptor plus
   request/descriptor hashes in every successful response. Service construction
@@ -30,6 +34,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Queue patch tickets may set `inputs.max_patch_attempts` (overrides
   `KORU_QUEUE_PATCH_RETRIES` for mechanical diff retries).
 
+## [0.1.435] - 2026-07-20
+
+### Docs
+- Update CHANGELOG.md
+- Update README.md
+- Update TODO.md
+- Update docs/architecture/dependency-boundary-inventory.yaml
+
+### Test
+- Update tests/test_deps_autorepair.py
+- Update tests/test_package_deduplication.py
+- Update tests/test_testql_bridge.py
+
+### Other
+- Update app.doql.less
+- Update uv.lock
+
 ## [0.1.434] - 2026-07-19
 
 ### Docs
diff --git a/README.md b/README.md
@@ -7,13 +7,13 @@
 
 ## AI Cost Tracking
 
-![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.1.434-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
-![AI Cost](https://img.shields.io/badge/AI%20Cost-$6.23-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-259.7h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fdeep%2Fdeep--v4--pro-lightgrey)
+![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.1.435-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![AI Cost](https://img.shields.io/badge/AI%20Cost-$5.64-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-260.3h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fdeep%2Fdeep--v4--pro-lightgrey)
 
-- 🤖 **LLM usage:** $6.2320 (723 commits)
-- 👤 **Human dev:** ~$25966 (259.7h @ $100/h, 30min dedup)
+- 🤖 **LLM usage:** $5.6374 (724 commits)
+- 👤 **Human dev:** ~$26029 (260.3h @ $100/h, 30min dedup)
 
-Generated on 2026-07-19 using [openrouter/deep/deep-v4-pro](https://openrouter.ai/deep/deep-v4-pro)
+Generated on 2026-07-20 using [openrouter/deep/deep-v4-pro](https://openrouter.ai/deep/deep-v4-pro)
 
 ---
 
diff --git a/TODO.md b/TODO.md
@@ -330,6 +330,12 @@ cudzych namespace'ów w produkcyjnym `src/`. Kolejność jest następująca:
         rejestrowanymi przez hosta. Koru wymaga tej wersji, dołącza typed result
         do odpowiedzi IDE i usunęło behavioral fallbacki drivera/recovery:
         kolejne 445 linii produkcyjnych netto, łącznie 2087 linii i 10 modułów.
+  - [x] TestQL 1.2.62 przejął rozwiązywanie ścieżek/globów, batch execution i
+        serializację wyniku przez `testql.verification-request.v1` oraz
+        `testql.verification-result.v1`. Most Koru nie importuje już prywatnych
+        symboli ani nie przepakowuje wyniku; zmalał o 26 linii netto. Po
+        uwzględnieniu jawnej provenance z env2llm łączna redukcja wynosi 2110
+        linii i 10 modułów produkcyjnych.
   - [ ] Alias `VisionFrame` pozostawić do osobnej decyzji kompatybilnościowej.
         Transporty OBS/browser przenosić tylko po pojawieniu się drugiego
         konsumenta lub neutralnego transportu.
@@ -444,6 +450,11 @@ execution DSL-em i sam nie nadaje żadnych uprawnień.
         odpowiedź niesie kanoniczny request/descriptor hash do audytu.
         Minimalna wersja runtime i DSL zależności to 0.1.14; guard AST blokuje
         powrót prywatnych importów env2llm.
+  - [x] **TestQL slice:** TestQL 1.2.62 udostępnia publiczny, wersjonowany
+        `VerificationRequest`/`VerificationResult`, pakowane JSON Schema oraz
+        kanoniczne `request_hash` i `result_hash`. Koru deleguje resolution i
+        batch execution jednym wywołaniem, zachowując wybór acceptance
+        criteria; guard AST blokuje powrót prywatnych importów TestQL.
 - [ ] **DEP-5 — cienki most tillm (kolejność 90, P2).** Po podbiciu minimalnej
       wersji usunąć lokalny provider registry i path injection; konsumować
       typowany completion/provenance. `ProposalEnvelope`, retry budget,
diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-0.1.434
+0.1.435
diff --git a/app.doql.less b/app.doql.less
@@ -11,13 +11,13 @@ dependencies {
   vision: "mss>=9.0,<11.0";
   mesh: "websockets>=12.0,<17.0";
   observe: "mss>=9.0,<11.0, websockets>=12.0,<17.0";
-  desktop: "nlp2uri[envmap]>=0.4.7, env2llm[mqtt]>=0.1.14, planfile>=0.1.100, testql>=1.2.55";
+  desktop: "nlp2uri[envmap]>=0.4.7, env2llm[mqtt]>=0.1.14, planfile>=0.1.100, testql>=1.2.62";
   imgl: "httpx>=0.27,<1.0";
   envmap: "nlp2uri[envmap]>=0.4.7, env2llm[mqtt]>=0.1.14";
-  testql: testql>=1.2.55;
+  testql: testql>=1.2.62;
   planfile: planfile>=0.1.100;
   curllm: curllm[mcp]>=1.0.0;
-  browser: "nlp2uri[envmap]>=0.4.7, env2llm[mqtt]>=0.1.14, testql>=1.2.55, curllm[mcp]>=1.0.0, playwright>=1.40,<2.0";
+  browser: "nlp2uri[envmap]>=0.4.7, env2llm[mqtt]>=0.1.14, testql>=1.2.62, curllm[mcp]>=1.0.0, playwright>=1.40,<2.0";
   vdisplay: vdisplay>=0.1.44;
   dev: "gillm>=0.1.24, pytest>=8.0,<10.0, pytest-cov>=5.0,<8.0, pytest-rerunfailures>=14.0,<17.0, pytest-timeout>=2.3,<3.0, pytest-xdist>=3.0,<4.0, ruff>=0.11,<0.16, mypy>=1.11,<3.0, pyright>=1.1.390,<2.0, hypothesis>=6.112,<7.0, pre-commit>=3.8,<5.0, types-PyYAML>=6.0,<7.0, goal>=2.1.264, costs>=0.1.53, pfix>=0.1.60, tagi>=0.49.0";
   api: "fastapi>=0.115,<1.0, uvicorn[standard]>=0.30,<1.0, httpx>=0.27,<1.0, prometheus-client>=0.21,<1.0";
@@ -27,7 +27,7 @@ dependencies {
   obs: "nfo>=0.2.22,<1.0, opentelemetry-exporter-otlp>=1.28,<2.0, opentelemetry-instrumentation-fastapi>=0.49b0,<1.0, opentelemetry-instrumentation-httpx>=0.49b0,<1.0, opentelemetry-sdk>=1.28,<2.0, sentry-sdk>=2.18,<3.0, structlog>=24.4,<26.0";
   queue: "apscheduler>=3.10,<4.0, arq>=0.26,<1.0, redis>=5.1,<8.0";
   quality: "import-linter>=2.0,<3.0, mutmut>=3.2,<4.0, pyupgrade>=3.17,<4.0, refurb>=2.0,<3.0";
-  all: "apscheduler>=3.10,<4.0, arq>=0.26,<1.0, fastapi>=0.115,<1.0, gillm>=0.1.24, hypothesis>=6.112,<7.0, httpx>=0.27,<1.0, import-linter>=2.0,<3.0, instructor>=1.6,<2.0, litellm>=1.51,<2.0, mss>=9.0,<11.0, mutmut>=3.2,<4.0, mypy>=1.11,<3.0, mss>=9.0,<11.0, nfo>=0.2.22,<1.0, openai>=1.54,<3.0, opentelemetry-exporter-otlp>=1.28,<2.0, opentelemetry-instrumentation-fastapi>=0.49b0,<1.0, opentelemetry-instrumentation-httpx>=0.49b0,<1.0, opentelemetry-sdk>=1.28,<2.0, pre-commit>=3.8,<5.0, prometheus-client>=0.21,<1.0, pyright>=1.1.390,<2.0, pytest>=8.0,<10.0, pytest-cov>=5.0,<8.0, pytest-rerunfailures>=14.0,<17.0, pytest-timeout>=2.3,<3.0, pytest-xdist>=3.0,<4.0, pyupgrade>=3.17,<4.0, redis>=5.1,<8.0, refurb>=2.0,<3.0, ruff>=0.11,<0.16, tillm>=0.1.35, sentry-sdk>=2.18,<3.0, structlog>=24.4,<26.0, tiktoken>=0.8,<1.0, types-PyYAML>=6.0,<7.0, uvicorn[standard]>=0.30,<1.0, websockets>=12.0,<17.0, goal>=2.1.264, costs>=0.1.53, pfix>=0.1.60, tagi>=0.49.0, curllm[mcp]>=1.0.0, env2llm[mqtt]>=0.1.14, fullm>=0.1.22, nlp2uri[envmap]>=0.4.7, planfile>=0.1.100, playwright>=1.40,<2.0, testql>=1.2.55, vdisplay>=0.1.44";
+  all: "apscheduler>=3.10,<4.0, arq>=0.26,<1.0, fastapi>=0.115,<1.0, gillm>=0.1.24, hypothesis>=6.112,<7.0, httpx>=0.27,<1.0, import-linter>=2.0,<3.0, instructor>=1.6,<2.0, litellm>=1.51,<2.0, mss>=9.0,<11.0, mutmut>=3.2,<4.0, mypy>=1.11,<3.0, mss>=9.0,<11.0, nfo>=0.2.22,<1.0, openai>=1.54,<3.0, opentelemetry-exporter-otlp>=1.28,<2.0, opentelemetry-instrumentation-fastapi>=0.49b0,<1.0, opentelemetry-instrumentation-httpx>=0.49b0,<1.0, opentelemetry-sdk>=1.28,<2.0, pre-commit>=3.8,<5.0, prometheus-client>=0.21,<1.0, pyright>=1.1.390,<2.0, pytest>=8.0,<10.0, pytest-cov>=5.0,<8.0, pytest-rerunfailures>=14.0,<17.0, pytest-timeout>=2.3,<3.0, pytest-xdist>=3.0,<4.0, pyupgrade>=3.17,<4.0, redis>=5.1,<8.0, refurb>=2.0,<3.0, ruff>=0.11,<0.16, tillm>=0.1.35, sentry-sdk>=2.18,<3.0, structlog>=24.4,<26.0, tiktoken>=0.8,<1.0, types-PyYAML>=6.0,<7.0, uvicorn[standard]>=0.30,<1.0, websockets>=12.0,<17.0, goal>=2.1.264, costs>=0.1.53, pfix>=0.1.60, tagi>=0.49.0, curllm[mcp]>=1.0.0, env2llm[mqtt]>=0.1.14, fullm>=0.1.22, nlp2uri[envmap]>=0.4.7, planfile>=0.1.100, playwright>=1.40,<2.0, testql>=1.2.62, vdisplay>=0.1.44";
 }
 
 entity[name="TextContent"] {
diff --git a/docs/architecture/dependency-boundary-inventory.yaml b/docs/architecture/dependency-boundary-inventory.yaml
@@ -353,7 +353,7 @@ extractions:
   - id: testql.public_runner
     order: 60
     priority: P0
-    status: proposed
+    status: complete
     kind: move
     source_modules:
       - src/koruapi/testql_bridge.py
@@ -366,9 +366,10 @@ extractions:
     keep_in_koru:
       - Selection of acceptance criteria and the completed versus applied_unverified decision.
     current_smells:
-      - Koru imports private TestQL runner symbols _resolve_input_paths and _run_single.
+      - Resolved in TestQL 1.2.62 and Koru 0.1.435+; TestQL owns path resolution, batch execution and canonical result serialization.
     acceptance:
       - Koru uses only a public TestQL API and records canonical verification result hashes.
+      - Malformed requests fail through the typed public contract before scenario execution.
     blocked_by: []
   - id: tillm.bridge_cleanup
     order: 90
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "koru-autopilot-plugins-workspace",
-  "version": "0.1.434",
+  "version": "0.1.435",
   "private": true,
   "description": "Monorepo root for all koru autopilot IDE plugins. Each IDE has its own VSIX so a regression in one cannot leak into another. Shared code (protocol, socket, host-click-submit) lives in plugins/koru-autopilot-shared and is copied into per-IDE plugins at prebuild time.",
   "workspaces": [
diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "koru"
-version = "0.1.434"
+version = "0.1.435"
 description = "Closed-loop automation across semcod/* repositories."
 readme = "README.md"
 requires-python = ">=3.12,<3.14"
@@ -52,7 +52,7 @@ desktop = [
     "nlp2uri[envmap]>=0.4.7",
     "env2llm[mqtt]>=0.1.14",
     "planfile>=0.1.116",
-    "testql>=1.2.55",
+    "testql>=1.2.62",
 ]
 imgl = [
     "httpx>=0.27,<1.0",
@@ -62,7 +62,7 @@ envmap = [
     "env2llm[mqtt]>=0.1.14",
 ]
 testql = [
-    "testql>=1.2.55",
+    "testql>=1.2.62",
 ]
 # The queue loop shells out to `planfile`; without this extra the resolver
 # can end up with no usable planfile anywhere and every cycle dies with
@@ -76,7 +76,7 @@ curllm = [
 browser = [
     "nlp2uri[envmap]>=0.4.7",
     "env2llm[mqtt]>=0.1.14",
-    "testql>=1.2.55",
+    "testql>=1.2.62",
     "curllm[mcp]>=1.0.0",
     "playwright>=1.40,<2.0",
 ]
@@ -191,7 +191,7 @@ all = [
     "nlp2uri[envmap]>=0.4.7",
     "planfile>=0.1.116",
     "playwright>=1.40,<2.0",
-    "testql>=1.2.55",
+    "testql>=1.2.62",
     "vdisplay>=0.1.58",
 ]
 
diff --git a/src/koru/deps_autorepair.py b/src/koru/deps_autorepair.py
@@ -13,7 +13,7 @@
     "env2llm": "env2llm[mqtt]>=0.1.14",
     "vdisplay": "vdisplay>=0.1.58",
     "nlp2uri": "nlp2uri[envmap]>=0.4.7",
-    "testql": "testql>=1.2.55",
+    "testql": "testql>=1.2.62",
     "gillm": "gillm>=0.1.24",
     "yaml": "pyyaml>=6.0,<7.0",
     "pytesseract": "pytesseract>=0.3.10",
@@ -25,7 +25,7 @@
     "desktop": [
         "nlp2uri[envmap]>=0.4.7",
         "env2llm[mqtt]>=0.1.14",
-        "testql>=1.2.55",
+        "testql>=1.2.62",
     ],
     "vdisplay": ["vdisplay>=0.1.58"],
     "vision": ["Pillow>=10.0", "pytesseract>=0.3.10"],
diff --git a/src/koruapi/testql_bridge.py b/src/koruapi/testql_bridge.py
@@ -2,15 +2,16 @@
 
 from __future__ import annotations
 
+import importlib
 import os
 from pathlib import Path
 from typing import Any
 
 _TESTQL_IMPORT_ERROR: str | None = None
+_TESTQL_API: Any = None
 
 try:
-    import testql  # noqa: F401
-    from testql.commands import run_cmd as _testql_run_cmd  # noqa: F401
+    _TESTQL_API = importlib.import_module("testql.verification")
 
     _TESTQL_AVAILABLE = True
 except ImportError as exc:
@@ -24,20 +25,12 @@ def testql_available() -> bool:
 
 def testql_missing_message() -> str:
     if _TESTQL_IMPORT_ERROR:
-        return (
-            f"testql is not installed ({_TESTQL_IMPORT_ERROR}). "
-            "Install from: pip install -e /path/to/oqlos/testql"
-        )
+        return f"testql is not installed ({_TESTQL_IMPORT_ERROR}). Install with: pip install 'testql>=1.2.62'"
     return "testql is not installed."
 
 
 def _resolve_root(project_dir: str | None = None, project_root: str | None = None) -> Path:
-    raw = (
-        project_dir
-        or project_root
-        or os.environ.get("KORU_PROJECT_ROOT")
-        or "."
-    )
+    raw = project_dir or project_root or os.environ.get("KORU_PROJECT_ROOT") or "."
     return Path(raw).resolve()
 
 
@@ -70,33 +63,14 @@ def testql_run_scenario(
     if not _TESTQL_AVAILABLE:
         return {"ok": False, "error": testql_missing_message()}
     try:
-        from testql.commands.run_cmd import _resolve_input_paths, _run_single
-
-        root = _resolve_root(project_dir, project_root)
-        spec_path = Path(file_spec)
-        resolved_spec = str(spec_path if spec_path.is_absolute() else root / file_spec)
-        paths = _resolve_input_paths(resolved_spec)
-        results = []
-        for path in paths:
-            result = _run_single(path, url, dry_run, quiet, timeout)
-            results.append(
-                {
-                    "file": str(path),
-                    "ok": bool(result.ok),
-                    "passed": result.passed,
-                    "failed": result.failed,
-                    "steps": len(result.steps),
-                    "duration_ms": round(result.duration_ms, 1),
-                    "errors": result.errors,
-                    "warnings": result.warnings,
-                }
-            )
-        failed = sum(1 for item in results if not item["ok"])
-        return {
-            "ok": failed == 0,
-            "files": len(results),
-            "runs": results,
-            "dry_run": dry_run,
-        }
+        request = _TESTQL_API.VerificationRequest(
+            file_specs=(file_spec,),
+            project_dir=_resolve_root(project_dir, project_root),
+            url=url,
+            dry_run=dry_run,
+            quiet=quiet,
+            timeout=timeout,
+        )
+        return _TESTQL_API.run_verification(request).to_dict()
     except Exception as exc:
         return {"ok": False, "error": str(exc)}
diff --git a/tests/test_deps_autorepair.py b/tests/test_deps_autorepair.py
@@ -62,6 +62,13 @@ def test_vdisplay_autorepair_uses_public_api_release_floor() -> None:
     assert EXTRA_PIP_SPECS["vdisplay"] == ["vdisplay>=0.1.58"]
 
 
+def test_testql_autorepair_uses_public_runner_release_floor() -> None:
+    from koru.deps_autorepair import EXTRA_PIP_SPECS, MODULE_PIP_SPECS
+
+    assert MODULE_PIP_SPECS["testql"] == "testql>=1.2.62"
+    assert "testql>=1.2.62" in EXTRA_PIP_SPECS["desktop"]
+
+
 def _load_env2llm_registry_module():
     root = Path(__file__).resolve().parents[1] / "src"
     path = root / "koruapi" / "env2llm_registry.py"
diff --git a/tests/test_package_deduplication.py b/tests/test_package_deduplication.py
@@ -11,22 +11,33 @@
 import pytest
 
 
-def test_koru_src_has_no_private_env2llm_imports() -> None:
+def _private_dependency_imports(package: str) -> list[str]:
     root = Path(__file__).resolve().parents[1] / "src"
     offenders: list[str] = []
     for path in root.rglob("*.py"):
         tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
         for node in ast.walk(tree):
             if isinstance(node, ast.ImportFrom) and node.module:
                 parts = node.module.split(".")
-                if parts[0] == "env2llm" and any(part.startswith("_") for part in parts):
+                private = any(part.startswith("_") for part in parts) or any(
+                    alias.name.startswith("_") for alias in node.names
+                )
+                if parts[0] == package and private:
                     offenders.append(str(path.relative_to(root)))
             elif isinstance(node, ast.Import):
                 for alias in node.names:
                     parts = alias.name.split(".")
-                    if parts[0] == "env2llm" and any(part.startswith("_") for part in parts):
+                    if parts[0] == package and any(part.startswith("_") for part in parts):
                         offenders.append(str(path.relative_to(root)))
-    assert offenders == []
+    return offenders
+
+
+def test_koru_src_has_no_private_env2llm_imports() -> None:
+    assert _private_dependency_imports("env2llm") == []
+
+
+def test_koru_src_has_no_private_testql_imports() -> None:
+    assert _private_dependency_imports("testql") == []
 
 
 def test_autopilot_config_is_gillm_canonical() -> None:
diff --git a/tests/test_testql_bridge.py b/tests/test_testql_bridge.py
diff --git a/uv.lock b/uv.lock

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "koru-autopilot-plugins-workspace",`
`3`		`- "version": "0.1.434",`
	`3`	`+ "version": "0.1.435",`
`4`	`4`	`"private": true,`
`5`	`5`	`"description": "Monorepo root for all koru autopilot IDE plugins. Each IDE has its own VSIX so a regression in one cannot leak into another. Shared code (protocol, socket, host-click-submit) lives in plugins/koru-autopilot-shared and is copied into per-IDE plugins at prebuild time.",`
`6`	`6`	`"workspaces": [`