Initial import

2026-07-04 20:44:28 +02:00
commit 624011da51
6 changed files with 374 additions and 0 deletions
@@ -0,0 +1,40 @@
+# 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>`.