From e8d28309f33c432cfa4694af21d5c6d1b05c3173 Mon Sep 17 00:00:00 2001
From: Vernon Stinebaker <vernon.stinebaker@gmail.com>
Date: Mon, 28 Sep 2026 22:11:54 +0800
Subject: [PATCH 1/2] docs: add AGENTS.md engineering protocol and
 CONTRIBUTING.md

Captures the headless-by-design constraints (no agents, no queues, no UI),
the JSON contract stability expectations for NullHub consumers, and the
standard validation gates.
---
 AGENTS.md       | 45 +++++++++++++++++++++++++++++++++++++++++++++
 CONTRIBUTING.md | 12 ++++++++++++
 2 files changed, 57 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 CONTRIBUTING.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..6863ba2
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,45 @@
+# AGENTS.md — NullWatch Engineering Protocol
+
+Default working protocol for coding agents in this repository. Scope: entire repository.
+
+## 1) Project Snapshot
+
+NullWatch is the execution-intelligence layer of the null stack: traces, evals,
+run summaries, costs, latency, and regression signals. Zig 0.16.0, single binary,
+headless by design — the product surface is a JSON HTTP API plus a CLI for
+ingestion and querying; UI belongs to NullHub, which consumes these endpoints.
+
+Division of labor (do not blur these boundaries):
+
+- `nullclaw` executes work — NullWatch never runs agents
+- `nulltickets` owns durable task state — NullWatch owns no queues
+- `nullboiler` owns orchestration policy — no scheduling logic here
+- `nullhub` owns install/config/UI — no installer or dashboards in this repo
+- NullWatch owns traces, evals, run summaries, token/cost accounting
+
+## 2) Architecture Facts
+
+- The implementation is intentionally small (MVP-shaped): file-backed storage,
+  JSON HTTP API, CLI. Do not add persistence engines or UI "while here".
+- Run and span ingest, eval-result ingest, and run-level summaries are the core
+  surface — changes must keep the JSON contracts stable for NullHub consumers.
+- Headless workflows only: anything that needs a human viewport belongs in NullHub.
+
+## 3) Engineering Principles
+
+- KISS / YAGNI / DRY, fail fast with explicit errors.
+- Determinism: tests must not hit the network or depend on wall-clock ordering.
+- Every code change ships with tests; `zig build test --summary all` must show
+  0 failures and 0 leaks. Regression tests cite the issue they guard.
+
+## 4) Validation
+
+```bash
+zig build test --summary all   # required before every commit
+zig fmt --check src/           # required before every commit
+zig build                      # dev build
+```
+
+## 5) Contribution flow
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..5d69452
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,12 @@
+# Contributing to NullWatch
+
+1. **Read [AGENTS.md](AGENTS.md)** first — headless-by-design constraints and
+   the JSON contract stability rules live there.
+2. One concern per PR. No drive-by refactors.
+3. Before every commit:
+   - `zig build test --summary all` — 0 failures, 0 leaks
+   - `zig fmt --check src/`
+4. Every PR runs the 4-target CI matrix. Keep it green.
+5. Bug fixes must include a regression test citing the issue number.
+6. Ingest/query API changes must stay backward-compatible for NullHub consumers,
+   or be versioned explicitly.

From e7c546ef23fc9cb1ca6a1f45b1a8f00a162503aa Mon Sep 17 00:00:00 2001
From: Vernon Stinebaker <vernonstinebaker@users.noreply.github.com>
Date: Sat, 3 Oct 2026 23:15:13 +0800
Subject: [PATCH 2/2] docs(contributing): use shared CI matrix wording; list
 e2e gate (DonPrus review)

---
 CONTRIBUTING.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5d69452..5122d89 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -6,7 +6,9 @@
 3. Before every commit:
    - `zig build test --summary all` — 0 failures, 0 leaks
    - `zig fmt --check src/`
-4. Every PR runs the 4-target CI matrix. Keep it green.
+   - API/CLI changes: `bash tests/test_e2e.sh` — CI runs this too, and it
+     verifies real ingest/query behavior
+4. Every PR runs the shared CI matrix. Keep it green.
 5. Bug fixes must include a regression test citing the issue number.
 6. Ingest/query API changes must stay backward-compatible for NullHub consumers,
-   or be versioned explicitly.
+   or be versioned explicitly.
\ No newline at end of file