tensor-grep-diagnostics-and-tooling

name

tensor-grep-diagnostics-and-tooling

description

Use when you need to MEASURE tensor-grep's health instead of eyeballing it -- interpreting a `tg doctor --json` field, reading a PASS/FAIL/SKIP from `tg dogfood` or `scripts/agent_readiness.py`, or explaining what a diagnostic field actually proves (and does not prove). Not for CLI syntax (tensor-grep-run-and-operate), fixing a found bug (tensor-grep-debugging-playbook), or deciding which `benchmarks/*.py` script to run / constructing a claim-quality benchmark artifact (tensor-grep-benchmark-and-proof-toolkit).

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:

You need...	Use instead
Exact CLI syntax for tg orient / search --rank / session / checkpoint / mcp / etc.	tensor-grep-run-and-operate
Investigating a hang, wrong/silent-empty result, red CI, or a release that didn't publish	tensor-grep-debugging-playbook
Whether a "novel" fix idea was already tried and reverted	tensor-grep-failure-archaeology
Constructing a claim-quality benchmark artifact, the noise-floor rule, fair-baseline rule	tensor-grep-benchmark-and-proof-toolkit
The 4 command / 2 flag registration sites, the front door, the backend fail-closed contract	tensor-grep-architecture-contract
Every TG_*/TENSOR_GREP_* env var and its default/guard	tensor-grep-config-and-flags
Rebuilding the Rust extension/binary, toolchain setup, maturin develop	tensor-grep-build-and-env
PR/release process gates (one-merge-per-tick, draft-PR-only, etc.)	tensor-grep-change-control

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

Tool	What it measures	Speed	Mutates repo?
tg doctor --json --no-lsp	One point-in-time snapshot: version parity, launcher routing, native-binary staleness, GPU/LSP/AST/session-daemon state	~2-5s	No
python scripts/agent_readiness.py --json	13 repo-local trust checks (+ up to ~9 more public-shell probes) — the governed pre-push gate	~1-5 min	Only --output <path> if given
tg dogfood --json	Wraps agent_readiness.py as a subprocess; adds a one-page verdict + a static "what this does NOT prove" disclaimer	Same as above + small overhead	Only --output <path> (+ sibling .agent-readiness.json)
python scripts/dogfood/dogfood_features.py	Runs the real published binary (post-release, in Docker or any clean install) through every user-facing feature	Seconds	No

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

Field	Healthy value	What a bad value means
version	your expected tensor-grep version string	absent/mismatched → doctor itself couldn't resolve the installed package
search_acceleration_backend	standalone-native-tg | rust-core-extension | python	These are the only 3 values the current builder emits (verified live: standalone-native-tg on this box). scripts/agent_readiness.py's validator also accepts a 4th legacy string native-standalone that nothing currently produces — don't be surprised if you never see it.
native_tg_binary_kind	standalone-executable, in-tree-*, etc.	tells you WHERE the resolved native binary came from
path_tg_first_launcher_kind	native-exe | managed-native | cmd-shim | powershell-shim | python-entrypoint | bash-shim	foreign means the first tg on PATH is not tensor-grep (some unrelated tool named tg)
path_tg_first_version_matches	true (or null if unprobed)	false is a hard problem: the first tg your shell resolves is stale or foreign. Read path_tg_foreign_warning + path_tg_foreign_remediation alongside it.
fresh_shell_path_tg_first_launcher_kind / *_version_matches	same shape as above, but simulated for a brand-new shell (reads Windows registry PATH on Windows)	catches "your current shell is fixed but a fresh terminal still resolves the wrong tg"
python_subprocess_path_tg_first_* (Windows only)	same shape	Python's own subprocess.run(["tg", ...]) can resolve than your interactive shell (e.g. Windows picks ahead of a bridge) — this is what MCP servers and other Python tooling actually see

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

