@agentsfleet/orly 0.5.0

package/docs/RULE_ENFORCEMENT.md

@@ -0,0 +1,41 @@
+# Rule enforcement ledger
+
+Generated by `audits/rule-ledger.sh`. Never hand-edit: `make audit`
+regenerates this file and fails on any difference. To update it, run
+`bash audits/rule-ledger.sh --write docs/RULE_ENFORCEMENT.md`.
+
+| Rule document | enforced by | judged | acknowledged | classified | trigger |
+|---|---|--:|--:|--:|---|
+| `docs/LOGGING_STANDARD.md` | `LOG` → `logging.sh` | 10 | 13 | 26/26 | mechanical |
+| `docs/REST_API_DESIGN_GUIDELINES.md` | — | 0 | 0 | 0/74 | mechanical |
+| `docs/SCHEMA_CONVENTIONS.md` | — | 0 | 0 | 0/16 | mechanical |
+| `docs/DOCUMENTATION_RULES.md` | — | 0 | 0 | 0/20 | latent |
+| `docs/LIFECYCLE_PATTERNS.md` | — | 0 | 0 | 0/22 | mechanical |
+| `docs/CHANGELOG_VOICE.md` | — | 0 | 0 | 0/3 | latent |
+| `docs/VERIFY_TIERS.md` | — | 0 | 0 | 0/4 | uncited |
+| `docs/greptile-learnings/RULES.md` | — | 0 | 0 | 0/113 | mechanical |
+| **corpus** | | | | **26/278** | |
+
+## How to read this
+
+- **enforced by** — the rules in this document a script decides, and the script
+  that decides each. This is the column worth acting on: it is the difference
+  between a rule that holds and a rule that is merely written down. A code
+  reading `no helper row` is a `[DETERMINISTIC → …]` tag with nothing behind it.
+- **judged / acknowledged** — clauses an agent must weigh (`[JUDGMENT → CODE]`)
+  and clauses nobody checks on purpose (`[UNENFORCED → reason]`, the reason
+  stated where a reader meets it).
+- **classified** — how much of the document has been triaged at all. The
+  denominator counts lines carrying a normative keyword outside headings and
+  tables — a keyword heuristic, not a parse. It informs; it never gates.
+- **trigger** — `mechanical` when a citing façade declares a file scope,
+  `latent` when every citing façade is prose the agent must choose to read,
+  `uncited` when no façade names the document at all.
+
+A tag alone on its line covers every clause under it until the next heading; a
+tag at the end of a sentence covers that sentence. Same grammar the
+`dispatch/*.md` façades use, read by the same code.
+
+Everything here is a function of the tree alone — no timestamps, no commit
+hashes, no history — so the file reproduces from a checkout and any diff means
+the corpus moved.

package/docs/SCHEMA_CONVENTIONS.md

