files/REQUIREMENTS.md

Requirements

Rows are TSV: RING<TAB>ID<TAB>SUMMARY. Rings are product-foundation layers, not implementation size.

files

0 001 files emits stdout records only: one file-like path per line, with no color, progress, prompts, paging, sorting, JSON, or decoration. [core] 0 002 files accepts zero or more PATH roots; --help and -h print complete usage, output, diagnostics, exit-status, and example guidance only when used as the sole argument. [core] 0 003 When a PATH root names a directory, files recursively traverses it without following symlinked directories and emits file-like entries below it. [core] 0 004 When a PATH root names a non-directory file-like path, files emits that path exactly once. Multiple roots are processed left-to-right without sorting or dedupe. [core] 0 005 Usage mistakes emit usage on stderr and exit 2; runtime failures emit a diagnostic on stderr and exit nonzero without corrupting stdout. [core] 0 006 files has no mutation surface: no deletion, exec, callbacks, network access, hidden writes, config discovery, glob policy, or expression language. [agent] 1 007 The repository verifies files with POSIX-sh smoke coverage for help, stdout/stderr separation, recursive traversal, empty directory success, file input, default . input, single- and multi-root failure paths, single- and multi-root pipeline/SIGPIPE behavior, and argv permission boundaries. [test] 1 008 The smoke suite covers awkward POSIX path records such as spaces and leading dashes, plus generated-tree performance sanity without a benchmark framework. [test] 1 009 The smoke suite covers no-argument default . traversal and explicit empty PATH failure with stderr-only diagnostics. [test] 1 010 The smoke suite covers trailing-slash directory roots without double-slash records while preserving multi-root left-to-right output. [test] 1 011 The smoke suite covers symlink-to-file roots as file-like records and symlinked directory roots as non-followed records, including symlink records followed by real directory roots. [test] 1 012 The smoke suite covers duplicate PATH roots as repeated records supplied by argv, with no sorting or dedupe policy. [test] 1 013 The smoke suite checks help text for the files [PATH...] paths-only contract and explicit refusal of filters, sorting, metadata, deletion, exec, hidden config, and expression surfaces. [test] 1 014 The smoke suite checks representative listing and help runs do not create target, home, or cache files; stdout and stderr redirection remain the only outputs. [test]