Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,13 @@ A new field: declare it in `tables.toml` (a `[[tables.<table>.fields]]` entry wi

Rename a field: `mlr -I --ijsonl --ojsonl rename old,new data/<table>.json`, make the same change in `tables.toml`, then `make canon` (forgetting the declaration is caught by `make check`).

Ask the data anything in SQL - joins, counts, what is missing - and change it the same way; a change through SQL is checked exactly as `tad set` is, and kept only if every rule still holds:
```
tad sql "SELECT status, count(*) FROM backlog GROUP BY status"
tad sql "UPDATE backlog SET status = 'done' WHERE id = 'an-id'"
tad sql --file a-query.sql --format csv
```

## Why it is built this way
- The data is plain text in git: one JSON object per line, so a change to one row is a one-line diff, readable without any tool.
- `tables.toml` declares the tables as data (after Frictionless Data's Table Schema): a person reads it, and [tad](https://github.com/creation-guidelines/tad-engine) checks every row and every rule across tables against it.
Expand Down
5 changes: 4 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,18 @@
SHELL := /bin/bash
TAD ?= tad

.PHONY: setup check canon render verify
.PHONY: setup check canon render sql verify
setup: ## install tad from its pinned release (its checksum checked)
./bin/install-tad.sh
$(TAD) engine
check: ## every row and every rule across tables (tables.toml)
$(TAD) check
canon: ## rewrite data/ in canonical form (only when it checks out)
$(TAD) canon
render: ## data/ -> docs/
$(TAD) render
sql: ## ask the data in SQL: make sql Q="SELECT ..." (a change is kept only if every rule holds)
$(TAD) sql "$(Q)"
verify: check ## what CI runs: data is valid and canonical, docs are fresh
@before="$$(find data docs -type f -print0 | sort -z | xargs -0 sha256sum)"; \
$(TAD) canon && $(TAD) render; \
Expand Down
1 change: 1 addition & 0 deletions data/glimpses.json
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
{"id":"g-20261111-213425","at":"2026-11-11T21:34:25Z","by":"lab-agent-session","kind":"chore","summary":"glimpses are recorded here from now on"}
{"id":"g-20261111-223547","at":"2026-11-11T22:35:47Z","by":"tad update-pins","kind":"build","summary":"tad 0.4.0: the pin moved, the data and documents re-rendered"}
{"id":"g-20261112-010648","at":"2026-11-12T01:06:48Z","by":"lab-agent-session","kind":"build","summary":"tad 0.5.0: the pin moved, the data and documents re-rendered"}
{"id":"g-20261112-010844","at":"2026-11-12T01:08:44Z","by":"lab-agent-session","kind":"feat","summary":"SQL is back: make sql, tad engine in setup, the recipe"}
Loading