@@ -0,0 +1,93 @@
+# Schema Conventions
+
+Canonical reference for agentsfleet database schema patterns. All new tables **must** follow these conventions. Existing tables are brought into compliance when rebuilt.
+
+## Migration Model
+
+**Teardown-rebuild is in force for the M154 rebuild (owner decision, Indy, Jul 31, 2026).** The development database is being dropped and re-created from empty while production is undeployed, so slots `001`–`046` are **retired wholesale** and the schema is re-authored by dependency layer. During this rebuild the frozen-slot rule below does not apply, and `ALTER`/`DROP` statements are forbidden rather than required — a change belongs in the base statement it would have patched. This is the posture RULE SCH already specifies for `VERSION < 2.0.0`; the Jul 22 additive model was the deviation.
+
+**Additive migrations resume once the rebuild lands.** Every subsequent schema change is a **new numbered migration file** — `ALTER TABLE … ADD COLUMN`, new tables, new indexes. **Shipped slot files are then frozen history: never edit an existing `schema/NNN_*.sql`.** Migrations are version-tracked and applied incrementally (expected-vs-applied state is inspectable via `agentsfleetd doctor --schema-gate`). Use `IF NOT EXISTS` guards so a migration is idempotent against both a fresh bootstrap (all slots in order) and an already-provisioned database (new slots only).
+
+Destructive changes (`DROP TABLE`, `DROP COLUMN`, type rewrites) require an explicit owner decision per change — additive is the default an agent may author alone.
+
+> Historical note: slots `001`–`031` predate the additive model (teardown-rebuild with inline DDL edits, enforced by a since-removed `check-schema-gate` lint target). M154 retires them along with everything up to `046`.
+
+## Schema File Organization
+
+- Each SQL file must be **≤100 lines** and **single-concern** (one table, one logical group, or one additive change).
+- Files are numbered sequentially: `001_core_foundation.sql`, `002_core_workflow.sql`, etc. New migrations append the next number; shipped numbers are never reused or slid.
+- Every SQL file must be registered in `schema/embed.zig` (compile-time embed) and `src/agentsfleetd/cmd/common.zig` (migration version array).
+- No-op stub files (e.g., columns folded into earlier files) are kept for version history but excluded from the migrations array.
+
+## SQL Qualification
+
+- Use schema-qualified table names in SQL (`core.platform_llm_keys`, `core.workspaces`, etc.) for new queries and handlers.
+- Do not rely on session `search_path` defaults for correctness.
+- Legacy unqualified queries may remain temporarily, but touched paths should be migrated to schema-qualified names.
+
+## Schema-Backed Runtime Defaults
+
+- If a numeric schema default is also used in runtime fallback or provisioning logic, define it once in Zig as a named constant and import that constant in runtime code.
+- Keep the database DDL value unchanged unless the product default is intentionally changing; the Zig constant mirrors the schema default for drift detection.
+- Add an adjacent `Canonical constant:` SQL comment next to each shared numeric default so reviewers can verify the linkage quickly.
+
+## Identity Column
+
+**One identity column per table, named `id` (owner decision, Indy, Jul 31, 2026 — M154).** The earlier `uid` rule paired a generated `uid` primary key with a duplicate twin column (`id`, `tenant_id`, `workspace_id`, …) holding the same value under its own `UNIQUE` constraint. That shape is retired.
+
+- **Column:** `id`
+- **Type:** Universally Unique Identifier (UUID) `PRIMARY KEY`
+- **Generation:** Application-side UUID version 7 (UUIDv7) via `src/agentsfleetd/types/id_format.zig`, never `gen_random_uuid()`.
+- **No second unique key on the same value.** This is a correctness rule, not only a storage one: `ON CONFLICT` can arbitrate exactly one constraint, so a table carrying two unique keys over the same value makes two sessions inserting a brand-new row race to a duplicate-key error on the *other* index instead of taking the update arm. `schema/043_runner_lifetime_counters.sql` recorded this before the rule was generalised.
+- **Foreign keys reference the primary key**, never a secondary unique constraint.
+- **Constraint:** every table carries a UUIDv7 CHECK:
+  ```sql
+  CONSTRAINT ck_{table}_id_uuidv7 CHECK (substring(id::text from 15 for 1) = '7')
+  ```
+- **Adding a new table:** add a `generate{TableName}Id()` function to `src/agentsfleetd/types/id_format.zig`.
+- **API shape:** unchanged — public fields keep exposing `id`, `tenant_id`, `workspace_id` and the other documented names. The column now *is* the public name in most tables, so the aliasing the old rule required mostly disappears; where a public field differs from `id`, alias at the boundary rather than renaming client-facing payloads.
+- **Exceptions,** each stated in the slot that creates the table: a curated catalogue keyed by a stable slug (`core.fleet_library`) and a singleton keyed by a pinned integer (`core.model_catalogue_revision`) carry no UUID.
+
+## Timestamps
+
+- **Type:** `BIGINT NOT NULL` — milliseconds since Unix epoch.
+- **Generation:** `std.time.milliTimestamp()` in Zig application code.
+- **Never** use `TIMESTAMPTZ`, `TIMESTAMP`, or `DEFAULT now()`.
+
+## Standard Columns
+
+Every table must have:
+
+| Column | Type | Required | Notes |
+|--------|------|----------|-------|
+| `id` | `UUID PRIMARY KEY` | Yes | UUIDv7, app-generated; the table's only identity column |
+| `created_at` | `BIGINT NOT NULL` | Yes | Set once at INSERT |
+| `updated_at` | `BIGINT NOT NULL` | If mutable | Set at INSERT and every UPDATE |
+
+**Naming is uniform.** `created_at` and `updated_at` are the only names for row lifecycle time — not `recorded_at`, `created_at_ms`, or `updated_at_ms`. A column carrying *domain* time distinct from row birth (for example the originating event's creation instant on a money row) is named for that domain meaning and documented in its slot.
+
+**Mutable tables** (any table where UPDATE is a valid operation) must have `updated_at`.
+
+**Append-only/event tables** (where UPDATE is blocked by trigger or by design) are exempt from `updated_at`.
+
+## Audit Pattern
+
+- **Actor tracking:** Use `actor TEXT` in event/transition tables (e.g., `policy_events`, `usage_ledger`).
+- **No `updated_by` column.** Changes to mutable tables are tracked via separate event-sourced audit tables (e.g., `workspace_billing_audit`, `harness_change_log`), not inline `updated_by`.
+- **Append-only enforcement:** Tables that must never be updated should have a trigger:
+  ```sql
+  CREATE OR REPLACE FUNCTION core.{table}_append_only() RETURNS trigger AS $$
+  BEGIN
+      RAISE EXCEPTION '{table} is append-only — UPDATE and DELETE are not permitted';
+  END;
+  $$ LANGUAGE plpgsql;
+
+  CREATE TRIGGER trg_{table}_append_only
+      BEFORE UPDATE OR DELETE ON core.{table}
+      FOR EACH ROW EXECUTE FUNCTION core.{table}_append_only();
+  ```
+
+## RNG
+
+- **Always** use `std.crypto.random` (via `allocUuidV7` in `id_format.zig`).
+- **Never** use custom RNG implementations or `std.rand`.

package/docs/TEMPLATE.md

@@ -0,0 +1,411 @@
+# Milestone Specification Template
+
+> **CANONICAL TEMPLATE — two agents consume this file, in different ways.**
+> The **authoring agent** (via the `orly-spec-new` skill) copies the body below the divider into `docs/v{N}/pending/M{N}_{NNN}_….md` and fills it — authoring order lives in the skill, not in this file. The **executing agent** reads the filled spec **top-to-bottom**: the body is physically ordered by execution need (understand → prepare → build → prove → record).
+> Enforced by `audits/spec-template.sh` (SPEC TEMPLATE GATE, façade `dispatch/write_spec.md`): required sections present, zero template residue, prohibited patterns absent. Lifecycle: `AGENTS.md → Specification Standards`.
+> A shipped instance outranks guidance: when `docs/v{N}/done/` holds specs, read the newest first and pattern-match.
+
+---
+
+## Fill grammar
+
+Three markup classes appear below the divider. The gate tells them apart mechanically:
+
+| Marker | Meaning | Fate in the filled spec |
+|---|---|---|
+| `{…}` | Fill slot — replace with instance content | Gone. Surviving slots are residue; the gate BLOCKs the known sentinels. |
+| `tpl:` guidance comment | How to fill the section — written for the authoring agent only | **Deleted after filling.** The gate BLOCKs any survivor. |
+| SPEC AUTHORING RULES banner comment | Standing constraints on the instance | The one comment that survives, verbatim. |
+
+Everything else — headings, table skeletons, the standard rubric rows — is kept and filled. The result: the executing agent reads **100% instance content, zero template noise**, and the 320-line budget buys signal, not boilerplate.
+
+## What a spec pins — and refuses to pin
+
+A milestone spec is a **goal rulebook** the executing agent plans and ships from *without playing 20-questions with the author*. It pins **intent + invariants + tests + pointers**; the agent has agency on everything else. It must NOT pin implementation detail that rots within a sprint: allocator/capacity choices, library versions, line-by-line code, exact Structured Query Language (SQL) Data Definition Language (DDL), import statements — the agent derives those from the repository.
+
+> **Pseudocode litmus.** If the spec names a version (`postcard 1.1`), a variable (`var ctx = …`), or a DDL clause (`CREATE TABLE … DEFAULT 'foo'`), it's pseudocode — it will be wrong within a sprint. Replace with *"use the project's existing X"* + a pointer to where X lives.
+
+## Anti-patterns (reject on sight)
+
+| # | Anti-pattern | Do instead |
+|---|---|---|
+| 1 | Code blocks inside section bodies | Describe WHAT the slice delivers; pin precise behaviour as a Test. Prose code drifts; tests don't. |
+| 2 | Listing every variable name | Point at an existing implementation to mirror; names match local style. |
+| 3 | SQL DDL line-by-line | Table shape + constraints in prose; the agent conforms to existing migrations. |
+| 4 | Pinning library versions | *"Use the existing Redis client"* + import pointer; the package manifest is the source of truth. |
+| 5 | Step-by-step ordering ("Step 1… Step 2…") | **Sections** (value slices); the agent sequences within. |
+| 6 | Test code in the spec | Name tests + assert behaviour in prose; the agent writes them in project style. |
+| 7 | One rubric row per Dimension, or pasted evidence walls | 5–12 outcome rows; Graded = ✅/❌ + one decisive output line. The Test Specification is the per-Dimension ledger. |
+| 8 | Template guidance surviving in the filled spec | Delete every `tpl:` comment; the executor reads instance content only. |
+
+Slipped into one? The fix is usually **point at a file** (read-first pointer) or **delete the detail** (the agent figures it out).
+
+## Hierarchy & terminology
+
+```
+v{N}.0.0 (Prototype)                  major release
+└── Milestone (M40, M41…)             one demoable end-to-end capability + evidence
+    └── Workstream (M40_001…)         one working function; ≤4 (a 5th only for a
+        │                             cross-cutting concern; never beyond 5 — split)
+        └── Section (§1, §2…)         implementation slice (what + why); 3–9 per spec
+            └── Dimension (3.1, 3.2…) verifiable sub-unit — the unit of DONE
+```
+
+**Dimension** is the atomic, verifiable unit: **1 Dimension → 1 Test**, marked `DONE` individually in the same commit as its code. "Mark Dimensions DONE" (per `AGENTS.md`) resolves here. A Section is DONE when all its Dimensions are. Outcome-level grading lives in the **Acceptance Rubric** — one row per Section or failure class, never one per Dimension.
+
+**Batch (B1, B2…)** — parallel execution group. Workstreams in the same batch run concurrently; batches are sequential (B2 starts after B1's gates clear).
+
+A milestone is not complete until evidence is captured: commands, logs, screenshots, or a recorded walkthrough.
+
+## Status markers
+
+- `PENDING` — not started. `IN_PROGRESS` — being worked. `DONE` / ✅ — complete, verified, tested.
+- `DEFERRED` — designed/attempted and explicitly not shipped; lives in `done/` as a record. **Discovery** MUST capture the rationale and reactivation conditions.
+
+## Prohibited (gate-enforced — `dispatch/write_spec.md`)
+
+- No time/effort estimates ("5 min", "1 hour", "2 days"). No effort columns or complexity ratings. No percentage-complete. No assigned owners. No implementation dates.
+- Sizing signal is **Priority** (P0/P1/P2/P3); sequencing is **Dependencies**.
+
+## Guardrails
+
+- **Length — hard upper bound 320 lines for the filled spec** (after `tpl:` comment deletion). Typical specs 150–300. Past the bound before the Acceptance Rubric → scope is two specs sharing one file; split.
+- **Sections** — 3–9. **Workstreams** — ≤4 (5th cross-cutting only).
+- **File naming** — `docs/v{N}/{pending|active|done}/M{N}_{NNN}_P{Priority}_{CATEGORIES}_{NAME}.md` (e.g. `M40_001_P0_API_WORKER_SUBSTRATE.md`). Categories alphabetised.
+
+---
+
+# Spec Body — Copy Everything Below This Line
+
+<!--
+SPEC AUTHORING RULES (load-bearing — the one comment that survives):
+- Body order = the executing agent's read order. Fill via the orly-spec-new
+  skill (authoring order lives there); after filling, DELETE every "tpl:"
+  guidance comment — the SPEC TEMPLATE GATE blocks tpl residue, unfilled
+  {slots}, and missing required sections (audits/spec-template.sh --staged).
+- No time/effort/hour/day estimates anywhere. No effort columns, complexity
+  ratings, percentage-complete, implementation dates, assigned owners.
+- Priority (P0/P1/P2/P3) is the only sizing signal; Dependencies are the only
+  sequencing signal. A section that contradicts these rules loses — delete it.
+-->
+
+# M{Milestone}_{Workstream}: {Title — testable, not vague}
+
+**Prototype:** v{major}.{minor}.{patch}
+**Milestone:** M{Number}
+**Workstream:** {001-009}
+**Date:** {MMM DD, YYYY}
+**Status:** PENDING | IN_PROGRESS | DONE
+**Priority:** P0 | P1 | P2 | P3 — {one-line reason}
+**Categories:** {API | CLI | UI | SKILL | DOCS | OBS | INFRA — alphabetised, one or more}
+**Batch:** B{1-4} — {parallel execution context}
+**Branch:** {feat/mNN-name — added at CHORE(open)}
+**Test Baseline:** set at CHORE(open) — `unit=<N> integration=<M>` from the repository's declared `verify.*` commands (`.oracle/orly.json`)
+**Depends on:** {M{N}_{NNN} (one-line reason), …}
+**Provenance:** human-written | LLM-drafted ({model}, {date}) | agent-generated (pre-spec, {source doc})
+**Canonical architecture:** `docs/architecture/{relevant-doc}.md` §{N}
+
+<!-- tpl: Provenance is load-bearing — the implementing agent calibrates trust by
+who wrote the spec: LLM-drafted gets extra cross-checking against the codebase;
+human-written assumes the author read the relevant code. Canonical architecture:
+the docs/architecture/ directory is the source of truth (Architecture Consult &
+Update Gate); greenfield → point at the doc that defines the shape. -->
+
+---
+
+## Overview
+
+**Goal (testable):** {one sentence that could be a test name}
+**Problem:** {observable symptoms, in user-facing terms}
+**Solution summary:** {one paragraph — what changes, at what layer, what the user-visible outcome is}
+
+<!-- tpl: Goal — bad: "Implement streaming." Good: "Server-Sent Events (SSE)
+handler streams Redis pubsub messages as text/event-stream with stable ordering
+and reconnection, p95 latency under 200ms." Problem — symptoms ("operators can't
+see the agent's tool calls in real time"), never implementation language ("we
+don't have a foo handler"). Implementation steps belong in Sections, not here. -->
+
+## PR Intent & comprehension handshake
+
+- **PR title (eventual):** {imperative, ≤72 chars — what the merged Pull Request (PR) is called}
+- **Intent (one sentence):** {why this PR exists, in user-facing-outcome terms}
+- **Handshake** — the implementing agent fills this at PLAN, before EXECUTE: restate the Intent in its own words and list `ASSUMPTIONS I'M MAKING: …`. A mismatch between the restatement and the Intent above → STOP and reconcile before any edit.
+
+## Implementing agent — read these first
+
+1. `{path/to/file.ext}` — {why this is the right pattern to mirror}
+2. `{path/to/spec_or_doc.md}` — {what canonical knowledge lives there}
+3. {external doc URL, if relevant} — {what convention to follow}
+
+<!-- tpl: 3–5 pointers. Fewer than 3 = authoring homework not done (the executing
+agent repeats it); more than 5 = a tutorial (trim). This is where judgment is
+preserved without pseudocode: point at code/docs to read BEFORE touching any
+file. Greenfield (no existing pattern)? Say so explicitly and point at the
+docs/architecture/ doc that defines the shape. Every pointer must resolve
+in THIS repository (`test -f` each) or be a URL — a pack this repository
+never selected materialised nothing here. -->
+
+## Files Changed (blast radius)
+
+| File | Action | Why |
+|------|--------|-----|
+| `path/to/file.ext` | CREATE / EDIT / DELETE | {one line — what changes about this file's role} |
+
+<!-- tpl: Every file created, modified, or deleted. Scopes the length gates,
+orphan sweeps, and review effort; per AGENTS.md the executing agent may only
+edit files in this table without explicit override. List FILES and ROLES —
+never line numbers or function names (they drift). Teardown/rename/flip specs
+open with a blast-radius grep first: git grep -rn -w '<token>' from repo root,
+no path filter (dispatch/write_spec.md, Authoring discipline). -->
+
+## Applicable Rules
+
+- **`docs/greptile-learnings/RULES.md`** — {specific rule IDs this diff trips: e.g. UFS, NDC, NLR, ORP, FLL}
+- {per-surface rule file} — {why it applies to this diff}
+
+<!-- tpl: The rule files the executing agent re-reads BEFORE EXECUTE and
+re-checks during VERIFY. Name the exact rule IDs the diff will trip — generic
+"follow RULES.md" earns a greptile finding; named IDs are obeyed by
+construction. Per-surface menu = the dispatch table in THIS repository's
+generated AGENTS.md plus the docs/ rule files those façades cite — all
+materialised locally by the selected packs; a rule file absent from this
+repository is not applicable by definition. Fully greenfield → write "Standard
+set only — docs/greptile-learnings/RULES.md; no other rule files apply." -->
+
+## Applicable Gates
+
+| Gate | Fires? | Satisfaction strategy |
+|------|--------|-----------------------|
+| {gate from this repository's AGENTS.md dispatch index} | {yes/no — why} | {how the diff stays clean} |
+| File & Function Length (≤350/≤50/≤70) | {yes/no} | {split plan if a file approaches the cap} |
+
+<!-- tpl: Which Action-Triggered Guards this Pull Request (PR) WILL trip, and
+how each stays clean — pre-declared so the agent plans for them instead of
+stalling mid-EXECUTE. The menu is THIS repository's generated AGENTS.md
+dispatch index — one row per materialised gate the diff can trip; never cite a
+gate from a pack this repository lacks. Rules ≠ Gates: rules are knowledge to
+read; gates are guards that fire on edits. Touch nothing a gate watches →
+replace the table with "N/A — docs/markdown only." -->
+
+## Prior-Art / Reference Implementations
+
+- **Reference:** {path / codebase} — {one line on alignment, or the justified divergence}
+
+<!-- tpl: SOUL.md rule — before proposing architecture, find the reference
+codebase; there almost always is one. Name it so the agent mirrors a known-good
+pattern instead of inventing. Menu: Command-Line Interface (CLI) → the "7
+Pillars" of CLI developer experience (vendored supabase-style oss/cli): command
+→ handler → errors split; handler purity (no console.log / process.exit in
+handlers); output as a service (human vs JSON vs env rendering chosen by the
+renderer); structured JSON errors with suggestion/retry fields; 3-tier test
+pyramid (handler unit / in-process integration / subprocess e2e); auto-JSON when
+stdout is piped (LLM-native) — state which pillars this spec aligns with and any
+divergence. API → docs/REST_API_DESIGN_GUIDELINES.md + the closest existing
+handler. Schema → the nearest migration + docs/SCHEMA_CONVENTIONS.md. UI →
+design-system primitives + theme.css tokens. Cite each doc only where this
+repository materialises it. Greenfield → "no prior art; shape
+defined in docs/architecture/{doc}.md." -->
+
+## Sections (implementation slices)
+
+### §1 — {Slice title}
+
+{What this slice delivers in goal terms; why it must exist; what it unblocks. Non-obvious choice → **Implementation default:** `{choice}` because `{reason}`.}
+
+- **Dimension 1.1** — {smallest verifiable behaviour} → Test `test_…`
+- **Dimension 1.2** — {…} → Test `test_…`
+
+### §2 — {Slice title}
+
+{Same shape.}
+
+<!-- tpl: Each Section: WHAT one slice delivers and WHY (not how); numbered
+Dimensions map 1:1 to Tests and get marked DONE in the same commit as their
+code. The agent picks each Implementation default unless it has evidence to
+deviate. Good: "§3 — Replay idempotency. Receiver dedupes on the delivery id.
+Implementation default: 24h dedupe window matching the upstream retry window;
+storage is a Redis key with a Time To Live (TTL) — the agent picks the key
+shape from existing dedupe patterns. Dimension 3.1 → test_dedupes_within_window;
+3.2 → test_evicts_after_ttl." Bad: "§3 — Use redis.SET(\"webhook:dedupe:\"+id,
+\"1\",\"NX\",\"EX\",86400) and check the return." — pseudocode; the agent reads
+the existing dedupe pattern and writes the call. -->
+
+## Interfaces
+
+```
+{HTTP endpoints, request/response shapes, internal signatures other code depends on}
+```
+
+<!-- tpl: Lock the interface — the surface the agent must NOT change without
+amending the spec. Specify input/output/error shapes; use a real example
+payload where shape isn't self-evident. Write the interface, not the
+implementation. -->
+
+## Failure Modes
+
+| Mode | Cause | Handling (system response + what the caller observes) |
+|------|-------|--------------------------------------------------------|
+| {short name} | {trigger} | {response + observable} |
+
+<!-- tpl: Every failure path the agent must handle; each row → a negative/
+integration test in the Test Specification. Cover at minimum: timeout,
+malformed input, auth failure, network blip, race, replay, exceeded quota,
+dependency unavailable. -->
+
+## Invariants
+
+1. {Invariant} — {how it's enforced}
+
+<!-- tpl: Each MUST be enforceable by code (compiler, lint, comptime assertion,
+runtime check) — NOT by review discipline. If a human can violate it silently,
+it's not an invariant. None → "N/A — no invariants." -->
+
+## Metrics & Observability
+
+| Metric / event | Owner | Fires when | Properties allowed | Privacy guard | Test proof |
+|----------------|-------|------------|--------------------|---------------|------------|
+| `{event_name}` | {product / ops / not applicable} | {exact user or system action} | {coarse product context, resource id, duration, outcome} | {no raw email/password/token/One-Time Password (OTP)/Secure Shell (SSH) key material} | `{test_name}` |
+
+<!-- tpl: Every realized spec declares what product or operational signal it
+adds, or explicitly why none: internal-only cleanup → the single row "not
+applicable — no product/operator signal changes". Prefer the project's
+analytics architecture doc (root page telemetry for views, typed event
+registries for actions, journey timers for funnels, authenticated identity
+linking). If a workflow already emits analytics, state whether this spec adds,
+renames, or leaves those events unchanged; if any funnel changes, update the
+analytics/funnel playbook in the same PR — otherwise Discovery records
+"Metrics review: no analytics/funnel playbook update required" with the reason.
+The implementing agent revisits this table after implementation and during
+/review; missing action events, funnel timers, or feature-flag exposure events
+are implementation gaps, not notes for later. -->
+
+## Test Specification (tiered)
+
+| Dimension | Tier | Test | Asserts (concrete inputs → expected output) |
+|-----------|------|------|---------------------------------------------|
+| 1.1 | {unit / integration / e2e} | `test_<short_name>` | {one-line behavioural claim} |
+
+<!-- tpl: Prose-and-assertions only — no test code. One row per Dimension;
+bound to the /orly-write-unit-test skill; ≥50% negative paths; every Failure Mode
+row and every Metrics row gets a test. Tiers: unit (pure logic, handlers,
+boundaries — empty/null/max/malformed/unicode) · integration (real stack, mock
+only at system boundaries, deterministic failure injection per Failure Mode) ·
+end-to-end (e2e) — any user-facing Category (CLI / UI / API) gets at least one
+user-centric scenario via test-e2e* walking the real path (subprocess CLI /
+real HTTP request / rendered UI); a unit test is not a substitute. Also
+include regression rows (pre-existing behaviour that must not change — "N/A —
+greenfield" if none) and idempotency/replay rows (any retry semantics).
+Non-self-evident input shape → point at a fixture
+(samples/fixtures/m{N}-fixtures/{name}.json); don't inline JSON. Hard-to-
+describe behaviour in prose ⇒ the Goal is fuzzy — fix the Goal, not this
+table. -->
+
+## Acceptance Rubric (single scoring surface)
+
+| # | Criterion (observable outcome) | Verify (copy-paste) | Expected | Priority | Graded (VERIFY) |
+|---|--------------------------------|---------------------|----------|----------|-----------------|
+| R1 | {outcome the user can observe} (§1) | `{command}` | {exit 0 / substring / 0 matches} | P0 | |
+| R2 | Diff stays inside Files Changed | `git diff --name-only origin/main...HEAD` | 0 paths missing from the Files Changed table | P0 | |
+| S1 | Conform gates green | `{conform command from .oracle/orly.json, verbatim}` | exit 0 | P0 | |
+| S2 | Unit tests pass | `{verify.unit command from .oracle/orly.json, verbatim}` | exit 0 | P0 | |
+| S3 | Slow tier green (code-carrying branch) | `{one row per declared slow verify.* the diff's surface needs — integration / e2e / memory / cross-compile — verbatim}` | exit 0 | P0 | |
+| S4 | No secrets | `gitleaks detect` | exit 0 | P0 | |
+| S5 | No oversize source file | `git diff --name-only origin/main...HEAD \| grep -v '\.md$' \| xargs wc -l 2>/dev/null \| awk '$1>350 && $2!="total"'` | no output | P0 | |
+| S6 | Orphan sweep | Dead Code Sweep greps | 0 matches | P0 | |
+
+**Command source rule:** every S-row Verify command is copied **verbatim from `.oracle/orly.json`** (`conform`, `verify.*`) — the same set `orly gate` runs, so the rubric and the mechanical PR gate grade one boundary. The gate BLOCKs a staged pending/active spec whose rubric omits the declared `conform` or `verify.unit` command; a rubric naming a runner the repository does not declare is wrong by construction. `.oracle/orly.json` still a seed → complete it first (`dispatch/lifecycle.md` §Bootstrap); authoring against an unseeded config is the nondeterminism this rule exists to kill.
+
+**Grading protocol (VERIFY):** run the Verify command verbatim; grade ONLY from its output. Graded = ✅/❌ + the one decisive output line (`342 passed`); long evidence goes to PR Session Notes with a pointer here. **Ship gate:** every row graded, every P0 ✅ → eligible for CHORE(close); any ❌ or empty cell → return to EXECUTE; a P1 ❌ ships only with an Indy-acked deferral quote in Discovery.
+
+<!-- tpl: The single scoring surface — no other scoreboard. 5–12 rows after
+pruning: one per Section outcome, failure class, or hygiene gate — never one
+per Dimension (that ledger is the Test Specification). S-row commands come verbatim from
+`.oracle/orly.json`; expand S3 to one row per declared slow `verify.*` the
+diff's surface needs; delete rows whose command this repository does not
+declare. Expected litmus: every Expected is
+mechanically checkable — an exit code, a literal substring, or a match count;
+can't write it that way → the criterion is fuzzy — fix the criterion, not the
+grading. Authoring fills every column except Graded; VERIFY fills Graded. -->
+
+### Behaviour evals
+
+- **Grounding rule:** {one sentence the output must never violate}
+- **Golden set:** `samples/fixtures/{path}` — {N} cases across {3–5 coverage axes, incl. the nightmare case}. A failure found in the wild becomes a new case; the set only grows.
+- **Ship threshold:** grounding 100% · task pass ≥{N}% · 0 critical failures on {nightmare case}. Each threshold is one rubric row with the command that computes it.
+- **Fallback:** below threshold or low confidence → {named recoverable behaviour}; fabricated output is a P0 ❌.
+
+<!-- tpl: Delete this whole sub-section unless the diff changes prompt/model/
+agent behaviour. Grounding-rule example: "responses cite only retrieved rows,
+never invented identifiers." -->
+
+## Dead Code Sweep
+
+**1. Orphaned files — deleted from disk and git.**
+
+| File to delete | Verify |
+|----------------|--------|
+| `{path/to/old_file.ext}` | `test ! -f {path/to/old_file.ext}` |
+
+**2. Orphaned references — zero remaining imports/uses.**
+
+| Deleted symbol/import | Grep | Expected |
+|-----------------------|------|----------|
+| `{old_symbol}` | `grep -rn "{old_symbol}" src/ \| head` | 0 matches |
+
+<!-- tpl: Mandatory when the spec deletes or replaces files: for every deleted
+file and removed/renamed public symbol, grep the repo; non-zero = stale. Use
+the same word-boundary pattern as the discovery grep. No deletions → replace
+both tables with "N/A — no files deleted." -->
+
+## Out of Scope
+
+- {Item explicitly not in this spec — points at a follow-up spec or "future work"}
+
+---
+
+<!-- tpl: The two sections below are the AUTHORING RECORD — written before the
+implementation sections above, read once by the executing agent at PLAN for
+intent, and never re-litigated during EXECUTE. They sit last so the executor's
+working sections stay front-loaded. -->
+
+## Product Clarity (authoring record)
+
+1. **Successful user moment** — {the single observable moment that proves this worked — a scene, not a metric}
+2. **Preserved user behaviour** — {what users do today that keeps working unchanged; breaking any of it is a redesign}
+3. **Optimal-way check** — {is this the most direct way to deliver moment #1? name the gap to the unconstrained-optimal shape and why it's acceptable now}
+4. **Rebuild-vs-iterate** — {would a larger refactor serve better? verdict here; rationale in Decomposition below. A refactor that trades run-to-run determinism away is wrong by default}
+5. **What we build** — {the shortest artifact list that delivers moment #1}
+6. **What we do NOT build** — {adjacent scope rejected, one-line reason each — seeds Out of Scope}
+7. **Fit with existing features** — {what this compounds with; the one feature it must not destabilize}
+8. **Surface order** — {CLI-first (repo default), UI-first, or both; justify divergence}
+9. **Dashboard restraint** — {what the UI must hide until the signal behind it is real: no controls before evidence, no quality claims before counters}
+10. **Confused-user next step** — {the self-serve move (a command, an error message, a doc); "file a ticket" means a surface is missing from item 5}
+
+<!-- tpl: Indy's product questions, answered in order at authoring BEFORE the
+implementation sections are written — so the authoring agent holds the product
+behaviour, not just the file list. One short paragraph or list item each. A
+question that can't be answered yet is a [?] that blocks the spec (golden-path
+rule, AGENTS.md). Internal-only work: answer 1–7 compactly; 8–10 may be "N/A —
+no user surface" with the reason. -->
+
+## Decomposition & alternatives (patch vs refactor)
+
+- **Chosen shape:** {why this Section/Workstream split — the decomposition rationale}
+- **Alternatives considered:** {≥1 — the larger refactor or the smaller patch — and why rejected for now}
+- **Patch-vs-refactor verdict:** this is a **{patch | refactor}** because {reason}. {If a larger refactor is the right long game but out of scope, name the follow-up spec rather than silently mud-patching.}
+
+<!-- tpl: Indy's rule — don't ship a mud-patch when the problem wants a
+refactor, and don't refactor when a patch is right. Match solution-size to
+problem-size; surface the call BEFORE approval, not mid-PR. Weigh against the
+platform constants (docs/architecture/direction.md). -->
+
+## Discovery (consult log)
+
+- **Consults** — Architecture / Legacy-Design / gate-flag triage: the question asked + Indy's decision.
+- **Metrics review** — events added, extra events found during `/review`, analytics/funnel playbook update or the explicit no-change reason.
+- **Skill-chain outcomes** — `/orly-write-unit-test`, `/review`, `orly-babysit-prs` results (order per `AGENTS.md` CHORE(close); iteration counts, findings dispositioned).
+- **Deferrals** — every "deferred to follow-up" needs an **Indy-acked verbatim quote** here, format `> Indy (YYYY-MM-DD HH:MM): "<quote>" — context: <which item, why>`. An agent-unilateral deferral is **incomplete scope, not deferral**, and blocks CHORE(close) until the item lands or the quote is captured.
+
+<!-- tpl: Empty at creation (keep the four bullet headers). This is the spec's
+running record — where deferrals and skill outcomes are proven as the work
+proceeds. -->

package/docs/VERIFY_TIERS.md

@@ -0,0 +1,57 @@
+# VERIFY — Tiers, performance, hygiene
+
+> Parent: [`../AGENTS.md`](../AGENTS.md) §VERIFY. Verification Gate (`dispatch/verify.md`) enforces; `make` targets are canonical.
+
+**FIRST: `/orly-write-unit-test`** — audits diff coverage vs spec's Test Specification (or changed surface when no spec). Iterate until clean. Skipping = CHORE(close) violation.
+
+## Correctness tiers (do not skip)
+
+| Tier | Command | When |
+|---|---|---|
+| 1 | `make test-unit-all` | Every EXECUTE iteration; start of VERIFY. Unit-only — never substitutes for 2/3. Zig-only fast loop: `make test-unit-agentsfleetd`. |
+| 2 | `make test-integration` | Diff touches `src/agentsfleetd/http/**`, `src/agentsfleetd/db/**`, `src/agentsfleetd/fleet/**`, `src/agentsfleetd/observability/**`, `*_integration_test.zig`, schema, migrations. Before COMMIT. |
+| 3 | `make test-integration` | ≥1× per branch from clean state (after `make down`) before ship-ready. Mandatory when schema changes pre-v2.0. Tier 2 passing + 3 failing = state pollution; fix isolation. |
+
+## Test delta — VERIFY ends by reporting coverage growth
+
+CHORE(open) recorded the branch-point counts in the spec header (`**Test Baseline:** unit=<N> integration=<M>`, from `make _lint_zig_test_depth`, which also writes `.tmp/agentsfleetd-test-depth.txt`). VERIFY ends with the same command and this required row in the verification block:
+
+```
+Test Delta: unit <N₀>→<N₁> (+x) · integration <M₀>→<M₁> (+y) vs CHORE(open) baseline
+Lacking:    <changed surfaces whose tests did not grow, or "none">
+```
+
+- **Delta is deterministic; Lacking is judgment (🤔)** — walk the diff's changed modules and name every one whose coverage did not move (e.g. "EgressScope Linux paths — integration lane pending"). "none" must be earned, not defaulted.
+- **Zero/negative unit delta while the diff adds non-trivial code** → justify in the row (pure refactor, test consolidation) or return to EXECUTE. Deleting tests to go green is a violation, not a justification.
+- Spec predates this rule (no `Test Baseline:` line) → reconstruct from the branch point (run the counter at the CHORE(open) commit or on `origin/main`) and add the line to the spec in the same commit as the VERIFY report.
+
+## Performance / leak (before PR)
+
+| Gate | Command | When |
+|---|---|---|
+| Leak | `make memleak` | Server lifecycle (`src/agentsfleetd/http/**`, `src/agentsfleetd/cmd/serve.zig`), allocator wiring, cross-thread heap ownership. |
+| Bench (local) | `make bench` | When the diff touches request-path code, allocator wiring, or startup/shutdown sequencing. |
+| Bench (dev) | `API_BENCH_URL=https://api-dev.agentsfleet.net/healthz make bench` | After deploy to dev. |
+
+**Zig coverage.** `make test-coverage-zig` runs the daemon, runner, and three shared-library unit binaries under kcov. Each component must produce a non-empty Cobertura report. The merged report lives under `coverage/zig/merged` and must meet `ZIG_COVERAGE_MIN_LINES`.
+
+**Integration roots.** `make test-unit-agentsfleetd` runs `src/agentsfleetd/tests.zig`. `make test-integration` prepares isolated services once and runs `src/agentsfleetd/integration_tests.zig`, which owns the live PostgreSQL, Redis, and QStash imports. The runner's Linux kernel root remains independently selectable.
+
+**Memleak lanes.** `make memleak` leak-gates all three test graphs concurrently, each named in its own lane prefix: **`agentsfleetd`** (daemon), **`runner`** (`build_runner.zig` unit tests — integration tests fork real children and are excluded), and **`lib`** (three `src/lib` binaries). Component failures are collected and reported before the final lifecycle proof. On Linux, Valgrind is blocking and propagates its exit code. On macOS, the Zig testing allocator is blocking. The advisory `leaks` rerun happens only when one lightweight preflight proves that the host can inspect child processes. `-Dopenssl=false` is a root-graph option only; the runner graph links no OpenSSL and rejects the flag. A final **`boot-drain`** lane migrates the test database, exports the integration environment, runs the filtered daemon lifecycle test under the blocking gate, and requires its run-proof marker.
+
+Knobs (`make/test-bench.mk`): `API_BENCH_METHOD`, `_DURATION_SEC`, `_CONCURRENCY`, `_TIMEOUT_MS`, `_MAX_ERROR_RATE`, `_MAX_P95_MS`, `_MAX_RSS_GROWTH_MB`.
+
+**Memleak evidence:** paste final `make memleak` line into PR Session Notes OR cite CI URL. Branches touching `src/agentsfleetd/http/**`/`src/agentsfleetd/cmd/serve.zig`/allocator wiring → last 3 lines verbatim. No "trust me".
+
+## Hygiene (always, before PR)
+
+`make lint-all` (hard); `make _lint_zig_pg_drain` (also folded into `make lint-all` via `lint-zig`) + cross-compile `x86_64-linux` + `aarch64-linux` (any `*.zig` touched); cross-layer orphan sweep (RULE ORP — every renamed/deleted symbol → 0 hits across schema/Zig/JS/tests/docs in non-historical files); `gitleaks detect` before any Zig-including commit; 350-line / 50-fn-line check via:
+
+```bash
+git diff --name-only origin/main \
+  | grep -v -E '\.md$|^vendor/|_test\.|\.test\.|\.spec\.|/tests?/' \
+  | xargs -I{} sh -c 'wc -l "{}"' \
+  | awk '$1 > 350'
+```
+
+**Other:** after refactors, list newly dead code before removing — `NEWLY UNREACHABLE: <symbol/file> — <why now dead>. Remove? Confirm.` **Greptile learning capture:** each finding → "Could this recur?" If yes, add compact rule (Rule/Why/Tags/Ref) to RULES.md same commit. Never defer.