Initial import

REQUIREMENTS.md

@@ -0,0 +1,15 @@
+# REQUIREMENTS
+
+## facts
+
+ring	id	requirement
+0	001	`facts` must be a compiled single-file Zig CLI with no runtime dependencies beyond the OS.
+0	002	`facts` must inspect file metadata only; it must not mutate files, execute callbacks, access the network, read hidden config, prompt, page, colorize, or emit JSON by default.
+1	003	`facts PATH...` must emit one TSV record per path plus a header row with stable columns `path`, `kind`, `size`, `mode`, and `mtime_ns`.
+1	003.tsv-safety	`facts` must preserve one-line TSV records by rejecting unsupported path bytes that cannot be emitted raw in TSV fields, including tab, carriage return, and newline, before writing a path record to stdout.
+1	004	With no path arguments, `facts` must read one path per stdin line and emit the same TSV contract.
+1	004.streaming	Stdin mode must stream with bounded memory: emit the TSV header before waiting for stdin EOF, process completed input lines independently, flush each completed output record before EOF, and never buffer all stdin.
+1	005	Per-path runtime errors must be diagnostics on stderr, must not corrupt stdout records for other paths, and must make the process exit nonzero after flushing valid records.
+1	006	`facts` must not filter, sort, glob, or provide an expression language; callers compose with `files`, `grep`, `pick`, `sort`, or similar stream tools.
+1	007	`zig build test` must prove argv input, stdin input, streaming stdin behavior, TSV header shape, TSV safety rejection, size reporting, directory reporting, help output, and per-path error handling.
+1	008	`facts --help` and `facts -h` must emit usage text to stdout without a TSV header and exit zero.