SETUP.md — Docs vs Code Checker

# Setup

1. Copy this complete package into the skills directory used by your agent harness. Use Python 3.10 or newer.
2. Load `SKILL.md` and `agents/docs-vs-code-checker.md` in the harness. Point the agent at a local project and the documentation files to review.
3. Run the helper from the package directory. Use paths to the target project as arguments; no project code is executed.

```text
python3 scripts/docs_claims.py extract /project/README.md --json
python3 scripts/docs_claims.py locate TIMEOUT_SECONDS --root /project --max 100
python3 scripts/docs_claims.py inventory --root /project
```

Save the `claims` array from extract as `claims.json`. The agent writes `verdicts.json` as an array with an `id`, `verdict`, `reason`, and `evidence` array per claim. Each evidence object has `file` and positive integer `line`. Ask the agent to show the completed verdicts before a report is created.

```text
python3 scripts/docs_claims.py report --claims claims.json --verdicts verdicts.json --out REPORT.md --dry-run
python3 scripts/docs_claims.py report --claims claims.json --verdicts verdicts.json --out REPORT.md --approve DIGEST
```

The second command must use the digest printed by the first. If either input, the report bytes, or the output path changes, repeat the dry run. `REPORT.md` must not already exist. The report command reads the two exact JSON files supplied and creates only the exact output path. `extract` reads only named docs; `locate` and `inventory` inspect every regular UTF-8 text file 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; `excluded_binary` reports the count without making coverage incomplete. Unreadable, undecodable, and oversized text files are listed as skipped, mark coverage incomplete, and exit 2 unless `--allow-partial` is supplied.

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