facts/AGENTS.md

AGENTS.md

Overview

facts is a tiny compiled Zig CLI for turning file paths into stable TSV file metadata. It exists as an agent-safe replacement for the safe subset of stat, du, and find -printf when allowlist policy needs argv-obvious behavior.

How to build

zig build

How to test

zig build test

Constraints

• One source file: facts.zig.
• No runtime dependencies, no shell execution, no mutation.
• stdout is TSV with a header; diagnostics go to stderr.
• No filtering, sorting, paging, JSON, color, expression language, callbacks, or hidden state.
• This is an inspection primitive. Keep filtering in adjacent stream tools such as grep/pick, not in facts.

Requirement Governance

REQUIREMENTS.md is the requirement authority for this repository and is checked with redgate. Before implementation work, read the applicable requirement row; if none covers durable behavior, update REQUIREMENTS.md first or stop and ask. For behavior intended to stick, add or update a failing smoke/contract proof before implementation unless that would be fake or disproportionate. Before handoff, compare the user request and diff against REQUIREMENTS.md; report REQUIREMENT IMPACT: updated <rows> or exactly REQUIREMENT IMPACT: none - <specific reason>.