Check name	What it verifies	A SKIP (not FAIL) is normal when...
repo-cli-build-warmup	uv run tg --version — syncs + warms the editable build; must pass first, everything after trusts it	never skips; if it fails, run uv sync (the validator message tells you this)
repo-doctor	uv run --no-sync tg doctor --json --no-lsp sanity on the just-built repo tg	—
context-render-trust	tg context-render on a fixed test file/query keeps the correct primary file + body context (an agent-capsule target-selection regression guard)	—
rg-parity-edges	tests/e2e/test_rg_parity_edges.py — deterministic rg edge cases (BOM, NUL bytes, etc.)	—
broad-generated-scan-guard	unbounded/broad generated-root scans require explicit bounds or opt-in (a DoS/hang guardrail)	—
ast-info-json	tg ast-info --json lists python among supported languages	—
ast-run-smoke	tg run --pattern ... --lang js --json AST smoke	AST dependencies/backend are unavailable in this environment (matched via skip_error_patterns)
mcp-context-render-smoke	MCP context-render tool preserves invoice body + target	—
mcp-stdio-protocol-smoke	full tg mcp stdio initialize/tools/list/tools/call roundtrip	—
agent-capsule	tg agent Actionable Context Capsule, CLI + MCP	—
agent-capsule-mixed-language	mixed-language invoice capsule + validation stay aligned	—
agent-capsule-hardcases

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):

Field	Healthy value	What a bad/absent value means
rank_fallback_reason	absent when the dense leg fully participated; a string (e.g. the semantic extra or model is unavailable) when it degraded	this is a visible, legitimate degrade — BM25-only is still a fully-supported result. Do NOT read a populated value as an error; DO be suspicious of a run you expected to be hybrid that shows no dense-leg evidence at all with this field also absent (see tensor-grep-debugging-playbook §4).
result_incomplete	false/absent on a complete scan	true means --deadline/--max-repo-files/the internal corpus-wide chunk cap truncated the walk — the ranked results are a FLOOR, not the full answer. Exit code confirms this independent of the JSON: any truncation exits 2, whether or not matches were found (tensor-grep-run-and-operate §11c, tensor-grep-large-repo-scale-campaign §1/§5).
exit code	0 = complete + found; 1 = complete + empty; 2 = BackendExecutionError OR any truncation	do not read exit 2 here as a plain usage error the way tg search's exit-2 convention works (§11b) — tg find follows the symbol-command-style "truncation trumps found" shape, a DIFFERENT convention than tg search.

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:

Field	Healthy value	What a bad value means
agreement	true	false means the two target-selection paths picked DIFFERENT primary files/symbols/lines for the same query — treat an edit-plan target as unverified until you understand why they diverged, not just proceed
warnings[]	[]	each entry names a specific divergence reason; read every entry before trusting either route's primary target

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):

Change area	Script	Compare with
plain search routing, startup/launcher, text-search control plane	benchmarks/run_benchmarks.py	benchmarks/check_regression.py --baseline auto
StringZilla index, CPU regex prefilter, cache/decode/posting-list	benchmarks/run_hot_query_benchmarks.py	absolute-jitter tolerance for sub-10ms rows
AST single-query cold start (tg run vs native sg)	benchmarks/run_ast_benchmarks.py	—
run/scan/test AST workflow startup/batching	benchmarks/run_ast_workflow_benchmarks.py	—
tg agent capsule routing, edit-loop latency	benchmarks/run_agent_workflow_benchmarks.py, benchmarks/run_agent_success_harness.py	workflow evidence, not a cold exact-text speed claim
GPU/NLP backend	benchmarks/run_gpu_benchmarks.py	rg -F -e ... -e ... (the fair many-pattern baseline); treat cyBERT SKIP as expected infra state when Triton is unavailable, not a fake failure

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

Symptom	Likely cause	What to do
tg doctor shows path_tg_first_launcher_kind = foreign	a different tool named tg is first on PATH	tg repair-launcher (see remediation above)
rust_binary_version_status = stale (not stale-skipped)	a dev build in rust_core/target/{debug,release}/ is stale and selected	rebuild via cargo (see remediation above); tensor-grep-build-and-env for full toolchain setup
ast-run-smoke shows SKIPPED	AST deps/backend unavailable in this environment	expected, not a regression — do not treat as FAIL
docs-claim-check FAILS right after a version bump	a doc still has stale vX.Y.Z prose, or is missing a required fragment	usually self-heals via python scripts/stamp_release_assets.py's _stamp_release_doc prose-pattern stamping during release (a separate mechanism from the version_variables list in pyproject.toml's [tool.semantic_release] config, which scripts/validate_release_assets.py checks); if hand-editing docs, match the exact prose patterns in validate_docs_claims
Unit/integration tests are all green, but the real published binary is broken	CliRunner bypasses tensor_grep.cli.bootstrap:main_entry (the real front door)	run Tool 4 (scripts/dogfood/dogfood_features.py) against the real binary; see dogfood-the-shipped-artifact
repo-cli-build-warmup fails or times out	the repo-local uv/tg editable entrypoint is stale/unsynchronized	uv sync, or uv run --refresh-package tensor-grep tg --version
gpu.available = true but you expected GPU search to actually run	available only reflects CUDA device presence	check and instead — GPU is experimental-until-proven

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), build_check_plan (agent_readiness.py:698). run_benchmarks.py's benchmark_binary_warnings/ benchmark_claim_blockers block (:194-225) had NOT drifted and needed no change. Field SEMANTICS remain UNCHANGED by this pass too — only line-number citations moved. This pass also added the Tool 3/Tool 4 warm-dogfood-hides-a-cold-path-win caveat above (the tg orient -36%-vs-+54% receipt) — see the global skill profile-guided-byte-identical-optimization for the full methodology.

