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. Most facts below are 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 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 (command registration at main.py:9903, payload builder at main.py:2745).

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 straight field dump — it does not compute PASS/FAIL/WARN. The bundled doctor_traffic_light.py script (below) fills that gap.

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 differently than your interactive shell (e.g. Windows CreateProcess picks .exe ahead of a .com bridge) — this is what MCP servers and other Python tooling actually see
rust_binary_version_status	matches or stale-skipped	missing is often benign (no standalone native binary in play; check search_acceleration_backend). stale or mismatch is a real problem — see remediation below.
rust_binary_remediation	null except for mismatch, stale, and the healthy stale-skipped case	when non-null, it is a copy-pasteable fix string, e.g. rebuild-the-in-tree-binary guidance; note stale-skipped always carries this rebuild-hint string even though it needs no action (_doctor_rust_binary_remediation, main.py:2153-2168, unconditionally returns it on stale-skipped)
skipped_native_tg_binaries	[], or a list of correctly-ignored stale in-tree binaries	a non-empty list here is the healthy outcome when you have an old local dev build lying around — it means doctor correctly did NOT select it
mcp_stdio_launcher_warning	null	non-null on Windows usually means a PowerShell shim (tg.ps1) is ambiguous for MCP stdio clients; the message tells you to point the MCP client at the native tg.exe directly
gpu.available / gpu.search_ready / gpu.tier.promotion_proof	available reflects CUDA device presence; search_ready reflects whether a real search actually routed through NativeGpuBackend	gpu.available=true does NOT mean GPU search works. Always read search_ready and tier.promotion_proof, not just available. GPU is experimental-until-proven (see docs/gpu_crossover.md) — never a PASS/FAIL signal, always informational.
gpu.search_runtime_probe.status (v1.75.2, #595 + gate-nits v1.75.4, #597)	supported, or one of the failure-taxonomy statuses: not_run, path_domain_mismatch, failed_input, failed_gpu_unavailable, failed_path_bridging (WSL cross-domain), failed_probe_path (same-domain path vanished), failed_other (unrecognized/unparseable -- fails closed)	Replaces a single opaque "failed" for every rc!=0 outcome -- read the specific status before assuming "GPU is just broken"; failed_input (e.g. gpu_invalid_device_id) means a bad request, not an unavailable GPU (_doctor_gpu_search_runtime_probe/_doctor_gpu_probe_failure_status, main.py:2774-2874)
gpu.search_runtime_probe.native_error_kind	null, or the native binary's own structured --json error kind (e.g. path_not_found, empty_pattern, invalid_regex, gpu_fatal, gpu_invalid_device_id)	the raw kind behind the mapped status above -- null means stdout wasn't the expected structured JSON at all (a raw panic, empty output), not that there was no error
native_frontdoor_flavor / native_frontdoor_requested_flavor / native_frontdoor_asset_name / native_frontdoor_metadata_status / native_frontdoor_flavor_mismatch_note	populated strings when a managed native front door is installed	surfaces "you asked for nvidia but got cpu" (_doctor_native_frontdoor_flavor_mismatch_note, main.py:2990) -- previously only a benchmark script could see this; now visible in plain tg doctor
lsp.enabled / lsp.providers[].health_status	health_status in {ready, available_unverified, unhealthy, missing}	provider availability is not navigation proof. A provider counts as real LSP evidence only when a completed request set lsp_provider_response = true — provenance = "lsp-*" alone is not enough (AGENTS.md LSP rules).
ast_grep.available / ast_grep.binary	true / a resolved path	false degrades tg run's semantic (--selector/--strictness) options; AST structural search itself still works via the native backend
session_daemon.running	informational	true means a warm localhost daemon is serving cached repo-map/session state for this root

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 at line 666).

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	polyglot monorepo, generated-noise, Rust/Python/JS/TS hardcases	—
docs-claim-check	no subprocess — reads AGENTS.md/README.md/SKILL.md/docs/*.md directly and checks required fragments + version-staleness prose patterns + a banned-phrase list on GPU docs	—

docs-claim-check (validate_docs_claims in agent_readiness.py:537) 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 main.py:9651.

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

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.17.25 -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.17.25"
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.

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 (main.py:4340-4440):

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 (main.py:9833-9925) — 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) — 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 gpu.search_ready and gpu.tier.promotion_proof instead — GPU is experimental-until-proven
tg search --gpu-device-ids N / tg agent --gpu-device-ids N silently proceeds despite an out-of-range N (v1.75.2, #595)	N isn't in the local DeviceDetector inventory	check stderr for the _warn_unavailable_gpu_device_ids WARN (never a hard failure) naming the requested id and the actually-available ids; silent when the inventory is empty (a CPU-only box has no CUDA devices to warn about)

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), verified directly against main.py:4340-4440/:9833-9925. Re-verify if this skill feels stale, and treat the v1.17.25-era claims as the ones most likely to have drifted furthest, not the GPU section:

# 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.