references/method.md — Docs vs Code Checker

# Evidence and verdict reference

The helper extracts candidates using text patterns; it cannot establish truth. Review every factual sentence in scope, including claims that the extraction heuristic misses. Record a stable claim ID, document path, line, and exact claim text.

Use TRUE when implementation or a direct configuration source establishes the whole claim. Use FALSE when implementation establishes an incompatible value or behavior. Use STALE when the documented value is demonstrably superseded, such as a renamed option or bumped version. Use UNVERIFIABLE for claims about deployed state, runtime results, undocumented external services, or code that is unavailable. Tests can support a finding but should not replace inspection of the behavior they exercise.

The report JSON schema is two arrays. `claims.json` contains objects with `id`, `file`, `line`, and `text`. `verdicts.json` contains matching objects with `id`, `verdict`, `reason`, and `evidence`; each evidence item has `file` and `line`. Non-UNVERIFIABLE verdicts require at least one evidence item. The helper validates structure, not the factual quality of the evidence; the agent is responsible for that review. `locate` and `inventory` inspect all regular UTF-8 text files beneath `--root` up to 1 MiB, regardless of extension. They skip `.git`, `node_modules`, `.venv`, `venv`, `dist`, `build`, `__pycache__`, and symlinked directories. For files within the size cap, a NUL byte in the first 8 KiB excludes a file as binary and increments `excluded_binary` without making coverage incomplete. Unreadable, undecodable, and oversized text files are listed as skipped; coverage is incomplete and exits 2 unless `--allow-partial` is supplied. Treat absence as evidence only when coverage is complete.

Supported platforms: macOS and Linux with POSIX directory descriptor and no-follow APIs; Windows and other platforms exit 1 before filesystem I/O.

User-supplied paths containing parent traversal (`..`), percent encoding, or backslashes are refused before reads. Repository entry names are used literally without URL decoding; percent signs and backslashes in those names are accepted. Explicit local input paths and `--root` may be absolute; repository-derived paths stay beneath the pinned root. Symlink files and directories are not followed; a symlink component is refused with physical-path guidance (on macOS, use `/private/tmp` over `/tmp` and `/private/var` over `/var`). Every file read is bounded to 1 MiB plus one byte for overflow detection; larger inputs are rejected or listed as incomplete. No stdin input is accepted. `locate` reads and decodes the whole eligible tree even after `--max` matches are collected; a token or match cap restricts output only. Directory enumeration failures are fatal errors (exit 1); individual file failures are listed as incomplete (exit 2, or 0 with `--allow-partial`).

Dry runs refuse any existing report destination, including a symlink. The report destination directory must already exist: no directories are created. Approval binds the resolved destination, report bytes, destination directory identity and its parent identity. Live mode opens path components with no-follow directory descriptors, verifies only the destination directory and its parent identities, and creates relative to the directory descriptor using exclusive no-follow creation. A symlink component or a change to either bound directory identity is refused before writing.

By Zero Width Lab (zerowidthlab.com)

License: MIT (read it).

Back to the listing