2026-07-27 re-derivation — WHICH ANCHORS DRIFT (read this before trusting any number above). A fourth pass re-derived every anchor in this file against origin/main and found the drift is not uniform, which is the useful part: six anchors had not moved at all — _doctor_rust_binary_remediation :2432, the GPU probes :2905/:2921, the flavor-mismatch helper :3121, _build_doctor_payload :3142, agent_capsule.py (find it: grep -n "^def _agent_gpu_tg_command" src/tensor_grep/cli/agent_capsule.py), and dogfood.py:207 — while every command registration had: doctor :14437->:14763, dogfood :14167->:14493, find :4574->:4625, route_test :10123->:10302, plus the two scripts/agent_readiness.py helpers (validate_docs_claims :560->:623, now :634, build_check_plan :698->:761). The rule: private helpers in main.py's ~2400-3500 band are stable anchors; @app.command() registrations in the file's tail are not, because every new tg command is appended and shifts all of them. So cite a helper by line if you must, but cite a command by its grep -n "^def <name>(" re-verify form — which is why the live sections above now carry one. The numbers inside the 2026-07-22 paragraph immediately above are superseded by this list; they are left in place as a record of that pass, not as current truth.

One methodological note worth keeping, because it cost a false finding this pass: a git cat-file blob origin/main:scripts/run_benchmarks.py returned "does not exist" and was nearly filed as a dead reference. The skill never said scripts/ — it correctly says benchmarks/run_benchmarks.py (:345, :352), and its :194-225 cite is still exact. The bad path was invented by the checker, not the doc. Re-read what the doc actually claims before filing drift against it.

