SKILL.md — Docs vs Code Checker

---
name: docs-vs-code-checker
description: Check documentation claims against repository source with an offline helper and evidence-led agent.
license: MIT
---

# Docs vs Code Checker

Install this directory as an Agent Skill in a harness that can read local files and run Python 3.10 or newer. Follow [SETUP.md](SETUP.md), then give the harness [agents/docs-vs-code-checker.md](agents/docs-vs-code-checker.md) as the agent instructions.

The agent reads the selected README and docs, extracts candidate factual claims, searches the repository, and assigns TRUE, FALSE, STALE, or UNVERIFIABLE with file:line evidence. It does not run project code, install dependencies, access the network, or edit files unless asked to create a report.

`locate` and `inventory` inspect all regular files beneath `--root` that decode as UTF-8 and fit the 1 MiB cap. They skip `.git`, `node_modules`, `.venv`, `venv`, `dist`, `build`, `__pycache__`, and symlinked directories. Files within the size cap with a NUL byte in the first 8 KiB are excluded as binary and shown in `excluded_binary`; they do not make coverage incomplete. Unreadable, undecodable, or oversized text files are listed as skipped, make coverage incomplete, and cause exit 2 unless `--allow-partial` is supplied. The helper provides `extract`, `locate`, `inventory`, and an approval-gated `report` command. A dry run prints the SHA-256 approval digest for the exact output path and report bytes. Live report creation requires `--approve DIGEST` and refuses an existing file or symlink.

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