Tensor Grep Diagnostics And Tooling

tensor-grep Diagnostics and Tooling

How to measure, not eyeball, whether a tensor-grep (tg) install or a repo checkout is healthy. A full citation re-verify pass against v1.95.0 (2026-07-23) found every fact below still accurate -- only source line numbers had drifted (now refreshed; see "Provenance and maintenance" for the itemized diff). Most facts below were verified against the repo at v1.17.25 (2026-07-02); the GPU doctor-probe fields (gpu.search_runtime_probe.*, native_frontdoor_*) were re-verified against v1.75.4 (2026-07-14) by reading the cited files; the agent_readiness.py check count/names (13 repo-local, 23 total), the core doctor field names, and the new tg find/tg route-test interpretation section were spot-checked against v1.78.1 (2026-07-16) — re-verify with the commands in "Provenance and maintenance" if you suspect further drift.

When to use this skill (and when to use a sibling instead)

Use this skill when you are about to:

• Read a tg doctor --json payload and need to know which of its ~40 fields are load-bearing.
• Run tg dogfood or scripts/agent_readiness.py before a push and need to interpret a FAILED/SKIPPED check name.
• Decide which benchmarks/*.py script answers "did my change make X faster/slower".
• Explain to someone (or yourself) what a green gate actually proves, so you don't overclaim.

Use a sibling instead when the question is really about:

This skill is the interpretation layer — it explains what a signal means. It does not tell you the CLI syntax to produce other output (tensor-grep-run-and-operate), how to fix what a signal reveals (tensor-grep-debugging-playbook), or how to build a defensible speed claim from a benchmark run (tensor-grep-benchmark-and-proof-toolkit).

The four measurement tools, at a glance

None of these four tools overlap in scope — each answers a different question. Run tg doctor first (cheapest), agent_readiness.py/tg dogfood before a push, and the post-release Docker dogfood only after a version actually publishes.

Tool 1: tg doctor --json — field-by-field interpretation

Source: _build_doctor_payload / _render_doctor_payload in src/tensor_grep/cli/main.py (payload builder — grep -n "^def _build_doctor_payload" src/tensor_grep/cli/main.py, was :3142, now :3452; command registration — grep -n "^def doctor(" src/tensor_grep/cli/main.py, was :14763, now :15329 — and see "which anchors drift" under Provenance before trusting any registration line number here, including this one: main.py grew another ~944 lines this pass and even the "stable" helper band moved).

tg doctor --json --no-lsp        # fast (~2-5s); always prefer this while iterating
tg doctor --json --with-lsp      # slower; also probes external LSP providers
tg doctor                        # same payload, human-readable field dump (no PASS/FAIL judgment)

--with-lsp is the default for tg doctor (--with-lsp/--no-lsp, default True) — pass --no-lsp explicitly for a fast check, which is what scripts/agent_readiness.py and the AGENTS.md release checklist both do (tg doctor --json --no-lsp).

tg doctor's own human-readable renderer (_render_doctor_payload) is a field dump that appends a prominent warning: installation_health=... line (with remediation) whenever installation_health != "ok" (v1.110.14, #1000) — so a foreign/version-mismatch/stale installation is unmissable in human output. The bundled doctor_traffic_light.py script (below) still provides a richer PASS/FAIL/WARN summary on top.

Load-bearing fields

Live example (this repo, this box, 2026-07-02)

version = 1.17.23
search_acceleration_backend = standalone-native-tg
path_tg_first_launcher_kind = native-exe
path_tg_first_version_matches = True
rust_binary_version_status = matches
mcp_stdio_launcher_warning = "MCP stdio launcher warning: PATH candidate 4 resolves
  C:\Users\oimir\bin\tg.ps1; ... Configure MCP clients for `tg mcp` to call the managed
  native tg.exe directly ..."
gpu.available = True, gpu.search_ready = False   (2 CUDA devices present, search NOT GPU-routed)

This is a healthy payload with one real WARN (the MCP stdio shim ambiguity) — a good demonstration that "all green" is not the bar; you read every field's meaning, not just its presence.

Remediation you'll actually use

• rust_binary_version_status = stale (an in-tree dev build IS being selected and it's old): rebuild it. On this dev box: C:/Users/oimir/.cargo/bin/cargo.exe build --manifest-path rust_core/Cargo.toml --release (this exact command is the shipped rust_binary_remediation string in main.py's _doctor_rust_binary_remediation, not just a local aside) — or set TG_NATIVE_TG_BINARY to pin a specific binary. Full toolchain setup: tensor-grep-build-and-env.
• rust_binary_version_status = stale-skipped: nothing to do — this is the healthy "doctor correctly ignored your stale local build" outcome, unless you specifically need that local build to take effect (then rebuild, or pin TG_NATIVE_TG_BINARY).
• path_tg_first_launcher_kind = foreign: another program named tg shadows tensor-grep on PATH. Try tg repair-launcher (--allow-foreign-rename if you own that foreign binary and want it backed up/replaced), or reorder PATH manually.
• mcp_stdio_launcher_warning non-null: point your MCP client config at the managed native tg.exe path directly (the warning message includes the exact resolved path), not tg.ps1.

Tool 2: python scripts/agent_readiness.py — the governed pre-push gate

Source: scripts/agent_readiness.py (entire file; build_check_plan — grep -n "^def build_check_plan" scripts/agent_readiness.py, was :698, now :761).

python scripts/agent_readiness.py --json --output artifacts/agent_readiness.json
python scripts/agent_readiness.py --no-shell-probes --no-wsl-probe --json   # repo-local checks only
python scripts/agent_readiness.py --only-shell-probes                       # public shell probes only

This is the exact command AGENTS.md "Required Local Validation" tells you to run before push, alongside tg dogfood (AGENTS.md:316-323).

Two independent phases

1. Public shell probes (skip with --no-shell-probes): verify the installed, on-PATH tg resolves consistently across PowerShell, cmd, unprofiled pwsh, Git Bash, WSL (optional), and — Windows only — a Python subprocess.run(["tg", ...]) call, plus tg doctor --json --no-lsp via cmd/pwsh, a quoted-multi-word-no-match-pattern regression guard (public-windows-launcher-quoted-patterns), and public-search-advertised-flag-sweep (every rg-style flag exercised by its sweep cases — 65 distinct flag tokens as of this writing, including all --no-* inverse-config overrides — must both appear in tg search --help and actually round-trip through the real binary without an "unexpected argument" error).
2. Repo-local checks (skip with --only-shell-probes; this is the 13-check fast gate referenced elsewhere in project history): repo-cli-build-warmup, repo-doctor, context-render-trust, rg-parity-edges, broad-generated-scan-guard, ast-info-json, ast-run-smoke, mcp-context-render-smoke, mcp-stdio-protocol-smoke, agent-capsule, agent-capsule-mixed-language, agent-capsule-hardcases, docs-claim-check — exactly 13 when counted in build_check_plan.

Check name → what it actually verifies

docs-claim-check (validate_docs_claims -- grep -n "^def validate_docs_claims" scripts/agent_readiness.py; :634 as of 2026-08-14) is the mechanism that enforces the no-oversell rule described in AGENTS.md: it bans phrases like "mathematically guaranteeing", "0ms interpreter lag", "peak theoretical throughput", "GPU-ready" from docs/benchmarks.md, docs/gpu_crossover.md, and docs/PAPER.md, and requires phrases like "not promotion-ready" and "no crossover" to be present. If you are writing docs or a skill and this check would fail on your prose, that prose is oversold — reword it.

JSON report shape

{
  "artifact": "agent_readiness_report",
  "status": "complete",              // "running" while --output is being written incrementally
  "expected_version": "1.17.25",
  "root": "...",
  "summary": {"passed": N, "failed": N, "skipped": N},
  "results": [
    {"name": "...", "status": "passed|failed|skipped", "duration_s": 1.23,
     "command": [...], "returncode": 0, "message": "...",
     "stdout_tail": [...], "stderr_tail": [...]}   // last 20 lines, 4000 chars each, bounded
  ]
}

With --output <path>, the file is rewritten after every check (status: "running" + current_check), so you can tail a still-running run instead of waiting for it to finish — useful when the shell-probe phase is slow.

agent_readiness.py itself has no built-in timeout for the whole run; timeout wrapping is tg dogfood's job (see below).

Tool 3: tg dogfood — verdict + JSON envelope around agent_readiness.py

Source: src/tensor_grep/cli/dogfood.py (run_dogfood_readiness), CLI command at grep -n "^def dogfood(" src/tensor_grep/cli/main.py (was :14493, now :15059).

tg dogfood --output artifacts/dogfood_readiness.json
tg dogfood --json --timeout-s 170 --no-wsl-probe

tg dogfood spawns python scripts/agent_readiness.py as a subprocess (same two phases as Tool 2) and wraps it with:

{
  "artifact": "dogfood_readiness_report",
  "dogfood_version": 1,
  "command": [...],                    // the exact agent_readiness.py argv used
  "agent_readiness": { ... },          // the full nested report from Tool 2 (or a timeout stub)
  "verdict": {"status": "PASS"|"FAIL", "failed_checks": [...], "summary": "..."},
  "world_class_readiness": { ... },    // see below -- READ THIS CAREFULLY
  "write_policy": { "mode": "read_only_except_explicit_output_and_readiness_probe_output", ... },
  "release_docs_worktree": {"status": "clean"|"dirty"|"unknown", "dirty_paths": [...]}
}

world_class_readiness is a STATIC disclaimer block, not a live signal. _build_world_class_readiness() (dogfood.py:207) takes zero arguments and returns the identical literal content on every single run, regardless of repo state. Its status field is always "not_claimed". Its purpose is purely governance: it exists so a passing tg dogfood run can never be misread as "tg replaces rg", "tg replaces ast-grep", "GPU is promotion-ready", or "LSP navigation is proven" — each of those surfaces has an explicit required_evidence entry describing what WOULD need to be true. Do not write code or docs that branch on world_class_readiness.status expecting it to reflect anything about the current run.

write_policy documents tg dogfood's own no-mutation contract: it writes only the explicit --output path plus a sibling <output-stem>.agent-readiness.json child report (or, with no --output, artifacts/agent_readiness/dogfood-agent-readiness.json). Tracked release docs are never touched by tg dogfood — that's python scripts/stamp_release_assets.py's job, a separate release-workflow step. release_docs_worktree just reports git status --porcelain on the 7 governance doc paths (AGENTS.md, README.md, SKILL.md, docs/SESSION_HANDOFF.md, docs/CONTINUATION_PLAN.md, docs/CONTRACTS.md, tests/unit/test_public_docs_governance.py) — informational, does not affect verdict.

--timeout-s (default 170.0) bounds the whole nested agent_readiness.py subprocess; on timeout, tg dogfood kills the process tree (via psutil if available, else taskkill /T /F on Windows) and injects a synthetic agent-readiness-timeout failed check plus "status": "timed_out" into the agent_readiness object — this is the ONLY place a timeout concept exists; agent_readiness.py run standalone has none.

Don't read tg dogfood's wall-clock time as a speed signal, warm or cold. Its checks invoke the CLI end-to-end (tg orient, tg agent, tg search, ...) against whatever repo/session state is already on disk — a warm session-daemon cache or an LRU-cached parse means the specific function you just changed may not even execute on this run, which can hide a real win just as easily as it can make a broken change look fine. Receipt: an end-to-end warm read of tg orient measured -36% (looked like a regression) on a function that was actually ~54% FASTER once isolated and cold-microbenched — the warm run was timing the cached path, not the changed one. For an actual speed claim, cold-microbench the specific changed function on the shipped wheel (see the global skill profile-guided-byte-identical-optimization) or use the dedicated scripts in tensor-grep-benchmark-and-proof-toolkit — never an end-to-end dogfood run.

Tool 4: post-release Docker dogfood (scripts/dogfood/)

Source: scripts/dogfood/dogfood_features.py, scripts/dogfood/README.md, scripts/dogfood/Dockerfile.

# after a version actually publishes to PyPI:
docker build --build-arg TG_VERSION=1.110.14 -f scripts/dogfood/Dockerfile -t tg-dogfood scripts/dogfood
docker run --rm tg-dogfood
# or, without Docker, against any installed tg:
pip install "tensor-grep==1.110.14"
python scripts/dogfood/dogfood_features.py         # or TG_BIN=/path/to/tg python ...

This is the only one of the four tools that runs the real, installed, published tg binary through its actual front door (tensor_grep.cli.bootstrap:main_entry). Tests using Typer's CliRunner — and, for CLI-invoked checks, parts of agent_readiness.py/tg dogfood when run inside a uv run editable checkout — still exercise real subprocesses, but the specific value of this tool is validating the published PyPI artifact, in a clean environment, with zero repo context. It generates a tiny fixture repo (a hub function imported by two modules, plus a .rs file) and runs --version, search (plain + --rank regression guard for the v1.14.0 bug + --rank --json + --json), orient (+ --json + empty-dir), map, agent --json. Exit 0 = every feature works on the shipped artifact; exit 1 = a named regression with output.

When you ship a new user-facing feature, add a check(...) line here so the battery grows. For the full "why CliRunner alone is not enough" rationale and workflow discipline, see the global skill dogfood-the-shipped-artifact — this section only covers what the script measures.

The same warm-vs-cold caution applies here. Even though each run builds a fresh fixture repo, this tool's per-check timing is incidental to a correctness pass/fail, not a controlled repeated measurement — do not read a fast or slow Docker-dogfood run as evidence a hot-path optimization landed or regressed; see the tg dogfood caveat above for the correct methodology.

Interpreting tg find / tg route-test output (v1.77.0+, #189)

Two newer JSON surfaces belong in this skill's "what does the field actually prove" territory — neither is a health-check tool like Tools 1-4 above, but both need the same field-by-field interpretation discipline before you trust them.

tg find (grep -n "^def find(" src/tensor_grep/cli/main.py, was :4625, now :5043, onward):

tg route-test (grep -n "^def route_test(" src/tensor_grep/cli/main.py, was :10302, now :10997, onward) — diagnoses routing agreement between context-render and edit-plan:

Both are new-command additions to this skill's interpretation layer, not new measurement TOOLS — the four tools table above (tg doctor, agent_readiness.py, tg dogfood, the Docker dogfood) is unchanged by their existence.

Benchmarks — which script answers which question

Deep methodology (claim-quality artifacts, the noise-floor/absolute-jitter rule, the fair-baseline rule, launcher-attribution fields) lives in tensor-grep-benchmark-and-proof-toolkit — load that skill before constructing or disputing a speed claim. This table is only the "which tool do I reach for" lookup (source: AGENTS.md "Benchmark Rules", verified against each script's argparse block):

benchmarks/run_benchmarks.py refuses claim-quality output (not the run itself) when the timed tg entrypoint is a stale in-tree native binary (benchmark_binary_warnings / benchmark_claim_blockers in run_benchmarks.py:194-225 — corrected this pass; a prior pass had mis-cited this as :212-243, which is benchmark_claim_blockers's own def line through past the end of the block, not the block's real start at benchmark_binary_warnings's def line) — it prints a blocker to stderr and requires --allow-claim-unsafe-launcher to proceed anyway for exploratory-only timing. It also tags every artifact with tg_launcher_mode and tg_launcher_command_kind (classify_tg_launcher_command, e.g. native_exe, uv, python_module, cmd_shim, powershell_shim) so a slow wrapper/interpreter overhead is never silently attributed to the search engine itself. benchmarks/check_regression.py --baseline auto resolves benchmarks/baselines/run_benchmarks.<platform>.json and fails (exit 2) on an environment mismatch unless you pass --allow-env-mismatch.

A handful of older scripts (scripts/parity_check.py, scripts/stress_test_gauntlet.py, scripts/generate_parity_corpus.py) exist but are not referenced by AGENTS.md or CONTRIBUTING.md and are not part of the governed gate — treat them as legacy/exploratory, not a source of truth.

Common failure patterns

The bundled traffic-light script

scripts/doctor_traffic_light.py (in this skill directory) fills the one real gap in the four tools above: there is no fast, standalone way to get a PASS/WARN/FAIL judgment on a single tg doctor --json snapshot without either eyeballing ~40 raw fields yourself or running the full 3-5 minute agent_readiness.py/tg dogfood gate. It is read-only (writes only to an explicit --output you pass) and works against any installed tg, not just a repo checkout.

python .claude/skills/tensor-grep-diagnostics-and-tooling/scripts/doctor_traffic_light.py
python .claude/skills/tensor-grep-diagnostics-and-tooling/scripts/doctor_traffic_light.py --json
python .claude/skills/tensor-grep-diagnostics-and-tooling/scripts/doctor_traffic_light.py --with-lsp
python .claude/skills/tensor-grep-diagnostics-and-tooling/scripts/doctor_traffic_light.py --root C:\some\repo --tg-bin tg
python .claude/skills/tensor-grep-diagnostics-and-tooling/scripts/doctor_traffic_light.py --from-file captured_doctor.json

It is a supplement, not a replacement: passing it only means one doctor snapshot looks sane — it does not run any of the 13 governed agent_readiness.py checks, does not dogfood the real published binary, and does not run a benchmark. Exit code 0 unless a check is FAIL (WARN/INFO never fail the exit code, matching tg doctor's own non-gating nature).

Provenance and maintenance

Base doctor/dogfood facts verified against v1.17.25 (2026-07-02); the GPU doctor-probe fields (failure taxonomy, native_error_kind, native_frontdoor_* flavor fields, the honest out-of-range device-id warning) re-verified against v1.75.4 (2026-07-14) -- both by reading the cited source directly; the tg find/tg route-test interpretation section is new as of v1.78.1 (2026-07-16), originally verified against main.py:4354-4440/:9833-9925. A consolidated re-grep pass 2026-07-22 (v1.93.2) found EVERY main.py:NNNN citation in this file had drifted (several by 1200-4400 lines — main.py is now 16897 lines) and refreshed them: doctor def :14302, _build_doctor_payload :3131, _doctor_rust_binary_remediation :2421, the GPU-probe functions :2894/:2910, the flavor-mismatch function :3110, dogfood :14032, find :4525, route_test :10074 — plus a one-line mention of A14/#708 (bootstrap no-ignore flag-field parity; _agent_gpu_tg_command's shutil.which pre-resolution). Field SEMANTICS in every table above are UNCHANGED by this pass — only the line-number citations moved.

A second consolidated re-grep pass 2026-07-23 (v1.95.0) re-checked every citation above plus the full doctor payload field set (_build_doctor_payload's literal dict, read end-to-end), the 13 repo-local + 10 shell-probe check names (23 total, build_check_plan read end-to-end), the 65-flag-token public-search-advertised-flag-sweep sweep (recounted by hand from _public_search_flag_sweep_cases), the GPU failure-taxonomy status strings, the docs-claim-check banned/required phrase list, and the 7-path RELEASE_DOCS_GOVERNANCE_PATHS tuple behind release_docs_worktree — every one of those facts is STILL accurate. Only line numbers had drifted again (main.py grew from 16897 to 17032 lines; dogfood.py and agent_readiness.py each grew too): _build_doctor_payload :3142, doctor command :14437, _doctor_rust_binary_remediation :2432, the GPU-probe functions :2905/:2921, the flavor-mismatch function :3121, _agent_gpu_tg_command (agent_capsule.py (find it: grep -n "^def _agent_gpu_tg_command" src/tensor_grep/cli/agent_capsule.py)), dogfood command :14167, _build_world_class_readiness (dogfood.py:207), find :4574, route_test :10123, validate_docs_claims (grep -n "^def validate_docs_claims" scripts/agent_readiness.py -- :634 as of 2026-08-14)

…(truncated)