# 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

```sh
zig build
```

## How to test

```sh
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>`.