2026-08-01 re-derivation — the "stable anchor" theory from the 2026-07-27 paragraph above did NOT hold on the next pass. That paragraph reported six main.py private helpers "had not moved at all" and proposed a rule — private helpers in the ~2400-3500 band are stable, @app.command() registrations in the tail are not. This pass re-derived the same six against origin/main (main.py grew again, 17032 -> 17976 lines) and found all six had moved 71-85 lines: _doctor_rust_binary_remediation :2432->:2503, the GPU probes :2905->:2976 / :2921->:2992, the flavor-mismatch helper :3121->:3206, _build_doctor_payload :3142->:3227 — while agent_capsule.py (find it: grep -n "^def _agent_gpu_tg_command" src/tensor_grep/cli/agent_capsule.py), dogfood.py:207, agent_readiness.py's validate_docs_claims :623, now :634, and build_check_plan :761 (the already-corrected 07-27 value) stayed exactly put. The refined rule: it is not "private helper vs. command registration" — it is "lives in main.py's own private-helper band vs. lives in a separate, smaller file." main.py is the single fastest-growing file in this repo (every new tg command AND most doctor/GPU features land there), so nothing inside it is a stable anchor across passes, helper or command; dogfood.py/agent_capsule.py/agent_readiness.py helpers have held steady across three consecutive passes because those files grow far slower. Every main.py citation in the live sections above (Tools 1-3, the tg find/tg route-test section, the Benchmarks section) has been converted to a grep -n "^def <name>(" instruction with its own was -> now receipt rather than a bare number, per AGENTS.md's never-re-stamp rule — do the same for any NEW main.py citation added to this file, regardless of whether it looks like a "stable" private helper. Also corrected this pass, an internal inconsistency rather than pure staleness: the "Source:" line for Tool 2 () still said was at line 698, even though the 07-27 paragraph two sections below it had already corrected that to 761 — the live citation and the file's own provenance record had drifted apart. And the Benchmarks-section citation for / said , which does not match either the actual current location (, confirmed unchanged since 2026-07-23) or make sense as a block start — is 's own def line, after at . Every other fact re-checked this pass (23 total agent-readiness checks, the 65-flag-token sweep, the banned-marketing-phrase list, the 7-path tuple, the -style function names referenced elsewhere) is confirmed STILL ACCURATE — this was a pure line-number-and-one-typo pass, no other field semantics changed.

2026-08-13 re-derivation (v1.110.14 doctor rows, #1000) — the v1.110.14-tagged rows above were verified against the source this pass, and four of them needed correction. Tree: 568065a (pyproject.toml version = "1.110.14" at :556; main.py is 17949 lines here). (1) installation_health — the live row carried THREE wrong enum names (foreign_tg_on_path, version_mismatch, stale_installation) and omitted unverifiable_version; the real names, verified in _doctor_installation_health (main.py:2712-2728), are foreign_launcher / unverifiable_version / launcher_version_mismatch / stale_install / unknown_pypi / ok in that precedence order — fixed directly in the table (wrong current-state claim, not a receipt rewrite). (2) shadow_launchers — the live row described "launchers registered on PATH behind the primary one", which is not what the builder does: _doctor_shadow_launchers (:2677-2695) consolidates the FIRST-CANDIDATE entries of the three routes (route_entries :3763-3794), listed iff foreign OR version_matches is False OR version_matches is None, absent routes filtered first, deterministic _ROUTE_ORDER (:2674) — row rewritten. (3) The "public tg doctor telemetry bundle sends this to the health endpoint" claim has ZERO source backing in src/ (grep health.endpoint|telemetry finds only unrelated opentelemetry/GPU-telemetry hits) — marked UNVERIFIED/NO-SOURCE in place rather than silently deleted. (4) gpu.search_runtime_probe.status was missing two statuses the probe itself sets: failed (timeout / spawn OSError / invalid-JSON stdout — :3298/:3302/:3319) and unsupported (exit 0 but not NativeGpuBackend, or sidecar — :3335); both added, and the taxonomy constants re-verified at :3168-3179. The two GPU-probe helper anchors moved again (:2976->, ->) — consistent with the "nothing inside is a stable anchor" rule above; every other fact re-checked this pass ( at , the renderer at , at , at ) is confirmed accurate. No other field semantics changed.

Re-verify if this skill feels stale:

# current version
grep -n '^version = ' pyproject.toml

# doctor payload fields (re-check the table above against the real builder)
grep -n 'search_acceleration_backend\|rust_binary_version_status\|launcher_kind' src/tensor_grep/cli/main.py

# GPU doctor-probe failure taxonomy + native-frontdoor flavor fields
grep -n 'native_error_kind\|_doctor_gpu_probe_failure_status\|native_frontdoor_flavor_mismatch_note\|_warn_unavailable_gpu_device_ids' src/tensor_grep/cli/main.py

# agent_readiness check names / count (13 repo-local checks expected)
grep -n 'name="' scripts/agent_readiness.py

# tg dogfood verdict/world_class_readiness shape
grep -n 'world_class_readiness\|_build_verdict\|write_policy' src/tensor_grep/cli/dogfood.py

# benchmark script -> change-area mapping, still current
grep -n '^## ' AGENTS.md | sed -n '/Benchmark Rules/,/Performance Discipline/p'

# does the traffic-light script still run clean against the live binary?
python .claude/skills/tensor-grep-diagnostics-and-tooling/scripts/doctor_traffic_light.py --json

Open uncertainties (do not treat as settled without re-checking):

• agent_readiness.py's doctor validator accepts a legacy "native-standalone" backend string that the current _build_doctor_payload never emits — unclear if this is intentional forward compatibility or simple drift; harmless either way (the traffic-light script also accepts it). Re-check main.py's search_acceleration_backend ternary if a 4th backend kind is ever added. Also unconfirmed against agent_readiness.py: no schema link — the two lists (this skill's KNOWN_BACKENDS and the payload builder) are recorded from direct reads, not enforced by a shared constant, so a future rename can silently desync all three. DEFERRED CANDIDATE: introduce a shared source-of-truth for this enum before it grows a 5th value.