docs: add AGENTS.md and CONTRIBUTING.md conventions

2026-08-28 19:32:29 -04:00
parent 1685eff2df
commit ea9ca79d48
2 changed files with 108 additions and 0 deletions
@@ -0,0 +1,52 @@
+# AGENTS.md
+
+Operating rules for anyone working in this repo, human or agent. The project:
+a GNU AutoTools replacement in C that reads a KDL build file and emits a
+POSIX-sh `./configure`. Yes, the name is the joke. The rules below are not.
+
+## 1. C23 only
+
+Write C23 (ISO/IEC 9899:2024). Compile with `-std=c23` and `-Wall -Wextra
+-Wpedantic`. Never target C20 (it does not exist as a ratified standard), never
+use C2y (the next draft). The build breaks on anything else.
+
+## 2. Vendoring: thirdparty/ only, license + pinned SHA
+
+Every third-party library is vendored in-tree under `thirdparty/<name>/`, with
+all three of:
+
+- the upstream `LICENSE` file (never omitted, never stubbed),
+- an `UPSTREAM` file recording the source URL and the pinned upstream commit
+  SHA,
+- a row in the `thirdparty/README.md` provenance table (name, version, license,
+  SHA).
+
+No git submodules. If it is not vendored this way, it does not exist.
+
+## 3. Tests: TDD, `make check` + `tests/run.sh`
+
+- Unit tests use the vendored single-header C test framework and run via
+  `make check`.
+- Shell integration tests live in `tests/*.sh` and are invoked by
+  `tests/run.sh`, asserting exact exit codes and grep-able output markers.
+- TDD workflow: write the test alongside the code. Implementation + test is one
+  unit of work, never separated.
+
+## 4. Generated configure scripts: POSIX-sh only
+
+The emitted `./configure` must run unmodified under `dash`, `bash`, and `zsh`.
+Banned constructs, no exceptions:
+
+- `[[ ]]`
+- arrays
+- `local`
+- `==` (use `=` with `[`, or `case`)
+- `<<<`
+- `&>`
+
+`set -e` IS POSIX, but it is avoided by policy in generated scripts because its
+failure semantics vary across shells. Do not rely on it; make the script fail
+explicitly. `dash` is the strict oracle: `dash -n` must pass on everything we
+generate.
+
+For build, test, and commit workflows, see CONTRIBUTING.md.
@@ -0,0 +1,56 @@
+# Contributing to stupidtools
+
+The project is a GNU AutoTools replacement: read a KDL build file, emit a
+POSIX-sh `./configure`. Contributions should follow the rules in AGENTS.md.
+This file covers the mechanics.
+
+## Build
+
+stupidtools bootstraps itself with autotools:
+
+```
+autoreconf -ivf
+./configure
+make
+```
+
+You need a C23-capable compiler (GCC >= 14 or Clang >= 18) and autotools.
+The build compiles with `-std=c23 -Wall -Wextra -Wpedantic`.
+
+## Test
+
+```
+make check      # unit tests via the vendored single-header C test framework
+tests/run.sh    # shell integration tests (exact exit codes + grep-able markers)
+```
+
+TDD workflow: write the test alongside the code. Implementation + test is one
+unit of work, never separated.
+
+## Commit
+
+Conventional commits, one per logical change:
+
+- `build:` build system, toolchain flags
+- `feat(kdl):` lexer, parser, values, schema
+- `feat(detect):` check registry, probes, feature resolution
+- `feat(gen):` configure generator, config.status/log/h, argument parsing
+- `feat(ext):` extension ABI, Lua embed, discovery
+- `test:` tests
+- `docs:` documentation
+- `chore:` vendoring, misc
+
+Never bundle two logical changes in one commit. Never commit generated
+artifacts (`configure`, `Makefile`, `config.h`, `config.status`, `config.log`).
+
+## Vendoring policy
+
+Every third-party library is vendored in-tree under `thirdparty/<name>/`:
+
+- the upstream `LICENSE` file (never omitted, never stubbed),
+- an `UPSTREAM` file recording the source URL and the pinned upstream commit
+  SHA,
+- a row in the `thirdparty/README.md` provenance table (name, version, license,
+  SHA).
+
+No git submodules. If it is not vendored this way, it does not exist.